HAMP

HAMP（Human-Agent-Machine Platform）连接人、AI Agent 与远端机器。用户可以通过 Web 或飞书向多个 Agent 分派任务；Agent 使用其原生文件、终端和开发工具完成工作，并可在审批后调用远端 Machine 暴露的结构化能力。

HAMP 当前处于 Alpha 阶段，接口和配置可能在后续版本中调整。

特性

• 统一管理多个 Agent 和 Machine，支持在线状态、会话绑定和消息路由；
• 内置 Codex Agent 适配器，并允许扩展其他 AI Agent；
• Web/PWA 与飞书入口共享会话和执行状态；
• Agent 与 Machine 通过 WebSocket/WSS 主动连接 Hub；
• 使用 MessagePack 二进制帧传输，支持 CRPC get、set 和 call；
• Machine 可桥接站点内已有的 MQTT/CRPC 服务，也可暴露本地 Python 模块；
• 支持高风险 Machine 操作审批、超时控制、迟到结果和 SQLite 审计；
• 支持独立 Node token 的签发、过期和吊销；
• 可选 Hub 托管模型认证，使远端 Agent 无须保存上游模型密钥。

架构

                   Web/PWA / Feishu
                           │
                           ▼
                          Hub
              conversations · routing · approval
                    ┌──────┴──────┐
                    │ WebSocket   │ WebSocket
                    ▼             ▼
               Agent Node     Machine Node
               Codex / AI      structured calls
                                      │
                                      ▼
                             local MQTT / CRPC
                                      │
                                      ▼
                                   Devices

Hub 不实现新的 Agent Loop。Agent 继续使用现有 AI 产品提供的文件编辑、终端、Git 和测试能力。Machine Node 不运行 AI，只负责执行明确的结构化调用。

跨网络的 Hub/Node 通信使用 WebSocket；MQTT 仅用于 Machine 所在站点的本地 CRPC 域，不应直接暴露到公网。

安装

HAMP 需要 Python 3.10 或更高版本。

# Agent 和 Machine Node
python -m pip install hamp

# Agent 调用 Machine 的 MCP 支持
python -m pip install "hamp[mcp]"

# Hub 与 Web 界面
python -m pip install "hamp[hub]"

# Hub、Web 与飞书适配器
python -m pip install "hamp[feishu]"

# 所有可选运行依赖
python -m pip install "hamp[all]"

使用 Codex Agent 时，还需单独安装 Codex CLI。HAMP 会自动发现 Codex 原生可执行文件；Windows 上即使 PATH 指向 npm 的 codex.cmd，也会自动定位 npm 全局安装目录或 VS Code Codex 扩展内的 codex.exe，无需传入可执行文件路径。

快速开始

单机演示

已登录 Codex CLI 的电脑可以直接启动 Hub、Web 界面和本地 Agent：

hamp --open

浏览器访问 http://127.0.0.1:8765/web/。

恢复指定 Codex 会话：

hamp --session <session-id> --open

分别启动 Hub 和 Agent

配置仅供 Human Adapter 和 Web 管理面使用的 control token，然后启动 Hub：

export HAMP_CONTROL_TOKEN=<random-control-token>
hamp-hub --web 0.0.0.0:8765

--web 使用 HOST:PORT 格式；默认值为 127.0.0.1:8765。

Owner 先通过飞书添加 Node 并取得一次性邀请：

/add agent-a

然后在 Agent 所在电脑启动 Node，并附上机器人返回的邀请：

hamp-agent \
  --id agent-a \
  --hub ws://127.0.0.1:8765/ws/node \
  --dir /path/to/project \
  --key <one-time-key>

邀请不设置有效期，但只能使用一次。Node 首次连接时在本地生成并保存自己的私有凭据；Hub 验证邀请后登记该凭据，邀请随即失效。私有凭据不会经过飞书。Windows PowerShell 可将行尾的 \ 改为反引号，或将命令写在一行。

连接 Machine

桥接站点内已有的 MQTT/CRPC service：

hamp-machine \
  --node-id machine-a \
  --hub ws://127.0.0.1:8765/ws/node \
  --backend crpc \
  --service controller

直接将本地 Python 模块作为 peval service 暴露：

hamp-machine \
  --node-id machine-a \
  --hub ws://127.0.0.1:8765/ws/node \
  --backend local \
  --module device_adapters

模块中的公开对象、属性和方法分别通过相同的 get、set、call 语义访问，无须修改 HAMP 源码注册。

飞书接入

安装 hamp[feishu]，配置飞书应用凭据后启动：

export FEISHU_APP_ID=<app-id>
export FEISHU_APP_SECRET=<app-secret>
hamp --feishu --open

Windows PowerShell 使用 $env:FEISHU_APP_ID = "..." 和 $env:FEISHU_APP_SECRET = "..."。

支持的主要命令：

