--- title: "Codex CLI 入门" wiki: cli category: "终端 Agent 工具" slug: codex-cli-overview url: https://learnagent.wiki/cli/cards/codex-cli-overview tags: ["Codex CLI", "OpenAI", "终端 Agent", "CLI", "入门"] last_updated: 2026-04-22 reading_time: 14 --- > Codex CLI 是 **OpenAI 在 2025 年重新启用 "Codex" 这块招牌之后做出来的官方终端 Agent**——一个跑在你本地终端里、由 GPT 系列模型驱动、能读你代码、能改你文件、能跑你命令的轻量编码助手。它的官方一句话定位是 "Lightweight coding agent that runs in your terminal"。截至 2026-04-20 的最新发布版本是 **0.122.0**，仓库地址 ，采用 **Apache-2.0 开源协议**。 # Codex CLI 入门 ## 基础概念 Codex CLI 是 **OpenAI 在 2025 年重新启用 "Codex" 这块招牌之后做出来的官方终端 Agent**——一个跑在你本地终端里、由 GPT 系列模型驱动、能读你代码、能改你文件、能跑你命令的轻量编码助手。它的官方一句话定位是 "Lightweight coding agent that runs in your terminal"。截至 2026-04-20 的最新发布版本是 **0.122.0**，仓库地址 ，采用 **Apache-2.0 开源协议**。 写这张卡之前要做的第一件事，就是把 "Codex" 这个名字的两段历史拆清楚，否则后面看文档容易越看越糊涂： - **2021 年的 Codex**：那是一个**模型**，名字叫 `code-davinci-002` / `code-cushman-001`，是 GPT-3 的代码微调分支，被 GitHub Copilot 第一代用来做补全。**这个模型在 2023 年 3 月被 OpenAI 全面下线**。后续历史上有过一个由微软维护的 `microsoft/Codex-CLI`，本质就是个把自然语言翻译成 shell 命令的小工具，依赖那个老模型，老模型一停服它也就跟着废了。 - **2025 年起的 Codex**：**这是一条全新的产品线**，由 OpenAI 自己出品，包含 **Codex CLI（本地终端）、Codex IDE 扩展（VS Code/Cursor/JetBrains）、Codex Cloud（云端 Agent）和 ChatGPT 里的 Codex 入口**四个形态。底层默认走的是 GPT-5 系列里专为编码训练的变体（**GPT-5.3-Codex** 是 2026-04 的主力，研究预览版还有更快的 **GPT-5.3-Codex-Spark**，>1000 tokens/s、128K 上下文）。本文讲的就是这一脉的 CLI。 老 Codex 是"模型"，新 Codex 是"产品系列里的终端 Agent"——**同名不同物**，这是这张卡要先帮你立起来的第一道篱笆。 ### 核心能力 | 能力 | 说明 | |------|------| | **代码读写** | 读取项目文件、跨文件改动、补丁式修改，自动生成 diff 让你审 | | **命令执行** | 在沙箱内跑测试、构建、迁移脚本等命令，受 approval policy 控制 | | **MCP 客户端** | 0.121.0 起原生支持 MCP，可挂第三方 server，扩展工具生态（与 [/mcp/cards/what-is-mcp](/mcp/cards/what-is-mcp) 互链） | | **Skills** | 通过仓库或用户目录里的 `.codex/skills` 注册可被 Agent 自主发现的"技能包" | | **Hooks** | 支持 SessionStart 等生命周期钩子，能区分 `/clear` 与全新启动 | | **Plan Mode** | 先想清楚再动手的规划模式，可携带规划上下文进入执行阶段 | | **TUI 多会话** | `/side` 在主对话外开一条侧边对话临时问问题，主任务不被打断 | ### 在 OpenAI 生态里的位置 ```mermaid graph TB subgraph Codex["OpenAI Codex 产品线（2025+）"] CLI[Codex CLI
跑在你终端里] IDE[Codex IDE 扩展
VS Code / Cursor / JetBrains] Cloud[Codex Cloud
云端长任务 Agent] ChatGPT[ChatGPT 里的 Codex 入口
桌面 / 网页] end Auth[ChatGPT 账号 或 OpenAI API Key] Models[GPT-5.3-Codex / GPT-5.3-Codex-Spark
等 Codex 优化变体] CLI --> Auth IDE --> Auth Cloud --> Auth ChatGPT --> Auth Auth --> Models User[开发者] --> CLI User --> IDE User --> ChatGPT User -. 委托长任务 .-> Cloud ``` 要点有三个： - **认证可共用**：CLI 默认就是 "Sign in with ChatGPT"，Plus/Pro/Business/Edu/Enterprise 任意一档订阅都可以直接用，不一定要单独开 API Key。 - **形态各管一段**：CLI 管"我现在就要在这个仓库里改代码"，IDE 管"我希望补全和编辑器联动"，Cloud 管"我要把一个长任务丢出去自己跑"，ChatGPT 桌面里的 Codex 则更像产品化入口。 - **模型同源**：四种形态背后是同一组 Codex 优化模型，所以体验是一致的，只是 UI 和触达方式不同。 ## 基础用法 ### 安装 CLI 提供了多种安装方式，按你常用的包管理器选一个即可： ```bash # 方式一：npm（最常见，跨平台） npm install -g @openai/codex # 方式二：macOS Homebrew brew install --cask codex # 方式三：直接下二进制（macOS / Linux x86_64 / arm64 都有） # 见 https://github.com/openai/codex/releases ``` 装完之后在终端里跑 `codex --version` 应该能看到类似 `0.122.0` 的输出。 ### 登录 最简单的路径是**用 ChatGPT 账号登录**，不需要去翻 API Key： ```bash codex login # 浏览器会自动打开 OpenAI 登录页 # 登录完成后 token 会写入 ~/.codex/auth.json ``` 如果你是企业用户、想用 API Key 计费，也可以走 API Key 模式： ```bash export OPENAI_API_KEY="sk-..." codex login --api-key ``` ### 最小示例 进入任意一个项目目录，直接敲 `codex`： ```bash cd ~/projects/my-app codex ``` 第一次启动会问你这个目录是否信任、是否允许写入。进入主界面后是一个 TUI，默认状态下你可以这样用： ```text > 帮我看一下 src/server.ts 里 listen 的端口是从哪里读的， 如果是硬编码就改成从环境变量 PORT 读，并加默认值 3001。 [Codex 列出待执行计划] 1. 读 src/server.ts 2. 找 listen 调用 3. 修改为从 process.env.PORT 读取，默认值 3001 4. 跑 npm run typecheck 验证 [审批待执行操作？] y/n ``` 按 `y` 之后 Codex 就会按计划读文件、生成 patch、跑命令，每一步都展示给你看。这套"读 → 改 → 跑 → 反馈"的循环就是终端 Agent 的标准工作模式。 ### 配置文件 Codex 的核心配置在 `~/.codex/config.toml`，项目级覆盖放在仓库根的 `.codex/config.toml`。一个最小配置示例： ```toml # ~/.codex/config.toml # 模型与默认行为 model = "gpt-5.3-codex" approval_policy = "on-request" # untrusted / on-request / never / granular sandbox_mode = "workspace-write" # 默认沙箱：可读项目，写入限定在 workspace，无网络 # 挂一个 MCP server（这里以本地 filesystem 为例） [mcp_servers.filesystem] command = "npx" args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/notes"] ``` 三个最常调的开关： - **`approval_policy`**：`untrusted` 只让已知安全的只读命令自动跑、其它都问；`on-request` 是默认，由模型判断什么时候该问；`never` 全部不问（高危，仅在隔离环境用）；`granular` 提供更细粒度白名单。 - **`sandbox_mode`**：默认 `workspace-write`，对 workspace 外只读、网络默认关闭，需要联网拉依赖时单独打开。 - **`mcp_servers.*`**：声明要挂载的 MCP server，CLI 启动时拉起对应进程并接管通信，工具列表会出现在 Codex 的可用工具菜单里。详见 [MCP 是什么](/mcp/cards/what-is-mcp) 和 [在 CLI 里挂 MCP server](/cli/cards/configure-mcp-in-cli)。 ## 同类工具对比 把 Codex CLI 放到 2026 年的终端 Agent 战场里横向看： | 维度 | Codex CLI | Claude Code | Gemini CLI | |------|-----------|-------------|------------| | 出品方 | OpenAI（官方） | Anthropic（官方） | Google（官方） | | 默认模型 | GPT-5.3-Codex / Spark | Claude 4.x 系列 | Gemini 2.x 系列 | | 是否多模型可切 | ⚠️ 主推自家 GPT，可对接 OpenAI 兼容 endpoint | ⚠️ 主推 Claude | ⚠️ 主推 Gemini | | 计费来源 | ChatGPT 订阅 / API Key | Claude Pro/Max / API Key | Google AI 订阅 / API Key | | 开源协议 | Apache-2.0 | 闭源（仓库是 issue tracker） | Apache-2.0 | | MCP 支持 | ✅ 原生（0.121.0+） | ✅ 原生 | ✅ 原生 | | Skills 机制 | ✅ `.codex/skills` | ✅ `.claude/skills` | ⚠️ 演进中 | | Hooks 机制 | ✅ SessionStart 等 | ✅ PreToolUse / PostToolUse / Stop 等 | ⚠️ 演进中 | | Sandbox / 权限 | workspace-write 默认 + 网络开关 | 工具白名单 + dangerous 模式 | 工具白名单 | | 上手难度 | 低 | 低 | 低 | **核心区别一句话**： - **Codex CLI** 适合"已经在用 ChatGPT、想把同一套账号扩到终端"的人，模型上限跟 OpenAI 主线版本同步快。 - **Claude Code** 适合追求 Anthropic 长上下文 + 严肃工程能力（hooks、skills、子 agent 生态都最成熟）。 - **Gemini CLI** 适合 Google Cloud / Workspace 重度用户，上下文窗口和价格是它的牌面。 三个工具的差别，本质上不是"哪个更强"，而是"你被绑在哪个生态、你愿意为什么付钱、你对工程化扩展性的要求有多高"。详见 [终端 Agent 横向对比](/cli/cards/terminal-agents-comparison)。 ## 常见误区 | 误区 | 准确理解 | |------|----------| | Codex CLI 就是 2021 年那个 Codex 的命令行版 | **完全无关**。2021 年的 Codex 是一个被 2023 年 3 月下线的代码模型，2025 年 OpenAI 复用了 "Codex" 这个名字命名一条新的 Agent 产品线，CLI 是其中一员，底层走 GPT-5 系列 | | Codex CLI 必须先去 OpenAI 平台开 API Key 才能用 | 默认推荐"Sign in with ChatGPT"，任何 ChatGPT 付费档（Plus/Pro/Business/Edu/Enterprise）都能直接用；API Key 是给企业计费 / 自动化场景准备的 | | Codex CLI 只能用 OpenAI 的模型 | 主推自家 GPT-5.3-Codex，不过它接受 OpenAI 兼容的 base URL，理论上能对接其它兼容厂商。但官方功能（Skills、Plan Mode 等）是为 Codex 系列调教的，换底座体验会打折 | | Codex CLI 是闭源产品 | 仓库 `openai/codex` 是 **Apache-2.0 开源**，代码、issue、release notes 都在 GitHub 上公开 | | Codex CLI 等于 ChatGPT 桌面版的命令行包装 | 两者认证可共用，但**形态完全不同**：CLI 是跑在终端里的本地 Agent，能直接读你工作区的文件、跑沙箱命令；ChatGPT 桌面里的 Codex 入口更偏对话式入口 + 云端任务 | | Codex CLI 不支持 MCP，只能用自家工具 | 0.121.0 起原生支持 MCP，可在 `~/.codex/config.toml` 里 `[mcp_servers.*]` 声明任意 MCP server，工具会自动并入 Agent 可用列表 | | Skills、Hooks 是 Claude Code 独有的 | Codex CLI 也有自己的 Skills（`.codex/skills`）和生命周期 Hooks（如 SessionStart），但具体规范和 Claude Code 不通用，写之前要看 OpenAI 自己的 docs | ## 优劣势分析 | 优势 | 劣势 | |------|------| | **OpenAI 官方第一方维护**，模型升级（GPT-5.3-Codex / Spark）几乎当天就能在 CLI 里用上，不用等社区适配 | **生态绑定 OpenAI 较深**，主流功能为自家模型调教，多模型切换是次等公民 | | **认证体验顺**：直接 Sign in with ChatGPT，省掉 API Key 申请、计费配置、组织管理一整套流程 | **沙箱与权限模型相对年轻**：相比 Claude Code 已经迭代多轮的 hooks/skills/dangerous 模式，Codex 这部分仍在快速变化，文档跟代码偶尔有时差 | | **Apache-2.0 完全开源**，能自己 fork 改 TUI、改 telemetry、加 hook，企业内审也容易过 | **MCP 支持虽然有但偏新**：0.121.0 才算稳定（2026 年 4 月），早期写的 server 可能踩到行为差异，需要自己测一遍 | | **跨平台二进制完备**：macOS / Linux x86_64 / arm64 都有，npm/brew 装包都不挑机器 | **TUI 体验在 Windows 原生终端略弱**，Windows 用户当前体验最好的是 WSL + 标准 Linux 包，纯 PowerShell 偶有渲染问题 | | **Plan Mode + /side 多会话**让"先想清楚再做"和"侧边问个小问题别打断主任务"两类常见痛点都有原生支持 | **强项偏编码**，做长链路文档生成、产品需求拆解时不一定比通用 ChatGPT 桌面更顺手 | | **GPT-5.3-Codex-Spark 提供 >1000 tokens/s 的低延迟体验**，做实时补全/快速审查特别舒服 | **成本控制需要自己上心**：默认开 ChatGPT 订阅时不显式按 token 计费，但企业 API Key 模式下，Agent 模式很容易跑出比预期更高的账单 | ## 思考题
初级：如果只用过 ChatGPT 网页版，为什么还要装一个 Codex CLI？两者解决的问题不一样在哪？ **参考答案：** ChatGPT 网页版解决的是**"我有一个问题，想找模型聊聊"**——你打开一个对话窗口，复制粘贴代码、贴报错、贴需求，模型回你一段答复，然后你再把答复手动搬回到 IDE 里执行。整个回路里**模型不直接接触你的项目**，你是中间那个"传话+执行"的人。 Codex CLI 解决的是**"我有一个项目，想让模型直接动手"**——你在项目根目录敲 `codex`，模型可以： 1. **直接读你的源代码**（不用复制粘贴） 2. **直接修改文件**（生成 diff，你审批后落盘） 3. **直接跑命令**（在沙箱里跑测试、构建、git） 4. **看到执行结果**，自动判断下一步 这就是 "Agent" 这个词的核心：**模型从被动应答升级成主动操作环境**。CLI 把"读项目—想方案—改文件—跑测试—看结果"的整条循环压进终端里，省掉的是你作为"中间人"的搬运成本。 一个直观的判断：如果你一天里 **超过 3 次** 把代码贴进 ChatGPT 又把回答贴回 IDE，那装个 Codex CLI 至少能省你一半时间。
中级：Codex CLI 已经支持 MCP 了，那它和"挂在 ChatGPT 桌面里的 MCP server"是同一回事吗？同一个 MCP server 能不能两边复用？ **参考答案：** **底层协议是同一回事，但运行环境和能力面不完全相同**，所以"复用"要分两层看。 **协议层**：MCP 是开放协议（详见 [MCP 是什么](/mcp/cards/what-is-mcp)），消息格式是 JSON-RPC 2.0，传输层是 stdio 或 Streamable HTTP。一个写好的 MCP server——比如 `@modelcontextprotocol/server-filesystem`——理论上**Codex CLI、ChatGPT 桌面、Claude Desktop、Cursor 都能挂**，server 端代码不用改。所以协议层是可复用的。 **配置层**：每个客户端有自己的配置位置和写法。 - Codex CLI：`~/.codex/config.toml` 里的 `[mcp_servers.]` 段 - ChatGPT 桌面：在桌面应用的设置面板里挂载（具体路径随版本变化） - Claude Desktop：`claude_desktop_config.json` 的 `mcpServers` 段 同一个 server，不同客户端要写一份对应格式的"挂载声明"。 **能力层**：客户端对 MCP 的支持度有差别。比如： - 有的客户端只支持 stdio，不支持 streamable HTTP； - 有的客户端对 sampling、elicitation 这类反向调用支持得好，有的还没有； - 不同客户端的工具白名单 / 权限审批流程也不一样。 **实操结论**：你写的 MCP server 本身是高度可复用的，挂三个客户端基本就是配三份小配置。但**别假设客户端 A 能跑通的高级能力，到客户端 B 也一定能跑**——尤其是反向 sampling、长会话生命周期、二进制 resource 这类边缘能力，先在每个客户端单测一遍。 更深入的部分见 [在 CLI 里挂 MCP server](/cli/cards/configure-mcp-in-cli) 与 [MCP 架构](/mcp/cards/mcp-architecture)。
## 参考资料 1. OpenAI Codex CLI 仓库 README：（查询日期 2026-04-22） 2. Codex CLI Releases（含 0.122.0 发布说明）：（查询日期 2026-04-22） 3. Codex 官方文档主站：（查询日期 2026-04-22） 4. Codex Configuration Reference：（查询日期 2026-04-22） 5. Codex MCP 文档：（查询日期 2026-04-22） 6. Codex Changelog：（查询日期 2026-04-22） 7. OpenAI 官方公告 - Introducing GPT-5.3-Codex：（查询日期 2026-04-22） 8. OpenAI 旧 Codex 模型下线说明（历史背景）：（查询日期 2026-04-22） --- *Source: https://learnagent.wiki/cli/cards/codex-cli-overview* *Markdown mirror of https://learnagent.wiki, served as text/markdown for LLM ingestion.*