CX 公开技术手册

Codex

安装与配置 返回文档中心

Codex 综合学习与安装配置手册

从安装配置到编程开发、内容创作、PPT、报告与日常办公的一站式实践手册

版本日期： 2026 年 7 月 15 日
作者： code.jimuxyz.com 开发者
适用对象： 第一次接触 Codex 的用户、开发者、内容创作者，以及希望使用 Codex 处理文档、演示文稿、表格、报告和日常办公任务的个人或团队

安装与配置教程： https://code.jimuxyz.com/docs/cli#config
第三方订阅低毛利定价： 把 Codex / Claude Code / Gemini 做成更直观的套餐权益，不让用户反复换算 tokens 成本。相比常见按 tokens 折算的中转站计费，日常使用更便宜、更好预估；具体价格、套餐权益、计费规则与实际成本以网站实时页面为准。
标准 API 中转： 如需标准 API 中转，也可以使用积木 API 中转平台：https://api.jimuxyz.com/
桌面端相关配套文件：

网盘链接： https://pan.quark.cn/s/7830a21fe13f?pwd=wde8
提取码： wde8

配套资料与快速开始

本手册配套内容包括：

  1. 当前这份《Codex 综合学习与安装配置手册》。
  2. Codex 桌面版配套网盘资料。
  3. Windows、macOS 和 Linux 可使用的一键配置脚本与命令教程入口。

一、桌面版配套资料

配套文件可通过以下夸克网盘获取。点击链接，或复制整段口令后打开夸克 App：

text
/~2b603ZXVYl~:/

网盘链接： https://pan.quark.cn/s/7830a21fe13f?pwd=wde8
提取码： wde8

该网盘地址是本资料提供的配套镜像入口，不是 OpenAI 官方下载页。网盘文件可能随版本更新；安装前请核对文件名、操作系统、处理器架构和更新时间，并使用本机安全软件检查文件。

二、一键配置脚本与命令

请访问以下页面下载脚本，或按页面教程复制命令安装：

https://code.jimuxyz.com/docs/cli#config

截至 2026 年 7 月 14 日，该页面提供：

系统 可选入口 建议
Windows 复制命令安装；下载脚本安装 二选一，不要重复执行两套安装流程
macOS 复制命令安装；下载 .sh 脚本后用 bash 运行 优先阅读页面当前提示
Linux 复制命令安装；下载 .sh 脚本后用 bash 运行 先确认发行版、权限和依赖

使用配套配置页时要注意：

  1. 先登录并在 Key 管理中创建 Codex 产品线的 Key。
  2. Codex、Claude Code 和 Gemini 的 Key 不通用，不能混填。
  3. 先选择产品线，再选择自己的操作系统，只执行其中一种推荐安装方式。
  4. 已经安装桌面版时，可进入该页面提供的桌面版配置说明；没有客户端时可优先使用 CLI。
  5. 页面所述“国内直连”能力由第三方服务提供，实际可用性、费用和服务规则以页面实时说明为准。

按本站教程配置后的 Codex CLI/provider 模型接口以站点当前说明为准，站点宣称支持中国大陆网络直连。该说明不等于官方 App、ChatGPT 登录和 Codex Web/Cloud 可以在所有中国大陆网络中直接访问；后者仍需要能够正常访问 OpenAI/ChatGPT 服务的网络环境。

三、推荐使用顺序

  1. 先保存本手册和网盘信息，不要立即执行所有脚本。
  2. 只选择一条使用路线：桌面版、Codex CLI 或编辑器插件。
  3. 选择 CLI 时，先在配置页创建正确的 Codex Key，再按自己的系统完成安装。
  4. 安装后运行 codex --version、codex --help 和 codex doctor 检查环境。
  5. 在练习目录完成一个低风险任务，确认文件读取、修改和命令执行符合预期。
  6. 如链接失效、提取码错误或收到的文件与说明不一致，请联系资料提供方，不要从来源不明的页面重新下载。

内容摘要

Codex 不只是写代码的工具。它既能辅助编程开发，也能完成文章撰写、方案设计、PPT 大纲、报告整理、产品文案与日常办公创作。安装 docx、pptx、xlsx、pdf、imagegen 等适合的 Skills 后，还可以按工作流创建、读取、编辑和检查对应格式的文件。

本手册围绕 Codex 的安装准备、CLI/IDE/官方 App 使用入口、模型与推理强度、斜杠命令、Skills、任务表达、编程协作、内容创作、文档与办公文件处理、错误排查、结果验收、安全边界和复盘方法展开，并提供可直接填写的模板、案例和检查清单。

读者完成本手册后，应能够区分 CLI、编辑器、官方 App 和 Web/Cloud，按 Windows 或 macOS/Linux 完成安装，理解 /model、/permissions 等会话命令，按任务选择合适的 Skills，并能分别完成低风险的编程、文章、方案、PPT、报告或办公文件任务。所有输出都应通过事实核对、文件检查、渲染预览或实际测试验收。

关键词： Codex；CLI；VS Code；官方 App；模型；Skills；编程开发；文章写作；PPT；报告整理；日常办公；结果验收

阅读说明

本手册按照真实任务的生命周期组织：先准备环境和材料，再提出任务、控制修改范围、验证结果，最后沉淀可复用的方法。第一次使用建议顺序阅读，熟悉后可按问题查阅对应章节。

建议按以下方式使用：

  1. 第一次阅读时，先完成“配套资料与快速开始”以及第 1 至第 4 章，建立基本概念并运行一个低风险练习。
  2. 需要处理代码项目时，重点阅读第 5 至第 11 章；需要写文章、方案、PPT 或报告时，重点阅读第 5 至第 7 章、第 12 至第 14 章和附录 F。
  3. 遇到安装问题时查看第 3 章和第 36 章；需要理解模型、权限和斜杠命令时查看第 4 章与附录 E；选择或安装办公、文档、设计类 Skills 时查看附录 F。
  4. 每次完成真实任务后，用第 37 章的复盘表记录有效做法。
  5. 命令和界面可能随 Codex 版本变化；执行前先查看本机 codex --help，并以官方文档为准。

非开发用户可以先跳过第三部分的代码专章，但仍建议阅读第 5 至第 7 章的任务表达方法，以及第 15 至第 22 章的排错、验收、安全和长期维护原则。

重要说明：本资料不包含账号、订阅、API Key、模型额度或代充值服务。第三方网络与配置方案应由使用者自行判断服务条款、隐私和费用风险。

全书结构

部分 主要内容 完成标准
第一部分 认识 Codex 的编程与办公创作能力，安装并首次运行 能在练习目录检查模型、权限并完成低风险任务
第二部分 提问、上下文与任务拆解 能写出目标、范围、限制和验收标准
第三部分 项目阅读、代码解释、修改与测试 能说明核心流程并检查实际改动
第四部分 文件、文章、方案、Markdown、Word、PPT、PDF 与摘要 能组织内容、选择格式并核对输出
第五部分 故障定位、诊断命令与验收 能区分现象、证据、原因和结论
第六部分 权限、密钥、备份、回滚与进度 能控制高风险操作并留下审计记录
第七部分 可复用任务模板 能按真实任务填写并直接使用
第八部分 案例与七天练习 能独立完成一轮实践
第九部分 效率方法与常见问题 能避免重复安装、盲目修改和无标准验收
第十部分 复盘与个人规范 能沉淀自己的长期工作规则

第一部分：认识 Codex 与完成首次运行

1. Codex 是什么

Codex 是能够在授权工作目录中读取资料、使用工具、运行命令、修改文件并验证结果的智能代理。它以软件开发能力见长，但用途不局限于写代码。只要任务有明确输入、输出、范围和验收方式，Codex 也可以辅助文章撰写、方案设计、PPT 大纲与演示文件、报告整理、产品文案、表格分析和其他日常办公工作。

常见使用场景包括：

  • 阅读陌生代码项目，解释入口、模块和数据流。
  • 定位报错原因，修改代码并运行相关测试。
  • 根据素材撰写文章、教程、通知、邮件或产品文案。
  • 比较多个方案，形成结构化实施方案、风险清单和决策记录。
  • 设计 PPT 叙事结构、逐页大纲、讲稿，并通过 pptx Skill 创建或编辑演示文稿。
  • 汇总多份材料，生成调研报告、会议纪要、周报、项目总结或管理摘要。
  • 使用 docx、xlsx、pdf 等 Skills 创建和处理 Word、Excel、PDF 文件。
  • 批量整理 Markdown、图片、录音转写文本和结构化数据。
  • 审查代码、文档、表格或演示文件，找出错误、遗漏和验收缺口。

Codex 不是“输入一句话后必然得到正确结果”的按钮。它的效果主要取决于四个条件：

条件 要解决的问题
上下文 它是否看到了与任务相关的文件、日志和规则
边界 哪些目录可以改，哪些服务、文件或数据禁止操作
权限 是否允许读写文件、运行命令、访问网络或调用外部系统
验收 用什么测试、页面、日志或数据证明任务已经完成

1.1 Codex 擅长什么

Codex 对“可以观察、可以分解、可以验证”的工作最有效。一个任务如果能明确写出素材、目标读者、输出格式、限制和检查方法，通常就适合交给它执行。

类型 可以完成的工作 推荐验收方式
编程开发 阅读代码、实现功能、修复缺陷、补测试、审查改动 测试、构建、Git 差异和真实页面/接口
文章写作 提纲、初稿、改写、扩写、摘要、事实核对清单 对照原始资料，检查结构、事实、引用和语气
方案设计 现状分析、目标、备选方案、实施步骤、预算/风险框架 逐项核对前提、数字、责任人、时间和可执行性
PPT 受众分析、叙事主线、逐页大纲、讲稿、可编辑 .pptx 打开或渲染每页，检查文字溢出、图表、图片和逻辑
报告整理 汇总多份材料、提取数据、形成摘要和正式报告 回查来源，检查结论是否有证据、附件是否完整
产品文案 标题、卖点、功能说明、FAQ、邮件和多版本文案 核对真实功能、受众、平台规则和禁用表达
日常办公 Word 排版、Excel 清洗、PDF 处理、会议纪要、周报 打开目标文件，检查格式、公式、页码和关键信息
视觉与音频 图片生成、海报、主题样式、录音转写、语音输出 检查素材权利、画面/音频质量和内容准确性

例如，“帮我优化一下”过于宽泛。下面两类任务都更容易正确执行：

text
编程任务：检查登录接口的失败处理，只修改 internal/auth，补充无效密码和过期会话测试，运行 go test ./internal/auth/...。

办公任务：根据 materials 目录中的三份会议记录，整理一份面向管理层的项目周报；保留原始数字，输出 Word，包含进展、问题、风险和下周计划；生成后检查目录、表格和分页。

1.2 不安装 Skill 和安装 Skill 的区别

不安装额外 Skill 时，Codex 已经可以在对话中完成文章初稿、方案框架、PPT 逐页大纲、报告结构和产品文案。安装对应 Skill 后，重点增加的是特定文件格式和专业工作流能力：

目标 不安装对应 Skill 使用对应 Skill
PPT 输出主题、结构、逐页大纲和讲稿 使用 pptx 创建、读取或编辑可下载的 .pptx 文件并检查页面
Word 输出 Markdown 或纯文本正文 使用 docx 创建或编辑 .docx，处理目录、页码、表格和版式
Excel 设计字段、公式和分析思路 使用 xlsx 读写工作簿、清洗数据、添加公式和图表
PDF 输出适合转为 PDF 的内容 使用 pdf 读取、合并、拆分、OCR、生成或检查 PDF
图片 撰写图片需求和提示词 使用 imagegen 或 canvas-design 生成或编辑视觉素材

Skill 不是质量保证。生成文件后仍要打开或渲染检查；文章、方案和报告仍要核实事实、数字、引用、版权和业务判断。

1.3 Codex 不应替你决定什么

以下事项需要由人作最终决定：

  • 是否删除生产数据、覆盖不可恢复的文件或停止线上服务。
  • 是否使用来源不明的软件、脚本、密钥、代理或第三方接口。
  • 涉及合同、财务、法律、医疗和隐私的高风险判断。
  • 软件授权、平台规则、数据使用范围和对外承诺。
  • 需求本身存在冲突时，哪个业务目标优先。

可靠的协作方式不是放弃判断，而是让 Codex 负责搜索、整理、实施和验证，让人负责目标、授权和高风险决策。

2. 选择适合自己的使用入口

Codex 不是只有一个界面。CLI、VS Code/IDE、官方 App 和 Web/Cloud 都能承载 Codex 工作，但它们的运行位置、认证方式、网络要求和适用任务不同。先选入口，再安装和配置，可以避免把“插件”“终端命令”和“桌面客户端”混为一谈。

