# Codex 配置详解

Codex 的行为由 `~/.codex/config.toml` 控制(Windows 为 `%USERPROFILE%\.codex\config.toml`)。本页解释常用字段——按需配置即可。

---

## 配置在哪、谁优先

优先级从高到低:**命令行参数/`--config` 覆盖 → 项目级 `.codex/config.toml`(仅受信任项目,从项目根到当前目录逐层加载,越近越优先)→ profile 文件 → 用户级 `~/.codex/config.toml` → 系统配置 → 内置默认值**。

> 项目级配置只有在项目被 Codex 标记为 trusted 后才会加载;如果项目不受信任,项目内 `.codex/` 层、hooks、rules 都会跳过。团队仓库里不要提交密钥。项目级 `.codex/config.toml` 适合提交不含凭据、且不会被 Codex 忽略的项目规则/沙箱/权限类配置；`model_provider`、`[model_providers.*]`、`openai_base_url`、`base_url`、`env_key` 等 provider/auth 配置请放用户级 `~/.codex/config.toml` 或 profile 文件,不要指望团队仓库里的 project config 覆盖 provider/base URL。受管机器还可能用 `requirements.toml` 禁止 `approval_policy = "never"` 或 `sandbox_mode = "danger-full-access"`。

高频误判：把 Clomio provider 片段复制到仓库里的 `.codex/config.toml` 后仍直连官方或仍用旧模型，并不代表网关不可用。先把 provider/auth 放进用户级 `~/.codex/config.toml`，再运行 `codex --config model_provider=clomio` 或最小 `POST /v1/responses` curl 验证；项目级文件只保留团队规则、沙箱、MCP、hooks 等不含密钥的内容。

---

## 接入 Clomio 的基础块

```toml
model_provider = "clomio"
model = "gpt-5.4"
model_reasoning_effort = "high"
preferred_auth_method = "apikey"

[model_providers.clomio]
name = "clomio"
base_url = "https://api.clomio.ai/v1"
wire_api = "responses"
env_key = "CLOMIO_API_KEY"
```

控制台「使用 Key」弹窗可能输出另一种自包含模板:直接写 `experimental_bearer_token = "sk-..."` 并配 `requires_openai_auth = true`。那种模板方便复制即用,但不适合提交或同步;长期推荐仍是上面的 `env_key` 模式。两种模式不要同时写。

密钥放在环境变量,不要写进项目仓库:

**macOS / Linux:**

```bash
export CLOMIO_API_KEY="你的密钥"
# 想长期生效可写入 ~/.zshrc 或 ~/.bashrc
```

**Windows(PowerShell):**

```powershell
$env:CLOMIO_API_KEY = "你的密钥"
# 想长期生效:
[Environment]::SetEnvironmentVariable("CLOMIO_API_KEY", "你的密钥", "User")
```

> `base_url` 可换成另外两条[线路](#/gateway-lines),例如 `https://sub.qazwc.com/v1` 或 `https://crs.qazwc.com/v1`。

---

## 模型与推理

| 字段 | 取值 | 含义 |
|------|------|------|
| `model` | 模型名 | 用哪个模型,以控制台分组为准 |
| `model_reasoning_effort` | `minimal`/`low`/`medium`/`high`/`xhigh` | 推理投入,越高越细致越慢越费 token |
| `model_reasoning_summary` | `auto`/`concise`/`detailed`/`none` | 推理摘要详略 |
| `model_verbosity` | `low`/`medium`/`high` | 输出详细程度(仅 Responses API 生效) |
| `plan_mode_reasoning_effort` | 同 effort | 仅 `/plan` 模式下的推理强度覆盖 |
| `hide_agent_reasoning` | `true`/`false` | 隐藏推理过程(截图/CI 日志更干净) |
| `show_raw_agent_reasoning` | `true`/`false` | 显示原始推理内容 |

---

## 审批与沙箱(安全相关)

控制 Codex 执行命令的自由度:

```toml
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[sandbox_workspace_write]
network_access = false
writable_roots = ["~/work/scratch"]
```

| 字段 | 取值 | 含义 |
|------|------|------|
| `approval_policy` | `untrusted` / `on-request` / `on-failure` / `never` | 何时停下来问你再执行命令 |
| `sandbox_mode` | `read-only` / `workspace-write` / `danger-full-access` | 文件/网络访问范围 |
| `[sandbox_workspace_write].network_access` | `true`/`false` | 写模式下是否允许联网 |
| `[sandbox_workspace_write].writable_roots` | 路径数组 | 额外可写目录 |

> `workspace-write` 下,`.git/` 等目录有时仍只读,所以 `git commit` 可能仍需确认。日常用 `on-request` + `workspace-write` 比较稳妥;别轻易用 `danger-full-access`。

---

### 审批/沙箱常见误区

- `approval_policy = "never"` 只是不再向你要授权,不是“自动获得更多权限”;如果沙箱仍是 `read-only` 或 `workspace-write`,越界写文件/联网仍会失败。
- `sandbox_mode = "danger-full-access"` 才是放开文件系统沙箱;不要为了让一个额外目录可写就全放开,优先用 `--add-dir` 或 `[sandbox_workspace_write].writable_roots`。
- `network_access = true` 只影响 `workspace-write` 沙箱下的联网;如果外层系统/代理不通,它不能修复网络。
- CI 或旁路 worker 推荐固定 `--sandbox workspace-write --approval on-request` 或对应配置,避免误改仓库外文件。

## 你给的这些字段怎么理解

你列出的配置混了"Codex 风格"与若干自定义键。Codex 原生用 TOML,部分字段对应如下:

```toml
# 语言、更新通道
# (Codex 用 AGENTS.md 控制回复语言;更新通道见各客户端设置)

# 推理强度 —— 对应 effortLevel = high
model_reasoning_effort = "high"

# 始终思考 / 显示思考摘要
model_reasoning_summary = "detailed"

# 详细输出
hide_agent_reasoning = false

# 署名:留空即不在 commit / PR 里加署名
[attribution]
commit = ""
pr = ""
```

下面几个是分组化的高级表:

```toml
# 子代理:并行线程数与递归深度
[agents]
max_threads = 10
max_depth = 2

# 记忆(留空表示使用默认)
[memories]

# 功能开关(留空接受默认,或显式开关单项)
[features]
# multi_agent = true
# fast_mode = true
```

| 表 / 字段 | 含义 |
|-----------|------|
| `[agents].max_threads` | 子代理最大并行数 |
| `[agents].max_depth` | 子代理最大递归深度 |
| `[memories]` | 记忆相关配置(留空用默认) |
| `[features]` | 功能开关表,如 `multi_agent`、`fast_mode`、`hooks` 等 |

---

## Profile:多套配置一键切

Codex 0.134.0 起,`--profile crs` 不再读取 `~/.codex/config.toml` 里的 `[profiles.crs]`。要给不同[线路](#/gateway-lines)或场景建 profile,请新建独立文件 `~/.codex/crs.config.toml`,里面直接写顶层配置键:

```toml
# ~/.codex/crs.config.toml
model_provider = "clomio_crs"
model = "gpt-5.4"

[model_providers.clomio_crs]
name = "clomio_crs"
base_url = "https://crs.qazwc.com/v1"
wire_api = "responses"
env_key = "CLOMIO_API_KEY"
```

```bash
codex --profile crs
```

> 不要再写 `[profiles.crs]` 或 `profile = "crs"`;新版 Codex 不会用这些旧写法。

## Provider 与认证放哪里

`model_provider`、`[model_providers.*]`、`base_url`、`env_key`、`wire_api` 等决定 Codex 如何连到供应商。provider/auth 相关键请放用户级或 profile 文件；项目级 `.codex/config.toml` 里出现这些键时可能被 Codex 忽略并给出启动警告。若 provider/base URL 配在项目目录后没有生效,先移到用户级 `~/.codex/config.toml` 或 `~/.codex/<profile>.config.toml`,再确认该项目是否 trusted,以及启动时是否被 `--profile`、`--config` 或受管 `requirements.toml` 覆盖。

认证方式二选一:

- 推荐:`env_key = "CLOMIO_API_KEY"`,密钥来自本机环境变量。
- 复制即用/不推荐长期保存:`experimental_bearer_token = "sk-..."` 配合 `requires_openai_auth = true`,控制台弹窗可能这样生成。
- 兼容/不推荐:`requires_openai_auth = true`,使用 Codex 的 OpenAI 认证链路,例如旧版 `~/.codex/auth.json` 里的 `OPENAI_API_KEY`。启用后 Codex 会忽略 `env_key`,所以不要和 `env_key` 混用。

如果你从控制台模板切换到环境变量模式,删除 `experimental_bearer_token` 和 `requires_openai_auth`,再确认 `codex /status` 或启动日志里实际 provider/base URL 已变更。

旧配置如需临时兼容可保留:

```toml
[model_providers.clomio]
name = "clomio"
base_url = "https://api.clomio.ai/v1"
wire_api = "responses"
requires_openai_auth = true
```

```json
{ "OPENAI_API_KEY": "你的密钥" }
```

---

## Responses wire API 与 WebSocket 选项

Clomio 的 Codex provider 固定按 OpenAI-compatible Responses 使用:

```toml
[model_providers.clomio]
base_url = "https://api.clomio.ai/v1"
wire_api = "responses"
env_key = "CLOMIO_API_KEY"
# 如客户端版本支持且网关账号允许,可启用 Responses WebSocket:
# supports_websockets = true
#
# [features]
# responses_websockets_v2 = true
```

官方配置参考里 `wire_api` 当前只支持 `responses`;`supports_websockets` 表示该 provider 是否支持 Responses API WebSocket transport。Codex WS v2 实际还需要 `[features].responses_websockets_v2 = true`;控制台「Codex WS」tab 会同时生成这两个开关。不开 WS 时仍可用普通 `POST /v1/responses` / SSE 流式。Codex wire API 只覆盖 Responses 对话链路;其他能力请按对应工具页配置。

普通 `GET /v1/responses` 不是健康检查 REST API。OpenAI/Grok 分组过鉴权后返回 426 才说明命中了 WS 入口；不支持该能力的分组才会返回 404。Grok 分组是否开放 WS 以当前分组能力为准。

### Provider 绑定与环境污染排查

- `model_provider = "clomio"` 必须能对应到 `[model_providers.clomio]`;改 provider 名时两处一起改。
- `env_key = "CLOMIO_API_KEY"` 只读取这个变量;如果同时保留 `OPENAI_API_KEY`、`OPENAI_BASE_URL` 或旧 `auth.json`,旧版/兼容写法可能让你误以为新 key 已生效。
- `requires_openai_auth = true` 与 `env_key` 二选一;前者走 Codex/OpenAI 认证链路,后者走指定环境变量。Clomio 网关推荐 `env_key`。
- OpenAI-compatible base URL 写到 `/v1` 即止:`https://api.clomio.ai/v1`;不要写 `/v1/responses`、`/v1/chat/completions` 或不带 `/v1`。
- 模型名只按当前 Clomio 分组开放列表填写;本地 alias、OpenAI 官网模型名和控制台展示不一致时,以控制台为准。

## MCP:接外部工具

```toml
[mcp_servers.context7]
command = "npx"
args = ["-y", "@upstash/context7-mcp"]
```

会话里 `/mcp` 查看已连接工具。更多见 [Codex 进阶](#/codex-advanced)。

---

## 参考资料

- [OpenAI Codex Config basics](https://developers.openai.com/codex/config-basic)
- [OpenAI Codex Configuration reference](https://developers.openai.com/codex/config-reference)
- [OpenAI Codex Advanced config](https://developers.openai.com/codex/config-advanced)
- [OpenAI Codex CLI reference](https://developers.openai.com/codex/cli/reference)
- [Codex 社区配置经验(X)](https://x.com/canghe/article/2060376680896799094):公开中转站教程反复强调 `base_url` 只写到 `/v1`,并保留 `wire_api = "responses"`。
- [Codex WS 排障经验(X)](https://x.com/mylifcc/status/2057308552738505031):WS 不稳定时可尝试禁用 `supports_websockets`,但不要把这个当成所有环境的默认值。

> 字段会随版本变化,完整列表以 [官方配置参考](https://developers.openai.com/codex/config-reference) 为准。生图功能见 [Codex 生图](#/codex-image)。