Codex 与 OpenSpec 快速安装使用

面向第一次接触 AI Coding 的同学：从环境准备，到完成一次可检查、可追踪的代码修改。

前言：为什么 AI 会“听不懂”你的需求

你可能已经在抖音、B 站、小红书或各种技术社区里刷到过很多 AI 内容：几句话生成网页、自动修复 Bug、编写脚本，甚至一个人完成过去一个团队的工作。

但真正开始使用 AI Coding 后，你可能马上遇到这些问题：第一句话不知道怎么说；不知道需求要写多细；不确定应该先规划还是直接写代码；明明觉得自己说清楚了，AI 却朝错误方向写了一大段。代码没有完成，Token、时间和耐心却消耗了不少。

📷 [图片 token=EIIPbysDpo3xT6xtHZMcCXmkn9b（未能下载，见飞书原文）]

这通常不只是模型能力的问题。无论你使用订阅工具、API 服务，还是豆包、千问、Kimi、ChatGPT 等产品，只要目标、背景、限制和验收标准不清楚，AI 就很难稳定地交付你真正需要的结果。

因此，学习 AI Coding 不能只学“怎样让 AI 写代码”，还要学会：

• 怎样把一个模糊想法变成清楚的需求；

• 怎样让 AI 先理解项目，再开始修改；

• 怎样用任务和测试检查结果；

• 怎样把需求、设计和实现记录在仓库里，方便以后继续。

本文用三个工具组成一套容易理解的学习流程：Codex 负责在项目中工作，OpenSpec 负责记录和管理变更，Superpowers 可选地提供头脑风暴、TDD 和调试等工程方法。

📷 [图片 token=JqpRbCaRrohk6VxojVQcJ2YRnUg（未能下载，见飞书原文）]

1. 先认识三个工具

1.1 Codex：真正执行开发任务的 AI 编码 Agent

Codex 是 OpenAI 的编码 Agent。打开一个项目后，你可以用自然语言让它阅读代码、解释实现、修改文件、运行命令、执行测试和检查结果。它不只是聊天窗口，而是能够围绕代码仓库完成任务的协作工具。

例如，不要只说：

帮我加一个深色模式。

可以改成：

请先阅读这个 Vue 项目的主题和布局实现，为设置页增加深色模式。刷新后要保留用户选择，不改动登录流程，并补充相关组件测试。先说明影响范围，再开始修改。

后一句提供了项目背景、目标、限制和验收要求，AI 更不容易跑偏。

📷 [图片 token=K4dyb96wWobxg5xYtN2cxct4ndf（未能下载，见飞书原文）]

Codex 的界面、基本操作和完整演示可以参考：Codex 使用教程（B 站）。安装和账号要求可能随版本变化，请同时以 Codex 应用内提示和 OpenAI 官方文档为准。

如果要开通ChatGPT Plus，可以参考这个文章：2026年最新ChatGPT充值教程，支持国内支付宝和微信充值 GPT 5.6、Plus、Pro、Codex等

如果你希望了解 Codex 接入国产模型的思路，可以参考：Codex 接入国产模型（B 站）。需要注意，第三方或 OpenAI-compatible 模型并不一定完整支持 Codex 所需的工具调用、结构化输出和长任务能力；API Key 也不要写进 Git 仓库、截图或聊天记录。

1.2 OpenSpec：把需求变成仓库里的开发说明书

OpenSpec 可以理解为 AI Coding 中的“规范驱动开发层”。它不会代替 Codex 写代码，而是帮助 Codex 和开发者先把一次变更整理清楚。

一个常见的 OpenSpec change 会包含：

• proposal.md：为什么要做、准备改变什么；

• design.md：准备怎样实现、有哪些技术取舍；

• tasks.md：可以逐项完成和勾选的任务；

• specs/.../spec.md：新增或修改的行为以及验收场景。

这样，“做什么、为什么做、怎样做、怎样才算完成”就不只存在于聊天记录里，而会成为仓库的一部分。以后换一个会话，或者由同学继续开发，也能根据这些文件恢复上下文。

在本仓库中，已经生效的规范位于 openspec/specs/，正在进行的变更位于 openspec/changes/<change-name>/，完成的历史变更位于 openspec/changes/archive/。归档目录只用于追溯，不应继续在里面开发。

📷 [图片 token=SkH3bzLLboTijexonExctSaXngg（未能下载，见飞书原文）]

