Codex 教程

ChatGPT (Codex) 教程

Codex 是 OpenAI 推出的 AI 编程代理(Agent),它基于 GPT 系列大模型,能够在真实开发环境中自主完成编码任务:读写文件、运行命令、执行测试、提交代码,甚至管理整个仓库的迭代。

本教程内容

本教程从 Codex 的简介与核心概念讲起,逐步覆盖安装配置、桌面应用、命令行工具、IDE 扩展、云端版本、提示词技巧、安全设置与团队协作等全部主题,帮助你把它真正用起来、用好。

Codex 能做什么

自主编写与修改代码,修复 Bug
运行与调试命令,执行测试
接入 MCP、子代理与 Agent Skills 扩展能力
在 IDE(Cursor、VS Code)与终端中无缝工作
接入 CI/CD 实现自动化开发流程

学习路径建议

先完成安装与基础入门,掌握对话式编程的基本操作;再学习配置定制与权限管理;随后深入 CLI、IDE、云端与自动化;最后研究提示词技巧与团队协作最佳实践。

准备好你的 API Key 或 ChatGPT 账号,即可开始第一章的学习。

CodeX 简介

Codex 是 OpenAI 的编程代理产品,于 2025 年正式发布。它不同于传统"聊天式补全"工具,而是能够理解任务目标、规划执行步骤、在沙箱环境中自主操作代码库的智能体。

核心定位

Codex 的设计目标:让 AI 成为真正意义上的"结对程序员"甚至"独立开发者"。它能在你睡觉时继续完成任务,把你的自然语言描述转化为可运行的软件成果。

技术基础

基于 GPT-5 系列模型,具备强大的代码理解与生成能力
支持长期任务执行:多步骤规划、自我检查、错误修正
沙箱隔离:代码在安全环境中运行,不污染宿主机

主要形态

形态	说明
ChatGPT 内置	在 ChatGPT 中直接使用 Codex 功能
Codex 桌面应用	macOS 原生应用,独立工作区
CLI 命令行	在终端中运行 codex,融入现有工作流
IDE 扩展	VS Code 等编辑器内联使用
云端版本	云端沙箱,随时随地访问

与其他工具的关系

Codex 与 Claude Code、Cursor、GitHub Copilot 等属于同类产品。Codex 的优势在于 OpenAI 大模型的编码能力、与 ChatGPT 生态的深度集成,以及对长任务的高可靠性。

为什么值得学习

AI 编程正在从"自动补全"走向"自主代理"。掌握 Codex 这类工具,等于掌握了一套新的生产力范式:需求描述、任务委派、结果验收,而不是逐行手写代码。

Codex 核心概念

理解 Codex 的架构与概念,有助于用好它的每一项能力。本节介绍 Codex 的核心组成与工作方式。

Agent(代理)

Codex 以"代理"方式工作:接收任务描述后,自主规划执行路径,循环执行"思考 → 操作 → 观察结果 → 调整"的步骤,直到任务完成。它不是一次性回答,而是持续行动。

沙箱(Sandbox)

Codex 的代码执行发生在隔离沙箱中,可以限制网络与文件访问权限。沙箱保障了宿主机的安全,是"让 AI 自主操作"得以放心的关键设计。

会话(Session)

一次对话是一个会话,包含连续的上下文。Codex 支持恢复会话(resume),让任务跨天持续进行。

规则与钩子(Hooks)

通过 AGENTS.md、规则文件和钩子机制,可以约束 Codex 的行为:指定编码规范、禁止的操作、必须执行的检查流程等。

Skills 与子代理

Agent Skills 为 Codex 提供领域能力(如特定的构建工具链);子代理允许 Codex 并行委派多个任务,提升复杂项目的处理效率。

MCP(模型上下文协议)

MCP 让 Codex 连接外部工具与数据源:数据库、浏览器、内部 API 等,极大扩展了它的能力边界。

模型选择

Codex 支持切换底层模型,不同模型在速度、成本、复杂任务能力上各有取舍,按需选择即可。

把这些概念串起来,就理解了 Codex 的完整工作流:任务输入 → 规则约束 → 规划执行(可能并行子代理)→ 沙箱验证 → 结果交付。

Codex 安装与使用

Codex 提供多种安装方式,最常见的是通过 npm 安装 CLI 与安装桌面应用。本节以 CLI 为例介绍完整流程。

环境要求

Node.js 18+ 或更高版本
macOS / Linux / Windows(Windows 需 WSL2 或原生支持)
OpenAI 账号与 API Key(或 ChatGPT Plus/Pro 订阅)

安装 CLI

npm install -g @openai/codex

# 验证安装
codex --version

登录与配置

# 交互式登录(ChatGPT 账号)
codex login

# 或使用 API Key
export OPENAI_API_KEY="sk-你的密钥"
codex login --api-key

首次使用

# 交互模式:开始对话
codex

# 直接提问
codex "修复 src/utils.js 里的日期解析 bug"

# 解释代码
codex "解释一下这个仓库的架构"

配置文件

Codex 的配置文件位于 ~/.codex/config.toml(全局)与项目根目录 .codex/config.toml(项目级):

[model]
model = "gpt-5.2-codex"

[permissions]
allow = ["Bash(git:*)", "Read(**)"]

验证是否可用

codex "用 Python 输出 1 到 10 的平方,并运行验证"

看到 Codex 自动创建文件并运行验证输出,说明安装配置成功,可以开始正式使用了。

Codex 桌面应用

Codex 桌面应用是 macOS 上的原生应用,提供独立的工作区界面,无需安装 Node.js 环境即可使用,适合以"项目"为单位的 AI 开发工作。

获取与安装

访问 OpenAI 官网 Codex 页面下载 macOS 版本
将应用拖入 Applications 文件夹
首次启动使用 ChatGPT 账号登录

主要界面

会话列表:管理多个并行任务会话
对话区:与 Codex 交互的主区域
文件浏览器:查看 Codex 生成/修改的文件
任务状态:查看运行中任务与执行日志

创建项目会话

点击"新建会话",选择或创建项目文件夹,即可开始工作。桌面应用会在项目目录中维护 Codex 的状态文件,支持随时恢复。

与 CLI 的关系

桌面应用与 CLI 共享底层能力与配置,可以混用:桌面应用适合可视化管理,CLI 适合脚本化与集成到现有终端工作流。

实用技巧

用 ⌘N 快速新建会话
在会话中 @ 引用其他任务结果
把常用任务保存为模板
开启"自动测试"开关,让 Codex 每次修改后自动运行测试

桌面应用降低了上手门槛,是体验 Codex 完整能力的最快路径。

Codex 基础入门

本节通过一个完整的小任务,演示 Codex 的典型工作流:理解需求 → 规划 → 写代码 → 运行验证 → 交付结果。

任务示例:创建命令行待办工具

在空目录中启动 Codex,输入:

创建一个 Python 命令行待办清单工具:
- 支持 add/list/done 三个子命令
- 数据持久化到本地 JSON 文件
- 运行 python todo.py add "买牛奶" 添加,list 列出,done 标记完成

Codex 的执行过程

规划:确定文件结构(单文件实现、JSON 存储)
编写:todo.py 的完整代码
验证:自动运行 python todo.py 测试各命令
修正:根据运行结果修复问题并复测

与 Codex 沟通的要点

描述"要什么",而不是"怎么做"
给出验收标准(如命令行用法示例)
明确约束(语言、依赖、是否允许修改某文件)
迭代反馈:不满意直接说"改成 X"

常用操作模式

# 修改现有代码
codex "给 todo.py 增加 edit 子命令,支持修改已存在的事项"

# 修复问题
codex "运行测试,修复所有失败用例"

# 代码审查
codex "审查我最近的改动,指出潜在问题"

结果验收

Codex 完成后,亲自运行一遍关键路径,检查产物是否符合预期。发现偏差就继续对话修正——这是"人机协作"的正常节奏。

掌握基础工作流后,就可以学习配置定制、权限管理等进阶能力了。

Codex 接入 DeepSeek (官方)

OpenAI 曾与 DeepSeek 合作,支持在 Codex 中接入 DeepSeek 模型,为开发者提供更多模型选择。本节介绍官方接入方式。

说明

通过配置自定义模型端点,Codex 可以调用 DeepSeek 的 API。适合希望使用 DeepSeek 编码模型的开发者,或在成本敏感场景下的备选方案。

获取 DeepSeek API Key

注册 DeepSeek 开放平台账号
创建 API Key(注意保管,勿泄露)
确认账户有余额

配置 Codex