入口 主要特点 适合场景 关键限制
Codex CLI 在终端中读取本地目录、运行命令并创建或修改文件 编程、批量文档、Word/PPT/Excel/PDF、脚本和可审计任务 需要会使用终端，并清楚当前工作目录和权限
VS Code/IDE 扩展 编辑器中直接提供选区、打开文件和项目上下文 阅读代码、撰写 Markdown、方案和技术文档 扩展版本、登录方式和组织策略会影响功能
VS Code 内置终端 本质仍是 CLI，只是终端位于编辑器内 同时处理代码、文档、数据和 Skills 安装扩展不是使用内置终端的前提
Codex 官方 App 图形化管理会话、本地资料和多类任务 不熟悉命令行、需要多任务、文章、方案或图形化操作 下载、ChatGPT 登录和云端功能需要可正常访问 OpenAI/ChatGPT 的网络环境
Codex Web/Cloud 任务在托管环境运行，可连接远程仓库 远程任务、研究整理和无需占用本机的任务 依赖 ChatGPT 账号、套餐、仓库授权和网络条件

2.1 Codex CLI：本手册的主线

CLI 的优势是“看得见”：启动目录、读取范围、执行命令、权限请求、修改文件和测试输出都比较明确。常见启动方式如下：

bash
# 先进入项目，再启动
cd /你的项目路径
codex

# 不切换终端目录，直接指定工作目录
codex -C /你的项目路径

# 启动时附带第一个任务
codex -C /你的项目路径 "先阅读项目，只说明结构，不修改文件"

CLI 更适合以下用户：

  • 需要在 Windows、macOS、Linux 或远程服务器上工作。
  • 希望明确控制工作目录、沙箱和命令审批。
  • 需要批量处理文件、生成 Word/PPT/Excel/PDF、运行测试或自动化执行。
  • 愿意通过命令输出判断任务是否真的完成。

2.2 VS Code、Cursor 和 Windsurf

官方 Codex README 将 VS Code、Cursor 和 Windsurf 列为可使用 Codex IDE 集成的编辑器。新手建议先理解下面两条路线：

路线 A：在编辑器内置终端运行 CLI。

  1. 在 VS Code 中打开目标项目文件夹。
  2. 选择“终端 -> 新建终端”。
  3. 执行 pwd（PowerShell 可执行 Get-Location），确认终端处于正确项目。
  4. 执行 codex。

这条路线只依赖 CLI，不要求安装 Codex 扩展，行为也最接近本手册示例。

路线 B：安装 Codex IDE 扩展。

  1. 从 Codex 官方文档进入扩展安装入口，或在编辑器扩展市场搜索 Codex。
  2. 核对扩展名称、发布者、下载来源和权限，不安装名称相似的未知扩展。
  3. 安装后完全退出并重新打开编辑器。
  4. 打开一个练习项目，通过扩展面板发起只读任务。
  5. 若已按 code.jimuxyz.com 写入 Codex 配置，扩展通常可读取同一用户目录下的配置；若未识别，以扩展当前设置页和配置站当前说明为准。

IDE 入口可以利用当前选区、打开文件和编辑器上下文，但仍应在任务中写清允许修改的范围。打开了一个文件不代表 Codex 只能修改这个文件。

2.3 Codex 官方 App

官方 App 是 OpenAI 提供的桌面体验。官方 npm 包 README 给出的入口包括运行 codex app，或访问 Codex App 页面：

https://chatgpt.com/codex?app-landing-page=true

这里要区分两件事：

  1. 官方 App 的获取、更新、ChatGPT 登录和云端能力。这些步骤需要能够正常访问 OpenAI/ChatGPT 服务的网络环境；部分中国大陆网络可能无法直接完成，也就是用户通常所说的官方 App 需要相应网络条件。第三方 Key 或配置脚本不能替代官方客户端的下载、官方账号登录、套餐权益和云端仓库授权，本手册也不提供绕过网络限制的方法或工具。
  2. 已安装客户端的本地接口配置。code.jimuxyz.com 的桌面版配置页说明，其脚本会把本站 Codex 配置写入本机 .codex 目录，供已安装的 Codex 客户端和相关插件读取。是否被某个 App 版本接受，应以该客户端实际结果为准。

桌面版配置说明：

https://code.jimuxyz.com/dashboard/desktop-app-config#codex

不要将网盘中的 ChatGPT 安装文件仅凭文件名认定为 Codex 官方 App。安装前应检查应用名称、开发者签名、版本和来源；无法确认时，优先通过官方入口获取。

2.4 Codex Web/Cloud

Web/Cloud 入口位于：

https://chatgpt.com/codex

它适合将任务交给托管环境执行，但本地配置的第三方 API Key 不等于 ChatGPT 登录，也不会自动获得 Cloud、连接器或组织仓库权限。使用前要单独确认：

  • ChatGPT 账号和套餐是否包含对应能力。
  • GitHub 等代码仓库是否已正确授权。
  • 组织管理员是否限制仓库、模型、网络或数据保留。
  • 云端环境是否具备项目所需依赖和密钥。

2.5 如何选择

  • 第一次学习：使用 CLI 或 VS Code 内置终端。
  • 日常写代码：使用 IDE 扩展 + Git 差异检查。
  • 写文章、方案和文案：CLI、IDE、App 都可以，建议把素材放进独立工作目录。
  • 生成 Word、PPT、Excel 或 PDF：优先使用 CLI/内置终端 + 对应 Skill，便于保存并检查文件。
  • 整理多份报告、会议记录或调研资料：使用 CLI 或 App，明确输入目录、目标读者和输出格式。
  • 需要图形化多会话：在网络、账号和系统支持的前提下使用 官方 App。
  • 需要托管并行任务：使用 Web/Cloud，并单独检查账号和仓库授权。
  • 在中国服务器上处理本地项目：优先使用 CLI，因为它最容易验证配置、网络和权限。

2.6 为办公和内容创作准备工作目录

即使不写代码，也建议为每个任务创建独立目录。这样可以把原始素材、参考图片、模板和输出分开，避免覆盖源文件。

text
office-task/
├── sources/       # 原始文章、会议记录、数据和图片
├── references/    # 模板、品牌规范和参考资料
├── drafts/        # 提纲与中间稿
└── output/        # 最终 Word、PPT、Excel、PDF 等文件

启动前进入这个目录，再运行 codex。任务中至少说明：

  • 要处理哪些素材，哪些文件仅供参考。
  • 目标读者、使用场景和希望达到的效果。
  • 输出是纯文本、Markdown、大纲，还是实际的 .docx、.pptx、.xlsx、.pdf 文件。
  • 是否已有模板、品牌颜色、页数、字数、语气或截止时间要求。
  • 哪些事实、数字、引用和图片必须保留或回查。
  • 最终如何检查内容和版式。

3. 按 code.jimuxyz.com 安装和配置 Codex CLI

本章以本资料指定的两个页面为主安装路径：

页面和脚本可能更新。若手册命令与页面当前内容不同，应先核对页面更新时间、变更说明和脚本内容，再决定是否使用新命令。本章记录的是 2026 年 7 月 14 日核实到的流程。

3.1 安装前的四项准备

准备一：确认系统和终端

Windows 使用 PowerShell；macOS 使用“终端”；Linux 使用 Bash 等终端。先确认系统和架构：

bash
# macOS / Linux
uname -s
uname -m
powershell
# Windows PowerShell
[System.Environment]::OSVersion
$env:PROCESSOR_ARCHITECTURE
准备二：安装 Node.js 22 或更高版本

配置页要求 Node.js 22+，Node.js 安装后会同时提供 npm。

Windows 和 macOS 可从 Node.js 官网下载安装：

https://nodejs.org/zh-cn/download

Debian/Ubuntu 类 Linux 可按配置页提供的方式安装 Node.js 22：

bash
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

验证版本：

bash
node -v
npm -v

node -v 应显示 v22 或更高主版本。若电脑由单位管理，应先遵守组织的软件安装策略。

准备三：创建 Codex 产品线 Key
  1. 登录 https://code.jimuxyz.com/。
  2. 进入“Key 管理”：https://code.jimuxyz.com/keys。
  3. 创建或复制 Codex 产品线的 sk- 开头 Key。
  4. 暂时保存在可信的密码管理器中，不要写入本手册、截图、公开页面或代码仓库。

Codex、Claude Code、Gemini 的 Key 不能混用。401 或 403 最常见的原因就是 Key 填错、Key 已失效、余额/权限不足，或使用了其他产品线的 Key。

准备四：备份旧配置

如果以前使用过 Codex，先备份用户目录中的 .codex：

bash
# macOS / Linux
cp -a ~/.codex ~/.codex.backup-$(date +%Y%m%d-%H%M%S)

Windows 可在资源管理器中将 C:\Users\你的用户名\.codex 复制一份并加上日期。配置脚本可能改写认证和模型服务商设置；备份用于恢复自己的旧配置，不应用来传播其中的密钥。

3.2 Windows 安装步骤

打开新的 PowerShell 窗口，按“环境检测 -> 安装 CLI -> 写入配置”的顺序执行。某一步报错时先处理该错误，不要跳到下一步。

可选：卸载已有的旧版 Codex。首次安装时跳过。

powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "npm uninstall -g @openai/codex"

第 1 步：环境检测。

powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "iwr -useb https://code.jimuxyz.com/env_deploy/codex-install.ps1 | iex"

第 2 步：安装最新版 Codex CLI。

powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "[Environment]::SetEnvironmentVariable('JIMUXYZ_NPM_PACKAGE','@openai/codex','Process'); [Environment]::SetEnvironmentVariable('JIMUXYZ_NPM_DISPLAY_NAME','Codex CLI','Process'); iwr -useb https://code.jimuxyz.com/env_deploy/npm-global-install.ps1 | iex"

第 3 步：写入本站 Codex 配置。先把命令中的 你的Codex_API_KEY 替换为自己刚创建的真实 Codex Key。

powershell
powershell -NoProfile -ExecutionPolicy Bypass -Command "[Environment]::SetEnvironmentVariable('JIMUXYZ_CODEX_KEY','你的Codex_API_KEY','Process'); iwr -useb https://code.jimuxyz.com/env_deploy/codex-deploy.ps1 | iex"

执行结束后，完全关闭 PowerShell、Windows Terminal、VS Code、Cursor、Codex App 和其他相关编辑器，再重新打开。仅新建一个编辑器标签页通常不够，因为旧进程可能仍持有旧环境或旧配置。

3.3 macOS/Linux 安装步骤

打开新的终端，按顺序执行。

可选：卸载已有的旧版 Codex。首次安装时跳过。

bash
npm uninstall -g @openai/codex

第 1 步：环境检测。

bash
curl -fsSL https://code.jimuxyz.com/env_deploy/codex-install.sh | bash

第 2 步：通过国内 npm 镜像安装最新版 Codex CLI。

bash
npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com

第 3 步：写入本站 Codex 配置。先把 你的Codex_API_KEY 替换为自己的真实 Codex Key。

bash
curl -fsSL https://code.jimuxyz.com/env_deploy/codex-deploy.sh | bash -s -- "你的Codex_API_KEY"

执行结束后，完全退出终端、VS Code、Cursor、Codex App 等相关进程，再重新打开。

3.4 脚本会写入什么

根据配置页面说明，Codex 配置脚本会写入：

系统 认证文件 主配置文件
Windows C:\Users\你的用户名\.codex\auth.json C:\Users\你的用户名\.codex\config.toml
macOS/Linux ~/.codex/auth.json ~/.codex/config.toml

它们通常包含认证信息、模型服务商和接口地址等设置。注意：

  • auth.json 属于敏感文件，不要上传网盘、Git、聊天或截图。
  • config.toml 决定使用哪个 provider、模型默认值和其他行为，不理解时不要随意删除字段。
  • 站点 Key 配置和“使用 ChatGPT 登录”是两条不同认证路径。配置本站服务后又执行官方登录，可能改变当前认证状态；只有在明确要切换路径时才这样做。
  • API Key 认证不等于获得 ChatGPT App、Codex Cloud 或连接器权限。

若只需要给已经安装的桌面版或 IDE 重新写入配置，可查看：

https://code.jimuxyz.com/dashboard/desktop-app-config#codex

3.5 验证安装结果

重新打开终端后依次执行：

bash
node -v
npm -v
codex -V
codex --help
codex doctor

通过标准：

  1. node -v 为 22 或更高主版本。
  2. npm -v 能显示版本。
  3. codex -V 能显示 Codex CLI 版本。
  4. codex --help 能显示命令和参数。
  5. codex doctor 没有必须先解决的配置、认证或网络故障。

