@myclaw163/openclaw-clawclaw 0.1.42

package/README.md

@@ -0,0 +1,220 @@
+# openclaw-clawclaw
+
+[简体中文](./README.zh.md)
+
+OpenClaw plugin for **ClawClaw (龙虾杀)** — wraps every [`clawclaw-cli`](http://apps-hp.danlu.netease.com:41842/repository/npm-group-prod/clawclaw-cli) subcommand as a native OpenClaw tool, and ships the in-game skill (`SKILL.md`) alongside the plugin so an agent can pick up and play out of the box.
+
+## Compatibility
+
+| Plugin Version | OpenClaw Version | Node.js   | Status |
+|----------------|------------------|-----------|--------|
+| 0.1.x          | >= 2026.5.7      | >= 18     | Active |
+
+> npm **10.9.x** has an `arborist saveIdealTree` crash bug that hits this plugin's dependency tree (`Cannot read properties of undefined (reading 'spec')`). Use npm **>= 10.10**.
+
+## Prerequisites
+
+- [OpenClaw](https://docs.openclaw.ai/install) installed and `openclaw --version` works
+- Network access to the internal npm registry: `http://apps-hp.danlu.netease.com:41842/repository/npm-group-prod/`
+
+## Install
+
+A single command installs `clawclaw-cli` and the game skill into OpenClaw, without polluting your global npm.
+
+**macOS / Linux**
+
+```bash
+openclaw plugins install --dangerously-force-unsafe-install @myclaw163/openclaw-clawclaw
+```
+
+**Windows (PowerShell)**
+
+```powershell
+openclaw plugins install --dangerously-force-unsafe-install @myclaw163/openclaw-clawclaw
+```
+
+After install:
+
+- All `clawclaw_*` tools are registered with the OpenClaw runtime
+- `skills/clawclaw/SKILL.md` is injected into the OpenClaw skill index
+- `clawclaw-cli` is installed under `~/.openclaw/npm/node_modules/` and invoked via the `ccl` binary
+
+Verify:
+
+```bash
+openclaw plugins list                  # clawclaw should be enabled
+openclaw tools list | grep clawclaw    # lists every registered clawclaw_* tool
+```
+
+> `--dangerously-force-unsafe-install` is required because this plugin uses `child_process` to spawn `ccl`, which OpenClaw blocks by default.
+
+## Configure tool permissions
+
+If your agent reports `No callable tools remain after resolving explicit tool allowlist`, or the `clawclaw_*` tools are registered but invisible to the LLM, your `tools.profile` is gating them out (e.g. the `coding` profile only allows built-in `group:fs/runtime/web/sessions/memory`).
+
+> ⚠️ Do **NOT** use `tools.allow: ["clawclaw"]`. OpenClaw's pipeline applies `profile` / `allow` / agent allow as a **per-stage intersection** (narrowing). Writing `allow: ["clawclaw"]` intersects with whatever your `profile` already resolves to — and if `clawclaw_*` isn't in that profile (e.g. `coding`), the intersection collapses to empty, triggering the "No callable tools remain" error.
+>
+> Use **`tools.alsoAllow`** instead. It runs before the pipeline and **unions** with the profile's allow list, truly stacking on top of your existing profile.
+
+### Recommended: one-line setup
+
+> Requires `clawclaw-cli` ≥ 0.5.26. Earlier versions don't ship the `setup` subcommand — use the manual snippet below.
+
+`clawclaw-cli` ships with a `setup openclaw` subcommand that does dry-run diff, backup, and atomic write. It never overwrites existing fields (set-union merge):
+
+```bash
+ccl setup openclaw            # preview diff (dry-run)
+ccl setup openclaw -y         # apply, auto-backup openclaw.json.bak.<timestamp>
+ccl setup openclaw --print    # print recommended JSON only, no read/write
+```
+
+Flags: `--no-backup` skips the backup file; `--skip-plugins-allow` / `--skip-tools-allow` leaves the corresponding section untouched.
+
+### Manual: append to `~/.openclaw/openclaw.json`
+
+```json
+{
+  "plugins": {
+    "allow": ["clawclaw"],
+    "entries": {
+      "clawclaw": { "enabled": true }
+    }
+  },
+  "tools": {
+    "alsoAllow": ["clawclaw"]
+  }
+}
+```
+
+> Keep your existing `tools.profile` (`coding` / `full` / whatever you've set). `alsoAllow` stacks **on top of** the profile — it doesn't replace it. Don't add `"profile": "coding"` if you weren't already using it.
+
+### Optional: force the streaming tool for `game start`
+
+In OpenClaw the game **must** be launched via the `clawclaw_game_start` tool — it spawns `ccl game start` and injects each NDJSON event back as an agent turn. If the agent instead runs `ccl game start` directly through a raw shell/exec, the events stream into an unconsumed buffer: the agent never receives `speech_your_turn` and stays silent.
+
+To make `ccl game start` reject that raw-exec path and steer the agent back to the tool, set this env var **in the OpenClaw gateway's process environment** (requires `clawclaw-cli` ≥ 0.6.35):
+
+```bash
+CLAWCLAW_REQUIRE_STREAM_TOOL=1
+```
+
+`clawclaw_game_start` stamps `CLAWCLAW_STREAMED=1` on the child it spawns, so the legitimate path passes; a raw `ccl game start` lacks the stamp and exits non-zero with a directive pointing back to the tool.
+
+> ⚠️ Set this **only on the gateway process** (systemd unit / docker-compose `environment:` / launch script) — **not** in a global shell profile. Other hosts that legitimately run `ccl game start` directly (e.g. Claude Code's `Monitor`) must not inherit this flag, or they would be blocked too. When the flag is unset, behavior is unchanged for everyone.
+
+- `"clawclaw"` is the **plugin id** declared in the manifest. OpenClaw expands it to all entries of the plugin's `contracts.tools`, so this never has to change when tools are added or removed.
+- `tools.alsoAllow` set-unions with the profile's allow list via `mergeAlsoAllowPolicy`, stacking on top without weakening the profile's security boundary.
+- `plugins.allow` is a separate **trust** allowlist (distinct from the tool allowlist). When empty, non-bundled plugins are marked untrusted and emit warnings.
+- If `tools.sandbox.tools` is set, add `"clawclaw"` to that list too — otherwise sandboxed sessions still won't see the tools.
+
+> `openclaw plugins install` does not write your global config. This is by design — `~/.openclaw/openclaw.json` belongs to the user, and plugins must not modify it silently. Use `ccl setup openclaw` or append the snippet above.
+
+## Upgrade
+
+```bash
+# 1. Upgrade the plugin to the latest published version
+openclaw plugins install --dangerously-force-unsafe-install @myclaw163/openclaw-clawclaw@latest
+
+# 2. Restart the gateway so the long-running process loads the new build
+openclaw gateway restart
+
+# 3. Verify
+openclaw plugins doctor                # verify the plugin loaded and tools are registered
+```
+
+To pin a specific version: `openclaw plugins install ... @myclaw163/openclaw-clawclaw@0.1.10`.
+
+## Uninstall
+
+```bash
+openclaw plugins uninstall @myclaw163/openclaw-clawclaw
+```
+
+This removes the plugin and its bundled `clawclaw-cli`. Your config in `~/.openclaw/openclaw.json` is preserved — for a clean slate, also remove `"clawclaw"` from `plugins.allow` and `tools.alsoAllow`, and delete `plugins.entries.clawclaw`.
+
+## Usage
+
+Once installed and allowed, an agent can call any `clawclaw_*` tool directly. The bundled SKILL guides the LLM through joining games, taking turns, and reading events. A quick smoke test:
+
+```bash
+openclaw agent --agent main --message "Call clawclaw_state and return the JSON"
+```
+
+To discover what's available:
+
+```bash
+openclaw tools list | grep clawclaw
+ccl --help
+```
+
+Tool surface at a glance — high-frequency game actions (`state` / `do` / `events`), account & persona management, in-game memory, TTS, an event-stream pipeline that injects updates back into the session, and a `clawclaw_run` raw passthrough (gated by `confirm: true`) for one-off CLI commands.
+
+Stand-alone CLI use (without OpenClaw) is also supported:
+
+```bash
+npm install -g clawclaw-cli --registry=http://apps-hp.danlu.netease.com:41842/repository/npm-group-prod/
+ccl --help
+```
+
+## Configuration reference
+
+Under `plugins.entries.clawclaw.config` in `~/.openclaw/openclaw.json`:
+
+| Field                          | Default        | Description                                                           |
+|--------------------------------|----------------|-----------------------------------------------------------------------|
+| `cclPath`                      | (PATH lookup)  | Explicit path to the `ccl` executable                                 |
+| `workspaceDir`                 | (CLI default)  | Overrides `CLAWCLAW_WORKSPACE_DIR` (account & event directory)        |
+| `spawnTimeoutMs`               | `30000`        | Per-call timeout for each `ccl` invocation (ms)                       |
+| `streamOpenclawCli`            | (PATH lookup)  | Path to the `openclaw` CLI used by the stream subsystem for injection |
+| `streamAgentTimeoutMs`         | `180000`       | Timeout for each `openclaw agent --deliver` call                      |
+| `streamDebounceMs`             | `300`          | Debounce window for batching stream lines                             |
+| `streamMinIntervalMs`          | `1000`         | Minimum interval between two injections                               |
+| `streamMaxBatchLines`          | `150`          | Max lines merged into a single injection                              |
+| `streamMaxQueueLines`          | `1000`         | Per-stream queue cap (backpressure)                                   |
+| `streamMaxInstances`           | `8`            | Max concurrent streams                                                |
+| `streamEmitLifecycleEvents`    | `true`         | Inject `[STREAM_EXIT]` / `[STREAM_STOPPED]` sentinel lines            |
+
+## Troubleshooting
+
+**`No callable tools remain after resolving explicit tool allowlist`**
+Your `tools.profile` is gating out plugin tools. See [Configure tool permissions](#configure-tool-permissions) — use `tools.alsoAllow`, not `tools.allow`.
+
+**`clawclaw_*` tools registered but LLM can't see them**
+Same root cause as above. Run `ccl setup openclaw --print` to inspect the recommended config diff.
+
+**`Cannot read properties of undefined (reading 'spec')` during install**
+You're on npm 10.9.x. Upgrade to npm >= 10.10.
+
+**`ccl: command not found` after install**
+The plugin uses `~/.openclaw/npm/node_modules/.bin/ccl` internally; you don't need `ccl` on your global PATH for the plugin to work. For standalone CLI use, install via `npm install -g clawclaw-cli`.
+
+**`clawclaw_monitor` hits a 30s timeout**
+By design, `clawclaw_monitor` streams continuously until `game_over`. For long-running observation, use the `Stream` tools (`clawclaw_event_stream_start`) which run in the background and inject events back into the session. For a one-shot snapshot of current state, pass `once: true`.
+
+**`plugins.allow is empty` warning from `openclaw plugins doctor`**
+Add `"clawclaw"` to `plugins.allow`, or run `ccl setup openclaw -y` which does it for you.
+
+## Development
+
+```bash
+git clone ssh://git@gitlab.leihuo.netease.com:32200/claw-kill/openclaw-clawclaw.git
+cd openclaw-clawclaw
+npm install                      # pulls deps; postinstall syncs SKILL.md
+npm run sync-manifest            # syncs tool names from ccl _schema into the manifest
+npm run build                    # tsdown → dist/index.mjs (+ .d.mts)
+npm run typecheck && npm test
+```
+
+Install the local source into OpenClaw for live testing:
+
+```bash
+openclaw plugins install --link --dangerously-force-unsafe-install /path/to/openclaw-clawclaw
+openclaw gateway restart
+openclaw plugins doctor
+```
+
+When `clawclaw-cli` adds a new subcommand, `npm run sync-manifest` regenerates the auto-generated tool list from `ccl _schema` — no changes to `src/index.ts` are required.
+
+## License
+
+[MIT](LICENSE)

package/README.zh.md

@@ -0,0 +1,206 @@
+# openclaw-clawclaw
+
+[English](./README.md)
+
+OpenClaw 的 **ClawClaw(龙虾杀)** 插件 —— 将 [`clawclaw-cli`](http://apps-hp.danlu.netease.com:41842/repository/npm-group-prod/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](https://docs.openclaw.ai/install),`openclaw --version` 可正常工作
+- 可访问内网 npm 私服:`http://apps-hp.danlu.netease.com:41842/repository/npm-group-prod/`
+
+## 安装
+
+一条命令把 `clawclaw-cli` 和游戏 skill 都装进 OpenClaw,不污染全局 npm。
+
+**macOS / Linux**
+
+```bash
+openclaw plugins install --dangerously-force-unsafe-install @myclaw163/openclaw-clawclaw
+```
+
+**Windows (PowerShell)**
+
+```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` 子进程被工具调用
+
+验证:
+
+```bash
+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 合并):
+
+```bash
+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`
+
+```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` 或手动追加以上片段即可。
+
+## 升级
+
+```bash
+# 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/openclaw-clawclaw@0.1.10`。
+
+## 卸载
+
+```bash
+openclaw plugins uninstall @myclaw163/openclaw-clawclaw
+```
+
+会一并移除插件和它捆绑的 `clawclaw-cli`。`~/.openclaw/openclaw.json` 里的配置会保留 —— 如需彻底清理,把 `"clawclaw"` 从 `plugins.allow` 和 `tools.alsoAllow` 里移除,并删除 `plugins.entries.clawclaw` 段。
+
+## 使用
+
+安装并放行后,agent 即可直接调用任意 `clawclaw_*` 工具。捆绑的 SKILL 会引导 LLM 完成加入游戏、出招、读事件等流程。冒烟测试:
+
+```bash
+openclaw agent --agent main --message "Call clawclaw_state and return the JSON"
+```
+
+查看可用工具:
+
+```bash
+openclaw tools list | grep clawclaw
+ccl --help
+```
+
+工具覆盖范围 —— 高频游戏动作(`state` / `do` / `events`)、账号与 persona 管理、局内记忆、TTS、把事件回流到 session 的 stream 子系统,以及一个原始透传工具 `clawclaw_run`(`confirm: true` 必填)用于临时跑任意 CLI 命令。
+
+也可以独立使用 CLI(不依赖 OpenClaw):
+
+```bash
+npm install -g clawclaw-cli --registry=http://apps-hp.danlu.netease.com:41842/repository/npm-group-prod/
+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` 自动写入。
+
+## 开发
+
+```bash
+git clone ssh://git@gitlab.leihuo.netease.com: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 用于联调:
+
+```bash
+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](LICENSE)

package/dist/index.d.mts

@@ -0,0 +1,15 @@
+//#region src/index.d.ts
+/**
+ * openclaw-clawclaw — OpenClaw plugin entry
+ * ─────────────────────────────────────────
+ * 工具组成:
+ *   - typed `clawclaw_*` 工具:大部分由 `ccl _schema` 元数据自动生成;
+ *     少数(如 clawclaw_do)手写覆盖以补足 schema 表达不出的约束(如 oneOf)。
+ *   - clawclaw_run:raw passthrough,仅在 typed 工具未覆盖时使用,需 confirm:true。
+ *
+ * 对 clawclaw-cli 升级的兼容性:新增 `ccl <cmd>` 子命令时,只需重启 gateway,
+ * 自动生成的工具会立刻暴露,无需重新发布插件。
+ */
+declare const _default: any;
+//#endregion
+export { _default as default };