Codex 的入门使用

[!abstract] 一句话介绍 **Codex 是 OpenAI 推出的 AI 编程 Agent。**你描述目标，它可以在授权范围内读取项目、修改文件、运行命令和检查结果；你负责确认方案、审核改动并决定是否采用。

[!info] Codex 与普通对话式 AI 的区别 普通对话更偏向“告诉你怎么做”，Codex 更偏向“进入项目并协助完成”。它仍然可能出错，因此不能省略代码审查、测试和版本控制。

🧭 本文导航

• #01 Codex 是什么
• #02 Codex 的使用方式
• #03 桌面 App 页面功能
• #04 CLI 命令行入门
• #05 使用 CC Switch 管理 Codex 配置
• #06 权限与安全设置
• #07 第一次使用：创建网页计算器
• #08 日常使用技巧
• #09 常见问题
• #10 学习检查清单

01 Codex 是什么

Codex 可以协助完成以下工作：

• 阅读并理解现有代码库；
• 创建、修改和删除项目文件；
• 执行终端命令、测试、构建和代码检查；
• 分析报错、截图和运行日志；
• 根据审查意见继续迭代；
• 在授权后接入 GitHub、浏览器、MCP 等外部工具。

典型协作方式是：

Mermaid 图表未随分享发布。

[!warning] 不要把 Codex 当成“自动正确”的程序 Codex 是开发加速器，不是最终责任人。涉及生产环境、数据库、密钥、支付、权限和删除操作时，必须人工确认。

02 Codex 的使用方式

[!tip] 选择建议

• **第一次体验：**Web 或桌面 App；
• **本地项目开发：**桌面 App 或 IDE 扩展；
• **终端、远程服务器、自动化：**CLI。

2.1 Web 网页端

访问 Codex Web，登录 ChatGPT 账号后使用。

[!note] 特点 无需安装，适合快速体验；如果任务依赖本地项目，需要按照页面提供的方式连接仓库或提供文件。

2.2 桌面 App

根据 OpenAI 官方页面或系统应用商店安装桌面客户端，登录后查看 Codex 入口。

• **macOS：**从官方渠道下载安装；
• **Windows：**从 OpenAI 下载页面 获取安装包；
• 功能、最低系统版本和入口位置可能随版本变化，以安装页提示为准。

2.3 CLI 命令行

安装

使用 npm：

npm install -g @openai/codex

macOS 也可以使用 Homebrew：

brew install --cask codex

安装后检查版本：

codex --version

启动：

codex

[!tip] 登录方式 新手优先使用 ChatGPT 账号登录。需要接入 API 或自定义供应商时，再配置 API Key；不要把密钥直接写进笔记、代码或聊天记录。

2.4 IDE 扩展

以 VS Code 为例：

1. 打开扩展面板：Ctrl/⌘ + Shift + X；
2. 搜索 Codex 或 OpenAI Codex；
3. 核对扩展发布者；
4. 安装并登录；
5. 打开一个项目，发起第一条任务。

03 桌面 App 页面功能

[!note] 以下界面以截图所示版本为例。客户端更新后，菜单名称和位置可能发生变化，但“选择项目 → 描述任务 → 审核改动 → 验证结果”的主流程基本一致。

3.1 对话主页面：日常工作的中心

推荐流程：

1. 在项目区选择或新建项目；
2. 新建对话并清晰描述任务；
3. 查看 Codex 的计划、操作记录和命令输出；
4. 检查修改过的文件与 Diff；
5. 运行测试或打开预览；
6. 确认无误后再提交代码。

3.2 插件页面：接入外部工具

常见用途：

• GitHub：读取仓库、Issue 或 Pull Request；
• 浏览器：打开页面并进行网页操作；
• Figma、Cloudflare 等：按实际技术栈安装；
• 安装完成后，优先使用页面中的试用入口验证是否生效。

[!warning] 插件会扩大 Codex 可访问的数据范围。安装前确认来源、权限和实际需要，不用的插件及时关闭。

3.3 已安排：定时任务与提醒

可以尝试：

• 每日简报；
• 每周回顾；
• 定时整理 GitHub 提交；
• 定时检查项目状态。

示例指令：

每天早上 9 点，汇总昨天这个项目的 Git 提交，并列出需要关注的问题。

3.4 账号菜单：用量与设置入口

遇到限额、权限或连接问题时，优先检查：

• 当前登录账号；
• 使用额度；
• 设置与权限；
• MCP 和外部连接状态。

3.5 常规设置：工作模式与权限

新手建议：

