AIGC标识 Herdr+Codex多 Agent · Windows 安装教程

Herdr + Codex 多 Agent · Windows 完整安装教程

本文所有命令都按 Windows / PowerShell 语法改写。

命令一条条执行，不要整段粘贴。
环境实测日期：2026-09-10。

目录

章节 内容 全新机器
0 全文路线图 —
1 环境现状自检 ✅ 必做
2 准备 Node.js（完整版） ✅ 要装
3 安装 Codex CLI ✅ 要装
4 安装 Herdr ✅ 要装
5 接入 Codex + 装 Skill ✅
6 建项目、启动主管 ✅
7 给主管的提示词 ✅
8 手机远程（UU 远程） 可选
9 踩坑清单 ✅
10 一屏速查 ✅

0. 全文路线图

flowchart LR A["① Node.js<br/>(提供 npm/npx)"] --> B["② Codex CLI<br/>(装一个 Agent)"] B --> C["③ Herdr 本体<br/>(终端多路复用)"] C --> D["④ 注册 Codex 集成<br/>+ 安装 herdr Skill"] D --> E["⑤ 建项目目录<br/>进 Herdr 启动主管"] E --> F["⑥ 主管创建子 Agent<br/>派活 / 收结果"] F --> G["⑦ (可选) UU 远程<br/>手机看进度"]

三个东西别搞混，缺一不可：

动作 装的是什么 作用
npm install -g @openai/codex Codex CLI（Agent 本体） 真正干活的 AI
irm https://herdr.dev/install.ps1 | iex Herdr 本体（终端多路复用器） 管终端、分 pane，让多个 Agent 并行
npx skills add herdrdev/herdr --skill herdr -g Skill（知识文件） 告诉 Codex「怎么操作 Herdr」
herdr integration install codex 集成注册 让 Herdr 认得 Codex 这个 Agent

1. 开跑之前：先看你的环境现状（一条条跑,先前装坏的可以先测试一下哪个问题，删了重装,没装过的跳过该节）

node -v

npm -v

npm config get prefix

codex --version

herdr --version

判断标准：

  • node -v / npm -v 有正常版本号 → 第 2 章可跳过
  • codex --version 输出版本号 → 第 3 章可跳过
  • herdr 报「无法识别」→ 说明还没装，正常，进第 4 章

2. 准备 Node.js（完整版）

本机已装 v22.23.2，本章可直接跳到 2.7 验证安装 或整章跳过。
下面是给全新机器准备的完整内容。

2.1 为什么要装 Node.js

Node.js 装完会自带 npm（包管理器）和 npx（包运行器）。
后面很多命令行工具都是靠 npm 装的，比如：

npm install -g @openai/codex

没有 Node，这条命令根本跑不了。

2.2 版本怎么选

只认 LTS。 当前（2026 年 9 月）的状态：

版本 状态 建议
v24.21.0（Krypton） 最新 LTS ✅ 推荐装这个
v26.8.2 Current（尝鲜版） ❌ 生产别用
v22.x（Jod） 仍在 LTS 维护期 能用，但偏旧（本机就是这个）
v20 及更早 已 EOL ❌ 别用

官方已宣布：从 Node 27 起改为一年发一个大版本，不再有一年两个版本的节奏。
版本号会随时间变化，把下文命令里的 v24.21.0 换成当时的最新 LTS 号即可
（查最新：https://nodejs.org/zh-cn/download）。

Codex CLI 的 Node 版本要求是 >= 16，所以 v22 / v24 都能正常跑。

2.3 三种装法怎么选

你的情况 选哪个
只装一个版本，图省事 方法 A：官方 .msi 安装包（推荐）
需要在多个 Node 版本之间来回切 方法 B：nvm-windows
没有管理员权限 / 想绿色免安装 方法 C：免安装 zip

2.4 方法 A：官方 .msi 安装包（推荐）

A-1 图形界面方式（新手首选）

  1. 打开下载页：https://nodejs.org/zh-cn/download
  2. 选 LTS → Windows 安装包 (.msi) → 64 位
  3. 直链（v24.21.0，可直接粘进浏览器地址栏）：
    https://nodejs.org/dist/v24.21.0/node-v24.21.0-x64.msi
  4. 双击安装，全程保持勾选 Add to PATH（默认就是勾上的，别取消）
  5. 一路 Next → Install → Finish

