Codex 使用指南

先读这张地图：什么必须配，什么不必配

• 先读哪里：配置层与 TOML 作用域 → 提供商与认证 → 按用途查字段字典。
• 必须建文件吗：config.toml 可以不存在，也可以为空，没有适用于所有用户的必抄模板。
• 连接需要什么：运行时能确定模型、提供商、地址和所需凭据；这些信息可来自内置值、登录态、环境变量或配置。

• 公开参考：306 条配置路径/用法，含表节点、别名和解绑写法，并非 306 个独立开关。
• 结构补充：103 个 Schema 顶层键及嵌套路径，用于核对字段结构。
• 版本差异：官方参考、Schema 与 CLI 帮助有时间差时，以正文标明的差异和版本边界理解。

依据：基础配置 · 完整配置参考 · 官方 Schema

文件位置、覆盖优先级与组织约束

普通配置优先级：从上到下逐级降低。

1. CLI 标志与 -c
2. 受信任项目配置（最近目录优先）
3. 选中的独立 profile 文件
4. 用户配置
5. 云端管理默认配置
6. 系统配置
7. 内置默认值

• 项目路径：相对路径通常相对于该 .codex/ 目录。
• 角色配置：config_file 相对于声明它的配置文件，不应一律按终端当前目录理解。
• 共享配置：含密钥、请求头或内部地址的用户配置，不要直接纳入公共 Dotfiles。

依据：配置层 · 项目限制与路径

TOML 语法：先查作用域与键值写法

• 顶层位置：顶层键写在表头之前。[model_providers.custom] 之后的键属于 custom，直到下一个表头；空行和注释不会重置作用域。
• 基本写法：字符串用引号，布尔值用 true/false，数组用方括号，# 开始注释。
• 重复定义：同一个键或同一个表重复定义，会产生解析问题。

#:schema https://learn.chatgpt.com/docs/config-schema.json
# 顶层：必须在下面的表头之前
model = "<你的服务支持的模型 ID>"
model_provider = "custom"
approval_policy = "on-request"

[model_providers.custom]
name = "公司的模型网关"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
env_key = "COMPANY_CODEX_KEY"
requires_openai_auth = false

# 新表头切换作用域
[mcp_servers.docs]
url = "https://developers.openai.com/mcp"

• 特殊 ID：含点号、斜杠或 @ 时加引号，如 [plugins."my-plugin@local-repo"]、[projects."/Users/me/work/app"]。
• 占位符：<id>、<name>、<tool>、<index> 需要替换，不能原样照抄。
• null：TOML 没有 JSON 的 null。参考中的“null 禁用”描述解析后的值；实际写法按字段支持的表达方式处理，通常先考虑省略。

一次性覆盖与配置方案

# shell 外层单引号保护 TOML 值；不会写回配置文件
codex -c 'model="gpt-6.1-sol"' -c 'web_search="disabled"'
codex --profile deep-review
# ~/.codex/deep-review.config.toml 内直接写顶层 model 等键
# profile 名允许字母、数字、连字符与下划线

• 旧写法：从 0.134.0 起，--profile 不再读取 [profiles.name]，顶层 profile = "name" 也不再受支持。
• 迁移方式：把旧表内容移入同目录 name.config.toml。Schema 中仍出现旧字段，不代表它们仍然有效。

依据：CLI 覆盖与 Profiles

提供商详解：ID、name、内置与自定义如何联动

• model：目标模型 ID。
• model_provider：选用的连接配置 ID，对应 [model_providers.ID]。
• name：给人看的显示名称，三者不要求同名。

自定义 ID 是 TOML 映射键，不是厂商名称枚举。仅改模型名不会自动切换服务。

model_provider = "custom"          # 选择的是 custom 这个 ID
model = "<gateway-model-id>"       # 网关实际接受的模型 ID

[model_providers.custom]           # 必须与选择器逐字一致
name = "OpenAI"                   # 仅显示名称；不会启用官方登录
base_url = "https://gateway.example.com/v1"
env_key = "COMPANY_CODEX_KEY"
wire_api = "responses"
requires_openai_auth = false

• 内置 ID：官方明确保留 openai、ollama、lmstudio；另有特殊内置提供商 amazon-bedrock。
• 自定义命名：建议用简短的 ASCII 字母、数字、连字符或下划线，减少 TOML 引号问题。这是维护建议，不是 provider 的固定字符长度规则。
• 必须选中：仅定义自定义表不会切换连接，还需要顶层 model_provider 选择对应 ID。

哪些是必需项？分清“语法必填”与“可工作的前提”

选择器与连接信息

协议、凭据与模型

依据：自定义与内置提供商 · Schema · Bedrock

地址、协议与能力：base_url 不是万能适配层

地址与登录入口

模型目录与服务能力

