toklens
中文

博客

Codex 接入 TokLens：config.toml 每一行是什么意思

生成的两个文件逐行说明，哪些设置可以自己加，接不通时先查哪里。

更新于 Codex约 6 分钟读完TokLens Team

本文目录
  1. 文件在哪
  2. config.toml 逐行说明
  3. auth.json
  4. 怎么让 Codex 用这份配置
  5. 哪些设置可以自己加
  6. 确认接通
  7. 常见报错

适用于 TokLens 接入工具 @toklens/agentic-setup 0.1.3，2026 年 10 月核对。

在「接入工具」里选好 Key 和 Codex，或者在活动页「接入指引」点「生成并复制命令」，运行生成的命令后，TokLens 会在你的电脑上写入两个文件。这篇逐行说明这两个文件、哪些设置可以自己加，以及接不通时先查哪里。

文件在哪

~/.toklens/profiles/<profile>/codex/config.toml
~/.toklens/profiles/<profile>/codex/auth.json

<profile> 是安装命令里 --profile 后面的名字；活动页一键配置的是 activity-<活动名>，比如 activity-waytoagi。Windows 上 ~ 是 %USERPROFILE%。

这两个文件不在 ~/.codex。Codex 默认读 ~/.codex，TokLens 工具启动 Codex 时会把环境变量 CODEX_HOME 指向上面这个目录。所以你原来用 ChatGPT 登录的 ~/.codex 不受影响，两套配置可以同时保留。

config.toml 逐行说明

model_provider = "toklens"
model = "gpt-6.1-sol"

[model_providers.toklens]
name = "toklens"
base_url = "https://<你的 Key 所属服务的地址>"
wire_api = "responses"
requires_openai_auth = true
  • model_provider = "toklens"：使用下面名为 toklens 的服务商配置，不用 Codex 内置的 OpenAI。
  • model：默认模型，就是在「接入工具」里填的模型；没填时是 gpt-6.1-sol。在 Codex 里用 /model 切换，或者启动时加 -m。模型要在这个 Key 所属服务的价格表里，否则请求会失败。
  • name：显示用的名字，不影响请求。
  • base_url：请求地址，也就是「接入工具」里这个 Key 的「接入地址」（去掉末尾的 /v1）。不同服务的地址不同，以生成的文件为准。Codex 会在后面加上 /responses。不要自己改，改了下次运行会被改回来。网上教程里带 /v1 的写法也能用，TokLens 在 /responses 和 /v1/responses 都接收请求。
  • wire_api = "responses"：使用 Responses 接口。TokLens 的 Codex 模型只支持这个接口。一些旧教程里写的 wire_api = "chat"，新版 Codex 已经不支持。
  • requires_openai_auth = true：让 Codex 用 auth.json 里的 Key 发请求。如果改成 false，又没有另外配置 Key，请求就不带 Key，TokLens 会返回 401 API_KEY_REQUIRED。

auth.json

{
  "OPENAI_API_KEY": "你的 TokLens Key"
}

字段名是 Codex 规定的，值是你的 TokLens Key。

Key 本身保存在 ~/.toklens/secrets/<profile>.env，auth.json 每次都按它重新生成。在 macOS 和 Linux 上，这两个文件的权限都是 600，只有你自己的账户能读。不要提交到 Git，也不要发给别人。

「接入工具」的安装命令里没有完整 Key。能自动下发时，命令里只有一张 15 分钟内有效、只能用一次的凭证，Key 在你的电脑上兑换后直接写进这个文件；不能自动下发的 Key，或者选了「其他 Key」时，运行后按提示在终端里粘贴。活动页「生成并复制命令」生成的命令是例外：它已经带上活动 Key，不需要粘贴，所以只在自己的电脑上运行，不要发给别人。

怎么让 Codex 用这份配置

直接在终端输入 codex，读的仍然是 ~/.codex。在活动页一键配置的，命令已经装好启动命令 codex-toklens，以后在新终端输入它就行。其他情况通过 toklens-agentic run 启动：

toklens-agentic run --client codex --profile <profile> -- codex

也可以先在当前终端设置好环境变量，之后直接用 codex：

