fmxj
Codex CLI 完整使用指南：终端里的 AI 编码代理
fmxj Lv1
  2026-03-31 00:00:00   2026-04-25 06:12:58  

什么是 Codex CLI

Codex CLI 是 OpenAI 提供的终端式编码代理工具。它的核心价值不是”在终端里聊天”，而是进入本地项目后，读取上下文、执行命令、修改文件、查看 diff、继续迭代，并在必要时通过审批和沙箱控制风险。

如果只用一句话概括：

Codex CLI 是终端里的工程执行代理，而不是终端问答壳。

适合谁使用

  • 习惯在终端里工作的开发者
  • 需要在本地仓库里做真实改动的人
  • 需要脚本化、自动化、CI 集成的人
  • 想把项目规则、技能、工具接入沉淀成长期工作流的人

使用前准备

基础要求

  • 一个可用的 ChatGPT 账号，或 OpenAI API key
  • 可用的网络环境
  • Node.js
  • Git
  • 一个可读写的项目目录，最好是 Git 仓库

平台说明

截至 2026 年 3 月，官方文档覆盖 macOS / Linux / Windows。

但实操里要注意：

  • 能安装 不等于 能顺畅做工程任务
  • 在 Windows 上，体验是否稳定往往取决于你有没有准备好 Git、包管理器、测试依赖和必要时的 WSL

安装与登录

安装

官方最直接的安装方式：

1
npm install -g @openai/codex

安装后可直接输入：

1
codex

登录方式

Codex CLI 当前主要支持两条认证路径：

  • 使用 ChatGPT 账号登录
  • 使用 OpenAI API key

常用登录命令：

1
2
3
4
5
6
7
8
9
10
11
# 标准登录
codex login

# 设备认证（无浏览器环境）
codex login --device-auth

# 使用 API key
codex login --with-api-key

# 检查登录状态
codex login status

认证路径选择

  • ChatGPT 登录：更适合个人直接上手
  • API key：更适合自动化、脚本环境、可控计费场景

最小闭环：快速上手

最适合第一次上手的流程：

  1. 安装 CLI
  2. 登录
  3. cd 进入一个 Git 仓库
  4. 输入 codex
  5. 提一个小而明确的任务
  6. 让它修改文件
  7. 查看 diff
  8. 再追问一轮，或审查后接受

适合演示的任务类型

  • 修一个明确的单测失败
  • 给某个页面补按钮文案
  • 给脚本加参数校验
  • 改一处小而清晰的前端交互

不建议第一次上手就做大重构，否则很难判断是工具问题还是任务本身太复杂。

基础工作流

1. 进入项目

先切到项目目录：

1
cd your-project

然后进入交互模式：

1
codex

2. 选择权限与沙箱模式

第一次进入时，通常会看到和审批、沙箱相关的选择。本质上是在决定三件事：

  • 它能不能直接改文件
  • 它能不能联网
  • 它做关键操作时是否必须先征得你同意

三类常见模式：

  • 保守模式：先读、少写、关键操作要批准
  • 工作区模式：允许在项目范围内改文件
  • 全权限模式：更强，但风险也更高

3. 提任务

进入主界面后，典型工作流：

  • 你给出任务
  • 它先读项目和相关文件
  • 必要时提出计划
  • 修改文件或运行命令
  • 展示 diff 或结果
  • 你继续追问、审查或收尾

顶层命令总览

交互与会话

1
2
3
codex                    # 交互式主入口
codex resume             # 恢复历史会话
codex resume --last      # 恢复当前目录最近会话

认证

1
2
codex login              # 登录或切换认证
codex login status       # 查看当前登录状态

自动化与脚本

1
codex exec "任务描述"    # 非交互执行，适合脚本化与 CI

codex exec 的几个关键点：

  • 过程流默认打到 stderr
  • 最终结果默认打到 stdout
  • 可用 --json 输出 JSONL 事件流
  • 可用 --output-schema 约束最终输出结构
  • 可用 --ephemeral 跑一次性任务，不落盘会话

