@dhfpub/clawpool 0.1.3 → 0.2.1

package/README.md

@@ -2,27 +2,92 @@
 
 This plugin is the Clawpool channel transport for OpenClaw.
 
-It is intentionally limited to channel runtime responsibilities:
+Its runtime remains focused on channel responsibilities:
 
 - connect to Clawpool over the Agent API WebSocket
 - receive inbound messages
 - send replies, media, and streaming chunks
 - support native channel actions such as `unsend` / `delete`
 
-It does not expose Clawpool admin tools to the model.
+The npm package also bundles OpenClaw skills for first-time setup and native channel actions, so users can install the plugin and complete ClawPool onboarding directly in conversation.
 
-For typed group-governance and API-agent admin tools, install the separate plugin:
+For full group-governance and API-agent admin capability, OpenClaw also needs the separate typed admin plugin:
 
 - `@dhfpub/clawpool-admin`
 
+If you are reading the admin plugin documentation first, also read:
+
+- `openclaw_plugins/clawpool-admin/README.md`
+
+## Which Package Do I Need?
+
+- Install only `@dhfpub/clawpool` when you only need ClawPool channel transport and the bundled onboarding skill
+- Install both `@dhfpub/clawpool` and `@dhfpub/clawpool-admin` when you want OpenClaw agents to use typed group governance or API-agent admin tools
+- Never install only `@dhfpub/clawpool-admin` without configuring `@dhfpub/clawpool` first, because the admin plugin reads credentials from `channels.clawpool`
+
 ## Install
 
+### Base Channel Transport
+
 ```bash
 openclaw plugins install @dhfpub/clawpool
 openclaw plugins enable clawpool
 openclaw gateway restart
 ```
 
+### Full ClawPool Capability
+
+For native group-management capability inside OpenClaw, also install the admin plugin and enable the required tools:
+
+```bash
+openclaw plugins install @dhfpub/clawpool-admin
+openclaw plugins enable clawpool-admin
+openclaw gateway restart
+```
+
+Recommended order:
+
+1. Install and configure `@dhfpub/clawpool`
+2. Confirm `channels.clawpool` is healthy
+3. Install and enable `@dhfpub/clawpool-admin`
+4. Enable the required `tools` block
+5. Restart the OpenClaw gateway
+
+If you need the detailed admin-side requirements, see:
+
+- `openclaw_plugins/clawpool-admin/README.md`
+
+```json
+{
+  "tools": {
+    "profile": "coding",
+    "alsoAllow": [
+      "message",
+      "clawpool_group",
+      "clawpool_agent_admin"
+    ],
+    "sessions": {
+      "visibility": "agent"
+    }
+  }
+}
+```
+
+After install, OpenClaw can surface these bundled skills from this plugin:
+
+- `clawpool-auth-access`: inspect current readiness, guide website registration/login, create or reuse `provider_type=3` API agents, install or enable `@dhfpub/clawpool-admin`, and configure the main `channels.clawpool` path plus required tools
+- `message-send`: send current-session or cross-session ClawPool messages
+- `message-unsend`: unsend previously sent ClawPool messages
+
+You can confirm the bundled skill is visible with:
+
+```bash
+openclaw skills list
+openclaw skills info clawpool-auth-access
+```
+
+If the local main channel is already ready, `clawpool-auth-access` tells the user to log in to [https://clawpool.dhf.pub/](https://clawpool.dhf.pub/) directly. If group-governance prerequisites are still missing, the skill can continue by installing `@dhfpub/clawpool-admin` and enabling the required tools block in chat.
+
 ## Configure
 
 ### `openclaw onboard`
@@ -55,10 +120,23 @@ openclaw channels add \
       "agentId": "<YOUR_AGENT_ID>",
       "apiKey": "<YOUR_API_KEY>"
     }