• 选择适合编程的工作模式；
• 从较严格的权限开始；
• 暂时保留命令确认，理解每条命令后再放宽；
• 命令无法运行时，检查 Shell 与当前操作系统是否匹配。

3.6 MCP 服务器：连接外部数据源

排查顺序：

1. MCP 是否出现在列表中；
2. 开关是否启用；
3. 配置、命令和环境变量是否正确；
4. 在对话中要求 Codex 列出当前可用的 MCP 工具；
5. 出错时先关闭该 MCP，确认问题是否由它引起。

3.7 连接：从其他设备访问

[!warning] 安全建议 不需要远程控制时保持关闭。需要时仅添加可信设备，并确保电脑锁屏、电源和网络策略符合要求。

3.8 宠物：界面彩蛋

这是界面装饰，不影响编程能力。觉得分心或遮挡按钮时，可以更换或关闭。

04 CLI 命令行入门

4.1 常用启动方式

# 在当前目录启动交互模式
codex

# 指定工作目录启动
codex --cd /path/to/your/project

# 启动时直接附带任务描述
codex "分析这个项目，并告诉我应该先运行哪些测试"

# 非交互执行一次任务
codex exec "运行测试并总结失败原因"

# 查看完整帮助
codex --help

4.2 常用子命令

[!tip] CLI 的命令和斜杠指令会随版本更新。进入交互界面后输入 /help，以本机当前版本显示的列表为准。

4.3 推荐的终端工作流

cd /path/to/project
git status
git add . && git commit -m "chore: checkpoint before codex"
codex

进入 Codex 后，可以这样描述任务：

先阅读项目结构和 AGENTS.md，不要修改文件。
告诉我你对问题的理解、最小修改方案和验证方式，等我确认后再实施。

05 使用 CC Switch 管理 Codex 配置

[!abstract] CC Switch 是什么 CC Switch 是一个第三方跨平台桌面工具，可集中管理 Codex、Claude Code、Gemini CLI 等 AI 编程工具的供应商、API 配置、MCP、Prompts 和 Skills。它适合需要在官方登录、不同 API 服务或多套配置之间切换的用户。

[!info] 项目信息

• 唯一官方网站：ccswitch.io
• 开源仓库：farion1231/cc-switch
• 支持平台：Windows、macOS、Linux

5.1 什么时候需要 CC Switch

适合以下场景：

• 同时维护 Codex 官方登录和 API Key 配置；
• 需要切换多个 Codex 供应商或账号；
• 希望统一管理 Codex、Claude Code、Gemini CLI 的 MCP；
• 希望集中管理 AGENTS.md、Prompts 和 Skills；
• 不想频繁手动修改 ~/.codex/config.toml 等配置文件。

如果你只使用一个 ChatGPT 账号，并且官方登录已经满足需要，可以不安装 CC Switch。

5.2 安装 CC Switch

macOS

推荐使用 Homebrew：

brew install --cask cc-switch

更新：

brew upgrade --cask cc-switch

也可以从 GitHub Releases 下载 .dmg 安装包。

Windows

从 GitHub Releases 下载以下任一版本：

• CC-Switch-v{版本号}-Windows.msi：安装版；
• CC-Switch-v{版本号}-Windows-Portable.zip：便携版。

Linux

根据发行版选择：

• Debian / Ubuntu：.deb；
• Fedora / RHEL / openSUSE：.rpm；
• 通用版本：.AppImage；
• Arch Linux：paru -S cc-switch-bin。

5.3 首次启动与导入

1. 先确保 Codex CLI 已安装，并至少启动过一次；
2. 打开 CC Switch；
3. 切换到 Codex 应用；
4. 首次启动时，根据提示导入现有 CLI 配置作为默认供应商；
5. 导入后先不要删除默认配置，它可以作为恢复入口。

[!tip] 最小侵入原则 CC Switch 会保留一个正在激活的配置，避免删除全部配置后导致 Codex 无法使用。

5.4 添加 Codex 供应商

1. 在 CC Switch 中选择 Codex；
2. 点击右上角的 「+」；
3. 选择“应用专属供应商”或“统一供应商”；
4. 从预设列表选择供应商，或创建自定义配置；
5. 填写 API Key；
6. 核对 API 地址、协议和模型；
7. 点击“添加”。

Codex 供应商大致分为两类：

[!warning] API Key 安全 只从可信供应商获取 Key。不要把 Key 发送到聊天、提交到 Git，或粘贴到不可信的配置分享链接中。

5.5 切换供应商

有两种方式：

