---
title: Codex CLI 安装、配置与常用方法
date: 2026-05-26
tags: [Codex, OpenAI, CLI, AI 编程]
collections: [软件安装]
summary: 基于 2026-05-26 检索到的 OpenAI 官方文档，整理使用 mamba 准备 Node.js 环境后安装 Codex CLI 的流程、配置文件写法和常用操作。
draft: false
featured: false
---

# Codex CLI 安装、配置与常用方法

这篇笔记基于 2026-05-26 检索到的 OpenAI 官方文档整理，目标是把 Codex CLI 的安装、配置文件和常用操作一次讲清楚。考虑到我自己更习惯用 `mamba` 管理本地 Node.js 环境，下面先保留这条安装路径，再接官方的 npm 安装步骤。原始草稿里那种把真实密钥直接写进配置文件的做法不适合保留，正式使用时应当改成环境变量或官方登录方式。

## 安装 Codex CLI

### 使用 mamba 准备 Node.js 环境

如果你平时用 `mamba` 管理开发环境，可以先单独准备一个 Node.js 环境，再在这个环境里安装 Codex CLI：

```bash
mamba create -n node nodejs -y
mamba activate node
```

如果你已经有可用的 Node.js 环境，可以直接跳到下一步。

### 使用 npm 安装 Codex CLI

OpenAI 官方文档给出的 npm 安装命令如下：

```bash
npm i -g @openai/codex
```

安装完成后直接运行：

```bash
codex
```

第一次启动时，Codex 会提示登录。官方也给出了升级命令：

```bash
npm i -g @openai/codex@latest
```

如果你只是想先确认 CLI 是否已经可用，最直接的方式就是运行 `codex` 看是否能进入交互界面。

## 登录方式

Codex 官方支持两种主要认证方式：

1. 使用 ChatGPT 账号登录，适合日常交互式使用。
2. 使用 API key 登录，适合按量计费和自动化场景。

### 使用 ChatGPT 登录

对 CLI 来说，默认登录路径是 ChatGPT 登录。运行 `codex` 或显式执行下面的命令后，Codex 会打开浏览器完成登录流程：

```bash
codex login
```

这种方式更适合个人日常使用，因为它直接走 ChatGPT 账号授权流程。

### 使用 API key 登录

如果你更关心脚本化、CI/CD 或明确的 API 计费路径，可以改用 API key。官方建议把 API key 用在程序化工作流中，而不是写死在配置文件里。

```bash
export OPENAI_API_KEY="sk-..."
printenv OPENAI_API_KEY | codex login --with-api-key
```

### 无图形界面环境

如果是在远程服务器、无浏览器环境或者本地回调被网络策略拦截，可以使用设备码登录：

```bash
codex login --device-auth
```

## 配置文件位置与优先级

Codex 的用户级配置文件位于 `~/.codex/config.toml`。如果希望只对某个仓库生效，可以在项目中添加 `.codex/config.toml`。

官方文档给出的配置优先级从高到低是：

1. CLI 参数和 `--config` 覆盖。
2. `--profile <name>` 指定的 profile。
3. 项目级 `.codex/config.toml`。
4. 用户级 `~/.codex/config.toml`。
5. 系统级配置。
6. 内置默认值。

需要注意的是，一些与机器本地环境强绑定的键不适合放在项目级配置里。像 `model_provider`、`model_providers`、`profiles`、`openai_base_url` 和 `chatgpt_base_url` 这类字段，官方明确要求放在用户级配置中。

## 一份适合日常使用的配置

如果你主要是在本机交互式写代码，下面这份配置已经够用：

```toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
plan_mode_reasoning_effort = "high"

approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"

cli_auth_credentials_store = "keyring"

[projects."/path/to/project"]
trust_level = "trusted"
```

这份配置的含义很直接：