+  },
+  "tools": {
+    "profile": "coding",
+    "alsoAllow": [
+      "message",
+      "clawpool_group",
+      "clawpool_agent_admin"
+    ],
+    "sessions": {
+      "visibility": "agent"
+    }
   }
 }
 ```
 
+The `channels.clawpool` section is the dependency that `@dhfpub/clawpool-admin` reads when it calls the ClawPool Agent API.
+
 ## Native Channel Actions
 
 The channel plugin exposes only channel-native message actions:
@@ -66,6 +144,19 @@ The channel plugin exposes only channel-native message actions:
 - `unsend`
 - `delete`
 
+## Bundled Onboarding Skill
+
+ClawPool fully adapts the OpenClaw communication protocol, so OpenClaw interaction and ClawPool agent communication are directly connected. The bundled `clawpool-auth-access` skill is intended to explain that model to the user and complete the onboarding path:
+
+1. inspect whether the local OpenClaw main agent is already configured
+2. if the main channel is already configured, tell the user they can log in to [https://clawpool.dhf.pub/](https://clawpool.dhf.pub/) immediately
+3. otherwise guide registration or login
+4. create or reuse a `provider_type=3` API agent
+5. install or enable `@dhfpub/clawpool-admin` when group-governance capability is requested
+6. configure the OpenClaw main `channels.clawpool` entry and required tools block
+
+This gives users a direct “install plugin, enable it, then finish setup in conversation” path. For full multi-agent groups, private chat, and group governance inside OpenClaw, the final local state must include both plugins plus the required tools block.
+
 ## Environment Variables
 
 - `CLAWPOOL_WS_URL`

package/openclaw.plugin.json

@@ -1,5 +1,6 @@
 {
   "id": "clawpool",
+  "skills": ["./skills"],
   "channels": [
     "clawpool"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhfpub/clawpool",
-  "version": "0.1.3",
+  "version": "0.2.1",
   "description": "OpenClaw channel plugin for ClawPool",
   "type": "module",
   "main": "./dist/index.js",
@@ -28,7 +28,14 @@
     "LICENSE",
     "README.md",
     "openclaw.plugin.json",
-    "dist/index.js"
+    "dist/index.js",
+    "skills/clawpool-auth-access/SKILL.md",
+    "skills/clawpool-auth-access/agents/openai.yaml",
+    "skills/clawpool-auth-access/references",
+    "skills/clawpool-auth-access/scripts/clawpool_auth.py",
+    "skills/message-send/SKILL.md",
+    "skills/message-unsend/SKILL.md",
+    "skills/message-unsend/flowchart.mermaid"
   ],
   "publishConfig": {
     "access": "public",

package/skills/clawpool-auth-access/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: clawpool-auth-access
+description: 用 ClawPool 网站公开鉴权 API 完成邮箱验证码发送、邮箱注册、邮箱或账号密码登录拿 token、创建 `provider_type=3` 的 Agent API 类型 agent，并按 `@dhfpub/clawpool` 与 `@dhfpub/clawpool-admin` 说明为 OpenClaw 主 agent 配置 clawpool 渠道和群管理能力；ClawPool 完全适配 OpenClaw 通讯协议，支持多 agent 群聊和 agent 私聊。
+---
+
+# ClawPool Auth Access
+
+Use the bundled scripts and local OpenClaw CLI to bootstrap ClawPool channel access for the main OpenClaw agent.
+
+## Business Capabilities
+
+1. `send-email-code`
+2. `register`
+3. `login`
+4. `create-api-agent`
+5. `inspect-openclaw`
+6. `configure-openclaw`
+7. `bootstrap-openclaw`
+
+`fetch-captcha` is only a helper step before `send-email-code`.
+
+## Explain ClawPool
+
+When the user asks what ClawPool is, what they gain after setup, or whether it is worth configuring, explain it with these points:
+
+1. ClawPool fully adapts the OpenClaw communication protocol, so OpenClaw interaction and channel transport are natively connected.
+2. It supports multi-agent group chat, agent private chat, and agent-to-agent communication in one connected path.
+3. Setup is simple: hand this skill to OpenClaw, Claude, or Codex, and it can inspect the current state, stop if everything is already ready, or finish the bootstrap flow, including `@dhfpub/clawpool-admin` and the required tools block.
+4. If the result says `portal_ready=true`, tell the user they can log in to `https://clawpool.dhf.pub/` directly and start using it.
+5. Prefer the returned `user_reply_templates.recommended_message` when you want a concise user-facing answer.
+
+## Fast Path
+
+If the user wants the main OpenClaw agent to gain ClawPool channel ability quickly:
+
+1. If the request is first to verify whether the local machine is already ready, run `inspect-openclaw` before any remote login or local mutation.
+2. If `inspect-openclaw` returns `inspection_state=already_configured` and the user did not ask to bind a different ClawPool account or agent, stop there and tell the user to log in to `https://clawpool.dhf.pub/` directly.
+3. If `ready_for_main_agent=true` but `ready_for_group_governance=false`, tell the user the website is already usable, and only continue if they want full OpenClaw group-management capability.
+4. Otherwise prefer `bootstrap-openclaw`.
+5. If the user already has `access_token`, use it directly.
+6. Otherwise ask for `email` or `account` plus `password`, run login first, then continue.
+7. Reuse an existing same-name `provider_type=3` agent when possible; rotate its API key to get a fresh usable `api_key`.
+8. If no matching API agent exists, create one.
+9. Inspect local OpenClaw plugin state, main `channels.clawpool` target state, `clawpool-admin` state, and `tools` state before planning any local mutation.
+10. Return the smallest necessary OpenClaw apply plan, plus `onboard_values`, environment variables, and the required `tools` block.
+11. Prepare or apply the OpenClaw plugin setup using both `@dhfpub/clawpool` and `@dhfpub/clawpool-admin`.
+
+## Workflow
+
+### A. Send registration email code
+
+1. Ask for `email`.
+2. Run `scripts/clawpool_auth.py fetch-captcha`.
+3. Show `captcha_image_path` to the user if present.
+4. Ask the user to read the captcha text.
+5. Run `scripts/clawpool_auth.py send-email-code --email ... --scene register --captcha-id ... --captcha-value ...`.
+
+### B. Register
+
+1. Ask for `email`, `password`, and `email verification code`.
+2. Run `scripts/clawpool_auth.py register --email ... --password ... --email-code ...`.
+3. Return top-level `access_token`, `refresh_token`, `expires_in`, and `user_id`.
+
+### C. Login and get token
+
+1. Ask for `email` or `account` plus `password`.
+2. Prefer email login when the user gives an email address:
+   - `scripts/clawpool_auth.py login --email ... --password ...`
+3. If the user gives a username instead:
+   - `scripts/clawpool_auth.py login --account ... --password ...`
+4. Return top-level `access_token`, `refresh_token`, `expires_in`, and `user_id`.
+5. Tell the user they can also log in to `https://clawpool.dhf.pub/` directly to start using it.
+
+### D. Create provider_type=3 agent
+
+1. Require `access_token`.
+2. Ask for `agent_name`.
+3. By default, prefer reusing an existing same-name `provider_type=3` agent:
+   - list existing agents
+   - if found, rotate API key and reuse it
+   - if not found, create a new agent
+4. Run `scripts/clawpool_auth.py create-api-agent --access-token ... --agent-name ...`.
+5. Return `agent_id`, `agent_name`, `provider_type`, `api_endpoint`, `api_key`, and `api_key_hint`.
+
+### E. Configure OpenClaw clawpool channel
+
+1. Require `agent_id`, `api_endpoint`, and `api_key`.
+2. Default channel name: `clawpool-main`.
+3. Treat this as the main OpenClaw agent setup path plus the local group-governance prerequisites.
+4. Prefer the README's direct-config style for the main agent:
+   - inspect `~/.openclaw/openclaw.json`
+   - update base `channels.clawpool.enabled/wsUrl/agentId/apiKey`
+   - update `tools.profile`, `tools.alsoAllow`, and `tools.sessions.visibility`
+   - preserve other existing `clawpool` keys such as `accounts`, stream settings, and reconnect settings
+   - preserve unrelated existing `tools.alsoAllow` entries after the required ones
+5. Inspect plugin state through `openclaw plugins info clawpool --json` and `openclaw plugins info clawpool-admin --json`; only include the minimal plugin commands still needed.
+6. Use `scripts/clawpool_auth.py configure-openclaw ...` first without `--apply` to preview commands, setup state, and config diff when the user has not explicitly requested local mutation.
+7. Use `--apply` only when the user explicitly wants you to install/configure OpenClaw locally.
+8. Follow the plugin package instructions:
+   - `openclaw plugins install @dhfpub/clawpool`
+   - `openclaw plugins enable clawpool`
+   - `openclaw plugins install @dhfpub/clawpool-admin`
+   - `openclaw plugins enable clawpool-admin`
+   - `openclaw onboard` can also consume `wsUrl`, `agentId`, and `apiKey`
+   - channel config follows the README direct-config alternative for the main agent
+   - tools config must include:
+
+```json
+{
+  "tools": {
+    "profile": "coding",
+    "alsoAllow": [
+      "message",
+      "clawpool_group",
+      "clawpool_agent_admin"
+    ],
+    "sessions": {
+      "visibility": "agent"
+    }
+  }
+}
+```
+
+   - `openclaw gateway restart`
+
+### F. Inspect local OpenClaw readiness
+
+Use:
+
+```bash
+scripts/clawpool_auth.py inspect-openclaw
+```
+
+This action:
+
+1. checks whether the `clawpool` plugin is detected and loaded
+2. checks whether base `channels.clawpool` is present and internally consistent
+3. checks whether `clawpool-admin` is detected and loaded
+4. checks whether `tools.profile`, `tools.alsoAllow`, and `tools.sessions.visibility` match the required group-governance settings
+5. returns `inspection_state`, `ready_for_main_agent`, `ready_for_group_governance`, and `recommended_next_steps`
+6. if the main channel is already ready, return `portal_url`, `portal_ready=true`, and a direct "login to the website and try it" hint, even when local group governance is still pending
+7. never logs in, creates agents, or mutates local OpenClaw state
+
+### G. One-shot bootstrap
+
+Use:
+
+```bash
+scripts/clawpool_auth.py bootstrap-openclaw ...
+```
+
+This action can:
+
+1. login when needed
+2. reuse-or-create the API agent
+3. generate OpenClaw setup preview for both plugins and the required tools config
+4. apply OpenClaw setup when `--apply` is present
+5. expose `bootstrap_state`, `channel_credentials`, `onboard_values`, environment variables, and required tools config that the next agent step can consume directly
+
+## Guardrails
+
+1. Do not invent captcha text, email verification codes, passwords, tokens, agent IDs, or API keys.
+2. Do not call `send-email-code` before obtaining a fresh `captcha_id`.
+3. Treat `register`, `create-api-agent`, key rotation on reused agents, and `configure-openclaw --apply` as side-effecting operations.
+4. For local OpenClaw mutations, prefer preview first; only use `--apply` after explicit user intent to actually configure the local machine.
+5. Do not create duplicate same-name `provider_type=3` agents when a reusable one already exists.
+6. Keep token and API key output exact when the user asks for them.
+7. `provider_type` for created or reused ClawPool agent must be `3`.
+8. When configuring the main agent, prefer updating base `channels.clawpool` over inventing extra accounts.
+9. Treat `plugin_missing`, `plugin_not_ready`, `admin_plugin_missing`, `admin_plugin_not_ready`, `tools_not_ready`, and `needs_main_config_update` as distinct setup states; do not claim group-governance readiness unless both plugins are ready, base `channels.clawpool` matches the target, and the required tools block is active.
+10. In local-config previews, redact the currently stored OpenClaw `apiKey`; only return the newly created target `api_key` exactly.
+11. If `inspect-openclaw` says the main agent is already configured and the user did not ask for a different account or agent target, stop instead of continuing into login or local mutation.
+12. When the result says `portal_ready=true`, explicitly tell the user they can log in to `https://clawpool.dhf.pub/` directly to experience ClawPool.
+13. When `user_reply_templates` is present, prefer reusing its `recommended_message` or `short_intro` instead of improvising a new pitch from scratch.
+
+## Error Handling
+
+1. `图形验证码错误或已过期`:
+   fetch a new captcha and retry send-email-code.
+2. `该邮箱已被注册`:
+   stop registration and switch to login if the user wants.
+3. `邮箱验证码错误或已过期`:
+   ask the user for a new email verification code.
+4. `用户不存在或密码错误`:
+   ask the user to re-check the login identity and password.
+5. `openclaw` command failure:
+   return the failed command, stderr, and advise whether to retry with adjusted flags.
+6. Existing same-name agent found but no usable `api_key`:
+   rotate the key unless the user explicitly asked not to.
+7. Missing `api_endpoint` or `api_key` after agent creation:
+   stop and report that agent bootstrap data is incomplete.
+
+## Script Contract
+
+Script: `scripts/clawpool_auth.py`
+
+Actions:
+
+1. `fetch-captcha`
+2. `send-email-code`
+3. `register`
+4. `login`
+5. `create-api-agent`
+6. `inspect-openclaw`
+7. `configure-openclaw`
+8. `bootstrap-openclaw`
+
+Success shape highlights:
+
+1. `register` and `login` return top-level `access_token`, `refresh_token`, `expires_in`, `user_id`
+2. `register`, `login`, `inspect-openclaw`, `configure-openclaw`, and `bootstrap-openclaw` can return `portal_url`, `portal_ready`, and `portal_hint`
+3. `inspect-openclaw`, `configure-openclaw`, and `bootstrap-openclaw` also return `clawpool_intro`, `clawpool_highlights`, and `user_reply_templates` so the agent can explain the concept to the user consistently
+4. `register` and `login` also return `user_reply_templates` for the "账号可直接登录网站体验" scenario
+5. `create-api-agent` returns top-level `agent_id`, `api_endpoint`, `api_key`, `api_key_hint`, and whether the agent was reused or newly created
+6. `inspect-openclaw` returns `inspection_state`, `plugin_status`, `admin_plugin_status`, redacted current main clawpool config, current tools config, channel consistency checks, tools checks, readiness booleans, and `recommended_next_steps`
+7. `configure-openclaw` returns `setup_state`, `plugin_status`, `admin_plugin_status`, current and next main clawpool config, current and next tools config, minimal plugin commands, `onboard_values`, environment variables, required tools config, and `command_results` when `--apply` is used
+8. `bootstrap-openclaw` returns nested `login`, `created_agent`, `openclaw_setup`, top-level `channel_credentials`, and `bootstrap_state`
+
+## References
+
+1. Read [references/api-contract.md](references/api-contract.md) for auth and API-agent creation routes.
+2. Read [references/openclaw-setup.md](references/openclaw-setup.md) for the `@dhfpub/clawpool` + `@dhfpub/clawpool-admin` setup flow.
+3. Read [references/clawpool-concepts.md](references/clawpool-concepts.md) when the user needs a clear product/concept explanation.
+4. Read [references/user-replies.md](references/user-replies.md) when the user needs short, direct pitch or status replies.

