OpenClaw HTTP Agent 桥接

它解决什么问题

很多团队把 OpenClaw 跑在容器或 Pod 里, agent 本身具备文件读写、shell 执行、消息发送等能力, 但外部服务很难直接调用它。直接在容器里跑 openclaw agent CLI 意味着每次调用都要冷启动, 实测 embedded 启动约 90 秒, 还容易把多个请求串进同一个 session, 互相污染。

agent-easy-http 的思路是: 不自己实现一套 agent 执行引擎, 而是把 OpenClaw 原生的 /hooks/agent 端点包一层薄代理, 让外部系统通过 HTTP(S) POST 一个自然语言 message, agent 自己决定调用哪些 Skill。v3.0 架构(内部代号, 与发布版本号 1.0.x 是两个维度)相对 v2.0 的改动集中在执行引擎和 session 隔离: hook 触发是毫秒级, 每个请求自动分配独立的 hook: session, 主会话不受干扰。

核心能力与关键步骤

• API Key 鉴权: 所有接口要求 X-API-Key, init wizard 生成 32 字符随机 key。
• 两个入口: /agent/run 接收开放式 message, 由 agent 自行决策; /skills/{name}/run 直接触发指定 skill, 自动注入 SKILL.md 并做加固。
• 结果轮询: /agent/run 立即返回 run_id, 客户端用 /result/{run_id} 轮询, 实测触发后 4-6 秒结果可读, 建议 4 秒后首次查询、每 1.5 秒轮询。
• Prompt 注入加固: 用户 message 被分隔符和反注入指令包裹; OpenClaw 内层还会加 EXTERNAL_UNTRUSTED_CONTENT 包装。
• 技能管控: deny_skills 黑名单(推荐拒掉有副作用或会对外发消息的 skill), expose_skills 白名单(空=全暴露)。
• Agent 路由: default_agent_id 设默认路由, allowed_agent_ids 控制调用方可指定的 agent 范围。
• watchdog: 每 30 秒检查 server, 挂了自动重启; hooks 配置被外部覆盖时也会触发 init_wizard 修复。
• 传输安全: 默认 HTTP 明文, 需要时跑 gen_cert.py --san auto 生成 SAN 证书切到 HTTPS。

适用边界与注意点

这个 skill 本质是把一个具备本机能力的 agent 暴露成远程控制面, 风险边界要清楚:

• /agent/run 是通用入口, 任何通过鉴权的调用方都能发任意 prompt, 包括发消息、改数据等有副作用的操作。端口只能对可信调用方开放。
• 默认 HTTP 不加密, X-API-Key、prompt、执行结果均明文传输。仅 localhost 或可信内网可接受, 监听 0.0.0.0 或跨主机务必开 HTTPS, 不要在生产用 curl -k 跳过证书校验。
• init / watchdog 会写入并自愈 ~/.openclaw/openclaw.json 的 hooks 配置, 这是平台级改动; 管理员手动回退后 watchdog 可能重新应用, 属于预期的持久化行为。
• GET /agents 会返回内部所有 agent 的 ID 和名称, API key 泄露时可被枚举。不需要动态查询时, 把 allowed_agent_ids 设为固定白名单而非 ["*"]。
• allowRequestSessionKey=true 是 OpenClaw 全局配置, 影响所有 /hooks/agent 调用方, 不只本 skill。受 allowedSessionKeyPrefixes=["hook:"] 限制, 外部只能用 hook: 前缀, 无法污染 webui/cron 等 session。

另一个定位问题: 如果你只需要"让外部直接跑某个指定 skill 并传结构化参数", 而不是让 agent 自由决策, skill-to-http-flash 更合适; 两者互补不重叠。