Codex CLI 安装、配置、使用与认证指南

Codex CLI 是 OpenAI 推出的本地化 AI 编程助手，在终端中运行，可读写与执行你指定目录下的代码。它开源、使用 Rust 编写，支持 macOS、Linux，Windows 为实验性支持。

一、简介与特点

开源：代码在 openai/codex，使用 Rust 编写，注重性能
本地运行：在终端中运行，可读取、修改并执行本机指定目录下的代码
全屏 TUI：提供终端全屏界面，便于实时查看操作、编辑与命令执行
与 ChatGPT 订阅绑定：随 ChatGPT Plus、Pro、Business、Edu、Enterprise 方案包含；也可使用 API Key 按量计费
多模态：支持附带截图或设计图（-i）作为输入
MCP 支持：支持 Model Context Protocol，可接入第三方工具与上下文
审批模式：可配置在执行命令或编辑前的审批策略（untrusted / on-request / never）
沙箱：可限制模型生成命令的权限（read-only / workspace-write / danger-full-access）

二、安装

系统要求

macOS、Linux 为正式支持
Windows 为实验性支持，建议在 WSL 中使用以获得更好体验

安装方式

bash

# npm 全局安装
npm install -g @openai/codex

# Homebrew（macOS / Linux）
brew install codex
# 或
brew install --cask codex

也可从 GitHub Releases 下载对应平台的二进制（macOS Apple Silicon/x86_64、Linux x86_64/arm64）。

登录 / 认证

安装后首次使用需完成认证：

bash

# 使用 ChatGPT 账号登录（推荐，与 Plus/Pro/Business/Edu/Enterprise 订阅关联）
codex login
# 选择 "Sign in with ChatGPT" 并按提示在浏览器中完成

# 或使用 API Key（按 API 定价计费，无订阅额度）
export OPENAI_API_KEY="your-api-key"
# 也可在项目根目录 .env 中设置 OPENAI_API_KEY，CLI 会自动读取

三、认证方式

与 ChatGPT Plus、Pro、Team、Edu、Enterprise 等订阅关联，使用各方案所包含的 Codex 额度
无需单独管理 API Key，在 CLI 中执行 codex login 并选择「Sign in with ChatGPT」完成 OAuth 即可
可在 Codex 用量页查看当前额度与用量

方式二：API Key

适合仅需按量使用、不依赖 ChatGPT 订阅的场景
设置环境变量 OPENAI_API_KEY，或在项目根目录 .env 中配置
按 OpenAI API 定价计费，无固定订阅额度；不包含云端 Code Review、Slack 等集成功能

四、基本使用

交互模式（TUI）

bash

# 启动交互式终端界面
codex

# 带初始指令启动
codex "为这个项目添加单元测试"

# 附带图片（截图、设计稿等）
codex -i screenshot.png "根据截图实现这个界面"

模型与推理

默认可使用 GPT-5.3-Codex 等模型；在 TUI 中通过 /model 切换模型或调整推理档位
命令行覆盖：codex --model gpt-5.3-codex "你的提示"

非交互模式（脚本 / 自动化）

bash

# 单次任务，流式输出到 stdout 或 JSONL
codex exec "列出并简要说明 src 目录下的所有 TypeScript 文件"

# 从 stdin 读入提示
echo "添加 README 章节：安装说明" | codex exec -

# 别名
codex e "你的提示"

会话恢复与分支

bash

# 恢复最近一次会话
codex resume
codex resume --last

# 按会话 ID 恢复
codex resume <session-id>

# 从某次会话 fork 出新会话（保留原对话，新开分支）
codex fork

常用子命令速览

命令	说明
`codex`	启动交互 TUI，可选初始提示或 -i 图片
`codex exec` / `codex e`	非交互执行单次任务
`codex login`	使用 ChatGPT 或 API Key 登录
`codex logout`	清除本地认证信息
`codex resume`	恢复历史会话
`codex fork`	从当前会话 fork 出新会话
`codex apply` / `codex a`	将 Codex Cloud 任务生成的最新 diff 应用到本地
`codex completion`	生成 Shell 补全（Bash/Zsh/Fish/PowerShell）
`codex features`	查看/启用/禁用功能开关（写入 config.toml）
`codex mcp`	管理 MCP 服务器（列表、添加、删除、认证）

五、配置

配置文件位置

用户级：~/.codex/config.toml
项目级（受信任项目）：.codex/config.toml，可覆盖用户级配置

例如，以下是配置文件示例：

toml

model = "gpt-5.3-codex"
model_provider = "azure"
model_reasoning_effort = "medium"

[model_providers.azure]
name = "azure"
base_url = "https://ai-gateway.dmall.com/openai/v1"
env_key = "DMALL_API_KEY"
wire_api = "responses"