# ~/.codex/config.toml
[model_providers.deepseek]
name = "deepseek"
base_url = "https://api.deepseek.com/v1"
env_key = "DEEPSEEK_API_KEY"

[model]
provider = "deepseek"
model = "deepseek-chat"

环境变量

export DEEPSEEK_API_KEY="sk-你的DeepSeek密钥"

切换与验证

codex "你好,请确认当前模型,并写一个快速排序"

注意事项

不同模型的工具调用能力有差异,复杂任务建议使用 Codex 原生模型
DeepSeek 的上下文长度与 Codex 默认配置可能不同,按需调整 max_tokens
敏感项目注意数据合规,确认模型服务商的数据政策

官方接入方式让模型选择更灵活。下一节介绍社区工具 CCSwitch 的多模型切换方案。

Codex DeepSeek (CCSwitch)

CCSwitch 是社区开发的模型切换工具,支持在 Codex、Claude Code 等多个 AI 编程工具之间一键切换底层模型服务商,包括 DeepSeek、通义千问等。

CCSwitch 是什么

CCSwitch(Codex Config Switch)通过改写工具的配置文件,实现模型供应商的快速切换。它维护一套配置模板,切换时自动备份与恢复。

安装

# 通过 Homebrew 或 npm 安装
brew install ccswitch
# 或
npm install -g ccswitch

基本用法

# 列出可用配置
ccswitch list

# 切换到 DeepSeek
ccswitch use deepseek

# 新增自定义供应商
ccswitch add my-provider --base-url https://api.xxx.com/v1

# 查看当前配置
ccswitch current

配置 DeepSeek

ccswitch add deepseek \
  --base-url https://api.deepseek.com/v1 \
  --model deepseek-chat \
  --env-key DEEPSEEK_API_KEY

原理说明

CCSwitch 本质是配置管理:切换时更新 ~/.codex/config.toml 中的 provider/model 字段,并校验 API Key 连通性。因此需要正确配置 API Key 环境变量。

适用场景

预算有限时切到低价模型跑日常任务
特殊任务需要特定模型能力
体验不同厂商的编码模型表现

注意事项

切换前确认目标供应商 API 可用且 Key 有效
部分高级功能(如沙箱、长上下文)可能依赖特定模型
保持工具与 CC 配置版本兼容

CCSwitch 让"模型自由"变得简单。不过要注意,第三方接入可能存在兼容性问题,官方支持路径更稳妥。

Codex App 界面说明

本节省略 Codex 桌面应用与 ChatGPT 内嵌界面中的常见界面元素,帮助你快速上手,不再迷路。

主布局

左侧栏:会话列表、项目切换、设置入口
中间区:对话时间线,AI 与用户的交流记录
右侧栏:任务详情、文件变更、执行日志
底部输入框:消息输入、附件上传、@ 引用

关键图标与状态

🔒 沙箱状态:显示当前权限模式
▶ 任务运行中 / ⏸ 暂停 / ✅ 完成 / ❌ 失败
📄 文件变更:绿色新增、黄色修改、红色删除
🧩 工具调用:查看 Codex 使用了哪些工具

会话管理

新建会话:开始独立任务
继续会话:恢复历史上下文
归档会话:清理列表,保留记录
导出会话:分享或备份对话记录

输入技巧

# 附加文件
@file path/to/file.py "优化这个文件的性能"

# 引用会话
@task 上一个会话 "基于那个结果继续"

# 指定行为
"只读分析,不要修改任何文件"

设置入口

设置中可调整:模型选择、权限级别、沙箱网络策略、自动测试开关、主题与快捷键等。建议初次使用先检查模型与权限配置。

常见问题

任务卡住:检查右侧日志,必要时中断重试
找不到设置:点击左下角头像进入
中文显示乱码:检查系统语言与字体

熟悉界面后,开发效率会有质的提升。建议花 10 分钟把每个区域点一遍。

Codex 配置与定制

Codex 通过 TOML 配置文件实现高度定制:模型、权限、行为、外观都可以按需调整。配置文件分为全局(~/.codex/config.toml)与项目级(.codex/config.toml)两层,项目级覆盖全局。

配置结构概览

# ~/.codex/config.toml
[model]
model = "gpt-5.2-codex"

[permissions]
allow = ["Bash(git:*)", "Read(**)"]
deny = ["Bash(rm -rf *)"]

[context]
ignore = [".git", "node_modules", "dist"]

[display]
theme = "dark"

模型配置

[model]
model = "gpt-5.2-codex"        # 主模型
provider = "openai"            # 供应商

权限配置

[permissions]
# 自动允许:git 命令与读取任意文件
allow = ["Bash(git:*)", "Read(**)"]
# 自动拒绝:危险操作
deny = ["Bash(rm -rf *)", "Bash(sudo *)"]
# 其余操作询问确认

上下文控制

[context]
ignore = [".git", "node_modules", "dist", "*.lock"]
include = ["src/**", "README.md"]

[context.instructions]
path = "AGENTS.md"   # 自动注入项目指南

工作区与网络

[workspace]
path = "/path/to/project"

[sandbox]
network = "local"     # none / local / full

查看与测试配置

codex config show          # 查看生效配置
codex doctor               # 检查环境健康度

配置改动即时生效(无需重启),建议在项目根目录放一份 .codex/config.toml,让团队共享一致的 AI 工作约定。

Codex 高级配置

高级配置面向进阶用户:自定义模型供应商、调整上下文策略、深度定制提示词与工具行为。本节覆盖最实用的几个方向。

自定义供应商

[model_providers.my_company]
name = "my-company"
base_url = "https://llm.internal.example.com/v1"
env_key = "MY_API_KEY"

[model]
provider = "my_company"
model = "my-coder-v1"

上下文窗口管理

[context]
max_tokens = 128000          # 上下文上限
auto_compact = true          # 超限自动压缩
history_lines = 200          # 保留的历史行数

# 压缩时保留关键信息
[context.compact_preserve]
patterns = ["TODO", "FIXME", "security"]

自定义提示词模板

[prompt_templates]
review = "请以资深工程师视角审查以下代码,关注安全与性能:\n{{diff}}"

# 用法
# codex --template review "审查这个 PR"

工具行为定制

[tools.bash]
timeout_seconds = 60         # 命令超时
auto_confirm_categories = ["git", "ls", "cat"]

[tools.edit]
confirm_large_changes = true # 大改动确认

日志与调试

[logging]
level = "debug"
file = "/tmp/codex.log"

# 环境变量方式
# CODEX_LOG_LEVEL=debug codex "任务"

团队共享配置

# 项目 .codex/config.toml 可被提交到 Git
# 团队通过 AGENTS.md 约定编码规范
# 敏感配置用环境变量注入,勿入库

高级配置的黄金法则:能用配置表达的约定,就不要靠口头提醒。把团队的编码规范、安全检查写进配置文件,AI 与人都受益。

Codex 权限设置

权限设置是安全使用 Codex 的核心:控制它"能读什么、能写什么、能执行什么命令"。合理的权限配置既保障效率,又守住安全底线。

权限模型

Codex 对每个操作请求都会做权限判断,结果是三种之一:允许(allow)、拒绝(deny)、询问(ask)。匹配规则优先级:精确 deny > 精确 allow > 通配规则 > 默认询问。

常用配置

[permissions]
# 自动允许的安全命令
allow = [
  "Read(**)",
  "Edit(**)",
  "Bash(ls:*)",
  "Bash(git status:*)",
  "Bash(python *.py:*)",
]

# 危险操作一律拒绝
deny = [
  "Bash(rm -rf *)",
  "Bash(sudo *)",
  "Bash(shutdown:*)",
]

# 也可以要求特定目录必须询问
ask = ["Write(/etc/**)", "Write(/usr/**)"]

交互式授权

未在规则内的操作,Codex 会弹出询问。你可以选择"允许一次""始终允许"或"拒绝"。始终允许的操作会被记录,下次自动通过。

沙箱与权限的关系

[sandbox]
mode = "workspace-write"   # 默认:只能写工作区
network = "local"          # 网络受限

# 完全只读模式(审查场景)
# mode = "read-only"

# 完全自由(高风险,慎用)
# mode = "danger-full-access"

企业场景

# 管理员可下发策略文件
# /etc/codex/policy.toml
[policy]
allow = ["Read(**)"]           # 只读
deny = ["Bash(git push:*)"]    # 禁止推送
require_mfa = true             # 敏感操作二次确认

权限审计

codex permissions list       # 查看已授予的权限
codex permissions revoke     # 撤销某项授权
codex audit --since 24h      # 查看操作审计日志

最佳实践