再进入一个练习目录启动：

bash
mkdir -p ~/codex-practice
cd ~/codex-practice
codex

启动后先输入 /status，检查工作目录、模型、认证/服务商线索、上下文和权限；再输入 /model，确认当前 provider 返回了可选择的模型。模型列表不是写死在 CLI 中的永久清单，会随服务商、Key、套餐、区域和版本变化。

3.6 在 VS Code 中验证

  1. 用 VS Code 打开 ~/codex-practice 或其他练习目录。
  2. 完全重启 VS Code 后，先在内置终端执行 codex -V。
  3. 若使用 IDE 扩展，再打开扩展面板发起“只读取当前目录并说明文件列表”的任务。
  4. 若内置终端正常而扩展失败，问题通常位于扩展登录、扩展配置或扩展版本，不要重复安装 CLI。
  5. 若内置终端也找不到 codex，检查 VS Code 是否在安装前已启动，并再次完全退出后重开。

3.7 官方 App 的安装与本站配置边界

已经具备官方 App 的用户，可以按桌面版配置页重新写入本站 Codex 配置，然后完全退出 App 再重开。但必须理解：

  • 配置脚本只负责本地配置，不负责提供或破解官方客户端。
  • App 下载、更新、ChatGPT 登录和部分云端能力仍可能要求可正常访问 OpenAI/ChatGPT 服务的网络。
  • 本站 Key 的余额、计费和日志由本站规则管理，不属于 ChatGPT 订阅权益。
  • 某次 App 更新若不再接受自定义 provider，应以当前 App 和配置页实测为准，CLI 仍是更容易排查的入口。

3.8 更新、重装和卸载

查看版本和帮助：

bash
codex -V
codex --help

按本手册路径更新 CLI：

bash
npm install -g @openai/codex@latest --registry=https://registry.npmmirror.com

也可在当前版本支持时执行：

bash
codex update

卸载 CLI：

bash
npm uninstall -g @openai/codex

卸载 npm 包不会自动删除 ~/.codex 或 Windows 用户目录中的 .codex。不要为了“彻底卸载”直接删除该目录，除非已备份并确认不再需要会话、配置、Skills、插件和认证信息。

3.9 常见安装故障

现象 优先检查 处理方向
node 或 npm 找不到 Node.js 是否安装、终端是否重开、PATH 安装 Node.js 22+，完全重开终端
codex 找不到 npm 全局安装是否成功、npm 全局目录是否在 PATH 执行 npm root -g、重开终端，不要连续重复安装
401 Key 是否完整、是否失效、是否填成其他产品线 重新从 Key 管理复制 Codex Key，暴露过则轮换
403 Key 权限、产品线、余额/套餐、接口策略 查看本站 Key 和用量页面，不要改成 Claude/Gemini Key
能启动但没有模型 provider 配置、Key 权限、模型目录刷新 查看 /status、/model 和 codex doctor
VS Code 扩展失败但终端正常 扩展版本、扩展登录、旧进程 完全重启编辑器，检查扩展自己的设置和日志
App 不能登录或下载 OpenAI/ChatGPT 网络、账号和系统支持 先处理官方访问与账号问题；第三方脚本不能替代登录
配置后仍使用旧接口 进程未退出、写入了另一个用户目录 确认当前系统用户和 .codex 路径，完全重启相关进程
远程脚本被安全软件阻止 脚本来源、组织策略、PowerShell 执行策略 先审查脚本；受管设备联系管理员，不关闭安全防护硬绕过

4. 首次使用、模型和会话命令

4.1 在正确目录启动

Codex 默认把启动目录当作主要工作根目录。启动前先执行：

bash
pwd
rg --files | head
git status --short

Windows PowerShell 对应可使用：

powershell
Get-Location
Get-ChildItem
git status --short

不要从用户主目录、磁盘根目录或包含多个无关项目的上级目录随意启动，否则可见范围和误改范围都会变大。

4.2 模型、provider 和推理强度是什么意思

这几个概念经常被混淆：

概念 含义 会影响什么
Codex 执行任务的产品和代理环境 文件、终端、工具、会话和工作流
模型（model） 负责理解和生成的推理引擎 质量、速度、上下文能力和成本
服务商（provider） 向 CLI 提供模型接口的一方 可用模型、接口地址、认证、计费和稳定性
API Key provider 用来识别调用者的凭证 身份、权限、额度和计费
推理强度（reasoning effort） 模型在一次回答中投入的推理程度 通常越高越慢、消耗越多，复杂任务可能更稳
上下文（context） 当前会话可供模型参考的消息、文件摘要和工具结果 上下文接近上限时，较早细节可能需要压缩或重述

模型不是入口。同一模型可能在 CLI、IDE 或 App 中使用；同一入口也可能允许切换多个模型。provider 也不是模型。配置为第三方 provider 后，可用模型由该 provider 和当前 Key 决定。

4.3 /model 与启动参数 -m

在交互会话中输入：

text
/model

它用于选择当前可用模型和推理强度。常见选择原则：

  • 文件查找、格式调整、简单解释：先使用较低或中等推理强度。
  • 跨模块修改、复杂调试、架构分析：使用中等或较高推理强度。
  • 高风险迁移、难复现缺陷、大型审查：在信息充分时再提高强度，并保留人工验收。
  • 提高推理强度不等于自动获得权限，也不能弥补错误目录、缺失日志或模糊需求。

启动 CLI 时也可临时指定模型：

bash
codex -m '<当前 provider 支持的模型名>'

不要把某张截图中的模型名当作永久推荐。模型名称、默认值和推理档位会变化，应以当前会话 /model 展示的列表为准。若列表为空或选择后报错，先检查 provider、Key 和套餐，而不是反复修改任务提示词。

4.4 /permissions 是什么

在交互会话中输入：

text
/permissions

它用于查看或选择 Codex 在当前环境中允许执行的操作，例如文件读取/写入范围、网络能力、沙箱和命令审批方式。具体选项受 CLI 版本、操作系统、组织策略和启动参数限制。

建议：

  1. 陌生项目先使用只读或受限写入权限。
  2. 只有任务确实需要时才开放网络、额外目录或更高权限。
  3. 不要为了少一次确认长期使用“完全访问”或绕过审批。
  4. /permissions 不能突破系统管理员、容器或组织策略强制设置的上限。
  5. 权限放开后，任务边界仍要在提示中写明；“有权限”不等于“应该修改”。

4.5 斜杠命令如何使用

斜杠命令是在 Codex 交互会话内部输入的控制命令。它们不是 Bash 或 PowerShell 命令。

text
/status
/diff
/review

在输入框键入 /，查看当前版本、当前登录方式和当前功能开关真正提供的命令。再继续输入字符可以筛选，例如输入 /per 查找 /permissions。

版本区别很重要：

  • 某些命令只在新版本、特定系统、ChatGPT 登录、实验功能或特定组织中显示。
  • 某些命令不能在任务正在执行时运行，应先等待任务结束或停止任务。
  • CLI 顶层命令 codex review 与会话内 /review 相关，但不是同一输入位置。
  • 本手册附录 E 按当前实测的 Codex CLI 0.144.1 整理了常用和条件命令；实际使用始终以本机输入 / 后显示的菜单为准。

4.6 完成第一个低风险任务

第一次使用不要从生产服务器、重要仓库或大规模批量修改开始。创建练习目录：

bash
mkdir -p ~/codex-practice
cd ~/codex-practice
printf '# 读书记录\n\n- 待读：\n' > README.md
codex

先检查会话状态和权限：

text
/status
/permissions

然后输入任务：

text
请先读取当前目录，只修改 README.md。
把它整理成“待读、阅读中、已读”三个小节，每个小节保留一个空白示例。
完成后重新读取文件，说明修改内容。不要创建其他文件。

任务结束后输入：

text
/diff

若练习目录不是 Git 仓库，直接重新读取 README.md 检查。这个练习包含完整闭环：

  1. 指定工作目录。
  2. 检查模型、状态和权限。
  3. 指定唯一允许修改的文件。
  4. 说明期望结构。
  5. 要求修改后复查。
  6. 检查实际差异或文件内容。

退出后可继续最近会话：

bash
codex resume --last

恢复会话后仍应重新说明当前目标，并用 /status 确认目录和模型，不要假定旧上下文自动代表现在的需求。

4.7 非编程用户的三个入门练习

完成基础文件练习后，可以选择下面任意一个办公或内容创作任务。第一次只处理虚构或已脱敏材料。

练习一：文章与报告整理。

在 sources 中放入两三份短材料，然后输入：

text
请读取 sources 中的材料，先列出每份材料的主题、关键事实和可能冲突。
然后面向第一次接触该主题的读者，撰写一篇 1500 至 2000 字的中文说明文章，输出到 drafts/article.md。
要求：结构包含标题、摘要、三个正文小节和结语；数字和事实只能来自原始材料；不确定内容标记为“待核实”；完成后给出事实核对清单。
不要修改 sources 中的任何文件。

练习二：PPT 逐页大纲。

text
根据 sources 中的项目资料，为 10 分钟内部汇报设计一份 8 页 PPT 大纲。
受众是不了解技术细节的管理人员。每页给出：页标题、核心结论、3 至 5 个要点、建议图表或图片、讲解备注。
先只输出到 drafts/ppt-outline.md，不生成 PPT 文件；确保第 1 页提出问题，第 2 至 6 页讲证据和方案，第 7 页讲风险，第 8 页给下一步行动。

练习三：通过 Skill 生成办公文件。

先输入 /skills，确认是否存在 docx、pptx 或 xlsx。例如需要可编辑演示文稿时：

text
请使用 pptx Skill，把 drafts/ppt-outline.md 制作为 16:9、8 页、适合内部汇报的可编辑 PPT。
使用 references 中的模板和图片；没有依据的数据不要编造。输出到 output/project-briefing.pptx。
生成后渲染全部页面并检查：标题和正文无溢出、图片不拉伸、字号可读、页面顺序与大纲一致。发现问题请修复后再报告。

如果当前会话没有对应 Skill，可以先完成大纲或正文，再按附录 F 安装合适的 Skill。不要把“已生成大纲”描述成“已生成并检查 .pptx 文件”。

第一部分小结

本部分完成了从认识使用入口到首次运行的基础闭环。读者应已经知道桌面版、CLI、编辑器和云端入口的区别，能够根据系统选择一种安装方式，理解官方登录与第三方 Key 配置不是同一条认证路径，并能在练习目录运行编程或办公创作任务。进入真实任务之前，请先确认当前目录、素材来源、账号来源、输出格式、权限和验收方法。

第二部分：把需求说清楚

5. 一个可靠任务的六个组成部分

实用提示词不需要堆砌术语。只要包含下列信息，就能显著减少误解和返工。

组成部分 应回答的问题 示例
目标 最终要解决什么问题 修复 CSV 导入时中文乱码
背景 为什么要做，当前发生了什么 Windows 导出的 GBK 文件导入失败
范围 可以读取或修改哪里 只改导入模块和相关测试
限制 哪些东西不能动 不改数据库结构，不重启其他服务
输出 希望留下什么结果 代码、测试、变更说明
验收 如何判断完成 两类编码样例都通过自动测试

可以直接使用以下结构：

text
目标：
背景：
允许修改：
禁止修改：
输入材料：
期望输出：
验收方法：

5.1 从模糊表达改为可执行任务

模糊表达：

text
这个后台不好用，帮我美化一下。

可执行表达：

text
目标：提升后台用户列表在桌面和手机上的可读性。
现状：标题会溢出，操作按钮在 390px 宽度下重叠。
范围：只修改 static/admin/users.css 和 users.html。
限制：保留现有颜色变量和接口，不引入新前端框架。
验收：在 1440x900 和 390x844 两种视口检查，无横向滚动、文字遮挡和按钮重叠。
完成后：运行现有前端检查并提供截图。

后者并不比前者“更客气”，但它给出了可观察的问题、修改范围和验收标准。

6. 上下文整理方法

上下文不是越多越好。与任务无关的大量文件会增加搜索成本，也可能让错误配置或旧文档干扰判断。

6.1 最小充分上下文

一次故障排查通常需要：

  • 完整错误信息，而不是只说“失败了”。
  • 触发错误的操作步骤和时间。
  • 相关文件路径、函数名或页面地址。
  • 期望结果与实际结果。
  • 最近发生的相关变更。
  • 运行环境和版本。
  • 已经尝试过的操作及结果。

不应提供：

  • 与问题无关的整个磁盘。
  • 明文密码、Cookie、Access Token 和私钥。
  • 未脱敏的客户隐私数据。
  • 无法确认来源的大段旧答案。

6.2 错误信息记录模板

