Add agent tool installation notes

2026-05-26 21:34:00 +08:00
parent 51cc6b29d6
commit f964a7b112
3 changed files with 572 additions and 0 deletions
@@ -0,0 +1,408 @@
+---
+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)