最小授权:只给任务必需的权限
只读模式用于代码审查与学习场景
禁止 Codex 直接操作生产环境
定期清理已授予的"始终允许"项

记住:权限越细,越安全。宁可多一次确认,也不要让 AI 在不知情的情况下执行危险操作。

Codex 斜杆 / 命令

Codex 斜杠 / 命令

斜杠命令(以 / 开头)是 Codex 中的快捷指令,用于触发预定义行为,如查看帮助、管理会话、调用模板等,类似 Discord/聊天机器人的斜杠命令。

常用命令一览

命令	功能
`/help`	显示帮助信息
`/new`	开启新会话
`/resume`	恢复之前的会话
`/status`	查看当前任务状态
`/model`	切换模型
`/permissions`	管理权限
`/clear`	清空上下文
`/config`	查看或修改配置

在 CLI 中使用

# 启动后输入斜杠命令
$ codex
> /help
> /model gpt-5.2-codex

# 直接在命令行传参
codex --resume 4d8f2a1e

自定义斜杠命令

通过配置可以定义自己的快捷命令:

# ~/.codex/config.toml
[commands.review]
description = "代码审查"
prompt = "请审查最近的代码改动,重点关注:安全性、性能、可读性。\n{{args}}"

[commands.test]
description = "运行测试并修复"
prompt = "运行项目测试,修复所有失败的用例,然后再次验证。\n{{args}}"

# 使用
> /review 重点看 auth 模块
> /test

会话内快捷操作

/continue:中断后继续上次任务
/compact:手动压缩上下文
/export:导出会话记录
/undo:撤销上一步文件修改(部分版本支持)

最佳实践

把高频任务做成自定义斜杠命令,统一团队工作流
命令模板中使用 {{args}} 传递参数,更灵活
团队共享命令配置:放入项目 .codex/config.toml 并提交 Git

斜杠命令是提升效率的杠杆:一次配置,长期复用。建议把团队的"代码审查""测试修复""发布前检查"都做成命令。

Codex 电脑操控

Codex 不仅操作代码,还能在一定范围内操控电脑:运行命令、管理文件、启动服务、操作系统界面,成为一个"全能助手"。

能做什么

执行终端命令与脚本
创建、复制、移动、删除文件
启动开发服务器、数据库等本地服务
管理进程(查看、终止)
在受控模式下操作图形界面应用

终端操控示例

codex "启动项目开发服务器,并确认能访问"

codex "查看 8000 端口占用,并结束对应进程"

codex "把 /tmp 下所有 .log 文件打包成 logs.tar.gz"

文件系统操作

codex "统计 src 目录下各语言文件数量"

codex "查找所有 TODO 注释,汇总到 report.md"

开发环境管理

codex "检查 Python 环境依赖,修复版本冲突"

codex "初始化 git 仓库,创建 .gitignore,提交初始代码"

安全边界

电脑操控受权限与沙箱双重约束:

默认只能访问工作区与明确授权的目录
破坏性命令(rm、格式化)默认需确认
网络访问默认受限,可配置放开
涉及系统级修改(安装软件、改系统配置)需显式授权

使用建议

把 Codex 当成"实习生":给出明确任务边界
涉及重要数据的操作,先让 Codex 列计划再执行
复杂操作分步进行,逐步验收
永远在开发环境而非生产环境授权

电脑操控能力让 Codex 从"写代码"升级为"干活"。能力越大,责任越大——权限与沙箱设置是使用该能力的前提。

Codex 进阶使用技巧

掌握本节技巧,让 Codex 从"能用"变"好用":上下文管理、任务拆解、结果验证、效率最大化。

技巧一:写好任务描述

# 不好的描述
"优化这个项目"

# 好的描述
"优化 src/api 目录下的请求模块:
1. 统一错误处理,返回标准错误格式
2. 超时时间从 10s 调到 5s
3. 增加请求重试(最多3次,指数退避)
4. 运行现有测试确保不破坏功能"

技巧二:控制上下文

单会话聚焦一个目标,任务太大就拆分
无关文件用 ignore 排除,减少噪声
上下文将满时用 /compact 压缩,或新开会话
关键背景信息(架构、约束)写在 AGENTS.md 自动注入

技巧三:善用迭代

# 先小步实现,再逐步扩展
codex "先实现用户登录的基础版本,不接数据库,用内存存储"

# 通过后再迭代
codex "现在把用户存储换成 SQLite,保持接口不变"

技巧四:让 Codex 自我验证

codex "实现功能后,必须:
1. 运行测试
2. 手动跑一个冒烟用例
3. 检查代码风格(lint)
全部通过再报告完成"

技巧五:并行与委派

# 拆成独立子任务,用子代理并行处理
codex "用子代理并行完成:
A. 重构 utils 模块
B. 补充 API 文档
C. 编写单元测试
各自完成后汇总报告"

技巧六:利用速查与模板

常用操作做成斜杠命令
沉淀团队的 AGENTS.md 项目指南
把"好的提示词"整理成文档供团队复用

进阶技巧的核心是"把 Codex 当专业同事":讲清楚背景、目标、约束与验收标准,它就能输出稳定高质量的结果。

Codex 速查表

本节汇总 Codex 最常用的命令、配置与操作,供日常快速查阅。

CLI 常用命令

codex                            # 交互模式
codex "任务描述"                  # 直接任务
codex --version                  # 版本
codex login                      # 登录
codex logout                     # 登出
codex doctor                     # 环境体检
codex config show                # 查看配置
codex --resume <会话ID>          # 恢复会话
codex -y "任务"                  # 全自动(不询问)
codex -s "任务"                   # 严格模式(只读+沙箱)

会话内斜杠命令

/help       /new        /resume     /status
/model      /permissions /clear      /compact
/config     /export     /undo       /continue

常用配置片段

[model]
model = "gpt-5.2-codex"

[permissions]
allow = ["Read(**)", "Edit(**)", "Bash(git:*)", "Bash(ls:*)", "Bash(python *.py:*)"]
deny = ["Bash(rm -rf *)", "Bash(sudo *)"]

[context]
ignore = [".git", "node_modules", "dist"]

[sandbox]
network = "local"

常用环境变量

OPENAI_API_KEY         # API 密钥
CODEX_LOG_LEVEL        # 日志级别 debug/info
CODEX_CONFIG_PATH      # 自定义配置文件路径
DEEPSEEK_API_KEY       # DeepSeek 密钥(接入时)

提示词速记

明确目标 + 约束 + 验收标准
"运行测试并修复" 强制验证
"只读分析" 用于审查场景
"列出计划再执行" 先规划后动手
"解释你的思路" 了解决策过程

排查问题

codex doctor                  # 环境问题
codex config show             # 配置问题
cat ~/.codex/logs/codex.log   # 日志
codex --debug "任务"           # 调试模式

把本页截图或打印出来,放在手边。遇到"不知道用什么命令"时,先查速查表。

Codex IDE 扩展

Codex 提供 IDE 扩展,让你在熟悉的编辑器环境中使用 AI 编程能力:内联代码生成、选中代码重构、终端集成等。

支持的 IDE

VS Code(官方扩展)
Cursor(内置兼容)
JetBrains 系列(社区/官方支持)
其他 LSP 兼容编辑器

安装(以 VS Code 为例)

# 扩展市场搜索 "Codex" 安装
# 或命令行安装
code --install-extension openai.codex

核心功能

内联补全:光标处智能补全代码
选中重构:选中代码,用自然语言描述修改
对话面板:右侧打开 Codex 对话,关联当前文件
问题修复:根据报错直接让 Codex 修复
终端命令:在 IDE 终端中运行 codex 命令

典型使用场景

# 场景1:重构选中函数
选中函数 → ⌘K 输入 "用 ES6 语法重写这个函数"

# 场景2:解释报错
鼠标悬停红色波浪线 → "解释这个错误并给修复方案"

# 场景3:生成测试
选中文件 → "为这个模块生成单元测试"

快捷键参考

⌘K / Ctrl+K    打开 Codex 对话
⌘I / Ctrl+I    内联编辑
⌘L / Ctrl+L    选中代码到对话

与 CLI 的关系

IDE 扩展底层调用 Codex CLI/API,共享登录与配置。在 IDE 中的权限设置与 CLI 一致,敏感操作同样会询问。

最佳实践

把 IDE 扩展用于"局部小改",CLI 用于"整仓任务"
让 Codex 生成代码后,务必自己 review 一遍
结合官方 Git 集成,让 Codex 帮助处理合并冲突

IDE 扩展降低了 AI 编程的门槛:不用离开编辑器,就能获得完整的 AI 辅助能力。

