智能体宿主服务 softov/ahpd

ahpd - 智能体宿主平台

智能体跑在哪都行，控制它们也从哪都行。

ahpd 是开源服务器，把你的 AI 智能体、工具和项目聚到一起。

智能体可以跑在你的电脑上、远程服务器上，或者容器里。从浏览器、桌面端、终端或手机连进来。

你的工作留在服务器上。关掉应用、换台设备、断开连接，会话都不会丢。

基于 Agent Host Protocol (AHP) 构建。实现了哪些内容，见 AHP 兼容性。

阅读文档 · GitHub · ahpio.com

几分钟就能跑起来

Linux 或 macOS 上，一行命令安装：

curl -fsSL https://ahpio.com/ahpd/install.sh | bash

Windows 上，在 PowerShell 里执行：

irm https://ahpio.com/ahpd/install.ps1 | iex

脚本会检查 Node 22.18 或更新版本，不用 sudo 就能装好 @ahpd/server，把 ahpd 加进 PATH，然后运行 ahpd configure。安装选项

也可以用 npm 安装，再跑初始化：

npm install -g @ahpd/server --allow-scripts=node-pty
ahpd configure

选好智能体、网络设置和项目文件夹。以后想加智能体，运行 ahpd plugin install @ahpd/agent-claude。

启动宿主：

ahpd start --path /work/project

宿主已经就绪，等着 AHP 客户端连进来。在终端里用 ahpc 连接：

npx @softov/ahpc --host ws://127.0.0.1:9187

🗂️ 同时服务多个项目

ahpd --path /work/api --path /work/web

项目路径只是目录条目，不是文件系统沙箱。能不能访问其他路径，取决于宿主配置的能力和权限。

🔐 远程连接

默认情况下，宿主只监听回环地址。要监听其他网卡，先配置连接 token：

ahpd --host 0.0.0.0 --connection-token-file ~/.config/ahpd/token
只把主机暴露给你信任的网络，并保护好 token。参见远程访问文档。

你的智能体。你的机器。你的掌控。

AI 智能体可以帮你写代码、修问题、管理文件、自动化任务。但它们往往依赖你启动它们时所用的终端或应用。

ahpd 给智能体一个运行的地方，也给你一条找到它们的路。

⏳ 让工作持续运行

启动任务，让它留在主机上跑。你关掉客户端，智能体照样继续干活。回头再看结果就行。

📱 任何设备都能干活

在桌面端开始。用手机看进度。在浏览器或终端里打开同一个会话。工作状态始终同步。

🤖 选你喜欢的智能体

用 Claude Code、Codex、Copilot、Gemini、pi 以及其他受支持的智能体。按需配置，通过一个主机统一使用。

🐳 在隔离环境里跑任务

用 Docker 容器给任务独立的环境。项目需要不同工具或依赖时，把工作隔开。

⏰ 自动化例行任务

给智能体工作排期，或者从 webhook 触发。没有客户端连接时，主机也能跑任务。

🔐 控制访问

控制谁能碰你的智能体和工具。定义谁可以和主机交互、能执行哪些操作。

📊 诊断

查看主机状态、日志、网络信息和遥测数据。

💰 控制花费

看清每个人、每个团队、每个项目在模型上花了多少。设置每日、每周或每月限额，达到限额后主机拒绝新任务。

🔀 共享你的模型

让智能体或脚本指向你的主机，用 ahpd token 调用任意模型。主机使用服务商的 key，套用你的策略，记录花费。模型代理

不只是聊天

启用相应能力后，智能体和客户端可以操作同一份主机资源。

📁 资源

通过资源端口读取、写入、创建、删除文件。

⌨️ 终端

从任意客户端在主机上打开 shell。智能体跑命令时你能实时看到，回头还能读完整输出。

🌳 Git 与 GitHub

查看变更、分支、工作树和 pull request。用独立工作树，避免并行会话共用同一个工作树。

用你偏好的智能体

不必绑定某一个智能体或模型服务商。

ahpd 支持多种智能体集成。每种集成都是一个插件。

✻ @ahpd/agent-claude：通过 Claude Agent SDK 运行 Claude。文档

ahpd plugin install @ahpd/agent-claude

π @ahpd/agent-pi：直接在宿主机里运行 pi 编码智能体。文档 ahpd plugin install @ahpd/agent-pi

⇄ @ahpd/agent-acp：通过 Agent Client Protocol 接入 Codex、Copilot、Gemini 等受支持的智能体。文档 ahpd plugin install @ahpd/agent-acp

◈ @ahpd/agent-cofold：通用运行框架，用来接入受支持的 OpenAI 兼容模型。文档 ahpd plugin install @ahpd/agent-cofold

用插件扩展更多能力

每项能力都可以按你的环境来配置。

@ahpd/computer：为智能体任务创建隔离环境。文档 ahpd plugin install @ahpd/computer

@ahpd/bot：给智能体一套自己的身份、工作区和会话。文档 ahpd plugin install @ahpd/bot

@ahpd/webhook：从 HTTP 请求启动工作。文档 ahpd plugin install @ahpd/webhook

@ahpd/tunnel-devtunnel：借助 Microsoft Dev Tunnel，在另一网络的 VS Code 里访问你的宿主机。文档 ahpd plugin install @ahpd/tunnel-devtunnel

@ahpd/tasks：维护一份任务与计划清单，每个智能体和每个人都能读写。文档 ahpd plugin install @ahpd/tasks

@ahpd/push：会话需要你时，即使应用已关闭，也能收到手机通知。文档 ahpd plugin install @ahpd/push

@ahpd/activepieces：把 Activepieces 连接器当作工具，供你的会话和机器人使用。文档 ahpd plugin install @ahpd/activepieces

