Codex CLI教程（四） | Superpowers安装指南（Windows）

Slow菜鸟2026-04-15 7:05

Codex CLI教程（四） | Superpowers安装指南（Windows）

一、前言

Codex CLI 是 OpenAI 推出的 AI 编程助手，可在终端中直接与 AI 对话，辅助代码编写、调试和解释。Superpowers 则是为 Codex 提供增强功能的技能集合，通过添加专业技能模块提升 Codex 的能力范围。

本文将详细介绍在 Windows 环境下为 Codex CLI 安装 Superpowers 的完整流程，按推荐度排序，确保步骤清晰专业。

二、准备工作

安装 Node.js
推荐度：★★★★★

  • 下载 ：访问 Node.js 官网 下载 LTS 版本（推荐 v18+ 或 v20+）

  • 安装 ：运行安装程序，务必勾选 "Add to PATH" 选项（自动配置环境变量）

  • 验证 ：

    powershell 复制代码 
    node -v  # 验证 Node.js 安装
npm -v   # 验证 npm 包管理器

三、安装方法（按推荐度排序）

方法一：官方 GitHub 安装法

推荐度：★★★★★
特点：官方推荐，稳定可靠，适合所有用户

步骤 1：安装 Codex CLI

powershell 复制代码 
npm install -g @openai/codex --registry=https://registry.npmmirror.com
  • 命令解析 ：
    • npm install -g：全局安装包，确保 codex 命令在任何位置可用
    • @openai/codex：OpenAI 官方 Codex CLI 包
    • --registry：使用国内镜像源，加速下载
powershell 复制代码 
codex --version  # 验证安装成功

步骤 2：安装 Superpowers

为什么需要创建技能目录并建立关联？

这是由 Codex CLI 的技能发现机制决定的：

  • Codex 启动时会自动扫描 ~/.agents/skills/ 目录（Windows 下为 %USERPROFILE%\.agents\skills\）
  • Superpowers 的技能文件存储在其仓库的 skills 目录中
  • 使用 junction（目录链接）可以保持技能与原始仓库的关联，便于后续更新

  1. 克隆 Superpowers 仓库：

    powershell 复制代码 
    git clone https://github.com/obra/superpowers.git "$env:USERPROFILE\.codex\superpowers"
    • 命令解析 ：
      • git clone：从 GitHub 克隆仓库到本地
      • https://github.com/obra/superpowers.git：Superpowers 项目官方地址
      • "$env:USERPROFILE\.codex\superpowers"：克隆目标路径
      • $env:USERPROFILE：PowerShell 环境变量，指向用户主目录

  2. 创建技能目录并建立 junction：

    powershell 复制代码 
    New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.agents\skills"
    • 命令解析 ：
      • New-Item：创建新目录
      • -ItemType Directory：指定创建类型为目录
      • -Force：强制创建，若目录已存在则不报错
      • -Path：指定目录路径
    powershell 复制代码 
    cmd /c mklink /J "$env:USERPROFILE\.agents\skills\superpowers" "$env:USERPROFILE\.codex\superpowers\skills"
    • 命令解析 ：
      • cmd /c：在 PowerShell 中执行 cmd 命令
      • mklink /J：创建目录 junction（Windows 目录链接，类似符号链接）
      • 第一个路径：链接目标位置（Codex 技能扫描目录）
      • 第二个路径：源目录（Superpowers 技能目录）

  3. 重启 Codex CLI：关闭并重新启动 Codex，使其发现新技能

方法二：通过 Codex 自动安装

推荐度：★★★★☆
特点：操作简单，适合新手用户

  1. 启动 Codex CLI：

    powershell 复制代码 
    codex

  2. 输入安装指令：

    复制代码 
    Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
    • 功能说明：让 Codex 自动获取并执行官方安装脚本

方法三：使用第三方镜像安装

推荐度：★★★☆☆
特点：适合网络环境较差的用户

  1. 安装 Node.js（步骤同前）

  2. 使用 88code 镜像安装 Codex：

    powershell 复制代码 
    npm i -g @88code/codex --registry=https://registry.npmmirror.com
    • 命令解析 ：
      • npm i -g：全局安装
      • @88code/codex：88code 定制版 Codex
      • --registry：使用国内镜像源

  3. 按照方法一的步骤安装 Superpowers

四、配置与优化

配置文件位置

  • Windows ：%USERPROFILE%\.codex\
  • Linux/macOS ：~/.codex/

启用高级功能

在 config.toml 文件中添加以下配置以启用多代理功能：

toml 复制代码 
[features]
multi_agent = true
  • 功能说明：启用 Codex 的多代理功能，支持 Superpowers 中的子代理技能

五、验证安装

步骤 1：检查 junction 创建状态