Codex 命令行工具

Codex CLI 是功能最完整的使用形态:适合脚本化、集成 CI、批量任务,以及习惯终端的开发者。本节系统介绍 CLI 的用法。

安装与登录

npm install -g @openai/codex
codex login

交互模式

codex
> 检查当前仓库,列出主要模块和它们的职责
> 帮我重构 config 解析部分,保持对外接口不变

非交互模式(脚本化)

# 单次任务
codex "修复 src/app.py 的编码问题"

# 从文件读取任务
codex < task.txt

# 带上下文
codex --include-path src/ "为 utils 模块补测试"

常用参数

-y, --yes          全自动,跳过所有确认
-s, --strict       严格模式(只读+沙箱)
-m, --model        指定模型
--resume <id>     恢复会话
--include-path     附加上下文路径
--debug            调试模式
--json             输出 JSON(便于解析)

脚本集成示例

#!/bin/bash
# 在 CI 中自动修复 lint 问题
codex -y "运行 eslint,自动修复所有可修复的问题,运行测试确认" \
  --include-path src/ || exit 1

会话管理

codex --resume            # 交互选择历史会话
codex sessions list       # 列出会话
codex sessions export <id>  # 导出会话 JSON

日志与审计

# 所有操作记录在 ~/.codex/logs/
# 审计:查看 Codex 执行过的命令
grep "bash" ~/.codex/logs/*.log | tail

最佳实践

日常开发用交互模式,自动化用 -y + 明确约束
CI 中给足超时时间,并设置 timeout_seconds
敏感仓库务必用 -s 严格模式或受限权限

CLI 是 Codex 能力最完整的入口,也是把它接入自动化体系的唯一方式。掌握 CLI 参数,等于解锁 Codex 的全部潜力。

Codex 云端版本

Codex 云端版本在 OpenAI 的云沙箱中运行,无需本地安装任何环境,从浏览器即可使用,适合快速原型、临时项目与多设备协作。

特点

零安装:浏览器直接使用
云端沙箱:代码在云端执行,不占本地资源
随处访问:换设备也能继续任务
预置环境:常用语言/工具链开箱即用

典型使用场景

快速验证想法与原型
学习新语言/框架(环境已配好)
临时性的一次性任务
在不方便装环境的机器上开发

与本地版本的区别

维度	云端	本地 CLI
环境	云端沙箱	本机
安装	无需	需要 Node.js
性能	受网络影响	本地速度快
隐私	代码上传云端	代码留在本地
集成	受限	完整(CI/IDE)

使用流程

打开 Codex 云端页面并登录
新建工作区(可选择预置模板)
描述任务,Codex 在云端沙箱中执行
通过文件浏览器查看结果,可下载到本地

数据与安全注意

敏感代码不建议使用云端版本
注意云端工作区的生命周期(定期清理)
涉及外部服务的凭据勿写入代码

云端版本是"随时随地开发"的最佳选择。生产项目建议本地 CLI + IDE 组合,兼顾安全与效率。

Codex 集成与连接

Codex 不是孤岛:通过 API、CLI、MCP 与 Webhooks,可以把它集成到你的工具链、团队流程与第三方服务中。

集成方式总览

方式	适用场景
CLI 脚本调用	CI/CD、定时任务、批处理
Responses API	自有应用内嵌 Codex 能力
MCP	连接外部工具与数据源
IDE 扩展	开发者日常编码
Webhooks/回调	任务完成通知、状态同步

CLI 集成到 CI

# .github/workflows/ai-fix.yml 片段
- name: AI 自动修复
  run: |
    codex -y "运行测试,自动修复失败,提交修复" \
      --include-path src/ test/
  env:
    OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

通过 API 集成

# Python 调用 Codex Responses API(示意)
import openai

client = openai.OpenAI()
resp = client.responses.create(
    model="gpt-5.2-codex",
    input="修复 src/utils.js 的 bug 并提交",
    tools=[{"type": "code_interpreter"}]
)
print(resp.output_text)

MCP 连接外部系统

# .codex/mcp.json 注册外部服务
{
  "mcpServers": {
    "internal-api": {
      "command": "npx",
      "args": ["-y", "@myco/internal-api-mcp"]
    }
  }
}

与版本管理集成

# 让 Codex 操作 Git
codex "创建 feature 分支,实现新功能,提交并推送到远端"

通知与监控

# 任务结束通过 hook 通知(示意)
[hooks.on_task_complete]
command = "curl -X POST https://hooks.slack.com/xxx -d '{"text":"任务完成"}'"

集成注意事项

API Key 用 secrets 管理,绝不硬编码
CI 中限制 Codex 权限(只读/受限沙箱)
为长时间任务设置超时与失败重试
记录 Codex 的操作日志用于审计

集成的本质是"把 AI 编程能力接入现有流程"。从最小可用集成开始,逐步扩展边界。

Codex 自动化与 CI/CD

Codex 可以在 CI/CD 流水线中承担自动化开发任务:自动修复构建失败、自动补测试、自动生成变更说明等,让 AI 成为持续开发流水线的一员。

典型自动化场景

构建/测试失败自动修复并重跑
PR 自动审查与建议
自动生成 CHANGELOG 与文档
依赖升级后的兼容性修复
定时执行维护任务(清理、重构)

GitHub Actions 示例

name: AI Test Fixer
on:
  workflow_run:
    workflows: ["CI"]
    types: [completed]

jobs:
  fix:
    runs-on: ubuntu-latest
    if: ${{ github.event.workflow_run.conclusion == 'failure' }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @openai/codex
      - name: AI 修复测试
        run: |
          codex -y "运行测试,修复失败的用例并提交" \
            --include-path src/ test/
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

GitLab CI 示例

ai_fix:
  stage: fix
  only:
    - schedules
  script:
    - npm install -g @openai/codex
    - codex -y "检查所有 TODO,处理简单的项并提交"
  env:
    OPENAI_API_KEY: $AI_KEY

安全护栏

# CI 中建议使用严格配置
codex -s -y "..."          # 严格模式
# 或限制权限
# deny = ["Bash(git push:*)"]  # 只修复不推送

质量保障

AI 修改必须通过原有测试门禁才能合入
设置"人工 review"门槛:AI 的提交先开 PR
记录 AI 操作日志,便于回溯
限制单次任务的改动范围

成本控制

只在失败/调度时触发,而非每次构建
控制任务复杂度,避免长任务空转
设置超时与 token 上限

把 Codex 放进 CI/CD 要遵循一个原则:AI 是"候选者",不是"发布者"——它的产出必须经过测试与人工确认。

Codex 工作流模式

针对不同任务类型,Codex 有对应的高效工作流。本节总结几种常用模式,以及它们的最佳适用场景。

模式一:对话式开发

交互式对话,边聊边改,适合探索性任务与需求澄清。

codex
> 我想给网站加一个暗色模式
> 具体说说你希望哪些部分变暗、是否有切换按钮

模式二:任务委派

一次性下达完整任务,Codex 独立完成,适合边界清晰的任务。

codex "实现用户注册功能:邮箱+密码,校验格式,存入 SQLite,附测试"

模式三:先计划后执行

先让 Codex 输出方案,确认后再动手,适合高风险/大改动。

codex "先分析现有架构,给出数据库迁移方案,不要执行,等我确认"

模式四:审查模式(只读)

codex -s "审查 src/ 下代码,输出问题清单与修改建议,不要修改文件"

模式五:并行子任务

codex "用子代理并行:1) 重构 auth 2) 补订单模块测试 3) 写 API 文档,完成后汇总"

模式六:持续会话

长任务跨天进行,用 resume 恢复,适合大型重构。

codex --resume
> 继续昨天的重构,先看当前进度

选择建议

场景	推荐模式
需求不明确	对话式
任务清晰	任务委派
大改动	先计划后执行
代码审查	只读审查
多模块并行	子代理
长周期任务	持续会话

工作流模式不是固定的:一个复杂任务可以组合多个模式。关键是"按任务的确定性选择介入程度"——越不确定,越要多确认。

Codex 提示词最佳实践

提示词的质量直接决定 Codex 的输出质量。本节总结经过验证的提示词编写方法,让你的任务一次到位。

好提示词的四个要素

目标:明确要达成的结果
背景:提供必要的上下文
约束:限制范围、方式、风格
验收:说明如何判断完成

对比示例

# ❌ 模糊
"优化登录功能"

# ✅ 完整
"优化登录接口:
- 背景:现有 /api/login 用明文密码
- 目标:改为 bcrypt 哈希校验,兼容已注册用户
- 约束:保持接口返回格式不变,不引入新依赖
- 验收:单元测试通过,手动用 curl 验证新旧密码均可登录"

明确"不要做什么"

codex "重构缓存模块,注意:
- 不要改变对外 API
- 不要动测试文件
- 不要引入新的第三方库
- 保持与现有代码风格一致"

让 Codex 验证自己的工作

codex "实现 X 功能后,必须运行测试并汇报结果,全部通过才算完成"

复杂任务分步描述

codex "按以下步骤执行:
1. 阅读 src/auth.py,总结当前逻辑
2. 设计 token 刷新方案(写 200 字设计说明)
3. 实现代码并补测试
4. 运行全部测试
每一步都汇报后再继续"

提供示例(少样本提示)

codex "参照现有 utils/format.py 的写法风格,实现:
- format_phone 手机号脱敏
- format_card 银行卡脱敏
输出格式与现有函数保持一致"

追问与澄清

> 你有几个地方不确定:数据库表结构?错误码规范?
> 先查项目里有没有现成约定,没有再问我

常见失败模式

一次给太多无关上下文(噪声)
没有验收标准(Codex 自认为完成就停)
任务过大(超上下文/超时)
表述矛盾(既说 A 又说不要 A)

提示词像需求文档:写得越清楚,返工越少。把常用的优秀提示词沉淀到团队文档,形成"提示词库"。

Codex 安全与企业管理

企业级使用 Codex 需要关注:数据安全、权限管控、审计合规与团队协作。本节梳理企业落地的关键点。

数据安全

敏感代码/数据不发送给第三方模型服务
企业版支持私有部署或数据不落盘的合规模式(视产品版本)
API Key 通过密钥管理服务(如 Vault)分发,不硬编码
日志脱敏:防止日志泄露 token 与用户数据

权限管控

# 企业策略示例:统一只读+白名单
[policy]
allow = ["Read(**)"]
deny = ["Bash(git push:*)", "Bash(rm -rf *)"]
require_mfa = true

# 按团队区分策略
[policy.teams.backend]
allow = ["Read(**)"]

审计与合规

记录 Codex 执行的所有命令与文件变更
定期导出审计日志,纳入安全审查流程
对 AI 生成的代码做依赖漏洞扫描
遵守企业数据出境与合规要求

团队协作

# 统一团队配置(提交到仓库)
.codex/config.toml
AGENTS.md          # 团队编码规范

AGENTS.md 沉淀团队约定:命名规范、提交规范、禁止事项
Codex 的改动一律走 PR + 人工 review
建立"AI 使用手册",培训团队成员

风险控制

生产环境操作永远禁止 Codex 直连
大额操作(批量删除、数据迁移)双重确认
设置任务超时与 token 预算
紧急熔断:发现异常立即撤销权限并审计

落地路线图

试点:小团队 + 只读模式 + 简单任务
规范:制定权限矩阵与 AGENTS.md
推广:全员培训 + 统一配置
治理:审计、合规、持续优化

企业引入 AI 编程工具,核心是"用制度管住能力":权限最小化、全程可审计、产出必 review。

Codex 模型选择

Codex 支持切换底层模型,不同模型在编码能力、速度、成本与上下文长度上各有差异。选对模型,事半功倍。

模型维度对比

维度	旗舰模型	均衡模型	轻量模型
编码能力	最强	良好	基础
速度	较慢	适中	快
成本	高	中	低
适用	复杂重构/架构	日常开发	简单脚本/补全

选择策略

复杂任务(重构、调试、架构设计)→ 旗舰模型
日常任务(写功能、改 Bug)→ 均衡模型
简单任务(格式化、补测试模板)→ 轻量模型
批量任务考虑成本优先

切换方式

# 会话内切换
> /model gpt-5.2-codex

# 启动时指定
codex -m gpt-5.2-codex "任务"

# 配置默认
# [model]
# model = "gpt-5.1-codex"

上下文长度注意

模型上下文窗口不同:大仓库任务需要长上下文模型;短任务用短上下文模型更省钱。上下文将满时及时 /compact。

第三方模型(如 DeepSeek)

通过自定义 provider 接入,但注意:第三方模型对 Codex 工具调用的支持可能不完整,复杂任务优先使用官方模型。

评估方法

# 用真实任务做对比测试
codex -m modelA "修复 src/main.py 的两个 bug"
codex -m modelB "修复 src/main.py 的两个 bug"
# 对比:正确率、耗时、改动质量、成本

模型选择没有绝对最优,建议团队固定 2-3 个常用模型组合,并沉淀"什么任务用什么模型"的决策规则。

Codex Agent Skills

Agent Skills(代理技能)是 Codex 的扩展能力机制:把特定领域的专业知识与操作流程打包成技能,Codex 遇到相关任务时自动加载使用。

什么是 Skills

Skills 是一组"知识 + 工具 + 指令"的组合,类似给 AI 安装的"专业插件"。例如:一个"Python 打包技能"知道如何正确构建 wheel 包,包括版本号规范、依赖声明、发布检查等完整流程。

Skills 目录结构

~/.codex/skills/
└── python-packaging/
    ├── SKILL.md          # 技能说明(触发条件+使用步骤)
    ├── scripts/          # 辅助脚本
    └── references/       # 参考资料

SKILL.md 示例

---
name: python-packaging
description: 用于构建和发布 Python 包。当任务涉及 setup.py、
  pyproject.toml、wheel 构建或 PyPI 发布时使用。
---

# Python 打包流程
1. 检查 pyproject.toml 配置
2. 验证版本号与依赖
3. 运行 python -m build 构建
4. 检查产物并建议发布方式

使用方式

# 自动触发:任务匹配技能描述时 Codex 会主动加载
codex "构建这个包的 wheel 并检查"

# 手动指定
codex "使用 python-packaging 技能发布这个包"

内置技能与社区技能

官方提供常用技能集(skills 命令可查看)
社区分享技能仓库,codex skills install <名称> 安装
企业可构建私有技能库,沉淀内部规范

技能管理命令

codex skills list
codex skills install <name>
codex skills remove <name>
codex skills create <name>   # 创建模板

编写技能的最佳实践

description 写清楚"何时触发",让自动匹配更准
步骤具体可执行,避免泛泛而谈
可复用的检查项/命令写在 references
小技能优先:单一职责,便于组合

Skills 是把团队经验固化给 AI 的最佳载体。建议把团队的高频操作流程逐步沉淀为技能库。

Codex 子代理

子代理(Sub-agents)允许 Codex 同时委派多个独立任务并行执行,大幅提升多模块项目的处理效率。

为什么需要子代理

一个 Codex 会话是串行工作的。面对"重构 3 个独立模块 + 补文档 + 写测试"这类多任务,串行很慢;子代理让多个任务并行推进,总耗时接近最慢的那个。

工作原理

主代理(协调)
├── 子代理 A:重构 utils 模块
├── 子代理 B:补充 API 文档
└── 子代理 C:编写单元测试
    ↓ 各自完成后
主代理汇总结果,处理冲突

使用示例

codex "用子代理并行完成以下任务:
1. 重构 src/utils.py,拆分过长函数
2. 为 src/api 模块补充 docstring
3. 编写 tests/test_models.py
任务间无依赖,各自独立完成后汇总改动报告"

适用场景

无依赖的多文件/多模块改动
重复性任务(批量生成测试、文档)
大型重构拆分

注意事项

子代理修改同一文件会冲突,任务要按文件隔离
主代理负责最终整合与冲突解决
子代理过多会消耗更多 token,按需启用
关键任务不要并行,确保质量优先

配置与查看

# 部分版本可配置并行数
# [agent]
# max_sub_agents = 3

# 在界面/日志中查看子代理状态

最佳实践

先规划"任务分解",再决定是否并行
每个子任务描述要自包含(背景+目标+验收)
冲突风险高的改动(公共接口)留给主代理

子代理是 Codex 处理大规模任务的利器,但"并行"的前提是"解耦"。合理的任务分解比盲目并行更重要。

Codex MCP

MCP(Model Context Protocol,模型上下文协议)是让 AI 连接外部工具与数据的开放标准。Codex 通过 MCP 服务器访问数据库、浏览器、内部 API 等外部资源。

MCP 是什么

MCP 定义了"AI 应用 ↔ 工具服务器"的统一协议:工具服务器通过 MCP 暴露能力(查询、操作),AI 应用按标准调用。一次接入,到处可用。

MCP 能带来什么

直接查询数据库、读取外部数据
操作浏览器做自动化测试
调用内部系统 API(工单、监控、部署)
连接知识库、搜索服务等

配置 MCP 服务器

# .codex/mcp.json(项目级)或 ~/.codex/mcp.json(全局)
{
  "mcpServers": {
    "mysql": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-mysql"],
      "env": {
        "MYSQL_HOST": "localhost",
        "MYSQL_DB": "app_db"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp"]
    }
  }
}

使用 MCP 工具

codex "查询数据库 app_db 中 orders 表的最近 10 条记录,汇总成表格"

codex "用浏览器打开 http://localhost:3000 登录页面,截图检查样式"

管理与排查

codex mcp list          # 查看已配置的 MCP 服务器
codex mcp test <name>   # 测试连接
# 日志: ~/.codex/logs/ 查看 MCP 调用记录

安全要点

MCP 服务器的凭据用环境变量注入,不写配置文件
生产数据库接入前先确认权限边界(只读?)
第三方 MCP 服务器要审查其行为,防止数据外泄
用完的敏感 MCP 连接及时移除

自建 MCP 服务器

# Python 快速实现(示意)
from mcp.server import Server

server = Server("internal-tools")

@server.tool()
def get_deploy_status(env: str) -> str:
    """查询部署状态"""
    return query_status(env)

MCP 让 Codex 从"代码助手"进化成"业务助手"。建议团队先接 1-2 个高价值工具(数据库/内部 API),再逐步扩展。

Codex 规则与钩子

规则(Rules)约束 Codex 的行为边界,钩子(Hooks)在特定事件发生时触发自定义脚本。二者是精细控制 Codex 行为的两大机制。

规则(Rules)

# .codex/rules.md 或 AGENTS.md 中声明
# 编码规范
- 所有函数必须写 docstring
- 禁止使用 eval
- 错误信息使用中文

# 流程约束
- 修改文件前先展示 diff 摘要
- 测试通过前不得标记任务完成

规则类型

项目规则(AGENTS.md):团队约定,随仓库分发
用户规则(~/.codex/rules.md):个人偏好
会话规则:单次会话临时指定

钩子(Hooks)

# ~/.codex/config.toml
[hooks]
# 工具执行前
[hooks.pre_tool]
command = "sh -c 'echo 执行: $TOOL_NAME >> /var/log/codex.log'"

# 工具执行后(检查命令安全)
[hooks.post_tool]
command = "sh -c 'check_safety.sh $COMMAND'"

# 任务完成时
[hooks.on_task_complete]
command = "sh -c 'curl -s -X POST https://hooks.example.com/codex-done'"

# 会话开始
[hooks.on_session_start]
command = "sh -c 'echo new session >> ~/.codex/sessions.log'"

钩子可用事件

事件	触发时机
pre_tool	执行工具前
post_tool	工具执行后
on_task_complete	任务完成
on_session_start	会话开始
on_error	发生错误时

常见用途

审计日志:记录 Codex 全部操作
安全检查:拦截危险命令
通知:任务完成推送到 IM/邮件
自动化:任务完成后自动运行 lint/测试

最佳实践

规则要具体可执行,避免模糊表述
钩子脚本保持幂等、快速、健壮
钩子失败不应阻塞主任务(视需求)
团队规则提交到仓库,统一执行

规则与钩子让 Codex 的行为"可编程"——这是企业级落地的关键能力,务必善用。

Codex 非交互模式

非交互模式(一次执行、无需人工干预)是 Codex 用于脚本化、自动化与 CI 集成的核心模式。通过参数控制,任务自动完成并输出结果。

基本用法

# 单条任务(自动确认)
codex -y "运行测试并修复失败用例"

# 严格模式(只读+沙箱,适合审查)
codex -s "审查代码安全风险"

# 组合使用
codex -y -s "检查代码质量并输出报告,不修改文件"

从文件读取任务

# task.md 中写任务描述
codex -y < task.md

# 输出到文件
codex -y "生成 CHANGELOG" > changelog.md

超时控制

# 配置中设置
[execution]
timeout_seconds = 300

# 或命令行
timeout 300 codex -y "长任务"

输出与退出码

# 成功退出码 0,失败非 0
codex -y "任务" && echo "成功" || echo "失败"

# JSON 输出(脚本解析)
codex --json -y "查询当前 git 状态并总结"

权限预设

# 非交互模式下无人工确认,权限规则更关键
[permissions]
allow = ["Read(**)", "Edit(**)", "Bash(python:*)", "Bash(git status:*)"]
deny = ["Bash(rm:*)", "Bash(curl *)"]

CI 集成示例

#!/bin/bash
set -e
echo "== 运行 AI 修复 =="
codex -y "运行 pytest,修复失败的测试并重新验证" --include-path src/ test/
echo "== 检查是否有未提交改动 =="
git diff --exit-code || git add -A && git commit -m "chore: AI 修复测试"

注意点

-y 跳过确认的同时也意味着"无人把关",权限配置必须收紧
非交互任务描述要极其明确,因为没有追问机会
长时间任务建议先小范围试跑,再全量执行

非交互模式是把 Codex 变成"自动化流水线工人"的关键,配合严格权限与良好提示词,可以放心交给 CI 使用。

Codex AGENTS.md

AGENTS.md 是项目根目录下的"AI 项目指南"文件,Codex 启动时自动读取,作为理解项目与遵守约定的依据。它相当于"给 AI 看的 README"。

为什么需要 AGENTS.md

没有指南的 AI 会用"通用常识"处理项目,而每个项目都有自己的约定:目录结构、命名规范、构建方式、禁区。AGENTS.md 把这些写清楚,AI 的输出质量立刻上一个台阶。

Codex 如何读取

会话开始时自动加载项目 AGENTS.md
可配置多个文件:AGENTS.md、docs/AGENTS.md 等
层级合并:全局 → 用户 → 项目,项目级优先级高

配置加载路径

[context.instructions]
path = "AGENTS.md"
# 支持多个
# paths = ["AGENTS.md", "docs/CODING.md"]

编写建议

内容要"可执行",每条都是 AI 能遵循的指令
优先写"如何验证"(命令),少写空泛口号
与团队代码规范保持一致,定期更新
加入易错点:"这个项目的坑"列表价值极高

示例:易错点部分

## 易错点
- 日期时间统一用 UTC 存储,展示层转本地
- 数据库迁移文件命名必须带时间戳
- 上线前必须跑 npx prisma migrate check

AGENTS.md 是"一次编写,持续受益"的投入。强烈建议每个项目都维护一份,团队和 AI 共同受益。

Codex GitHub 集成

Codex 与 GitHub 的集成包括:操作本地 Git 仓库、通过 GitHub CLI 管理远端、以及 Codex 云端与 GitHub 的深层集成(自动开 PR 等)。

本地 Git 操作

codex "查看当前分支与未提交改动,总结改动内容"

codex "创建 feature-auth 分支,提交当前改动,推送到远端"

codex "合并 main 到当前分支,解决冲突"

GitHub CLI 集成

# 授权 gh 后,Codex 可以操作 GitHub
codex "用 gh 查看最近的 PR,列出需要 review 的"

codex "为当前分支创建 PR,标题'feat: 用户注册',关联 issue #12"

自动创建 PR

codex "完成功能后:
1. 运行测试
2. 提交改动
3. 创建 PR 描述改动内容
4. 附上测试结果"

PR 审查辅助

# 审查远端 PR
codex "审查 PR #45 的代码改动,重点关注安全与性能问题,输出审查意见"

# 结合 CI 状态
codex "查看 PR #45 的 CI 状态,如果失败就分析原因"

GitHub Actions 中的 Codex

# 在 Actions 中调用(之前章节有完整示例)
- run: codex -y "修复失败的测试并提交"

权限与安全

gh token 权限最小化(仅所需仓库)
生产分支保护:AI 的推送走 PR,不直接 push
敏感仓库关闭 Codex 的写权限

最佳实践

# 规范化的 Git 工作流
codex "按规范执行:
1. 从 main 拉取最新
2. 创建分支 feat/xxx
3. 实现功能+测试
4. 提交(规范 message: type(scope): desc)
5. 推送并创建 PR"

GitHub 集成让 Codex 融入标准协作流程:开发、提交、PR、审查全链路 AI 辅助。关键是保持"AI 改动必须走 PR + review"的护栏。

Codex Windows

Codex 在 Windows 上的安装与使用与 Unix 略有差异。本节介绍 Windows 环境的完整配置方案。

安装方式

# 需要 Node.js 18+
# 下载并安装 Node.js LTS(官网)

# 打开 PowerShell,全局安装
npm install -g @openai/codex

# 验证
codex --version

推荐:Windows Terminal + PowerShell 7

# 安装 Windows Terminal(微软商店)
# 安装 PowerShell 7
winget install Microsoft.PowerShell

WSL2 方案(推荐开发场景)

# 在 WSL2(Ubuntu)中安装,体验与 Linux 一致
wsl --install -d Ubuntu
# 在 WSL 内
sudo apt update && sudo apt install -y nodejs npm
npm install -g @openai/codex

路径与权限差异

配置文件目录:%USERPROFILE%\.codex\ 或 ~/.codex/(Git Bash/WSL)
shell 命令默认使用 cmd/PowerShell,注意语法差异
路径含中文与空格时,配置中注意引号

常见问题

# 问题:codex 不是可识别的命令
# 解决:检查 PATH 是否包含 npm 全局目录
npm config get prefix   # 查看路径
# 加入系统 PATH

# 问题:git 命令在 PowerShell 中异常
# 解决:使用 Git Bash 或配置 git for windows 到 PATH

代理配置(国内网络)

# PowerShell
$env:HTTPS_PROXY = "http://127.0.0.1:7890"
$env:HTTP_PROXY = "http://127.0.0.1:7890"
codex login

沙箱说明

Windows 原生沙箱依赖 WSL 或 Docker Desktop;使用 WSL2 方案可以获得与 Linux 一致的沙箱体验。生产使用建议在 WSL2 或 Linux 服务器上运行。

Windows 用户的最佳实践:日常用 Windows Terminal + PowerShell,开发项目放 WSL2 里跑 Codex,兼顾体验与兼容性。

Codex Worktrees 使用

Git Worktree(工作树)允许一个仓库同时检出多个工作目录。Codex 结合 Worktree,可以在隔离目录中安全地尝试改动,不干扰主工作区。

什么是 Worktree

# 创建新工作树(基于某分支/提交)
git worktree add ../codex-experiment -b exp/new-feature

# 列出工作树
git worktree list

# 删除
git worktree remove ../codex-experiment

为什么与 Codex 搭配

隔离实验:AI 的改动不影响当前工作区
并行开发:主分支继续开发,Codex 在独立工作树干活
安全回退:不满意直接丢弃该工作树
CI/沙箱友好:独立目录更接近干净环境

使用流程

# 1. 创建隔离工作树
git worktree add /tmp/ai-feature -b feat/ai

# 2. 在该目录运行 Codex
cd /tmp/ai-feature
codex "实现 X 功能,运行测试,提交"

# 3. 验收后合入
git checkout main
git merge feat/ai

# 4. 清理
git worktree remove /tmp/ai-feature
git branch -d feat/ai

Codex 中的工作树配置

# 部分版本支持自动工作树模式
[worktree]
auto_create = true           # 任务自动创建
base_branch = "main"         # 基于哪个分支
cleanup = "on_success"       # 成功后清理

注意事项

工作树是独立目录,依赖需要重新安装(node_modules 等)
确保主工作区没有未提交改动会冲突
AI 提交后要人工 review 再合并
避免同时在多个工作树操作同一分支

与子代理配合

# 每个子代理一个工作树,彻底隔离
codex "为 3 个模块分别创建工作树并并行实现..."

Worktree 是"让 AI 大胆干活"的保险栓:隔离、可弃、可并。强烈建议团队将其纳入 AI 开发流程。

Codex CLI 配置

CLI 的配置通过 config.toml 与环境变量两层实现,支持全局与项目级覆盖。本节完整梳理 CLI 的配置项。

配置文件位置

~/.codex/config.toml        # 全局配置
~/.codex/config.local.toml  # 本地覆盖(不入库)
.codex/config.toml          # 项目级(可入库)
.codex/config.local.toml    # 项目本地(不入库)

配置优先级

项目级 > 全局;local > 普通。敏感信息(如 token)放 local 文件,并加入 .gitignore。

完整配置示例

[model]
model = "gpt-5.2-codex"

[model_providers.openai]
name = "openai"
base_url = "https://api.openai.com/v1"
env_key = "OPENAI_API_KEY"

[permissions]
allow = ["Read(**)", "Edit(**)", "Bash(git:*)", "Bash(python:*)", "Bash(ls:*)"]
deny = ["Bash(rm -rf *)", "Bash(sudo *)"]

[context]
ignore = [".git", "node_modules", "dist", "*.lock"]

[context.instructions]
paths = ["AGENTS.md", "docs/CODING.md"]

[sandbox]
mode = "workspace-write"
network = "local"

[execution]
timeout_seconds = 300
max_iterations = 50

[display]
theme = "dark"
show_tokens = true

[logging]
level = "info"
file = "~/.codex/logs/codex.log"

环境变量配置

OPENAI_API_KEY=sk-xxx
CODEX_MODEL=gpt-5.2-codex
CODEX_LOG_LEVEL=debug
CODEX_CONFIG_PATH=/custom/path/config.toml
HTTPS_PROXY=http://127.0.0.1:7890   # 代理

常用查看命令

codex config show          # 生效配置(合并后)
codex config set model gpt-5.1-codex   # 修改单项
codex config unset model   # 删除单项
codex doctor               # 环境体检

配置技巧

团队规范写项目 config.toml 并提交,个人偏好写 local
token/密钥一律环境变量注入
权限先收紧再放开:从最小集开始,按需添加
改动配置后重启会话生效

CLI 配置是 Codex 体验的"地基"。花 10 分钟配置到位,后续每天都能省下大量确认与返工时间。

Codex CLI Skills

Skills 机制在 CLI 中通过命令管理,配合配置与目录约定,实现技能的定义、安装、触发与共享。

技能命令

codex skills list                 # 列出已安装技能
codex skills install <name>       # 安装(官方/社区)
codex skills remove <name>        # 卸载
codex skills create <name>        # 创建技能模板
codex skills search <keyword>     # 搜索社区技能

技能目录约定

~/.codex/skills/           # 用户级
.codex/skills/             # 项目级(入库共享)
/etc/codex/skills/         # 企业级

# 技能内结构
my-skill/
├── SKILL.md
├── scripts/install.sh     # 环境准备
├── scripts/run.sh         # 主流程
└── references/guide.md    # 参考资料

SKILL.md 元数据

---
name: docker-ops
description: >
  处理 Docker 相关任务:镜像构建、容器管理、Compose 编排。
  当用户提到 docker、容器、镜像、compose 时自动使用。
version: 1.0.0
---

# Docker 操作流程
## 构建
docker build -t app:latest .
## 运行
docker run -d -p 8080:80 app:latest

触发机制

Codex 分析任务描述,与技能 description 匹配,自动加载匹配技能。也可以显式指定:

codex "使用 docker-ops 技能:检查当前容器状态并重建异常容器"

编写高质量技能

description 精确描述触发场景(自动匹配的关键)
步骤可执行,包含完整命令与检查点
常见错误与排查写进 references
版本化并随仓库分发,团队共享

排查技能问题

codex skills list          # 确认已安装
cat ~/.codex/skills/xxx/SKILL.md   # 检查内容
codex --debug "任务"       # 调试触发情况

CLI 的 Skills 管理让"团队经验"可以像软件一样安装、升级、共享。建议团队从 3-5 个高频技能开始沉淀。

Codex CLI 沙箱与安全

沙箱是 Codex 安全模型的基石:把代码执行限制在隔离环境中,防止 AI 的误操作影响宿主机。理解并正确配置沙箱,是安全使用 Codex 的前提。

沙箱模式

# workspace-write(默认):只允许写工作区,网络受限
[sandbox]
mode = "workspace-write"

# read-only:只读,适合审查
mode = "read-only"

# danger-full-access:完全自由(高风险!)
mode = "danger-full-access"

网络策略

[sandbox]
network = "none"    # 无网络
network = "local"   # 仅本机
network = "full"    # 全部网络(慎用)

权限规则与沙箱配合

[permissions]
# 白名单:只读+git+测试命令
allow = ["Read(**)", "Bash(git:*)", "Bash(pytest:*)"]
deny = ["Bash(rm:*)", "Bash(curl *)", "Bash(wget *)"]
# 其余操作弹窗确认

安全清单

公开/陌生仓库:用 read-only 模式 + 无网络
日常开发:workspace-write + local 网络
涉及密钥/生产:禁止访问敏感目录,deny 关键命令
绝不使用 danger-full-access(除非隔离虚拟机)

敏感信息防护

# 配置忽略敏感文件,避免被读取
[context]
ignore = [".env", "*.pem", "credentials*"]

# 或 deny 读取
[permissions]
deny = ["Read(.env)", "Read(**/*.pem)"]

