Codex CLI 安装与配置教程(含第三方API配置)

适用对象：希望在本地终端中使用 OpenAI Codex CLI，并需要理解安装、登录、配置、沙箱、审批策略、模型 provider 与 profile 切换机制的开发者。 校对依据：本文以本机 codex-cli 0.130.0 的 --help 输出，以及 OpenAI Codex 官方文档、OpenAI Codex 官方仓库为准。

Codex CLI 是 OpenAI 提供的本地命令行编程代理。它可以在项目目录中读取代码、修改文件、执行命令、运行测试，并通过审批策略与沙箱限制控制操作边界。当前 Codex CLI 使用 config.toml 作为主要配置文件，用户级配置路径通常为 ~/.codex/config.toml。

一、安装

Codex CLI 可通过 npm、Homebrew 或 GitHub Release 安装。官方仓库说明中，npm 是最直接的安装方式；macOS 和 Linux 也可以使用 Homebrew。

1. npm 安装

bash
npm install -g @openai/codexcodex --version

2. Homebrew 安装

bash
brew install --cask codexcodex --version

3. GitHub Release 二进制安装

适用于 Linux 服务器或不希望依赖 npm 的环境。到 OpenAI Codex GitHub Release 页面下载对应平台压缩包，解压后将可执行文件放入 PATH。

常见平台文件名示例：

• macOS Apple Silicon：codex-aarch64-apple-darwin.tar.gz
• macOS x86_64：codex-x86_64-apple-darwin.tar.gz
• Linux x86_64：codex-x86_64-unknown-linux-musl.tar.gz
• Linux arm64：codex-aarch64-unknown-linux-musl.tar.gz

bash
curl -LO "https://github.com/openai/codex/releases/latest/download/<release-file>.tar.gz"tar -xzf "<release-file>.tar.gz"chmod +x codex-*sudomv codex-* /usr/local/bin/codexcodex --version

文件名与打包格式会随版本和平台变化，实际操作时应以 Release 页面列出的 asset 名称为准。

二、登录与认证

首次运行：

bash
codex

Codex CLI 支持两类主要登录方式：

1. Sign in with ChatGPT
   ：通过浏览器完成登录，适合使用 ChatGPT Plus、Pro、Business、Edu 或 Enterprise 计划的用户，也是交互式使用的推荐方式。
2. API Key 登录
   ：适合脚本、CI/CD、自动化任务或希望按 OpenAI Platform API 用量计费的场景。

使用 API Key 时，可以通过标准输入写入：

bash
printenv OPENAI_API_KEY | codex login --with-api-key

如果已有 Codex access token，也可以通过标准输入写入：

bash
printenv CODEX_ACCESS_TOKEN | codex login --with-access-token

远程服务器或无浏览器环境可以使用 Device Code：

bash
codex login --device-auth

查看登录状态：

bash
codex login status

退出登录：

bash
codex logout

Codex 会缓存登录凭据。官方文档说明，凭据可存放在 ~/.codex/auth.json 或操作系统凭据存储中，具体位置可通过 cli_auth_credentials_store = "file" | "keyring" | "auto" 控制。使用文件存储时，应把 ~/.codex/auth.json 当作密码文件处理，不要提交、粘贴或分享。

三、配置文件与优先级

Codex 的用户级配置文件位于：

text
~/.codex/config.toml

项目级配置可放在仓库内：

text
.codex/config.toml

官方配置优先级从高到低为：

1. CLI 参数与 -c/--config 覆盖项；
2. --profile <name>
    指定的 profile；
3. 受信任项目中的 .codex/config.toml；
4. 用户级 ~/.codex/config.toml；
5. 系统级配置，例如 Unix 上的 /etc/codex/config.toml；
6. Codex 内置默认值。

项目级配置只会在受信任项目中加载。Codex 会从项目根目录到当前工作目录逐层查找 .codex/config.toml；越靠近当前工作目录的配置优先级越高。项目级配置不应存放密钥，只应存放模型、沙箱、审批、profile、规则等可共享设置。

一个常用的最小配置如下：

toml
model = "gpt-5.5"approval_policy = "on-request"sandbox_mode = "workspace-write"

常用字段说明：

on-failure 在当前 CLI 帮助中仍可见，但已标记为 deprecated。交互式使用通常采用 on-request；非交互自动化任务如果有外部隔离环境，可考虑 never。

四、常用运行方式

启动交互式 TUI：

bash
codex

带初始提示启动：

bash
codex "检查当前项目的测试失败原因"

非交互执行：

bash
codex exec"为当前模块补充单元测试"

从标准输入传入上下文：

bash
git diff | codex exec"审查这个 diff 的风险"

指定工作目录：

bash
codex --cd /path/to/project

允许额外可写目录：

bash
codex --add-dir /path/to/shared

临时覆盖模型：

bash
codex --model gpt-5.5

临时覆盖任意配置项：

bash
codex -c 'model_reasoning_effort="high"'

-c/--config 使用点号路径覆盖配置项，等号右侧会先按 TOML 解析；如果解析失败，才会作为原始字符串处理。例如：