text
问题名称：
发生时间：
运行环境：
触发步骤：
期望结果：
实际结果：
完整错误：
相关日志：
最近变更：
已经尝试：
禁止操作：

6.3 长任务如何交接

当任务跨会话或需要交给另一个人时，应创建交接文档，而不是只写“继续上次任务”。交接文档至少包含：

  1. 最终目标。
  2. 项目路径和服务边界。
  3. 已完成事项及验证证据。
  4. 未完成事项和阻塞原因。
  5. 关键文件、命令和数据位置。
  6. 不得重复或不得执行的操作。
  7. 下一步最小动作。

7. 任务拆解与执行顺序

任务拆解的目的不是制造长清单，而是把风险隔离并让每一步都能验证。

一个常见的软件任务可以分为：

  1. 确认现状： 阅读规则、入口、配置和相关测试。
  2. 复现问题： 用最小输入稳定触发问题。
  3. 确定原因： 区分表象、直接原因和根本原因。
  4. 设计修改： 说明影响范围、兼容性和失败回退。
  5. 实施修改： 小步编辑，避免夹带无关重构。
  6. 运行验证： 先跑聚焦测试，再跑受影响范围测试。
  7. 检查改动： 查看差异、生成物和服务状态。
  8. 记录结果： 写明完成内容、验证方法和残余风险。

7.1 任务优先级

可以用以下顺序决定先做什么：

优先级 判断标准 示例
P0 数据、安全或服务正在受损 密钥泄露、错误扣款、生产数据损坏
P1 核心流程不可用 无法登录、文件导入失败、关键接口持续报错
P2 可用但效率或体验明显受影响 批量导入慢、移动端按钮重叠
P3 增强和长期优化 新报表、视觉细节、非关键自动化

不要在 P0/P1 尚未解决时投入大量时间调整装饰性样式。

7.2 什么时候应该停下来确认

遇到以下情况应暂停高风险动作：

  • 目标存在互相冲突的解释。
  • 即将删除、覆盖或迁移不可恢复的数据。
  • 需要使用未获授权的账号、系统或第三方接口。
  • 发现工作目录中存在来源不明且会影响任务的并发修改。
  • 测试结果与预期相反，继续操作会扩大影响。
  • 外部平台权限、法律许可或数据授权无法从现有材料中确认。

第二部分小结

本部分把“会提问”具体化为目标、背景、范围、限制、输出和验收六个要素。上下文应追求最小充分，而不是把整个磁盘和所有历史对话一次交给 Codex。复杂任务要按观察、复现、分析、修改、验证和记录拆解；遇到目标冲突、不可恢复数据或未授权系统时，应先停止并确认。

第三部分：与项目和代码协作

8. 进入陌生项目的阅读顺序

不要一开始逐行阅读所有代码。先建立项目地图，再沿核心流程深入。

推荐顺序：

  1. 查看项目根目录和文件清单。
  2. 阅读 README、AGENTS.md、部署说明和环境变量示例。
  3. 识别语言、框架、依赖管理和启动命令。
  4. 找到程序入口、路由入口、配置入口和数据存储层。
  5. 搜索与当前任务直接相关的关键词。
  6. 阅读现有测试，理解代码声称保证的行为。
  7. 绘制“请求进入 -> 业务处理 -> 数据写入 -> 响应返回”的路径。

8.1 项目地图模板

text
项目目标：
主要语言/框架：
启动入口：
配置来源：
路由或命令入口：
核心业务模块：
数据存储：
外部依赖：
测试入口：
构建与部署：
禁止操作：
当前任务相关文件：

8.2 用搜索代替盲目浏览

常用命令示例：

bash
# 列出文件
rg --files

# 查找函数、错误文字或接口路径
rg -n "ImportCSV|INVALID_ENCODING|/api/imports"

# 查找配置项的定义和使用位置
rg -n "APP_SECRET|database_path|listen_port"

# 查看某个文件的一段内容
sed -n '1,220p' path/to/file

搜索时同时找“定义、调用、测试和文档”。只看到函数定义，不代表它已经接入真实流程。

9. 使用 AGENTS.md 固化项目规则

AGENTS.md 适合记录需要在该项目长期生效的工程约束，例如：

  • 哪些目录或外部项目只能阅读，禁止修改。
  • 构建、测试和格式化命令。
  • 默认端口和服务边界。
  • 数据安全与密钥管理要求。
  • 关键业务不变量。
  • 上线前必须完成的检查。

示例：

markdown
# 项目约束

- 只修改当前项目，参考项目只能读取。
- 默认开发端口为 8080，不占用同一台机器上的已有服务端口。
- 修改后运行 `go test ./...`。
- 任何密钥不得写入代码、日志或提交记录。
- 批量导入缺少唯一标识时必须拒绝自动处理。

AGENTS.md 不是需求文档。一次性的文案、临时测试账号或本轮任务细节应放在当前提示词或任务文档中。

10. 代码修改的安全闭环

10.1 修改前

  • 确认工作目录和项目边界。
  • 查看当前改动，避免覆盖他人正在进行的工作。
  • 找到与目标行为最接近的现有实现和测试。
  • 先复现问题，保存失败证据。
  • 判断是否涉及数据库迁移、外部 API 或部署配置。

10.2 修改中

  • 只改解决当前问题所需的文件。
  • 优先延续项目现有模式，不随意引入新框架。
  • 先修根本原因，不用吞掉异常来伪造成功。
  • 对外部接口设置超时、错误处理和可审计日志。
  • 涉及重复请求时考虑幂等性。
  • 涉及多租户、多账号或批量记录时使用明确标识匹配，不能随机回退。

10.3 修改后

bash
# 示例：先运行聚焦测试
go test ./internal/imports/...

# 再运行项目全量测试
go test ./...

# 查看改动
git diff --check
git diff
git status --short

如果目录不是 Git 仓库，应改用文件清单、哈希、备份和测试记录追踪修改，不能假装已经完成 Git 检查。

10.4 完成不等于“代码能编译”

一个功能至少应从以下层面检查：

层面 检查内容
语法 编译、类型检查、脚本语法检查
单元 核心函数在正常与异常输入下的行为
集成 数据库、文件、外部 API 和路由能否协作
界面 桌面与移动端能否操作，是否有重叠和溢出
安全 未登录、签名错误、越权和敏感信息处理
运维 日志、健康检查、重启、回滚和备份
业务 最终流程是否真正达到用户目标

11. 让 Codex 解释代码而不是只给结论

一个有效的代码解释请求应要求引用具体文件和调用关系：

text
请解释用户登录流程：
1. 从 HTTP 路由开始，追踪到数据库写入；
2. 标出关键函数和文件位置；
3. 说明身份校验、会话处理和错误返回；
4. 列出当前测试覆盖和未覆盖分支；
5. 暂时不要修改代码。

阅读解释时重点核对：

  • 是否把“可能调用”误写为“实际调用”。
  • 是否引用了已经废弃的文件。
  • 是否忽略异步任务、回调或中间件。
  • 是否混淆配置默认值与生产实际值。
  • 是否说明了异常路径和数据一致性。

11.1 方案对比模板

text
请比较方案 A 和方案 B，按以下维度输出：
- 实现复杂度
- 对现有数据的影响
- 兼容性
- 故障恢复
- 测试成本
- 长期维护

先给事实和取舍，再给建议；没有依据的部分明确标为假设。

第三部分小结

阅读陌生项目时，应先建立项目地图，再沿真实调用链阅读入口、配置、业务、存储和测试。修改代码前要复现问题，修改中控制范围，修改后同时检查聚焦测试、受影响范围测试和实际差异。AGENTS.md 适合保存长期项目规则，一次性任务信息仍应写在当前任务说明中。

第四部分：文件、文档和批量任务

12. 文件整理工作流

文件类任务的风险通常来自路径错误、编码差异、覆盖原件和批量范围失控。

推荐流程：

  1. 先列出输入文件数量、格式、大小和命名规律。
  2. 抽查至少一个普通样本、一个最大样本和一个异常样本。
  3. 明确输出目录、命名规则和重复文件处理方式。
  4. 先对 1 至 3 个文件试运行。
  5. 检查内容、格式、编码和链接。
  6. 再执行全量转换。
  7. 输出成功、跳过和失败清单。
  8. 保留源文件，批量结果写入独立目录。

12.1 批量转换任务模板

text
目标：把指定目录中的 Markdown 转为 Word。
输入目录：/path/to/markdown
输出目录：/path/to/docx
包含：仅一级目录中的 .md
排除：临时文件、历史输出和隐藏目录
命名：保留原文件名，只替换扩展名
覆盖策略：已有文件跳过并记录
格式：A4、中文字体、标题层级、页码、目录
验收：先转换 2 个样本；结构校验通过后再批量处理

12.2 编码和换行

中文文档常见问题包括 UTF-8、GBK、CRLF 和 LF 混用。不要直接用“看起来正常”判断编码。可以先运行：

bash
file path/to/document.md

文本中出现字面量 \n 时，它不是换行，而是反斜杠和字母 n。需要根据内容语义转换，不能对程序代码和 JSON 做无差别替换。

13. Markdown、Word 与 PDF 的关系

建议把 Markdown 作为可维护的内容源，Word 作为可编辑分享格式，PDF 作为版式固定的阅读版本。

格式 优点 注意事项
Markdown 易维护、可搜索、适合版本管理 复杂分页和页眉能力有限
Word 可编辑、支持目录、页码和批注 不同 Office 软件渲染可能不同
PDF 版式稳定、便于阅读与打印 修改成本高，链接和字体需检查

转换后必须检查：

  • 标题是否进入目录。
  • 中文字体是否缺失或显示为方框。
  • 代码块是否换行、截断或超出页面。
  • 表格是否超过页宽。
  • URL 是否完整且可点击。
  • 页眉、页脚和页码是否连续。
  • 空白页和章节分页是否合理。
  • 图片是否清晰且没有拉伸。

13.1 如何整合多份重复文档

如果多个 PDF 只是更换标题和少量主题词，直接合并会形成篇幅很长但信息密度很低的文档。更合理的处理是：

  1. 提取所有主题。
  2. 合并重复章节。
  3. 补足真实步骤、案例和检查方法。
  4. 按学习顺序重新编排。
  5. 只保留有独立价值的模板和练习。

这个流程同样适用于 Markdown、Word、PDF 和从网页导出的资料。

14. 摘要、整理和改写

摘要任务应先说明读者和用途。同一份材料给管理者、开发者和客户的摘要不会相同。

14.1 文件摘要模板

text
文件名称：
文件目的：
目标读者：
核心结论：
关键数据或规则：
需要执行的动作：
风险和限制：
仍待确认的问题：

14.2 防止摘要失真

  • 数字、日期、路径和配置名应回到原文核对。
  • 原文没有的因果关系不能自行补充。
  • “建议、计划、已经完成”必须区分。
  • 多份文档冲突时，应列出冲突来源，不擅自合并成一个结论。
  • 涉及密钥和隐私时先脱敏，再整理。

14.3 文档重写验收表

  • 原始目标没有被改变。
  • 重复段落已经合并。
  • 术语前后一致。
  • 操作步骤按真实先后顺序排列。
  • 命令有适用系统和执行目录说明。
  • 外部链接标明官方或第三方属性。
  • 没有真实密码、密钥、Cookie 或个人隐私。
  • 外部链接的用途和来源已经说明。

第四部分小结

文件批处理应先统计、抽样和确定覆盖策略，再执行全量操作。Markdown 适合作为可维护原稿，Word 适合作为可编辑分享文件，PDF 适合作为固定版式阅读件。多个高度重复的短文不应机械合并；应先建立主题地图，去重重写，并在转换后检查字体、分页、链接、表格、代码段和目录。

第五部分：错误排查与结果验收

15. 从错误现象找到根本原因

错误排查不是不断尝试随机命令。先建立可重复的观察，再逐层缩小范围。

15.1 五层排查法

  1. 输入层： 参数、文件、编码、请求体是否符合要求。
  2. 应用层： 路由、业务逻辑、状态机和异常处理是否正确。
  3. 数据层： 数据库、缓存、文件权限和迁移是否一致。
  4. 连接层： DNS、端口、代理、证书、超时和防火墙是否正常。
  5. 外部层： 第三方服务状态、签名规则、审核和额度是否影响结果。

15.2 现象、原因和证据

text
现象：Codex 启动后请求模型时返回 401。

错误做法：不查看配置和响应，直接反复重装 Codex。

正确拆解：
- 当前配置使用哪个 provider 和接口地址？
- HTTP 状态码和响应体是什么？
- Codex Key 是否属于正确产品线且仍然有效？
- `/status` 和 `codex doctor` 显示什么？
- 服务端是否收到请求，用量或额度是否正常？
- 同一个 Key 能否通过最小请求验证？

