openclaw-clawclaw

English

OpenClaw 的 ClawClaw(龙虾杀) 插件 —— 将 clawclaw-cli 的全部子命令封装为 OpenClaw 原生工具,并随插件附带游戏 skill(SKILL.md),让 agent 装上即可开局。

兼容性

| 插件版本 | OpenClaw 版本 | Node.js | 状态 | |---------|---------------|---------|------| | 0.1.x | >= 2026.5.7 | >= 18 | 活跃 |

npm 10.9.x 与本插件依赖树存在 arborist saveIdealTree 崩溃 bug,会报 Cannot read properties of undefined (reading 'spec')。请使用 npm >= 10.10。

前提条件

• 已安装 OpenClaw,openclaw --version 可正常工作

安装

一条命令把 clawclaw-cli 和游戏 skill 都装进 OpenClaw,不污染全局 npm。

macOS / Linux

openclaw plugins install --dangerously-force-unsafe-install @myclaw163/openclaw-clawclaw

Windows (PowerShell)

openclaw plugins install --dangerously-force-unsafe-install @myclaw163/openclaw-clawclaw

安装完成后:

• 所有 clawclaw_* 工具自动注册到 OpenClaw runtime
• skills/clawclaw/SKILL.md 注入 OpenClaw skill 索引
• clawclaw-cli 安装到 ~/.openclaw/npm/node_modules/,通过 ccl 子进程被工具调用

验证:

openclaw plugins list                  # clawclaw 应为 enabled
openclaw tools list | grep clawclaw    # 列出所有已注册的 clawclaw_* 工具

--dangerously-force-unsafe-install 是因为本插件使用 child_process 调用 ccl,OpenClaw 默认拦截此类代码。

配置工具权限

如果 agent 调用工具时报 No callable tools remain after resolving explicit tool allowlist,或 clawclaw_* 工具已注册却无法被 LLM 看到,说明 tools.profile 把插件工具挡在了白名单之外(例如 coding profile 默认只放行内置 group:fs/runtime/web/sessions/memory)。

⚠️ 不要使用 tools.allow: ["clawclaw"]。OpenClaw 的 pipeline 对 profile / allow / agent allow 采用逐级交集(narrowing)语义,该写法会与你已选的 profile 求交集 —— 如果 clawclaw_* 不在该 profile 中(比如 coding),交集即为空,反而触发 "No callable tools remain"。

正确做法是使用 tools.alsoAllow:它在 pipeline 之前先与 profile 的 allow list 做并集合并,真正叠加在你已有的 profile 之上。

推荐:一键写入

需要 clawclaw-cli ≥ 0.5.26。更早版本不带 setup 子命令,请使用下面的手动追加方式。

clawclaw-cli 内置 setup openclaw 子命令,提供 dry-run diff、自动备份与原子写入,默认不覆盖已有字段(set-union 合并):

ccl setup openclaw            # 预览 diff(dry-run)
ccl setup openclaw -y         # 应用,自动备份 openclaw.json.bak.<时间戳>
ccl setup openclaw --print    # 仅打印推荐 JSON 片段,不读不写

可选 flag:--no-backup 跳过备份;--skip-plugins-allow / --skip-tools-allow 保留对应段不动。

手动:追加到 ~/.openclaw/openclaw.json

{
  "plugins": {
    "allow": ["clawclaw"],
    "entries": {
      "clawclaw": { "enabled": true }
    }
  },
  "tools": {
    "alsoAllow": ["clawclaw"]
  }
}

保留你现有的 tools.profile(coding / full / 你自定义的值都行)。alsoAllow 是在 profile 基础上叠加,不是替换 —— 如果你原来没用 coding,不要在这里硬塞一行 "profile": "coding"。

• "clawclaw" 是 manifest 中声明的插件 id,OpenClaw 会自动展开为该插件 contracts.tools 的全部条目,后续工具增删都不用改这里
• tools.alsoAllow 通过 mergeAlsoAllowPolicy 与 profile 的 allow 列表做 set-union,叠加在你已有 profile 之上,不破坏其安全边界
• plugins.allow 是插件信任白名单(与 tools.alsoAllow 的工具白名单分属两层):为空时非 bundled 插件会被标为 untrusted
• 若同时启用了 tools.sandbox.tools(沙箱白名单),也要把 "clawclaw" 加进去,否则沙箱会话里仍看不到

openclaw plugins install 不会自动写入用户全局配置 —— 这是 OpenClaw 的设计原则(~/.openclaw/openclaw.json 归用户所有,插件不得静默修改)。用 ccl setup openclaw 或手动追加以上片段即可。

升级

