企业官网建设流程全解析

如果你在终端里用过 Codex，大概率被这几类报错问候过：chatgpt can't load config.toml, so this thread can't resume、the 'gpt-5.6-sol' model is not supported、codex auth token is unavailable。乍一看像三个不相关的问题，但追到根上，它们基本都指向同一个地方：~/.codex/config.toml。

这个不起眼的 TOML 文件，是 Codex CLI 的“总控制台”。模型选哪个、请求发往哪个接口、文件系统能碰多大范围、执行命令要不要逐条审批、第三方服务怎么接进来，全由它说了算。我见过不少朋友抱怨 Codex 不好用，最后发现不是工具不行，而是配置文件没写对。

这篇文章就把~/.codex/config.toml从头到尾拆一遍：每个核心字段是干什么的、为什么这么设计、怎么写才能跑通、报错了怎么排查。适合刚接触 Codex 的新手，也适合已经在用但经常被配置问题卡住的老手。看完你可以直接照着抄一份能用的配置，也能在下次被报错折磨时，快速定位到底是哪一行的锅。

1. 先搞清楚：config.toml 在 Codex 里到底是什么角色

1.1 为什么一个本地配置文件如此重要

Codex 是 OpenAI 开源的终端编程智能体，它和网页对话最根本的区别是：它直接跑在你本地，能读你的项目代码、改文件、执行命令、跑测试，再把结果反馈回来继续干活。既然它要操作本地文件系统、又要连远端模型服务，就必须有一套统一的本地裁定依据——我该用哪个模型、请求发到哪、哪些操作需要你点头、哪些动作绝对不允许。

这套裁定依据就是 config.toml。Codex 每次启动都会先读这个文件，读不到或者读坏了，最常见的结果就是开头那几种报错。它和普通应用配置文件还有一个本质区别：很多配置项直接决定安全边界，比如审批策略和沙箱级别。换句话说，config.toml 不只是“调参”，它约束的是这个智能体在你机器上的权限上限。想用好 Codex，先学会和 config.toml 打交道，这件事绕不开。

1.2 配置文件路径与 TOML 语法速览

不同平台路径不一样，别找错地方：

• Linux / macOS：~/.codex/config.toml
• Windows 原生安装：%USERPROFILE%\.codex\config.toml，实际通常是C:\Users\你的用户名\.codex\config.toml
• 如果你在 WSL 里用，路径回到 Linux 风格：~/.codex/config.toml

TOML 语法简单到可以三十秒入门，核心就三条：键 = 值、# 注释、[表名]表示子配置块。比如model = "gpt-5-codex"是给 model 赋一个字符串；[model_providers.deepseek]下面再写一堆键值对，就是定义一个叫 deepseek 的模型提供方。真正的坑不在语法本身，而在于类型敏感：字符串必须加引号，布尔值只能写 true/false，数字不要加引号。你要是把model的引号丢了，整个文件解析就会失败，Codex 可能直接拒绝启动。

注意：Windows 上编辑这个文件时，保存编码务必选 UTF-8 without BOM。带 BOM 的 UTF-8 会在文件开头藏一个不可见字符，我已经见过不止一次因为这个问题导致 TOML 解析失败的案例。

1.3 配置的读取优先级与生效验证

Codex 读取配置遵循一套常见的优先级规则：命令行启动参数最优先，其次是环境变量，最后才是 config.toml 里的默认值。所以当你用某个命令启动 Codex 时，命令行里的参数能临时覆盖配置文件的对应项，但不会改文件本身，这也解释了为什么有人改了配置文件却没生效——大概率是被环境变量或启动参数盖住了。

验证配置是否真的生效，我有一个笨但很有效的办法：改完配置后新开一个会话，让它执行一个简单的文件修改操作。如果你设的是approval_policy = "untrusted"，它要改文件之前应该停下来等你确认；如果它一声不吭直接把文件改了，说明配置压根没被读进去，或者你改的文件路径不对。先用这个办法确认“文件确实在生效”，再去折腾复杂字段，能省掉大量无效排查。

2. 核心配置项拆解：这几个字段决定 Codex 的行为边界

2.1 model 与 model_provider：为什么 model 字段一动，整个会话就废

model指定默认模型，model_provider指定这个模型由谁提供。官方默认场景下，常见配置是：

model = "gpt-5-codex" model_provider = "openai"

gpt-5-codex这类带 codex 后缀的型号，是针对 agent 编程场景优化的版本，通常在工具调用、长代码上下文的处理上表现更好。model_provider默认是openai，当你配置了多个 provider，比如 DeepSeek、本地推理服务，这里就是总开关。