• 协议值：本次基线只支持 wire_api = "responses"，省略时也是该值；旧 "chat" 写法不适用。
• 兼容条件：服务需要支持 Codex 使用的 Responses、流式事件、工具调用及所选能力。仅有 /v1/chat/completions 不足以证明兼容。

• 官方 API：常见基地址为 https://api.openai.com/v1。
• 普通网关：示例可为 https://gateway.example.com/v1，但末尾路径以服务约定为准，不是一律追加 /v1。
• 不要填完整请求地址：避免把完整 /responses 请求 URL 当基地址。
• ChatGPT 透传网关：可能使用 /backend-api/codex；按网关文档填写，不要强改成 API Key 风格地址。

• 地址分别生效：模型请求、登录、模型目录、搜索、MCP 和插件可能各走不同端点；改一个 base_url 不代表代理全部流量。
• 联网开关的范围：命令沙箱的 network_access 不是模型请求的联网总开关。

依据：提供商配置 · 网关端点核对 · ChatGPT 网关路径

认证矩阵：登录方式、凭据来源与互斥组合

官方账号与 API

网关与动态凭据

本地、云平台与企业自动化

requires_openai_auth 到底控制什么？

• false（自定义提供商默认）：跳过 OpenAI 登录界面，需要令牌时使用 env_key 等已配置来源。
• true：使用 OpenAI API Key 或 ChatGPT 登录凭据，并走 OpenAI 认证流程和选定的凭据存储。
• 关键互斥：设为 true 时，env_key 会被忽略。不要同时填网关 Key 并期待它仍作为 Bearer 使用。
• 计费与登录限制：该开关不专指订阅登录，也不会根据 base_url 判断费用归属。只允许一种登录时，另看 forced_login_method = "chatgpt" 或 "api"。

设备码、企业令牌与强制登录限制

• 设备码：codex login --device-auth 是无浏览器场景的登录流程（Beta），不是第三种收费身份；可用性受工作空间设置影响。
• 企业令牌：Enterprise 管理员授权后，可为可信本地非交互工作流创建 Codex access token。它使用 ChatGPT 工作空间权益，不是通用 Platform API Key。

printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

• 工作负载身份：由进程环境选择；此时 codex login/logout 会被拒绝，不能靠修改 auth.json 修复。
• 强制登录限制：forced_login_method、forced_chatgpt_workspace_id 与活动凭据不符时，客户端会登出并退出；修改前先确认限制对象。

保存在哪里，与什么无关

cli_auth_credentials_store 选择 CLI 登录凭据的存储位置：

• file：使用 $CODEX_HOME/auth.json。
• keyring：使用系统凭据存储；不可用时失败。
• auto：优先系统凭据存储，不可用时回退到文件。
• ephemeral：只保存在当前进程内。

分别看待其他凭据：env_key 保存的是变量名，不会自动把环境变量写入 auth.json；mcp_oauth_credentials_store 管的是 MCP OAuth，不能替代模型登录。

依据：OpenAI 登录与自动化 · API / Provider 网关 · ChatGPT 经网关 · 凭据语义 Schema

七组最小配置：按认证场景选一组

A. 官方 ChatGPT 账号：可以完全不创建 config.toml

# 可选 ~/.codex/config.toml；模型须对账号可用
model = "gpt-6.1-sol"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

codex login
codex login status
# 无浏览器环境：先核对 codex login --help，再用 --device-auth

B. 官方 API Key：与订阅计费分开

# 终端已通过安全方式设置 OPENAI_API_KEY 后执行
printenv OPENAI_API_KEY | codex login --with-api-key
codex login status

C. 第三方 / 企业 Responses 网关，Bearer Key

model = "<gateway-model-id>"
model_provider = "company"

[model_providers.company]
name = "Company gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
env_key = "COMPANY_CODEX_KEY"
requires_openai_auth = false

启动 Codex 的进程需要拿到 COMPANY_CODEX_KEY。终端 export 不保证从 Dock / 开始菜单启动的桌面程序能继承它；不要为解决继承问题直接把密钥硬编码进公共配置。

D. 网关只接受 X-API-Key，而非 Authorization: Bearer

model = "<gateway-model-id>"
model_provider = "header_gateway"

[model_providers.header_gateway]
name = "Header gateway"
base_url = "https://gateway.example.com/v1"
requires_openai_auth = false
env_http_headers = { "X-API-Key" = "COMPANY_CODEX_KEY" }
# 不再设置 env_key 或 auth；缺失/空变量时该请求头会被省略

E. 外部命令动态返回 Bearer Token

model = "<gateway-model-id>"
model_provider = "token_gateway"

[model_providers.token_gateway]
name = "Short-lived token gateway"
base_url = "https://gateway.example.com/v1"
wire_api = "responses"
# 不设置 env_key、experimental_bearer_token、requires_openai_auth

[model_providers.token_gateway.auth]
command = "/usr/local/bin/fetch-codex-token"
args = ["--audience", "codex"]
timeout_ms = 5000
refresh_interval_ms = 300000