ARM64 设备（骁龙本）请下载 node-v24.21.0-arm64.msi。

A-2 命令行方式（复制粘贴即可）

第 1 步，下载安装包：

$ProgressPreference = 'SilentlyContinue'
$msi = "$env:TEMP\node-lts-x64.msi"
Invoke-WebRequest "https://nodejs.org/dist/v24.21.0/node-v24.21.0-x64.msi" -OutFile $msi

$ProgressPreference 那行不是可有可无的：PowerShell 5.1 的进度条会让大文件下载慢十几倍。

第 2 步，校验文件是否被网络篡改（强烈建议）：

(Get-FileHash $msi -Algorithm SHA256).Hash.ToLower()

正确结果应该是：

bb0eaee134f9357f22aea915ee793343e627aefc1e66488164bac6915bce2cac

对不上就不要安装，重新下载。

第 3 步，静默安装：

Start-Process msiexec.exe -ArgumentList "/i `"$msi`" /qn /norestart" -Wait

第 4 步，删除安装包：

Remove-Item $msi

想看到安装向导界面，把命令里的 /qn 去掉即可。
静默安装用的是默认选项，默认包含「添加进 PATH」。

A-3 用 winget（如果机器上能跑）

winget install OpenJS.NodeJS.LTS

如果提示找不到命令或报错，说明你的机器上 winget（App Installer）不可用，直接回退到 A-1 / A-2。
winget 装在 C:\Users\<你的用户名>\AppData\Local\Microsoft\WindowsApps\winget.exe。

2.5 方法 B：nvm-windows（多版本切换）

⚠️ nvm-windows 是社区项目，和 macOS/Linux 上的 nvm 不是同一个东西，命令有差异
（Mac 上常写 nvm install --lts，Windows 版要写具体版本号）。

第 1 步：先卸载已装的 Node。 两者并存会打架。

第 2 步：安装 nvm-windows。
到 https://github.com/coreybutler/nvm-windows/releases 下载 nvm-setup.exe，双击安装。
（或用 winget：winget install CoreyButler.NVMforWindows）

第 3 步：新开一个 PowerShell 窗口（PATH 不会自动刷新），然后：

nvm version

nvm list available

nvm install 24.21.0

nvm list

nvm use 24.21.0

node -v

注意事项：

  • nvm-windows 通常需要管理员权限才能切换版本
  • 每次 nvm use 之后，要新开终端窗口才生效
  • 用 nvm 装的 Node，卸载要用 nvm uninstall 24.21.0，别去控制面板卸

2.6 方法 C：免安装 zip（无管理员权限）

$ProgressPreference = 'SilentlyContinue'
$zip = "$env:TEMP\node-win-x64.zip"
Invoke-WebRequest "https://nodejs.org/dist/v24.21.0/node-v24.21.0-win-x64.zip" -OutFile $zip

Expand-Archive $zip -DestinationPath "D:\nodejs" -Force

Remove-Item $zip

先确认 node.exe 的真实路径（zip 解压后通常会多一层目录）：

Get-ChildItem "D:\nodejs" -Recurse -Filter node.exe | Select-Object -ExpandProperty FullName

假设结果是 D:\nodejs\node-v24.21.0-win-x64\node.exe，就把它的所在目录加进用户 PATH：

$dir = "D:\nodejs\node-v24.21.0-win-x64"
$old = [Environment]::GetEnvironmentVariable("Path", "User")
[Environment]::SetEnvironmentVariable("Path", "$dir;$old", "User")

然后关掉终端重新开一个，再验证。

2.7 验证安装

关掉所有终端窗口，重新开一个，然后逐条执行：

node -v

npm -v

node -e "console.log('Node 安装成功: ' + process.version)"

三条都有正常输出（比如 v24.21.0 / 11.x.x / Node 安装成功: v24.21.0）就是装好了。

记住这个规律：Windows 上凡是改了 PATH，都必须新开终端窗口。
这是 90% 的「明明装了却找不到命令」的原因。

本机当前输出：v22.23.2 / 10.9.8，属于「能用但偏旧」，不影响 Herdr 和 Codex。

2.8 装完建议做的两步配置

2.8.1 换国内 npm 镜像（可选，国内下包快很多）

npm config set registry https://registry.npmmirror.com

npm config get registry

以后想还原成官方源：

npm config set registry https://registry.npmjs.org

2.8.2 把全局包目录挪到非系统盘（可选，C 盘紧张才做）

npm config set prefix "D:\npm-global"

然后把 D:\npm-global 手动加进用户环境变量 PATH（步骤同方法 C），新开窗口生效。

改过之后，npm install -g xxx 装出来的命令就落在 D:\npm-global\ 下，
比如装 codex 会得到 D:\npm-global\codex.cmd。

本机已经这么配了（npm config get prefix → D:\npm-global），所以后面的 codex 命令能直接用。

2.9 常见报错排查表

现象 原因 解决办法
'node' 不是内部或外部命令 / 无法将"node"项识别为 cmdlet PATH 没生效 关掉终端重开；仍不行就检查 PATH 里有没有 Node 安装目录
无法加载文件 ...\npm.ps1，因为在此系统上禁止运行脚本 PowerShell 执行策略太严 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，然后重开窗口
node -v 显示的版本和刚装的不一样 装了多个 Node where.exe node 看有几个结果，卸掉多余的，或改用 nvm 管理
安装包双击没反应 / 卡住 杀毒软件拦截 临时关闭杀软，或右键「以管理员身份运行」
npm install -g 报 EPERM / EBUSY 权限不足或文件被占用 用管理员 PowerShell；或按 2.8.2 把全局目录改到用户可写路径；关掉占用文件的程序
node-gyp 报错要求 Visual Studio 需要编译原生模块 安装 VS Build Tools（勾选「使用 C++ 的桌面开发」），或改用预编译版本
卸载重装后还是旧版本 有残留目录/缓存 卸载后删掉 %APPDATA%\npm、%APPDATA%\npm-cache 再重装
下载 .msi 特别慢或者失败 网络问题 换 A-2 的命令行方式重试，或改用国内镜像下载 Node 安装包

2.10 升级和卸载

升级（.msi 装的）：下载新版 msi 直接覆盖安装即可；或用 winget：

winget upgrade OpenJS.NodeJS.LTS

卸载：

  • .msi 装的 → 设置 → 应用 → 已安装的应用 → Node.js → 卸载
  • nvm 装的 → nvm uninstall 24.21.0
  • zip 装的 → 删目录 + 从 PATH 里移除对应项

3. 安装 Codex CLI

本机已装 codex-cli 0.154.0，本章可整章跳过。

3.1 安装

npm install -g @openai/codex

装完检查（应输出 0.154.0 或更新版本）：

codex --version

3.2 登录

codex

按提示登录（会拉起浏览器做 OAuth），随便问一个问题确认能正常回复。
用完退出：输入 /quit，或按两次 Ctrl+C。

如果你打算用 API Key 而不是账号登录：$env:OPENAI_API_KEY="sk-..." 只对当前窗口有效；
setx OPENAI_API_KEY "sk-..." 才持久化（明文存在注册表里，注意别在共享电脑上用），
而且 setx 之后也要新开一个窗口才生效。

补充：Codex CLI 原生 Windows 是可用的。万一遇到跟 shell 执行/沙箱相关的报错，
常规兜底方案是改用 WSL —— 但那意味着 Herdr 也得装在 WSL 里，属于另一条路线，先别急。

4. 安装 Herdr（Windows 专用安装器）

4.1 ⚠️ 先看这条：Mac 命令在 Windows 上会直接失败

动作 视频里的 Mac 命令 你要用的 Windows 命令
装 Herdr curl -fsSL https://herdr.dev/install.sh | sh irm https://herdr.dev/install.ps1 | iex
建目录 mkdir -p ~/proj New-Item -ItemType Directory -Force -Path "$HOME\proj"
进目录 cd ~/proj Set-Location "$HOME\proj"
查环境变量 echo $HERDR_ENV $env:HERDR_ENV
配置文件位置 ~/.config/herdr/config.toml %APPDATA%\herdr\config.toml
路径分隔符 / \（PowerShell 里 / 大多也能用，但别在原生程序参数里混用）

⚠️ 绝对不要在你的机器上跑 curl -fsSL https://herdr.dev/install.sh | sh。
cmd 从 PATH 里找到的 sh 是便携版 Git（MSYS2）的，它的 uname -s 返回 MSYS_NT-10.0-26200，
脚本只认 Linux/Darwin，会直接报 unsupported OS。就算强行绕过，它下的是 Linux ELF 二进制，
在 Windows 上根本跑不起来（Windows 版是 herdr-windows-x86_64.zip，脚本里没有解压分支）。

4.2 正式安装

在 PowerShell 窗口里执行：

irm https://herdr.dev/install.ps1 | iex

如果被执行策略拦住：

powershell -ExecutionPolicy Bypass -c "irm https://herdr.dev/install.ps1 | iex"

如果安全软件拦截这种「无文件 PowerShell」方式，改用 cmd.exe 的本地引导脚本：

curl.exe -fsSLo install.cmd https://herdr.dev/install.cmd && install.cmd && del install.cmd

4.3 验证

装完后：关掉当前窗口，重新开一个 Windows Terminal / PowerShell（PATH 是写进注册表的，旧窗口不会自动刷新）。

然后验证：

herdr --version

4.4 安装位置说明（以后排查问题时用得上）

  • 实体程序：C:\Users\<你的用户名>\.herdr\packages\standalone\releases\<版本>-x86_64-pc-windows-msvc\
  • 兼容别名：C:\Users\<你的用户名>\AppData\Local\Programs\Herdr\bin
  • 更新走 herdr update（新终端或重连的 SSH 会话会自动拿到新路径）

Windows 版默认用 stable 通道，stable 是官方推荐的正常使用通道，别乱切 preview。

5. 把 Codex 接进 Herdr + 安装 Skill

5.1 注册 Codex 集成（Windows 官方支持）

herdr integration install codex

5.2 安装 Herdr 的 Skill

npx skills add herdrdev/herdr --skill herdr -g

如果它让你选择安装给哪个 Agent，选 Codex。
首次运行 npx 会先下载 skills 包，需要联网，慢一点正常。

5.3 兜底方案：npx 网络失败怎么办

Skill 文件其实是随 Herdr 一起发布的，直接跑下面这条把与版本匹配的副本打印出来，
手动存成 Codex 的 skill / 用户指令文件即可：

herdr --skill

5.4 Skill 到底干什么

当 HERDR_ENV=1 时，告诉 Agent 用 herdr CLI 去创建 pane、跑命令、读输出、等待其它 Agent。
它自带一条安全规则 —— 如果 HERDR_ENV 不是 1，Agent 应当停下并声明自己不在 Herdr 管理的 pane 里。

6. 建项目文件夹，启动主管

6.1 建目录

文件夹名可以自己换：

New-Item -ItemType Directory -Force -Path "$HOME\ai-relay-station" | Out-Null

Set-Location "$HOME\ai-relay-station"

6.2 启动 Herdr

herdr

6.3 确认环境（注意是 PowerShell 语法）

$env:HERDR_ENV

正常会返回 1。如果返回空，说明你不在 Herdr 管理的 pane 里跑的，或者语法写成了 echo $HERDR_ENV。

6.4 启动主管

确认无误后，在这个窗口里输入：

codex

这次启动的 Codex 就是「主管」。

⚠️ 顺序很重要：先进入 Herdr，再启动 Codex。
反了的话，Codex 拿不到 HERDR_ENV=1，Skill 的安全规则会让它拒绝操作 Herdr。

遇到项目信任 / Hook 信任提示时，确认是自己刚建的目录和刚装的内容，再点继续。

7. 把这段提示词发给主管

你现在是主管 Agent，我要做一个XXXXX。请先分析需求、拆分任务，并真实通过 Herdr 创建独立的 Codex Agent。前端、功能分别交给不同的 Agent，开发完成后再安排一个 Agent 检查代码和 Bug。你负责派发任务、检查进度、读取各个 Agent 的结果，最后把完整项目和运行方法交给我。请先完成创建和派工，让我能在 Herdr 中看到对应的 Agent。遇到需要我决定的问题再问我，其他情况自行推进。

把「XXXXX」换成你自己想做的项目，具体功能尽量写清楚。

发完之后看一眼 Herdr 的 Agent 列表，确认它真的创建了其它 Agent。
如果它嘴上说分工了、列表里还是只有自己，就补一句：

请先通过 Herdr 真实创建其他 Agent 并派发任务，完成后再继续开发。

8. 想在手机上操作，再接 UU 远程

电脑端（Windows）和手机端都装好 UU 远程，按界面提示完成连接和授权。
手机连上电脑后进入远程终端，进项目目录运行 Herdr，就能查看任务、给主管补需求。

长提示词用手机系统输入法的语音输入，检查完文字再发送。

必须先关掉自动睡眠，否则手机连过去人就没了。在你自己的 PowerShell 里执行：

powercfg /change standby-timeout-ac 0
powercfg /change hibernate-timeout-ac 0
powercfg /change monitor-timeout-ac 15

（-ac 是插电状态；如果笔记本要合盖长时间跑，还得去「电源和电池 → 合盖时不采取任何操作」，
或者直接用 -dc 系列同样设一遍。）

9. Windows 专属踩坑清单

  1. 别用 install.sh —— Windows 版只有 PowerShell / install.cmd 两条路。

  2. 装完 Herdr 找不到命令 → 关掉终端重新开一个，PATH 已经写进注册表了，只是旧窗口没刷新。

  3. echo $HERDR_ENV 在 PowerShell 里会输出空 → 用 $env:HERDR_ENV。

  4. Herdr 光标不闪烁 —— 这是 Windows 上的默认行为（host_cursor = "auto" 时 Herdr 自己画光标，为了避开 ConPTY 光标抖动）。
    如果中文/日文输入法的候选框位置飘，在 %APPDATA%\herdr\config.toml 里加：

    [ui]
host_cursor = "native"

    然后执行 herdr server reload-config。代价是可能重新出现光标闪烁/跳动。

  5. 复制粘贴 —— pane 里拖选即复制；粘贴用 Ctrl+Shift+V（Windows Terminal）。
    想用终端自己的右键菜单，按住 Shift 再右键（不然右键会被 Herdr 的 pane 菜单截走）。

  6. Windows 上不支持：herdr terminal attach、把本机当 herdr --remote 的目标主机、live handoff。
    想远程到 Linux/macOS 机器用 herdr --remote <主机名> 是支持的。

  7. 多开 Agent 费额度 —— 先开 2~3 个试流程，跑通了再加。

  8. 权限确认先看清内容，重要项目提前备份，账号密钥别直接贴进提示词。

  9. 第一次拿小项目试 —— 先把「创建 Agent → 派任务 → 收结果」这条链路跑通，再上复杂任务。

  10. 改了 PATH 就要新开终端 —— Node、Codex、Herdr 全部适用，这是最高频的「明明装了却找不到命令」。

10. 一屏速查（全部命令汇总）

# ========== ① Node.js（本机已装 v22.23.2，可跳过）==========
# 方法A：官方 msi（推荐）
$ProgressPreference = 'SilentlyContinue'
$msi = "$env:TEMP\node-lts-x64.msi"
Invoke-WebRequest "https://nodejs.org/dist/v24.21.0/node-v24.21.0-x64.msi" -OutFile $msi
(Get-FileHash $msi -Algorithm SHA256).Hash.ToLower()   # 期望 bb0eaee1...2cac
Start-Process msiexec.exe -ArgumentList "/i `"$msi`" /qn /norestart" -Wait
Remove-Item $msi

