OpenClaw Integration

OpenClaw native plugin for Meego Harness integrations.

安装

如果希望让 OpenClaw agent 代为安装、配置并引导用户完成绑定，可以把 README.agent.md 交给 agent；该文件按 agent 操作流程组织。

安装前置条件：

• 已安装 OpenClaw CLI，且 openclaw --help 可正常执行。
• OpenClaw 版本需满足插件声明的兼容范围：pluginApi >= 2026.4.12。可通过 openclaw --version 查看当前版本。
• 已安装并启用 openclaw-lark，且当前 OpenClaw 环境可使用 feishu_ask_user_question 工具。插件通过该工具发送飞书交互卡片。
• 安装机器能访问可用的 npm registry，用于安装插件运行时依赖。若在公司内网或离线环境，需要先配置可用的 npm mirror / proxy。
• 运行机器能访问 Harness gateway 的 workspace OpenAPI。
• 已准备好 Harness workspace OpenAPI 根地址与 token。根地址应以 /openapi 结尾。

使用前置条件：

• OpenClaw gateway 运行中，且安装或更新插件后已执行 openclaw gateway restart。
• 已完成 Harness OpenAPI 配置。缺少配置时插件会保持 inactive，不启动 HITL SSE。
• 已在目标 OpenClaw 主 agent 会话中完成绑定，或通过 /mhh 在目标会话主动拉取一次 HITL。缺少绑定时，新 HITL 只会进入插件队列，不会发送飞书卡片。
• Harness OpenAPI token 需要有读取 open HITL、读取 HITL 详情、resolve 和 dismiss 的权限。

安装插件：

openclaw plugins install @meego-harness/openclaw-integration
openclaw gateway restart

确认插件已启用：

openclaw plugins inspect meego-harness-openclaw
openclaw plugins list --enabled

安装完成后可以用 CLI 交互式写入 Harness OpenAPI 配置：

openclaw meego-harness-openclaw setup
openclaw meego-harness-openclaw doctor --json

也可以不走 CLI setup，直接在 OpenClaw 主 agent 会话里用自然语言配置，见下方“配置 Harness OpenAPI”。

如果安装失败：

openclaw plugins doctor
openclaw plugins install @meego-harness/openclaw-integration
openclaw gateway restart

如果 inspect 能看到插件但没有开始监听 HITL，先运行 openclaw meego-harness-openclaw doctor --json，确认 OpenAPI 配置是否存在。

未发布时本地试用

如果包还没有发布，可以直接从本地仓库安装。

推荐先打本地 tarball，再安装该 tarball。这条路径最接近正式发版后的安装方式，也能避开 monorepo node_modules symlink 被 OpenClaw 安全扫描拦截的问题：

cd <repo-root>
corepack pnpm --filter @meego-harness/openclaw-integration pack --pack-destination ./dist-pack
openclaw plugins install --force ./dist-pack/meego-harness-openclaw-integration-*.tgz
openclaw gateway restart
openclaw plugins inspect meego-harness-openclaw

如果确认当前 OpenClaw 允许 link 本地目录，也可以使用 link 安装。修改代码后需要重新 build 并重启 gateway：

cd <repo-root>
corepack pnpm --filter @meego-harness/openclaw-integration build
openclaw plugins install --link ./packages/openclaw-integration
openclaw gateway restart
openclaw plugins inspect meego-harness-openclaw

本地试用时仍然需要完成配置和绑定：

openclaw meego-harness-openclaw setup
openclaw meego-harness-openclaw doctor --json

然后在目标 OpenClaw 主 agent 会话中绑定当前会话：

绑定当前会话用于接收 harness HITL 卡片

功能

该插件提供 Meego Harness 面向 OpenClaw 的通用集成入口。当前包含 hitl-notifier 能力：

• 通过 OpenClaw 主 agent 的自然语言对话配置 Harness OpenAPI 地址与 token。
• 监听 Harness OpenAPI 的 open HITL SSE。
• 当新 HITL 创建时，通过 OpenClaw 环境中的 feishu_ask_user_question 工具向已绑定会话发送飞书交互卡片。
• 通过 /mhh 主动拉取最早创建的 open HITL，并向当前会话重新发送飞书交互卡片。
• 用户提交卡片后，将结构化答案回写到 Harness OpenAPI，完成 HITL resolve 或 dismiss。

启用插件

在 OpenClaw 中安装并启用本包后，插件会注册以下工具：

• meego_harness_openclaw_configure
• meego_harness_openclaw_status
• meego_harness_openclaw_bind_session

插件还会注册 slash command：

• /mhh

插件启用后如果还没有 Harness OpenAPI 配置，会保持 inactive，不会启动 SSE 监听。

