由代理驱动的新机器安装

本页是写给AI 编码代理（Claude Code、Codex、Hermes 或类似工具）的，前提是它被要求在一台全新机器上安装配置 ADHDev。请按顺序执行下面编号的步骤，并严格按原样运行每条命令。

给人类读者： 你可以把本页交给你的代理并说*"按照新机器指南在这台机器上安装 ADHDev"* —— 除了唯一一次只有你能批准的浏览器登录之外，代理会完成所有事情。

目标：从一台干净的机器出发，以尽可能少的人工参与，达到守护进程运行并完成第一次 adhdev launch。恰好只有一个步骤需要人类参与 —— 云端浏览器登录 —— 而且它有清晰的标记。

先选择一种模式

ADHDev 有两种运行模式。开始之前先做决定；安装命令是相同的，只有账户流程不同。

	A —— Standalone	B —— Cloud
账户 / 登录	无	GitHub 或 Google（浏览器登录）
是否需要人工步骤	否 —— 完全自主	是 —— 一次浏览器批准
仪表板	`http://localhost:3000`	`https://adhf.dev`
最适合	单台机器、本地使用、无账户、完全无人值守的安装	多机器、远程访问、共享、Repo Mesh

给代理的经验法则： 如果用户没有要求云端/多机器/远程功能，就选择 Standalone（A） —— 它不需要人类参与，也不需要账户。只有当用户明确想要账户、远程访问或 mesh，并且本人在场可以批准浏览器登录时，才选择 Cloud（B）。

第 1 步 —— 检查前置条件

ADHDev 需要 Node.js ≥ 22。

bash

node --version

Node ≥ 22： 很好，继续。
没有 Node，或 Node < 22： 安装脚本（第 2 步）会为你引导一个运行时（macOS/Linux 上用 nvm/fnm/brew/apt/dnf/yum；Windows 上用便携版 Node 22）。如果你更愿意自己先安装 Node，请安装 22.x LTS —— 不要在 Windows 上安装 Node 24+（参见下面的警告）。

Windows + Node 24+

在 Windows 上，Node.js 24+ 会阻止全局 npm install -g adhdev。请改用 PowerShell 安装器 —— 它会在 ~/.adhdev/tools/node22 下配置一个便携版 Node.js 22 并使用它。不要试图通过强制使用更新的 Node 来绕过这一点。

顺便确认一下操作系统，以便在第 2 步中选对安装命令：macOS、Linux 还是 Windows。

第 2 步 —— 安装 CLI（无人值守）

安装脚本会检测平台，在缺失时安装 Node.js，并把 adhdev 放入 PATH。

对于无人值守的代理驱动安装，请设置 ADHDEV_NO_SETUP=1，这样安装器只安装而不启动交互式安装向导（后续步骤由你自己来驱动安装配置）。

macOS / Linux：

bash

ADHDEV_NO_SETUP=1 curl -fsSL https://adhf.dev/install | sh

Windows（PowerShell）：

powershell

$env:ADHDEV_NO_SETUP=1; iwr https://adhf.dev/install.ps1 -useb | iex

已经有 Node ≥ 22？（任意平台）：

bash

npm install -g adhdev

Homebrew（macOS / Linux）—— 无需单独的 Node：

bash

brew tap vilmire/adhdev && brew install adhdev

Homebrew 自带它自己的 Node.js 运行时。上面的无人值守安装脚本在 macOS 上存在 brew 时已经会自动优先走这条路径，所以你通常不需要手动运行它。

可选：preview 通道

设置 ADHDEV_CHANNEL=preview 可安装 @next（候选发布）构建而非 stable。正常的 stable 安装请省略它。Homebrew tap 只跟踪 stable 版本，因此 preview 安装始终通过 npm 进行。

验证安装：

bash

adhdev --version

这应当打印出一个版本号。安装器会为当前会话更新 PATH 并将其永久注册，所以这通常立即就能工作 —— 不需要开新终端。