# 验证（必须新开一个终端窗口）
node -v
npm -v
node -e "console.log('Node 安装成功: ' + process.version)"

# 可选：国内镜像 + 全局目录
npm config set registry https://registry.npmmirror.com
npm config get registry
npm config set prefix "D:\npm-global"    # 改完记得把该目录加进用户 PATH

# ========== ② Codex CLI（本机已装 0.154.0，可跳过）==========
npm install -g @openai/codex
codex --version
codex                      # 登录后 /quit 退出

# ========== ③ Herdr（新窗口再执行 herdr --version）==========
irm https://herdr.dev/install.ps1 | iex

# ========== ④ 接入 + Skill ==========
herdr integration install codex
npx skills add herdrdev/herdr --skill herdr -g
herdr --skill              # npx 失败时的兜底：打印内置 Skill

# ========== ⑤ 建项目 + 启动主管 ==========
New-Item -ItemType Directory -Force -Path "$HOME\ai-relay-station" | Out-Null
Set-Location "$HOME\ai-relay-station"
herdr
$env:HERDR_ENV             # 期望输出 1
codex                      # 在这里面启动主管

# ========== ⑥ 防睡眠 ==========
powercfg /change standby-timeout-ac 0
powercfg /change hibernate-timeout-ac 0
powercfg /change monitor-timeout-ac 15

# ========== 常见错误修复 ==========
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned
where.exe node
herdr update
posted @ 2026-09-12 00:24  Floatingfur  阅读(4)  评论(0)    收藏  举报