Codex CLI 完整指南：从安装到远程控制

OpenAI 的终端编程代理，能读代码、跑命令、改文件。这篇文章讲清楚怎么装、怎么配、怎么用，一直到手机远程控制。

先说清楚 Codex 是什么

Codex CLI 是 OpenAI 推出的本地编程代理。它运行在你电脑的终端里，能：

• 读你的代码库

• 执行 Bash 命令

• 编辑、创建、删除文件

• 跑测试、查日志、调试

• 联网搜索、抓网页内容

它不是 IDE 插件，是独立的终端工具。如果你想要 IDE 集成，OpenAI 另外有 Codex IDE 扩展。

和 Claude Code 的区别：

适合谁用：

• 已经在用 ChatGPT Pro/Plus 订阅的人（不用额外花钱）

• 习惯终端工作流的开发者

• 需要 AI 帮忙改代码、跑测试、查文档

• 想在手机上远程查看/控制编码会话

不适合谁：

• 期望完全自动化、不看代码就发布的人

• 不愿意审查 AI 输出的人

• 没有稳定网络环境的人

一、安装

系统要求

• macOS、Linux 或 Windows 11

• Node.js 20+（npm 安装方式）

• ChatGPT Plus/Pro/Business/Enterprise 订阅，或 OpenAI API Key

安装方式

方式一：npm（推荐）

npm install -g @openai/codex

方式二：Homebrew（macOS）

brew install --cask codex

方式三：下载二进制

从 GitHub Releases 下载对应平台的压缩包：

• macOS Apple Silicon: codex-aarch64-apple-darwin.tar.gz

• macOS Intel: 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

• Windows: codex-x86_64-pc-windows-msvc.exe.zip

解压后重命名为 codex，放到 PATH 目录。

验证安装

codex --version

二、认证

方式一：ChatGPT 登录（推荐）

如果你有 ChatGPT Plus/Pro 订阅，这是最简单的方式：

codex

首次运行会提示选择认证方式，选择 Sign in with ChatGPT。

浏览器会打开 ChatGPT 登录页面，完成登录后回到终端即可。

ChatGPT 订阅包含的额度：

方式二：API Key

如果你用 API Key，需要额外配置：

export OPENAI_API_KEY="sk-..."

然后在 ~/.codex/config.toml 中配置：

model = "o4-mini" # 或 "gpt-4.1", "o3"

[api]

key = "sk-..." # 也可以写在这里

API Key 计费：按实际使用量计费，不从 ChatGPT 订阅扣。

退出登录

codex logout

三、第一次使用

启动交互会话

进入你的项目目录，然后：

codex

Codex 会启动一个交互式终端界面（TUI），底部有输入框，顶部显示对话历史。

基本用法

直接用自然语言描述你想做的事：

> 找到所有 TypeScript 文件里的 console.log，帮我删掉

> 跑一下测试，看看哪些失败了

> 解释一下 src/auth/login.ts 的主要逻辑

Codex 会： 1. 理解你的意图 2. 在你的代码库里搜索相关信息 3. 提出执行计划（需要你确认） 4. 执行并报告结果

权限审批

Codex 执行敏感操作前会询问你：

Codex wants to run: rm -rf node_modules

Approve? [y/n/a] (y = once, n = deny, a = always for this session)

• y: 批准这一次

• n: 拒绝

• a: 本次会话内始终批准这类操作

常用快捷键

中断当前操作

四、配置文件

Codex 的配置文件在 ~/.codex/config.toml。

基础配置

model = "o4-mini"

approval_policy = "untrusted"

模型选择

Codex 支持的模型：

默认，速度快、成本低

切换模型：

codex --model o3

或在 config.toml 中设置默认值。

审批策略

approval_policy 控制 Codex 执行命令时何时询问你确认：

只读操作自动执行，其他都需要确认（最安全，默认）

配置：

approval_policy = "untrusted" # 最安全

项目级配置

项目级配置放在 <项目根目录>/.codex/config.toml，会覆盖全局配置：

model = "o3"

approval_policy = "untrusted"

配置按以下优先级加载（后加载的覆盖先加载的）：

1. 系统配置：/etc/codex/config.toml（Unix）或 %ProgramData%\OpenAI\Codex\config.toml（Windows）

2. 用户配置：~/.codex/config.toml

3. 项目配置：<项目根目录>/.codex/config.toml

五、AGENTS.md：项目说明书

AGENTS.md 是放在项目根目录的说明文件，告诉 Codex 这个项目是做什么的、有什么规矩。

为什么需要 AGENTS.md

没有 AGENTS.md，Codex 只能靠代码推断项目结构。 有 AGENTS.md，Codex 能：

• 知道项目的构建/测试命令

• 理解代码风格偏好

• 遵守项目特有的开发规范

• 避免踩已知坑

写法示例

## 项目概述

这是一个 TypeScript Node.js 后端服务，提供用户认证和数据处理 API。

## 常用命令