• 输入与输出：命令不接收 stdin；stdout 只输出令牌，诊断写 stderr。周围空白会被清理，空结果视为错误。
• 超时与刷新：默认 5 秒超时、5 分钟主动刷新。refresh_interval_ms = 0 关闭主动刷新，仅在认证重试路径重新获取。
• 工作目录：用 cwd 指定命令运行目录。

F. ChatGPT 登录经过可信企业网关

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

[model_providers.enterprise_gateway]
name = "ChatGPT via company gateway"
base_url = "https://gateway.example.com/backend-api/codex"
requires_openai_auth = true
env_http_headers = { "X-Gateway-Key" = "GATEWAY_KEY" }
# 不配置 provider.auth；Authorization 留给 ChatGPT 凭据

• 两份凭据：Authorization 承载 ChatGPT Token；X-Gateway-Key 承载网关 Key。
• 另一种方案：原生 gateway_oauth 见结构补充与企业部署文档。官方示例放在托管 requirements.toml，不能照搬成所有客户端都支持的用户层写法。
• 实施前提：网关具备对应转发实现，并获得组织授权。

G. 本地与 AWS：两条完全不同的提供商路径

# 本地模型：模型名须已在本机服务中存在
# ~/.codex/config.toml
oss_provider = "ollama"
# 终端：codex --oss --local-provider ollama -m <local-model-id>

# AWS 示例：独立配置方案，不与上例混用
model_provider = "amazon-bedrock"
model = "<supported-bedrock-model-id>"

[model_providers.amazon-bedrock.aws]
profile = "default"
region = "<supported-aws-region>"

依据：官方认证 · Provider API Key 与自定义头 · 令牌命令与 OSS · 双凭据网关

模型、推理、上下文与费用：四组参数不要混淆

模型与回答行为

上下文与压缩

速度、费用与预算

• 上下文：先保留模型默认参数，按任务调整模型支持的 effort。
• 压缩：/compact 总结会话，不退还已消耗额度；固定“省 80%”或“省 85%”没有普适保证。

依据：模型及可用性 · 上下文与配置

权限与审批：旧沙箱、新方案和自动审查

• 沙箱：决定命令能访问什么。
• 审批：决定何时、由谁审查请求。approval_policy = "never" 不弹出用户审批，失败直接返回模型，不单独扩大权限。
• 全访问：danger-full-access 移除本地沙箱限制，不宜作为一般排错第一步。

# Beta 示例：独立方案；不要同时保留 sandbox_mode
approval_policy = "on-request"
default_permissions = "project-edit"

[features]
network_proxy = true

[permissions.project-edit]
extends = ":workspace"

[permissions.project-edit.filesystem.":workspace_roots"]
"." = "write"
"**/*.env" = "deny"

[permissions.project-edit.network]
enabled = true

[permissions.project-edit.network.domains]
"registry.npmjs.org" = "allow"

• 先启用代理：enabled = true 只允许命令联网。要让 domain 规则生效，还需启用网络代理或管理员托管网络要求；没有活动代理时可能直接联网。
• 域名冲突：deny 优先。不能把未生效的代理规则当成已启用的域名白名单。
• 文件规则：先比较路径具体程度；同一路径再按 deny > write > read 决定。
• 继承限制：extends 不允许继承 :danger-full-access，也不允许循环。

• 代理范围：约束沙箱命令，不是 hosted web search、apps 或 MCP 的总防火墙。
• 平台差异：部分平台会在启动新进程前展开读拒绝 glob。后续新建文件及已有进程的行为，需按平台核实。
• 同名不同义：旧审批策略 untrusted 已不支持，on-failure 已废弃；项目的 trust_level = "untrusted" 仍有效。

依据：权限方案 Beta 与迁移 · 审批与沙箱 · 公开配置字典

搜索、MCP、Skills、插件、Hooks 与环境联动

搜索与 MCP 连接

技能、代理与运行环境

# 示例：远程 HTTP MCP；不需要此服务器时不要照抄
[mcp_servers.openai_docs]
url = "https://developers.openai.com/mcp"
startup_timeout_sec = 20
tool_timeout_sec = 60
required = false

# 私有服务可另配 bearer_token_env_var = "DOCS_MCP_TOKEN"
# 本地 stdio 示例应改用 command/args，而不是在同一服务混合两种传输

• 当前写法：使用 shell_environment_policy.filters；同一层不要混用旧 exclude/include_only。
• 默认行为：本次参考中 ignore_default_excludes 默认为 true，不会先自动剔除名称含 KEY / SECRET / TOKEN 的变量。
• 启用自动剔除：设为 false，再结合显式过滤规则。
• 设置顺序：显式 set 在排除后加入，但 include 过滤仍可能移除它。不要只凭字段名猜默认行为。

依据：配置参考 · Hooks · MCP · 子代理