快速开始

本指南带你从零开始，通过 ADHDev 与你的第一个 AI 代理聊天。整个过程大约需要五分钟。

ADHDev 以两种模式运行。安装命令相同，但仪表板 URL 和账户流程不同。

	Cloud	Standalone
账户	GitHub 或 Google	无
仪表板	https://adhf.dev	http://localhost:3847
适用场景	跨网络的机器、远程访问、共享	本地使用、隐私、同一网络内的机器配对

下面默认走的是 Cloud 路径 —— 这是安装脚本会自动为你完成的设置。如果你想完全本地使用、不创建账户，请查看步骤 1 和步骤 2 中的 Standalone 部分 —— 这是正式支持的路径，而不是退而求其次的选项。

---

步骤 1 —— 安装 CLI

运行安装脚本。它会检测你的平台，在需要时安装 Node.js，把 adhdev CLI 放到你的 PATH 上，并且——对于 Cloud——直接引导你完成登录。

macOS / Linux：

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

Windows（PowerShell）：

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

macOS / Linux（Homebrew）：

brew tap vilmire/adhdev
brew install adhdev

Homebrew 会附带自己的 Node.js 运行时，因此这样可以让 adhdev 与你的全局 npm 环境保持隔离。（上面的安装脚本在 macOS 上检测到 Homebrew 可用时，也会自动使用它。）

通过 npm（任意平台）：

npm install -g adhdev

WARNING

在 Windows 上，Node.js 24+ 的全局 npm 安装目前不受支持。PowerShell 安装程序会为你引导一个可移植的 Node.js 22 运行时。

预期结果：

adhdev --version

会打印一个版本号。如果出现 command not found，请打开新的终端窗口 — 安装程序已将路径永久注册到 User 作用域的 PATH，重启后依然有效。重启后仍无法识别，请参阅 Windows PATH 故障排除。

Cloud

上面的安装脚本在安装完成后已经为你运行了设置向导（adhdev setup）—— 它会打开浏览器标签页，针对 adhf.dev 进行设备授权，让你用 GitHub 或 Google 登录，注册这台机器，并启动守护进程。如果这一步已经完成，请直接跳到下面的步骤 3。

只有在向导没有自动运行时（ADHDEV_NO_SETUP=1、非交互式终端，或者你在修复 command not found 之后需要收尾）才需要自己运行它：

adhdev setup

TIP

Cloud 登录需要 OAuth 提供方的已验证邮箱。如果你的 GitHub/Google 账户没有已验证邮箱，登录会被拒绝，而不是猜测要关联哪个账户。

预期结果： 向导会打印 Setup complete，注册这台机器，并询问是否要启动守护进程（默认：是）。

Standalone

Standalone 完全不使用设置向导 —— 因为没有账户需要创建。直接跳到下面的步骤 2，运行 adhdev standalone。

---

步骤 2 —— 打开仪表板

Cloud

如果设置阶段已经为你启动了守护进程，它现在应该正在运行 —— 在浏览器中打开 https://adhf.dev，如有提示请登录，然后跳到下面的预期结果。

否则，请自己启动它：

adhdev daemon

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

预期结果： 几秒钟内，仪表板的机器列表会将你的机器显示为 online，并带有绿色指示。当 WebRTC 通道建立后，你会看到 “P2P connected”。

如果机器没有出现：

adhdev doctor

此命令会检查守护进程进程、WebSocket 连接以及本地提供方注册表。大多数问题都会附带具体修复方案被标记出来。

Standalone

adhdev standalone

此命令会将守护进程和仪表板作为一个本地服务器一起启动，监听 http://localhost:3847，并自动在浏览器中打开它。

预期结果： 仪表板加载后显示一个空的机器列表，其中你的本地机器为 “online”。没有登录界面。

如果你想从网络中的另一台设备进行局域网访问：

adhdev standalone --host 0.0.0.0 --token <some-secret>

---

步骤 3 —— 选择一个提供方

提供方是 ADHDev 针对某个 AI 代理的适配器。首次使用时重要的两个类别：

• CLI 提供方 —— 基于终端的代理，如 Claude Code、Codex CLI、Antigravity CLI。守护进程在 PTY 下运行它们，并把终端管道传输到仪表板。
• IDE 提供方 —— 正在运行的编辑器，如 Cursor、VS Code、Antigravity、Windsurf。守护进程通过 Chrome DevTools Protocol（CDP）连接，读取/写入 IDE 内部的代理面板。

要查看 ADHDev 在你机器上检测到什么：

adhdev detect

预期结果： 一个列表，为每个已知提供方标注 installed: yes/no。任何标记为 yes 的都已可启动。

推荐的起点

为了获得最顺畅的首次运行，请选择你已经安装的其中之一：

1. Claude Code（CLI）—— adhdev launch claude
2. Codex CLI —— adhdev launch codex-cli
3. Cursor（IDE）—— adhdev launch cursor

adhdev launch 会在守护进程下打开代理。对于 IDE，它会以启用 CDP 的方式重新启动编辑器。

WARNING

adhdev launch <ide> 会关闭并重新打开 IDE，以便它能以启用 CDP 的方式启动。请先保存你的工作。

预期结果： 仪表板会为该代理生成一张新卡片（或在机器视图内生成一个新标签页），并实时显示其终端输出或 IDE 状态。

---

步骤 4 —— 发送你的第一个提示

在仪表板中，点击你刚启动的代理的卡片。你会得到两种视图之一：

• CLI 视图 —— 一个实时终端，底部有一个输入框。像在本地终端里一样输入提示并按 Enter（或点击 Send）。
• IDE 视图 —— 一个镜像你编辑器内部代理面板的聊天面板。输入提示并点击 Send。

试试一些简单的：

列出当前目录中的文件，并告诉我这是个什么类型的项目。

预期结果：

• 提供方会将代理的响应实时流式传输到仪表板。
• 对于 CLI 代理，你会看到与本地终端中相同的 token。
• 对于 IDE 代理，聊天气泡会随着模型生成而更新。
• 代理发起的任何工具/批准提示都会被镜像到仪表板，并带有相同的批准/拒绝按钮。

如果你看到提示已到达但没有响应，请检查：

adhdev status         # 守护进程健康吗？
adhdev provider list  # 提供方已加载吗？
adhdev doctor         # 有任何认证或网络问题吗？

如果代理本身要求 API 密钥或登录（Anthropic、OpenAI、Google 等），请在代理自己的 UI 或 ~/.config 中处理。ADHDev 不存储或代理这些凭据 —— 每个工具各自保留自己的认证。

---

你已就绪

现在你已经运行了一个守护进程，连接了仪表板，并且至少有一个代理通过 ADHDev 的传输回应你。

接下来去哪里

• 仪表板指南 —— 面板、机器切换器
• CLI 代理 —— 管理 PTY 会话、滚动回看、重启
• 远程视图 —— 从另一台设备控制 IDE（仅 Cloud）
• 多机器 —— 连接笔记本 + 台式机 + 工作机（Cloud 为账户关联，Standalone 为同一网络内配对）
• 兼容性与注意事项 —— 已验证的 vs. 实验性的
• 故障排除 —— 常见故障与修复

深入了解

• Provider Guide —— 编写自定义提供方
• Provider SDK —— 清单、TUI 原语、调试

卸载

adhdev uninstall     # 停止守护进程，移除 ~/.adhdev/
npm uninstall -g adhdev   # 同时移除 CLI 本身

要在不丢失本地状态的情况下切换账户，请改用 adhdev logout。