手动配置 - Codex

本文介绍如何手动修改 Codex 的配置文件，完成中转站接入。

适合场景：自动配置不可用、需要自己排查配置、或者想把模型与接口参数明确写进本地配置文件。

---

你需要准备的信息

在开始之前，请先从中转站后台准备以下内容：

信息	说明	示例
API Key	你的访问凭证	sk-xxxxxxxxxxxxxxxx
Base URL	中转站接口地址	https://xxx.example.com/v1

Codex 官方文档明确使用 ~/.codex/config.toml 作为全局配置文件位置。Windows 路径通常可以按同样规则对应到 %USERPROFILE%\.codex\config.toml，这里属于基于官方路径规则的推断。

---

第一步：找到 config.toml

常见路径：

• macOS / Linux： ~/.codex/config.toml
• Windows（推断路径）： %USERPROFILE%\.codex\config.toml

如果 ~/.codex 或 .codex 目录还不存在，可以先启动一次 Codex，或者手动创建该目录和文件。

---

第二步：写入中转站配置

打开 config.toml 后，可以按下面的格式填写：

model = "gpt-5.4"
model_reasoning_effort = "medium"

[model_providers.ktoken]
name = "KToken"
base_url = "https://your-base-url.example.com/v1"
env_key = "OPENAI_API_KEY"

[profiles.ktoken]
model_provider = "ktoken"
model = "gpt-5.4"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

然后把你的 API Key 写入环境变量：

• macOS / Linux：

export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

• Windows PowerShell：

$env:OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx"

如果你希望长期生效，请把环境变量写进自己的 shell 配置文件，或者用系统环境变量方式保存。

---

第三步：启动并验证

保存配置后，重新打开终端，执行：

codex

进入 Codex 后，发一条简单测试消息，例如：

请回复“配置已生效”。

如果能正常收到回复，说明配置已经生效。

---

排错清单

启动后仍然走默认配置？
→ 检查 config.toml 是否写在正确位置，尤其注意是不是写成了 .json

提示鉴权失败 / 401？
→ 优先检查 API Key 是否正确，以及环境变量是否在当前终端会话中生效

提示连接失败？
→ 检查 base_url 是否可访问，必要时切换到其他中转线路

改完配置没反应？
→ 完全关闭当前终端，再重新打开 Codex，确保新配置被重新读取