Codex 第三方 API 配置教程：config.toml、auth.json 和聊天记录恢复

最近折腾 Codex 的时候，最常遇到两个问题：

  1. 第三方 API 的 base_url 和 key 到底写哪里？
  2. 切换 provider 之后，之前的聊天记录怎么突然没了？

这篇就直接把几种写法和恢复方法放出来。想快速用的，直接看第三部分复制配置。

1. Codex 配置文件在哪里

Windows 默认路径：

C:\Users\你的用户名\.codex

macOS / Linux 默认路径：

~/.codex

常见文件就这几个：

config.toml              # 主配置，模型、provider、base_url 都在这里
auth.json                # 登录信息、API Key
sessions/                # 聊天记录 jsonl 文件
state_5.sqlite           # 聊天列表、线程信息
sqlite/codex-dev.db      # Codex Desktop 本地线程目录

注意一下，Codex 用的是 config.toml，不是 config.yml。

2. config.toml 是什么

config.toml 可以理解成 Codex 的启动配置。

最简单的结构是这样：

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

[model_providers.openai]
name = "OpenAI"
base_url = "https://api.openai.com/v1"
wire_api = "responses"

重点看两个字段：

model_provider：当前使用哪个提供商。

[model_providers.xxx]：这个提供商的具体配置。

比如：

model_provider = "custom"

[model_providers.custom]
base_url = "https://api.xxx.com/v1"

这里的 custom 就是 provider 名字。后面聊天记录恢复也主要和这个字段有关。

3. 第三方 API Key 的几种写法

下面几种都可以写。日常最省事的是写法 1。

写法 1：base_url 和 key 全部写到 config.toml

这个最直观，配置都在一个文件里。

model = "your-model-name"
model_provider = "custom"

[model_providers.custom]
name = "Custom API"
base_url = "https://api.example.com/v1"
wire_api = "responses"
experimental_bearer_token = "sk-REDACTED"

参数说明：

model：你要用的模型名。

model_provider：当前 provider，比如这里是 custom。

base_url：第三方 API 地址。

experimental_bearer_token：第三方 API Key。

这种写法简单，但 key 是明文写在配置文件里的。如果是自己电脑用，没问题；如果配置文件会同步到网盘或仓库，就要注意。

写法 2：config.toml 写 base_url，auth.json 写 key

这种写法适合想把地址和 key 分开放的人。

config.toml：

model = "your-model-name"
model_provider = "custom"

[model_providers.custom]
name = "Custom API"
base_url = "https://api.example.com/v1"
wire_api = "responses"
requires_openai_auth = true

auth.json：

{
  "OPENAI_API_KEY": "sk-REDACTED"
}

这类写法的逻辑是：config.toml 负责告诉 Codex 请求哪个地址，auth.json 负责提供 Bearer Token。

如果你的 Codex 版本或上游代理不吃这个写法，就换成写法 1，最直接。

写法 3：config.toml 写 base_url，key 走环境变量

这个是更干净的写法。配置文件里不出现真实 key。

model = "your-model-name"
model_provider = "custom"

[model_providers.custom]
name = "Custom API"
base_url = "https://api.example.com/v1"
wire_api = "responses"
env_key = "MY_CODEX_API_KEY"

然后在系统环境变量里放：

MY_CODEX_API_KEY=sk-REDACTED

这种方式适合团队、脚本、服务器环境。个人本地使用的话，写法 1 更省事。

写法 4：动态获取 token

如果你的 token 是临时的，比如公司 SSO、代理服务动态签发，可以用命令动态取 token。

model = "your-model-name"
model_provider = "custom"

[model_providers.custom]
name = "Custom API"
base_url = "https://api.example.com/v1"
wire_api = "responses"

[model_providers.custom.auth]
command = "node"
args = ["get-token.js"]
refresh_interval_ms = 300000

这个写法普通用户基本用不到，但做内部代理时比较方便。

怎么选

只想最快跑起来：写法 1
想把 key 单独放：写法 2
不想配置里出现 key：写法 3
token 会过期或动态签发：写法 4

另外提醒一下：Codex 原生更偏 Responses API。如果第三方只支持 Chat Completions，可能需要一个代理层做协议转换。

4. auth.json 怎么看

auth.json 主要放登录信息。

如果是 API Key 方式，可能长这样：

{
  "OPENAI_API_KEY": "sk-REDACTED"
}

如果是官方账号登录，可能长这样：

{
  "auth_mode": "chatgpt",
  "last_refresh": "2026-07-08T10:37:54Z",
  "tokens": {
    "access_token": "REDACTED",
    "id_token": "REDACTED",
    "refresh_token": "REDACTED",
    "account_id": "acct_REDACTED"
  }
}

