Codex 怎么用？CLI、IDE 插件、Codex Cloud 和桌面端完整上手指南

第一次用 Codex，不要先问它能不能重构整个项目。先把仓库打开，给它一个 20 分钟内能验收的小任务。

入口选择总览

OpenAI Codex 不是单一的终端工具或插件，而是一套可以在多个入口使用的 coding agent。你会在官方文档里看到 CLI、IDE extension、Codex app、Codex web/cloud 四个名字，它们共享同一套认证和底层能力，但适合的场景不同。

四入口对照表

入口	定义	适合场景	典型用户	限制条件
CLI	本机终端运行的 coding agent	已有本地仓库、小改动、命令行环境	命令行重度用户、CI 环境	需本地有 Git 仓库；文件改动在本地可见
IDE Extension	编辑器侧边栏协作	当前编辑器工作、上下文更短（open files/selected code）	VS Code/Cursor/Windsurf/JetBrains 用户	依赖编辑器环境；复杂任务可委派 Cloud
Codex App	桌面端 command center	多线程、worktree、automations、Git 管理	需并行处理多个任务的本地用户	macOS/Windows 可用，Linux 可用性以官方页面为准
Codex Cloud/Web	连接 GitHub 的云端 agent	远程仓库、PR、异步任务、离开电脑	团队用户、远程仓库场景	Enterprise workspace 可能需要 admin setup

认证方式与功能差异

Codex 支持两种认证方式，但功能范围不同：

认证方式	可用入口	Cloud 功能可用性	适用场景
ChatGPT account（Plus/Pro/Business/Edu/Enterprise）	全部入口（CLI/IDE/App/Cloud）	包含 GitHub code review、Slack 等 cloud-based features	个人订阅用户、团队用户
API Key	CLI、SDK、IDE Extension	不含 GitHub code review、Slack 等 cloud-based features	CI 环境、需要 API 计费的场景

价格、额度、具体功能开通以官方 pricing 页面和你的账号 dashboard 为准。如果你用 API key 登录后发现 Cloud 功能不可用，这不是故障，而是 surface 差异。

CLI 入口

CLI 是在本机终端运行的 coding agent。它能读取选定目录的代码、修改文件、运行命令和检查结果，适合已经有本地仓库的场景。

CLI 定义与场景

CLI 的核心能力是”在本地仓库里执行任务”：读代码、改文件、跑测试、跑 lint、检查报错、生成 diff。你不需要在编辑器里打开文件，只需要在终端里给出任务描述。

适合 CLI 的场景：

• 本地已有 Git 仓库
• 任务涉及多个文件或需要跑命令验证
• 希望改动直接在本地可见，方便 git diff 和 commit
• CI 环境或自动化脚本调用

不适合 CLI 的场景：

• 没有本地仓库（需要先 clone）
• 只想改当前打开的一个文件（IDE extension 更顺手）
• 需要远程仓库的 PR 流程（Cloud 更合适）

CLI 安装与登录

安装和登录步骤会随版本变化，以下只给高层流程，具体命令以官方 CLI 页面为准：

1. 按官方 CLI 页面选择安装方式：当前官方页面提供 standalone installer，部分历史文章可能提到 npm 安装，但应以官方当前页面为准。
2. 首次运行：安装后执行 codex，会引导你登录。
3. 登录方式：可选择 ChatGPT account 或 API key。ChatGPT account 包含全部 surface；API key 仅限 CLI/SDK/IDE extension，不含 Cloud 功能。

CLI 支持 macOS、Windows、Linux。Windows 用户可用 PowerShell native sandbox 或 WSL2，具体平台细节以官方 CLI 页面为准。

CLI 常用命令

CLI 提供两类入口：interactive 和 non-interactive。以下是新手常用的 6 个命令（命令名可能随版本变化，以 CLI reference 为准）：

命令	用途	示例
codex	Interactive 模式，在终端里对话式完成任务	codex（进入对话）
codex exec	Non-interactive 模式，适合 CI 或脚本调用	codex exec "fix the CI failure"
codex login	登录或切换账号	codex login
codex update	升级 CLI 版本	codex update
codex doctor	检查环境配置和问题	codex doctor
常用 flags	调整权限、模型、沙箱等	--sandbox read-only、--model、--ask-for-approval

CLI reference 还提供更多命令和 flags，如 codex apply、codex cloud、codex app 等，部分命令成熟度可能不同。新手阶段先掌握 interactive 模式即可，后续可看 codex exec 自动化专题。

CLI 第一次任务

第一次任务的核心原则：选择一个已有仓库，给它一个 20 分钟内能验收的小任务。

官方 best practices 建议高质量 prompt 包含四个要素：

Prompt 要素	说明	示例
Goal	任务目标	”修复 README 里过期的安装命令”
Context	上下文	”这是 Node.js 项目，README 里提到 npm install 但实际应该用 yarn”
Constraints	约束条件	”只改 README，不要改其他文件；改完跑一次 node README-example.js 确认命令能跑”
Done when	完成条件	”当 README 命令更新后，node README-example.js 成功输出结果”