审计与监控

# 记录操作日志
[logging]
level = "info"
file = "~/.codex/logs/codex.log"

# 用 hook 实现操作审计
[hooks.post_tool]
command = "sh -c 'log_tool.sh >> /var/log/codex-audit.log'"

意外处理

# 发现异常操作
# 1. 立即中断会话(Ctrl+C)
# 2. 检查审计日志
# 3. 撤销已授予的权限
codex permissions revoke --all

沙箱不是"可选项",而是使用 AI 编程代理的"必备护栏"。宁可牺牲一点便利,也要守住安全的底线。

Codex CLI 实用示例

本节提供一组开箱即用的 Codex CLI 实战示例,覆盖开发中的高频场景,可直接复制使用。

1. 代码审查

codex -s "审查最近的 git diff,输出:
- 潜在 bug(带行号)
- 安全问题
- 性能问题
- 改进建议
不要修改文件"

2. 写单元测试

codex "为 src/utils.py 编写单元测试:
- 覆盖所有公共函数
- 包含边界与异常用例
- 用 pytest 风格
- 运行测试确保全部通过"

3. 修复 CI 失败

codex "查看 CI 最新失败日志(README 中有 CI 说明),
定位失败原因,修复代码,本地重跑验证"

4. 数据库迁移

codex "分析 models.py 的变更,生成 SQLite 迁移 SQL:
- 新增 users.age 字段
- 保留数据不丢失
- 提供回滚语句"

