clawwatch-openclaw-plugin

本仓库提供两部分能力：

1. Native OpenClaw 插件（openclaw.plugin.json + dist/index.js）：在 Gateway 内注册后台 Service，按配置拉起 clawwatch-agent run（自适应上报）。
2. 独立 CLI clawwatch-agent（src/agent.mjs）：可在任意 Node 环境执行 setup / bind / run，向 ClawWatch Worker 上报遥测；HMAC 与 ClawWatchServer README 一致。

与 ClawWatchServer、ClawWatchiOS 分仓维护；Issue / PR 请在本仓库提交。

OpenClaw 用户：安装与配置

• 兼容：本包 package.json 中 openclaw.compat / openclaw.build 以 OpenClaw 2026.3.1 为最低基线（低于此前的 2026.4.14 要求）；请使用满足 pluginApi 的 Gateway（详见 Building Plugins）。
• Node：开发与作为插件安装的环境需 Node ≥ 22（engines.node）。仅运行已编译 CLI 的极简场景仍可用 Node 18+ 直接执行 node src/agent.mjs，但 npm install 本包会按 engines 校验。

安装示例（任选其一）：

# 自 ClawHub（发布后）
openclaw plugins install clawhub:clawwatch-openclaw-plugin

# 或本地路径开发（不拷贝）
openclaw plugins install -l /path/to/clawwatch-openclaw-plugin

在 OpenClaw 配置中为插件 clawwatch（与 openclaw.plugin.json 的 id 一致）启用即可；Worker 根地址已固定为 https://cw.osglab.win，无需再填 worker_base_url。可选 state_path 指定状态文件路径（JSON5 示例）：

{
  plugins: {
    enabled: true,
    entries: {
      clawwatch: {
        enabled: true,
        config: {
          // state_path: "/optional/custom/agent.json",
        },
      },
    },
  },
}

修改配置后执行 openclaw gateway restart（或依赖你当前的 config watch 行为）。后台服务会在启动时 spawn 本包内的 src/agent.mjs run --base https://cw.osglab.win，并把 state_path 映射为环境变量 CLAWWATCH_STATE（若设置）。

说明：setup / bind 仍建议通过 clawwatch-agent CLI（全局安装或 npx / node src/agent.mjs）在节点上执行一次；Gateway Service 主要负责 已登记且绑定后 的常驻 run 循环。

前置条件

获取代码（私有仓库）

若本仓库为 GitHub Private，克隆时需已登录 GitHub：

• HTTPS（推荐配合 gh 或凭据管理器）

  gh auth login   # 若尚未登录
  git clone https://github.com/hkgood/clawwatch-openclaw-plugin.git
  

  或使用 Personal Access Token 作为密码（需 repo 权限）。

• SSH

  git clone git@github.com:hkgood/clawwatch-openclaw-plugin.git
  

  需本机已配置 SSH key 并添加到 GitHub。

cd clawwatch-openclaw-plugin

安装指南

1. 安装依赖（开发/本地运行）

npm install

本包无第三方运行时依赖，安装步骤主要用于校验 package.json 与后续 npm link / npm install -g。

2. 将 CLI 加入 PATH

任选其一：

全局安装（推荐在生产节点）

npm install -g .

完成后应能直接执行：

clawwatch-agent setup --base https://你的-worker.workers.dev

仅当前仓库可执行（开发调试）

npm link
# 或不用 link，始终使用：
node src/agent.mjs setup --base https://你的-worker.workers.dev

3. 验证安装

which clawwatch-agent   # 若使用全局安装
node src/agent.mjs      # 无参数时应打印 Usage 并以非零退出（预期行为）

预期 Usage 提示：

Usage: clawwatch-agent <setup|bind|run> --base <workerOrigin> [link_token]

4. 与 OpenClaw 集成（无 Gateway / 仅进程保活）

若不使用上述 Native 插件 Service，仍可：

1. 将仓库放到任意路径，npm install -g . 或 npm link；
2. 用 LaunchAgent（macOS）或 systemd（Linux）对 clawwatch-agent run --base … 保活。

发布到 ClawHub（维护者）

1. 安装 CLI：npm i -g clawhub，并 clawhub login。
2. 在本仓库执行 npm run build，再 clawhub package publish . --dry-run，确认无报错后去掉 --dry-run 正式发布。
3. 详见官方 ClawHub 与仓库内 CONTRIBUTING.md。

凭据安全：setup 写入的 ~/.clawwatch/agent.json（或 CLAWWATCH_STATE）含节点密钥；勿提交到 Git；本包在写入后会尝试 chmod 600（POSIX）。

上报字段清单

插件 JSON 里会出现的键（buildPayloadFromEnv / CLAWWATCH_PAYLOAD_JSON）

下表区分 Worker 会写入 D1 snapshots 的列、只更新 nodes 元数据、以及 当前不入库（由 Worker 忽略） 的键，避免与「表结构一一对应」混淆。

未列出的键仍会出现在签名的 JSON body 中，但 Worker 不会写入 D1；自定义字段请通过 CLAWWATCH_PAYLOAD_JSON 只使用上表已支持列，或扩展 Server 后再用。

使用流程

1. 首次登记节点（setup）

clawwatch-agent setup --base https://你的-worker.workers.dev
# 或: node src/agent.mjs setup --base ...

凭据写入 ~/.clawwatch/agent.json（或由 CLAWWATCH_STATE 指定）。

2. 与手机账号绑定（bind）

在 ClawWatch App 中生成 link token，在节点执行：

clawwatch-agent bind --base https://你的-worker.workers.dev "<粘贴的_token>"

3. 常驻上报（run）

clawwatch-agent run --base https://你的-worker.workers.dev

未绑定前 Worker 会拒绝 report；进程会以 report_policy 为主循环等待绑定。

自定义快照示例

export CLAWWATCH_PAYLOAD_JSON='{"status":"online","cpu_load":12.5,"mem_usage":8192}'
clawwatch-agent run --base https://你的-worker.workers.dev

API 与契约

与 ClawWatch Worker 的 HMAC、路径约定见 Server 仓库：ClawWatchServer README。

故障排查

开发

npm install
npm run typecheck
npm run build
node src/agent.mjs
# 子命令: setup | bind | run

本仓库不把 openclaw 写入 devDependencies：其依赖树会通过 git@github.com:... 拉私有/特殊仓库，在未配置 SSH 时会导致 npm install 失败。插件在 Gateway 进程内加载时由 OpenClaw 提供真实模块；本地编译使用 types/openclaw-plugin-sdk.d.ts 类型桩。

许可证

MIT

环境变量

延迟与 OpenClaw 状态：run 循环在每次上报前会对 GET {base}/api/v1/config 测 RTT，写入 api_latency（毫秒）。若本机存在 openclaw status --json，会尝试解析并合并 task_status / task_desc / step_progress / need_approval 及队列深度等字段（均为尽力而为，CLI 不可用时静默跳过）。