很多人遇到“对话串无法继续”就是在 model 上翻车。Codex 的会话恢复机制会用当前配置里的 model 去继续旧线程，如果这个模型在对应 provider 下不存在、已下线、或者你的账号没有权限，它就会给出类似can't load config.toml, so this thread can't resume的提示。与其说这是配置文件坏了，不如说它在提醒你：去把 model 改掉。排查顺序我建议固定成三步：先确认型号真实存在，再确认当前 provider 支持这个型号，最后确认 wire_api 和 provider 对得上。

2.2 model_reasoning_effort：推理档位不是越高越好

model_reasoning_effort控制模型在推理上投入的“精力”，取值一般是minimal、low、medium、high，默认medium。效果很直观：档位越高，复杂任务处理越可靠，但响应越慢、消耗的 token 越多；档位太低，稍微绕一点的逻辑就可能出错。

我的实际体感是：简单任务，比如格式化代码、写注释、跑个小脚本，用low完全够，速度快到像开了快进；涉及架构设计、重构、跨文件排查 bug，再切回high。你完全可以在不同的配置文件里预置不同档位，配合后文提到的配置切换方式，一个项目一套档位。

2.3 approval_policy 与 sandbox_mode：安全边界的两道闸门

这是 config.toml 里我最看重的一块，它决定了 Codex 敢不敢乱动你的机器。approval_policy是审批策略，常见取值有四种：

• untrusted：默认值。低风险操作自动放行，比如读文件、查状态；写文件和执行高风险命令前会停下来问你。
• on-request：每个工具调用都要你确认，最保守，适合刚接触、还不信任它的时候。
• on-failure：倾向于尽量自动批准，但如果某一步操作失败，会停下来让你决策。
• never：完全自动批准所有操作，不弹确认。适合无人值守的自动化场景，新手别碰。

sandbox_mode是沙箱级别，决定 Codex 能碰哪些文件：read-only只能读不能改；workspace-write允许写当前工作目录，这是默认值，也是绝大多数日常开发的选择；danger-full-access不限制文件系统访问，整个机器都能改，非必要别用。

这两个字段通常是配合使用的。我在日常项目里就是approval_policy = "untrusted"加sandbox_mode = "workspace-write"，让它在项目里放手干活，但做危险动作前先问我一声。这个组合能覆盖绝大多数开发场景，既有生产力又有安全兜底。

2.4 输出与上下文相关字段：max_output_tokens、temperature、include_previous_errors

max_output_tokens限制单次回复的最大 token 数。代码生成任务很容易一口气输出大量内容，如果你经常发现回复写到一半被截断，可以把它调大，比如从默认的 8192 调到 16384。但注意别超过模型的上下文窗口，否则会直接报错。

temperature控制随机性，Codex 默认是 0.0，也就是尽量确定性输出。写代码这个场景我强烈建议保持默认。不要为了提高“创意”把它调高，否则你得到的可能是逻辑清奇的抽象 bug，调试成本远高于那一点随机性带来的“惊喜”。

include_previous_errors设为 true 时，Codex 会把上一轮执行时的报错信息带进下一轮，让它自己看着错误继续修。这个默认开启，基本不用动。但如果你想让每次对话从干净状态开始，避免历史错误干扰判断，也可以关掉它。

2.5 model_providers 区块：把第三方服务接进 Codex 的关键

这才是 config.toml 最有价值的部分。Codex 默认只连 OpenAI 官方，但通过[model_providers.xxx]可以接入任何兼容 OpenAI API 协议的服务。一个典型配置长这样：