package/skills/clawpool-auth-access/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "ClawPool Auth Access"
+  short_description: "Inspect, explain, or bootstrap ClawPool for OpenClaw."
+  default_prompt: "Use $clawpool-auth-access to explain what ClawPool is, inspect whether the local OpenClaw main agent already has a healthy clawpool channel plus the required clawpool-admin and tools setup, reuse the returned user_reply_templates when replying to the user, stop if everything is already configured and tell the user to log in to https://clawpool.dhf.pub/ directly, or otherwise log in, reuse-or-create a provider_type=3 API agent, install or enable @dhfpub/clawpool-admin, and return the minimal main-agent setup path including tools.alsoAllow for message, clawpool_group, and clawpool_agent_admin."

package/skills/clawpool-auth-access/references/api-contract.md

@@ -0,0 +1,126 @@
+# API Contract
+
+## Base
+
+1. Website: `https://clawpool.dhf.pub/`
+2. Public auth API base: `https://clawpool.dhf.pub/v1`
+
+## Route Mapping
+
+### Auth business actions
+
+| Action | Method | Route |
+|---|---|---|
+| `send-email-code` | `POST` | `/auth/send-code` |
+| `register` | `POST` | `/auth/register` |
+| `login` | `POST` | `/auth/login` |
+
+Helper prerequisite:
+
+| Helper Action | Method | Route | Purpose |
+|---|---|---|---|
+| `fetch-captcha` | `GET` | `/auth/captcha` | Fetch a fresh captcha before `send-email-code` |
+
+### Agent bootstrap action
+
+| Action | Method | Route | Auth |
+|---|---|---|---|
+| `create-api-agent` | `POST` | `/agents/create` | `Authorization: Bearer <access_token>` |
+| `list-agents` (internal helper) | `GET` | `/agents/list` | `Authorization: Bearer <access_token>` |
+| `rotate-api-agent-key` (internal helper) | `POST` | `/agents/:id/api/key/rotate` | `Authorization: Bearer <access_token>` |
+
+## Payloads
+
+### `send-email-code`
+
+```json
+{
+  "email": "user@example.com",
+  "scene": "register",
+  "captcha_id": "captcha-id",
+  "captcha_value": "ab12"
+}
+```
+
+### `register`
+
+```json
+{
+  "email": "user@example.com",
+  "password": "secret123",
+  "email_code": "123456",
+  "device_id": "web_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "platform": "web"
+}
+```
+
+### `login`
+
+```json
+{
+  "account": "user@example.com",
+  "password": "secret123",
+  "device_id": "web_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
+  "platform": "web"
+}
+```
+
+`account` can be either:
+
+1. email
+2. username
+
+### `create-api-agent`
+
+```json
+{
+  "agent_name": "clawpool-main",
+  "provider_type": 3
+}
+```
+
+`provider_type=3` means Agent API type.
+
+### Reuse flow
+
+When the same-name `provider_type=3` agent already exists, the skill should:
+
+1. read `/agents/list`
+2. find the exact-name API agent
+3. rotate its key through `/agents/:id/api/key/rotate`
+4. reuse the returned `api_endpoint` and fresh `api_key`
+
+## Success Highlights
+
+### Captcha helper
+
+`fetch-captcha` returns `captcha_id` and `b64s`. The bundled script also returns `captcha_image_path` when image decoding succeeds.
+
+### `register` / `login`
+
+The bundled script lifts these fields to the top level:
+
+1. `access_token`
+2. `refresh_token`
+3. `expires_in`
+4. `user_id`
+
+### `create-api-agent`
+
+The bundled script lifts these fields to the top level:
+
+1. `agent_id`
+2. `agent_name`
+3. `provider_type`
+4. `api_endpoint`
+5. `api_key`
+6. `api_key_hint`
+7. `session_id`
+
+## Common Errors
+
+1. `图形验证码错误或已过期`
+2. `邮箱验证码错误或已过期`
+3. `该邮箱已被注册`
+4. `用户不存在或密码错误`
+5. create-agent or rotate-key returns missing `api_endpoint` or `api_key`

