企业官网建设流程全解析

先说背景吧。我自己的主力开发机是一台 Windows 笔记本，平时大部分项目跑在 WSL2 的 Ubuntu 里。最近因为要在终端里找一个能真正干活的 AI 编程助手，就把 Codex CLI 装上了，后来又给 Codex 配了 Superpowers 插件，折腾了一整天。标题里这三个词各管一摊：Codex 是核心工具，Superpowers 是给这个工具补“工作方法论”的插件，WSL 则是 Windows 用户绕不开的 Linux 兼容层。这一套组合搞明白之后，感觉像是给终端里塞进了一个能按流程办事的初级工程师。

这篇文章写给谁？两类人。一类是跟我一样用 Windows 当主力、想尝试 Codex CLI 但不知道从哪下手的开发者；另一类是已经在 macOS 或 Linux 上把 Codex 跑起来了，想给它的工作流再上个台阶、顺便看看 WSL 环境可能踩到哪些坑的人。我会把安装、登录、插件配置、路径问题和性能问题串起来写，重点放在“我当时是怎么踩进去的”和“后来是怎么爬出来的”。

1. 先把 Codex CLI 装明白：环境准备与首次运行

1.1 Codex CLI 是什么，以及它解决的真正问题

Codex CLI 是 OpenAI 出的终端型 AI 编程助手（agentic coding tool）。它和聊天窗口里的 AI 最大的区别是：它活在你的项目目录里。你启动它之后，它能感知当前目录的文件结构、git 状态、已经跑过的命令输出，然后根据你的任务描述，自己去改代码、执行命令、跑测试、看报错、再修。整个过程是“它在干活”，而不是“它在教你干活”。

举个例子，你让它“把这个模块从 CommonJS 改成 ESM，并把所有 import 路径修正一遍”，它不会只给你一段改好的样例代码，而是会真的打开每个文件做修改，再跑一遍测试确认没问题。如果中途报错了，它会把报错贴出来，然后自己分析下一步怎么处理。这种体验跟 Copilot 的自动补全不是一回事，补全解决的是“这一行怎么写”，Codex 解决的是“这个任务怎么做完”。

为什么选它？我在试用阶段对比过几个同类工具。Codex 给我的感觉是，它对任务的长程规划能力更强，上下文一大也不会跑偏；而且终端里的 slash 命令体系让“先计划、再执行”这件事变得可控制。举个最直接的场景：让它重构一个不熟悉的模块，我可以在计划阶段就喊停，而不是等它把代码改得面目全非再后悔。后来配上 Superpowers，这个“先规划再动手”的路径又被强化了一个量级。

1.2 前置环境：Node 版本、WSL2 与终端选择

Codex CLI 官方支持在 macOS、Linux 和 WSL 上运行，所以 Windows 用户不需要装什么虚拟机，直接把 WSL2 配好就行。我整理一下我自己安装顺序，每一步背后的原因也写出来：

1. 启用 WSL2。WSL2 是完整 Linux 内核，对文件监听、Node 原生模块编译的支持都比 WSL1 好太多。命令就两条：

wsl --install -d Ubuntu-22.04 wsl --set-default-version 2

2. 进到 WSL 的 Ubuntu 后，装基础包。这一步很多人会跳过，但后面装 npm 依赖一旦缺编译器会非常痛苦：

sudo apt update && sudo apt upgrade -y sudo apt install -y curl git build-essential

3. 安装 Node.js 20+。Codex CLI 是 npm 包，装它至少需要 Node 18。我建议直接用 NodeSource 仓库装 Node 20，别用 Ubuntu 自带的 apt 源——Ubuntu 默认仓库里的 Node 版本太保守，装完之后大概率卡在低版本上，后面跑 npm install 会报各种引擎不兼容的错。

curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs node -v npm -v

4. 终端选择。Windows 自带的 conhost 和传统命令提示符都不太适合跑 WSL 里的交互式工具，建议直接用 Windows Terminal。它支持分栏、多 Tab、字体设置，对 WSL 的 ANSI 颜色和 Unicode 输出支持也更好。这是一层“皮”，但天天要用的东西，皮顺手真的很影响心情。

5. 全局安装 Codex CLI：

sudo npm install -g @openai/codex codex --version

