最近我把日常工作用的编码环境做了一次比较大的调整：在 WSL 里接入了 Codex CLI，又给这个终端里的 AI 编程助手配上了 Superpowers 插件。折腾完整套流程之后，我最大的感受是——AI 编程工具早就不是“补全几个函数”的玩具了，它更像一个带工牌的实习生，能真正在终端里读代码、敲命令、改文件、跑测试。这篇文章把我从零开始安装、配置、实操，以及踩过的一系列坑完整记录下来。如果你也是 Windows 用户，想在 WSL 环境里用上 Codex，又听说 Superpowers 能明显提升效率，那这篇就是给你准备的。

先说结论：Codex 本身的学习曲线不算陡，真正的坑集中在两块——一是 WSL 环境下的工具链细节，二是 Superpowers 这类技能框架的配置思路。这两块如果不提前搞清楚，新手很容易卡在“工具装好了但不会用”的尴尬阶段。下面我会把完整过程拆开来讲，每一步都附上我当时为什么这么做、遇到问题怎么排查。

1. Codex 到底是个什么东西

1.1 终端里的 AI 编程助手，和 IDE 插件的本质区别

很多人第一次听到 Codex，会把它和常见的 IDE 代码补全插件归为一类。实际上这俩的差别非常大。IDE 里的 AI 插件更像“副驾驶”，它的主要动作是帮你在光标位置补全代码、在侧边栏回答局部问题。而 Codex CLI 是一个跑在终端里的编程代理，它有能力读取整个代码仓库、创建和修改文件、执行 shell 命令、运行测试，然后根据执行结果决定下一步做什么。

我用一个表格来对比，这样更直观：

换句话说，Codex 不是给你“提建议”，而是直接上手干活。你给它一个目标，它会自己拆解步骤、读文件、写代码、跑命令验证。做得好不好另说，但它是真的会动手。这种“代理式”的工作方式，往小了说适合搭原型、写测试、解释陌生代码库；往大了说，它可以承担一部分常规开发任务，比如跨文件重命名、批量修 bug、补齐测试用例。

1.2 新手适合用 Codex 做什么，以及不该做什么

我实际用下来，Codex 最擅长的是这几类事情：

• 快速搭建项目骨架：给它一个需求描述，它能生成目录结构、入口文件、配置文件，省掉大量重复劳动。
• 写测试和补测试：让它读代码然后补测试，效果通常不错，尤其是边界条件较多的函数。
• 解读别人的代码：把陌生仓库丢给它，让它先梳理模块结构、调用关系，再解释关键逻辑。
• 批量重构：比如统一命名、拆分大函数、把某类调用改掉，这种机械但量大的活很适合它。
• 写文档和 README：概括代码思路、生成示例用法，这些正好是它比较稳定的输出项。

但它不适合完全放权使用。我见过一些人把整个项目丢给 Codex，然后自己什么都不看，等它出结果。这种用法早晚出问题——它生成的代码可能在逻辑上是通的，但依赖版本是旧的，或者引入了不必要的抽象，或者在某些边界条件下直接崩溃。它毕竟只是个工具，最后把关的还是你自己。

这里有一个很重要的心态：Codex 更像是你的“结对同事”，不是“外包团队”。它干活，但你必须 review。新手最容易踩的坑不是不会用，而是用得太信任。

2. 在 WSL 里把环境先弄干净

2.1 为什么不直接用 Windows 或者 Linux，而是 WSL

我知道有很多人纠结环境选择。我自己用的机器就是 Windows，日常办公离不开 Windows 生态，但开发习惯又更贴近 Linux 命令行。WSL 恰好是这两者之间的桥梁。关于版本的问题，我强烈建议直接用 WSL2，别再用 WSL1 了。WSL1 的兼容性和 IO 性能都有明显短板，很多工具在里面跑起来会出现莫名问题。WSL2 是基于轻量虚拟化的完整 Linux 内核，绝大多数 Linux 软件都能直接跑。

发行版我选的是 Ubuntu 24.04 LTS。这也是社区里最常规的选择，遇到问题最容易搜到答案。安装过程就不啰嗦了，Windows 上执行一句wsl --install -d Ubuntu-24.04就能搞定。装完之后记得先跑一遍系统更新，把基础编译工具链装全：