只有日志、请求和协议字段能支持原因判断。相似的页面提示可能对应完全不同的问题。

15.3 最小复现记录

text
复现环境：
前置数据：
最少步骤：
实际输出：
预期输出：
复现频率：
首次出现版本：
对照环境：
附件或日志：

16. 常用诊断命令

16.1 进程和端口

bash
ps aux | rg '程序名'
ss -lntp
systemctl status 服务名 --no-pager
journalctl -u 服务名 -n 100 --no-pager

16.2 HTTP 与证书

bash
curl -i http://127.0.0.1:端口/health
curl -i https://example.com/health
curl -v https://example.com/ 2>&1

先检查本机服务，再检查公网域名，可以区分应用故障与反向代理、DNS 或证书问题。

16.3 JSON 和日志

bash
jq . response.json
rg -n "error|failed|timeout|SIGN_INVALID" logs/

不要为了“日志干净”删除错误。应记录错误类型、请求标识和可操作信息，同时脱敏密钥、令牌和个人数据。

17. 验收标准如何写

“看起来可以”“应该好了”不是验收。一个标准应能由另一位人员在相同输入下重复检查。

17.1 功能验收示例

text
给定：一个包含 10 行有效数据的 UTF-8 CSV 文件。
当：用户使用同一个导入标识连续提交两次。
则：系统只写入一次，不产生重复记录。
并且：接口返回可追踪的导入结果。
异常：缺少必填列时明确拒绝，数据库不写入部分数据。

17.2 文档验收示例

text
- Markdown 可用 UTF-8 正常打开。
- Word 结构校验通过。
- PDF 所有页面中文可读，无方框、裁切和重叠。
- 目录包含一级至三级标题。
- 配置链接完整，不含账号、密码或 API Key。
- 随机抽取三个章节与 Markdown 内容一致。

17.3 验收记录模板

检查项 方法 预期 实际 结论
语法/构建 运行项目命令 退出码 0 待填写 待验收
核心流程 使用测试数据操作 结果符合规则 待填写 待验收
异常流程 缺参数或无权限请求 明确拒绝且不改数据 待填写 待验收
页面 桌面与手机检查 无遮挡和溢出 待填写 待验收
日志 搜索错误与敏感值 可追踪且已脱敏 待填写 待验收

18. 代码审查请求

如果希望 Codex 做审查，应明确“先找问题，不要先总结”。

text
请审查当前改动，重点检查：
- 行为回归和边界条件
- 数据安全与权限
- 并发、幂等和事务
- 外部 API 错误处理
- 缺失测试

先按严重程度列出发现，引用文件和行号；没有发现也要说明残余风险。暂时不要修改。

审查结论仍需要验证。尤其要警惕：

  • 只根据函数名推断行为，没有追踪调用。
  • 只检查成功路径。
  • 测试本身复用了错误实现，导致“错误地通过”。
  • 忽略数据库已有数据和升级过程。
  • 忽略浏览器、代理或第三方平台的异步行为。

第五部分小结

故障排查必须从可重复的现象和证据开始，并按输入、应用、数据、连接和外部服务逐层缩小范围。页面提示本身通常不足以证明原因。验收标准需要给出输入、操作、预期结果和异常行为，让另一位人员能够重复检查；编译通过只是最基础的一层，不等于业务闭环完成。

第六部分：安全、权限与长期维护

19. 权限不是越大越方便

Codex 是否能完成某项操作，取决于当前入口提供的文件、网络和命令权限。应按任务授予最小必要权限。

19.1 常见权限风险

  • 在错误目录运行批量删除或替换。
  • 把参考项目当成当前项目修改。
  • 使用生产密钥进行测试并写入日志。
  • 在未备份数据库前运行迁移。
  • 为解决一个端口问题停止无关服务。
  • 绕过审批和沙箱后执行来源不明脚本。

19.2 高风险动作确认表

执行前逐项回答：

  • 当前路径是否正确？
  • 操作对象是否属于本任务？
  • 是否有可恢复备份？
  • 是否知道命令会修改哪些文件或数据？
  • 是否会影响其他端口、项目、用户或业务数据？
  • 是否有更小范围的验证方式？
  • 失败后如何回滚？

20. 密钥与隐私

20.1 不应进入资料或代码的内容

  • API Key、AppSecret 等接口凭证。
  • API Key、Access Token、Cookie 和会话文件。
  • 管理员密码和验证码种子。
  • 数据库完整备份中的用户信息。
  • 私钥、证书私钥和云服务凭证。

20.2 推荐处理方式

  • 使用环境变量、受权限保护的配置文件或密钥管理服务。
  • 示例文件只使用明显的占位符。
  • 日志只保留必要标识，敏感字段脱敏。
  • 分享截图前检查地址栏、终端历史和浏览器自动填充。
  • 密钥疑似泄露时立即撤销并轮换，而不是只删除聊天记录。

21. 变更、备份与回滚

21.1 变更记录模板

text
变更日期：
变更目标：
修改文件：
数据变更：
服务操作：
验证命令：
验证结果：
备份位置：
回滚方法：
残余风险：

21.2 数据库备份原则

  • 使用数据库支持的一致性备份方法。
  • 备份文件与在线数据库分开存放。
  • 记录备份时间、版本和恢复步骤。
  • 定期做恢复演练；只有“能恢复”的文件才算有效备份。
  • 不把包含真实数据的备份直接放进公开仓库或外部共享目录。

22. 长任务中的进度管理

一个好的进度更新应说明“正在做什么、学到了什么、下一步是什么”，而不是只说“正在处理”。

示例：

text
已确认重复导入发生在请求重试路径，数据库没有唯一约束。
下一步先补充重复提交失败测试，再实现导入标识幂等写入；暂不调整其他导入格式。

任务完成记录应区分：

  • 已实现并验证。
  • 已实现但等待真实环境联调。
  • 仅有入口或草稿，尚未形成闭环。
  • 因缺少账号、数据或平台审核而阻塞。

第六部分小结

权限应按任务最小化，密钥和隐私数据不能进入文档、仓库或普通日志。删除、覆盖、迁移、重启和生产部署前，应确认路径、备份、影响范围和回滚方法。进度记录要区分“已实现并验证”“等待真实联调”“只有入口”和“被外部条件阻塞”，避免用一句“已完成”掩盖未闭环事项。

第七部分：可直接复用的模板

23. 通用实施任务模板

text
项目路径：/absolute/path/to/project

目标：
请实现……

现状：
目前……，实际结果是……，期望结果是……

范围：
- 可以读取：
- 可以修改：
- 可以运行：

限制：
- 禁止修改：
- 禁止重启：
- 不允许泄露：
- 必须保持：

验收：
- 测试命令：
- 页面或接口检查：
- 异常输入检查：

交付：
- 代码和文档
- 验证结果
- 未解决问题和残余风险

24. 只分析不修改模板

text
请先分析，不要修改文件、数据库、服务或外部平台。

需要回答：
1. 当前流程从哪里进入，经过哪些关键函数？
2. 现象的直接原因和根本原因分别是什么？
3. 哪些结论有日志或代码证据，哪些只是推测？
4. 可选方案及其风险是什么？
5. 推荐的最小修改范围和验证步骤是什么？

请引用具体文件位置。

25. 故障修复模板

text
错误现象：
完整错误：
复现步骤：
发生环境：
最近变更：
期望行为：
允许修改：
禁止操作：

请先稳定复现并补充失败测试，再修改根本原因。
修复后运行聚焦测试和受影响范围测试，并说明未覆盖风险。

26. 项目阅读模板

text
请阅读当前项目并输出项目地图，暂时不要修改。

内容包括：
- 技术栈和启动入口
- 目录职责
- 配置和环境变量来源
- 核心请求或任务流程
- 数据库和外部依赖
- 测试、构建、部署方式
- 与本次目标直接相关的文件
- 现有风险和待确认问题

结论必须引用文件位置，无法确认的内容标为未知。

27. 文件批处理模板

text
输入路径：
输出路径：
文件类型：
包含范围：
排除范围：
命名规则：
覆盖规则：
编码要求：
格式要求：

先统计和抽样，不修改源文件。
样本结果确认后再批量执行。
最终提供成功、跳过、失败数量和失败清单。

28. 前端页面验收模板

text
目标页面：
主要用户：
核心操作：
沿用的设计系统：
允许修改文件：

必须检查：
- 桌面视口 1440x900
- 手机视口 390x844
- 加载、空数据、失败和成功状态
- 键盘操作和表单标签
- 长标题、长 URL 和错误文字
- 浏览器控制台错误
- 按钮、文字和弹窗无重叠

完成后提供自动检查结果和截图。

29. 结果交付模板

text
完成内容：
- 

验证：
- 命令：
- 结果：

文件位置：
- 

未完成或等待外部条件：
- 

使用注意：
-

第七部分小结

模板的作用是帮助补齐必要信息，而不是让所有任务写成同一种长提示词。使用时应删掉不适用项目，并把占位符换成真实路径、输入、限制和验收标准。高风险任务适合分为“只分析”“确认方案”“实施修改”“独立验收”几个阶段，低风险小任务则可以一次完成。

第八部分：案例与练习

30. 案例一：修复导入乱码

30.1 初始需求

“CSV 导入乱码，帮我修一下。”

30.2 补齐信息

text
目标：让联系人导入同时支持 UTF-8 和常见 Windows 中文 CSV。
输入：一个 UTF-8 样本和一个带中文的 GBK 样本。
现状：UTF-8 成功，GBK 返回 invalid UTF-8。
范围：导入解析模块及测试夹具。
限制：不修改数据库字段，不改变 CSV 列名。
验收：两个样本导入后中文一致；未知编码返回可理解错误，不写入部分数据。

30.3 推荐执行

  1. 保存最小失败样本。
  2. 阅读导入入口和事务边界。
  3. 先补充失败测试。
  4. 明确支持的编码，不用忽略错误字节的方式“修复”。
  5. 转码后统一进入原解析流程。
  6. 验证失败时数据库没有部分写入。
  7. 更新导入说明。

30.4 练习

为“Excel 导出的日期被解析成数字”写一份同样结构的任务说明。

31. 案例二：阅读批量导入流程

31.1 目标

确认批量导入是否会产生重复记录或写入部分失败数据。

31.2 阅读路径

  1. 找到文件上传或导入路由。
  2. 检查身份验证和重复请求处理。
  3. 跟踪文件编码、表头和每行数据解析。
  4. 找到记录的唯一标识和去重规则。
  5. 检查缺失必填列和无效数据时的行为。
  6. 跟踪事务提交、回滚和导入结果记录。
  7. 阅读正常导入、重复提交、部分错误和大文件测试。

31.3 关键不变量

text
每条导入数据必须使用明确的唯一标识进行匹配。
缺少标识或校验失败时应明确拒绝，不能随机匹配已有记录，也不能留下部分写入。

这个不变量应同时出现在代码、测试、项目约束和使用说明中。

32. 案例三：把多份短资料整合为一份手册

32.1 错误方式

  • 按文件名顺序直接拼接。
  • 保留 100 次相同的“阅读说明”和“记录页”。
  • 只替换标题，正文没有独立内容。
  • 生成 PDF 后不检查字体和分页。

32.2 正确方式

  1. 统计标题和章节结构。
  2. 抽样比较文本相似度。
  3. 建立主题清单。
  4. 按用户完成任务的先后顺序重新分组。
  5. 去除重复说明，补充真实命令和案例。
  6. 统一术语、链接和安全提示。
  7. 生成 Word 和 PDF 后进行结构与视觉检查。

33. 七天练习计划

第 1 天：安装与低风险任务

  • 验证 codex --version 和 codex --help。
  • 在练习目录完成一次只修改单文件的任务。
  • 记录工作目录和验收结果。

第 2 天：提问表达

  • 把三个模糊需求改写为六要素任务。
  • 检查每个任务是否包含禁止操作和验收。

第 3 天：文件整理

  • 让 Codex 统计一个小目录，不立即修改。
  • 先处理两个样本，再进行批量操作。

第 4 天：文章、方案与报告

  • 用两至三份脱敏材料制作事实清单和文章提纲。
  • 将同一批材料分别整理为面向管理者的摘要和面向普通读者的说明。
  • 检查数字、日期和结论是否能回到原始材料。

第 5 天：PPT 与办公文件

  • 先制作一份 8 页 PPT 逐页大纲。
  • 使用 /skills 检查 docx、pptx 或 xlsx 是否可用。
  • 选择一个 Skill 生成样例文件，并打开或渲染检查版式。

