clawwatch-openclaw-plugin

本仓库提供两部分能力：

Native OpenClaw 插件（openclaw.plugin.json + dist/index.js）：在 Gateway 内注册后台 Service，按配置拉起 clawwatch-agent run（自适应上报）。
独立 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 循环。

前置条件

项目	要求
Node.js	≥ 22（安装本 npm 包 / 作为 OpenClaw 插件开发时）；裸跑 `node src/agent.mjs` 可仍用 18+
ClawWatch Worker	插件与默认 CLI 使用固定地址 `https://cw.osglab.win`；自建 Worker 时请在命令行对 `clawwatch-agent` 显式传入 `--base`
ClawWatch 账号与 App	生成 link token 或（旧流程）扫码绑定码完成绑定

获取代码（私有仓库）

若本仓库为 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，仍可：

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

发布到 ClawHub（维护者）

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

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

上报字段清单

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

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

字段	类型	说明	Worker / D1
`node_id`	string	节点 ID（必填）	用于路由，不写 `snapshots` 列
`status`	string	如 `"online"`	`snapshots.status`
`today_tokens`	number	今日 token 总计	`snapshots.today_tokens`
`input_tokens`	number	今日输入 token	`snapshots.input_tokens`
`output_tokens`	number	今日输出 token	`snapshots.output_tokens`
`sessions`	number	总会话数（也可用 `session_count`）	`snapshots.session_count`
`active_sessions`	number	活跃会话（也可用 `active_session_count`）	`snapshots.active_session_count`
`requests_processed`	number	今日请求/调用计数	`snapshots.requests_processed`
`requests_failed`	number	失败计数	`snapshots.requests_failed`
`tokens_per_second`	number	今日 token ÷ 运行时间	`snapshots.tokens_per_second`
`cpu_load`	number	CPU 负载 %	`snapshots.cpu_load`
`mem_usage`	number	内存 MB	`snapshots.mem_usage`
`gpu_load`	number	GPU 负载 %	`snapshots.gpu_load`
`vram_usage`	number	显存用量	`snapshots.vram_usage`
`disk_usage`	number	磁盘使用 %	`snapshots.disk_usage`
`uptime_seconds`	number	运行时间（秒）	`snapshots.uptime_seconds`
`api_latency`	number	到 Worker 的 RTT（ms），测不到时可省略	`snapshots.api_latency`
`active_model`	string	当前模型	`snapshots.active_model`
`agents_summary`	string 或数组	多 Agent 摘要 JSON	`snapshots.agents_summary`（TEXT）
`task_status` / `task_desc` / `step_progress` / `need_approval`	混合	任务与审批态（若 `openclaw status --json` 可解析）	对应 `snapshots` 列
`daily_cost` / `token_usage` / `api_balance`	number	成本类（可选自定义上报）	对应列
`version` / `ip_address` / `region` / `gpu_model`	string	节点环境	`nodes` 表，非 `snapshots`

未列出的键仍会出现在签名的 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。

故障排查

现象	处理
`Missing --base`	传入 `--base <URL>` 或设置 `CLAWWATCH_BASE_URL`
`Invalid state file; run setup first`	先执行 `setup`，再 `bind` / `run`
`report` / `claim` 返回 4xx	检查 Worker 地址、是否已 `bind`、link token 是否过期
私有仓库 `git clone` 失败	使用 `gh auth login`、SSH key 或带 `repo` 权限的 PAT

开发

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

环境变量

变量	说明
`CLAWWATCH_BASE_URL`	Worker 根地址；与 `--base` 二选一（不要尾部 `/`）
`CLAWWATCH_STATE`	凭据文件路径；默认 `~/.clawwatch/agent.json`
`CLAWWATCH_PAYLOAD_JSON`	JSON 对象，自定义上报字段；不要包含 `node_id`（会自动注入）。未设置时使用内置默认占位字段

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

ClawWatch OpenClaw Plugin

clawwatch-openclaw-plugin

OpenClaw 用户：安装与配置

前置条件

获取代码（私有仓库）

安装指南

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

2. 将 CLI 加入 PATH

3. 验证安装

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

发布到 ClawHub（维护者）

上报字段清单

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

使用流程

1. 首次登记节点（`setup`）

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

3. 常驻上报（`run`）

自定义快照示例

API 与契约

故障排查

开发

许可证

环境变量

Source and release

Source repository

Source commit

Install command

Metadata

Compatibility

ClawWatch OpenClaw Plugin

clawwatch-openclaw-plugin

OpenClaw 用户：安装与配置

前置条件

获取代码（私有仓库）

安装指南

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

2. 将 CLI 加入 PATH

3. 验证安装

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

发布到 ClawHub（维护者）

上报字段清单

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

使用流程

1. 首次登记节点（setup）

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

3. 常驻上报（run）

自定义快照示例

API 与契约

故障排查

开发

许可证

环境变量

Source and release

Source repository

Source commit

Install command

Metadata

Compatibility

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

1. 首次登记节点（`setup`）

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

3. 常驻上报（`run`）