如果你仍然遇到 command not found（某个未接收到 PATH 变更的受限 shell），你有两个无需打开新终端就能工作的后备方案：

通过完整路径调用稳定的 shim（安装器总是把 adhdev 放在这里）：

powershell

# Windows
& "$HOME\.adhdev\npm-global\adhdev.cmd" --version

bash

# macOS / Linux
"$HOME/.adhdev/npm-global/bin/adhdev" --version

Windows 便携版 Node 逃生舱 —— 如果连 shim 本身都跑不起来（例如 CLI 已落地但通往 node.exe 的 PATH 是陈旧的），请用安装器配置的便携版 Node 22 直接调用已安装的 CLI 入口：
powershell
```
& "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js" --version
```

除此之外，打开一个新终端总是有效的（PATH 已被永久注册）。

第 3 步 —— 启动守护进程

模式 A —— Standalone（无需登录）

Standalone 不需要账户。直接启动它：

bash

adhdev standalone

这会在 localhost:3847 上启动守护进程，在 localhost:3000 上启动仪表板，且没有认证。完全跳过第 4 步 —— 直接进入第 5 步。

可选的局域网访问：adhdev standalone --host 0.0.0.0 --token <some-secret>。--token 是可选的，只有在把 standalone 暴露到 localhost 之外时才相关。

模式 B —— Cloud（需要登录）

Cloud 需要账户。第 4 步中的登录是唯一的人工步骤。在第 4 步报告机器上线之前，不要运行 adhdev daemon。

第 4 步 —— 登录（仅 Cloud）⏸ 人工步骤

⏸ 人工步骤 —— 代理必须在此停下

云端登录使用打开浏览器让人类批准的 OAuth 设备流程。没有非交互式登录标志，而且这是有意为之 —— 账户授权是一道安全边界，按设计应由人类跨越一次。

绝不要试图通过环境变量或任何其他旁路注入机器密钥来绕过这一点。那不受支持，也不得被写入文档或脚本。

本步骤给代理的指示：

不要自己运行登录命令并在那里等待。 相反，告诉用户："我需要你登录。请运行 adhdev setup（别名 adhdev login）并用你的 GitHub 或 Google 账户批准浏览器提示。"
暂停并把控制权交给用户。 在登录待处理期间不要继续。
只在账户获得授权后才恢复。 轮询 adhdev status，只有在它报告机器/账户上线后才继续到第 5 步。在此之前，请持续等待 —— 不要重试安装或守护进程命令。

给人类：运行这条命令，并批准针对 adhf.dev 打开的浏览器标签页：

bash

adhdev setup    # or: adhdev login

登录需要一个来自 GitHub 或 Google 的已验证邮箱，否则会被拒绝。你在浏览器中批准之后，把控制权交回给代理。

然后启动云端守护进程（后台、长期运行）：

bash

adhdev daemon

守护进程会连接到 api.adhf.dev，注册这台机器，并打印一个机器 ID。

第 5 步 —— 验证

确认守护进程健康：

bash

adhdev status

预期：

Standalone： 守护进程在 localhost:3847 上报告健康。
Cloud： 机器显示为在线，已连接到 api.adhf.dev。

如果状态不健康，请在启动之前先看下面的疑难排查。

第 6 步 —— 启动第一个代理

启动一个用户已经安装的 CLI 代理：

bash

adhdev launch claude    # Claude Code
# or:  adhdev launch codex-cli
# or:  adhdev launch <target>

adhdev launch <target> 会在守护进程之下启动该代理，并把它镜像到仪表板。ADHDev 不管理代理自身的 API 密钥或登录 —— 每个工具保有自己的认证。如果代理索要它自己的凭据，那是在该代理的界面中处理的，而不是由 ADHDev 处理。

完成。 现在你有了一个运行中的守护进程、已连接的仪表板，以及第一个在线的代理。

疑难排查