官方登录时，最好让 Codex 自己生成，不要手写 token：

codex login

API Key 登录也可以让 Codex 自己写：

$env:OPENAI_API_KEY | codex login --with-api-key

简单理解就是：

config.toml：管请求地址、模型、provider
auth.json：管登录凭据、API Key

5. 为什么切换 provider 后聊天记录没了

这个问题的核心不是聊天记录真的被删了，而是 Codex 会按 model_provider 分桶。

比如你之前用的是：

model_provider = "openai"

后来切成：

model_provider = "custom"

Codex 界面可能只看当前 custom 这个桶，之前 openai 桶里的记录就不显示了。

本地大概会涉及这些地方：

sessions/**/*.jsonl                  # session_meta 里有 model_provider
state_5.sqlite -> threads            # threads.model_provider
sqlite/codex-dev.db -> local_thread_catalog

所以恢复的思路也很简单：

把旧 provider 名字统一改成当前 provider 名字

例如把 openai、deepseek、openrouter 都统一成 custom，聊天列表就能回到同一个桶里。

6. 聊天记录怎么恢复

最简单的方式是让 Codex 自己帮你恢复。把下面这段 prompt 复制给 Codex，用之前改一下目标 provider。

请帮我恢复 Codex 本地聊天记录。

我的目标：
- 把旧 provider 的聊天记录恢复到当前 provider 下显示。
- 当前目标 provider：custom
- 旧 provider 列表：openai, deepseek, openrouter, rightcode

要求：
1. 默认 Codex 目录是 ~/.codex，Windows 下是 %USERPROFILE%\.codex。
2. 先备份整个 .codex 目录，备份目录带时间戳。
3. 不要输出 auth.json 里的真实 token、API Key、refresh_token、access_token。
4. 统计 state_*.sqlite 里 threads.model_provider 的分布。
5. 统计 sqlite/codex-dev.db 里 local_thread_catalog.model_provider 的分布。
6. 找到 sessions/**/*.jsonl 里 session_meta.payload.model_provider 的分布。
7. 把旧 provider 列表里的 provider 更新为目标 provider：
   - state_*.sqlite 的 threads.model_provider
   - sqlite/codex-dev.db 的 local_thread_catalog.model_provider
   - sessions/**/*.jsonl 的 session_meta.payload.model_provider
8. 修改 JSONL 时必须逐行解析 JSON，只修改 session_meta 行，不要全文字符串替换。
9. 修改完成后生成 restore-report.md，写清楚备份位置、修改了哪些文件、改了多少条记录、如何回滚。
10. 不要删除任何原始文件。

如果你想手动操作，核心 SQL 类似这样：

UPDATE threads
SET model_provider = 'custom'
WHERE model_provider IN ('openai', 'deepseek', 'openrouter');

但我不建议新手直接手动改数据库。让 Codex 写脚本处理 JSONL 和 SQLite，会更稳一点。

7. 推荐工具：codex-switch

如果只是偶尔改一次 provider，手改配置就够了。

但如果你经常在这些配置之间切换：

官方订阅
第三方 API
本地代理
备用线路

那就很适合用工具统一管理。

项目地址：

https://github.com/gstranded/codex-switch

这个工具主要解决几个问题：

  1. 可以维护多个 Codex 配置。
  2. 官方订阅和自定义 API 可以一键切换。
  3. 自动写入 config.toml / auth.json。
  4. 切换 provider 后，聊天记录不会因为分桶问题消失。
  5. 支持把多个第三方 provider 放到一个界面里管理。

也就是说，以后不用每次手动打开 .codex 目录改配置，也不用每次切换后再想办法恢复聊天记录。

8. 最后总结

Codex 接第三方 API，主要就是三件事：

1. config.toml 里配置 model_provider、model、base_url
2. key 可以写在 config.toml，也可以写 auth.json，也可以走环境变量
3. 聊天记录跟 model_provider 绑定，切 provider 后不显示，可以通过统一 provider 桶恢复

如果你只是想最快跑起来，用写法 1。

如果你要长期维护多个 provider，用 codex-switch 会省很多事。

# json # 编辑器 # 人工智能
Logo
AI Agent技术社区

Agent 垂直技术社区，欢迎活跃、内容共建。

更多推荐

cover

从「能说」到「能做」：一份理清 AI Agent 的学习笔记

avatar AI Agent技术社区
cover

DeepSeek Harness 深度解析：一切皆插件的开源 AI Agent 框架如何运行？

avatar AI Agent技术社区
cover

2026年，集团企业想要AI落地，选RPA还是Agent？

avatar AI Agent技术社区