1. 第一次跑 Codex 卡在哪安装命令、auth.json 与 Base URL 三件事OpenAI Codex 是一个能进入你项目目录、读文件、改代码、跑命令的 AI 编程代理适合刚接触它、想从零跑通第一个代码任务的开发者。很多人第一次上手时卡点并不在“会不会写提示词”而是环境没打通CLI 装完不知道登录方式、~/.codex/auth.json该写什么、Base URL 指向哪里、模型 ID 填哪个。这篇就按“安装 → 配置 → 跑通第一个任务 → 排错”的顺序把每一步都写成可以直接复制的形式。我试过在 macOS 和 Windows 上各装一遍结论是只要把认证和 Base URL 这两处配对后面让 Codex 读项目、改文件、跑测试都会顺很多。下面所有配置都以~/.codex/目录为准Windows 对应C:\Users\你的用户名\.codex\。先明确 Codex 的几种入口避免你装错东西入口适用场景配置文件Codex CLI终端工作流、服务器、自动化~/.codex/config.tomlauth.jsonCodex IDE 扩展VS Code / Cursor / Windsurf 里边看边改同上扩展读取同一目录Codex App图形界面管理多任务同上Codex Web/Cloud云端跑长任务、接 GitHub网页端配置新手建议从 CLI 起步因为它最容易验证“到底通没通”。装完之后你会在项目根目录运行codex它会读取当前工作区然后按你的自然语言指令干活。第一个任务不要选“重构整个项目”选一个可验证的小目标比如“新增一个/health接口并补测试”这样成功与否一眼能看出来。环境准备清单Git用于回退、Node.js可选npm 安装方式需要、一个本地代码项目、一个可用的 API Key。如果你打算用 TaoToken 作为接入点Key 在控制台的 API Keys 页面生成Base URL 用https://taotoken.net/api。这两样东西后面会分别写进auth.json和config.toml。2. 用 TaoToken 打通 Codex 的认证与 Base URL 前置配置Codex CLI 默认会引导你用账号登录但在很多本地开发场景里用 API Key 自定义 Base URL 的方式更可控也方便团队统一管理。TaoToken 在这里扮演的是“统一接入层”的角色你拿到一个 Key把 Base URL 指向https://taotoken.net/apiCodex 的请求就会走这个入口模型侧仍然是你选定的模型 ID。这一步的核心是理解两个文件的分工~/.codex/auth.json负责“我是谁”——存放 API Key。它的结构是一个 JSON 对象字段名要和 Codex 读取的键一致写错键名会出现 401。~/.codex/config.toml负责“连哪里、用哪个模型、权限多大”——存放 Base URL、模型 ID、审批策略、沙箱模式。先建目录如果还没有mkdir -p ~/.codex然后写auth.json。注意这是敏感文件不要提交到 Git也不要把真实 Key 贴到任何公开地方。{ OPENAI_API_KEY: sk-你的TaoToken密钥 }这里的键名OPENAI_API_KEY是 Codex 读取 API Key 时使用的字段。如果你之前登录过官方账号这个文件里可能还有别的字段追加或替换时保持 JSON 合法即可多个键之间用逗号分隔最后一项后面不要留逗号。接着写config.toml把 Base URL 和模型 ID 一起定下来model gpt-5.5 model_provider taotoken approval_policy on-request sandbox_mode workspace-write model_reasoning_effort high [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chat几个字段的含义逐个说清楚model是你要调用的模型 ID必须和接入方支持的模型名一致写错会报模型不存在。model_provider指向下面[model_providers.taotoken]这个段Codex 会按这个段里的base_url发请求。base_url就是接入地址注意结尾不要多加/v1之类的路径除非文档明确要求这里用https://taotoken.net/api。wire_api表示请求协议形态chat对应常见的对话补全接口。approval_policy on-request表示 Codex 在执行敏感操作时会先问你新手别一上来就设成完全放行。sandbox_mode workspace-write表示它只能在当前工作区写文件不会乱动系统其他目录。如果你更习惯用环境变量而不是auth.json也可以在启动前导出export OPENAI_API_KEYsk-你的TaoToken密钥 export OPENAI_BASE_URLhttps://taotoken.net/api但要注意环境变量和auth.json同时存在时优先级可能因版本而异。为了排错简单建议只用一种方式推荐auth.jsonconfig.toml的组合因为它是持久化的重开终端不用重新导出。配置写完先别急着跑任务用一条最小请求验证认证是否生效这一步在下一节展开。3. 可复制的 config.toml 与 auth.json 完整配置片段这一节把上一节的文件补全成“可以直接抄”的版本并说明路径、权限和常见变体。路径统一为macOS / Linux~/.codex/config.toml、~/.codex/auth.jsonWindowsC:\Users\你的用户名\.codex\config.toml、C:\Users\你的用户名\.codex\auth.json完整的config.toml示例含注释说明实际使用时 TOML 支持#注释# 默认模型 ID按接入方支持的名称填写 model gpt-5.5 # 指向下方自定义 provider model_provider taotoken # 审批策略on-request 表示敏感操作前询问 approval_policy on-request # 沙箱只允许在工作区写入 sandbox_mode workspace-write # 推理强度可选 low / medium / high model_reasoning_effort high [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chat完整的auth.json示例{ OPENAI_API_KEY: sk-你的TaoToken密钥 }如果你同时使用多个接入点可以在config.toml里定义多个 provider 段然后通过切换model_provider的值来换model gpt-5.5 model_provider taotoken [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api wire_api chat [model_providers.backup] name Backup base_url https://taotoken.net/api wire_api chat注意base_url的写法不要写成https://taotoken.net/api/结尾多斜杠有时会导致路径拼接出双斜杠也不要在后面手动加/chat/completions这些路径由 Codex 根据wire_api自动拼接。写错路径最典型的表现是 404 或 “local proxy failed”。文件权限也顺手处理一下避免 Key 被同机其他用户读到chmod 600 ~/.codex/auth.json chmod 600 ~/.codex/config.tomlWindows 下可以在文件属性 → 安全里把权限限制为当前用户。关于模型 IDmodel字段必须和接入方实际支持的模型名一致。如果你不确定先在模型对话页面发一条消息确认模型可用再把同一个模型名填进config.toml。这一步能省掉大量“配置没错但就是报模型不存在”的排查时间。配置完成后目录结构应该是这样~/.codex/ ├── auth.json └── config.toml没有多余文件也没关系Codex 首次运行可能会生成会话缓存或日志属于正常现象。4. 验证请求跑通第一个代码任务并确认 Codex 已可用配置写完先做一次最小验证再上真实任务。最小验证的目的是确认“认证 Base URL 模型 ID”三件套都对而不是一上来就让它改代码。第一步进入一个测试项目目录mkdir -p ~/codex-demo cd ~/codex-demo git init printf def add(a, b):\n return a b\n calc.py第二步启动 Codexcodex如果认证和 Base URL 正确你会进入交互界面。先发一条“只读”指令避免它直接改文件请先不要修改任何代码。阅读当前目录说明 calc.py 里有哪些函数各自做什么。预期结果是它读出add函数并解释参数与返回值。这一步成功说明请求已经打通。第三步让它完成一个可验证的小任务——新增一个测试文件请在当前目录新增 test_calc.py使用 pytest 为 add 函数补充测试覆盖正数、负数和零。只新增测试文件不要修改 calc.py。完成后运行 pytest 并告诉我结果。如果环境里没装 pytest它会提示或尝试安装。你可以先手动装好pip install pytest然后回到 Codex 里让它继续。预期它会生成类似这样的文件from calc import add def test_add_positive(): assert add(1, 2) 3 def test_add_negative(): assert add(-1, -2) -3 def test_add_zero(): assert add(0, 0) 0并运行pytest输出3 passed。看到这个结果就说明 Codex 已经能读项目、写文件、跑命令链路完整可用。第四步人工审查改动git status git diff pytest确认无误后提交git add . git commit -m add tests for calc.add这套流程的价值在于每一步都有可观察的结果。读文件成功 → 认证通写文件成功 → 沙箱权限对跑测试成功 → 命令执行通。任何一步失败都能定位到具体环节而不是笼统地“Codex 用不了”。如果你更想先在图形界面里确认模型可用可以打开模型对话页面发一条消息确认返回正常后再回到 CLI 做上面的任务。两者用的是同一套认证信息验证一个即可。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth这一节按真实报错来对照每条都给出触发原因和修复动作。401 Unauthorized最常见的原因是auth.json里的键名写错或者 Key 本身失效。检查两点键名必须是OPENAI_API_KEY值必须是完整的 Key不要带引号外的空格。如果 Key 是从控制台复制的确认没有把前后空格带进去。修复后重开终端再跑codex。local proxy failed / connection refused这个报错通常出现在 Base URL 写错或网络不可达时。检查config.toml里的base_url是否为https://taotoken.net/api结尾有没有多余斜杠model_provider是否指向了正确的段名。如果段名写的是taotoken但model_provider写成了taotoken2就会找不到 provider表现也可能是连接失败。reading choices / 响应解析失败这类报错说明请求发出去了但返回结构不符合预期。常见原因是wire_api设错或者模型 ID 与接入方不匹配。把wire_api确认为chat并核对model字段是否和实际支持的模型名一致。如果刚改过配置记得完全退出 Codex 再重进避免读到旧配置。OAuth 登录相关报错如果你之前用账号登录过auth.json里可能残留 OAuth 字段和 API Key 混在一起导致冲突。处理方式是备份后清空auth.json只保留OPENAI_API_KEY一个键再重启 Codex。如果它仍然弹登录引导检查是否有环境变量OPENAI_API_KEY覆盖了文件配置。模型不存在 / model not foundmodel字段写了一个接入方不支持的名称。解决方式是先在模型对话里确认可用模型名再原样填进config.toml。注意大小写和连字符gpt-5.5和gpt5.5不是一回事。权限被拒 / 无法写入文件sandbox_mode设成了只读或者当前目录不在工作区内。确认sandbox_mode workspace-write并且你是在项目根目录启动的codex。如果任务需要写工作区外的路径Codex 会请求审批按提示确认即可。改了配置不生效Codex 可能在启动时读取一次配置。改完config.toml或auth.json后退出当前会话再重新运行codex。如果还不生效检查是否存在多个.codex目录比如家目录和项目目录各有一个以实际读取的那个为准。排查顺序建议固定为先看 Key401→ 再看 Base URL连接失败→ 再看模型 ID 和 wire_api解析失败→ 最后看权限和沙箱。按这个顺序走绝大多数问题能在五分钟内定位。6. 把 Codex 接进日常开发从第一个任务到稳定工作流跑通第一个任务之后真正决定效率的是工作流而不是单次提示词写得多漂亮。下面这套流程是我实际用下来比较稳的。第一动手前先建 Git 检查点git status git add . git commit -m checkpoint before codex changes这样即使 Codex 改错也能一条命令回退不用手动比对。第二任务粒度控制在一个可验证的小目标。比如“给 user 模块补三个边界测试”“把/health接口加上并跑通测试”而不是“优化整个项目”。范围越小审查成本越低成功率越高。第三坚持“先分析、后修改”的两段式。第一轮让它只输出方案请分析当前项目中 service 层是否有重复逻辑。先不要修改代码只列出重复点、建议的抽象方式、影响范围和风险。确认方案合理后第二轮再让它执行按刚才的方案重构保持对外接口不变不改变业务逻辑完成后运行测试并输出修改文件列表。第四每次修改后固定做三件事git diff看改动、跑测试、确认没有引入敏感信息。Codex 生成的代码需要人工审查这一点不会因为它能力强而改变。第五长期高频使用的话把常用配置固化下来。config.toml里的approval_policy和sandbox_mode按项目风险调整团队协作时把auth.json排除在版本控制之外用.gitignore兜底.codex/ auth.json如果你打算把 Codex 用在持续的编码任务或 Agent 场景里可以了解下 Coding Plan 这类长期方案配合 API Keys 和接入文档把认证与额度管理固定下来。需要确认模型能力时直接在模型对话里试一条比反复改配置更快。最后给一个实用技巧把“最小改动”写进提示词。修 Bug 时加一句“请使用最小改动修复不要重构无关代码”能显著减少意外改动。新手阶段稳定比激进重要先把一个任务跑通、审查、提交再逐步扩大范围。