bash
codex -c 'sandbox_permissions=["disk-full-read-access"]'codex -c shell_environment_policy.inherit=all

启用实时网页搜索：

bash
codex --search

配置文件中可用 web_search = "cached" | "live" | "disabled" 控制搜索模式。官方默认值是 cached，表示使用 OpenAI 维护的索引，不会实时抓取网页；--search 会启用实时网页搜索，并让模型可使用 Responses API 的 web_search 工具。

--dangerously-bypass-approvals-and-sandbox 会跳过审批和沙箱限制，只应在已经由容器、虚拟机或 CI 隔离的环境中使用。

五、沙箱与审批策略

沙箱控制 Codex 执行命令时能访问的资源范围。审批策略控制 Codex 何时向用户请求确认。

1. 沙箱模式

bash
codex --sandbox read-onlycodex --sandbox workspace-writecodex --sandbox danger-full-access

也可以写入配置文件：

toml
sandbox_mode = "workspace-write"

模式含义：

2. 审批策略

bash
codex --ask-for-approval on-request

也可以写入配置文件：

toml
approval_policy = "on-request"

常用取值：

官方配置参考还支持 granular approval policy，可分别控制沙箱提权、rules、MCP elicitation、request_permissions、skill 脚本审批等提示类别。普通用户通常不需要一开始就使用 granular 配置。

对于日常本地开发，较稳妥的组合是：

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

六、模型 Provider 配置

Codex 通过 model_provider 决定请求发往哪个模型服务。官方内置 provider 包括 openai，当前配置参考还保留了 ollama、lmstudio 等内置 provider 标识；内置 provider ID 不能被自定义配置覆盖。

自定义 provider 的基本结构如下：

toml
model = "gpt-5.5"model_provider = "example"[model_providers.example]name = "Example Provider"base_url = "https://example.com/v1"env_key = "EXAMPLE_API_KEY"wire_api = "responses"

字段说明：

需要特别注意：当前 OpenAI 官方配置参考将 wire_api 标为 responses，并说明这是唯一支持值。因此，只有 /v1/chat/completions 兼容而不支持 Responses API 的第三方服务，不能简单依赖 wire_api = "chat"。这类服务通常需要经过支持 Responses API 的代理网关、服务商适配层，或等待 Codex CLI 对其他 wire protocol 的正式支持。

1. OpenAI 官方 provider

使用 OpenAI 官方模型时，通常不需要显式配置 provider：

toml
model = "gpt-5.5"approval_policy = "on-request"sandbox_mode = "workspace-write"

如果经过企业代理或内部网关访问 OpenAI，并希望复用 Codex 的 OpenAI 登录凭据，可使用：

toml
model = "gpt-5.5"model_provider = "company-openai-proxy"[model_providers.company-openai-proxy]name = "Company OpenAI Proxy"base_url = "https://proxy.example.com/v1"requires_openai_auth = truewire_api = "responses"

当 requires_openai_auth = true 时，Codex 使用 OpenAI 认证信息，env_key 会被忽略。

2. 第三方或自建 Responses API provider

如果第三方服务或自建网关明确支持 Responses API，可采用如下配置：

toml
model = "provider/model-name"model_provider = "custom-responses"[model_providers.custom-responses]name = "Custom Responses Provider"base_url = "https://api.example.com/v1"env_key = "CUSTOM_RESPONSES_API_KEY"wire_api = "responses"request_max_retries = 4stream_max_retries = 5stream_idle_timeout_ms = 300000

Shell 中导出密钥：

bash
export CUSTOM_RESPONSES_API_KEY="your-api-key"codex

排查 provider 时，优先确认三件事：

1. base_url
    是否是 API 根地址，而不是完整 endpoint。
2. env_key
    指向的环境变量是否在当前 shell 中存在。
3. provider 是否真正支持 Responses API、流式输出、工具调用与模型所需参数。

3. 本地模型

当前 CLI 帮助提供了开源 provider 相关参数：

bash
codex --osscodex --oss --local-provider ollamacodex --oss --local-provider lmstudio

--oss 等价于使用开源模型 provider；--local-provider 可选择 ollama 或 lmstudio。配置文件中的对应字段是 oss_provider = "ollama" | "lmstudio"。如果使用本地模型，应先确保 Ollama 或 LM Studio 服务已启动，并确认模型具备足够的上下文窗口、工具调用能力和代码任务质量。对于需要大量文件修改的任务，本地小模型通常更适合作为轻量辅助，而不是复杂重构的唯一执行模型。

七、Profiles 一键切换配置

Profile 可以将常用配置组合固化到 config.toml 中。官方文档说明，profiles 仍属于实验能力，未来可能变化；CLI 支持 --profile，IDE 扩展当前不支持 profile。

示例：