sudo apt update && sudo apt upgrade -y sudo apt install build-essential python3-dev -y

很多新手装完 WSL 就急着装 Codex，结果在后续安装某些依赖时因为缺少编译工具链而失败。提前把build-essential和python3-dev装上，可以省很多事。

2.2 项目目录千万别放在 /mnt/c 下面

这是我在 WSL 里踩过最典型的坑之一。Windows 的磁盘在 WSL 里会被挂在/mnt/c这种路径下面，很多人一开始图方便，直接把项目放在C:\work\myproject，然后在 WSL 里通过/mnt/c/work/myproject访问。

表面上一切正常，但实际 IO 性能非常差。因为 /mnt/c 是跨文件系统访问，WSL 要把 Linux 的系统调用翻译到 Windows 文件系统上，再加上各种权限模型不一致，跑起测试、安装依赖、启动服务都会肉眼可见地慢。更麻烦的是，两个文件系统的权限和换行符规则也不一样，经常出现“明明代码没问题但执行报错”的怪事。

正确的做法是在 WSL 的 Linux 文件系统内建项目目录，比如~/work/myproject。你自己的代码写在 Linux 侧，如果要用 Windows 侧的工具打开，可以通过\\wsl$\Ubuntu-24.04\home\用户名\work\myproject这样的路径访问。这个操作起来也简单，Windows 的资源管理器地址栏直接输入就行。

2.3 Node 环境与 Codex 安装

Codex CLI 是基于 Node 生态的，所以第一步先把 Node 环境配好。这里我建议用 nvm 来管理 Node 版本，而不是直接apt install nodejs。因为 apt 源里的 Node 版本通常偏旧，Codex 对 Node 版本有明确要求，版本太低直接跑不起来。

# 安装 nvm，具体命令看 nvm 官方文档 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node 20 LTS 并使用 nvm install 20 nvm use 20

装完之后检查一下版本：

node -v npm -v

这里有一个容易忽略的坑：有些人是先在 Windows 侧装了 Node，然后在 WSL 里执行 npm。这样做的结果是 PATH 里混入了 Windows 的 Node 路径，两个人环境互相干扰，经常出现“npm 命令能找到但模块装不上”的诡异情况。我的建议是在 WSL 里单独维护一套 Node 环境，跟 Windows 侧完全独立。

Node 准备好之后，用 npm 全局安装 Codex CLI 即可。具体包名以官方文档为准，不要凭记忆猜版本号。安装完成后测试：

codex --version

如果提示codex: command not found，基本就是 npm 全局 bin 目录不在 PATH 里。用npm config get prefix查看全局安装目录，然后把它的 bin 子目录加到 PATH 里，通常是在~/.bashrc里写一行 export。这一步处理完之后，重新打开终端或者source ~/.bashrc即可。

2.4 首次登录与会话

Codex 安装好之后，第一步是配置访问凭证。官方文档里有很明确的一次性登录流程，照着做就行。如果你用的环境不方便走浏览器登录流程，也可以直接设置环境变量方式。我是用官方一次性登录完成验证的，整个流程大概两三分钟。

配置好凭证之后，可以进到一个空目录里试一下：

mkdir -p ~/work/hello-codex cd ~/work/hello-codex codex

进入交互界面后，随便问一句“帮我看看这个目录里有什么”，它应该能正常响应并列出目录内容。如果这一步通了，说明 Codex 的基本链路没问题。之后所有的问题，基本都出在更上层的使用方式上。

3. Superpowers 插件：给 Codex 装上工程化工作流

3.1 一个致命痛点：Codex 默认的行为太自由

Codex 原生的交互方式，本质上是“你问一句，它答一句”。你让它写代码，它就直接写；你让它解释代码，它就解释。这看起来很灵活，但实际用起来有一个很大的问题：所有开发流程都需要你临时口述。每次都花大量时间描述背景、约束、步骤、完成标准，而且不同会话之间的行为可能不一致——今天它写代码前会先列计划，明天可能上来就动手。