[projects."/Users/zhijunio/development/personal"]
trust_level = "trusted"

[mcp_servers.playwright]
args = ["@playwright/mcp@latest"]
command = "npx"

命令行覆盖

使用 --config / -c 临时覆盖配置项，例如：

bash

codex -c "model_provider=\"oss\"" "解释这段代码"
# 或
codex -c features.web_search=true

使用 --profile / -p 指定 ~/.codex/config.toml 中的配置 profile：

bash

codex -p my-profile

常用命令行选项

选项	说明
`--model, -m`	覆盖配置中的模型（如 gpt-5.3-codex）
`--sandbox, -s`	沙箱策略：read-only / workspace-write / danger-full-access
`--ask-for-approval, -a`	审批时机：untrusted / on-request / never
`--full-auto`	快捷：on-request + workspace-write，适合本地低摩擦使用
`--cd, -C`	指定工作目录
`--add-dir`	添加额外目录到上下文（可多次使用）
`--exclude`	排除路径模式（如 "*/.log"）
`--no-history`	禁用会话历史记录
`--json`	以 JSON 格式输出（非 TUI）
`--verbose`	显示详细日志

六、订阅与用量

订阅包含

ChatGPT Plus：包含基础 Codex CLI 使用权，每月有固定额度
ChatGPT Pro：更高额度与更多高级功能
ChatGPT Business / Enterprise：团队级管理、更高额度与 SLA

用量管理

在 Codex 用量页查看当前使用情况
API Key 方式按 OpenAI API 定价计费
超出订阅额度后，可选择升级订阅或切换到 API Key 按次计费

七、常见问题与排障

认证失败

确认网络连接正常，可访问 OpenAI 服务
检查 API Key 是否正确，且未过期
尝试重新执行 codex login 完成 OAuth 流程

模型调用失败

检查网络连接与代理设置
确认模型名正确，且当前订阅包含该模型
查看 Codex 用量是否已用尽

权限与沙箱

如需执行命令，确保沙箱策略设置为 workspace-write 或 danger-full-access
审批模式设置为 never 可提高流畅度，但降低安全性

性能优化

对于大型项目，使用 --exclude 排除无关目录
调整 model_reasoning_effort 平衡速度与质量
本地缓存模型可提高响应速度（需额外配置）

八、高级功能

MCP 集成

通过 MCP（Model Context Protocol）接入第三方工具：

bash

# 添加 MCP 服务器
codex mcp add playwright npx @playwright/mcp@latest

# 列出已添加的 MCP 服务器
codex mcp list

自定义工具

在配置文件中定义自定义工具：

toml

[tools.my_tool]
name = "My Tool"
description = "执行自定义操作"
command = "python"
args = ["/path/to/tool.py"]

批量操作

结合 shell 命令实现批量处理：

bash

# 对多个文件执行相同操作
for file in src/*.ts; do
  codex exec "优化 $file 的性能"
 done

九、总结

Codex CLI 是一个强大的本地 AI 编程助手，通过终端提供代码理解、生成与执行能力。它既可以与 ChatGPT 订阅绑定使用，也可以通过 API Key 按量计费。合理配置沙箱策略与审批模式，可在安全性与流畅度之间取得平衡。

通过本文的指南，你应该能够成功安装、配置并使用 Codex CLI，提升编程效率。

Codex CLI 安装、配置、使用与认证指南 ​

一、简介与特点 ​

二、安装 ​

系统要求 ​

安装方式 ​

登录 / 认证 ​

三、认证方式 ​

方式一：Sign in with ChatGPT（推荐） ​

方式二：API Key ​

四、基本使用 ​

交互模式（TUI） ​

模型与推理 ​

非交互模式（脚本 / 自动化） ​

会话恢复与分支 ​

常用子命令速览 ​

五、配置 ​

配置文件位置 ​

命令行覆盖 ​

常用命令行选项 ​

六、订阅与用量 ​

订阅包含 ​

用量管理 ​

七、常见问题与排障 ​

认证失败 ​

模型调用失败 ​

权限与沙箱 ​

性能优化 ​

八、高级功能 ​

MCP 集成 ​

自定义工具 ​

批量操作 ​

九、总结 ​

Codex CLI 安装、配置、使用与认证指南

一、简介与特点

二、安装

系统要求

安装方式

登录 / 认证

三、认证方式

方式一：Sign in with ChatGPT（推荐）

方式二：API Key

四、基本使用

交互模式（TUI）

模型与推理

非交互模式（脚本 / 自动化）

会话恢复与分支

常用子命令速览

五、配置

配置文件位置

命令行覆盖

常用命令行选项

六、订阅与用量

订阅包含

用量管理

七、常见问题与排障

认证失败

模型调用失败

权限与沙箱

性能优化

八、高级功能

MCP 集成

自定义工具

批量操作

九、总结