第 6 天：代码阅读或数据处理

  • 选择一个小项目。
  • 输出入口、配置、核心流程和测试地图。
  • 随机核对三个文件引用是否正确。

非开发用户可以改为：清洗一份小型 Excel/CSV，检查日期、公式和汇总结果。

第 7 天：错误排查、验收与复盘

  • 选择一个可重复的小错误。
  • 填写错误记录模板。
  • 分别列出现象、证据、直接原因和根本原因。
  • 完成一个范围明确的小修改或办公文件任务，并独立验收。
  • 汇总本周最有效的三个提示词。
  • 找出一次返工的原因。
  • 为自己的常用项目编写或完善 AGENTS.md。

第八部分小结

案例把抽象方法落实为 CSV 编码、批量导入和多文档整合三种场景。七天练习的目标不是背诵命令，而是建立一条可重复的工作路径：先准备安全练习环境，再提升表达、文章与方案创作、PPT/办公文件处理、代码或数据阅读、排错、验收和复盘能力。完成练习后，应保留有效提示词和个人检查清单。

第九部分：效率方法与常见问题

34. 高效使用不是一次提出所有要求

对于复杂任务，推荐采用“探索、实施、验证”三个阶段：

阶段一：探索

text
先阅读相关规则、入口和测试，说明现状与风险，不修改。

阶段二：实施

text
按已确认方案修改指定范围，先完成最小闭环。

阶段三：验证

text
运行测试，检查差异和真实页面/接口；修复本轮引入的问题。

任务很小且边界清楚时可以一次完成；涉及生产、支付、账号权限和数据迁移时应保留阶段检查点。

35. 常见低效习惯

35.1 只说“继续做”

长会话中“继续”可能指向过期目标。更有效的说法是：

text
继续完成上线前检查中的第 2 项，只处理图片验证；其他待办暂不处理。

35.2 反复要求“全部做好”但没有验收

把“全部”展开成清单，并标出哪些需要真实账号、外部审核或业务数据。技术入口完成不代表线上闭环完成。

35.3 遇到错误立即换方案

先保存错误、检查日志和最小复现。不断更换命令会破坏现场，让原因更难确认。

35.4 把参考项目直接复制到当前项目

参考项目可用于理解模式，但它可能有不同端口、密钥、数据库和业务规则。应逐项确认适用性，不能复制后混用服务和配置。

35.5 只看最终回复，不看文件和测试

最终回复是工作摘要，不是完成证据。关键任务应核对实际文件、测试输出、服务状态和外部平台结果。

36. 常见问题

36.1 codex: command not found 怎么办？

重新打开终端，运行 command -v codex（Windows 使用 Get-Command codex），检查安装目录是否进入 PATH。若使用 npm，再检查 npm 全局可执行目录。不要在原因不明时连续使用多种方式重复安装。

36.2 登录成功但请求失败怎么办？

依次检查登录状态、网络、配置来源、服务商、模型可用性和额度。使用 API Key 时确认密钥对应的服务地址与计费主体；不要把不同服务商的密钥混用。

36.3 为什么 Codex 没有修改文件？

可能原因包括：当前任务是分析请求、工作目录错误、文件不在可写范围、权限受限、需求存在冲突或命令失败。先要求它说明当前路径、权限和阻塞证据。

36.4 为什么它修改了不相关文件？

检查任务是否明确了修改范围，项目是否有生成器或格式化工具造成连带变化。让 Codex 列出每个改动文件及原因；对来源不明的已有改动不能直接覆盖或回退。

36.5 能否让 Codex 直接操作服务器或网页？

只有当前环境提供对应权限和工具时才可以。即使技术上可操作，生产数据、账号设置、公开发布和付费行为仍应使用最小权限、审计和明确授权。

36.6 能否完全相信自动测试？

不能。测试只证明被覆盖的输入满足测试断言。还需检查测试是否贴近真实流程、是否遗漏外部系统异步状态、历史数据和浏览器行为。

36.7 配置文件在哪里？

Codex CLI 默认从 ~/.codex/config.toml 读取用户配置，也可以通过命令行 -c key=value 临时覆盖。版本可能增加或调整配置项，应以本机 codex --help 和官方文档为准。修改前备份原文件。

36.8 如何更新？

先运行：

bash
codex update

如果当前安装方式不支持该命令，则使用原安装渠道更新，例如 npm 或 Homebrew。更新后运行 codex --version 和 codex doctor，并在练习目录做一次低风险验证。

36.9 Codex 能否直接制作 PPT、Word、Excel 或 PDF？

可以，但要区分内容生成和文件生成：

  • 不使用额外 Skill 时，Codex 可以先生成文章正文、方案、PPT 逐页大纲、表格字段和公式设计。
  • 要创建或编辑实际的 .pptx、.docx、.xlsx、.pdf 文件，通常应使用对应的 pptx、docx、xlsx、pdf Skill。
  • 安装 Skill 后仍可能需要 LibreOffice、Pandoc、Poppler、字体或 Python/Node.js 依赖。
  • 生成文件不等于完成。Word/PDF 要检查目录、分页和字体；PPT 要渲染每页检查溢出和图片；Excel 要检查公式、日期、金额和汇总结果。
  • 当前会话没有对应 Skill 时，可使用 skill-installer 查询和安装，重启 Codex 后再用 /skills 确认。

第九部分小结

高效使用 Codex 的关键不是一次塞入所有要求，而是根据风险选择合适的阶段和检查点。不要只说“继续做”，不要在没有验收标准时反复要求“全部做好”，也不要在错误发生后无记录地频繁换方案。安装、认证、配置、网络和模型可用性是不同层面，应逐层确认。

第十部分：复盘与个人工作规范

37. 每次任务后的五分钟复盘

text
任务目标：
最终结果：
最有效的信息：
发生返工的地方：
返工原因：
验证是否充分：
应写入项目规则的内容：
下次可以复用的提示词：
仍待处理的风险：

38. 建立个人检查清单

开始前

  • 我知道当前工作目录。
  • 我读过项目规则。
  • 我写清楚了目标和验收。
  • 我明确了允许和禁止修改的范围。
  • 我没有提供明文密钥和隐私数据。

执行中

  • 先观察和复现，再修改。
  • 每一步都有可检查结果。
  • 没有夹带无关重构。
  • 高风险动作有备份和回滚办法。
  • 外部平台的审核状态没有被误判为最终结果。

完成后

  • 已运行相关测试。
  • 已检查实际文件和差异。
  • 已检查异常路径和安全边界。
  • 已区分本地完成与线上联调完成。
  • 已记录文件位置、验证结果和残余风险。

39. 个人使用规范示例

text
1. 所有任务先写绝对路径。
2. 参考项目默认只读，除非任务明确授权修改。
3. 删除、覆盖、重启和生产部署前必须单独确认。
4. 密钥只从环境变量或受保护配置读取。
5. 修改代码必须运行相关测试并检查差异。
6. 批量任务先抽样，输出到独立目录。
7. 外部平台状态必须通过真实查询确认。
8. 完成记录要写验证证据，不能只写“已完成”。

第十部分小结

稳定协作来自长期习惯。每次任务结束后，用几分钟记录有效信息、返工原因、验证范围和残余风险；把只适用于本次的内容留在任务记录，把需要长期遵守的内容写入项目规则。个人规范应足够短，能够在每次开始、执行和完成时真正使用。

附录 A：命令速查

A.1 Codex CLI

bash
codex -V                              # 查看版本
codex --help                          # 查看当前版本的命令和参数
codex doctor                          # 诊断安装、配置、认证和运行环境
codex                                 # 在当前目录启动交互会话
codex -C /absolute/path/to/project    # 在指定项目目录启动
codex -m '<当前可用模型名>'            # 启动时临时指定模型
codex exec "任务内容"                 # 非交互执行一次任务
codex review                          # 从终端进入代码审查流程
codex login status                    # 查看登录状态
codex resume --last                   # 继续最近会话
codex fork --last                     # 从最近会话创建分支
codex mcp list                        # 列出已配置的 MCP 服务
codex plugin list                     # 列出插件市场中的插件
codex update                          # 当前版本支持时尝试更新

临时覆盖单个配置值：

bash
codex -c 'key="value"'

查看某个子命令的准确参数：

bash
codex exec --help
codex review --help
codex mcp --help
codex plugin --help

codex review、codex mcp list 等是在系统终端执行的顶层命令；/review、/mcp 等是在 Codex 交互会话输入框中执行的斜杠命令。不要照抄不理解的模型名或配置键，应先查看当前版本帮助、会话中的 / 菜单和官方说明。

A.2 文件与搜索

bash
pwd                          # 当前目录
ls -lah                      # 文件列表
rg --files                   # 快速列出项目文件
rg -n "关键词"               # 搜索文本并显示行号
file 文件名                  # 文件类型和编码线索
wc -l 文件名                 # 统计行数
sha256sum 文件名             # 计算哈希

A.3 Git 基础检查

bash
git status --short
git diff --check
git diff
git log -n 5 --oneline

不要在存在未确认改动时使用破坏性恢复命令。

A.4 服务检查

bash
ss -lntp
systemctl status 服务名 --no-pager
journalctl -u 服务名 -n 100 --no-pager
curl -i http://127.0.0.1:端口/health

附录 B：一页式任务卡

text
【目标】

【当前现象】

【项目路径】

【相关文件/日志】

【允许修改】

【禁止修改】

【输入与样例】

【验收标准】

【测试命令】

【交付形式】

【待确认风险】

附录 C：资料与服务边界

本手册提供的是学习和操作参考，不代表以下承诺：

  • 不提供 OpenAI、ChatGPT、Codex 或第三方平台账号。
  • 不包含 API 调用额度、订阅费用或模型使用费。
  • 不保证任何第三方配置服务长期可用、免费或适合所有地区。
  • 不代替软件官方文档、平台规则和组织安全政策。
  • 不包含未经授权的软件许可、破解内容或绕过访问控制的方法。
  • 不保证所有示例可不经调整直接用于生产环境。

安装包、脚本和链接具有时效性。使用者应在运行前检查来源、版本、签名、权限和实际修改内容，并以当前官方文档和配置页面为准。

附录 D：推荐资源

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

Windows Codex 复制命令：
https://code.jimuxyz.com/dashboard/codex-installation/windows-copy

macOS/Linux Codex 复制命令：
https://code.jimuxyz.com/dashboard/codex-installation/macos-linux-copy

本站 Codex 桌面版和插件配置说明：
https://code.jimuxyz.com/dashboard/desktop-app-config#codex

CLI 配置总入口：
https://code.jimuxyz.com/docs/cli#config

Codex 官方开源仓库与版本发布：
https://github.com/openai/codex
https://github.com/openai/codex/releases/latest

OpenAI 官方精选 Skills 仓库：
https://github.com/openai/skills/tree/main/skills/.curated

Codex 官方 App 与 Web：
https://chatgpt.com/codex?app-landing-page=true
https://chatgpt.com/codex

使用外部资源时，先确认页面域名、服务主体和最新更新时间。不要在不可信页面提交账号密码、API Key 或支付信息。

附录 E：Codex 斜杠命令完整说明

本附录依据 2026 年 7 月 14 日核对的 Codex CLI 0.144.1 及其对应官方开源代码整理。斜杠命令更新较快，不同系统、登录方式、组织权限和实验功能可能显示不同菜单。

最重要的规则：进入 Codex 交互界面后输入 /，以本机弹出的命令列表和说明为最终准则。本附录用于理解命令，不应替代当前版本菜单。

E.1 斜杠命令与终端命令的区别

下面内容在 Codex 交互输入框中执行：

text
/model
/permissions
/status

下面内容在 Bash、PowerShell 或 VS Code 内置终端中执行：

bash
codex --help
codex -m '<模型名>'
codex resume --last

不要在 PowerShell 中直接输入 /model，也不要在 Codex 对话输入框中把 codex --help 当作斜杠命令。

E.2 模型、权限和状态

命令 作用 使用建议
/model 选择模型和推理强度 复杂任务提高推理强度，简单任务先用较低档；列表由当前 provider 和 Key 决定
/permissions 选择或查看 Codex 被允许执行的操作 陌生项目先受限，按任务需要逐步开放，不长期绕过审批
/status 查看当前会话配置、目录、模型、上下文和 token 使用等状态 启动、恢复会话、切换目录或排错时优先查看
/usage 查看账号用量、限制或重置时间等信息 是否可用及显示内容取决于登录方式、套餐和 provider
/debug-config 查看配置层、项目要求和配置来源 用于排查“为什么某配置不生效”，输出可能含路径等环境信息，分享前先脱敏
/logout 退出当前 Codex 认证 会影响后续请求；只有明确需要切换账号或认证路径时使用

