★ FEATURED ARTICLE 1. 为什么要在 PowerShell 里折腾 Codex 的 config.toml 和 AGENTS.md如果你在 Windows 上用 Codex 做日常编码大概率会遇到一个尴尬局面桌面版设置页点得挺顺手但一旦换到命令行、换到 CI、换到另一台机器所有偏好都得重新点一遍。更麻烦的是团队里每个人对代理能改哪些文件、能跑哪些命令的理解都不一样最后代码 review 时才发现有人让代理直接动了生产配置。Codex 的配置体系其实是分层的理解这三层后面就不会乱第一层是应用级权限也就是设置页里那几个总开关决定代理这台机器上能碰什么。第二层是 config.toml它决定每个新会话的默认行为可以放在用户级目录也可以放在项目根目录做项目级覆盖。第三层是 AGENTS.md它是仓库级的行为说明书告诉代理这个项目里有哪些约定、哪些目录不能碰、提交信息怎么写。MCP 则是第四块拼图。它把外部能力数据库、GitHub、文档检索以工具的形式挂给代理而 MCP 服务器的启动、环境变量、超时全都要在 config.toml 里声明。PowerShell 环境下这一步尤其容易翻车因为路径分隔符、环境变量语法、引号转义和 bash 都不一样。这篇就按先讲清楚职责划分再给可复制配置最后逐步验证的顺序来。目标很明确让你在 PowerShell 里搭出一套可维护、可提交到仓库、换台机器也能复现的本地 AI 编码工作流。适合已经在用 Codex 但配置散落各处的人也适合刚准备把 MCP 接进来的开发者。我试过把用户级配置和项目级配置混着写结果代理在一个仓库里能跑数据库查询换到另一个仓库还在跑排查了半天才发现是用户级 config.toml 没清干净。所以下面会反复强调哪一层该放什么。2. 前置准备TaoToken 接入与 Codex 配置目录定位在动 config.toml 之前先把模型接入这条链路打通。Codex 本身是客户端它需要一个兼容的 API 端点来发请求。TaoToken 提供的就是这个端点官网在 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。你需要先拿到一个 API Key。登录后进控制台在 API Keys 页面创建一个复制出来。这个 Key 后面会写进 config.toml 的模型提供方配置里或者通过环境变量注入。建议用环境变量的方式别把 Key 硬编码进要提交到 Git 的文件。Codex 在 Windows 上的配置目录通常在用户主目录下的.codex文件夹。PowerShell 里可以这样确认# 查看 Codex 配置目录是否存在 Test-Path $env:USERPROFILE\.codex # 如果不存在就创建 New-Item -ItemType Directory -Force -Path $env:USERPROFILE\.codex # 列出目录内容确认有没有 config.toml Get-ChildItem $env:USERPROFILE\.codex -Force项目级配置则放在仓库根目录的.codex文件夹里或者直接用仓库根目录的AGENTS.md。这里有个容易混淆的点config.toml管的是怎么连、连哪个模型、MCP 怎么起AGENTS.md管的是在这个仓库里该怎么干活。前者是机器配置后者是行为约定。环境变量注入 Key 的推荐做法在 PowerShell 里是写进用户级环境变量而不是每次开终端都 set 一遍# 设置用户级环境变量重启终端后生效 [Environment]::SetEnvironmentVariable(TAOTOKEN_API_KEY, 你的Key, User) # 当前会话临时生效 $env:TAOTOKEN_API_KEY 你的Key # 验证是否读到 $env:TAOTOKEN_API_KEY如果你用的是 Claude Code 那套体系配置路径和字段名会不一样但思路一致Base URL 指向 https://taotoken.net/api Key 走环境变量Model ID 按你实际要用的模型填。这三件套Base URL、Key、Model ID在任何接入场景里都是必须对齐的缺一个就会报 401 或者模型找不到。MCP 服务器的准备也要在这一步想清楚。你要接的是数据库、GitHub 还是本地文件检索每个 MCP 服务器都有自己的启动命令和参数PowerShell 下启动命令通常是npx、node或者一个 exe 路径。先把这些命令在 PowerShell 里单独跑通再写进 config.toml否则配置报错时你分不清是 Codex 的问题还是 MCP 本身起不来。3. 可复制配置config.toml 与 AGENTS.md 的职责划分与完整片段这一节是核心直接给能抄的片段。先明确职责边界再上代码。config.toml负责四件事模型提供方Base URL、Key 引用、Model ID、沙箱与批准策略、MCP 服务器声明、以及一些运行时参数超时、日志级别。它不负责业务约定。AGENTS.md负责项目结构说明、编码规范、提交信息格式、哪些目录只读、测试怎么跑、代理在什么情况下必须先问人。它是纯文本代理会读它来调整行为。先看用户级config.toml路径是$env:USERPROFILE\.codex\config.toml# 用户级 Codex 配置所有项目共享的默认行为 # 路径C:\Users\你的用户名\.codex\config.toml # 模型提供方配置 [model_providers.taotoken] name TaoToken base_url https://taotoken.net/api env_key TAOTOKEN_API_KEY # 默认使用的模型 model gpt-5-codex model_provider taotoken # 沙箱与批准策略 # workspace-write 表示工作空间内可写空间外需批准 sandbox_mode workspace-write approval_policy on-request # 运行时参数 [model_providers.taotoken.options] timeout_ms 120000 max_retries 3 # MCP 服务器声明本地文档检索示例 [mcp_servers.local_docs] command npx args [-y, modelcontextprotocol/server-filesystem, C:\\projects\\docs] env { NODE_NO_WARNINGS 1 } # MCP 服务器声明GitHub 示例需要先设置 GITHUB_TOKEN 环境变量 [mcp_servers.github] command npx args [-y, modelcontextprotocol/server-github] env { GITHUB_PERSONAL_ACCESS_TOKEN ${GITHUB_TOKEN} }几个 PowerShell 下必须注意的点。路径里的反斜杠在 TOML 字符串里要写成双反斜杠\\或者用正斜杠/TOML 两种都认。环境变量引用用${VAR}语法Codex 会在启动 MCP 时展开。npx在 PowerShell 里能直接调用前提是 Node.js 装好了并且在 PATH 里。再看项目级config.toml放在仓库根目录.codex\config.toml它只覆盖需要改的字段# 项目级覆盖只写和用户级不同的部分 # 路径仓库根\.codex\config.toml # 这个项目需要更严格的批准策略 approval_policy untrusted # 项目专属 MCP只在这个仓库里挂载 [mcp_servers.project_db] command node args [C:\\tools\\mcp-db\\server.js] env { DB_URL ${PROJECT_DB_URL} }然后是AGENTS.md放在仓库根目录。它不是配置文件是给代理看的说明书# AGENTS.md ## 项目结构 - src/ 源码目录代理可以自由读写 - config/ 配置文件代理只能读改动必须先问 - migrations/ 数据库迁移代理禁止自动生成必须人工确认 ## 编码规范 - 使用 2 空格缩进 - 提交信息格式type(scope): descriptiontype 限 feat/fix/docs/refactor/test - 所有新增函数必须有 JSDoc 注释 ## 测试 - 运行测试npm test - 代理在提交前必须跑一次测试失败则不得提交 ## 禁止事项 - 不得修改 .env 和任何含密钥的文件 - 不得执行 git push --force - 不得直接操作生产数据库职责划分一句话总结config.toml决定代理能用什么工具、在什么权限下跑AGENTS.md决定代理在这个项目里该怎么用这些工具。两者不重叠也不该互相替代。把编码规范写进 config.toml 是无效的把 MCP 启动命令写进 AGENTS.md 也不会被执行。如果你用的是 Cline MCP 或者 Codex 的 auth.json 体系字段名会不同但三件套不变Base URL 填 https://taotoken.net/api Key 走环境变量或 auth 文件Model ID 按实际模型填。CC Switch 这类切换工具也是同样的对齐逻辑。4. 逐步验证从 MCP 启动到一次完整请求配置写完不代表能用必须一步步验证。顺序是先验证模型接入再验证 MCP 单独能起最后验证 Codex 能同时用上两者。第一步验证 API 端点连通。在 PowerShell 里直接发一个请求确认 Key 和 Base URL 没问题# 验证 TaoToken API 连通性 $headers { Authorization Bearer $env:TAOTOKEN_API_KEY Content-Type application/json } $body { model gpt-5-codex messages ({ role user; content 回复 ok 两个字母即可 }) } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri https://taotoken.net/api/v1/chat/completions -Method Post -Headers $headers -Body $body如果返回里有正常的 choices 结构说明接入层通了。如果报 401检查 Key 有没有正确读到如果报模型不存在检查 Model ID 拼写。第二步单独验证 MCP 服务器能启动。别急着让 Codex 去起先在 PowerShell 里手动跑一遍# 手动启动 filesystem MCP确认能跑起来 npx -y modelcontextprotocol/server-filesystem C:\projects\docs # 如果卡住不动是正常的它是个常驻进程CtrlC 退出 # 如果报错先解决 Node.js 或包安装问题这一步能过滤掉大部分配置写对了但 MCP 起不来的问题。常见的是 npx 首次下载包超时或者路径不存在。第三步启动 Codex 并确认它读到了配置。在项目根目录打开 PowerShell# 进入项目目录 cd C:\projects\my-app # 启动 Codex观察启动日志里有没有加载 config.toml 和 MCP codex # 在 Codex 会话里问它当前有哪些 MCP 工具可用 # 输入列出你当前可用的 MCP 工具如果 Codex 能列出local_docs和github的工具说明 MCP 挂载成功。如果只列出一部分回去检查对应 MCP 的 env 变量有没有设置。第四步做一次端到端验证让 Codex 读 AGENTS.md 里的约定然后用 MCP 工具完成一个小任务。比如让它读取 docs 目录下的 README总结项目结构并按 AGENTS.md 的提交格式给一个提交信息建议。观察它是否遵守了 AGENTS.md 里的缩进和提交格式约定。成功的结果应该是Codex 调用了 filesystem MCP 读到文件输出里体现了 AGENTS.md 的规范且没有越界去碰config/目录。如果它试图写config/说明 AGENTS.md 的约束没生效或者沙箱模式设得太松。5. 常见报错排查401、local proxy failed、reading choices、OAuth配置落地阶段最容易撞上的就这几类报错逐个拆。401 Unauthorized。最常见的原因是 Key 没读到。PowerShell 里环境变量分用户级和进程级[Environment]::SetEnvironmentVariable设的是用户级但已经开着的终端不会自动刷新。解决方法是关掉终端重开或者临时$env:TAOTOKEN_API_KEY ...覆盖。另一个原因是 config.toml 里env_key写错了名字比如写成TAOTOKEN_KEY但实际设的是TAOTOKEN_API_KEY。对照检查这两个字符串是否完全一致。local proxy failed / connection refused。这个通常出现在 MCP 服务器启动失败时。Codex 尝试拉起 MCP 进程但进程没起来或者端口被占。排查顺序先在 PowerShell 里手动跑 MCP 的 command 和 args看能不能起能起的话检查 config.toml 里的路径转义Windows 路径必须双反斜杠或正斜杠再检查env里的变量有没有引用到不存在的值。如果 MCP 依赖某个端口确认端口没被别的进程占用# 查看端口占用 Get-NetTCPConnection -LocalPort 3000 -ErrorAction SilentlyContinuereading choices / unexpected response shape。这个报错说明请求发出去了但返回的 JSON 结构不是 Codex 期望的。常见于 Base URL 写错比如漏了/v1或者多写了路径。TaoToken 的 API 根是 https://taotoken.net/api 具体端点路径按文档来。另一个原因是 Model ID 填了一个端点不支持的模型返回了错误结构。先用第 4 节的 Invoke-RestMethod 单独验证一次确认返回结构正常。OAuth 相关报错。如果你接的 MCP 服务器需要 OAuth比如某些 GitHub 或云服务集成报错通常是 token 过期或 scope 不足。这类 MCP 一般要求先跑一次授权流程把 token 存到本地再在 config.toml 的 env 里引用。PowerShell 下注意 token 文件路径也要用双反斜杠。如果反复授权失败先确认系统时间准确OAuth 对时间偏差很敏感。MCP 工具列出来了但调用报错。这通常是 MCP 服务器本身的问题不是 Codex 的问题。回到手动启动那一步在 PowerShell 里直接给 MCP 发一个测试请求看它自己能不能正常工作。很多 MCP 服务器的日志会输出到 stderrCodex 默认可能不显示可以在 config.toml 里临时调高日志级别。排查的通用原则把链路拆成API 接入和MCP 启动两段分别用 PowerShell 原生命令验证确认各自没问题后再让 Codex 串起来。这样报错时你能立刻定位是哪一段的问题而不是对着一个笼统的失败发呆。6. 把配置沉淀成可维护的工作流配置能跑通只是起点真正省时间的是让它可维护。几个实践建议。用户级 config.toml 只放跨项目通用的东西模型提供方、默认沙箱策略、常用的 MCP比如文档检索。项目级 config.toml 只放这个项目特有的专属 MCP、更严格的批准策略。AGENTS.md 跟着仓库走进 Git团队共享。这样新人 clone 下来配好环境变量就能直接开工不用问你的 Codex 怎么设的。MCP 的密钥一律走环境变量不写进任何进 Git 的文件。config.toml 里用${VAR}引用实际值放在用户级环境变量或者本地的.env记得加进.gitignore。这样配置可以放心提交密钥不会泄露。定期清理用户级 config.toml。项目做完了对应的 MCP 如果不再用就从用户级配置里删掉避免它在别的仓库里被意外挂载。我踩过的坑就是用户级挂了一个数据库 MCP换项目后代理还在尝试连那个库日志里一堆连接失败。如果你需要长期跑编码任务或者 Agent 类的自动化可以考虑 Coding Plan 这类方案把调用配额和并发管理起来地址在 https://taotoken.net/api 对应的控制台里能找到入口。日常验证模型行为、试新 prompt用模型对话页面就够了地址是 https://taotoken.net/api 同域下的对话入口。接入文档在 https://taotoken.net/api 的文档区API Keys 管理在控制台的 API Keys 页面。最后一步把验证流程脚本化。在仓库里放一个scripts/verify-codex.ps1内容就是第 4 节那几步的 PowerShell 版本新人拉下来跑一遍就知道环境对不对# scripts/verify-codex.ps1 Write-Host 检查环境变量... if (-not $env:TAOTOKEN_API_KEY) { Write-Error TAOTOKEN_API_KEY 未设置; exit 1 } Write-Host 检查 config.toml... if (-not (Test-Path $env:USERPROFILE\.codex\config.toml)) { Write-Error 用户级 config.toml 不存在; exit 1 } Write-Host 检查 AGENTS.md... if (-not (Test-Path .\AGENTS.md)) { Write-Warning 当前仓库没有 AGENTS.md } Write-Host 验证 API 连通... $headers { Authorization Bearer $env:TAOTOKEN_API_KEY } try { Invoke-RestMethod -Uri https://taotoken.net/api/v1/models -Headers $headers | Out-Null Write-Host API 连通正常 } catch { Write-Error API 连通失败$_ exit 1 }这套东西跑顺之后你在任何一台 Windows 机器上clone 仓库、设两个环境变量、跑一次验证脚本就能得到一台行为一致、边界清晰、MCP 能力就位的 Codex 工作环境。剩下的时间就可以真正花在写代码上而不是反复调配置。
阅读完成 · 觉得有帮助？