Superpowers 这类技能框架解决的就是这个问题。它把高频的工程实践——写计划、测试驱动开发、代码审查、调试排查、写文档——固化成一整套标准流程。每个流程都对应一个“技能”，通过斜杠命令触发。你在会话里输入/plan，Codex 就会严格按照“先理解需求、再拆解步骤、最后输出实施计划”的流程来执行，而不是自由发挥。

我用一个生活化类比来理解它：Codex 默认状态像一个什么都会一点但没什么主见的实习生，你每次都要把任务交代得清清楚楚；而 Superpowers 相当于给这个实习生发了一本岗位手册和一堆标准作业程序。它看到/plan，就知道该走哪套流程；看到/tdd，就知道“先写失败测试、再写实现、最后重构”这条路线。

3.2 核心概念：技能文件、核心指令、斜杠命令

Superpowers 的核心机制其实不复杂，关键在于理解三个概念：

技能文件是描述一个技能如何执行的文档，通常命名为SKILL.md，放在特定的技能目录下。里面会写清楚这个技能的触发条件、执行步骤、输入输出要求和注意事项。比如写代码技能，会要求先确认需求、再设计接口、然后实现、最后补测试。

核心指令是一个被长期注入到 Codex 上下文里的说明文件，内容大致是“你拥有这些技能，当用户输入的斜杠命令匹配到某个技能时，你必须严格按照该技能的流程执行”。这个核心指令就是框架的入口。

斜杠命令是用户在会话里输入的触发词，比如/plan、/tdd、/review。Codex 看到斜杠命令，会去技能列表里匹配对应的技能文件，然后执行里面的流程。

这套设计最妙的地方是可以自定义。你自己踩过的坑、总结出的最佳实践，都可以写成新的技能文件放进去。比如我发现自己在做数据库迁移时经常漏备份，就可以写一个/db-migration技能，规定先出备份方案、再出回滚方案、然后才动手。

3.3 安装与配置实操

我的安装路径是这样的：先把 Superpowers 框架的代码拉到本地，放在~/superpowers目录下。这个框架的核心是SKILL.md和一堆默认技能文件。

然后，把核心指令挂到 Codex 的上下文里。Codex 支持项目级和用户级的指令文件，项目根目录下的AGENTS.md就是一个很好的挂载点。我在AGENTS.md里写了类似这样的内容：

请先阅读 /home/用户名/superpowers/SKILL.md 中的技能体系。 当用户在会话中使用 /技能名 格式的命令时， 你必须检索并遵循对应技能文件中描述的完整流程来执行任务。

如果你希望所有项目都生效，可以把同样的配置写到用户级的~/.codex/AGENTS.md里。注意，修改完指令文件之后，必须新开一个 Codex 会话才能生效。我一开始以为当前会话能自动重新加载，结果反复试了好几次都没反应，后来才发现要重启会话。

项目级自定义技能放在项目的.superpowers/skills/目录下，每个技能一个子目录，里面放SKILL.md。整体结构大概是这样的：

~/superpowers/ ├── SKILL.md # 核心指令文件 ├── skills/ # 默认技能集合 │ ├── plan/ │ │ └── SKILL.md │ ├── tdd/ │ │ └── SKILL.md │ └── code-review/ │ └── SKILL.md

3.4 常用技能及其使用场景

我自己比较常用的是这几个技能，列个表方便你参考：

刚开始用的时候，我建议先别贪多，挑/plan和/review这两个用熟。一个管“动手前想清楚”，一个管“动完手后查一遍”，这两个技能养成的习惯比单纯让 AI 写得快更有价值。

4. 实操过程：用 Codex 加 Superpowers 从零完成一个小项目

4.1 需求设定

我给自己设置了一个练手项目：用 Python 写一个命令行待办事项管理工具，支持添加任务、列出任务、完成任务、删除任务，数据持久化到本地 JSON 文件，并且要用 pytest 写单元测试。这个需求难度适中，足够展示 Codex 的完整工作流，又不会让过程拖太长。

4.2 用 plan 技能先做规划

进入项目目录后，启动 Codex，然后输入：