1.3 Superpowers：可选的工程方法工具箱

Superpowers 可以理解为一套给 AI Agent 使用的工程技能和工作流。它常见的思路包括：先通过 brainstorming 澄清问题，再设计方案；用 test-driven-development 按“红—绿—重构”推进；遇到失败时进行 systematic-debugging；交付前执行 verification-before-completion。

它解决的是“AI 应该怎样做事”，OpenSpec 解决的是“需求和变更怎样沉淀”。二者并不冲突：OpenSpec 像项目说明书，Superpowers 像工程纪律。

📷 [图片 token=FvsebJh4LoWIyHx6HUXcxaY9nMG（未能下载，见飞书原文）]

Superpowers 是可选项，而且插件名称、安装入口和可用 Skill 会随 Codex 版本、平台或组织策略不同。没有安装它也能完成本文练习：直接要求 Codex“先澄清、按 TDD 实现、完成前验证”即可。

2. 环境准备清单

开始前请准备：

• 一台 Windows、macOS 或 Linux 电脑；

• Git，用来获取项目和查看代码变化；

• Node.js 与 npm，用来安装 OpenSpec；

• Codex 应用或 Codex CLI（如果要开通ChatGPT Plus，可以参考这个文章：2026年最新ChatGPT充值教程，支持国内支付宝和微信充值 GPT 5.6、Plus、Pro、Codex等）

• 一个可以练习的 Git 项目，建议先使用测试项目，不要直接修改重要作业或生产代码。

每安装一个工具都要马上检查版本。这样出现问题时，你能判断究竟是“没有安装”，还是“已经安装但配置不正确”。

📷 [图片 token=C6D8bLdcloImAwxaEqqcWFQcnye（未能下载，见飞书原文）]

3. 安装 Codex

1. 从 OpenAI 官方渠道下载适合自己系统的 Codex，或按照官方文档安装 Codex CLI。

2. 如果想要开通 chatgpt plus 套餐的，教程看这个：2026年最新ChatGPT充值教程，支持国内支付宝和微信充值 GPT 5.6、Plus、Pro、Codex等

3. 完成登录或所需的 API 配置。

4. 在 Codex 中打开你的项目文件夹。

5. 先提出一个只读问题，例如：“请阅读这个仓库的 README，告诉我如何启动项目，暂时不要修改文件。”

如果无法登录或加载模型，请依次检查网络是否能访问所使用的官方服务、账号是否有相应权限、系统时间是否正确，以及学校或公司的网络策略是否拦截连接。不要使用来源不明的安装包、代理脚本或共享 API Key。

📷 [图片 token=IgoRb7qfKoaY0lx30RzcJjFBnqo（未能下载，见飞书原文）]

4. 安装 OpenSpec

4.1 安装 Node.js

前往 Node.js 官网 安装仍在维护的 LTS 版本。安装完成后，重新打开终端并运行：

node --version
npm --version

两条命令都能输出版本号，才能继续。

📷 [图片 token=JcS1bCcP0oars7xGMbYc9WEAnkc（未能下载，见飞书原文）]

4.2 全局安装 OpenSpec

在 macOS、Linux 或普通命令行中运行：

npm install -g @fission-ai/openspec@latest

在 Windows PowerShell 中，如果 npm 被执行策略拦截，可以运行：

npm.cmd install -g @fission-ai/openspec@latest

然后验证：

openspec --version
openspec --help

📷 [图片 token=WRlSbw4aXo0sKJx5ewucpqtKnch（未能下载，见飞书原文）]

如果系统提示找不到 openspec，先关闭并重新打开终端，再检查 npm 的全局可执行目录是否已经加入 PATH。不要反复执行不同来源的安装脚本，否则会让环境更难排查。

4.3 在项目中初始化

进入你的项目根目录，先查看当前版本支持的命令：

openspec --help

对于还没有 openspec/ 的项目，按照当前版本帮助执行初始化命令（常见命令为 openspec init）。初始化后，确认仓库中出现 OpenSpec 目录和相关配置，再让 Codex读取其中的说明。

本仓库已经完成初始化，不要重复初始化。你应该能看到：

openspec/
├── specs/                # 已生效的主规格
└── changes/
    ├── <change-name>/    # 正在进行的变更
    └── archive/          # 已完成的历史变更

