@hirey/hi-agent-receiver

v0.1.10

Published

2 days ago

`hi-agent-receiver` 是给“没有公网 ingress 的宿主”准备的本地常驻事件接收器。

0High
0Medium
0Low

liyongzhi

hi-agent-receiver

hi-agent-receiver 是给“没有公网 ingress 的宿主”准备的本地常驻事件接收器。

第一版只做一件事：

从 Hi 读取 durable events
把事件转交给本机宿主适配器
只有本机宿主确认收到了，才向 Hi ack

它不承载任何 Hi 业务工具，不负责搜索、直聊、meeting 业务逻辑。

第一版范围

上游来源：Hi
本地宿主适配：OpenClaw
支持的本机交付模式：
- openclaw_hooks
- openresponses

安装

普通用户的正式安装路径不应该依赖 AWS、CodeArtifact 或任何私有 registry。

这里的 Hi 指 Hirey Hi Agent Platform，不是 Hi.Events。

官方推荐安装方式：

npm install -g @hirey/hi-agent-receiver

如果你是在自动化脚本、镜像、或可复现安装链里使用它，应该固定具体版本，不要依赖隐式最新版本。

普通用户通常不需要手工先装 receiver 再自己写 config。

推荐顺序是：

先把 hi-mcp-server 挂到宿主里
通过 hi_agent_install 完成 register / activate / receiver config 生成
再由 hi_agent_doctor 检查 delivery probe

配置文件

默认配置路径会按 profile 落到稳定目录：

~/.hirey/hi-mcp/<profile>/hi-agent-receiver.json

OpenClaw 推荐的 canonical 配置路径是：

~/.openclaw/hi-mcp/openclaw-main/hi-agent-receiver.json

普通 OpenClaw 用户推荐直接复用同机 hi-mcp-server 已经持久化好的 installation state，不要手抄 client_id / client_secret。

推荐顺序：

先装好并完成 hi-mcp-server 的 hi_agent_install
固定 HI_MCP_STATE_DIR 和 HI_MCP_PROFILE
receiver 配置里优先写 identity_source.kind = "hi_mcp_profile"
再补 host_adapter 与事件消费参数

只有在没有 hi-mcp-server 本地 state 的高级场景下，才建议直接内联 identity

也可以用环境变量覆盖：

HI_AGENT_RECEIVER_CONFIG=/path/to/receiver.json

示例

{
  "profile": "openclaw-main",
  "platform_base_url": "https://your-hi-platform.example.com",
  "identity_source": {
    "kind": "hi_mcp_profile",
    "profile": "openclaw-main",
    "state_dir": "/Users/you/.openclaw/hi-mcp/openclaw-main"
  },
  "runtime": {
    "last_consumed_stream_seq": 0,
    "last_claim_lease_id": null,
    "updated_at": null
  },
  "event_source": {
    "transport": "claim",
    "claim_limit": 20,
    "claim_poll_interval_ms": 1500,
    "stream_reconnect_delay_ms": 2000,
    "ack_retry_after_ms": 30000
  },
  "host_adapter": {
    "kind": "openclaw_hooks",
    "url": "http://127.0.0.1:18789/hooks/agent",
    "auth": {
      "type": "bearer",
      "token": "replace-with-your-openclaw-hooks-token"
    },
    "config": {
      "name": "Hirey Hi Agent Platform",
      "agent_id": "main",
      "message_prefix": "[Hi Event]"
    }
  }
}

这个 example 现在和 hi_agent_install(host_kind="openclaw", enable_local_receiver=true) 生成的 receiver config 保持同一份 canonical 形状：优先使用 hi_mcp_profile，并且 OpenClaw 本地展示名固定为 Hirey Hi Agent Platform。

注意：这里的 host_adapter.url = http://127.0.0.1:18789/hooks/agent 是 完整 agent endpoint。如果 OpenClaw 侧需要启用 hooks，hooks.path 应配置成 /hooks 这个 base path，而不是 /hooks/agent；否则真实 agent 子路由会变成 /hooks/agent/agent，delivery probe 会直接返回 404.

运行时约束

receiver 启动时会先读一次当前 installation，并严格校验 delivery capabilities：

必须有 local_receiver
transport=stream 时必须有 pull_stream
transport=claim 时必须有 claim_ack

如果 declaration 不满足，就直接报错退出，不静默降级。

如果配置使用 identity_source.kind = "hi_mcp_profile"，receiver 会自动定位对应 profile 的 hi-mcp-server state 文件，并使用其中已经持久化的 installation 身份换取短期 token。hi_mcp_state 仍可用于显式文件路径场景，但不再是普通用户主路径。

运行方式

CLI 子命令

hi-agent-receiver init
hi-agent-receiver doctor
hi-agent-receiver reset
hi-agent-receiver run

init：生成 receiver config，优先绑定到现有 hi-mcp-server profile
doctor：检查配置、installation delivery capability 与当前 adapter 设置
reset：删除 receiver config
run：真正开始 claim / stream 消费循环

常驻模式

hi-agent-receiver run

单次消费模式

HI_AGENT_RECEIVER_RUN_ONCE=true hi-agent-receiver run

这个模式适合部署前 smoke test 或手动补 backlog。

事件处理顺序

`stream` 模式

先 claim 一次 backlog
再连接 Hi SSE stream
收到 envelope 后回 fetch 完整 event
本机宿主适配成功后 ack consumed
断线后重新 claim backlog，再重连 SSE

`claim` 模式

按 persisted cursor claim
顺序处理每个 event
成功才 ack consumed
失败就 ack failed 并带 retry_after_ms

OpenClaw 适配

`openclaw_hooks`

适合本机 OpenClaw 暴露了 hooks 风格入口
payload 与 gateway 的 openclaw.hooks.agent.v1 复用同一套 builder
OpenClaw hooks 需要共享 token；普通用户路径应使用 host_adapter.auth = { "type": "bearer", "token": "..." }
OpenClaw 的 hooks.path 是 base path；保持 hooks.path="/hooks"，然后把 receiver 指向完整 endpoint http://127.0.0.1:18789/hooks/agent，不要把 hooks.path 直接写成 /hooks/agent
receiver 现在优先消费每条 event 自带的 reply_route_snapshot；host_adapter.config.session_key/channel/to 只作为 installation 级 explicit default route，在事件没有 origin route 时兜到这条正式默认线程
receiver 还会拒绝 reply_route_snapshot.installation_id 明确指向其它 installation 的事件，避免同一个 agent 下多 installation 场景把 continuation 投到错误宿主
普通用户默认不要发送 sessionKey；只有在 OpenClaw 明确启用了 hooks.allowRequestSessionKey=true 时，才应额外配置 host_adapter.config.send_session_key=true

`openresponses`

适合本机 OpenClaw 或兼容入口更适合走 responses ingestion
payload 与 gateway 的 openresponses.v1 复用同一套 builder

自启动建议

macOS `launchd`

把启动命令包成 plist
工作目录指向 receiver config 所在目录
升级后只替换 package 版本并重启服务

Linux `systemd`

WorkingDirectory 指向配置目录
Restart=always
用固定版本升级，不要用 latest

npm 分发目标

当前公开包名：

@hirey/hi-agent-receiver

当前公开发布内容：

dist/
README.md
自启动说明

升级策略：

固定版本安装
升级前先停服务
替换版本后再启动
保留原 config 文件和 runtime cursor

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme