macOS安装配置Codex与Claude Code实战指南

如果你最近打开过 macOS 的终端大概率已经在各种技术群里看到过这两条命令npm install -g openai/codex和npm install -g anthropic-ai/claude-code。Codex 是 OpenAI 推出的命令行编码代理Claude Code 是 Anthropic 的同类产品它们能让 AI 直接在你的本地仓库里读代码、改文件、跑命令、提 PR整个流程从“我和 AI 对话”变成“AI 在我的电脑上干活”。这篇博文会把 Mac 上安装配置这两套环境的所有步骤、坑和思路一次讲清楚适合刚接触 AI 编程、想在本机跑通这两个工具的同学参考。全文基于我在 Intel 和 Apple Silicon 两台 Mac 上的实际安装经历包括镜像加速、权限坑、认证失败和本地模型接入照着做基本能省下半天折腾时间。1. 先把思路理清Codex 和 Claude Code 到底是干什么的1.1 两个工具的本质区别这两个工具名字听着像竞品实际上定位也确实高度重合都是跑在终端里的 AI 编程代理都能理解项目结构都能自动改代码、执行命令、看报错信息并自己迭代修复。但它们的实现思路有明显差异这决定了你后续的配置方式和使用习惯。CodexCLI 版继承了 OpenAI 在 GPT 系列模型上的工程能力它的强项是代码补全、多文件重构和遵循严格的项目规范。默认模型是 GPT-5 系列具体版本会随官方更新对 TypeScript、Python、Go 等主流语言的把握很稳。它的工作方式更像“远程员工”你把任务交给它它会自己规划步骤调用工具跑测试然后把改动结果汇报给你。Claude Code 则是 Anthropic 的产品Claude 系列模型在长上下文理解和复杂指令遵循上口碑很好。对于那种“这个老项目我完全没看过你帮我梳理下架构”的需求Claude Code 的表现往往让人眼前一亮。它读取整个代码库的能力很强而且和 Claude 订阅账号深度打通如果你已经是 Claude Pro 或 Max 用户可以直接用订阅身份运行不需要单独为 CLI 买 API 额度。下面这张表是我用下来的直观对照对比维度Codex CLIClaude Code开发方OpenAIAnthropic默认模型GPT-5 系列Claude Opus / Sonnet认证方式ChatGPT 账号登录 / API KeyClaude 订阅账号 / API Key强项格式化代码、多语言重构、测试生成超大仓库理解、需求拆解、长任务执行配置复杂度中等config.toml中等交互式 /config本地模型支持支持 OpenAI 兼容接口支持 Anthropic 兼容接口如 LM Studio1.2 为什么用 CLI 而不是直接打开网页版我在最开始也犹豫过网页版 ChatGPT 或 Claude 不也能写代码吗为什么非要在终端里装一套工具用过一周后我的感受是——这是两种完全不同的协作模式。网页版的典型流程是你把代码片段复制进对话框AI 给你改好的片段你再复制回编辑器手动跑测试报错后再复制回去……来回搬运信息效率很低。而 CLI 代理直接住在你的项目目录里它不需要你复制粘贴因为文件就在它手边。你说“修复一下登录接口的内存泄漏”它会自己打开相关文件、定位可疑代码、修改、运行测试然后告诉你结果。这种“代理式”工作流让我从繁琐的上下文搬运里解放出来特别是做跨文件重构的时候价值尤其明显。还有一个非常实际的原因CLI 工具能和你的 Git 工作流无缝衔接。Codex 和 Claude Code 都可以在改动前自动创建分支、写规范的 commit message甚至直接推送到远端发起 PR。这是网页版做不到的。对需要频繁交付代码的开发者来说省的不只是时间还有大量机械操作。1.3 我的选型建议如果你只能选一个我的建议是看你的账号情况。手头有 ChatGPT Plus 或 API 额度优先 Codex已经是 Claude Pro / Max 订阅用户Claude Code 上手成本最低。两个都装也完全没问题它们共用终端的 Agent 模式但在一个项目里建议只启用其中一个避免两个代理同时改文件造成冲突。提示这两个工具目前都在快速迭代阶段安装时不要只盯着“最新版”这个词更重要的是锁定自己用的 Node 版本和认证方式。版本更新频繁后面我会专门讲到锁版本的问题。2. 安装前的准备工作环境没配好后面全是坑很多人装 Codex / Claude Code 失败其实不是这两个工具本身难装而是 macOS 基础环境没过关。我在实战中踩过的坑主要集中在 Homebrew、Node.js、Git 和 API 凭证这几块提前排查能省一大半麻烦。2.1 Homebrew 安装与加速方案Codex 和 Claude Code 的官方推荐方式都是通过 npm 安装而 npm 通常由 Node.js 自带。问题来了Mac 上装 Node.js 最省心的方式就是通过 Homebrew如果你连 Homebrew 都没有第一步就卡住了。网上搜“mac 安装 Homebrew 失败”能看到大量求助帖绝大多数症状其实就两种下载慢、脚本执行中断。如果你直接运行官网那条安装命令在国内网络环境下经常会卡在下载阶段。标准的解决思路是使用国内镜像源比如清华 TUNA 或中科大镜像。操作上可以直接把安装脚本中的仓库地址替换为镜像地址或者装完之后重新设置 git remote。我自己更推荐后者先按官方脚本安装如果慢就换镜像这套流程更稳定。安装成功后建议立刻执行一次brew update并确认brew doctor没有报严重错误。如果提示Command Line Tools未安装直接执行xcode-select --install这个是后续安装 Node 原生模块时的隐型依赖漏掉的话后面 npm install 容易在编译环节爆红。2.2 Node.js 版本管理不要裸装Codex CLI 对 Node 版本有硬性要求官方文档写的是 Node 18但我在实测中发现Node 20 以下的版本偶尔会出现 WebSocket 连接不稳定、模型流式响应中断的情况。所以我不建议直接brew install node装一个全局版本了事更推荐用版本管理工具。macOS 上我用的是 fnmFast Node Manager安装就一条命令brew install fnm然后在 shell 配置里加一行初始化脚本。你也可以用 nvm原理一样找个你顺手的。版本管理的好处是哪天 Codex 要求 Node 22或者某个旧项目依赖 Node 16你随时切换不用把全局环境搞成一团乱麻。装好后把 Node 切到 LTS 版本比如 22.x然后确认 npm 能正常访问仓库。如果npm install提示网络超时可以配置 npm 镜像源注意只改 registry不要动其他乱七八糟的配置。2.3 Git 配置与终端权限两个 CLI 工具都会频繁调用 Git创建分支、提交、回滚、查看 diff。如果你的 Git 没配好它们干活时会莫名报错。至少保证这三项是配好的git config --global user.name和user.email、SSH key 已添加到 GitHub / GitLab、默认分支名统一比如 main。终端权限这块是新手最容易懵的。Codex 和 Claude Code 首次运行时都会申请“完全磁盘访问权限”弹窗出现时很多人直接点拒结果发现工具只能读文件不能写文件。正确做法是在系统设置里把终端或 iTerm2加入“隐私与安全性”-“完全磁盘访问权限”列表然后重启终端。注意改完权限一定要重启终端进程否则不会生效。2.4 API Key 准备与收费方式认证方式直接影响你要不要提前准备 API Key。如果你走 ChatGPT / Claude 订阅账号登录基本不用额外准备什么登录后自动绑定订阅额度。但如果你要用 API Key 方式比如想接入第三方模型、或者做精细的用量控制需要提前去对应平台的开发者后台创建 Key。这里要特别提醒Codex 和 Claude Code 的 API 计费和订阅计费是两套体系。订阅账号登录时消耗的是你的订阅额度有速率限制API Key 模式下按 token 计费写大任务时费用会肉眼可见地涨。建议第一次跑通时先给一个小任务验证不要一上来就扔一个几万行项目进去不然月底账单会教你做人。3. Codex 安装配置实战从零到跑通第一个任务3.1 用 npm 安装 Codex CLI环境整理干净后安装 Codex 本身很简单。官方推荐方式是 npm 全局安装npm install -g openai/codex安装完成后先确认版本号codex --version能正常输出就说明安装成功。这里有个实测细节如果 npm 全局路径没配好会出现codex: command not found。用npm config get prefix查看全局安装路径然后把对应的 bin 目录加入你的 PATH 环境变量。我用的是 fnm全局 bin 通常在~/.local/share/fnm相关的路径下。安装时如果报权限错误不要直接sudo npm install -g那是饮鸩止渴。正确做法是检查 npm 全局目录的所有权或者改用 fnm/nvm 管理 Node这样全局包会装到用户目录下不再碰系统级目录权限。3.2 登录认证的两种方式Codex 支持两种认证模式第一种是 ChatGPT 账号登录codex login执行后会打开浏览器授权后命令行自动完成登录。这种方式的优势是方便直接用你已有的 ChatGPT 订阅额度不需要单独管理 API Key。但要注意组织账号比如公司统一开通的 ChatGPT Business在部分情况下会被限制使用 CLI报错信息往往是权限相关后文排查部分有详细分析。第二种是 API Key 模式环境变量方式配置export OPENAI_API_KEYsk-...或者写一个.env文件在项目目录里放好。我个人更喜欢环境变量方式因为不会搞乱多个项目的配置。API Key 模式的好处是计费独立、可用云账号统一管理适合公司内部按项目核算的情况。3.3 config.toml 核心配置项Codex CLI 的配置文件是~/.codex/config.toml这是它和 Claude Code 差异比较大的一点Claude Code 更偏交互式配置而 Codex 倾向于静态文件。第一次运行后会自动生成默认配置我经过多次调整保留下来一组高频配置model gpt-5.2-codex approval_policy on-failure sandbox_mode workspace-writemodel字段指定默认模型可以按需要换成其他支持版本。approval_policy是权限批准策略on-failure表示仅在命令执行失败时才询问on-request是每次执行都询问never是全自动执行新手建议用on-request先观察它每一步在干什么熟悉后再放手。sandbox_mode控制沙箱范围workspace-write允许写当前工作区但不碰外部目录整体安全性和自由度比较均衡。如果你要接入 OpenAI 兼容接口的第三方模型比如 DeepSeek 这类可以在配置里指向自定义 base URL。不过不同模型对工具调用的格式支持程度不同实测下来兼容性最好的还是 OpenAI 官方模型第三方模型建议用一个单独配置或目录避免影响主力工作流。3.4 第一个任务让 Codex 真正干活装好之后我建议不要直接上重活先用一个小练习验证全链路。找个空目录初始化一个 Node 项目然后用自然语言下指令codex 创建一个 express 服务器监听 3000 端口提供一个 /health 接口返回 JSON观察它的行为正常流程是它先规划文件结构然后逐文件写入再安装依赖最后启动服务验证。整个过程中你会看到它对代码库的读写动作、Shell 命令的执行记录。跑通后说明安装配置全部正确可以放心进入真实项目。这里有一个我反复强调的习惯让 Codex 独立完成“改动 测试 修复”循环时务必用 Git 做好版本隔离。最省心的做法是让它自己开分支不要直接在主分支上乱动。哪怕中途失败也可以一键丢弃重来。3.5 模型切换与本地模型接入Codex 支持通过环境变量CODEX_MODEL或配置文件临时切换模型。如果你在 config 里设了默认模型但某个任务想用更强的推理模型可以直接运行CODEX_MODELgpt-5.6-codex codex 分析这个项目的安全漏洞模型名要写准确写错会报model is not supported错误我踩过这个坑。还有一种玩法是接入本地模型通过 LocalAI 或 vLLM 启动一个 OpenAI 兼容服务然后在配置里把 base URL 指向http://localhost:8080/v1。不过本地模型跑 Codex 的 Agent 循环需要很强的工具调用能力普通 7B 模型基本带不动至少要 32B 以上才有可用性而且速度受限于你的显卡。如果没有特殊需求建议还是优先用官方模型。4. Claude Code 安装配置实战订阅账号直连与本地模型4.1 安装与首次启动Claude Code 同样通过 npm 安装命令行略有不同npm install -g anthropic-ai/claude-code安装后运行claude进入交互界面。首次启动建议在项目的根目录执行这样它能立刻感知项目结构而不是空跑一个 Shell。如果你在 VS Code 里用官方还提供集成方式但我个人测试下来独立的终端窗口反而是最顺手的状态因为可以方便地上下翻看大量输出日志。4.2 认证方式对比Claude Code 的登录路径跟 Codex 有明显差异。如果你有 Claude 订阅账号直接在 CLI 里执行登录按提示完成浏览器授权即可。这种方式的额度与你的订阅套餐绑定Pro 用户有每日消息上限Max 用户额度更高。实测中订阅登录方式跑日常开发任务足够但如果是超大代码库或长时间自动化任务订阅账号的速率限制会有点难受。另一种方式是 Anthropic API Key。创建 Key 后同样通过环境变量注入export ANTHROPIC_API_KEYsk-ant-...这里有个重要区别API Key 模式下默认不包含订阅权益按 token 计费。而且要留意即使你同时拥有订阅和 API KeyCLI 通常只认其中一种切换认证方式时最好先清理掉旧的凭证缓存文件在~/.claude目录下。有些用户遇到your organization has disabled claude subscription access for claude code的报错本质就是订阅权限在组织层面被禁用工作区管理员关闭了 CLI 访问权限这时候只能走 API Key 或以个人账号登录。4.3 权限授权与会话管理Claude Code 在首次进入项目时会展示授权说明你需要同意它读取文件、执行命令。和 Codex 一样它也支持细粒度权限控制。具体管理方式是输入/permissions命令可以设置不同命令的自动放行策略。我建议的配置是文件读取自动放行Shell 执行每次询问网络请求需要确认。这套策略既保证效率又不会让 AI 在你不知不觉中执行高风险操作。提示Claude Code 会生成CLAUDE.md这样的记忆文件你可以把项目规范写进去比如“不要改公共接口”“测试命令是 pnpm test”它会在后续任务中自动遵守。这招非常实用等于给 AI 写了一份项目操作手册。4.4 本地模型联动以 LM Studio 为例关于热词里的claude code 调用 lmstudio 的本地模型这个需求在很多开发者中很流行主要是为了隐私和数据安全考虑。LM Studio 是 Mac 上跑本地大模型最省心的图形化工具之一能加载 GGUF 格式模型并启动兼容 OpenAI 的本地服务。要让 Claude Code 使用 LM Studio 的模型通常需要设置两个环境变量ANTHROPIC_BASE_URL指向http://localhost:1234之类的本地地址以及对应的模型名变量。不过这里要泼一盆冷水Claude Code 对基础模型的工具调用格式要求很严格很多量化后的开源模型在交互中会出现“理解任务但拒绝调用工具”或“调用格式错误”的情况。实测下来能稳定驱动的本地模型需要足够大的参数量比如 70B 量级的量化版Mac 上要跑得顺畅至少得 64GB 内存。M 系列芯片配合大内存确实能跑但速度远不如云端 API 直接利落。我的定位是本地模型适合做离线实验、敏感代码处理不适合当主力日常驱动。4.5 高效使用/config 与内存管理Claude Code 的配置是动态的输入/config可以快速调整模型、输出风格、权限策略等。跟 Codex 的静态配置文件相比这种方式更直觉但不利于跨机器同步。如果你有多台 Mac可以考虑把你常用的设置写进项目的CLAUDE.md或全局配置文件中。内存管理是 Claude Code 在长会话中必须注意的问题。随着对话轮次增长上下文窗口会持续累积。当它开始“忘记”项目里的关键文件时通常就是上下文过载了。我的习惯是一个功能需求开一个新会话并在开头简述项目背景用/compact压缩历史对话或者在关键节点/clear重置上下文。这比让它带着一大堆陈旧信息继续干活要可靠得多响应速度和准确性都有明显提升。5. 常见问题与排查技巧实录5.1 Codex 常见报错速查codex: command not foundnpm 全局安装路径没进 PATH检查npm prefix对应的 bin 目录加入 shell 配置即可。model is not supported when using codex with a...模型中指定了当前环境下不支持的版本。比如你手误写了个不存在或未开放的模型名。处理方式是修改 config.toml 中的模型字段或用CODEX_MODEL环境变量覆盖为官方支持的模型。cc switch local proxy failed while handling codex endpoint /responses这类错误通常发生在你配置了本地代理转发比如把请求转发到自定义网关做统一审计或限流时地址或协议配置不正确。检查代理服务的监听地址、路径前缀是否与 codex 配置匹配建议先把代理相关配置临时去掉确认官方直连正常后再逐步加回。登录后仍然提示无权限检查你的 ChatGPT 账号是否是组织管理账号部分组织会在后台关闭 CLI 功能。如果你用的是团队版找管理员确认或者直接用个人账号登录很多报错会瞬间消失。5.2 Claude Code 常见报错速查your organization has disabled claude subscription access for claude code字面意思是组织禁用了 Claude Code 的订阅访问。常见于公司统一管理账号解决方案是让管理员开启权限或改用个人订阅账号 / API Key 方式登录。认证成功但一直 429速率限制触发。订阅账号的并发和 RPM 都有限制建议暂时降低任务频率或者考虑切换到 API Key 模式如果预算允许。输出乱码或中断多半是终端编码问题。确保终端是 UTF-8 编码并且没有使用不支持的字符集。某些旧版 iTerm2 会遇到流式输出的渲染问题升级到最新版基本能解决。Agent 修改了不该改的文件这是权限策略没设置好。用/permissions把文件写权限从“全部允许”改成“每次询问”危险操作自然被拦下来。报错信息主要原因推荐处理command not foundPATH 未包含 npm 全局 bin修复 PATH 配置model is not supported模型名不存在/不兼容改用官方支持模型organization has disabled组织订阅权限被禁用换个人账号或 API Key429 rate limit触发速率限制降频/升级套餐/API Keylocal proxy failed本地转发配置错误检查代理地址与路径前缀5.3 Homebrew 和 Node 的通病很多安装失败的根因不在 Codex / Claude Code而是 Homebrew 本身。常见表现为brew install卡在Updating Homebrew...。这个问题的标准解法是替换 Homebrew 的远程仓库为镜像源清华、中科大都有对应文档执行两行git remote set-url就能解决。Node 方面最常见的坑是版本过旧。如果npm install时出现 engine 不满足的警告不要装完就完事卡在“能用但行为怪异”的状态建议直接切换到 Node 20 的 LTS。另外npm cache 损坏也会导致莫名其妙的安装失败执行npm cache clean --force后重试成功率很高。5.4 避坑心得来自多次重装后的总结第一不要在系统自带的 Python 或 Ruby 环境里碰 Codex / Claude Code。它们之间没有任何依赖关系但网上很多教程会把事情搞复杂让你去装各种层级的依赖。这两款工具本质就是一个 Node 全局包不需要额外运行时。第二配置文件最好纳入版本管理。特别是你精心调整过的config.toml或CLAUDE.md建议复制一份到自己的 dotfiles 仓库里换新电脑时五分钟还原环境不用重新踩一遍配置坑。第三模型选择比工具重要得多。同样的任务Codex 用默认模型和 Claude Code 用 Sonnet 的表现可能完全不同。我的经验是把两个工具都装好遇到具体项目时分别试几次再决定哪个作为主力。毕竟工具只是壳真正干活的是后面的模型和你的任务拆解能力。最后再分享一个小技巧跑了这么久的本地 AI 编程代理我个人养成的习惯是日常小改动用 Claude Code因为它对项目整体语境的感知更敏锐适合快速理解陌生代码库涉及大规模重构、需要严格代码风格和多文件搬移时切到 Codex它在工程化操作上更踏实。两个工具共用同一套 Git 工作流互相补充反而比只押注一个更高效。最后提醒一句这些 CLI 工具几乎每个月都在更新安装了就跑一次npm update -g既能让体验保持稳定也能避开一些已经在版本迭代中修复的旧 bug。