powershell 复制代码 
ls "$env:USERPROFILE\.agents\skills"
  • 功能说明：列出技能目录内容，确认 superpowers 链接已正确创建
  • 预期结果 ：应显示 superpowers 目录链接

步骤 2：在 Codex 中验证安装

重启 Codex ：

关闭并重新启动 Codex CLI，使其发现新技能。

官方验证方法：

  1. 检查 junction 创建状态：

    powershell 复制代码 
    ls "$env:USERPROFILE\.agents\skills\superpowers"
    • 功能说明：检查 Superpowers 技能链接是否正确创建
    • 预期结果 ：应显示 junction 链接指向 $env:USERPROFILE\.codex\superpowers\skills

  2. 在 Codex CLI 中验证 ：

    启动 Codex 并输入以下任一命令：

    复制代码 
    Help me plan this feature

    或

    复制代码 
    Let's debug this issue
    • 功能说明：测试 Superpowers 技能是否自动触发
    • 预期结果：Codex 应启动相应技能，开始提问澄清需求或系统性排查

  3. 直接询问技能：

    复制代码 
    do you have brainstorming?
    • 功能说明：直接询问 Codex 是否具备 Superpowers 技能
    • 预期结果：Codex 应确认拥有 brainstorming 等 Superpowers 技能

  4. 测试具体技能：

    复制代码 
    use brainstorming to generate ideas for a new project
    • 功能说明：直接使用 Superpowers 的头脑风暴技能
    • 预期结果：Codex 应启动头脑风暴技能，开始询问项目相关问题

六、维护与管理

更新 Superpowers

powershell 复制代码 
cd "$env:USERPROFILE\.codex\superpowers" && git pull
  • 命令解析 ：
    • cd：切换到 Superpowers 目录
    • git pull：从 GitHub 拉取最新代码
  • 优势：由于使用了 junction 链接，更新后技能会自动同步

卸载 Superpowers

powershell 复制代码 
Remove-Item "$env:USERPROFILE\.agents\skills\superpowers"
# 可选：删除克隆的仓库
Remove-Item -Recurse -Force "$env:USERPROFILE\.codex\superpowers"

七、常见问题与解决方案

1. 权限错误

  • 症状：安装时提示 "权限不足" 或 "access denied"
  • 解决方案：以管理员身份运行 PowerShell

2. 命令未找到

  • 症状 ：运行 codex 时提示 "不是内部或外部命令"
  • 解决方案 ：
    1. 检查 npm 全局安装路径：npm config get prefix
    2. 确保该路径已添加到系统 PATH 环境变量
    3. 重新安装 Node.js 并确保勾选 "Add to PATH"

3. 技能不显示

  • 症状：Codex 无法发现 Superpowers 技能
  • 解决方案 ：
    1. 检查 junction 是否正确创建
    2. 重启 Codex CLI
    3. 确认 ~/.agents/skills/superpowers 目录存在

八、技术原理

1. Superpowers 功能架构

Superpowers 是一个模块化技能系统，为 Codex CLI 提供扩展功能，包括：

  • 头脑风暴（brainstorming）
  • 代码审查（code-review）
  • 测试生成（test-generation）
  • 子代理驱动开发（subagent-driven-development）

2. 技能发现机制

Codex 启动时会扫描 ~/.agents/skills/ 目录，自动发现并加载技能。每个技能通过 SKILL.md 文件定义，包含：

  • 技能名称和描述
  • 触发条件
  • 使用方法和示例

3. Windows 链接技术

在 Windows 环境下，使用 mklink /J 创建目录 junction（目录链接），实现类似 Linux 符号链接的功能，使 Codex 能够通过标准路径访问 Superpowers 技能文件。

4. 安装方法的官方来源

此安装方法来自 Superpowers 项目的官方文档（.codex/INSTALL.md），由项目维护者 obra 制定，是官方推荐的标准安装方式。

九、Superpowers 技能列表与使用方法

核心技能列表

Superpowers 提供了丰富的技能，帮助开发者遵循最佳实践：

技能名称 功能描述 触发场景
brainstorming 交互式设计优化，帮助澄清需求 开发新功能、设计系统
writing-plans 创建详细的实施计划，拆解任务 复杂功能开发、重构
test-driven-development 测试驱动开发，先写测试再实现 代码实现、功能开发
requesting-code-review 代码审查，分析质量和潜在问题 代码完成后、PR 前
systematic-debugging 系统性调试，排查问题根因 修复 bug、性能优化
using-git-worktrees 利用 Git worktrees 创建隔离开发环境 多分支并行开发
finishing-a-development-branch 完成分支开发，运行测试并准备合并 功能开发完成后

技能使用方法

1. 自动触发（推荐）

Superpowers 设计为自动触发模式，AI 会根据上下文自动调用合适的技能：