- `model` 指定默认模型。官方示例给大多数用户推荐的是 `gpt-5.5`。
- `model_reasoning_effort` 控制默认推理强度，可选值包括 `minimal`、`low`、`medium`、`high` 和 `xhigh`。
- `plan_mode_reasoning_effort` 控制计划模式下的推理强度，适合在 `/plan` 时单独拉高。
- `approval_policy = "on-request"` 表示由 Codex 决定何时向你申请批准，适合多数交互式场景。
- `sandbox_mode = "workspace-write"` 表示允许在当前工作区写文件，但不是完全放开机器权限。
- `web_search = "cached"` 表示默认启用缓存型网页搜索；如果要查最新资料，可以临时改成 `--search` 或把配置改成 `live`。
- `cli_auth_credentials_store = "keyring"` 表示尽量把登录凭据放进系统密钥链，而不是纯文件。
- `trust_level = "trusted"` 表示把这个仓库标记为可信项目，这样项目级 `.codex/` 配置、rules 和 hooks 才会生效。

## 配置项详解

下面这些字段是最常用、也最值得理解的。

### `model`

`model` 决定 Codex 默认调用哪个模型。OpenAI 官方示例里推荐大多数用户使用 `gpt-5.5`；如果你更想显式指定编码导向模型，也可以改成例如 `gpt-5.3-codex`。

```toml
model = "gpt-5.5"
```

### `model_provider`

`model_provider` 指向 `[model_providers]` 中的某个 provider id。默认 provider 是 `openai`。

```toml
model_provider = "openai"
```

如果你没有自建代理、Azure 或本地模型需求，通常不需要改它。

### `model_reasoning_effort`

这个字段控制模型的推理强度，适合在速度和深度之间做平衡。

```toml
model_reasoning_effort = "medium"
```

一般可以这样理解：

- `low` 或 `medium` 适合日常改代码、解释报错、补文档。
- `high` 或 `xhigh` 更适合复杂重构、跨文件问题定位和方案分析。

### `plan_mode_reasoning_effort`

这是计划模式专用的推理强度覆盖项。也就是说，平时对话可以用 `medium`，但在 `/plan` 阶段单独切到 `high`。

```toml
plan_mode_reasoning_effort = "high"
```

### `approval_policy`

官方支持三种主模式：

- `untrusted`：只自动执行已知安全的只读命令，其他操作更谨慎。
- `on-request`：由 Codex 决定何时请求批准。
- `never`：尽量不询问，风险最高。

```toml
approval_policy = "on-request"
```

如果是个人机器上的正常开发工作流，`on-request` 通常最稳妥。

### `sandbox_mode`

这个字段控制 Codex 执行命令时的沙箱范围：

- `read-only`
- `workspace-write`
- `danger-full-access`

```toml
sandbox_mode = "workspace-write"
```

通常建议从 `workspace-write` 起步，不要一开始就切到 `danger-full-access`。

### `default_permissions`

新权限体系可以用 `default_permissions` 指向命名权限配置，官方内置了：

- `:read-only`
- `:workspace`
- `:danger-full-access`

```toml
default_permissions = ":workspace"
```

官方文档特别提醒，不要把这套权限配置和旧式的 `sandbox_mode` 混着用。二选一即可。

### `web_search`

Codex 自带第一方网页搜索工具，顶层配置支持：

- `disabled`
- `cached`
- `live`

```toml
web_search = "cached"
```

如果你查的是版本更新、价格、新闻或最近发布内容，改成 `live` 更合适。

### `review_model`

如果你经常在交互界面里使用 `/review`，可以单独给 review 指定模型：

```toml
review_model = "gpt-5.5"
```

不配置时，默认沿用当前会话模型。

### `cli_auth_credentials_store`

这个字段决定 CLI 如何保存登录凭据：

- `file`
- `keyring`
- `auto`

```toml
cli_auth_credentials_store = "keyring"
```

如果本机系统支持密钥链，优先用 `keyring` 或 `auto` 更合理。

## 自定义 provider 的正确写法

原始草稿里把真实密钥直接写进 TOML，这种方式不应该继续使用。官方给出的思路是：

1. 如果底层仍然使用 OpenAI 身份认证，就设置 `requires_openai_auth = true`。
2. 如果底层需要单独的 provider key，就设置 `env_key = "YOUR_ENV_VAR"`。
3. `wire_api` 目前只支持 `responses`。

### 场景一：代理后端仍然走 OpenAI 登录

```toml
model = "gpt-5.3-codex"
model_provider = "proxy-openai"

[model_providers.proxy-openai]
name = "OpenAI Proxy"
base_url = "https://your-proxy.example.com/v1"
wire_api = "responses"
requires_openai_auth = true
```