/permissions 调整的是工具可执行范围，不是模型能力。即使选择更强模型，它也不会自动获得文件写入、网络或生产环境权限；即使开放了高权限，模型也不应超出任务明确范围。

E.3 会话与上下文管理

命令 作用 注意事项
/new 在当前运行中开始一个新聊天 适合切换到完全不同的任务，先记录旧任务的验证结果
/clear 清理终端显示并开始新聊天 不要把它误认为仅清屏；当前版本说明中还包含开始新聊天
/compact 总结当前对话，降低上下文占用 长任务接近上下文上限时使用；压缩后应重申关键路径、禁区和验收标准
/resume 选择并恢复已保存的会话 恢复后先用 /status 核对目录、模型和任务状态
/fork 从当前会话分叉一个新会话 适合比较两种方案，不应让两个分支同时修改同一批文件
/rename <名称> 重命名当前会话 用“项目-任务-日期”比“新会话 1”更容易检索
/archive 归档当前会话并退出 适合保留记录但不再出现在日常活跃列表
/delete 永久删除当前会话并退出 破坏性操作；删除前确认交接、结论和验证证据已另行保存
/quit、/exit 退出 Codex 退出前确认没有仍在运行的命令和未核对的改动
/feedback 向维护者发送反馈或日志 发送前检查日志中是否包含项目路径、代码、密钥或隐私数据

/compact 不是删除文件，也不是开启新会话；它主要压缩会话上下文。压缩不能保证保留每个细节，因此长任务的关键规则仍应写入 AGENTS.md、任务文档或明确的交接记录。

E.4 文件、差异和结果检查

命令 作用 使用建议
/mention 在消息中引用文件 用于精确提供相关文件，不代表授权修改该文件
/diff 显示当前 Git 差异，并可包含未跟踪文件 修改后必查；仍需结合测试和重新读取文件验收
/review [补充要求] 审查当前改动并寻找问题 让 findings、风险和缺失测试优先，不要只要求总结
/copy 将上一条回复按 Markdown 复制 复制前检查内容中是否有密钥、内部地址或隐私信息
/raw 切换便于终端选择和复制的原始回滚显示 适合复制长输出；它不改变模型或任务内容
/init 在当前项目生成 AGENTS.md 指引文件 生成后必须人工审查，不要覆盖已有项目规则或写入密钥
/import 从 Claude Code 导入设置、项目或近期聊天 仅在确认来源、导入范围和隐私边界后使用，具体能力随版本变化

/review 是会话内审查；终端里的 codex review 是 CLI 顶层审查入口。两者都不能替代测试，也不保证发现所有问题。

E.5 工作模式和多代理能力

这些命令受版本、功能开关或当前产品入口影响，不一定每个人都能看到：

命令 作用 适合场景
/plan 切换到计划模式 先分析方案、风险和步骤，暂不直接实施
/goal 设置或查看长任务目标 需要跨多轮持续推进、有明确完成条件的任务
/agent、/subagents 切换或管理代理线程 将互不冲突的调研或实现任务并行处理
/side、/btw 在临时分叉中开启旁支对话 主任务执行中询问不应污染主上下文的附带问题
/personality 选择 Codex 的沟通风格 只改变表达倾向，不改变权限、事实和验收要求
/ide 引入编辑器选区、打开文件等 IDE 上下文 使用 IDE 集成时帮助精确引用当前编辑状态
/app 将会话继续到 Codex Desktop 当前源码仅在支持的 macOS/Windows 环境显示，且依赖 App 可用性

多代理并行不等于无限加速。多个代理同时编辑相同文件、数据库或部署环境会增加冲突风险。应拆分为互不重叠的工作范围，并由主会话统一检查和集成结果。

E.6 Skills、MCP、Apps、Plugins 和 Hooks

命令 作用 关键边界
/skills 查看或使用当前可用 Skills Skill 是工作流程说明，不自动提供账号、依赖或外部权限
/mcp 列出已配置 MCP 工具；/mcp verbose 查看更多细节 MCP 可连接外部数据和动作，必须确认服务来源、认证和可写范围
/apps 管理当前可用 Apps 是否显示取决于登录、插件和功能开关
/plugins 浏览或管理插件 Plugin 可捆绑 Skills、MCP、Hooks 等，比单个 Skill 权限面更大
/hooks 查看和管理生命周期 Hooks Hook 可在命令或文件操作前后自动运行，安装外部 Hook 前必须审查脚本
/memories 配置会话记忆的生成和使用 不适合保存密钥、临时口令或不应跨会话保留的敏感信息
/experimental 开关实验功能 实验功能可能不稳定、改变或被移除，不应用于关键生产流程的唯一方案

安装新的 Skill、Plugin 或 MCP 后，通常需要重启 Codex 或开启新会话，才能重新加载能力清单。

E.7 终端和界面控制

命令 作用 注意事项
/ps 查看后台终端任务 长任务排错时确认是否仍有命令运行
/stop 停止所有后台终端；当前版本还接受 /clean 别名 可能中断构建、下载或迁移，执行前确认影响
/keymap 配置 TUI 快捷键 修改后记录自己的映射，避免与终端快捷键冲突
/vim 切换输入区 Vim 模式 只影响输入编辑方式
/title 配置终端标题显示项 可显示项目、模型或任务线索，分享截图前检查隐私
/statusline 配置底部状态栏项目 用于持续显示模型、目录、上下文等信息
/theme 选择语法高亮主题 只影响显示
/pets、/pet 显示、选择或隐藏终端装饰项 与任务能力无关；部分版本或策略可能不显示

E.8 沙箱、审批和条件命令

命令 作用 条件或风险
/setup-default-sandbox 配置增强或默认代理沙箱 依赖系统支持和当前版本；先理解文件、网络边界
/sandbox-add-read-dir <绝对路径> 给沙箱增加一个只读目录 当前源码主要在 Windows 显示；只添加任务必需路径
/approve 对最近一次自动审查拒绝批准一次重试 仅在对应自动审查流程出现时有意义，不是通用“批准所有”

启动 CLI 时还可以用 --sandbox 和 --ask-for-approval 设置策略。--dangerously-bypass-approvals-and-sandbox 会绕过审批与沙箱，风险极高，不应作为日常教程或排错捷径。

E.9 不应日常使用的内部命令

源码中可能存在 /rollout、/test-approval、/debug-m-drop、/debug-m-update 等调试命令。部分命令只在调试构建中可见，部分源码明确标注“不要使用”。普通用户不应尝试启用或依赖这些内部命令。

E.10 推荐的日常命令顺序

开始任务：

text
/status
/permissions
/model

实施过程中：

text
/mention
/status

完成前：

text
/diff
/review
/status

长会话接近上限时：

text
/compact

命令只是辅助。真正的完成标准仍然是：文件内容正确、测试通过、页面或接口实测符合预期、没有越界修改，并清楚记录残余风险。

附录 F：Skills 安装、选择与使用

F.1 Skill 是什么

Skill 是一个可复用、可触发的专业工作流程目录。它通常包含一个必需的 SKILL.md，也可以带脚本、参考文档和输出资产。Skill 可以教 Codex 如何稳定完成某类工作，例如创建 Word、检查 PDF、运行 Playwright、处理 Figma 或部署到云平台。

一个典型 Skill 结构如下：

text
skill-name/
├── SKILL.md
├── agents/
│   └── openai.yaml
├── scripts/
├── references/
└── assets/

各部分作用：

  • SKILL.md：名称、触发说明和核心工作流程，是 Skill 的必需文件。
  • agents/openai.yaml：可选的界面显示信息。
  • scripts/：重复、精确或容易出错的确定性操作脚本。
  • references/：按需读取的规范、API 文档和领域知识。
  • assets/：模板、图标、字体、示例文件等输出资源。

Skill 不是模型，不会让弱模型永久变成强模型；Skill 也不是账号或权限，不会自动获得 GitHub、Notion、Figma、服务器或浏览器登录状态。它主要让 Codex 知道“遇到这类任务应按什么流程做”。

F.2 Skill、Plugin、MCP 和 AGENTS.md 的区别

机制 适用范围 解决的问题 示例
当前提示词 当前任务或当前对话 一次性的目标、限制和验收 “只修改这个 Markdown”
AGENTS.md 某个仓库或子目录长期生效 项目规则、测试命令、禁区和编码规范 “参考目录只读，修改后运行项目测试”
Skill 跨项目复用的某类任务流程 文档、测试、部署、设计等专业步骤 pdf、playwright、openai-docs
Plugin 可安装的能力包 可同时打包 Skills、命令、工具、MCP、Hooks、资产等 团队完整开发工具包
MCP 连接实时外部系统 读取或操作 Notion、Figma、数据库、内部 API 等 Figma MCP、文档 MCP
Hook 工具调用或生命周期前后的自动规则 强制检查、记录、拦截或自动执行 修改后自动运行格式检查
config.toml 用户或项目的 Codex 运行设置 模型、provider、沙箱、MCP、功能开关等 ~/.codex/config.toml

选择原则：一次要求写进提示；项目长期规则写进 AGENTS.md；跨项目重复流程做成 Skill；需要实时外部数据时使用 MCP；需要整套可安装能力时再使用 Plugin。

F.3 如何查看已经可用的 Skills

在 Codex 会话中输入：

text
/skills

也可以直接询问：

text
请列出本次会话可用的 Skills，并按文档、浏览器、设计、部署和协作分类说明。

Skills 默认通常位于：

text
~/.codex/skills/<skill-name>/SKILL.md

如果设置了 CODEX_HOME，则位于：

text
$CODEX_HOME/skills/<skill-name>/SKILL.md

文件夹存在不等于当前会话已经加载。安装后应完全重启 Codex 或开启新会话，再用 /skills 检查。

F.4 推荐的官方系统 Skills

这类 Skill 通常随 Codex 环境提供，不需要重复下载安装：

Skill 用途 什么时候使用
openai-docs 按官方资料查询 Codex 和 OpenAI 产品、模型、API 询问 Codex 配置、最新模型、OpenAI API 或官方行为时
skill-installer 列出和安装精选 Skill，或从 GitHub 路径安装 用户要求安装、列出或更新 Skills 时
skill-creator 创建或更新自定义 Skill 团队有重复工作流、规范或脚本需要固化时
plugin-creator 创建符合结构要求的 Codex Plugin 单个 Skill 不足，需要捆绑更多能力时
imagegen 生成或编辑位图图像 需要产品图、插图、背景、素材修改时

系统 Skill 已存在时不要从未知来源覆盖。若同名目录来自不同仓库，应先比较来源和内容。

F.5 文档与数据处理 Skills

以下是常见的实用 Skills 示例，不代表每一套 Codex 都已预装，也不代表全部来自同一发布者。安装前应先通过 /skills 和 skill-installer 核对当前来源；非 OpenAI 官方来源必须按 F.12 节审查。

Skill 主要能力 使用示例 额外注意
docx 创建、读取、编辑 Word，处理目录、页码和排版 “把这份 Markdown 制作为专业 Word” 需要最终打开或渲染检查版式
pdf 读取、合并、拆分、旋转、OCR、生成和检查 PDF “合并这些 PDF 并生成目录” 扫描件要确认 OCR；生成后抽查页面
xlsx 创建和编辑 Excel/CSV，清洗数据、公式和图表 “清洗销售表并生成汇总” 公式、日期、金额和编码要抽样核对
pptx 创建、读取和编辑 PowerPoint “把报告做成 12 页可编辑演示文稿” 必须渲染检查溢出、字体、图片和备注
jupyter-notebook 创建和维护 .ipynb 实验或教程 数据探索、模型实验、教学笔记 保持单元可重复运行，清理敏感输出

使用这些 Skills 时仍可能需要相应的本地依赖。例如处理 Word 或 PDF 可能需要 LibreOffice、Pandoc、Poppler 或 Python 库；缺少依赖时，应先说明用途并从可信来源安装。

F.5.1 内容创作任务如何选择输出和 Skill

任务 可以先让 Codex 直接输出 需要正式文件时 必查内容
文章撰写 Markdown 提纲、初稿、改写稿 使用 docx 制作 Word，必要时使用 pdf 输出 PDF 事实、引用、原创性、语气、字数
方案设计 目标、现状、选项、实施步骤和风险清单 使用 docx 形成正式方案，使用 pptx 做汇报版 前提、数据、预算、责任人、时间表
PPT 叙事主线、逐页大纲、讲稿、图表建议 使用 pptx 创建或编辑 .pptx 页数、逻辑、字号、溢出、图片、备注
报告整理 材料清单、证据表、摘要、章节正文 使用 docx/pdf 形成报告，使用 xlsx 放明细数据 来源、数字、结论、附件、目录和页码
产品文案 受众、卖点、标题、详情、FAQ 和多版本文案 使用 docx 汇总，必要时用 xlsx 管理文案矩阵 真实性、平台规则、禁用词、版本一致性
会议与日常办公 纪要、待办、邮件、周报、计划 使用 docx、xlsx 或 Notion 类 Skill 人名、日期、责任人、截止时间、隐私