云端任务

1
2
3
4
codex cloud              # 交互式查看或选择云端任务
codex cloud exec         # 提交云端任务
codex cloud list         # 列出最近任务
codex apply              # 把云端任务产生的 diff 应用回本地仓库

工具与附加入口

1
2
3
4
5
6
codex mcp                # 管理 MCP 配置
codex mcp-server         # 把 Codex 暴露成 MCP server
codex completion         # 生成 Shell 补全脚本
codex features           # 查看和切换功能 flag
codex sandbox            # 在与 Codex 相同的沙箱策略下执行命令
codex app                # 从 CLI 拉起 Codex App（macOS）

Slash Commands

CLI 内常见的斜杠命令分类：

项目初始化与状态

1
2
3
4
/init          生成 AGENTS.md 脚手架
/status        查看当前状态
/model         查看或切换模型
/permissions   调整权限模式

计划与审查

1
2
3
/plan          先出思路，再决定是否执行
/review        站在代码审查角度回看改动
/diff          查看当前 Git diff

对话与上下文管理

1
2
3
4
/compact       压缩上下文
/new           在同一个 CLI 里开新对话
/clear         清空当前界面并开始新的对话
/copy          复制最新一条已完成输出

环境与工具扩展

1
2
3
4
5
6
/mcp                    查看当前 MCP 工具
/apps                   浏览和插入 app 或 connector
/sandbox-add-read-dir   补充可读目录
/agent                  切换当前活跃代理线程
/experimental           切换实验功能
/personality            调整沟通风格（friendly / pragmatic / none）

其他

1
2
/logout        清掉本地登录状态
/feedback      提交日志和诊断信息

高阶能力

CLI 当前支持搜索能力。

实操上很重要的一个点：

  • 本地任务里，web search 默认开启
  • 默认优先使用 OpenAI 维护的缓存搜索结果
  • 如果你显式加 --search，会切到 live 模式

这么设计的原因，是降低直接暴露在任意网页 prompt injection 里的风险。

适合用它的场景：

  • 查最近变更的外部库文档
  • 排查依赖或 API 的最新行为变化
  • 一边看本地项目，一边补外部上下文

2. 图片输入

CLI 不只支持纯文本，可以直接喂截图、设计稿、报错页面。

典型写法：

1
2
codex -i screenshot.png "Explain this error"
codex --image img1.png,img2.jpg "Summarize these diagrams"

适合用它的场景：

  • 根据报错截图分析问题
  • 根据设计稿补 UI
  • 根据参考图复刻页面结构

3. Subagents

Codex 支持子代理能力。

最容易理解的方式是：

  • 不再让一个代理从头硬扛到尾
  • 而是把不同子任务拆给不同代理并行推进

适合用它的场景：

  • 一个代理查测试失败
  • 一个代理看文档
  • 一个代理检查配置文件
  • 最后主代理汇总结果

要注意的边界：

  • 官方文档说明，只有在你明确要求时才会启用 subagents
  • 每个子代理都会额外消耗模型和工具资源

4. Skills

skill 可以理解成可复用的方法包。

它的意义是：

  • 把固定流程沉淀下来
  • 下次直接复用，不用每次重新教代理做事

例如：

  • 代码审查 skill
  • 前端页面实现 skill
  • 博客生成 skill
  • 调研整理 skill

官方文档里还提供了：

  • $skill-creator：用于创建 skill
  • 手工创建带 SKILL.md 的 skill 目录

5. MCP

MCP 的作用，是把外部工具和数据源接进 Codex。

例如：

  • 文档库
  • 数据库
  • 设计工具
  • 知识库
  • API 服务

它让 Codex 从”能在本地改代码”，扩展到”能在真实工作环境里协作”。

配置与项目规则

AGENTS.md