/help
/status
/agents
/use <agent-id>
/cancel
/approve <operation-id>
/reject <operation-id>
/allow @成员
/deny @成员
/add <node-id>
/del <node-id>

已授权成员使用 /status 查看当前会话绑定的 Agent；只有 Owner 可以使用 /agents 查看全部 Agent。飞书支持向 Agent 发送文件：先发送一个或多个文件，再发送处理指令，文件会交给该指令所使用的 Agent。

不同私聊或群聊可分别绑定 Agent。默认只有应用创建者能够操作机器人；创建者在群聊中使用 /allow @成员 时，权限仅对当前群聊和该群当前绑定的 Agent 生效，并可在同一群聊使用 /deny @成员 回收。普通成员不能使用 /use 切换 Agent，也不能通过 @agent-id 操作其他 Agent；只有 Owner 能选择或临时指定 Agent。群成员单独私聊机器人时仍无权调用 Agent。Owner 权限全局有效，授权记录持久保存在 Hub 运行目录中。未获授权的成员即使 @机器人也不会触发 Agent。

飞书消息撤回会同步到 Hub：尚未处理的文件或排队中的命令会被取消，正在运行的命令会请求停止且不再发送最终回复；已经完成的操作不会回滚。撤回后的消息正文会从 Hub 消息记录中清除，仅保留不含原文的审计信息。

多 Agent

同一台电脑可以运行多个 Agent，但每个进程必须使用不同的 node_id、工作目录和 AI session：

hamp-agent --id agent-a --dir /work/project-a \
  --hub ws://127.0.0.1:8765/ws/node --session <session-a>

hamp-agent --id agent-b --dir /work/project-b \
  --hub ws://127.0.0.1:8765/ws/node --session <session-b>

不要让多个进程同时写入同一个 Codex session。

TLS 与安全

默认配置使用 HTTP/WS，适用于可信内网和本机测试。不要把默认端口直接暴露到公网。

启用 HTTPS/WSS：

hamp-hub --tls

若未指定证书，Hub 会在 .hamp/tls/ 生成自签名证书。正式部署应使用受信任证书，并通过以下环境变量指定：

HAMP_TLS_CERTFILE=/path/to/fullchain.pem
HAMP_TLS_KEYFILE=/path/to/private.key

安全部署还应遵循以下原则：

• 每个 Agent 和 Machine 使用独立、随机生成的 Node token；
• 将 token 通过环境变量或受保护的配置文件传入；
• 使用 WSS 或受保护的私有网络承载跨网络通信；
• 仅向 Machine 暴露必要的 service，并配置 payload 大小和执行超时；
• 对具有副作用的 Machine 操作启用人工审批；
• 将站点 MQTT broker 保留在可信局域网内，并自行配置认证和 ACL。

当前 Node 客户端允许使用 Hub 自动生成的自签名证书，因此不会验证其证书链与主机名。此模式便于测试，但不能抵御中间人攻击；公网部署应在受保护网络中使用，或等待客户端 CA 校验能力完善后再直接开放。

托管模型认证

Hub 可以提供 OpenAI-compatible 模型网关，使远端 Agent 不保存上游 API key：

Hub 默认使用 --provider auto：配置了 HAMP_PROVIDER_API_KEY 时选择 OpenAI API，否则使用 ~/.codex/auth.json 中的 Codex OAuth 登录。也可以 显式指定 --provider openai 或 --provider codex。

export HAMP_PROVIDER_TYPE=openai
export HAMP_PROVIDER_URL=https://api.openai.com/v1
export HAMP_PROVIDER_API_KEY=<provider-api-key>
hamp-hub --provider openai

使用当前用户的 Codex OAuth 时：

hamp --feishu \
  --provider codex \
  --proxy http://127.0.0.1:7897

--data 默认使用 ~/.hamp，--auth 默认使用 ~/.codex/auth.json；仅在需要更换位置时指定。hamp 和 hamp-hub 均支持 --provider、--proxy、--data 和 --auth。

Agent 使用自动配对的 Node 凭据访问网关，并且必须已通过 /use 激活：

hamp-agent \
  --id agent-a \
  --hub wss://hub.example/ws/node

Agent 默认使用 Hub 托管的模型认证，并从 --hub 自动推导模型网关；只有 反向代理将两者发布在不同地址时才需要额外指定 --gateway。使用 Agent 电脑自己的 Codex 账号时添加 --own。

/del agent-a 会回收 managed-auth、吊销 Node 凭据并断开 Node。重新接入需要再次执行 /add agent-a。

命令行工具

命令	用途
hamp	启动本地演示环境
hamp-hub	启动 Hub 和 Web 界面
hamp-agent	启动 Agent Node
hamp-machine	启动 Machine Node
hamp-feishu	单独启动飞书适配器
hamp-mcp	启动供 AI 使用的 HAMP MCP 工具

运行 <command> --help 查看完整参数。