409 lines
12 KiB
Markdown
409 lines
12 KiB
Markdown
---
|
||
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)
|