AGENTS.md 是项目级规则文件。

适合写进去的内容：

  • 代码风格
  • 禁止改动的目录
  • 默认先跑什么测试
  • 审查关注点
  • 输出语言与协作规范

它的价值在于把临时聊天要求，变成项目长期约束。

配置文件

官方文档当前给出的主配置路径：

  • 用户级：~/.codex/config.toml
  • 项目级：.codex/config.toml

配置优先级：

  1. CLI flags / --config
  2. --profile 指定的 profile
  3. 项目配置
  4. 用户配置

注意：

  • 只有项目被标记为 trusted 时，项目级 .codex/config.toml 才会生效

权限、审批与沙箱

这是理解 Codex CLI 的关键。

几个常见概念：

  • approval_policy
  • workspace-write
  • danger-full-access
  • network access

可以把它们简化成三种理解：

  • 只读不提权：适合 CI 或保守检查
  • 工作区可写：适合正常本地开发
  • 全权限：更强，但风险也更高

常见参数：

  • -a / --ask-for-approval
  • -s / --sandbox
  • --full-auto
  • --yolo
  • --add-dir

需要特别说明的点：

  • --full-auto 本质上是方便记忆的组合别名
  • --yolo 风险明显更高，不适合随便开
  • /sandbox-add-read-dir 非常适合说明”沙箱不是默认能读整台机器”

自动化与 CI

如果你想把 Codex CLI 用进更正式的流程，codex exec 是最关键的入口。

适合的使用方式：

  • 固定脚本
  • 批量任务
  • CI 辅助
  • 结果输出给其他脚本继续消费

最有代表性的点：

  • 它不是只能交互
  • 它已经有结构化输出能力
  • 它可以逐步接入自动化流水线

常见坑与排查

1. 登录成功但任务跑不起来

常见原因不是账号，而是：

  • 本地依赖不全
  • Git 状态混乱
  • 测试命令本身不可复现
  • Windows 与 Unix 路径差异

2. 改动看起来很多，但你不敢合

通常是因为：

  • 任务边界不清晰
  • 没写验收标准
  • 没限制改动范围
  • 没要求先看 diff

3. 仓库太大，上下文污染

常见表现：

  • 说了 A，它顺手改了 B
  • 不相关文件被带改
  • 修一个 bug，顺便做了重构

解决方式：

  • 限目录
  • 限文件
  • 限目标
  • 限验收
  • 必要时拆成多个代理或多轮任务

4. Windows 误把环境问题当产品问题

最常见的是：

  • 路径分隔符差异
  • shell 差异
  • 权限差异
  • 原生工具链缺失

最佳实践

1. 像给工程师派单一样写任务

❌ 不要说：

  • “帮我优化一下这个项目”

✅ 要说：

  • “只修改 src/auth.ts 和对应测试，使登录失败时返回明确错误码；验收标准是现有测试全部通过，并新增 1 个失败用例”

2. 先给验收标准，再让它执行

高质量任务描述重点是：

  • 改哪些文件
  • 不准改哪些文件
  • 成功标准是什么
  • 是否先出方案
  • 是否先给 diff

3. 把规则写进 AGENTS.md

临时聊天容易丢，写进项目规则更稳定。

4. 长任务拆成可恢复阶段

这样可以显著提升：

  • 可调试性
  • 可复现性
  • 失败后的恢复效率

5. 该用 CLI 的时候就用 CLI

最自然的场景是：

  • 精确执行
  • 终端流开发
  • 脚本化
  • CI 集成

学习路径建议

如果你是为了真正学会 Codex CLI，而不是只看演示，建议按这个顺序：

  1. 跑通最小闭环
  2. 学会看 diff 和 /review
  3. 理解沙箱与审批
  4. 把一个真实项目规则写进 AGENTS.md
  5. 学会 codex exec
  6. 再去理解 skills、MCP、subagents、cloud

总结

