Star-Office-UI-Node 实战：从 0 到 1 接入 OpenClaw 的多 Agent 看板

项目地址先放这里，避免读到最后还找链接：

GitHub Node Express：github.com/wangmiaozer...
Upstream python Flask：github.com/ringhyacint...

项目预览图（可直接放掘金正文）：

多 Agent 协作里，最难排障的一件事不是模型能力，而是状态不可见。你知道任务在跑，但不知道谁卡住、谁离线、谁正在执行关键步骤。Star-Office-UI-Node 的目标很明确：把这个"黑盒协作"变成"实时可观察"。

这个项目是 Star-Office-UI 的 Node.js 复刻版，后端由 Flask 改为 Express，接口行为尽量兼容原版，方便 OpenClaw/龙虾/自研 Agent 低成本接入。

核心能力不是 UI，而是这条生命周期协议：

join-agent -> agent-push -> leave-agent

1. 本地启动

bash 复制代码

cd /Users/hfy/wm-code/Star-Office-UI-Node
pnpm install
pnpm start

默认地址：http://127.0.0.1:18791

端口占用时：PORT=18792 pnpm start

健康检查：

bash 复制代码

curl -s http://127.0.0.1:18791/health

2. API 速览（接入必须知道）

GET /health：服务健康
GET /status：主 Agent 状态
POST /set_state：设置主 Agent 状态
GET /agents：访客 Agent 列表
POST /join-agent：访客加入
POST /agent-push：状态心跳
POST /leave-agent：访客离开

状态枚举：idle / writing / researching / executing / syncing / error

兼容映射：busy -> writing，run/exec -> executing，search -> researching

3. OpenClaw 对接步骤（可直接照抄）

Step 1：启动后 join，一次拿到 agentId

bash 复制代码

curl -s -X POST http://127.0.0.1:18791/join-agent \
  -H "Content-Type: application/json" \
  -d '{
    "name": "openclaw-agent-01",
    "joinKey": "ocj_starteam02",
    "state": "idle",
    "detail": "just joined"
  }'

返回里的 agentId 必须缓存（内存或本地文件）。

Step 2：每 10~30 秒推送状态

bash 复制代码

curl -s -X POST http://127.0.0.1:18791/agent-push \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "agent_xxx",
    "joinKey": "ocj_starteam02",
    "name": "openclaw-agent-01",
    "state": "executing",
    "detail": "running task #A-129"
  }'

Step 3：进程退出时 leave

bash 复制代码

curl -s -X POST http://127.0.0.1:18791/leave-agent \
  -H "Content-Type: application/json" \
  -d '{"agentId":"agent_xxx"}'

4. 我给的生产建议（别跳过）

agent-push 增加 timeout + retry + exponential backoff。
收到 403/404 说明会话失效：停止 push，重新 join。
detail 字段标准化：任务ID | 阶段 | 动作，后续诊断会轻松很多。
在 SIGINT/SIGTERM 强制调用 leave，避免"幽灵在线"。

5. 结论

Star-Office-UI-Node 的价值不在"像素风界面"，而在它把多 Agent 状态协议沉淀成了一个可快速部署、可直接接入、可持续扩展的协作层。

如果你已经在并行跑 Agent，这类状态看板建议尽早上，不然团队越大，状态黑盒带来的沟通和排障成本越高。