📷 [图片 token=IMQRbJm90ooTPgxQDricYhXbnKf（未能下载，见飞书原文）]

5. 可选：安装 Superpowers

如果你使用的 Codex 版本提供插件市场，可以打开“设置 → 插件”，搜索 Superpowers，阅读插件来源、权限和说明后再安装。安装完成后重新打开任务，并让 Codex列出当前可用的相关 Skill，确认是否真的包含 brainstorming、TDD、debugging 和 verification 等能力。

📷 [图片 token=Rbncb9qT7oOIVbxku5icGHDhnse（未能下载，见飞书原文）]

如果搜索不到，说明当前平台、账号或插件源没有提供该插件。此时不需要卡在安装步骤，可以直接使用这样的提示词：

先通过提问澄清需求，再给出实现方案；实现时先补失败测试，再写最小代码让测试通过；完成前运行相关测试并检查 Git diff。

📷 [图片 token=UIzjbB3b3oB2PqxniFwcyWrtnVd（未能下载，见飞书原文）]

6. OpenSpec 的完整使用流程

下面以“增加深色模式”为例。变更名称使用小写英文和连字符：add-dark-mode。

📷 [图片 token=YzYYbf3kwoLm8SxseLncTbAYngd（未能下载，见飞书原文）]

第一步：需求不清楚时，先讨论

你可以对 Codex 说：

先用 brainstorming 的方式帮我梳理深色模式需求。请确认适用页面、颜色来源、是否跟随系统、是否保存用户选择，以及验收标准。先不要写代码。

即使没有 Superpowers，Codex 也可以按这段自然语言完成澄清。

📷 [图片 token=AhiMbhJepoygGMxYMvqcnrxdngc（未能下载，见飞书原文）]

第二步：创建 OpenSpec 变更

在本仓库中，直接说：

使用 openspec-propose 创建 add-dark-mode 变更。先阅读现有主规格、实现和测试，生成 proposal、design、tasks 和需要的 delta specs，内容使用简体中文。

如果你的安装环境提供 OpenSpec 斜杠命令，也可以使用：

/opsx:propose add-dark-mode

生成后不要急着实现。先阅读 proposal.md、design.md 和 tasks.md，重点检查功能边界、风险与验收步骤。规划错了，后面的代码通常也会错。

📷 [图片 token=Wuu8bsY9noNdNYxtydhcSBW4nsd（未能下载，见飞书原文）]

第三步：按任务实现

确认方案后，对 Codex 说：

使用 openspec-apply-change 实现 add-dark-mode，按 tasks.md 顺序完成。遵守仓库 AGENTS.md，先写或更新测试，再修改实现；每完成一项就勾选任务。

有斜杠命令的环境也可以使用：

/opsx:apply add-dark-mode

如果实现过程中出现 Bug，可以说：

使用 systematic-debugging 的方式排查这个失败：先复现并收集证据，说明根因，再提出最小修复。不要先猜答案。

📷 [图片 token=BprEbINySoyjyqxvaaNcARcyn6g（未能下载，见飞书原文）]

第四步：验证实现

在本仓库中，可以要求：

使用 openspec-verify-change 验证 add-dark-mode。对照 proposal、design、tasks、delta specs 和实际实现，运行与改动范围匹配的测试，并列出没有执行的检查及原因。

还应运行 OpenSpec 校验：

openspec validate --all

修改前端时，至少从相关测试开始；如果改动涉及 API 或 SSE，还要同步检查共享契约、后端和前端。不要用“测试应该能过”代替真实的命令结果。

📷 [图片 token=R7nsbkqcRoQ5mwx0ABDcYacCnwf（未能下载，见飞书原文）]

第五步：归档变更

只有在任务完成、验证通过，并将 delta specs 同步到主规格后，才归档：

使用 openspec-archive-change 归档 add-dark-mode，并按仓库规则同步 WIKI、索引和侧栏，最后验证文档构建。

支持斜杠命令时，也可以使用：

/opsx:archive add-dark-mode

本仓库规定：创建或归档 change 后，还要使用 wiki-sync Skill 同步 docs/changes/，并运行 npm run docs:build。这一步是本仓库特有的交付要求，不是所有 OpenSpec 项目都一样。

📷 [图片 token=Ustpb7Fc8oZ8WsxlULucNzx3nUg（未能下载，见飞书原文）]

7. 一段可以直接使用的完整提示词