这里有一个非常重要的小知识点：在 WSL 里敲命令，你用的是 Linux 环境，所以 npm 和 node 必须装 WSL 内部的那一份，而不是 Windows 侧装的 Node。怎么确认？直接在 WSL 终端里输入which node，如果输出是/usr/bin/node或者/home/你的用户名/.nvm/versions/node/...这种 Linux 路径就对了；如果出来的是/mnt/c/Program Files/nodejs/node.exe，说明你 PATH 里先找到了 Windows 的 Node，这会非常混乱。

1.3 首次登录与身份认证：坑从这里开始

安装只是热身，登录才是第一个真正的坑。

在终端里执行codex login，它会给一个很长的登录链接。正常流程是自动打开浏览器，但你是在 WSL 里跑，xdg-open十有八九是失效的。现象就是终端卡在 “Waiting for authorization...” 一直不动，好像死机了一样。

我当时的第一反应是“完了，卡 bug 了”，然后就开始找日志。其实没那个必要。解决办法是把终端里打印出来的完整 URL 复制出来，手动贴到 Windows 侧的浏览器地址栏里打开。登录页面会让你确认授权，然后会显示一串授权码，把这串授权码复制出来，再贴回终端回车。两秒之后终端显示 Login successful，~/.codex 目录下会生成对应的凭据文件。

这个流程本质上走的是 OAuth 设备码流程。设备码流程的好处是：命令行工具不需要保存你的账号密码，浏览器和 CLI 通过一段临时码完成配对。想明白了这一点，就不会被“为什么浏览器没打开”卡住。

登录成功之后，你默认能用的模型是 gpt-5-codex 这一类云端模型（具体看账号权限）。先跑一条最小的任务验证链路：

codex "写一个 Python 函数计算斐波那契数列第 n 项，并解释每行代码的作用"

这条任务同时验证了模型连通性、文件读写能力和基础对话能力。如果这一步能顺畅跑完，说明前面所有步骤都通了。

提示：如果你的终端提示 codex command not found，别急着怀疑安装，先检查npm prefix -g指向的目录在不在 PATH 里。这个我后面在踩坑实录里还会展开讲。

2. Superpowers 插件：给 Codex 装配专业工作流

2.1 插件机制与解决的实际问题

Codex 原生的执行能力很强，但它有个问题：太“听话”了。你说“把这个功能做完”，它就真的直接开始做。遇到简单任务还好，遇到稍微复杂一点的任务，没有规划就直接动手，经常干到一半发现路径不对。

Superpowers 解决的就是这个问题。它是一套基于 skills 机制的插件，本质是一组带明确流程指引的 SKILL.md 文件，放在 ~/.codex/skills 目录下。Codex 在加载这些技能文件之后，会按照里面定义的流程来响应任务。

用一句话概括：如果把 Codex 比作一个聪明但没经验的实习生，原生状态下的你只能告诉他“你去把这件事干了”，而装上 Superpowers 之后，你相当于给了这个实习生一套岗位说明书：接到任务先怎么拆解、计划要包含哪些内容、什么时候写测试、什么时候写实现、什么时候停下来确认。这套机制让“让 AI 干活”变得可靠了非常多。

具体到能力上，它涵盖了几个我非常常用的流程：

• 任务拆解：把一个大需求拆成多个可独立验证的小步骤，并且重新整理优先级。
• 计划先行：在动手实现之前，先生成一个包含文件结构、依赖关系和测试策略的计划，等待确认。
• 测试驱动：实现类任务按照“先写测试、确认测试失败、再写实现、确认测试通过”的顺序推进。
• 逐文件实现：把一个计划里的多个文件逐个实现，而不是一次性铺开导致上下文混乱。

2.2 安装验证与配置原理

安装 Superpowers 不需要手动下载技能文件，用 npm 装一个公共 CLI，然后让它去向 Codex 注册即可：

npm install -g superpowers-cli superpowers install codex

执行完第二条命令后，它会自动检测 Codex 的配置目录，把技能文件写入 ~/.codex/skills。为了确认真的装上了，我建议直接看目录：

ls -la ~/.codex/skills

正常情况下能看到多个技能子目录，比如 plan-skills、tdd-skills、implement-skills 之类的。如果目录是空的，说明注册环节出了问题，多半是版本不匹配或配置文件路径不对。

现在很多 AI 编程工具都支持类似的 skills 机制，Superpowers 这个生态一开始主要面向 Claude Code，后来扩展到了 Codex。这里有一个非常容易踩的坑：如果你机器上同时装了 Claude Code 和 Codex，安装插件时一定要看清楚 target 参数到底指向哪个客户端，不然技能文件可能被写到了 ~/.claude/skills，结果你在 Codex 里怎么调都看不到。装完验证一下目录，两秒钟的事，能省半小时的排查时间。

技能文件之所以有效，是因为 Codex 的 slash 命令体系和技能文件是天然配合的：你在对话里输入斜杠命令时，Codex 会去 skills 目录寻找对应的定义文件，然后把里面的流程性内容填充到当前上下文。这意味着你可以随时加载或卸载技能，甚至针对不同项目放不同的技能目录组合，相当灵活。

2.3 实测：用 TDD 流程跑一个真实小任务

理论讲完，我实测了一个任务：让 Codex 实现一个带单元测试的字符串工具函数。具体需求是用 TypeScript 实现一个toTitleCase(title: string): string函数，把英文句子转成标题大小写，并配套测试。

第一步，在项目目录里进入 Codex，开一个新对话，输入/new让插件为这个任务生成一个临时技能。它当然不会真的给你变出一个新技能文件，而是会根据任务类型选择匹配的既有技能流程。紧接着它会问我：这个任务属于什么类型？大概涉及哪些文件？

第二步，我把需求描述清楚。然后它输出了一份计划，包括：

• 文件结构：src/title-case.ts 和 tests/title-case.test.ts
• 函数签名：toTitleCase(title: string): string
• 测试用例列表：空字符串、单个单词、多个单词、连字符单词、缩写词等
• 实现策略：先按空格分词、处理小写化/大写化、再拼接

这份计划是让我确认的，不是我直接跳到写代码。这里就是 Superpowers 和原生 Codex 最不一样的地方——原生 Codex 有时候也会口头给你讲计划，但很少会把这个步骤固化成一次等待确认的交互。

第三步，确认计划后，进入红绿重构循环。Codex 先改写测试文件，然后运行测试，把失败结果贴回来给我看；接着写实现文件，再跑测试，显示通过；最后做了一处小重构，把硬编码的介词列表提取成常量。整个过程中，它每执行完一步都会把终端输出摘要贴回来，我随时可以插入纠正。

这个流程最值钱的地方在于，它把“先测试后实现”从一句口号变成了一个可执行、可监督的流程。我后来在处理稍微核心一点的模块时都用这套，质量明显比直接一把梭写出来的要稳。

3. WSL 环境实测：路径、性能与终端三座大山

3.1 路径映射：/mnt/c 一直在拖后腿

WSL 里访问 Windows 盘符，路径长这样：/mnt/c/Users/你的用户名/Projects/demo。Codex 启动时的根目录取决于你cd到哪，所以如果你在 Windows 盘上的项目里跑 Codex，它实际读写的是 /mnt/c 这一层的文件。

问题来了：WSL2 的跨盘文件访问用的是 9P 协议，性能比 Linux 原生文件系统差很多。具体表现是，git status慢、npm install慢、文件监听不稳定，而且 Codex 扫描项目文件时也会被拖慢。我做了个简单测试，同一个项目目录下，在 /mnt/c 里跑git status要 2 到 4 秒，在 ~/projects 里跑只要 0.2 秒，体感完全不一样。

所以我强烈建议：新项目直接建在 WSL 的 Linux 文件系统里，也就是~/projects这类路径下，别放在/mnt/c/Users/...里。这一点是整套方案里回报率最高的一次调整。

有人会担心：项目在 Linux 文件系统里，Windows 那边怎么用 IDE 打开？其实完全不用担心。VS Code 的 WSL 远程扩展（Remote-WSL）可以直接以 Linux 环境为工作区打开项目，读取文件走的是 WSL 内部协议，速度飞快；浏览器调试等服务也能通过 localhost 映射访问。两边互不干扰，路径却能统一。

3.2 项目放哪边：一份实测性能对比

为了把“迁移到 Linux 文件系统”这个建议讲得更有说服力，我做了一个对比测试。项目大小不大，两千多个文件的一个 TypeScript 工程。

从数据能直接看出来，跨盘访问的性能损失非常大，而且会在各种你想不到的地方冒出来。最坑的是文件监听。在 /mnt/c 下的项目里跑带 watch 的构建脚本，inotify 会频繁出问题——有时直接在终端里报错，有时是悄悄不响应用户的修改，让你以为热更新坏了。把项目迁到 Linux 文件系统后，这个问题就再也没出现。