/plan 我需要一个Python命令行待办事项管理工具。功能包括：添加任务、列出任务、完成任务、删除任务。数据保存到本地JSON文件。需要pytest单元测试。

Codex 先读取了技能文件，然后给出了一个分步骤计划。它列出的要点大概是：定义任务数据结构、封装存储层（读写 JSON）、实现命令行解析、实现核心业务逻辑、编写针对每个命令的测试、补充 README。整体结构比我预想的还要合理，它甚至注意到了“命令行解析器应该单独成模块，方便测试”这个细节。

这里有一个技巧：计划输出后，我会仔细读一遍，如果发现不符合预期的地方，当场修改，而不是直接放行让它动手。比如我当时补充了一条“任务 ID 从 1 开始自增，删除和完成操作按 ID 进行”，这个补充避免后面生成代码时出现 ID 定义模糊的问题。

4.3 生成代码与测试

计划确认后，我接着输入：

/tdd 按计划开始。先写测试，再实现，确保所有测试通过。

Codex 先创建了test_todo.py，针对数据存储、任务添加、状态变更、删除等场景写了测试用例。然后创建了主模块，实现对应的功能。中间我截取了一段核心实现，大概是这样的结构：

from pathlib import Path import json class TodoStore: def __init__(self, path: str): self.path = Path(path) self.tasks = self._load() def _load(self) -> list: if not self.path.exists(): return [] return json.loads(self.path.read_text(encoding="utf-8")) def save(self) -> None: self.path.write_text( json.dumps(self.tasks, ensure_ascii=False, indent=2), encoding="utf-8", ) def add(self, content: str): task_id = len(self.tasks) + 1 self.tasks.append({"id": task_id, "content": content, "done": False}) self.save()

我注意它用了pathlib和标准库json，没有引入额外依赖，符合这个量级项目的合理做法。随后它主动执行了测试：

pytest -q

一次通过。这个环节让我印象很深刻：它不是写完代码就完了，而是真的会跑命令验证结果。

4.4 人工审查与修正

测试通过并不等于可以交付。我仔细 review 了一遍生成代码，发现一个实际问题：add方法的 ID 生成方式是len(self.tasks) + 1，这在“删除任务后再添加”的场景下会导致 ID 重复。比如先添加了三个任务，删除第二个，再新加任务时 ID 还是 3，就冲突了。

我把这个问题反馈给 Codex：“任务 ID 需要在当前最大 ID 的基础上自增，而不是列表长度加一，因为删除操作会减少列表长度。”它很快修正了逻辑：

def add(self, content: str): task_id = max((t["id"] for t in self.tasks), default=0) + 1 self.tasks.append({"id": task_id, "content": content, "done": False}) self.save()

这个案例恰好说明了前面提到的观点：AI 写的代码一定要人工 review。这种业务语义上的细微差异，靠测试跑通是发现不了的，只有带着业务场景去看代码，才能发现潜在问题。

4.5 收尾与总结

功能全部通过后，我让 Codex 用/document技能生成了 README，包含安装方式、命令列表、使用示例。整个流程下来，从计划到文档完成，大概十几分钟。其中真正值得关注的不是“速度快”，而是整个开发过程被拆成了可审查、可控的阶段：计划先审，测试先写，实现后跑，最后统一 review。这种节奏感，正是 Superpowers 带来的核心价值。

5. 常见问题与排查技巧实录

5.1 WSL 环境专属问题

问题一：项目放在 /mnt/c 下，Codex 操作文件明显卡顿。

这个我前面已经强调过。如果你的项目已经在 /mnt/c 下面，最简单的处理是把它拷贝到 Linux 侧：

cp -r /mnt/c/work/myproject ~/work/myproject

然后把 Codex 的工作目录切到新路径。实测切换后，安装依赖、跑测试的速度会有质的提升，那种“等半天没反应”的折磨感基本消失。

问题二：脚本执行时报bad interpreter: /bin/bash^M错误。

这个报错是 Windows 文件系统的 CRLF 换行符导致的。文件在 Windows 侧编辑过，换行符是\r\n，而 Linux 只认\n。解决办法是用dos2unix转换，或者直接把回车符删掉：

