# Codex 配置参考

> Codex config.toml、auth.json、profiles、Provider、模型、沙箱、审批、环境变量和项目级配置的速查。

URL: https://docs.passion8.cc/docs/codex/config-reference
Language: zh-CN
Publisher: Passion8

[配置教程](https://docs.passion8.cc/docs/codex/config) 负责让 Passion8 先跑通。本页负责解释 Codex 配置层级和常用字段,方便后续做团队模板、Profile、CI 或高级权限策略。

## 文件位置

| 文件 | 作用 |
| --- | --- |
| `~/.codex/config.toml` | 用户级默认配置 |
| `~/.codex/auth.json` | 文件型认证缓存或 API key 存放位置 |
| `~/.codex/<profile>.config.toml` | CLI `--profile` 加载的命名配置 |
| `.codex/config.toml` | 项目级配置,仅在信任项目后加载 |
| `.codex/hooks.json` / `.codex/rules/` | 项目级 hooks 和 rules |

Codex 本地状态默认放在 `~/.codex`。如果你设置 `CODEX_HOME`,配置、auth、日志、skills、sessions 都会跟着换目录。

## 配置优先级

从高到低:

1. CLI flags 与 `-c key=value`
2. 项目 `.codex/config.toml`,从项目根到当前目录,越近优先级越高
3. `--profile <name>` 对应的 `~/.codex/<name>.config.toml`
4. 用户 `~/.codex/config.toml`
5. 系统配置
6. Codex 内置默认值




项目级 `.codex/config.toml` 只在 trusted project 中加载。未信任项目时,项目 hooks、rules 和项目配置都会被跳过。




## Passion8 Provider 模板

```toml title="~/.codex/config.toml"
model_provider = "Passion8"
cli_auth_credentials_store = "file"
forced_login_method = "api"
model = "gpt-6-sol"
review_model = "gpt-6-sol"
model_reasoning_effort = "medium"
model_context_window = 272000
model_auto_compact_token_limit = 250000
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

[model_providers.Passion8]
name = "Passion8"
wire_api = "responses"
requires_openai_auth = true
base_url = "https://passion8.cc/v1"
```

认证放在 `~/.codex/auth.json`:

```json title="~/.codex/auth.json"
{
  "OPENAI_API_KEY": "sk-你的 Passion8 API Key"
}
```




`base_url` 必须带 `/v1`。Key 不建议写进 `config.toml`,避免把配置文件同步或截图时泄露凭据。




## Profile

Profile 适合保存“深度审查”“只读巡检”“快速小改”等常用配置。Codex 会先加载用户配置,再叠加 profile 文件。

```toml title="~/.codex/deep-review.config.toml"
model = "gpt-6-sol"
model_reasoning_effort = "xhigh"
sandbox_mode = "read-only"
approval_policy = "on-request"
```

启动:

```bash
codex --profile deep-review
codex exec --profile deep-review "review this change"
```

Profile 文件使用顶层配置键,不要写成 `[profiles.deep-review]`。

## 常用字段

| 字段 | 示例 | 说明 |
| --- | --- | --- |
| `model` | `"gpt-6-sol"` | 默认模型 |
| `review_model` | `"gpt-6-sol"` | `/review` 等审查场景使用的模型 |
| `model_provider` | `"Passion8"` | 使用哪个 provider |
| `model_reasoning_effort` | `"medium"` | 推理强度 |
| `model_verbosity` | `"low"` | Responses API 下的输出详略 |
| `model_context_window` | `272000` | 本站 gpt-6-sol 客户端窗口限制;与手动配置和 CC-Switch 保持一致,不是官方最大窗口 |
| `model_auto_compact_token_limit` | `250000` | 达到该 token 数时自动压缩;通常略低于窗口(示例为 `gpt-6-sol`;`grok-4.7` 用 `500000` / `475000`) |

| `approval_policy` | `"on-request"` | 什么时候需要审批 |
| `sandbox_mode` | `"workspace-write"` | 文件和命令沙箱边界 |
| `web_search` | `"cached"` | cached / indexed / live / disabled |
| `personality` | `"pragmatic"` | 交流风格 |
| `log_dir` | `"./.codex-log"` | 明文诊断日志目录 |

## 项目级配置限制

项目 `.codex/config.toml` 适合写 repo 内规则,例如项目默认沙箱、hooks、rules 或 AGENTS.md 发现参数。它不适合写 Provider 和凭据。

Codex 会忽略或警告部分项目级敏感键,包括:

- `model_provider`
- `model_providers`
- `openai_base_url`
- `chatgpt_base_url`
- `profile`
- `profiles`
- `notify`
- `otel`

这些应放在用户级或管理员配置里。

## 环境变量

| 变量 | 用途 |
| --- | --- |
| `CODEX_HOME` | 改变 Codex 本地状态根目录 |
| `CODEX_API_KEY` | 只用于单次 `codex exec` 的 API key |
| `CODEX_ACCESS_TOKEN` | 受信自动化使用的 Codex access token |
| `CODEX_CA_CERTIFICATE` | 企业 TLS 代理或私有 CA |
| `RUST_LOG` | CLI / app-server 日志级别 |

自动化里优先把 `CODEX_API_KEY` 设置在单个命令前,不要让整个 CI job 环境长期持有 key。

## Web search

```toml
web_search = "cached"   # 默认,使用 OpenAI 维护的搜索缓存
# web_search = "live"   # 实时抓取,等价于 --search
# web_search = "disabled"
```

Live search 会增加接触不可信网页内容的机会。陌生网页、issue、README 和网页里的隐藏指令都要当作不可信输入。

## 排错命令

```bash
codex --version
codex doctor
codex --strict-config
codex -c log_dir=./.codex-log
```

在 TUI 内优先看:

```text
/status
/debug-config
/model
/permissions
```

## 官方参考

- [Codex manual: Config basics](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Advanced Configuration](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Configuration Reference](https://developers.openai.com/codex/codex-manual.md)
- [Codex manual: Environment variables](https://developers.openai.com/codex/codex-manual.md)