1. 从 Claude Code 迁到 Codex CLI为什么值得折腾这一趟如果你已经在终端里用 Claude Code 写了不少代码最近又频繁听到 Codex CLI 这个名字那这篇就是写给你的。Codex 是 OpenAI 推出的软件工程智能体核心是 codex-1 系列模型能通过自然语言驱动生成代码、修复错误、跑测试甚至提交 PR。它和 Claude Code、Gemini CLI 属于同一类产品终端里的智能编码助手。区别在于 Codex 的 ReAct 式循环更彻底——思考→工具调用→观察→重复会一直跑到模型不再请求工具、直接给出最终答案为止所以长任务不容易半路偷懒。适合谁三类人最该试一是被 Claude Code 复杂 bug 定位能力折磨过的后端同学二是想用同一套预算写更多代码、对成本敏感的独立开发者三是已经在用终端工作流、不想再开 IDE 的运维和全栈。我自己从 Claude Code 切过来最大的感受是任务完成度更完整它会主动把测试补上而不是告诉你已完成然后留个坑。但迁移不是复制粘贴就完事。Codex CLI 的配置体系和 Claude Code 完全不同它靠~/.codex/config.toml定义模型提供方靠环境变量注入 Key认证走auth.json或环境变量两条路。很多人卡在第一步——装完了不知道怎么把 Base URL 指到自己的 API 服务上或者auth.json写错字段导致 401。这篇就按安装→认证→Base URL 配置→验证请求→排错的完整路径走一遍所有配置片段都能直接复制。核心检索词先记住Codex CLI 安装、auth.json 配置、Base URL 设置、TaoToken 接入。2. TaoToken 前置准备拿 Key、认模型、理清 Base URL在动 Codex 之前先把大脑准备好。Codex CLI 本身只是个壳真正干活的是背后的大模型。只要兼容 OpenAI API 协议的服务理论上都能接。这里用 TaoToken 作为统一入口好处是一个 Key 能切多个模型省得为每个模型单独配环境变量。第一步打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册账号。注册流程不展开重点说拿 Key 的位置登录后进控制台找到 API Keys 页面新建一个 Key。这个 Key 就是后面auth.json和环境变量里要填的东西格式通常以sk-开头。新建后立刻复制保存页面刷新后可能不再完整显示。第二步确认你要用的模型 ID。Codex CLI 的配置里model字段必须写准确的模型标识比如gpt-5-codex、claude-sonnet-4.5、glm-4.6这类。写错了不会报模型不存在而是直接请求失败或者返回空 choices这点后面排错会细说。你可以在模型对话页面先手动试一下目标模型能不能正常回话确认可用再写进配置。第三步理清 Base URL。TaoToken 的 API 入口是 https://taotoken.net/api 注意这里不加任何 UTM 参数配置里就写这个干净地址。Codex 的config.toml里base_url字段要填到/v1这一层也就是https://taotoken.net/api/v1因为 Codex 内部会按 OpenAI 的/chat/completions路径拼接。这一步写错是最常见的 404 来源。关于认证方式Codex CLI 支持两种一种是环境变量env_key在config.toml里声明变量名运行时从环境读取另一种是auth.json把凭证写进文件。两种不要同时配否则行为不确定。我建议本地开发用环境变量CI 或容器里用auth.json因为文件更好挂载。下面两节分别给可复制片段。3. 可复制配置config.toml、auth.json 与 settings 片段先装 CLI。Node 环境准备好后一条命令npm install -g openai/codex装完执行codex --version能打印版本号就说明二进制到位了。接下来创建配置目录。macOS 和 Linux 是$HOME/.codex/Windows 是C:\Users\你的用户名\.codex\。目录不存在就手动建mkdir -p ~/.codex然后写~/.codex/config.toml。这是 Codex 的核心配置文件模型提供方、Base URL、环境变量名、推理力度都在这里。下面这份可以直接复制把model换成你要用的模型 ID# ~/.codex/config.toml profile taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api/v1 env_key TAOTOKEN_API_KEY wire_api chat [profiles.taotoken] model gpt-5-codex model_provider taotoken model_reasoning_effort high几个字段解释清楚wire_api chat表示走 OpenAI 的 chat completions 协议这是兼容性最好的选项model_reasoning_effort控制推理深度high适合复杂任务日常改小 bug 可以调medium省钱profile顶层字段决定默认加载哪个 profile切换模型时改这里或者用/model命令。如果你更倾向用auth.json而不是环境变量把env_key那行删掉改成在~/.codex/auth.json里写{ OPENAI_API_KEY: sk-你的TaoToken密钥 }注意auth.json的字段名是固定的OPENAI_API_KEY不是自定义的。Codex 读这个文件时会按这个键取值。文件权限建议收紧chmod 600 ~/.codex/auth.json环境变量方式则更直接。macOS/Linux 写进~/.bashrc或~/.zshrcexport TAOTOKEN_API_KEYsk-你的TaoToken密钥然后source ~/.zshrc让当前终端生效。Windows 用set临时设置或者进系统环境变量面板持久化。验证变量是否生效echo $TAOTOKEN_API_KEY能打印出 Key 就对了。这里有个坑config.toml里的env_key值必须和实际环境变量名完全一致大小写敏感写成TAOTOKEN_API_KEY就不能在环境里叫taotoken_api_key。4. 验证请求跑通第一次 Codex 调用与成功结果判断配置写完进一个 git 仓库目录直接敲codex首次启动会让你选审批模式。选 1 是允许 Codex 自由操作选 2 是每次写入都确认。建议先用 2观察它的行为熟悉后再放开。Windows 用户如果提示需要 WSL按提示装一个因为 Codex 依赖 bash 命令执行器cat、grep、apply_patch这些工具在纯 CMD 下跑不起来。进入交互界面后先跑/status确认当前模型和审批模式/status输出里应该能看到model: gpt-5-codex、provider: taotoken、approval: on-request这类信息。如果模型显示的是默认值而不是你配的说明profile没生效回去检查config.toml顶层profile字段拼写。接着发一条最简单的请求比如帮我在当前目录创建一个 hello.py打印 Hello Codex正常情况你会看到它调用 shell 工具、生成文件、然后返回结果。成功的关键标志有三个一是没有报 401 或 403二是返回内容里有实际的工具调用记录而不是纯文本空谈三是hello.py真的出现在目录里。如果只看到文字回复但没有文件落地多半是审批模式拦住了写入输入/approvals切到自动模式再试。想更直接地验证 API 通不通可以绕过交互界面用一条 curl 打 TaoToken 的接口curl https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: gpt-5-codex, messages: [{role: user, content: say ok}] }返回 JSON 里有choices[0].message.content就说明 Key 和 Base URL 都没问题。这一步能把Codex 配置问题和API 服务问题彻底分开排错时非常有用。实测下来先 curl 通再接 Codex能省掉一大半瞎猜的时间。5. 本篇常见错排查401、local proxy failed 与 reading choices迁移过程中最容易撞的几个报错逐个拆。401 Unauthorized。九成是 Key 没读到。先确认echo $TAOTOKEN_API_KEY有输出如果为空说明source没执行或者写错了 shell 配置文件zsh 用户写进.bashrc是不生效的。用auth.json的话检查字段名是不是OPENAI_API_KEY以及文件路径是不是~/.codex/auth.json。还有一种隐蔽情况config.toml里同时留了env_key和auth.jsonCodex 优先读环境变量环境变量为空就报 401把env_key删掉即可。local proxy failed / connection refused。这个报错说明 Codex 连不上base_url。检查三处一是地址有没有写成https://taotoken.net/api少了/v1Codex 会拼成/api/chat/completions导致 404二是本地网络能不能访问该域名用curl -I https://taotoken.net/api/v1看返回码三是公司网络如果有出口限制需要走允许的通道这块按你所在环境的合规要求处理。reading choices 相关报错比如 cannot read properties of undefined (reading choices)。这通常不是网络问题而是返回体结构不对。原因多半是wire_api配错了比如写成了responses但服务端只支持 chat 协议。改回wire_api chat基本能解决。另一个可能是模型 ID 写错服务端返回了错误对象而不是正常的 choices 数组Codex 解析时就崩了。用上一节的 curl 命令确认模型 ID 拼写。OAuth 相关报错。如果你之前用 ChatGPT 账号登录过 Codex本地可能残留了 OAuth 凭证和 API Key 模式冲突。执行codex logout清掉登录态再重新用 Key 模式启动。VSCode 插件里的 Codex 会共用~/.codex/config.toml如果插件里跳转 ChatGPT 登录CLI 这边可能被带偏两边认证方式保持一致最省心。模型切换后不生效。改了config.toml的model字段但/status还是旧模型多半是当前会话缓存了配置。退出重进或者在会话里用/model手动切。另外profile顶层字段如果指向的不是你改的那个 profile改了也白改确认profile taotoken和[profiles.taotoken]对得上。6. 长期编码与 Agent 场景把 Codex 用顺的下一步跑通基础调用只是开始。Codex 真正拉开差距的地方在长周期任务和 Agent 式工作流。几个实用动作进仓库先跑/init生成AGENTS.md把测试命令、代码规范、CI 标准写进去之后 Codex 每次都会读这份文件产出会贴合你的工程惯例开发中随时/review让它基于 git diff 做审查比等到 PR 阶段再发现问题早得多长对话快超上下文时用/compact压缩避免中途断掉。模型选择上复杂重构和跨文件 bug 用gpt-5-codex配high推理力度日常小改用medium甚至low成本能压下来不少。需要切换时改config.toml的model字段或者会话里/model直接切。如果你要接 MCP 扩展能力配置同样写进config.toml用/mcp命令查看已挂载的工具。想把 Codex 纳入日常开发流建议配一个 Coding Plan把模型调用和额度统一管理长期跑 Agent 任务时不用每次担心 Key 的余额。接入文档里有完整的 Base URL 和认证说明遇到配置细节可以直接对照。模型对话页面可以先手动验证目标模型是否可用确认后再写进config.toml避免在 CLI 里反复试错。API Keys 页面管理你的凭证定期轮换更安全。