- 构建：`npm run build`

- 测试：`npm test`

- 启动开发服务器：`npm run dev`

- 代码检查：`npm run lint`

## 代码规范

- 使用 ES Modules（import/export）

- 异步操作用 async/await，不用回调

- 测试文件放在 `__tests__/` 目录

- 提交前必须跑 `npm run lint` 和 `npm test`

## 已知问题

- node_modules 有时会损坏，需要 `rm -rf node_modules && npm install`

- 测试数据库需要手动启动：`docker-compose up -d test-db`

## 不要做的事

- 不要修改 `legacy/` 目录下的代码

- 不要直接提交到 main 分支

- 不要跳过测试

自动生成

Codex 可以帮你生成 AGENTS.md：

codex /init

它会分析项目结构，生成一份草稿供你修改。

六、斜杠命令

Codex 内置了一系列斜杠命令，在对话中输入 / 可以看到完整列表。

常用命令

生成 AGENTS.md 文件

工作流命令

切换到计划模式

调试和配置

显示配置层和来源

七、Skills：扩展能力

Skills 是 Codex 的插件机制，让 Codex 学会特定领域的技能。

使用 Skills

通过 /skills 命令管理 skills：

> /skills

这会打开 skills 管理界面，你可以查看已安装的 skills、安装新的 skills、或管理现有 skills。

Skills 目录结构

Skills 存放在 ~/.codex/skills/ 目录：

~/.codex/skills/

├── my-skill/

│ └── SKILL.md

SKILL.md 文件定义了 skill 的用途和执行指南。

编写自己的 Skill

创建 ~/.codex/skills/my-skill/SKILL.md：

---

name: my-skill

description: 做某件事的技能

---

## 使用场景

当用户要求 XXX 时使用此 skill。

## 执行步骤

1. 先检查 YYY

2. 然后执行 ZZZ

3. 最后报告结果

## 注意事项

- 不要在生产环境执行

- 需要提前安装依赖 ABC

Codex 会自动加载并识别这个 skill。

八、MCP：连接外部工具

MCP（Model Context Protocol）让 Codex 能连接外部服务，比如数据库、API、文件系统。

配置 MCP Server

在 ~/.codex/mcp.json 中配置：

{

"mcpServers": {

"filesystem": {

"command": "npx",

"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/dir"]

},

"postgres": {

"command": "npx",

"args": ["-y", "@modelcontextprotocol/server-postgres"],

"env": {

"DATABASE_URL": "postgresql://user:pass@localhost/db"

}

}

}

}

常用 MCP Server

文件系统访问

使用 MCP 工具

配置好 MCP 后，Codex 会自动发现新工具。你可以直接在对话中使用：

> 查一下 users 表里最近注册的 10 个用户

Codex 会调用 postgres MCP server 执行查询。

九、非交互模式：自动化脚本

Codex 支持非交互模式，适合 CI/CD 或脚本调用。

基本用法

codex exec "分析这个项目的测试覆盖率"

指定输出格式

codex exec --output json "列出所有 TODO 注释"

输出：

{

"todos": [

{"file": "src/auth.ts", "line": 42, "text": "TODO: 添加重试逻辑"},

{"file": "src/db.ts", "line": 128, "text": "TODO: 优化查询性能"}

]

}

恢复会话

codex exec --list

codex exec resume <session-id>

CI/CD 集成示例

name: Codex Code Review

on: [pull_request]

jobs:

review:

runs-on: ubuntu-latest

steps:

- uses: actions/checkout@v4

- name: Run Codex Review

env:

OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

run: |

npm install -g @openai/codex

codex exec --output json "审查这个 PR 的代码变更" > review.json

十、远程控制：手机端操作

这是 Codex 最近新增的功能：通过 ChatGPT 手机 App 远程控制电脑上的 Codex。

前提条件

• Codex Desktop App（macOS，Windows 即将支持）

• ChatGPT 手机 App（iOS/Android）

• 同一个 ChatGPT 账号

配对步骤

1. 在电脑上打开 Codex Desktop App

2. 启动远程配对

在 Codex Desktop 中找到 "Set up Codex mobile" 或 "Remote Control" 选项，会显示一个 QR 码。

1. 用手机扫描 QR 码

打开 ChatGPT App，使用内置扫码功能扫描电脑上的 QR 码。

1. 完成配对

配对成功后，手机上会显示你的电脑设备名称。

手机端能做什么

配对后，手机端可以：

• 查看会话：看到电脑上正在进行的 Codex 会话

• 发送指令：输入新的编码任务

• 审批操作：审批 Codex 请求的敏感操作

• 查看进度：看到 Codex 的执行进度和输出

• 切换项目：在不同项目目录间切换

使用场景

场景一：离开电脑时继续监控

你在电脑上启动了一个长时间运行的 Codex 任务（比如重构、跑测试），然后需要离开。打开手机 ChatGPT App，可以：

• 查看任务进度