• **主界面：**选择供应商卡片，点击“启用”；
• **系统托盘：**直接点击目标供应商名称。

切换完成后：

1. 退出正在运行的 Codex CLI；
2. 重新打开终端或重新启动 codex；
3. 新建会话验证配置；
4. 如有异常，切回原来的默认供应商。

[!note] 根据 CC Switch 官方说明，多数 CLI 工具切换供应商后需要重启才能生效。

5.6 恢复 Codex 官方登录

1. 在 Codex 的预设供应商中添加 OpenAI 官方 / 官方登录；
2. 启用该供应商；
3. 重启 Codex CLI；
4. 执行登录流程：

codex logout
codex login

5.7 用 CC Switch 管理 MCP、Prompts 与 Skills

5.8 配置文件与备份位置

~/.cc-switch/cc-switch.db          # 供应商、MCP、Prompts、Skills
~/.cc-switch/settings.json         # 本机 UI 设置
~/.cc-switch/backups/              # 自动备份
~/.cc-switch/skills/               # Skills 数据

[!danger] 第三方服务风险 CC Switch 本身是第三方开源工具，第三方 API 中转服务也不等于 OpenAI 官方服务。使用前应评估隐私、稳定性、费用、服务条款和账号风险。对于 CC Switch 中标注为逆向工程、OAuth 反向代理或实验性的功能，建议普通用户不要启用；优先使用 Codex 官方登录或官方支持的 API 方式。

5.9 常见问题排查

06 权限与安全设置

Codex 能读取文件并执行命令，因此权限设置必须认真对待。

6.1 工作目录权限

优先只开放当前项目：

codex --cd /path/to/project

[!danger] 不推荐 不要为了省事把整个用户目录或包含大量隐私文件的目录设为工作区。每个项目使用独立目录，按需增加额外可写目录。

6.2 命令执行权限

新手建议保留命令确认，重点检查：

• 删除文件：rm、del；
• 覆盖文件或批量替换；
• 安装全局依赖；
• 修改系统配置；
• 访问网络或上传文件；
• 数据库写入、迁移和清理；
• git push、发布和部署命令。

6.3 网络与密钥

• 仅在任务确实需要时开放网络；
• 使用环境变量或密钥管理工具保存 Key；
• .env 应加入 .gitignore；
• 不把生产密钥直接粘贴到对话中；
• 对第三方 MCP 和供应商执行最小权限授权。

6.4 Git 安全

开始任务前建立检查点：

git status
git add .
git commit -m "chore: checkpoint before codex"

推荐原则：

• 在独立分支上让 Codex 工作；
• 每次只完成一个小目标；
• 查看 Diff 后再接受；
• 运行测试后再提交；
• 不让 Codex 在无人审核时直接推送主分支。

07 第一次使用：创建网页计算器

Step 1：创建项目目录

mkdir -p ~/projects/my-calculator
cd ~/projects/my-calculator

Step 2：启动 Codex

codex

Step 3：发送明确指令

请在当前目录创建一个网页计算器，只生成一个 index.html。

要求：
1. 使用原生 HTML、CSS 和 JavaScript，不安装依赖；
2. 现代简约风格，支持深色主题；
3. 支持鼠标点击和键盘输入；
4. 完成后检查基础运算、清空和退格功能；
5. 先说明计划，再修改文件；
6. 最后总结修改内容和验证结果。

Step 4：观察执行过程

Codex 通常会：

1. 分析需求；
2. 创建 index.html；
3. 编写 HTML、CSS 和 JavaScript；
4. 检查文件或运行验证；
5. 展示修改摘要和 Diff。

Step 5：审查改动

检查以下内容：

• 是否只修改了预期文件；
• 是否引入外部脚本或可疑网络请求；
• 计算逻辑是否正确；
• 是否存在明显报错；
• 页面是否符合需求。

Step 6：预览

请在浏览器中打开 index.html，并检查页面布局与键盘输入。

Step 7：小步迭代

在不改变计算逻辑的前提下，把按钮改成更大的圆角按钮，并增强移动端适配。

[!success] 完成标准 页面能打开、基本运算正确、键盘可用、没有控制台报错，并且 Git Diff 中只有预期修改。

08 日常使用技巧

8.1 写好 AGENTS.md

AGENTS.md 是给 Codex 的项目说明书。建议放在项目根目录，包含技术栈、运行方法、代码规范、验证命令和禁止事项。

# AGENTS.md

## 项目概述
这是一个基于 Next.js 的个人博客，使用 TypeScript 和 Supabase。