command not found: adhdev —— 安装器也会为当前会话更新 PATH，所以这很少见。如果确实发生了，请通过完整路径调用稳定的 shim，而不是打开新终端：& "$HOME\.adhdev\npm-global\adhdev.cmd"（Windows）或 "$HOME/.adhdev/npm-global/bin/adhdev"（macOS/Linux）。仅限 Windows 的最后手段，即连 shim 都跑不起来时：& "$HOME\.adhdev\tools\node22\node-v22.*-win-x64\node.exe" "$HOME\.adhdev\npm-global\node_modules\adhdev\dist\cli\index.js"。打开新终端同样有效 —— PATH 已被永久注册。
Node < 22 —— 安装一个 22.x LTS（或让安装器为你引导一个）。ADHDev 拒绝在更老的 Node 上运行。
Windows 上在 Node 24+ 安装失败 —— 请使用 PowerShell 安装器（便携版 Node 22），而不是在 Node 24+ 上执行 npm install -g。
Windows 针对 ...\adhdev.ps1 报 PSSecurityException / "cannot be loaded because running scripts is disabled" —— 默认的 Restricted 执行策略会阻止 npm 生成的 PowerShell shim（PowerShell 优先使用 adhdev.ps1 而非 adhdev.cmd）。安装器会自动为当前用户放宽这一策略；如果它被阻止了（例如组策略），请自行运行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，或者通过调用 .cmd 完全绕开 .ps1：& "$HOME\.adhdev\npm-global\adhdev.cmd" --version。
守护进程无法上线（Cloud） —— 运行 adhdev status；如果它一直离线，就退出并重新登录：先 adhdev logout 然后 adhdev setup，之后再次运行 adhdev daemon。
启动后代理不响应 —— 先 adhdev status（守护进程健康吗？），然后确认你的目标所需的提供方已安装。

引导脚本

一个配套的 Node 脚本把第 1–6 步自动化，并内置了人工步骤的护栏：scripts/bootstrap-new-machine.mjs。

bash

# See exactly what would run, without executing anything:
node scripts/bootstrap-new-machine.mjs --mode standalone --dry-run

# Fully unattended standalone setup:
node scripts/bootstrap-new-machine.mjs --mode standalone --yes

# Cloud: runs up to the sign-in, then stops and waits for you to approve in the browser:
node scripts/bootstrap-new-machine.mjs --mode cloud --yes

标志：

--mode cloud|standalone —— 要安装配置哪种模式。
--yes —— 无人值守；不经额外确认就运行安装/守护进程。不加它时，破坏性步骤只会被描述而不会被执行。
--dry-run —— 只打印命令；不运行任何东西。请先用它来预览。

在 cloud 模式下，脚本会有意地在登录步骤停下，打印浏览器批准的指示，然后轮询 adhdev status 直到机器上线才恢复 —— 与上面的 ⏸ 人工步骤保持一致。它绝不会注入凭据。

由代理驱动的新机器安装 ​

先选择一种模式 ​

第 1 步 —— 检查前置条件 ​

第 2 步 —— 安装 CLI（无人值守） ​

第 3 步 —— 启动守护进程 ​

模式 A —— Standalone（无需登录） ​

模式 B —— Cloud（需要登录） ​

第 4 步 —— 登录（仅 Cloud）⏸ 人工步骤 ​

第 5 步 —— 验证 ​

第 6 步 —— 启动第一个代理 ​

疑难排查 ​

引导脚本 ​

由代理驱动的新机器安装

先选择一种模式

第 1 步 —— 检查前置条件

第 2 步 —— 安装 CLI（无人值守）

第 3 步 —— 启动守护进程

模式 A —— Standalone（无需登录）

模式 B —— Cloud（需要登录）

第 4 步 —— 登录（仅 Cloud）⏸ 人工步骤

第 5 步 —— 验证

第 6 步 —— 启动第一个代理

疑难排查

引导脚本