场景 预期触发技能 示例输入
新功能开发 brainstorming "我想给博客添加评论功能"
问题排查 systematic-debugging "登录接口有时返回 500 错误"
代码实现 writing-plans + test-driven-development "帮我实现用户认证系统"
代码审查 requesting-code-review "帮我审查这段代码"

2. 手动触发

你也可以通过 use 命令手动触发特定技能：

复制代码 
use brainstorming to generate ideas for a new project

use test-driven-development to implement a user authentication system

3. 技能工作流程

Superpowers 技能通常遵循以下工作流程：

  1. 澄清需求：技能会询问关键问题，确保理解需求
  2. 生成方案：基于需求生成详细的设计或计划
  3. 执行实施：按照方案执行，如编写测试、实现代码
  4. 质量检查：进行代码审查、测试验证
  5. 完成交付：总结工作成果，提供最终方案

实际使用示例

示例 1：开发新功能

复制代码 
我想给电商网站添加购物车功能
  • 预期流程 ：
    1. brainstorming 技能自动触发，询问功能细节
    2. 生成设计方案后，writing-plans 技能生成实施计划
    3. test-driven-development 技能按 TDD 方式实现
    4. requesting-code-review 技能进行代码审查

示例 2：修复 bug

复制代码 
用户登录后无法访问个人中心，总是跳转到首页
  • 预期流程 ：
    1. systematic-debugging 技能自动触发
    2. 分析问题根因，提出解决方案
    3. test-driven-development 技能修复并验证

使用最佳实践

  1. 主动沟通：与技能保持互动，及时回答问题
  2. 明确需求：尽可能详细描述需求，减少误解
  3. 遵循流程：信任技能的工作流程，不要跳过步骤
  4. 定期更新：定期更新 Superpowers 以获得最新功能
  5. 反馈问题：遇到问题时，通过 GitHub 提交 issue

十、使用建议

推荐使用场景

  • 新手用户：通过方法二（Codex 自动安装）快速上手
  • 专业用户：使用方法一（官方 GitHub 安装）获得完整控制
  • 网络受限用户：使用方法三（第三方镜像）解决网络问题

注意事项

  1. 技能发现：确保 junction 链接正确创建，Codex 才能发现技能
  2. 重启必要：安装后需要重启 Codex 才能加载技能
  3. 自然语言：使用自然语言描述需求，Superpowers 会自动识别并调用合适技能
  4. 循序渐进：技能会分步骤执行，耐心跟随工作流程
  5. 质量保证：Superpowers 会强制遵循最佳实践，确保代码质量

十一、总结

通过本文介绍的方法，你可以在 Windows 环境下成功为 Codex CLI 安装 Superpowers，获得更强大的 AI 编程助手能力。官方 GitHub 安装法是最推荐的方式，提供最稳定可靠的体验。

Superpowers 扩展了 Codex 的能力边界，使其不仅是代码生成工具，更是一个完整的开发助手生态系统。合理使用这些技能，将显著提升你的编程效率和代码质量。

参考资源

更新时间：2026 年 4 月 14 日

注意：本文基于最新官方文档编写，确保方法的有效性和可靠性。若后续版本更新，可能需要相应调整安装步骤。

相关推荐
智慧地球（AI·Earth）4 个月前
GPT Codex CLI报错：The encrypted content gAAA...lA== could not be verified.
gpt·codex cli·400 error
叶庭云6 个月前
一文掌握 CodeX CLI 安装以及使用！
人工智能·openai·安装·使用教程·codex cli·编码智能体·vibe coding 终端
YoungHong19927 个月前
【图文】Codex接入Kimi K2/GLM-4.5 环境配置指南 (Windows/macOS/Ubuntu)
windows·ubuntu·macos·codex·kimi-k2·glm-4.5·codex cli
热门推荐
012026年4月技术前沿：AI大模型爆发、智能体革命与量子安全新纪元02GitHub 镜像站点03一周AI热点速览（2026.03.31-04.06）：GPT-6曝光、谷歌开源Gemma 4、资本狂飙与模型军备竞赛04GPT-6核心能力解析及与现有主流大模型对比05基于 Docker 部署 Hermes Agent 并接入飞书机器人的完整指南06零成本！Ollama本地部署国产大模型全指南（支持Kimi-K2.5/GLM-5/Qwen，新手秒上手）07AI Weekly | 2026年4月第二周 · GitHub热门项目与AI发展趋势深度解析08免费！不限量！用opencode接入英伟达（NVIDIA）大模型，轻松打造你的 AI 编程助手09CodeBuddy与WorkBuddy深度对比：腾讯两款AI工具差异及实操指南10从限购到畅通：GLM-5.1 Coding Plan接入攻略