周末想在 Mac 上把 Codex 跑起来结果从安装开始就被各种报错教育终端敲codex提示 command not found换成 Desktop 版又弹 “unable to locate the codex CLI binary”好不容易进了界面切个模型还蹦出一句 “cc switch local proxy failed while handling codex endpoint /responses”。说实话Codex 本身不算难用难的是它在 macOS 上要把 PATH、zsh、Homebrew、权限、MCP 这一长串环境问题全部捋顺。这篇文章把我自己在 Mac 上安装和使用 Codex 时踩过的坑、查过的资料、验证过的解法按问题域完整整理了一遍覆盖安装方式选型、PATH 与 zsh 配置、网络请求转发异常、MCP 接入、Desktop 客户端报错和 macOS 安全机制引起的权限问题。适合两类读者一类是刚接触 Codex 的小白跟着章节顺序操作就能跑通另一类是已经装上但被某个报错卡住的老手直接按速查清单定位即可。1. 先交代清楚Codex 在 Mac 上到底有哪两条安装路线很多人的第一个坑发生在安装方式的选择上。Codex 在 macOS 上不是只有一个安装入口而是有 CLI 和 Desktop 两条路线两条路线的报错逻辑完全不同混着用就会出现“客户端装了但终端找不到命令”的怪现象。1.1 npm 安装对 Mac 基础环境的要求用 npm 装 Codex CLI 是最直接的路线命令就一行npm install -g openai/codex但这一行命令能不能成功取决于你的 Node.js 环境。Codex CLI 要求 Node.js 18 或更高版本建议直接用 20 LTS。检查方式node -v npm -v如果node都没装那就先装 Node。macOS 上装 Node 的常见方式有官方 pkg 安装包、Homebrew 和 nvm。我的建议是如果只是为 Codex 装 Node那就用官方 pkg省心如果你平时还要在多个 Node 版本间切换那就用 nvm。这里埋一个坑nvm 装的 Nodenpm 全局包的目录会落在~/.nvm/versions/node/xxx/bin下面而这个目录往往不在 PATH 里这直接导致了后面最常见的zsh: command not found: codex。还有一个高频问题是一行命令直接报权限错误npm ERR! code EACCES npm ERR! syscall mkdir npm ERR! path /usr/local/lib/node_modules/openai这是 npm 全局目录无写入权限。不要一上来就用sudo npm install -g那会把后续所有包的属主都搞乱。正确做法是把 npm 的全局目录指到用户目录下mkdir ~/.npm-global npm config set prefix ~/.npm-global然后把这个 bin 目录加进 PATH具体加法和 zsh 的配置在下一章详细讲。1.2 Homebrew 安装与装完找不到 brew 的坑如果你的 Mac 上已经比较依赖 Homebrew也可以走brew install codex或直接搜索brew search codex看当前公式的准确包名。Homebrew 的优势在于依赖管理统一卸载也干净。但 Homebrew 本身在 Mac 上装的时候就有不少坑。最常见的就是官方安装脚本跑了半天最后报curl: (7) Failed to connect to raw.githubusercontent.com port 443: Connection refused这就是网络不通导致的需要换用国内镜像源。我实际验证过的安装方式是在执行官方脚本之前先设置镜像环境变量比如用清华源export HOMEBREW_BREW_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/brew.git export HOMEBREW_CORE_GIT_REMOTEhttps://mirrors.tuna.tsinghua.edu.cn/git/homebrew/homebrew-core.git export HOMEBREW_BOTTLE_DOMAINhttps://mirrors.tuna.tsinghua.edu.cn/homebrew-bottles /bin/bash -c $(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)还有一类更隐蔽的坑安装过程全程没有任何报错但在终端敲brew却提示zsh: command not found: brew。原因在于 Apple Silicon 和 Intel 芯片的 Homebrew 安装目录不同Apple Silicon 装在/opt/homebrewIntel 装在/usr/local。如果你的.zshrc里没有把对应路径的bin目录导进 PATHshell 就找不到它。Apple Silicon 上必须在 shell 配置里加上一句export PATH/opt/homebrew/bin:$PATH顺带提一句网上有些教程会让用户直接执行一串从第三方站点拉取安装脚本的命令zsh -c $(curl -fSSL https://xxx/install.sh)这类“一键脚本”我建议谨慎使用你根本不知道脚本在本地做了什么操作尽量以官方安装脚本或可信任的镜像站作为来源。1.3 Desktop 客户端和 CLI 的角色分工为什么“装了客户端”不等于“装好了 Codex”这是很多人最容易产生误解的地方。从官网下载的 Codex Desktop 是一个 Electron 应用它本质上是“壳”真正的对话、代码检索、模型调用逻辑是通过一个 CLI 子进程执行的。Desktop 应用启动时会在系统里找codex命令找到之后才能正常工作。所以如果你只装了 Desktop 客户端终端里敲codex当然会提示 command not found——因为 CLI 根本没装。反过来如果你的 Desktop 弹 “unable to locate the codex CLI binary”那就是它找不到后台那个命令行工具。理解了这两个角色的关系后面 Desktop 相关报错的排查思路就很清晰了。1.4 npm 安装慢、下载失败时的镜像与 registry 配置此外用 npm 安装时如果下载慢或者直接卡死不要反复重试同一个命令先把 registry 切到国内镜像npm config set registry https://registry.npmmirror.com再执行安装。这是个全局配置普通项目不会受影响只是把 npm 下载源切到了国内同步节点。切完之后可以通过npm config get registry确认。2. PATH 与 zsh排查“command not found: codex”的完整链路这个是 Codex 在 Mac 上报错的重灾区我把完整的排查链路写出来建议一步都不要跳每一步都有它存在的意义。2.1 第一步先确认codex 到底装到哪里了看到zsh: command not found: codex第一反应不是急着改 PATH而是先确认 codex 到底有没有装上、装到哪个目录了。先列出全局包看看npm ls -g openai/codex如果这里显示包名和版本号说明包确实装了。接下来找 install 路径npm prefix -g ls -l $(npm prefix -g)/bin如果 bin 目录里能看到codex这个可执行文件或软链那问题就非常明确了路径里没有指向这个 bin 目录。常见的三种 bin 位置官方 pkg 安装 Node 时npm 全局 bin 通常在/usr/local/binHomebrew 安装 Node 时npm 全局 bin 通常在/opt/homebrew/binApple Siliconnvm 安装 Node 时npm 全局 bin 通常在~/.nvm/versions/node/v20.xx.x/bin最后执行一下这个命令把当前 PATH 打出来echo $PATH | tr : \n肉眼扫一遍列表里有没有上面的 bin 目录基本就定位了。2.2 第二步理解 zsh 的 PATH 加载顺序.zshrc 与 .zprofile 的职责区分macOS 从 Catalina 开始默认 shell 就换成了 zsh配置文件有.zprofile、.zshrc、.zshenv三个。很多教程让人“把 export 写进 .zshrc”但如果你细心观察会发现登录 shell 和非登录 shell 加载的配置不一样。简单梳理一下.zshenv不管什么情况都会加载适合放最基础的环境变量.zprofile登录 shell 时加载适合放需要显示登录时才初始化的内容.zshrc交互式 shell 加载绝大部分场景都在这里配 PATH实操建议是把 PATH 相关配置统一写在.zshrc里因为终端里手动执行codex时打开的必然是交互式 shell.zshrc一定会被读取。写完记得source ~/.zshrc或者直接重开一个终端窗口。这里有个常见的迷惑行为有人同时改写了.zprofile和.zshrc两边各自追加 PATH结果 PATH 被重复拼接了很多次虽然不影响正常使用但排查的时候看着特别乱。我的习惯是只维护.zshrc一处。2.3 nvm/Homebrew/自定义 prefix 三种环境下 PATH 的差异三种环境对应三种不同的修复方式如果混着写会出问题。如果你用的是nvm那么需要确认.zshrc里有 nvm 的初始化脚本export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh只有 nvm 初始化完成后当前 Node 版本对应的 bin 目录才会被追加到 PATH 里。很多人重启终端后node能找到、codex找不到就是因为 nvm 初始化正常但 npm 全局 bin 目录不在 PATH。如果你用的是Homebrew 装的 Node在 Apple Silicon 上要把 Homebrew 的 bin 和 npm 全局 bin 一起加进去export PATH/opt/homebrew/bin:$PATH如果你按我前面的方法设置了自定义 npm prefix那就需要export PATH$HOME/.npm-global/bin:$PATH不同的变量写好后可以用which -a codex看 shell 实际找到的是哪个路径也可以echo $PATH再检查一次。2.4 Desktop 报“unable to locate the codex CLI binary”怎么办Desktop 端报这个错时处理方式不是改 shell 配置而是直接在 Desktop 的设置界面里指定 CLI 路径。先用终端找到 codex 的绝对路径which codex正常情况下会输出类似/opt/homebrew/bin/codex或$HOME/.npm-global/bin/codex。把这个绝对路径填到 Desktop 的 “Codex CLI path” 设置项里重启应用。如果which codex本身都没输出那说明终端侧 PATH 都还没弄好先回去处理第 2.3 节的内容。还要注意一个细节Desktop 是从 Finder 启动的它不会加载终端里的.zshrc。也就是说即使你的.zshrc配置完全正确Desktop 也可能因为读不到这个环境变量而找不到 CLI。这也是为什么我建议 Desktop 用户直接在设置里填绝对路径一劳永逸不依赖 shell 环境。3. 网络问题local proxy 转发失败与模型服务接入Codex 跑通之后紧接着可能踩到网络层的问题。这一章的报错文本看着很唬人拆开看其实就两件事请求从 CLI 发出后怎么被转发到模型服务以及目标模型服务的协议是否兼容。3.1 “cc switch local proxy failed while handling codex endpoint /responses” 到底在说什么先把这个报错拆开解释一下。Codex 的工具链里有一个本地请求转发组件也就是日志里所说的 local proxy。它的职责是把 CLI 或 Desktop 产生的对话补全请求统一转发到远端模型服务商同时负责拼装认证信息、写入日志、处理重试。这个设计让 Codex 可以插拔式地对接不同的模型提供方但也让排查多了一层。/responses是 OpenAI Responses API 的端点路径。你在 Codex 里发出的每一条消息最终都会以一个 HTTP 请求打到模型服务商的/responses端点。当 local proxy 在转发这个请求时抛了异常就出现了failed while handling codex endpoint /responses这样的报错。cc switch这个命令是用来切换模型 provider 配置的。很多人是在执行切换操作之后立刻遇到这个报错原因通常不是切换动作本身而是切换后的 provider 配置有残缺要么base_url指向的服务根本不可达要么 API key 没配置要么目标服务不支持/responses路径的协议。3.2 解码 /responses 端点Responses API 与 chat/completions 的协议差异这里要展开一个关键概念。早期 OpenAI 的 API 走的是/v1/chat/completions端点后来新版 Responses API 走的是/v1/responses。两者在请求参数和返回结构上有差异Responses API 是 OpenAI 当前主推的协议。Codex 在设计上默认使用/responses端点。如果你在config.toml里配置了一个只实现了/v1/chat/completions接口的服务但没有显式声明wire_api chat_completions那么 local proxy 转发到/responses路径时对方必然返回 404错误就会以 “failed while handling codex endpoint /responses” 的形式暴露出来。所以在排查这类问题时第一件事不是怀疑网络而是确认你配置的 provider 到底支持哪种协议。如果目标服务只兼容 chat completions 协议需要把 wire_api 字段设置为 chat_completions让 Codex 内部走协议转换或直接改用对应端点。3.3 接入第三方模型以 DeepSeek 为例的 profile 配置Codex 接入第三方模型的场景很常见很多人想通过它免费用上或者低费用体验不同家的模型。以接入 DeepSeek 为例配置文件在~/.codex/config.toml示例如下model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat_completions然后把 API key 写到环境变量里export DEEPSEEK_API_KEYsk-xxxx再运行codex switch或者直接启动Codex 就会把请求转发到 DeepSeek 的兼容端点。这里最关键的配置项就是wire_api我实测下来 DeepSeek 的兼容接口走的是 chat completions 协议如果漏掉这一项就会撞上前面说的/responses转发失败。另外base_url要以v1结尾还是不带v1不同服务商不一样。OpenAI 官方是带/v1DeepSeek 官方文档给的也是带/v1但有些服务商的文档写得含糊。拿不准的时候先用 curl 直接探一下目标地址能返回什么再决定怎么填curl -I https://api.deepseek.com/v13.4 排查网络层问题的顺序与方法综合我的经验网络层报错按这个顺序查效率最高第一步确认目标服务可达。直接 curl 一下配置的 base_url看通不通。如果不通先检查网络环境本身这个是最基础的前提。第二步确认认证信息。检查环境变量里是否真的有 API keykey 是否对应当前配置的 provider。很多人配置了多个 provider环境变量名 easydiff最终请求带着错误的 key 或者空 key 出去服务端返回 401。第三步检查 config.toml 里 provider 的 base_url、wire_api、env_key 三件套是否互相匹配。第四步打开调试日志看实际请求发去了哪里、返回了什么状态码。Codex 的调试日志开启方式通常是设置环境变量RUST_LOGdebug或者在设置里打开 debug 模式不同小版本可能不同以当前版本帮助信息为准。日志会直接打印出请求的完整 URL一眼就能看出 local proxy 是不是把请求转发到了你预期的地方。4. MCP 配置与 Desktop 客户端疑难杂症这一章处理两件事MCP 接入外部工具时的问题以及 Desktop 客户端本身的诡异故障。4.1 MCP 在 Codex 里的配置方式MCPModel Context Protocol是模型和外部工具之间的桥梁协议。通过 MCPCodex 可以读取本地文件、查数据库、操作浏览器等而不只是纯对话。Codex 里配置 MCP server 的地方同样是~/.codex/config.toml。文件系统中转 server 的典型配置长这样[mcp_servers.filesystem] command npx args [-y, modelcontextprotocol/server-filesystem, /Users/yourname/Documents]command是要启动的程序args是传给程序的参数。Codex 启动时会用command args拉起一个子进程通过标准输入输出和它通信这种叫 stdio 类型。还有一种走 HTTP 的 sse 类型多用于远程服务本地自用场景很少碰到。4.2 MCP server 启动失败的定位思路MCP 配置后 Codex 报错或者模型无法调用某个工具绝大多数是配置里的 command 路径或参数写错了。排查思路和排查普通子进程启动失败一样先手动在终端把这条命令原样跑一遍。比如配置里写的是command npx就先在终端执行npx -y modelcontextprotocol/server-filesystem /Users/yourname/Documents看看会不会报command not found、Cannot find module之类的问题。如果手动运行正常再看 Codex 配置里的 writable 目录路径是否有拼写错误。如果手动就报错那可能是 npx 不在 Codex 的 PATH 里——注意Desktop 从 Finder 启动时不加载 shell 环境npx 的路径它可能找不到这时候把 command 换成绝对路径最稳妥which npx然后把输出结果填进 command 字段。对于其他 MCP server涉及 Python 环境的还要注意用的是哪个 python 解释器虚拟环境里的路径和系统 Python 的路径完全不一样写错了同样启动失败。MCP 相关的报错文本五花八门但是定位思路高度一致先在外部手动启动一次成功后再让 Codex 去启动。4.3 Desktop 打不开、登录失败、缓存问题的处理Desktop 客户端用久了之后可能会遇到点击图标没反应、界面上一直转圈、登录页死活打不开这些问题。先说登录打不开。Desktop 的登录页本质是一个内嵌浏览器窗口它需要正确加载登录服务。如果网络本身能通但登录页空白优先怀疑缓存或本地状态损坏。解决方法是退出应用后清理 Codex 的本地目录。Codex 的状态默认在~/.codex下可以先备份再清理mv ~/.codex ~/.codex.bak.$(date %Y%m%d)重新启动 Desktop 后它会重新初始化目录。如果这样登录正常了再把备份里的配置逐项搬回来定位具体是哪份配置坏了。如果是应用完全打不开连图标都点不动先看 Activity Monitor 里有没有残留的 Codex 进程有就全部结束再重新打开。这能解决 70% 的 Electron 类应用假死问题。4.4 macOS 安全机制导致的权限弹窗处理有一类报错和 Codex 本身没关系而是 macOS 安全机制在“作怪”。比如下载解压的第三方工具在首次启动时弹窗提示“未打开 xxx.helper因其包含恶意软件”又或者提示某个辅助进程无法运行。macOS 会对所有从网络下载的、没有正确签名和公证的应用做隔离检查。被 Gatekeeper 拦截后系统会拒绝执行并弹出警告。处理方式分两种。第一种是在“系统设置 - 隐私与安全性”里找到对应提示点击“仍要打开”第二种是如果你对来源非常信任可以在终端里移除文件的隔离属性xattr -d com.apple.quarantine /path/to/app这个命令只对来源绝对可信的软件执行从网上下载的来路不明的工具宁可直接删掉也别放行。还有一种权限问题不是隔离属性导致的而是 macOS 的 TCC 隐私权限。比如 Desktop 读写某个目录时被拒绝需要在“系统设置 - 隐私与安全性 - 文件与文件夹”里给 Codex 或者你的终端 App 打开对应目录的权限。这类问题表面上的报错是“Permission denied”但根源是 macOS 对用户隐私目录的访问控制在 bash 里直接 chmod 是解决不了的。5. 高频报错速查清单与我的通用排查方法论最后把这篇文章涉及的主要报错整理成一张速查表后面遇到问题可以直接对照定位不用从头翻文章。5.1 报错速查对照表报错现象可能原因解决方向对应章节zsh: command not found: codexnpm 全局 bin 不在 PATH 里检查 .zshrc 并追加对应 bin 目录2.1 - 2.3unable to locate the codex CLI binaryDesktop 找不到 codex 可执行文件设置里填 CLI 绝对路径2.4EACCES permission deniednpm 全局目录无写入权限设置用户级 prefix不用 sudo1.1brew: command not foundHomebrew bin 目录不在 PATHApple Silicon 加 /opt/homebrew/bin1.2cc switch local proxy failed while handling codex endpoint /responsesprovider 配置不完整或协议不匹配检查 base_url、env_key、wire_api3.1 - 3.3404 请求到 /responses 端点目标服务只兼容 chat/completions设置 wire_api chat_completions3.2Desktop 登录页打不开本地缓存或状态损坏备份并清理 ~/.codex4.3应用弹窗未打开 xxx.helper 恶意软件macOS Gatekeeper 拦截隐私与安全性中“仍要打开”或清除隔离属性4.4MCP 工具无法调用command 路径不存在或参数错误手动执行命令行定位问题4.2远程目录 Permission deniedTCC 隐私权限未开放系统设置里额外授权4.45.2 一套通用排查三步法如果表格里找不到你遇到的报错我给你一套通用的排查思路几乎适用于所有 Codex 在 macOS 上的问题。第一步看完整原始报错。不要只看弹窗里的一行去终端启动时留意完整输出或者找日志文件。Codex 的日志在~/.codex/log/和~/Library/Logs/Codex/这些目录下不同版本位置略有差异里面记录的内容比终端输出详细得多。第二步最小化复现。把配置里的第三方 provider 全部去掉MCP server 全部禁用只留最基础的官方配置跑一次。如果能跑通说明问题出在你后加的某项配置上再把配置逐个加回来。这个方法比拿着一大堆配置瞎猜要好得多。第三步确认版本。codex --version看看当前版本是多少同时确认 Node 版本满足要求。Codex 更新频率很快很多怪异 bug 其实是旧版本的遗留问题升级往往比排查省时间。CLI 升级的话npm 全局安装的包直接重新执行一次安装命令即可。5.3 版本先行先确保 codex 和 Node 都是干净的版本还有一点值得单独提醒就是版本绑定。我遇到过一种情况Codex CLI 更新到新版本后旧版本 Desktop 无法识别表现就是 Desktop 里模型列表空白怎么刷新都没用。这时候如果只盯着 Desktop 的配置看方向就错了正确的是把 Desktop 也更新到和 CLI 匹配的版本。Node 的版本同理。Codex 要求 Node 18但如果你用的某个 MCP server 只支持更高版本或者反过来依赖旧版 API那就会出现“单测没问题、实际跑就报错”的情况。建议你长期保留一个干净的 LTS Node 版本作为跑 Codex 的环境不要和公司项目的 Node 版本混用。我在实际使用中养成了一个习惯任何配置改动前先备份~/.codex/config.toml一行cp ~/.codex/config.toml ~/.codex/config.toml.bak不费事但能让你在大胆尝试各种配置时没有后顾之忧。还有一点Codex 的 MCP 生态和 Desktop 功能迭代很快如果你按这篇文章操作仍然无效优先去官方仓库的 issue 里搜索报错文本大概率能找到已经被确认的 bug 或临时绕过的方案。