把项目文件夹在 Codex 中打开，然后发送：

请使用 OpenSpec 流程处理下面的需求。

1. 先阅读 AGENTS.md、openspec/specs/、相关实现和测试。
2. 先通过提问澄清目标、边界和验收标准，不要立刻写代码。
3. 使用 openspec-propose 创建一个聚焦的 change。
4. 等我确认方案后，再使用 openspec-apply-change 实现。
5. 实现时先补测试，再写最小代码，并逐项更新 tasks.md。
6. 完成后使用 openspec-verify-change 验证，报告实际运行的命令和结果。
7. 验证通过后提醒我归档；未经确认不要提前归档。

需求：为前端设置页增加深色模式。用户选择需要保留，刷新页面后仍然生效，不影响登录和聊天功能。

这比只写“做一个深色模式”多花一分钟，却能明显减少误解、返工和无效 Token 消耗。

📷 [图片 token=VWG1bl2jQoI2f6xPKnKc6LN0n7g（未能下载，见飞书原文）]

8. 在本仓库中练习启动与验证

Agent Py 是一个已经有完整实现的本地优先 AIOps 工作台，不是空白脚手架。开始任何练习前，先执行：

git status --short

如果看到已有修改，不要删除、覆盖或顺手格式化这些文件。阅读根目录 AGENTS.md，再查看与你的需求相关的 openspec/specs/、实现和测试。

📷 [图片 token=BsfubaxrDoVpanxAy2YcMqqKnAc（未能下载，见飞书原文）]

安装项目依赖后，macOS/Linux 的正式本机启动入口是：

./scripts/start-local.sh

Windows 使用：

scripts\start-local.bat

启动器会安装依赖、执行数据库迁移并启动有状态服务，因此不要把它当成无副作用的检查命令。只想验证文档时，应运行：

npm run docs:build

仓库的完整检查还包括前端、共享契约、后端和 OpenSpec 校验，应根据实际改动范围选择，不能为了“看起来通过”而跳过类型检查、删除测试或弱化断言。

📷 [图片 token=XDm2bVlezou3HTxZOnbcMsWhnpc（未能下载，见飞书原文）]

9. 常见问题

Codex 需要开通 chatgpt 会员吗？

codex有免费的额度，但是要开发项目的话，还是得开通chatgpt会员才行，如果你还没有开通，可以看这个教程开通：2026年最新ChatGPT充值教程，支持国内支付宝和微信充值 GPT 5.6、Plus、Pro、Codex等

Codex 一上来就开始改代码怎么办？

明确说“先阅读和说明影响范围，暂时不要修改文件”。需要较大改动时，先完成 OpenSpec proposal，再批准实现。

OpenSpec 安装成功，但 /opsx:propose 不可用怎么办？

CLI 与 Codex Skill/斜杠命令是不同层。先确认 openspec --version 可用，再检查项目是否安装了 OpenSpec Skills。没有斜杠命令时，直接说“使用 openspec-propose Skill 创建变更”即可。

一定要安装 Superpowers 吗？

不需要。它能帮助规范流程，但真正重要的是把澄清、规划、测试、调试和验证这些动作落实。自然语言也能明确要求 Codex 这样工作。

怎样减少 Token 浪费？

一次说明目标、背景、限制、验收标准和允许修改的范围；让 Codex 先读取仓库事实；把长期约束写入 AGENTS.md，把一次变更写入 OpenSpec；发现方向错误时立即停止并回到方案，不要在错误实现上连续打补丁。

📷 [图片 token=LEQzbK5g6oDqp4x0WLRcemKQnLd（未能下载，见飞书原文）]

结语

OpenSpec 和 Superpowers 的目的都不是让 AI 看起来更“炫”，而是让 AI Coding 更清晰、更稳定、更可控。

OpenSpec 解决“需求如何沉淀”：它把聊天里的想法整理成提案、设计、任务、规格和验收标准。Superpowers 解决“AI 如何执行”：先理解、再规划、再测试和实现，最后验证。Codex 则把这些信息真正落实到代码、命令和检查结果中。

一个负责执行，一个负责记录，一个可选地约束工程方法。把三者正确组合起来，AI 才不只是会生成代码的工具，而会成为一个能够参与工程协作的开发伙伴。

📷 [图片 token=HUaab7K5qousK7xxGbLcbtEWn8c（未能下载，见飞书原文）]