F.5.2 办公创作的六步工作流

  1. 整理素材： 将原始资料放到 sources/，模板和品牌规范放到 references/，不要覆盖原文件。
  2. 明确任务： 写清目标读者、使用场景、篇幅/页数、语气、输出格式和截止时间。
  3. 先做结构： 先让 Codex 输出素材清单、事实表、文章提纲或 PPT 逐页大纲，不急于生成最终文件。
  4. 生成内容： 确认结构后再写正文，或调用 docx、pptx、xlsx、pdf 等 Skill 生成文件。
  5. 核对事实： 数字、日期、引文、法规、产品能力和外部结论必须回到来源检查；缺乏依据时标为待核实。
  6. 检查成品： 打开或渲染输出文件，检查版式、公式、图表、图片、链接、分页、演讲时长和可编辑性。

F.5.3 可直接使用的文章与报告提示词

text
请根据 sources 目录中的材料撰写一份报告。

目标读者：
使用场景：
核心问题：
篇幅：
输出格式：先 Markdown，确认后再使用 docx Skill 生成 Word。

工作步骤：
1. 先列出所有素材及其日期、作者、核心事实；
2. 标出材料之间的重复、冲突和缺失；
3. 给出报告目录和每章目标，等我确认；
4. 只依据可核实材料写正文，不确定内容标为“待核实”；
5. 在文末给出事实核对表和仍需补充的资料；
6. 生成 Word 后检查目录、页码、表格、链接和分页。

F.5.4 可直接使用的方案设计提示词

text
请根据现有资料设计一份可执行方案，先不要直接给唯一结论。

请输出：
- 背景和当前问题
- 目标与不在范围内的事项
- 约束和关键假设
- 方案 A、B、C 的成本、收益、风险和适用条件
- 推荐方案及推荐依据
- 分阶段实施计划、负责人角色、里程碑和验收标准
- 风险登记表、回滚方案和待确认问题

没有数据支持的数字不要编造；假设必须单独标出。

F.5.5 可直接使用的 PPT 提示词

只需要 PPT 大纲时：

text
请为“主题”设计一份 10 分钟、8 页的 PPT 逐页大纲。
受众是：
汇报目标是：

每页包含：页标题、一句话核心结论、3 至 5 个要点、建议图表或图片、演讲备注。
整套结构必须形成“问题 -> 证据 -> 方案 -> 风险 -> 行动”的叙事，不要把长报告逐段贴到幻灯片。

需要实际 .pptx 文件时：

text
请使用 pptx Skill，根据已确认的逐页大纲创建可编辑的 16:9 PPT。
输出路径：output/presentation.pptx
视觉要求：
品牌颜色/模板：
图片来源：只使用 references 中已授权素材；不足时先列出缺口。

完成后必须渲染全部页面并检查：
- 标题、正文、页码、图表和图片没有重叠或裁切；
- 每页只有一个核心结论，正文适合现场阅读；
- 图表数字与 sources 一致；
- 图片不拉伸，备注与页面内容匹配；
- 文件可正常打开和继续编辑。

F.5.6 可直接使用的产品文案提示词

text
请根据 sources 中已经确认的产品资料撰写文案。

目标用户：
使用平台：
核心场景：
语气：
禁止使用的表达：

先输出“事实清单”和“不能确认的卖点”，再提供 3 组标题、1 份正文、5 个 FAQ 和 3 个短文案版本。
不得编造功能、效果、用户评价、授权或优惠；最终逐条检查文案是否与真实产品能力一致。

F.6 浏览器、前端和界面测试 Skills

Skill 主要能力 推荐场景
playwright 自动化真实浏览器，填写表单、截图和验证流程 网页登录、表单、后台操作和回归测试
playwright-interactive 保持浏览器会话，快速迭代调试 需要多轮查看页面状态和定位交互问题
webapp-testing 面向本地 Web 应用的综合测试流程 启动本地服务后检查功能、控制台和截图
frontend-design 创建或美化生产级前端界面 仪表盘、后台、页面和组件设计
screenshot 截取整个桌面、窗口或指定区域 需要操作系统级截图且其他工具不能截图时

浏览器 Skill 不会自动拥有网站账号。遇到验证码、短信、支付、隐私授权或高风险发布动作时，应由用户确认；不要把账号密码硬编码进 Skill、脚本或仓库。

F.7 视觉、音频和内容制作 Skills

Skill 主要能力 推荐场景
imagegen 生成或编辑位图 封面、插图、抠图和场景图
canvas-design 设计海报、静态视觉和 PDF 艺术品 宣传图、信息图、活动海报
theme-factory 为文档、网页和演示统一主题 统一颜色、字体和视觉规范
transcribe 将音频或视频语音转成文本，可做说话人区分 会议、访谈、课程和录音整理
speech 把文字生成语音 旁白、无障碍朗读和批量语音内容

生成公开内容时必须保持真实，不应用 Skill 制作虚假授权、假评价或误导性截图。

F.8 Figma、协作和项目管理 Skills

Skill 主要能力 使用前提
figma 获取 Figma 设计上下文、截图、变量和资产 Figma MCP 可用，具备文件访问权限
figma-use 在 Figma 文件中执行读写操作的基础流程 进行 Figma 写操作前必须按其工作流执行
figma-implement-design 将 Figma 设计实现为生产代码 提供有效 Figma 链接/节点和目标代码库
figma-generate-design 将页面或描述生成到 Figma 需要 Figma 写权限和设计系统上下文
figma-generate-library 在 Figma 创建或更新设计系统 需要明确 token、组件和主题范围
linear 读取、创建和更新 Linear 事项 已连接并授权 Linear
notion-knowledge-capture 把对话和决策整理到 Notion 已连接并授权 Notion 工作区
notion-research-documentation 跨 Notion 页面调研并形成文档 有权读取相关页面
notion-spec-to-implementation 将 Notion 需求转为实施计划和任务 需求页面可访问且边界明确
notion-meeting-intelligence 基于 Notion 准备会议材料 有参会人和背景资料权限

这些 Skill 通常还依赖 MCP 或连接器。只安装 Skill 而没有完成外部服务授权时，Codex 只能说明流程，不能读取私有文件。

F.9 代码、安全、CI 和部署 Skills

Skill 主要用途 适合场景
gh-fix-ci 分析并修复 GitHub Actions CI 失败 已授权 GitHub，且允许修改相关代码/配置
gh-address-comments 处理 Pull Request 审查意见 需要逐条核对意见和改动证据
security-best-practices 按语言和框架检查安全实践 用户明确要求安全审查或安全实现建议时
security-threat-model 建立威胁模型、资产和信任边界 新系统、敏感数据或高风险功能设计阶段
security-ownership-map 分析安全相关代码所有权和风险集中点 大型仓库、关键模块和人员风险分析
sentry 查询和分析 Sentry 错误 已配置 Sentry 访问，注意生产隐私数据
vercel-deploy 部署到 Vercel 前端或全栈项目，已具备账户和项目权限
cloudflare-deploy 部署到 Cloudflare Workers、Pages 等 Cloudflare 项目
netlify-deploy 部署到 Netlify 静态站点和支持的 Web 项目
render-deploy 部署到 Render Web 服务、后台任务和数据库相关项目
aspnet-core ASP.NET Core 项目工作流 .NET Web API 和后端项目
winui-app Windows WinUI 应用开发 Windows 桌面应用项目
cli-creator 设计和创建命令行工具 需要稳定参数、帮助、错误处理和发布流程
migrate-to-codex 将其他代理工作流迁移到 Codex 从其他工具切换配置、规则和操作习惯

部署 Skill 不应在没有确认域名、环境变量、账单、回滚和生产权限的情况下直接发布。安全 Skill 也不能给出“绝对安全”的保证。

F.10 推荐安装组合

不要一次安装所有 Skills。每个 Skill 都会增加能力发现、依赖和审查成本，应按真实工作选择。

普通学习和文档用户：

text
openai-docs、docx、pdf、xlsx、pptx、screenshot

文章、方案、PPT 与日常办公用户：

text
docx、pptx、xlsx、pdf、imagegen、theme-factory、screenshot

这组适合文章撰写、正式方案、汇报材料、报告、会议纪要、周报、产品文案和办公文件。文章或方案本身不一定要求 Skill，但生成正式 Word/PPT/Excel/PDF 时应使用对应 Skill。

Web 开发用户：

text
openai-docs、playwright、playwright-interactive、webapp-testing、frontend-design、screenshot

设计和内容用户：

text
imagegen、canvas-design、theme-factory、figma、figma-use、figma-implement-design

GitHub 和生产维护用户：

text
gh-fix-ci、gh-address-comments、security-best-practices、security-threat-model、sentry

团队协作用户：

text
linear、notion-knowledge-capture、notion-research-documentation、notion-spec-to-implementation

新手第一批建议只安装 3 至 6 个真正会用的 Skill，实际使用一段时间后再扩充。

F.11 安装 Skills 的推荐方法

官方精选 Skill 来源：

https://github.com/openai/skills/tree/main/skills/.curated

推荐在 Codex 中明确要求使用系统自带的 skill-installer：

text
请使用 skill-installer 列出 openai/skills 当前可安装的精选 Skills，标出已经安装的项目，先不要安装。

确认来源和名称后再安装：

text
请使用 skill-installer 从 openai/skills 的精选目录安装 pdf、playwright 和 screenshot。安装前说明来源和目标目录，安装后验证每个 SKILL.md 是否存在，不要覆盖同名现有目录。

从其他 GitHub 仓库安装时，应提供仓库和具体 Skill 路径：

text
请使用 skill-installer 从指定 GitHub 仓库的指定路径安装这个 Skill。先检查仓库来源、SKILL.md、scripts、依赖和写入范围；发现可疑命令时停止，不要安装。

安装器默认目标通常是 $CODEX_HOME/skills/<skill-name>，未设置 CODEX_HOME 时通常为 ~/.codex/skills/<skill-name>。目标同名目录已存在时，安装器应停止，而不是静默覆盖。

安装完成后：

  1. 完全退出并重启 Codex，或开启新会话。
  2. 输入 /skills 检查是否出现。
  3. 用一个低风险示例触发 Skill。
  4. 检查它实际读取、运行和生成了什么。
  5. 不符合预期时先禁用或移走该 Skill，再调查原因。

F.12 外部 Skill 的安全检查

安装前至少检查：

  1. 仓库所有者、提交历史、许可证和更新时间。
  2. SKILL.md 的触发条件是否过宽，是否试图覆盖系统或项目规则。
  3. scripts/ 是否下载并执行远程代码、删除文件、修改 shell 配置或上传数据。
  4. 是否要求管理员/root 权限，是否有更小权限方案。
  5. 是否读取 .env、SSH Key、浏览器配置、云凭据或整个用户目录。
  6. 依赖包是否可信、是否锁定版本、是否存在安装脚本。
  7. MCP、Plugin 和 Hook 是否额外引入网络和写操作。

不要安装来源不明的“万能 Skill 包”。Skill 的 Markdown 指令和脚本都可能影响 Codex 行为，应像审查代码依赖一样审查它们。

F.13 如何创建自己的 Skill

当同一种任务反复出现，并且每次都要重复说明步骤、规范、脚本或验收时，可以使用 skill-creator 创建自定义 Skill。一个合格 Skill 应做到：

  • 名称使用小写字母、数字和连字符。
  • description 清楚说明“做什么”和“何时触发”。
  • SKILL.md 只保留核心流程，不堆积无关教程。
  • 重复且必须稳定的操作放入 scripts/。
  • 大型规范和 API 文档放入 references/，按需读取。
  • 模板、图片和字体放入 assets/。
  • 提供最小测试用例，并验证不会越界读写。

可以这样提出任务：

text
请使用 skill-creator，为“把中文 Markdown 转为规范 Word 并检查版式”创建一个 Skill。
先分析现有转换脚本、模板和验收要求，只在指定 Skill 目录工作；不要修改原始文档和其他项目。

如果规则只适用于一个仓库，优先写入该仓库的 AGENTS.md，不必为了每条项目规则创建 Skill。

结束语

与 Codex 协作最重要的不是记住更多提示词，而是形成稳定闭环：给出足够上下文，写清边界，把任务拆成可验证步骤，检查实际结果，并把长期规则沉淀到项目中。只要坚持这一流程，工具版本和界面即使变化，核心方法仍然有效。