Codex CLI 不是简单的”终端聊天工具”，而是一个完整的工程执行代理系统。它的价值在于：

  • 本地化：直接在你的项目里工作
  • 可控性：通过沙箱和审批机制保证安全
  • 可扩展：通过 Skills、MCP 接入更多能力
  • 可自动化：通过 codex exec 接入 CI/CD

掌握它的关键不是记住所有命令，而是理解它的工作模式：明确任务边界、设定验收标准、控制改动范围、审查执行结果。

参考资源

 Comments
Comment plugin failed to load
Loading comment plugin
  1. 什么是 Codex CLI
  2. 适合谁使用
  3. 使用前准备
    1. 基础要求
    2. 平台说明
  4. 安装与登录
    1. 安装
    2. 登录方式
    3. 认证路径选择
  5. 最小闭环：快速上手
    1. 适合演示的任务类型
  6. 基础工作流
    1. 1. 进入项目
    2. 2. 选择权限与沙箱模式
    3. 3. 提任务
  7. 顶层命令总览
    1. 交互与会话
    2. 认证
    3. 自动化与脚本
    4. 云端任务
    5. 工具与附加入口
  8. Slash Commands
    1. 项目初始化与状态
    2. 计划与审查
    3. 对话与上下文管理
    4. 环境与工具扩展
    5. 其他
  9. 高阶能力
    1. 1. Web Search
    2. 2. 图片输入
    3. 3. Subagents
    4. 4. Skills
    5. 5. MCP
  10. 配置与项目规则
    1. AGENTS.md
    2. 配置文件
  11. 权限、审批与沙箱
  12. 自动化与 CI
  13. 常见坑与排查
    1. 1. 登录成功但任务跑不起来
    2. 2. 改动看起来很多，但你不敢合
    3. 3. 仓库太大，上下文污染
    4. 4. Windows 误把环境问题当产品问题
  14. 最佳实践
    1. 1. 像给工程师派单一样写任务
    2. 2. 先给验收标准，再让它执行
    3. 3. 把规则写进 AGENTS.md
    4. 4. 长任务拆成可恢复阶段
    5. 5. 该用 CLI 的时候就用 CLI
  15. 学习路径建议
  16. 总结
  17. 参考资源
  1. 什么是 Codex CLI
  2. 适合谁使用
  3. 使用前准备
    1. 基础要求
    2. 平台说明
  4. 安装与登录
    1. 安装
    2. 登录方式
    3. 认证路径选择
  5. 最小闭环：快速上手
    1. 适合演示的任务类型
  6. 基础工作流
    1. 1. 进入项目
    2. 2. 选择权限与沙箱模式
    3. 3. 提任务
  7. 顶层命令总览
    1. 交互与会话
    2. 认证
    3. 自动化与脚本
    4. 云端任务
    5. 工具与附加入口
  8. Slash Commands
    1. 项目初始化与状态
    2. 计划与审查
    3. 对话与上下文管理
    4. 环境与工具扩展
    5. 其他
  9. 高阶能力
    1. 1. Web Search
    2. 2. 图片输入
    3. 3. Subagents
    4. 4. Skills
    5. 5. MCP
  10. 配置与项目规则
    1. AGENTS.md
    2. 配置文件
  11. 权限、审批与沙箱
  12. 自动化与 CI
  13. 常见坑与排查
    1. 1. 登录成功但任务跑不起来
    2. 2. 改动看起来很多，但你不敢合
    3. 3. 仓库太大，上下文污染
    4. 4. Windows 误把环境问题当产品问题
  14. 最佳实践
    1. 1. 像给工程师派单一样写任务
    2. 2. 先给验收标准，再让它执行
    3. 3. 把规则写进 AGENTS.md
    4. 4. 长任务拆成可恢复阶段
    5. 5. 该用 CLI 的时候就用 CLI
  15. 学习路径建议
  16. 总结
  17. 参考资源