• 在 Codex 遇到问题时审批操作

• 给 Codex 补充指令

场景二：通勤时发起任务

早上通勤时，在手机上给 Codex 发送任务：

检查 src/api/ 目录下的所有接口，找出缺少错误处理的

等你到公司，Codex 已经完成了分析。

场景三：审批紧急操作

同事在 Slack 上说测试挂了，你在开会。用手机查看 Codex 会话，审批紧急修复。

注意事项

1. 电脑必须在线：Codex Desktop App 需要运行，电脑需要开机联网

2. 同一账号：手机和电脑必须登录同一个 ChatGPT 账号

3. 网络要求：手机和电脑在同一局域网时响应更快；互联网模式也可用，但可能稍慢

4. Windows 支持：目前仅 macOS 作为 host，Windows 支持正在开发中

5. 安全考虑： - 可以在 Codex Desktop 中随时取消配对 - 敏感操作仍需手机端确认 - 建议不要在公共网络使用

故障排查

配对后手机显示设备离线：

• 检查 Codex Desktop 是否在运行

• 检查电脑网络连接

• 尝试重新配对

无法审批操作：

• 确认手机 App 是最新版本

• 检查 ChatGPT 订阅是否有效

重新配对失败：

• 在 Codex Desktop 中先移除旧设备

• 在 ChatGPT App 中清除旧设备记录

• 重新扫描 QR 码

十一、最佳实践

1. 写好 AGENTS.md

这是最重要的。AGENTS.md 决定了 Codex 对你项目的理解深度。

写清楚： - 项目的构建、测试、运行命令 - 代码风格和命名规范 - 已知的坑和解决方案 - 不想让 Codex 动的区域

2. 从小任务开始

第一次用，不要让 Codex 做大重构。先试：

• 添加一个简单的函数

• 修复一个小 bug

• 解释一段代码

等熟悉 Codex 的行为模式后，再给大任务。

3. 审批要仔细

untrusted 策略下，Codex 会问你确认敏感操作。认真看它在做什么，养成习惯。

4. 用版本控制

Codex 会修改你的代码。确保：

• 工作在 Git 分支上

• 频繁提交

• 让 Codex 改之前先 commit

git checkout -b codex-work

git add .

git commit -m "保存当前状态"

5. 分步骤给指令

大任务拆成小步骤：

不好：

> 重构整个认证系统

好：

> 第一步：分析当前认证系统的结构

> 第二步：设计新的认证流程

> 第三步：先重构登录接口

> ...

6. 利用上下文

Codex 会记住对话历史。善用这一点：

> 基于刚才的分析，把 login 函数重构一下

7. 善用 /compact

长对话会消耗上下文。定期用 /compact 压缩历史：

> /compact

十二、常见问题

Q: Codex 和 GitHub Copilot 有什么区别？

Copilot 是 IDE 内的代码补全工具，主要做单行或小块代码补全。 Codex 是终端代理，能执行复杂任务：读代码、跑命令、改文件、调试。

Q: 用 ChatGPT 订阅还是 API Key？

有 ChatGPT Plus/Pro 就用 ChatGPT 登录，最简单。 如果公司不让用 ChatGPT 账号，或需要精确控制成本，用 API Key。

Q: Codex 会把我的代码发送到 OpenAI 吗？

会。Codex 需要把代码上下文发给 OpenAI 的服务器才能工作。 如果代码敏感，考虑： - 用本地模型（需要自己部署） - 只让 Codex 访问非敏感目录 - 和公司安全团队确认

Q: 如何撤销 Codex 的修改？

用 Git：

git diff # 查看修改

git checkout . # 撤销所有未提交的修改

git reset --hard # 硬重置

Q: Codex 太慢了怎么办？

• 用更快的模型：o4-mini 比 o3 快

• 减少 AGENTS.md 的长度

• 用 /compact 压缩对话历史

• 确保网络稳定

Q: Codex 卡住了怎么办？

按 Ctrl+C 中断，然后重新开始。 如果频繁卡住，检查网络连接或重启 Codex。

Q: 如何查看当前配置？

使用 /debug-config 命令查看所有配置层和来源：

> /debug-config

十三、总结

Codex CLI 是一个强大的终端编程代理。用好它的关键是：

1. 配置好 AGENTS.md：让 Codex 理解你的项目

2. 从小任务开始：建立信任后再给大任务

3. 保持版本控制：方便回滚

4. 善用远程控制：离开电脑时也能监控和审批

它不会替代程序员，但能显著提升编码效率——尤其是那些重复性高、上下文复杂的任务。

参考链接

• Codex CLI GitHub 仓库：https://github.com/openai/codex

• Codex 官方文档：https://developers.openai.com/codex

• ChatGPT 订阅说明：https://help.openai.com/en/articles/11369540-codex-in-chatgpt

• AGENTS.md 指南：https://developers.openai.com/codex/guides/agents-md

• MCP 协议：https://modelcontextprotocol.io