一个主机，多种客户端。

ahpd 运行你的智能体，并保留它们的会话。用顺手的客户端连上来。

🌐 浏览器 → @ahpd/web

在浏览器里管理会话、文件、终端和主机设置。

GitHub · Releases

🖥️ 桌面 → ahp-desk

连接多个主机，管理本地安装，在独立窗口中工作。

GitHub · 下载

💻 终端 → @softov/ahpc

通过交互式终端、命令行命令或脚本与智能体协作。

Connect to your host with the terminal client
npx @softov/ahpc --host <host-address> --token <your-token>

GitHub · Releases

📱 移动端 → AgentHost Client

跟进工作进度，接收通知，智能体需要你批准时及时响应。

Android · iOS 即将推出 · 官网

🔌 其他 AHP 客户端

连接兼容应用，包括受支持的 VS Code 集成。

AHP 客户端库 · AHP 实现

一个主机，每块屏幕。 在一台设备上开始工作，换一台接着做。会话始终留在主机上。

按你的需要定制

ahpd 核心很小，另有一套插件系统。新增智能体、工具、URI scheme、环境和服务，都不用改守护进程。

🧰 用 SDK 构建

@ahpd/sdk 让你把 AHP 主机嵌进自己的应用。协议协商、订阅、快照、状态更新、重连、会话、聊天和对话记录分页，它都替你处理。

import { createHost, listen } from '@ahpd/sdk';
import { claude } from '@ahpd/agent-claude';

const path = process.cwd();
const host = createHost({ path, agents: [claude({ paths: [path] })] });
await listen({ port: 9187 }, (peer) => host.accept(peer));

构建你自己的主机

🧩 编写插件与智能体

不用改动服务端本身，就能扩展你的宿主。

实现 Agent 接口，或者贡献宿主端口、工具和 URI scheme。扩展可以从 npm 包、本地目录或带 manifest 的文件加载。

Load plugins for one run, in place of the configured list
ahpd --plugin @ahpd/agent-claude --plugin @ahpd/computer
A single file, with a plugin.json beside it that names its id and main
ahpd --plugin ./scratch-agent.mjs
A directory with a manifest, tried against the working directory first
ahpd --plugin ./my-custom-agent

自定义智能体实现同一个 Agent 接口，命名方式与上面的智能体一致。客户端只说 AHP，不依赖任何智能体 SDK。

flowchart LR
classDef core fill:#0f172a,stroke:#10b981,stroke-width:1.5px,color:#fff
classDef plugin fill:#1e293b,stroke:#8b5cf6,stroke-width:1.5px,color:#fff
classDef claude fill:#1e293b,stroke:#F88c00,stroke-width:1.5px,color:#fff
classDef cofold fill:#1e293b,stroke:#3b82f6,stroke-width:1.5px,color:#fff

SERVER["@ahpd/server"]
SDK["@ahpd/sdk"]

subgraph Plugins ["Agent Plugins"]
CLAUDE["@ahpd/agent-claude"]
COFOLD["@ahpd/agent-cofold"]
ACP["@ahpd/agent-acp"]
PI["@ahpd/agent-pi"]
CUSTOM["Your agent"]
end

SERVER --> SDK
SERVER -. "dynamically loads" .-> Plugins

CLAUDE -->|"implements"| AGENT["Agent Interface"]
COFOLD -->|"implements"| AGENT
ACP -->|"implements"| AGENT
PI -->|"implements"| AGENT
CUSTOM -->|"implements"| AGENT

SDK -->|"hosts & manages"| AGENT

class SERVER,SDK core
class CLAUDE claude
class COFOLD cofold
class ACP,PI,CUSTOM plugin

插件在守护进程内运行，拥有它的权限：只安装你信任的代码。
需要哪些集成就加哪些，用不到的删掉或禁用。

编写插件 · 编写智能体 · 最小智能体示例

文档

完整文档在 softov.github.io/ahpd。

| 文档 | 用途 |
| 快速上手 | 安装、配置、启动，并连接 VS Code |
| 安装 | 安装，以及在 Node、Bun 或 Deno 上运行 |
| 升级 | 升级守护进程及其插件 |
| 参考 | 所有命令与参数 |
| 插件 | 安装、更新和配置插件 |
| 用户 | 用户与授权 |
| 策略 | 谁可以使用哪个智能体、模型和计算机，以及用量上限 |
| 用量 | 每个人、每个团队、每个项目花了多少 |
| 模型代理 | 用你的 ahpd token 通过宿主调用模型 |
| 编写插件 | 插件契约、清单和事件 |
| 编写智能体 | Agent 和 Session 契约 |
| 构建你自己的宿主 | createHost 和端口 |
| AHP 兼容性 | 本宿主实现了 AHP 的哪些部分，逐条命令说明 |

每份文档都列在 docs/README.md 里，一行一条。

开发

欢迎提供技巧、PR 和贡献！

详细开发指南见 DEVELOPER.md。

在 GitHub Discussions 页面讨论开发、问题和想法。

任何开发都从克隆或 fork 仓库、安装依赖开始。

git clone https://github.com/softov/ahpd
cd ahpd

pnpm install
pnpm build

pnpm test
pnpm typecheck

可以用严格 schema 校验协议抓包：

pnpm wire -- packages/sdk/test/fixtures/wire.jsonl

开源。为选择而生。

ahpd 开源，采用 MIT 协议发布。

跑在你自己的基础设施上。选你的智能体，配你的工具，搭出适合你的环境。

个人项目、开发团队，或者需要智能体能力的应用，都可以用它。

你的基础设施。你的智能体。你的工作流。

ahpd 属于 ahpio，即 Agent Host Platform。到 ahpio.com 了解整个平台。

文档 · 源码 · ahpio.com