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 中使用以获得更好体验

安装方式

# 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）。

登录 / 认证

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

# 使用 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 会自动读取

三、认证方式

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

与 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）

# 启动交互式终端界面
codex

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

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

模型与推理

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

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

# 单次任务，流式输出到 stdout 或 JSONL
codex exec "列出并简要说明 src 目录下的所有 TypeScript 文件"
# 从 stdin 读入提示
echo "添加 README 章节：安装说明" | codex exec -

# 别名
codex e "你的提示"

会话恢复与分支

# 恢复最近一次会话
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，可覆盖用户级配置

例如，以下是我的配置文件，DMALL_API_KEY 在环境变量中定义：

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/chensoul/development/personal"]
trust_level = "trusted"

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

命令行覆盖

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

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

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

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`	为 agent 授予额外可写目录（可多次指定）
`--search`	开启实时网页搜索（默认多为 cached）
`--oss`	使用本地开源模型（需已运行 Ollama）

AGENTS.md：项目级说明

在仓库或目录中放置 AGENTS.md（或 AGENTS.override.md），Codex 会在开始任务前读取，用于约定项目规范、构建命令、评审期望等。

发现顺序：从项目根到当前目录逐级合并，近者覆盖远者；全局可用 ~/.codex/AGENTS.md
建议：目录级说明、代码规范、常用构建/测试命令、常见反馈（避免重复犯错）
详见 Custom instructions with AGENTS.md。

MCP（Model Context Protocol）

通过 MCP 为 Codex 接入外部工具与数据源。

配置：在 ~/.codex/config.toml 或 .codex/config.toml 中配置 [mcp_servers.*]；或使用 codex mcp add <name> -- <command> 添加
类型：支持 STDIO（本地进程）与 Streamable HTTP（远程），支持 OAuth 认证
策略：可用 enabled_tools / disabled_tools、tool_timeout_sec、startup_timeout_sec 等控制
详见 Codex MCP。

六、Slash 命令（TUI 内）

在交互界面的输入框中输入 / 可调出斜杠命令列表，输入命令名可过滤。常用命令如下：

命令	用途
`/model`	切换当前模型或推理档位（如 gpt-4.1-mini、gpt-5.3-codex）
`/permissions`	设置审批策略（如 Auto、Read Only），决定 Codex 在未询问前可执行的操作
`/personality`	设置回复风格（friendly / pragmatic / none），不改变任务内容
`/diff`	查看工作区 Git diff，含未暂存与未跟踪文件
`/status`	查看会话配置、当前模型、审批策略、可写目录及 token 用量/限额
`/compact`	将当前对话总结为简短摘要，释放上下文窗口，适合长会话后使用
`/plan`	切换到计划模式，可先让 Codex 提出执行计划再动手改代码
`/review`	请 Codex 对当前工作区做代码审查（行为变更、缺失测试等）
`/new`	在同一 CLI 会话内开启新对话，清空当前上下文
`/resume`	从已保存会话列表中恢复某次对话
`/fork`	将当前对话 fork 为新线程，保留原对话，便于尝试不同方案
`/agent`	切换当前活动的 agent 子线程（多 agent 时）
`/mention`	将指定文件或目录加入对话（如 `/mention src/lib/api.ts`）
`/mcp`	列出当前已配置的 MCP 工具，确认 Codex 可调用的外部能力
`/apps`	浏览并插入 App（连接器）到输入框，以 `$app-slug` 形式让 Codex 使用
`/init`	在当前目录生成 AGENTS.md 脚手架，便于写入持久化项目说明
`/experimental`	开关实验功能（如多 agent），修改会写入 config 并在重启后生效
`/statusline`	交互式配置 TUI 底部状态栏显示项（模型、上下文、限额、git、token 等），并写入 config.toml
`/debug-config`	输出配置层级与策略诊断，便于排查与 config.toml 不一致的原因
`/ps`	查看实验性后台终端列表及其最近输出（需启用 unified_exec）
`/sandbox-add-read-dir`	为沙箱授予某目录的读权限（仅 Windows 原生运行时可用）
`/feedback`	提交日志或诊断信息给 Codex 维护者
`/logout`	登出并清除本地认证信息
`/quit` / `/exit`	退出 CLI（二者等价；退出前请保存或提交重要修改）

说明：/approvals 仍可作为别名使用，但已不在斜杠列表中显示。

七、订阅与用量

与 ChatGPT 方案的关系

Codex 随以下 ChatGPT 方案包含（具体以官网为准）。Free、Go 不包含 Codex，仅 Plus 及以上可用；偶有限时活动时 Free/Go 可能可体验，以官网为准。

ChatGPT Plus：Codex 在网页、CLI、IDE 扩展及 iOS 可用；含一定量本地消息与云端任务、Code Review 等
ChatGPT Pro：更高额度、优先处理、GPT-5.3-Codex-Spark 等
ChatGPT Business / Edu / Enterprise：团队管理、SSO、审计、数据保留等，Enterprise/Edu 可有弹性额度（credits）

使用 API Key 时：仅按 OpenAI API 定价计费，无 ChatGPT 订阅所含的云端 Code Review、Slack 等集成。

订阅方案与价格（参考）

Codex 随 ChatGPT 以下方案包含，价格以 ChatGPT 定价页为准，下表为常见参考：

方案	价格（约）	说明
ChatGPT Free	Free
ChatGPT Go	$8/月	不包含 Codex；仅有更多消息、上传、记忆等。
ChatGPT Plus	$20/月	含 Codex（网页、CLI、IDE、iOS）、高级推理、深度研究、代理等
ChatGPT Pro	$200/月	含 Plus 全部 + 更高 Codex 额度、优先处理、GPT-5.3-Codex-Spark 等
ChatGPT Business	$30/用户/月（年付均价）	含 Plus 能力 + 团队协作、60+ 集成、SAML SSO、合规等；Codex 包含
ChatGPT Enterprise	联系销售	按需报价，含 Business 全部 + 扩展上下文、SCIM/EKM/RBAC、数据驻留、SLA 等
ChatGPT Edu	联系销售或按校方	教育机构方案，Codex 包含，额度可能为 credits 制
仅用 API Key	按 API 定价按量计费	无订阅额度，无云端 Code Review / Slack 等集成

以上金额为美元、月费或年付折算，实际以官网与当地货币为准。

用量与限额（参考）

以下为文档中常见的每 5 小时本地消息 / 云端任务及每周 Code Review 的大致范围，实际以 Codex 定价页与用量仪表盘为准：

方案	本地消息 / 5h	云端任务 / 5h	Code Review / 周
ChatGPT Plus	约 45–225	约 10–60	约 10–25
ChatGPT Pro	约 300–1500	约 50–400	约 100–250
Business	约 45–225	约 10–60	约 10–25
Enterprise & Edu	按 credits，无固定上限	按 credits	按 credits
API Key	按 API 定价	不可用	不可用

本地消息与云端任务通常共享同一 5 小时窗口的额度；另有每周上限的可能
使用 GPT-5.1-Codex-Mini 做本地任务时，可获得更高倍数用量（约 4x），便于延长额度
达到限额后：Plus/Pro 可购买额外 credits；Business/Edu/Enterprise 弹性定价方案可购买 workspace credits；也可改用 API Key 继续使用并按 API 计费

节省用量的建议

日常小任务优先使用 GPT-5.1-Codex-Mini，延长额度
减少不必要的 MCP 服务器数量，不用时关闭
控制 AGENTS.md 体积，避免注入过多上下文
提示尽量精简、明确，减少单次请求消耗

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

一、简介与特点

二、安装

系统要求

安装方式

登录 / 认证

三、认证方式

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

方式二：API Key

四、基本使用

交互模式（TUI）

模型与推理

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

会话恢复与分支

常用子命令速览

五、配置

配置文件位置

命令行覆盖

常用命令行选项

AGENTS.md：项目级说明

MCP（Model Context Protocol）

六、Slash 命令（TUI 内）

七、订阅与用量

与 ChatGPT 方案的关系

订阅方案与价格（参考）

用量与限额（参考）

节省用量的建议

八、参考链接

订阅与分享

订阅更新，不错过后续文章

如果这篇有帮助，可以顺手转发

一、简介与特点

二、安装

系统要求

安装方式

登录 / 认证

三、认证方式

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

方式二：API Key

四、基本使用

交互模式（TUI）

模型与推理

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

会话恢复与分支

常用子命令速览

五、配置

配置文件位置

命令行覆盖

常用命令行选项

AGENTS.md：项目级说明

MCP（Model Context Protocol）

六、Slash 命令（TUI 内）

七、订阅与用量

与 ChatGPT 方案的关系

订阅方案与价格（参考）

用量与限额（参考）

节省用量的建议

八、参考链接

订阅与分享

订阅更新，不错过后续文章

如果这篇有帮助，可以顺手转发

相关文章