toml
model = "gpt-5.5"approval_policy = "on-request"sandbox_mode = "workspace-write"[profiles.review]model = "gpt-5.5"model_reasoning_effort = "high"approval_policy = "untrusted"sandbox_mode = "read-only"[profiles.automation]model = "gpt-5.5"model_reasoning_effort = "medium"approval_policy = "never"sandbox_mode = "workspace-write"[profiles.custom-provider]model = "provider/model-name"model_provider = "custom-responses"approval_policy = "on-request"sandbox_mode = "workspace-write"

使用方式：

bash
codex --profile reviewcodex exec --profile automation "运行测试并修复失败用例"codex --profile custom-provider

也可以设置默认 profile：

toml
profile = "review"

八、完整配置示例

以下示例适合日常本地开发，并包含一个自定义 Responses API provider：

toml
# ===== 全局默认 =====model = "gpt-5.5"approval_policy = "on-request"sandbox_mode = "workspace-write"model_reasoning_effort = "medium"web_search = "cached"# ===== 自定义 provider：仅适用于明确支持 Responses API 的网关 =====[model_providers.custom-responses]name = "Custom Responses Provider"base_url = "https://api.example.com/v1"env_key = "CUSTOM_RESPONSES_API_KEY"wire_api = "responses"request_max_retries = 4stream_max_retries = 5stream_idle_timeout_ms = 300000# ===== 企业 OpenAI 代理：复用 OpenAI 登录凭据 =====[model_providers.company-openai-proxy]name = "Company OpenAI Proxy"base_url = "https://proxy.example.com/v1"requires_openai_auth = truewire_api = "responses"# ===== Profiles =====[profiles.review]model = "gpt-5.5"approval_policy = "untrusted"sandbox_mode = "read-only"model_reasoning_effort = "high"[profiles.custom]model = "provider/model-name"model_provider = "custom-responses"approval_policy = "on-request"sandbox_mode = "workspace-write"[profiles.proxy]model = "gpt-5.5"model_provider = "company-openai-proxy"approval_policy = "on-request"sandbox_mode = "workspace-write"

九、常用命令速查

十、故障排查

1. 无法读取 API Key

检查环境变量是否存在：

bash
printenv CUSTOM_RESPONSES_API_KEY

如果变量为空，应在启动 Codex 的同一个 shell 中导出：

bash
export CUSTOM_RESPONSES_API_KEY="your-api-key"

2. provider 返回 404

常见原因包括：

• base_url
   写成了完整接口路径，例如误写为 /v1/responses。
• 模型 ID 与 provider 实际模型名称不一致。
• provider 并不支持 Responses API。

3. wire_api = "chat" 不再受支持

如果启动 Codex 时出现如下错误：

text
Error loading config.toml: `wire_api = "chat"` is no longer supported.How to fix: set `wire_api = "responses"` in your provider config.in `model_providers.shubiaobiao.wire_api`

说明 ~/.codex/config.toml 中仍保留了旧版 provider 配置。需要将对应 provider 的 wire_api 改为 responses：

toml
[model_providers.shubiaobiao]name = "shubiaobiao"base_url = "https://api.shubiaobiao.com/v1"env_key = "SHUBIAOBIAO_API_KEY"wire_api = "responses"

如果该 provider 只兼容 /v1/chat/completions，仅修改 wire_api 可能仍无法正常工作。此时需要确认服务商是否提供 Responses API 兼容入口，或改用支持 Responses API 的代理网关。

4. provider 返回 401 或 403

常见原因包括：

• API Key 错误或过期。
• env_key
   指向的环境变量名写错。
• 服务商要求额外请求头或账号权限。
• 配置了 requires_openai_auth = true，但实际 provider 需要自有 API Key。

5. 工具调用异常

Codex 的编码能力依赖文件读写、命令执行和工具调用。如果第三方模型或网关不能正确处理工具调用，可能出现只生成文字、不修改文件、流式输出中断或参数格式错误等现象。应优先选择明确支持 Responses API 与工具调用的 provider。

6. 项目级配置未生效

Codex 只会加载受信任项目中的 .codex/config.toml。如果项目未被信任，项目级配置、hooks 与 rules 会被跳过。

7. 日志排查

TUI 日志通常位于：

text
~/.codex/log/codex-tui.log

查看实时日志：

bash
tail -F ~/.codex/log/codex-tui.log

临时提高日志级别：

bash
RUST_LOG=codex_core=debug codex

十一、建议实践

1. 日常本地开发使用 approval_policy = "on-request" 与 sandbox_mode = "workspace-write"。
2. 阅读代码或审查 diff 时使用只读 profile，例如 sandbox_mode = "read-only"。
3. CI/CD 或批量任务应优先运行在容器、虚拟机或受控 runner 中，再考虑 approval_policy = "never"。
4. 第三方 provider 接入前，先确认是否支持 Responses API、流式输出和工具调用。
5. 不要把 API Key 写入 config.toml，优先通过 env_key 从环境变量读取。
6. 对复杂任务建立多个 profile，例如 review、automation、custom，减少命令行临时参数。

参考资料

• OpenAI Codex 官方文档
• Codex CLI 官方仓库
• Codex 配置基础
• Codex 高级配置
• Codex 配置参考
• Codex 认证文档