015、config.toml 逐字段解析：模型选择、提供商配置、代理设置
从一次“模型不响应”的深夜调试说起
上周五凌晨两点，我盯着终端里反复出现的ConnectionError: [Errno 11001] getaddrinfo failed，咖啡已经凉透了。CodeX 突然罢工，所有请求都卡在“等待模型响应”阶段。我检查了 API Key、网络、甚至重启了 Docker，问题依旧。最后，是 config.toml 里一个被我忽略的proxy字段救了我——原来公司网络策略变更，代理地址变了，而 CodeX 默认不走系统代理，必须手动配置。
那次之后，我决定把 config.toml 的每个字段都吃透。今天这篇笔记，就围绕这个配置文件展开，重点讲模型选择、提供商配置和代理设置这三个最容易踩坑的地方。
config.toml 的整体结构：别被“多段式”吓到
CodeX 的配置文件采用 TOML 格式，看起来像多个[section]块。你打开默认的 config.toml，会看到类似这样的骨架：
[model] # 模型相关 [provider] # 提供商相关 [proxy] # 代理相关 [logging] # 日志级别每个块独立，但互相影响。比如[model]里选的模型名，必须和[provider]里配置的 API 端点匹配，否则 CodeX 会报“模型不存在”或“认证失败”。我见过有人把 OpenAI 的模型名填到 Azure 提供商下，结果折腾半天。
[model] 块：模型选择，别只看名字
[model] name = "gpt-4" # 这里踩过坑：name 字段必须和提供商支持的模型 ID 完全一致 # 比如 OpenAI 的 "gpt-4" 和 "gpt-4-0613" 是两个不同版本 # 别这样写：name = "gpt4"（少个横杠，直接报错）name字段是核心。CodeX 用它去匹配提供商 API 里的模型列表。如果你用 Azure，模型名可能是gpt-35-turbo（注意是 35 不是 3.5），写错一个字符就 404。
还有一个隐藏字段max_tokens，虽然不强制，但我建议显式设置：
[model] name = "gpt-4" max_tokens = 4096 # 别写太大，超过模型上限会静默截断我习惯把max_tokens设成模型支持的最大值的一半，比如 gpt-4 上限 8192，我就设 4096。这样既保证输出质量，又避免因为上下文太长导致 API 超时。
[provider] 块：提供商配置，API Key 别硬编码
[provider] type = "openai" # 可选：openai, azure, anthropic, local api_key = "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" # 别这样写：api_key = "your-api-key-here"（忘了替换，调试时一脸懵）type字段决定 CodeX 用哪个 SDK 去调用。openai和azure的 API 格式不同，选错了会报AuthenticationError。我建议用环境变量代替硬编码：
[provider] type = "openai" api_key = "${OPENAI_API_KEY}" # 从环境变量读取，安全且方便切换如果你用 Azure，还需要额外字段：
[provider] type = "azure" api_key = "${AZURE_OPENAI_KEY}" endpoint = "https://your-resource.openai.azure.com/" deployment_id = "gpt-4-deployment" # 这里踩过坑：deployment_id 不是模型名，是你在 Azure 上部署时起的名字deployment_id是 Azure 特有的，很多人把它和模型名混淆。你在 Azure Portal 里创建部署时，会要求你输入一个“部署名称”，那个才是deployment_id。模型名（比如gpt-4）是另一个字段，但 CodeX 的 Azure 提供商下，你只需要填deployment_id，它会自动关联模型。
[proxy] 块：代理设置，网络不通的救星
[proxy] enabled = true # 默认 false，很多人忘了开 # 别这样写：enabled = "true"（TOML 里布尔值不加引号，否则变成字符串）enabled设为true后，还需要配置代理地址：
[proxy] enabled = true http = "http://127.0.0.1:7890" # HTTP 代理 https = "http://127.0.0.1:7890" # HTTPS 代理，通常和 http 一样 # 这里踩过坑：如果只配 http，不配 https，CodeX 的 HTTPS 请求会直连，导致部分 API 失败我遇到过一种情况：公司网络只允许特定端口，代理地址是http://proxy.company.com:8080，但 CodeX 默认用 443 端口，结果连不上。解决方案是显式指定端口：
[proxy] enabled = true http = "http://proxy.company.com:8080" https = "http://proxy.company.com:8080" no_proxy = "localhost,127.0.0.1,.local" # 内网地址不走代理，避免冲突no_proxy字段很实用。如果你本地还跑了其他服务（比如 Ollama 或本地模型），不配这个字段，CodeX 会尝试通过代理访问localhost，导致连接被拒绝。
其他值得注意的字段
[logging] 块：调试利器
[logging] level = "debug" # 可选：debug, info, warning, error # 别这样写：level = "DEBUG"（大小写敏感，必须小写）调试时设成debug，会打印每次 API 请求的完整 URL、请求头和响应状态码。生产环境记得改回info或warning，否则日志文件会爆炸。
[cache] 块：性能优化
[cache] enabled = true type = "disk" # 可选：disk, memory path = "./cache" # 磁盘缓存路径如果你频繁调用相同 prompt，开启缓存能省 API 费用。但注意：type = "memory"只在进程生命周期内有效，重启后缓存清空。我一般用disk，并定期清理./cache目录。
个人经验：配置文件的“三要三不要”
- 要用环境变量管理敏感信息（API Key、代理密码），不要硬编码在 config.toml 里。我见过有人把 config.toml 提交到 Git 仓库，结果 API Key 泄露，被刷了几百美元。
- 要在修改配置后重启 CodeX 服务，不要以为热加载生效。CodeX 目前不支持配置热更新，改完必须
systemctl restart codex或重新启动进程。 - 要保留一份默认配置备份，不要直接覆盖。我习惯把原始 config.toml 重命名为
config.toml.default，这样改坏了能快速恢复。
最后，如果你遇到“模型不响应”或“连接超时”，先检查[proxy]块。我 80% 的网络问题都是代理配置不对。其次是[provider]里的api_key和endpoint，确保它们和你的 API 提供商一致。模型名写错反而少见，因为 CodeX 会给出明确的错误提示。
这篇笔记就到这里。下次遇到 config.toml 的问题，希望你能少走我走过的弯路。