5. 依赖升级

codex "把 requests 从 2.28 升级到 2.31:
- 更新依赖文件
- 修复破坏性变更
- 运行测试验证"

6. 生成项目文档

codex "根据代码生成 README:
- 项目简介与架构图(Mermaid)
- 快速开始
- API 说明
- 常见问题"

7. 性能优化

codex "分析 src/main.py 的热点:
- 找出 O(n^2) 及以上复杂度代码
- 给出优化方案并实现
- 用 benchmark 脚本对比前后耗时"

8. 批量重构

codex "把 src/ 下所有 print 调试替换为 logging:
- 保持输出格式一致
- 修改后运行测试"

示例使用技巧

所有示例都包含"验收动作"(运行测试/输出报告)
按需增加约束(文件范围、风格、依赖)
关键场景先加 -s 试跑,确认方案再放开

把这些示例按你的项目微调后保存为斜杠命令或技能,就是你的"个人 AI 工具库"。

Codex CLI 提示词技巧

CLI 场景下的提示词有独特讲究:非交互任务的提示词必须"自包含"。本节补充 CLI 专属的提示词技巧。

技巧一:告诉 Codex 项目背景

# 单任务时携带最小背景
codex "这是一个 Python FastAPI 项目,数据库用 SQLite,
ORM 用 SQLAlchemy。请为 order 模块补 CRUD 接口"