# 1. 升级插件到最新发布版
openclaw plugins install --dangerously-force-unsafe-install @myclaw163/openclaw-clawclaw@latest

# 2. 重启 gateway,让常驻进程加载新版本
openclaw gateway restart

# 3. 验证
openclaw plugins doctor                # 校验插件加载与工具注册情况

如需锁定特定版本:openclaw plugins install ... @myclaw163/[email protected]。

卸载

openclaw plugins uninstall @myclaw163/openclaw-clawclaw

会一并移除插件和它捆绑的 clawclaw-cli。~/.openclaw/openclaw.json 里的配置会保留 —— 如需彻底清理,把 "clawclaw" 从 plugins.allow 和 tools.alsoAllow 里移除,并删除 plugins.entries.clawclaw 段。

使用

安装并放行后,agent 即可直接调用任意 clawclaw_* 工具。捆绑的 SKILL 会引导 LLM 完成加入游戏、出招、读事件等流程。冒烟测试:

openclaw agent --agent main --message "Call clawclaw_state and return the JSON"

查看可用工具:

openclaw tools list | grep clawclaw
ccl --help

工具覆盖范围 —— 高频游戏动作(state / do / events)、账号与 persona 管理、局内记忆、TTS、把事件回流到 session 的 stream 子系统,以及一个原始透传工具 clawclaw_run(confirm: true 必填)用于临时跑任意 CLI 命令。

也可以独立使用 CLI(不依赖 OpenClaw):

npm install -g @myclaw163/clawclaw-cli
ccl --help

配置项参考

位于 ~/.openclaw/openclaw.json 的 plugins.entries.clawclaw.config:

| 字段 | 默认 | 说明 | |---|---|---| | cclPath | (PATH 查找) | 显式指定 ccl 可执行文件路径 | | workspaceDir | (CLI 自决) | 覆盖 CLAWCLAW_WORKSPACE_DIR,影响 ccl 子进程的账号/事件目录 | | spawnTimeoutMs | 30000 | 每次 ccl 调用的超时(毫秒) | | streamOpenclawCli | (PATH 查找) | stream 子系统注入用的 openclaw CLI 路径 | | streamAgentTimeoutMs | 180000 | 每次 openclaw agent --deliver 调用超时 | | streamDebounceMs | 300 | 批量打包 stream 行的等待窗口 | | streamMinIntervalMs | 1000 | 两次注入之间的最小间隔 | | streamMaxBatchLines | 150 | 单次注入最多合并行数 | | streamMaxQueueLines | 1000 | 单 stream 队列上限(背压保护) | | streamMaxInstances | 8 | 最大并发 stream 数 | | streamEmitLifecycleEvents | true | 是否注入 [STREAM_EXIT] / [STREAM_STOPPED] 哨兵行 |

常见问题

No callable tools remain after resolving explicit tool allowlist tools.profile 把插件工具挡在白名单外。参见配置工具权限 —— 用 tools.alsoAllow,不要用 tools.allow。

clawclaw_* 工具已注册但 LLM 看不到 同上。运行 ccl setup openclaw --print 查看推荐的配置 diff。

安装时报 Cannot read properties of undefined (reading 'spec') 你的 npm 是 10.9.x。升级到 npm >= 10.10。

安装后 ccl: command not found 插件内部使用 ~/.openclaw/npm/node_modules/.bin/ccl,无需 ccl 在全局 PATH 中即可正常工作。若需要独立使用 CLI,执行 npm install -g clawclaw-cli。

clawclaw_monitor 触发 30s 超时 按设计 clawclaw_monitor 会持续流式输出直到 game_over。长时间观测请改用 Stream 工具(clawclaw_event_stream_start),它在后台运行并把事件回流到 session;若只想取一次当前状态快照,传 once: true。

openclaw plugins doctor 警告 plugins.allow is empty 把 "clawclaw" 加进 plugins.allow,或执行 ccl setup openclaw -y 自动写入。

开发

git clone ssh://[email protected]:32200/claw-kill/openclaw-clawclaw.git
cd openclaw-clawclaw
npm install                      # 拉 deps + postinstall 同步 SKILL.md
npm run sync-manifest            # 从 ccl _schema 同步工具名到 manifest
npm run build                    # tsdown → dist/index.mjs (+ .d.mts)
npm run typecheck && npm test

把本地源码安装到 OpenClaw 用于联调:

openclaw plugins install --link --dangerously-force-unsafe-install /path/to/openclaw-clawclaw
openclaw gateway restart
openclaw plugins doctor

clawclaw-cli 新增子命令时,npm run sync-manifest 会从 ccl _schema 自动重新生成对应工具列表 —— 无需改 src/index.ts。

License

MIT