eval "$(toklens-agentic env --client codex --profile <profile>)"
codex

env 会把 Key 放进当前终端的环境变量，关掉这个终端就失效。它输出的是 bash 和 zsh 的写法。

终端里原有的 OPENAI_API_KEY、OPENAI_BASE_URL 和 CODEX_HOME 不会造成干扰：run 启动的 Codex 不继承这三个变量，env 会用 profile 的值覆盖它们。

安装命令最后已经执行过 switch，把这个 profile 设成了默认，所以 run 可以省略 --profile。有多个 profile 时，用 switch 改默认：

toklens-agentic --mode sandbox --action switch --client codex --profile <profile> --apply

在执行过 env 的终端里，run 优先使用 env 设置的 profile。

哪些设置可以自己加

auth.json，以及 config.toml 里的 model_provider 和 [model_providers.toklens]，由工具管理。run、env、doctor，以及带 --apply 的 setup 和 switch，都会按 profile 重写这些内容，手动改了也会被改回来。

config.toml 里的其他设置会保留，比如 service_tier、model_reasoning_effort 和 [mcp_servers.*]。model 改成别的模型也会保留，重新运行 setup 时恢复为默认模型。

这需要 0.1.3 或更高版本。旧版本每次运行都会重写整个文件，先用 toklens-agentic --version 查看版本，需要时升级：

npm install -g @toklens/agentic-setup@latest

service_tier 这类顶层设置，要写在第一个 [...] 之前。写在文件末尾，TOML 会把它当作上一个表的内容。如果上一个表是 [model_providers.toklens]，工具会把它移回顶层；其他表不会。

常见的改法：

  • 换模型：在 Codex 里用 /model，或者启动时加 -m。
  • 开 Fast：在 Codex 里输入 /fast on。要一直开启，见 Codex Fast 配置和计费说明。
  • 换 Key：在「接入工具」重新生成安装命令并运行（活动 Key 在活动页重新点「生成并复制命令」）。profile 名跟着 Key 走，之后命令里的 <profile> 要换成新的名字。

因为 CODEX_HOME 换了目录，~/.codex/config.toml 里的 MCP 服务器等设置、~/.codex/AGENTS.md 都不会生效，会话记录也保存在 profile 目录里。需要的话，把 MCP 设置复制到 profile 的 config.toml，把 AGENTS.md 复制到 profile 的 codex 目录。项目目录里的 AGENTS.md 照常读取。

确认接通

先检查文件：

toklens-agentic doctor --client codex --profile <profile> --skip-client

它先按 profile 更新工具管理的内容，再检查 base_url、wire_api、requires_openai_auth、auth.json 的权限和 Key。通过只说明文件没问题，不代表请求一定能成功。

再发一条真实请求：

toklens-agentic run --client codex --profile <profile> -- \
  codex exec --skip-git-repo-check "Reply with exactly TOKLENS_OK."

最后在「用量明细」里找到这条请求，核对模型和扣费。

常见报错

报错原因处理
401 API_KEY_REQUIRED请求里没有 Key检查 auth.json 里有没有 Key、requires_openai_auth 是不是 true；运行一次 doctor 会改回正确的值
401 INVALID_API_KEYKey 不存在或不完整重新生成安装命令再运行一次
401 API_KEY_DISABLEDKey 已停用换一个 Key
403 API_KEY_EXPIREDKey 已过期换一个没过期的 Key
403 INSUFFICIENT_BALANCE余额不足到「钱包」给这个 Key 分配余额
429 insufficient_quotaKey 上的余额用完（「API key 额度已用完」）自己的 Key 到「钱包」的「为 Key 分配余额」补上，管理员发的 Key 联系管理员
429 rate_limit_exceeded、rate_limit_error请求太频繁或到了限额稍后重试
usage_limit_reachedChatGPT 套餐的用量上限，不是 TokLens 的报错；通常说明 Codex 读的还是 ~/.codex 里的 ChatGPT 登录通过 toklens-agentic run 启动

每种报错的原因和处理办法，见 Codex 报错对照：401、403、429。

用户手册：接入 Codex 和 Claude Code