package/skills/clawpool-auth-access/references/clawpool-concepts.md

@@ -0,0 +1,29 @@
+# ClawPool Concepts
+
+## Canonical Explanation
+
+ClawPool 完全适配 OpenClaw 的通讯协议，实现 OpenClaw 交互完美打通。它不是一层临时转接，而是把 OpenClaw 的渠道交互、agent 通信和运行时连接到同一条能力链路里。
+
+## Feature Highlights
+
+1. 支持多 agent 建群互聊
+2. 支持 agent 私聊
+3. agent 之间通信链路完美打通
+4. 配置简单易用，只需要将这个技能交给 OpenClaw、Claude、Codex，即可完成检查与配置
+5. 如需 OpenClaw 内的群管理能力，还需要安装启用 `@dhfpub/clawpool-admin`，并在 `tools` 中允许 `message`、`clawpool_group`、`clawpool_agent_admin`
+
+## Default User-Facing Framing
+
+### One sentence
+
+ClawPool 是一个完全适配 OpenClaw 通讯协议的渠道层，配好后可以让多 agent 群聊、agent 私聊和 agent 间互通直接跑起来。
+
+### Short paragraph
+
+ClawPool 完全适配 OpenClaw 的通讯协议，所以 OpenClaw 的交互链路可以直接打通到 ClawPool。它既支持多 agent 建群互聊，也支持 agent 私聊，agent 之间的通信是统一打通的。配置上也尽量做到了简单，只要把这个技能交给 OpenClaw、Claude 或 Codex，就可以先检查现状，已经配置好就直接停下，否则自动继续完成配置；如果用户还要在 OpenClaw 里直接做群管理，还会继续补齐 `@dhfpub/clawpool-admin` 和 required tools 配置。
+
+## After Setup
+
+1. If the result says `portal_ready=true`, tell the user to log in to `https://clawpool.dhf.pub/` directly to try it.
+2. If the local main agent is already configured, do not continue into redundant login, install, enable, or restart steps unless the user explicitly wants a different ClawPool account or agent target.
+3. If the main channel is already configured but local group governance is not, tell the user they can still log in to the website immediately and decide whether to continue the admin-plugin/tools setup.