3.3 终端与显示问题：别小看这层皮

终端本身不是核心，但它直接影响使用体验。WSL 里跑 Codex，输出内容里经常带 ANSI 颜色、表格字符、进度条和路径高亮，这些对终端字体和配色都有要求。

我的建议是 Windows Terminal 配 Cascadia Code 字体，或者任意一款 Nerd Font。直接用系统默认的 Consolas 会遇到两种情况：一种是某些特殊字符渲染成方框，另一种是表格的竖线没有对齐。看起来是小问题，但你在看测试输出和 diff 的时候，每一处错位都在消耗你的注意力。

配色方面，如果你跟我一样喜欢深色背景，把 colorScheme 设置成 Campell 或者 One Half Dark 都行。关键是保证 WSL 的 LS_COLORS 和终端主题不冲突，不然目录列表的颜色会很奇怪，比如白色字贴着浅色背景，根本看不清。

还有一组快捷键值得区分：Windows Terminal 里复制粘贴是 Ctrl+Shift+C 和 Ctrl+Shift+V，而在 WSL 里直接 Ctrl+C 是中断信号。我刚切换的时候经常按错，后来习惯了也不觉得什么，但新手一开始很容易被误触搞烦躁。

4. 踩坑实录：高频报错与排查速查表

4.1 高频报错与解决办法对照表

我把第一天折腾的时候遇到的高频问题整理成了表格，方便你直接对着查：

4.2 两个最费时间的现场复盘

第一个坑：明明 npm install 成功了，终端里codex就是 command not found。

当时我排查了很久，最后发现是 .bashrc 里 PATH 被我之前配其他工具的时候改过，把/usr/local/bin给漏掉了。npm 全局包默认装到/usr/local/bin/codex，PATH 里没有这个目录，Shell 自然找不到。解决方式是把标准路径加回去，然后source ~/.bashrc。这类问题其实靠echo $PATH加which codex就能定位，但对环境变量理解不够深的时候，真的能卡住人。

第二个坑：在 /mnt/c 下的一个大项目里跑 Codex，任务执行到一半直接卡死，终端没有任何报错，也没办法响应 Ctrl+C。

后来排查发现，问题根源是 WSL2 跨盘访问时文件监听机制吃掉了大量文件句柄，直接把进程卡住了。表面看起来是 Codex 崩了，实际上是底层文件系统交互出了问题。解决办法就是把项目迁到了 ~/projects 下，后面再也没出现过类似情况。这一步也让我彻底放弃了“项目放在 Windows 盘直接用 WSL 访问”的幻想。

4.3 我最终保留的稳定配置清单

折腾一圈之后，我把稳定运行的配置固化了下来，现在每次换机器或者重装系统都照这个来：

1. WSL2 + Ubuntu 22.04，项目一律放 ~/projects。
2. Node.js 20（NodeSource 源安装），不用系统自带 apt 源。
3. Codex CLI 全局安装，登录一次，凭据保存在 ~/.codex。
4. Windows Terminal 配 Cascadia Code，深色主题。
5. 安装 Superpowers 插件，并验证 ~/.codex/skills 目录存在。
6. 在 .wslconfig 里给 WSL 分配 8GB 内存和 4 个处理器：

[wsl2] memory=8GB processors=4 swap=2GB

7. 所有命令和路径统一走 Linux 格式，绝不用/mnt/c访问工作项目。

配置完这套之后，Codex 跑任务基本没有因为环境问题中断过。环境稳定下来，AI 才像是真的在帮你干活，而不是像个水土不服的玩具。

我个人真实体会是，这套组合里真正值钱的部分不在安装那一下，而在于把工作习惯改造成了“让工具按流程做事”。Codex 解决的是“能不能做”，Superpowers 解决的是“做得好不好”，WSL 解决的是“在哪做”。三个阶段各有各的坑，但每个坑的解法其实都回到最基础的排查逻辑：先确认路径、再确认权限、再确认进程环境，哪一环不对劲就一层一层查。如果你也是 Windows 用户，正在犹豫要不要上这套组合，我的建议是先把“项目迁移到 Linux 文件系统”这一件事做完，这是性价比最高的一步。后面再调插件和工作流，你会明显感觉到生产力在往上走。最后补一个小原则：任何新工具装上之后，先跑两条最小任务验证链路，不要一上来就搬大项目，否则出了问题很难分清是工具的锅还是环境的锅。