Codex · 手动配置

v0.145.02026-07-21Apache-2.0GitHub

适用场景

配置 Codex 的模型、审批、沙箱、Profile 或第三方 provider

面向读者

需要手写 TOML、项目级覆盖或多 provider 的开发者

TL;DR

config.toml 保存设置 → codex login 管理官方认证 → 第三方 Key 用独立环境变量

配置位置

范围	路径
用户级	`~/.codex/config.toml`
项目级	项目根目录 `.codex/config.toml`（仅信任项目时加载）
Profile	`~/.codex/<profile-name>.config.toml`，用 `--profile <name>` 选择
Codex 主目录	`CODEX_HOME` 可改变默认 `~/.codex` 位置

CLI、IDE 扩展和 Codex 桌面 App 共享配置层。修改后启动新会话核对实际 provider、模型与权限。

官方 OpenAI 登录

# 默认：浏览器完成 ChatGPT 登录
codex login
 
# 从环境变量通过 stdin 使用 OpenAI API Key
printenv OPENAI_API_KEY | codex login --with-api-key
 
# 查看当前认证方式
codex login status

不要手工编辑 auth.json。Codex 可能把凭据保存在 ~/.codex/auth.json 或操作系统凭据存储中；如果使用文件存储，应把它当作密码文件，绝不能上传仓库、截图或排障网站。

第三方自定义 provider

下面是基于 OpenAI 官方 custom provider schema 的最小模板；foropencode.com 是第三方网关，不是 OpenAI：

model_provider = "foropencode"
model = "gateway-model-id"
model_reasoning_effort = "medium"
 
[model_providers.foropencode]
name = "foropencode (third-party gateway)"
base_url = "https://foropencode.com/v1"
env_key = "FOROPENCODE_API_KEY"
wire_api = "responses"

在启动 Codex 的 shell 中提供 Key：

export FOROPENCODE_API_KEY="sk-xxx"
codex

$env:FOROPENCODE_API_KEY = "sk-xxx"
codex

env_key 让 Codex 从环境变量读取第三方凭据，避免手写到 TOML。当前官方配置参考中 wire_api 仅支持 responses（省略时的默认值）；Chat Completions（wire_api = "chat"）已不在受支持取值之列。若网关只支持 Chat Completions，应向网关确认当前 Codex 兼容方案，不要自行猜字段。

审批与沙箱默认值

approval_policy = "on-request"
sandbox_mode = "workspace-write"
 
[sandbox_workspace_write]
network_access = false

默认保持网络关闭和工作区写入边界。只有任务确实需要时再放宽；不要把 danger-full-access 作为解决权限报错的通用方式。

Profile

# ~/.codex/read-only.config.toml
sandbox_mode = "read-only"
approval_policy = "on-request"

codex --profile read-only
codex exec --profile read-only "review this change"

旧 CODEX_PROFILE=...、顶层 profile = ... 与 [profiles.<name>] 不适用于 Codex 0.134.0 及以后。

排查

现象	检查
401	`codex login status`；或第三方 `env_key` 对应环境变量是否存在
404	第三方网关给出的 Base URL 与协议是否匹配
项目配置不生效	项目是否已信任；`.codex/config.toml` 路径是否正确
Profile 不生效	文件是否为 `~/.codex/<name>.config.toml`，启动时是否传 `--profile <name>`
App 与 CLI 不一致	完全退出旧会话，再核对共享配置层和实际登录方式

Codex · 手动配置​

配置位置​

官方 OpenAI 登录​

第三方自定义 provider​

审批与沙箱默认值​

Profile​

排查​

相关