1. Codex CLI 装完就卡住先搞懂它到底怎么跑起来OpenAI Codex CLI 是一个跑在终端里的代码智能体能读你的仓库、改文件、执行命令、跑测试适合习惯命令行、想把 AI 编码能力嵌进本地工作流的开发者。它和编辑器插件最大的区别是Codex CLI 用 TOML 做配置、用 AGENTS.md 做项目记忆、用沙箱和审批策略管权限整套东西都在终端里完成。很多人第一次装完 Codex CLI 会卡在三个地方模型选不对、权限弹窗点不完、AGENTS.md 不知道写什么。这篇就按安装到进阶的顺序把模型切换、权限管控、AGENTS.md 配置技巧一条条拆开并且用 TaoToken 统一 Key 接入省掉单独申请通道的麻烦。先说清楚 Codex CLI 的定位。它不是补全工具而是一个能自主执行多步任务的 agent。你给它一句“把 Dashboard 组件重构成 React Hooks”它会自己找文件、改代码、跑 npm test、把 diff 给你看。这种能力靠的是沙箱加审批机制默认情况下它只能在工作目录里读写碰到目录外文件或联网操作会停下来问你。理解这套机制后面配权限才不会慌。安装方式按你的包管理器来。Node 环境用 npm 全局装npm install -g openai/codex装完验证版本codex --version如果你用 Homebrew也可以走 brew 通道。装好后第一次运行codex会进入交互式 TUI 界面这时候它会找认证信息。默认走 OpenAI 官方登录但如果你想像我一样用统一 Key 管理多个模型通道就往下看第二节的 TaoToken 接入。这里先给一个最小可跑的例子确认 CLI 本身没问题codex explain what this regex does: ^(?.*[A-Z]).{8,}$这条命令会让 Codex 解释一段正则属于纯读操作不涉及文件修改适合做冒烟测试。如果它能正常返回解释说明 CLI 装好了接下来才是配置模型和权限。新手最容易忽略的是工作目录。Codex CLI 的沙箱边界默认就是你启动它的那个目录所以进项目前先cd到仓库根目录再运行codex。否则它会把你 home 目录当工作区读文件的范围完全不对。我试过在错误目录启动结果它找不到 package.json一直问我要不要扩大权限白白浪费几轮对话。还有一点Codex CLI 的配置分两层全局配置在~/.codex/config.toml项目级配置在仓库里的.codex/config.toml。模型、推理等级、审批策略这些都能写进配置文件也可以用命令行参数临时覆盖。搞清楚这个优先级后面切换模型和权限就不会互相打架。命令行参数优先级最高其次是项目配置最后是全局配置。2. TaoToken 统一 Key 接入 Codex CLI 的前置准备TaoToken 在这里扮演的角色是统一 API 通道你不需要为每个模型单独维护一套 Key 和 Base URL而是用同一个 Key 走同一个入口在 Codex CLI 里通过配置指向它就行。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址不带 UTM 参数配置里填的就是这个干净地址。前置准备分三步。第一步拿到 Key。进控制台创建 API Key路径在 console 页面创建后复制出来形如sk-开头的一串。这个 Key 只显示一次建议先存到密码管理器。第二步确认你要用的模型 ID。Codex CLI 默认搭配的是代码专用模型你也可以在模型对话页面先试一下目标模型能不能正常回话确认通道通了再写进配置。第三步把 Base URL 和 Key 写进 Codex 的配置文件。Codex CLI 的认证信息放在~/.codex/auth.json配置项放在~/.codex/config.toml。这两个文件要一起改缺一个都会报 401。先看 auth.json 的结构{ OPENAI_API_KEY: sk-你的TaoToken密钥 }再看 config.toml 里跟通道相关的部分model gpt-5-codex model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chat这里三个要素必须齐全Base URL 指向 TaoToken 的 API 地址Key 放在 auth.jsonModel ID 在 config.toml 的 model 字段。少任何一个Codex CLI 启动时要么报认证失败要么报找不到 provider。我踩过的坑是只改了 config.toml 没动 auth.json结果一直提示 401排查了半天才发现 Key 根本没读进去。如果你用环境变量方式也可以这样export OPENAI_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/api但环境变量方式在 TUI 里不如配置文件稳定尤其是你开了多个终端窗口时容易串。建议还是落到 auth.json 和 config.toml 里一次配好长期用。配完先别急着跑复杂任务用一条只读命令验证通道codex exec say hello and tell me which model you are如果返回里能看到模型正常应答说明 Key、Base URL、Model ID 三件套都通了。这一步过了再进模型切换和权限配置才有意义。要是这里就报错直接跳到第五节对照报错排查。3. 可复制配置模型切换、推理等级与权限策略一次写全这一节给的是可以直接抄进配置文件的片段。Codex CLI 用 TOML和编辑器插件的 JSON 不一样注意别抄错格式。先看完整的~/.codex/config.toml示例model gpt-5-codex model_provider taotoken model_reasoning_effort medium approval_policy on-request sandbox_mode workspace-write [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chat逐项解释。model是默认模型model_reasoning_effort是推理等级可选 low、medium、high等级越高思考越深但消耗也越大。approval_policy控制审批行为sandbox_mode控制沙箱边界。这两个组合起来就是权限策略。模型切换有两种方式。临时切换用命令行参数codex --model gpt-5-codex -c model_reasoning_efforthigh-c是 set config 的缩写可以覆盖任意配置项。持久切换就改 config.toml 里的 model 字段。在 TUI 里也可以用/model命令交互式切换会弹出模型和推理等级的选择列表。权限策略这块Codex CLI 提供四种模式对应关系如下模式沙箱标志审批标志适用场景只读--sandbox read-only--ask-for-approval never代码阅读、安全审计请求审批默认默认常规开发、受控环境智能放行--sandbox workspace-write--ask-for-approval on-request日常开发推荐完全访问--dangerously-bypass-approvals-and-sandbox无完全信任环境高危日常开发我建议用智能放行工作目录内读写和跑命令自动放行碰到目录外文件或联网才弹窗。配置写法就是上面 config.toml 里的approval_policy on-request加sandbox_mode workspace-write。如果你要临时开完全访问跑一个批量重命名任务可以这样codex --dangerously-bypass-approvals-and-sandbox bulk-rename *.jpeg to *.jpg with git mv但这条命令别名是--yolo用之前确认仓库有 git 兜底改错了能回滚。我一般只在临时目录里用正式仓库不敢开。AGENTS.md 的配置也放这一节。它分三层全局~/.codex/AGENTS.md、项目根./AGENTS.md、子目录./components/AGENTS.md。项目级的优先级高于全局子目录的高于项目根。一个实用的项目级模板# 项目约定 ## 技术栈 - 前端 React 18 TypeScript - 测试用 Vitest跑 npm test - 提交前必须过 lintnpm run lint ## 代码风格 - 组件用函数式 Hooks不用 class - 文件命名用 kebab-case - 禁止直接改 generated 目录下的文件 ## 常用命令 - 启动开发npm run dev - 构建npm run build在 Codex 里输入/init可以让它帮你生成初始 AGENTS.md然后你手动补细节。这个文件相当于给 agent 的 README写得越具体它干活越少跑偏。4. 验证请求确认模型切换与权限策略真的生效配置写完不代表生效得逐条验证。第一步验证模型切换。启动 Codex 后输入/status会显示当前会话的模型、推理等级、Token 用量。如果显示的还是默认模型而不是你配的说明 config.toml 没被读到检查文件路径是不是~/.codex/config.toml。第二步验证推理等级。用命令行参数跑一条需要思考的任务codex -c model_reasoning_efforthigh review this repo and propose 3 high impact PRs对比 low 和 high 的输出深度high 会给出更详细的分析和更多候选方案。如果两者没区别可能是模型不支持该参数换个模型再试。第三步验证权限策略。在只读模式下试着让它改文件codex --sandbox read-only --ask-for-approval never add a console.log to index.js正常情况它会拒绝修改并告诉你当前是只读模式。如果它直接改了说明沙箱标志没生效检查参数拼写。第四步验证 AGENTS.md 是否被读取。在项目根放一个 AGENTS.md写一条特殊约定比如“所有注释用中文”。然后让 Codex 写个函数codex write a function to calculate fibonacci看它生成的注释是不是中文。如果是说明 AGENTS.md 生效了。如果还是英文检查文件是不是放在启动目录下或者用/status看它加载了哪些记忆文件。第五步验证 TaoToken 通道。跑一条 exec 命令看返回codex exec explain utils.ts返回正常且没有认证报错说明 Key 和 Base URL 都对。这一步和第二节的冒烟测试类似但这次是在完整配置下跑能验证配置之间没有冲突。验证完这五步你的 Codex CLI 基本就处于可用状态了。后面就是日常使用中按需调整模型和权限。5. 本篇常见报错排查401、local proxy failed、reading choices、OAuth报错一401 Unauthorized。最常见的原因是 auth.json 里的 Key 没写对或者 config.toml 里的 base_url 和 Key 不匹配。排查顺序先确认~/.codex/auth.json里OPENAI_API_KEY是 TaoToken 的 Key再确认 config.toml 里base_url https://taotoken.net/api没有多余斜杠或路径。两个都对还报 401就去 console 页面确认 Key 没过期、额度没用完。报错二local proxy failed。这个通常出现在你本地有网络代理设置但 Codex CLI 读不到或读到了错误的代理配置。Codex CLI 会读环境变量里的代理设置如果你之前设过HTTP_PROXY或HTTPS_PROXY指向一个已经关掉的本地端口就会报这个。解决方法是清掉相关环境变量unset HTTP_PROXY unset HTTPS_PROXY unset ALL_PROXY然后重开终端再跑。注意这里说的是清理本地失效的代理环境变量不是让你去配什么通道纯粹是排除干扰。报错三reading choices 相关错误。这个一般出现在模型返回格式和 Codex CLI 预期不一致时比如你用的模型不支持 chat 格式的返回结构。检查 config.toml 里wire_api chat是否和模型匹配。如果换模型后出现这个错先把 wire_api 改回默认再试。另外确认模型 ID 拼写正确写错的模型 ID 有时不会直接报 404而是返回一个空结构导致解析失败。报错四OAuth 相关报错。Codex CLI 默认走 OpenAI 官方 OAuth 登录如果你已经用 TaoToken 的 Key 接入就不需要再走 OAuth。出现 OAuth 报错通常是因为 auth.json 里同时存在 OAuth token 和 API KeyCLI 优先读了 OAuth。解决方法是清掉 auth.json 里 OAuth 相关的字段只保留OPENAI_API_KEY。如果 auth.json 里有tokens字段删掉它。排查通用思路先看报错里有没有 URL有 URL 就检查 base_url 配置再看有没有状态码401 查 Key404 查模型 ID429 查额度最后看是不是本地环境干扰清掉代理环境变量重试。每次改完配置记得重开终端Codex CLI 不会热加载配置文件。还有一个隐蔽的坑多个配置文件冲突。如果你同时有~/.codex/config.toml和项目里的.codex/config.toml项目级的会覆盖全局的。排查时用/status看实际生效的配置别只看你改的那个文件。6. 长期编码与 Agent 场景把 Codex CLI 用顺手的几个习惯Codex CLI 用久了会发现真正影响效率的不是模型多强而是你的工作习惯。第一个习惯是善用codex resume。长任务中断后不用重开直接codex resume --last恢复最近会话或者codex resume弹出选择器挑历史会话。会话 ID 可以在~/.codex/sessions/目录下找也可以用/status看。第二个习惯是上下文压缩。长会话跑到后面会触发上下文限制用/compact压缩一下能继续跑。但要注意压缩次数多了模型精度会下降重要任务建议压缩前先让它把关键结论写进文件。第三个习惯是自定义命令。Codex CLI 支持把常用提示词存成 Markdown 文件放在~/.codex/prompts/文件名就是命令名。比如存一个review.md里面写“仔细审查当前 diff列出潜在 bug 和安全问题”之后输入/review就能调用。注意自定义命令不支持参数提示词要自包含。第四个习惯是权限最小化。日常开发用智能放行模式只在临时任务里开完全访问。跑批量操作前先git status确认工作区干净出问题能回滚。如果你要把 Codex CLI 用在长期编码或 Agent 编排场景建议把模型和通道配置固定下来用 TaoToken 的统一 Key 管理省得每个模型单独维护。需要长期跑编码任务的可以看 Coding Plan 页面需要临时验证模型的去模型对话页面试接入配置细节在接入文档里查。API Key 在 console 的 api-keys 页面管理创建和吊销都在那里。最后说个实际经验Codex CLI 的 AGENTS.md 不要一次写太多先写技术栈和常用命令用一段时间发现它老犯某个错再把那条约定补进去。这样长出来的 AGENTS.md 才是真正贴合项目的比一开始抄一堆模板有用得多。