[model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

每个字段的含义：

• name：显示名，随便起，只影响日志和提示里的展示。
• base_url：API 入口地址，这是 Codex 发请求的目标。
• env_key：指定从哪个环境变量读取 API Key。注意填的是“变量名”而不是“值”。
• wire_api：接口协议类型，responses或chat。OpenAI 官方同时支持两套，但大量第三方平台只实现了/chat/completions，那就必须写chat，写错会直接导致请求失败。

配好 provider 后，再把model_provider和model指过去，就能让 Codex 用上第三方模型。这是很多开发者切换模型、节省成本的核心手段，后面的实操部分我会给一份完整样例。

3. 实操：从零写一份能直接运行的 config.toml

3.1 安装认证与前置检查：让 codex 命令先跑起来

写配置之前，先保证 Codex 本体装好、能启动。安装方式常见有三类：macOS 用 Homebrew，Node 环境用 npm 全局安装，或者直接下载官方编译好的二进制。Windows 上我建议优先用 npm 或官方安装包，少折腾编译链。

认证有两种方式：跑codex login走浏览器 OAuth 登录，登录态会存在~/.codex/auth.json；或者设置环境变量OPENAI_API_KEY，Codex 会优先读环境变量里的 Key。装完、认证完，先跑一下codex --version确认版本正常。如果你准备用第三方 provider，还要在启动 Codex 的终端里先设置好对应的环境变量：

export DEEPSEEK_API_KEY=你的key

这里有个很隐蔽的坑：很多人把 Key 写进了.env文件，但换个终端启动 codex 时.env并没有被加载，于是报 auth token unavailable。排查 auth 类问题，第一件事永远是确认“当前这个 shell”里有没有对应的环境变量，而不是怀疑配置文件写错。

3.2 官方 OpenAI 场景：一份开箱即用的完整配置

如果你用官方模型，其实[model_providers.openai]是内置的，不写也能跑。但我还是建议把完整配置摆出来，方便你理解结构：

model = "gpt-5-codex" model_provider = "openai" approval_policy = "untrusted" sandbox_mode = "workspace-write" model_reasoning_effort = "medium" max_output_tokens = 16384 temperature = 0.0 include_previous_errors = true [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com/v1" env_key = "OPENAI_API_KEY" wire_api = "responses"

这段配置的意思是：用 gpt-5-codex 干活，走官方接口，项目目录内的文件可以改，但改文件前会征求你同意，单次回复最多 16384 token，完全确定性输出。如果你不需要自定义 provider，把下面[model_providers.openai]这段整体删掉也完全没问题，内置默认值就是它。

3.3 接入 DeepSeek：改几行就能用上第三方模型

接入 DeepSeek 是很多人的真实需求，这里给一份能直接抄的配置。先在 DeepSeek 平台把 API Key 申请好，然后编辑~/.codex/config.toml：

model = "deepseek-chat" model_provider = "deepseek" approval_policy = "untrusted" sandbox_mode = "workspace-write" [model_providers.deepseek] name = "DeepSeek" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"

启动前不要忘记做这一步：

export DEEPSEEK_API_KEY=你的key codex

几个要点：base_url写成https://api.deepseek.com/v1，Codex 会自动在后面拼/chat/completions。有些平台提供的地址不带/v1也能用，但按 OpenAI 兼容规范写最保险。不要对 DeepSeek 用wire_api = "responses"，它兼容的是 chat completions 协议，写错的话报错通常是不认识的端点或 model not supported。model字段也要和 provider 的实际型号对上，比如deepseek-chat、deepseek-reasoner，别拿 OpenAI 的型号名去 DeepSeek 的 provider 下用。

如果你手头还有别的兼容服务，比如本地部署的推理框架，套路完全一样：新增一个[model_providers.xxx]区块，改model_provider指向它，就是一套通用玩法。

3.4 Windows 用户特别提醒：路径、编码、环境变量三个坑

Windows 下配置 Codex 有自己的一套脾气。第一是路径，很多人在 PowerShell 里习惯了~，但原生安装的 Codex 读的是%USERPROFILE%\.codex\config.toml，也就是C:\Users\你的用户名\.codex目录。找不到文件就先看这个目录有没有被创建。

第二是编码问题。前面也提过，Windows 记事本保存容易带 BOM 头，TOML 解析器对 BOM 很敏感，轻则某个键读不出来，重则整体解析失败。我建议用 VS Code 或 Notepad++ 保存，编码选择 UTF-8 without BOM。

第三是环境变量。Windows 上通过“系统属性”设置的环境变量，新开终端才能生效，已经打开的终端不会自动读到新值。所以我习惯在 PowerShell 里显式设置：

$env:DEEPSEEK_API_KEY = "你的key"

设置完再启动 Codex，能避开大部分 auth 类的玄学报错。如果你之前遇到过“安装未完成”或者“命令找不到”一类的问题，大概率是安装时权限不足或者 PATH 没刷新，重启终端、以管理员身份重新安装基本都能解决。

4. 常见报错速查：config.toml 相关的 5 类高频问题

4.1 会话无法加载或恢复：先查 model 字段

报错示例：chatgpt can't load config.toml, so this thread can't resume，中文版通常是“无法加载 config.toml，因此此对话串无法继续”。

这个提示的迷惑性很强，因为它直译过来是“配置文件加载失败”，但绝大多数情况和文件语法无关，而是你配置的 model 已经不可用，导致 Codex 无法用当前配置重新拉起旧线程。修复路径：打开 config.toml 看model写的是什么；确认这个型号在你选的 provider 下真实存在并且你有权限；不确定时，先注释掉model和model_provider两行，让 Codex 用内置默认值恢复。

我见过最离谱的一次，是用户从网上抄了一段配置，模型名是别人内测环境的 ID，正常渠道根本调不到，结果每次恢复会话都卡死。模型名这种东西，一定要以官方文档或平台控制台为准，别迷信网上贴的所谓“隐藏模型”。

4.2 model is not supported：型号与协议不匹配

报错示例：the 'gpt-5.6-sol' model is not supported when using codex with a ...

这类报错一般是三选一：型号拼错、provider 不支持该型号、或者 wire_api 设置和平台实际能力不匹配。比如某些平台只做 chat completions，你把 wire_api 写成 responses，即使型号存在也可能被直接拒绝。

处理思路很明确：去 provider 文档确认支持列表，核对model和wire_api。如果是第三方平台，优先用它们文档里明确写了“OpenAI 兼容”的型号和地址。大多数情况下，问题出在“模型名看着眼熟就直接抄进去”，而不是平台服务本身有毛病。

4.3 auth token is unavailable：认证信息到底去哪了

报错示例：codex auth token is unavailable。

原因很直白：Codex 在启动时既没找到登录态，也没找到环境变量里的 Key。逐项排查：看~/.codex/auth.json是否存在；在当前 shell 里执行echo $OPENAI_API_KEY看环境变量是否真的导入；第三方 provider 则确认 config.toml 里是否正确写了env_key，并且当前 shell 有这个环境变量。

还有一个高频细节：env_key填的是变量名，不是 Key 本身。写反的人不少，写成env_key = "sk-xxxxxxxx"，Codex 会把这串 Key 当变量名去找，自然永远找不到。这个字段的正确写法是env_key = "DEEPSEEK_API_KEY"，真正的 Key 放在环境变量里。

4.4 请求 /responses 端点失败：网络链路怎么查

报错示例：failed while handling codex endpoint /responses，常见于请求超时、连接被重置、接口 404 等。

这类问题和 config.toml 的关系主要是两点：base_url写没写对，以及wire_api和 base_url 指向的平台是否兼容。排查顺序我建议这样走：

1. 先确认网络通不通，用 curl 直接打接口地址。
2. 确认 base_url 拼写，别多了斜杠，别少了 v1。
3. 确认 wire_api 和平台实际协议一致。
4. 如果身处企业网络或受限网络，请求被防火墙拦住了，那就走正规渠道找网络管理员协助，这属于网络环境问题，不是改配置文件能绕过去的事。

4.5 TOML 语法错误：一个引号毁掉整个文件

报错示例：解析失败、Failed to parse config、启动即退出。

常见原因：字符串忘了加引号、复制配置时引入了中文全角引号、键名多了空格、数组或表格多写了逗号、文件带 BOM。这类问题最好别靠肉眼找，用工具校验最快。Python 3.11 以上直接跑：

import tomllib with open("config.toml", "rb") as f: config = tomllib.load(f) print(config)

能正常打印出字典，说明语法没问题；报错的话，行号会直接告诉你错在哪一行。把这 5 类问题整理成速查表，方便你以后直接对照定位：

5. 用了一段时间后，我最想提醒你的三件事

第一，配置文件一定要纳入版本管理。把~/.codex/下的config.toml和personalization.md放进 dotfiles 仓库，换机器、重装系统之后一条同步命令就能恢复整套配置。Codex 本身会读~/.codex/personalization.md作为全局指令，很多团队把代码规范、commit 风格、目录约定写在那里，config.toml 只负责技术参数，两者分工非常清晰。

第二，用CODEX_HOME环境变量做多套配置切换。Codex 支持通过CODEX_HOME指定配置目录，我日常会准备两份：一套官方模型高速档位，一套第三方 provider 省钱档位。要切换的时候改一下环境变量即可，不用反复改文件内容，也不用担心改错把主力配置弄坏。

第三，遇到诡异问题先重置再看。别在一份已经读不出来的配置上死磕。备份当前文件，删掉或改名，重新启动 Codex，它会生成一份默认配置。把默认配置和出问题的配置逐行对比，大多数“玄学报错”的答案就在差异里。回顾下来，config.toml 就是典型的“配置一时爽，排查火葬场”文件，但只要吃透 model、model_provider、wire_api、approval_policy 这几个核心字段，剩下的一切都会顺理成章，希望这份解析能帮你少走我踩过的那些坑。