技巧二:让 Codex 先探索再执行

codex "先阅读项目 README 与目录结构,理解架构后再:
1. 说明你的理解(200字)
2. 给出实现方案
3. 等我确认后执行"

技巧三:使用 include-path 定向

codex --include-path src/models/ --include-path tests/ \
  "重构模型层,更新对应测试"

技巧四:约束输出格式

codex "分析代码并输出 markdown 报告:
- ## 问题清单(严重程度|文件:行号|描述|建议)
- ## 修改方案
不写代码,只出报告"

技巧五:分级指令

codex "按优先级处理:
P0: 修复登录接口 500 错误
P1: 补充 email 字段校验
P2: 优化查询性能(非必须)
每个完成都运行相关测试"

技巧六:限制改动范围

codex "只允许修改 src/app.py 和 tests/,其他文件一律不动,
如需改其他文件先说明原因"

技巧七:多轮追问的替代

# CLI 无人工追问,给出"决策规则"
codex "遇到以下情况按规则处理:
- 表结构未知:查看 models.py 确认
- 接口规范:参考现有 api/*.py
- 实在无法确定:保留 TODO 并报告"

技巧八:验证强制

codex "完成后必须执行:
1. pytest -q(全部通过)
2. ruff check .
3. 展示关键代码 diff
全部满足才报告完成"

CLI 提示词的核心心法:把"人会追问的问题"提前写进提示词。写得越完整,结果越稳定。

Codex CLI 模型选择

CLI 中通过参数或配置指定模型,不同模型对 CLI 场景(长任务、工具调用)的支持程度不同。本节给出 CLI 场景的模型选择指引。

指定模型

# 参数方式
codex -m gpt-5.2-codex "任务"

# 配置方式
codex config set model gpt-5.2-codex

模型能力对 CLI 的影响

能力项	说明
工具调用	决定 Codex 能否可靠操作文件/命令
长上下文	影响大仓库任务的上下文容量
指令遵循	影响多步骤任务的执行质量
稳定性	影响长任务的完成率

第三方模型注意

第三方模型(DeepSeek 等)可能不完整支持 Codex 工具协议
长任务/工具密集任务优先官方模型
接入前用小任务验证工具调用是否正常

成本控制

# 限制 token 预算
[model]
max_input_tokens = 40000
max_output_tokens = 8000

# 会话中监控用量
> /status

实测评估法

# 用同一任务对比模型(脚本化)
for m in gpt-5.2-codex gpt-5.1-codex; do
  codex -m $m -y "修复 tests 中 3 个失败用例" --json | jq .result
done

CLI 场景下"工具调用可靠性"往往比"文字生成质量"更重要,选模型时优先实测工具类任务。

Codex 官方资源

本节汇总 Codex 的官方文档、下载入口与社区资源,方便你获取最新信息与支持。

官方入口

OpenAI 官网 Codex 页面:openai.com/codex(产品介绍与下载)
Codex 官方文档:platform.openai.com/docs/codex(完整指南)
OpenAI API 平台:platform.openai.com(密钥管理、用量查看)
GitHub 开源仓库:github.com/openai/codex(CLI 源码与 issue)

获取帮助的途径

官方文档的 Troubleshooting 章节
GitHub Issues:搜索或提交 bug
OpenAI 开发者论坛
官方 Discord 社区

版本更新关注

# 检查 CLI 版本与更新
codex --version
npm update -g @openai/codex

# 关注官方 release notes 了解新功能

社区资源

Reddit r/CodexAI、r/OpenAI 讨论区
技术博客与教程(中文社区:掘金、CSDN 等)
第三方工具:CCSwitch、Codex 中文教程站等

数据与安全声明

使用 Codex 前建议阅读官方的数据使用政策:了解代码是否被用于训练、企业版的数据隔离能力等,按合规要求选择合适的产品版本。

版本兼容提示

CLI、桌面应用、云端版本的功能可能存在差异
配置格式随版本演进,升级后运行 codex doctor 检查
第三方接入(如 DeepSeek)注意官方政策变化

AI 产品迭代很快,保持关注官方公告是"用好 Codex"的一部分。本教程的其余章节已经覆盖了核心用法,官方资源用于跟进最新变化。

Codex 教程总结

恭喜你完成了 Codex 教程的学习!本节回顾全教程的核心要点,并给出下一步的学习建议。

核心知识回顾

是什么:Codex 是 OpenAI 的 AI 编程代理,能自主完成编码任务
形态:ChatGPT 内置 / 桌面应用 / CLI / IDE 扩展 / 云端
安装:npm 安装 CLI + 登录(ChatGPT 账号或 API Key)
配置:config.toml 控制模型、权限、上下文、沙箱
安全:权限白名单 + 沙箱隔离 + 审计日志,是使用底线
扩展:Skills、MCP、子代理、钩子,按需接入
自动化:非交互模式 + CI/CD 集成,让 AI 进入流水线

成长路线

基础期:完成安装配置,用对话式完成任务
成长期:掌握提示词技巧与工作流模式,效率翻倍
进阶期:配置权限/沙箱,接入 MCP/Skills 扩展能力
专家期:自动化流水线 + 企业治理 + 团队规范

给你的行动清单

# 今天就可以做的
1. codex login
2. 写一份 AGENTS.md 到常用项目
3. 用 Codex 完成一个小功能
4. 配置权限白名单
5. 体验一次 /model 切换

常见误区提醒

不要完全信任输出:AI 代码必须 review
不要跳过权限配置:安全先行
不要一个会话塞所有任务:合理拆分
不要忘记更新:AI 工具迭代极快

AI 编程代理正在改变软件开发的方式。工具会不断进化,但"明确需求、审慎验收、守住安全"的原则不会过时。祝你用 Codex 写出更多好代码!

第 1 / 42 节