配置 Harness OpenAPI

在 OpenClaw 主 agent 会话里直接用自然语言说明配置即可，例如：

把 harness OpenAPI 配置为 https://gateway.example.com/api/workspaces/workspace-key/openapi，token 是 <token>

agent 会调用 meego_harness_openclaw_configure 写入插件 state。配置要求：

• harnessOpenapiBaseUrl 必须是 HTTP/HTTPS URL。
• URL 必须指向 workspace OpenAPI 根地址，并以 /openapi 结尾。
• token 只用于 Authorization: Bearer <token>。
• 状态输出、日志和 doctor 输出不会返回 token 明文。

配置完成后，插件会立即启动或重启 HITL SSE 监听。

绑定投递会话

配置完成后，在希望接收 HITL 飞书卡片的 OpenClaw 主 agent 会话中说：

绑定当前会话用于接收 harness HITL 卡片

agent 会调用 meego_harness_openclaw_bind_session 保存当前 OpenClaw delivery context。未绑定前，新 HITL 会进入待通知队列，不会调用 feishu_ask_user_question。

查看状态

可以在主 agent 会话中询问：

查看 harness OpenClaw 集成状态

状态工具会返回：

• 是否已配置 Harness OpenAPI。
• 当前 base URL。
• token 是否存在。
• 是否已绑定投递会话。
• HITL SSE 监听是否运行。
• 待通知队列长度。

状态不会返回 token 明文。

主动拉取 HITL

如果错过 SSE 推送，或者上一张飞书卡片已经过期，可以在目标 OpenClaw 会话中发送：

/mhh

插件会调用 GET /hitl?status=open 拉取当前 open HITL，默认选择 createdAt 最早的一条，并向当前命令所在会话发送新的飞书交互卡片。该会话也会被保存为后续 HITL 卡片投递目标。

也可以在 /mhh 后追加正整数，按 createdAt 从早到晚选择第 N 个 open HITL：

/mhh 2

使用 -1 可以选择最新创建的 open HITL：

/mhh -1

如果当前没有 open HITL，命令只返回状态提示，不会发送卡片。/mhh 不解析普通文本答案，卡片提交后的处理规则仍与 SSE 推送卡片一致。

注意：

• 命令名是 /mhh。
• /mhh 不带数字时拉取最早创建的 open HITL。
• /mhh 2 拉取按创建时间排序后的第 2 个 open HITL；序号从 1 开始。
• /mhh -1 拉取最新创建的 open HITL。
• /mhh 发送的新卡片只影响当前命令所在会话，不会更新已经发出的旧卡片。
• 卡片会展示 HITL 标题和 summary 说明，便于直接在飞书里判断要 resolve 还是 dismiss。

处理 HITL 卡片

当 Harness OpenAPI SSE 推送新 open HITL 时，插件会发送一张飞书交互卡片。卡片固定包含：

• HITL 标题与说明：来自 OpenAPI 返回的 title 和 summary。
• 处理方式：resolve 或 dismiss，默认 resolve。
• 选择项：仅当 HITL responseSpec.options 存在时展示，最多 10 个选项。
• 补充输出：自由文本输入；如果没有补充内容，填写 无。

提交卡片后的回写规则：

• resolve 且选择了选项：调用 POST /hitl/{hitlId}/resolve，传 optionValue；补充输出不是 无 时额外传 note。
• resolve 且没有选项：调用 POST /hitl/{hitlId}/resolve；补充输出不是 无 时额外传 responseText。
• dismiss：调用 POST /hitl/{hitlId}/dismiss；补充输出不是 无 时额外传 reason。

feishu_ask_user_question 当前会把卡片中的每个问题都当成必填项，且自由文本框不支持默认值。为了保留用户填写文本的能力，补充输出仍使用自由文本框；提交时 无 会被插件当成空补充处理。

插件只接受 feishu_ask_user_question 返回的结构化答案，不解析普通文本消息。

行为边界

• 初始 hitl.snapshot 只记录已有 HITL，不发送卡片。
• 后续 hitl.update 中出现的新 open HITL 才会进入通知队列。
• 同一个绑定会话同一时间只发送一个 HITL 卡片，多个 HITL 按 FIFO 排队。
• SSE 连接会每 10 分钟主动关闭并重连。
• HITL 选项超过 10 个或 label 重复时，不发送卡片，HITL 保持 open。
• OpenAPI 调用失败时不会自动反复重试，插件会记录失败并保持 HITL 原状态。

CLI

插件也提供 CLI 辅助配置：

meego-harness-openclaw setup
meego-harness-openclaw doctor

setup 会交互式写入 Harness OpenAPI 地址与 token。doctor 用于检查配置状态，不会输出 token 明文。