## 常用命令
- `npm run dev`：启动开发服务器
- `npm run lint`：代码检查
- `npm test`：运行测试
- `npm run build`：生产构建

## 代码约定
- 使用 TypeScript，避免 `any`
- React 组件使用函数组件
- 样式使用 Tailwind CSS
- 组件名使用 PascalCase
- 文件名使用 kebab-case

## 修改原则
- 只修改与当前任务直接相关的代码
- 优先最小改动，不做无关重构
- 修改行为前先补充或运行测试

## 红线
- 未经明确要求，不升级依赖
- 不修改 `.env.local`
- 不删除已有迁移文件
- 不直接向 `main` 分支执行 `git push`
- 不操作生产数据库

8.2 指令要具体

对比：

❌ 帮我优化一下这个项目。

✅ 首页首屏加载较慢。请先定位原因，只优化图片加载和首屏 JavaScript 体积；
不要更换框架，不升级依赖。完成后运行 npm run build，并对比构建产物。

8.3 分步执行

复杂任务拆成：

1. 只分析，不修改；
2. 给出最小方案；
3. 实施第一步；
4. 运行验证；
5. 审核后继续。

8.4 明确成功标准

修复登录按钮重复提交问题。
成功标准：
- 连续点击只发出一次请求；
- 请求期间按钮禁用；
- 成功和失败路径都有测试；
- npm test 全部通过。

8.5 用截图和日志补充上下文

遇到界面错位或报错时，可以提供：

• 完整截图；
• 控制台错误；
• 复现步骤；
• 期望结果；
• 操作系统与版本；
• 最近修改过的文件。

8.6 不确定时先问下一步

请先检查当前项目状态，不要修改文件。
告诉我风险最高的三个问题，以及你建议先处理哪一个。

8.7 每轮结束都要验证

请总结：
1. 修改了哪些文件；
2. 为什么这样改；
3. 运行了哪些测试；
4. 哪些风险仍未验证；
5. 我应该重点审查哪些 Diff。

09 常见问题

Codex 和 Cursor 有什么区别？

Cursor 是以 AI 编辑器为核心的开发工具；Codex 是编程 Agent，可通过 App、CLI、Web 或 IDE 扩展参与开发。选择取决于你更偏好编辑器内协作，还是独立 Agent 工作流。

Codex 和 Claude Code 有什么区别？

两者都属于 coding agent，但账号体系、模型、配置文件、工具生态和交互细节不同。可以根据已有订阅、模型偏好和团队工具链选择，也可以通过 CC Switch 管理多套 CLI 配置。

Codex 生成的代码能直接上线吗？

不建议未经审核直接上线。简单页面和脚本也要经过代码审查、测试、安全检查和部署验证；复杂业务还需要领域专家确认。

Codex 把代码改坏了怎么办？

优先使用 Git 恢复：

git status
git diff

如果改动尚未提交，可只恢复确认不需要的文件；如果已经建立任务前检查点，可以回到对应提交。执行恢复前先确认未保存的重要改动，避免误删。

可以让 Codex 连接数据库吗？

可以，但建议：

• 先使用本地或测试数据库；
• 凭据放在环境变量中；
• 生产环境只给最小权限；
• 写操作、迁移和删除操作必须人工确认；
• 重要数据先备份。

Web、App、CLI 应该选哪个？

• 想快速体验：Web；
• 想图形化操作本地项目：App；
• 熟悉终端或需要自动化：CLI；
• 长时间在编辑器里工作：IDE 扩展。

是否必须安装 CC Switch？

不是。只有在需要多账号、多供应商、统一 MCP 或频繁切换配置时才有明显价值。单账号用户优先保持官方登录，配置更简单、风险也更低。

10 学习检查清单

• 已选择一种适合自己的 Codex 使用方式
• 已成功登录并完成第一次对话
• 已理解工作目录和命令审批的含义
• 已在测试项目中完成一次文件修改
• 已查看并理解 Git Diff
• 已运行测试或手动验证结果
• 已为常用项目编写 AGENTS.md
• 已建立“修改前提交、修改后测试”的习惯
• 如需多供应商，已安装并备份 CC Switch 配置
• 已避免在聊天、笔记和 Git 中暴露 API Key

[!success] 下一步 创建一个小项目，写一份简短的 AGENTS.md，让 Codex 完成一个可以验证的真实任务。不要只收藏教程——从第一条清晰、可检查的指令开始。

参考资料

• OpenAI Codex
• OpenAI 下载页面
• CC Switch 官方网站
• CC Switch GitHub 仓库
• CC Switch 中文用户手册
• 原文