示例任务：

• 修复 README 里过期的命令或链接
• 补一个缺失的测试或修复一个失败的测试
• 改一个小的 bug（有明确的报错信息）
• 清理一个 TODO 注释
• 给一个模块补简单的类型注释

不要让第一个任务：

• 涉及密钥或生产数据
• 是大重构或完整新功能
• 没有明确的验收条件（如”优化性能”太模糊）

CLI 验收清单

CLI 完成任务后，按以下步骤验收：

1. 看 diff：在终端里 git diff，确认改动符合预期。不要只看”任务完成”的文字回复。
2. 跑测试：如果项目有测试，跑一次 npm test 或对应命令，确认改动没有破坏现有功能。
3. 跑 lint/type check：如有 lint 或 type check，跑一次确认没有新增报错。
4. 检查命令执行结果：如果任务包含”跑某个命令”，确认命令输出符合预期。
5. 不要把密钥交给第一个任务：如果任务涉及密钥或敏感配置，先人工检查是否真的需要修改，不要让 agent 直接改。

验收通过后，再 commit 或 push。如果发现改动不符合预期，可以用 git checkout 恢复，调整 prompt 后重新尝试。

IDE Extension 入口

IDE extension 让 Codex 在编辑器侧边栏协作，适合当前正在编辑器工作的场景。它的核心优势是上下文更短：open files、selected code、@file 引用，不需要在终端里描述整个项目。

IDE 定义与场景

IDE extension 不是替代编辑器本身，而是让 Codex 作为 coding agent 嵌入你的编辑器工作流。它拿到的是你当前打开的文件、选中的代码片段或你用 @file 明确引用的文件，上下文更精准。

适合 IDE extension 的场景：

• 当前在 VS Code/Cursor/Windsurf/JetBrains 工作
• 任务涉及当前打开的文件或少量相关文件
• 希望边写边改，实时看到编辑器内的改动
• 需要引用特定文件作为上下文

不适合 IDE extension 的场景：

• 没有编辑器环境（CLI 更合适）
• 任务需要长时间后台运行（可委派 Cloud）
• 涉及大量文件或复杂命令流程（CLI 或 Cloud 更合适）

IDE 支持列表

IDE extension 支持以下编辑器（可用性以官方 IDE 页面为准）：

编辑器	说明
VS Code	官方支持
Cursor	VS Code fork，兼容 VS Code extension
Windsurf	VS Code fork，兼容 VS Code extension
JetBrains	支持 Rider、IntelliJ、PyCharm、WebStorm 等（可用性以官方页面为准）

如果你在 Cursor 或 Windsurf 工作，Codex extension 和编辑器自带的 AI 功能是并行关系，不是替代。Codex 可以作为另一个 coding agent，你可以在需要时切换或配合使用。

IDE 安装与登录

安装和登录步骤以官方 IDE 页面为准：

1. 从扩展商店安装：在 VS Code/Cursor/Windsurf/JetBrains 的扩展商店搜索 Codex extension。
2. 登录方式：支持 ChatGPT account 或 API key。ChatGPT account 包含全部 surface；API key 不含 Cloud 功能。

IDE 上下文能力

IDE extension 的核心能力是拿到编辑器上下文：

上下文类型	说明	示例
Open files	当前打开的文件自动作为上下文	打开 example.tsx，Codex 能直接看到文件内容
Selected code	选中的代码片段作为上下文	选中一段函数，让 Codex 解释或重构
@file 引用	用 @filename 明确引用其他文件	@example.tsx 请检查这个组件的类型定义
Reasoning effort	可调整推理深度	low/medium/high，复杂任务可用 higher effort

IDE 还支持 Chat/Agent/Agent Full Access 模式，区别在于权限和自动化程度。新手先用默认 Agent 模式，熟悉后再调整。

IDE 委派 Cloud

IDE extension 可以把任务委派到 Codex Cloud，适合：

• 任务需要长时间运行
• 任务涉及远程仓库
• 需要离开电脑但保持任务执行
• 复杂任务希望后台跑，完成后再看结果

常用 slash commands（命令名可能变化，以 IDE features 页面为准）：

命令	用途
/cloud	委派当前任务到 Cloud
/local	在本地执行任务
/review	Review base branch、uncommitted changes 或 commit
/status	查看 Cloud 任务状态

当你用 /cloud 委派任务后，IDE 会显示任务状态，你可以在 Cloud 任务完成后回来查看 diff 和结果。

Codex App 入口

Codex app 是桌面端 command center，定位是”多线程和 Git 管理的工作台”，而不是另一个聊天窗口。它会拾取 CLI 和 IDE extension 的历史和配置，方便在已有项目上继续。

App 定义与场景

App 的核心能力是多线程管理、worktree、automations、Git 操作。它适合需要并行处理多个任务、需要 diff pane 和 Git 集成的本地用户。

适合 App 的场景：

• 需要同时处理多个任务线程
• 需要隔离并行任务（worktree）
• 需要可视化的 diff pane 和 Git 操作
• 希望桌面端集成 terminal