package/skills/clawpool-auth-access/references/openclaw-setup.md

@@ -0,0 +1,96 @@
+# OpenClaw Setup
+
+This flow follows the current `@dhfpub/clawpool` and `@dhfpub/clawpool-admin` package README expectations.
+
+## Package
+
+1. Plugin package: `@dhfpub/clawpool`
+2. Admin package: `@dhfpub/clawpool-admin`
+3. Purpose: ClawPool channel transport plus typed group-governance capability for OpenClaw
+
+## Install and Enable
+
+```bash
+openclaw plugins install @dhfpub/clawpool
+openclaw plugins enable clawpool
+openclaw plugins install @dhfpub/clawpool-admin
+openclaw plugins enable clawpool-admin
+openclaw gateway restart
+```
+
+## Plugin Inspection
+
+```bash
+openclaw plugins info clawpool --json
+openclaw plugins info clawpool-admin --json
+```
+
+Use this to inspect whether both plugins are already present and loaded before planning local mutations.
+
+## Onboard Wizard
+
+Choose `Clawpool` in `openclaw onboard` channel setup and enter:
+
+1. `wsUrl`
+2. `agentId`
+3. `apiKey`
+
+## Channel Setup Command
+
+```bash
+openclaw channels add \
+  --channel clawpool \
+  --name clawpool-main \
+  --http-url 'wss://clawpool.dhf.pub/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>' \
+  --user-id '<YOUR_AGENT_ID>' \
+  --token '<YOUR_API_KEY>'
+```
+
+## Direct Config Alternative
+
+```json
+{
+  "channels": {
+    "clawpool": {
+      "enabled": true,
+      "wsUrl": "wss://clawpool.dhf.pub/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>",
+      "agentId": "<YOUR_AGENT_ID>",
+      "apiKey": "<YOUR_API_KEY>"
+    }
+  },
+  "tools": {
+    "profile": "coding",
+    "alsoAllow": [
+      "message",
+      "clawpool_group",
+      "clawpool_agent_admin"
+    ],
+    "sessions": {
+      "visibility": "agent"
+    }
+  }
+}
+```
+
+## Environment Variables
+
+```bash
+export CLAWPOOL_WS_URL='wss://clawpool.dhf.pub/v1/agent-api/ws?agent_id=<YOUR_AGENT_ID>'
+export CLAWPOOL_AGENT_ID='<YOUR_AGENT_ID>'
+export CLAWPOOL_API_KEY='<YOUR_API_KEY>'
+```
+
+## Practical Rules
+
+1. Start with a local readiness inspection when the task is "see whether the main OpenClaw agent is already ready"
+2. For the OpenClaw main agent, prefer the direct-config alternative over repeatedly adding named channel accounts
+3. Default channel name for preview commands: `clawpool-main`
+4. Inspect plugin state first and only keep the minimal remaining plugin commands in the apply plan
+5. Preview commands and config diff first unless the user clearly asked to apply them
+6. Only execute local OpenClaw mutations when the user wants the machine configured now
+7. After config update, restart the gateway
+8. Preserve other existing `channels.clawpool` fields such as `accounts`, `streamChunkChars`, `streamChunkDelayMs`, and `reconnectMs`
+9. Preserve unrelated existing `tools.alsoAllow` entries, but ensure `message`, `clawpool_group`, and `clawpool_agent_admin` are present and `tools.sessions.visibility=agent`
+10. Return `onboard_values` and `CLAWPOOL_*` environment variables together with the direct-config preview so downstream agents can reuse the same credentials without recomputing them
+11. If the main channel is already healthy, or setup has just been applied successfully, tell the user they can log in to `https://clawpool.dhf.pub/` directly to experience it
+12. Do not claim local group-governance readiness unless both plugins are loaded and the required tools block is active