这种写法的重点是：既然已经使用 OpenAI 认证，就不要再写 `env_key`，因为官方文档明确说明 `requires_openai_auth = true` 时会忽略 `env_key`。

### 场景二：第三方兼容端点使用环境变量认证

```toml
model = "gpt-5.3-codex"
model_provider = "compatible-api"

[model_providers.compatible-api]
name = "Compatible API"
base_url = "https://api.example.com/v1"
wire_api = "responses"
env_key = "COMPATIBLE_API_KEY"
env_key_instructions = "export COMPATIBLE_API_KEY=..."
```

这里的 `env_key` 写的是环境变量名，不是密钥本身。

## 常用方法

Codex 真正常用的不是“装完能启动”，而是下面这些操作。

### 进入交互式会话

最常见的用法就是直接启动：

```bash
codex
```

如果启动时顺便给一句任务，也可以这样写：

```bash
codex "Explain this repository structure"
```

### 附带图片一起提问

CLI 支持把截图或设计图一起传给 Codex：

```bash
codex -i screenshot.png "Explain this error"
```

多张图片也可以一起传：

```bash
codex -i img1.png -i img2.jpg "Summarize these diagrams"
```

### 查询最新网页信息

官方文档说明，Codex CLI 默认可以使用缓存搜索；如果你需要最新信息，可以显式开启 live web search：

```bash
codex --search "Check the latest release notes for this library"
```

### 非交互脚本化运行

如果要把 Codex 接进脚本或流水线，核心命令是 `codex exec`：

```bash
codex exec "summarize the repo structure"
```

如果下游程序要消费结构化事件流，可以输出 JSON Lines：

```bash
codex exec --json "summarize the repo structure" | jq
```

还可以用 JSON Schema 限定最终输出格式，这对自动化很实用。

### 续跑上一次任务

非交互任务跑到一半后，如果你想接着上一轮继续做，可以使用 `resume`：

```bash
codex exec "review the change for race conditions"
codex exec resume --last "fix the race conditions you found"
```

### Git 仓库保护

官方文档说明，`codex exec` 默认要求在 Git 仓库内运行，以降低误操作风险。只有在你明确知道环境安全时，才建议跳过这个检查：

```bash
codex exec --skip-git-repo-check "summarize files in this directory"
```

### 交互模式下最值得记住的 slash commands

下面这些命令最常用：

- `/model`：切换模型和推理强度。
- `/plan`：先让 Codex 给出计划，再决定是否进入执行。
- `/permissions`：动态调整当前会话的审批和权限级别。
- `/review`：让 Codex 检查当前工作区改动，优先指出风险和遗漏测试。
- `/diff`：查看当前工作树的变更。
- `/mcp`：检查本次会话可用的 MCP 工具。
- `/status`：查看当前模型、权限、上下文容量等状态。
- `/theme`：切换终端高亮主题。

## 一个更稳妥的使用建议

如果你刚开始用 Codex，建议先采用下面这套组合：

```toml
model = "gpt-5.5"
model_reasoning_effort = "medium"
approval_policy = "on-request"
sandbox_mode = "workspace-write"
web_search = "cached"
```

这套配置的特点是：

- 模型能力足够强。
- 推理强度不过高，响应速度更平衡。
- 允许写工作区，但不会默认放开整台机器。
- 大部分危险动作仍然会停下来让你确认。

等你熟悉自己的工作流后，再去细调 `plan_mode_reasoning_effort`、`review_model`、`profiles` 和自定义 provider。

## 参考链接

- [Codex CLI 官方总览](https://developers.openai.com/codex/cli)
- [Codex Authentication](https://developers.openai.com/codex/auth)
- [Config basics](https://developers.openai.com/codex/config-basic)
- [Configuration Reference](https://developers.openai.com/codex/config-reference)
- [Sample Configuration](https://developers.openai.com/codex/config-sample)
- [CLI Features](https://developers.openai.com/codex/cli/features)
- [Command line options](https://developers.openai.com/codex/cli/reference)
- [Slash commands](https://developers.openai.com/codex/cli/slash-commands)
- [Non-interactive mode](https://developers.openai.com/codex/noninteractive)