sudo apt install dos2unix -y dos2unix 你的脚本文件.sh # 或者用 sed 临时处理 sed -i 's/\r$//' 你的脚本文件.sh

问题三：codex 命令找不到。

多半是 npm 全局 bin 目录没在 PATH 里。先查 npm 全局目录：

npm config get prefix

然后把输出的路径下的 bin 目录加到 PATH，比如：

export PATH="/home/用户名/.nvm/versions/node/v20.14.0/bin:$PATH"

注意路径里的版本号要和你实际安装的 Node 版本一致。为了保险，把这行写到~/.bashrc末尾，避免每次启动都要手动 export。

问题四：WSL 里设置了环境变量，但 Codex 读不到。

WSL 和 Windows 的环境变量是各自独立的。Windows 系统变量不会自动同步到 WSL 的 bash 会话里，如果你是在 Windows 图形界面里配的环境变量，在 WSL 里是看不到的。处理方式是在~/.bashrc或~/.profile里重新设置一份。

5.2 Codex 和 Superpowers 使用问题

问题一：输入/plan后，Codex 没有按技能流程走，而是当成普通对话。

这是 Superpowers 配置没生效的典型表现。排查思路按顺序来：

• 检查AGENTS.md里的路径是否写对，相对路径最容易出错，尽量用绝对路径。
• 确认修改的是当前项目下的AGENTS.md，或者用户级的~/.codex/AGENTS.md。
• 新开一个会话再试。指令文件只在会话启动时加载，中途改配置不生效。
• 在会话里直接问它“你现在有哪些可用技能”，如果它一个都说不出来，说明核心指令没被读到。

问题二：上下文窗口很快用完，任务执行到一半就断。

Codex 需要在上下文里装载仓库信息，如果项目很大、文件很多，很快会撞到窗口上限。我的处理方法是把无关目录排除掉，让 Codex 只关注核心路径。一是靠.gitignore缩小辅助工具扫描范围，二是把任务拆小，一次只解决一个模块，避免让它同时掌握所有代码。每次会话前我也会明确告诉它“只需要关注 src 目录，其他目录不要读”。

问题三：模型选择影响很大。

同一个任务，用快的模型和用强的模型，产出质量差别明显。简单任务比如补注释、写测试框架，我用小模型就够；复杂任务比如理解遗留代码、跨模块重构，我会切到更强的模型。这里没有绝对最优解，建议新手先把默认配置跑通，再根据实际任务类型切换。切换方式看 Codex 官方配置说明，一般是在启动时指定模型名或者在交互界面里切换。

5.3 避坑技巧速查表

6. 一点个人的使用心得

整套流程跑下来，我最大的体会是：决定 Codex 产出质量的，不只是模型本身的能力，更是你描述需求的能力。同样一个任务，有人输入“帮我写个工具”，有人输入“我要一个 Python CLI 待办工具，支持增删改查，数据存 JSON，用 pytest 测覆盖核心逻辑”，产出的差距是巨大的。Codex 不是读心术工具，它只是一个执行力很强的实习生，你给它的指令越清晰，它的表现越接近你想要的结果。

Superpowers 这个框架对我来说，作用不只是提升了 Codex 的产出质量，更是强迫我把工作流本身想清楚了。以前我开发时经常跳过测试、跳过 review，觉得自己心里有数。但当我给 Codex 配置了/tdd技能，看着它老老实实先写测试、再写实现、最后重构，我会反思：我自己写代码的时候，为什么不也用同样的流程？这种“用工具约束自己”的效果，是我最初没有预料到的。

最后分享一个完全来自实操的小技巧：如果你刚开始用 Codex 跑项目，别急着让它一口气完成所有功能，先从“让它读代码、解释代码”开始。把陌生仓库丢给它，让它梳理结构、标注关键文件、写下它对代码逻辑的理解。这个过程既不会产生破坏性改动，又能快速验证你的配置是否正常、模型对仓库的理解是否准确。等这一步稳定了，再让它动手改代码，你会发现自己对它的信任边界有了更清晰的认识。