不适合 App 的场景：

• 只想改当前打开的文件（IDE extension 更顺手）
• 没有本地仓库（Cloud 或先 clone）
• 只想跑一个简单任务（CLI 更快）

App 平台支持

Codex app 支持 macOS 和 Windows。Linux 可用性以官方 app 页面为准。

App 安装与登录

安装和登录步骤以官方 app 页面为准：

1. 下载安装：从官方 app 页面下载 macOS/Windows 安装包。
2. 登录方式：支持 ChatGPT account 或 API key。API key 部分功能可能不可用，具体以官方页面为准。
3. 选择项目：首次打开会引导选择本地项目目录。

App Thread Mode

App 提供 Local、Worktree、Cloud 三种 thread mode：

Thread Mode	说明	适合场景
Local	在当前项目目录直接工作	小改动、单线程任务、首次消息默认选择
Worktree	创建隔离的工作树，适合并行任务	多任务并行、需要隔离改动、避免冲突
Cloud	委派到 Codex Cloud	远程仓库、PR、长时间任务

Worktree 模式的详细使用留给后续专题（worktree 并行隔离），新手先用 Local 模式。

App 核心功能

App 的核心功能包括：

功能	说明
Diff pane	可视化查看文件改动，stage/revert chunks
Git 操作	commit/push/create PR，集成 Git 流程
集成 terminal	Cmd+J（macOS）打开 terminal，快捷键以官方页面为准
IDE 同步	IDE extension 与 app 可在同项目同步
MCP settings 共享	CLI/IDE/app 共享 MCP settings

App 还集成 in-app browser，但不支持需要登录的页面和用户浏览器 profile，需要登录的页面建议在外部浏览器打开。

Codex Cloud/Web 入口

Codex web/cloud 连接 GitHub account，让 Codex 在远程仓库中工作并创建 PR。它适合团队用户、远程仓库场景、需要离开电脑但保持任务执行的情况。

Cloud 定义与场景

Cloud 的核心能力是”远程仓库 + PR + 异步任务”。它在云端创建容器、checkout repo、运行 setup script、执行任务、给出 diff 和回答。

适合 Cloud 的场景：

• 远程仓库（本地没有或不希望本地改动）
• PR 流程（需要 Codex 创建 PR 或 review）
• 需要离开电脑但保持任务执行
• 团队流程（多人协作、review）

不适合 Cloud 的场景：

• 本地小改动（CLI 或 IDE 更合适）
• 第一次任务（建议先在本地验证）
• 需要频繁交互的任务（Cloud 是异步流程）

Cloud 适合任务

Cloud 适合的任务类型：

任务类型	说明
PR review	Review 远程仓库的 PR
复杂/长时间任务	需要长时间运行的任务
并行任务	多个任务同时委派
远程仓库改动	本地不需要改动

不建议第一次就把大重构或完整功能丢给 Cloud。第一次任务建议在本地用 CLI 或 IDE 验证，熟悉后再用 Cloud。

Enterprise workspace 可能需要 admin setup，具体以官方 Cloud 页面和你的 workspace policy 为准。

Cloud 流程概述

Cloud task 的大致流程（5 步）：

1. 创建容器：Cloud 创建运行环境。
2. Checkout repo：从 GitHub checkout 仓库。
3. 运行 setup script：运行项目配置的 setup script（如有）。
4. Agent 循环执行：Agent 循环执行命令、验证结果，直到任务完成。
5. 给出 diff 和回答：任务完成后展示 diff 和回答。

容器缓存最长 12 小时，具体策略以官方 Cloud environments 页面为准。

Cloud 安全提醒

Cloud 的安全边界：

安全项	说明
Secrets 仅 setup 可用	Secrets 只在 setup scripts 可用，agent phase 前会移除。不要把密钥写在 agent phase 依赖的脚本里。
Agent phase 默认无网络	Agent phase 默认 internet off，可配置有限或 unrestricted access。不要假设 agent 能访问外部网络。
缓存 12 小时	容器缓存最长 12 小时，不要假设长期保留状态。

如果你需要更详细的安全配置，看后续专题（权限、沙箱、密钥）。

下一步

完成第一次任务后，如果你发现 Codex 第二次还在犯同样的错误，说明需要写 AGENTS.md 项目规范。AGENTS.md 是面向 coding agent 的项目说明文件，可以沉淀重复指导，减少每次任务都要重新描述的上下文。

后续专题推荐：

• AGENTS.md 项目规范：沉淀项目指导，减少重复描述。
• Worktree 并行隔离：多任务并行，避免改动冲突。
• Cloud 实战：远程仓库、PR、环境配置。
• 权限、沙箱、密钥：安全边界和配置细节。
• 三工具横评：Codex vs Claude Code vs Cursor 真实项目对比。
• codex exec 自动化：CI 调用、脚本自动化。

站内相关文章：

• 2026 年 AI 编程工具全景盘点
• Claude Code CLI 高效使用指南
• Cursor 生态实践
• Codex 网关与 Harness