@dhfpub/clawpool-admin 0.1.0 → 0.1.2

package/README.md

@@ -7,6 +7,16 @@ It is intentionally separate from the channel transport plugin:
 - `@dhfpub/clawpool`: channel transport only
 - `@dhfpub/clawpool-admin`: admin tools and CLI only
 
+If you are reading the channel plugin documentation first, also read:
+
+- `openclaw_plugins/clawpool/README.md`
+
+## Which Package Do I Need?
+
+- Install only `@dhfpub/clawpool` when you only need ClawPool channel transport, website onboarding, and the bundled onboarding skill
+- Install both `@dhfpub/clawpool` and `@dhfpub/clawpool-admin` when you want typed group governance or typed API-agent admin actions inside OpenClaw
+- Do not install only `@dhfpub/clawpool-admin` and expect it to work alone, because it depends on the `channels.clawpool` credentials managed by `@dhfpub/clawpool`
+
 ## Install
 
 ```bash
@@ -17,6 +27,116 @@ openclaw gateway restart
 
 The admin plugin reads credentials from the configured `channels.clawpool` account. Install and configure `@dhfpub/clawpool` first.
 
+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
+
+For the channel-side setup flow, see:
+
+- `openclaw_plugins/clawpool/README.md`
+
+## Required OpenClaw Setup
+
+`@dhfpub/clawpool-admin` is not enough by itself. For the tools to be callable inside OpenClaw, you must complete all of these steps:
+
+1. Install and configure `@dhfpub/clawpool` so `channels.clawpool` already has valid `wsUrl`, `agentId`, and `apiKey`
+2. Install and enable `@dhfpub/clawpool-admin`
+3. Enable the required tools in OpenClaw config
+4. Restart the OpenClaw gateway
+
+If the `tools` block is missing, the plugin may be installed and loaded, but the agent still cannot use `clawpool_group` or `clawpool_agent_admin`.
+
+## Configure `channels.clawpool` First
+
+The admin plugin depends on the main ClawPool channel config. A minimal working example is:
+
+```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>"
+    }
+  }
+}
+```
+
+If you have not configured this yet, install `@dhfpub/clawpool` first and complete the channel setup before using the admin plugin.
+
+## Enable Required Tools
+
+To make the admin capabilities available to the OpenClaw agent, configure `tools` like this:
+
+```json
+{
+  "tools": {
+    "profile": "coding",
+    "alsoAllow": [
+      "message",
+      "clawpool_group",
+      "clawpool_agent_admin"
+    ],
+    "sessions": {
+      "visibility": "agent"
+    }
+  }
+}
+```
+
+These fields are required for the intended ClawPool group-governance workflow:
+
+- `message`: lets the agent send and coordinate messages in the group workflow
+- `clawpool_group`: enables typed group governance actions
+- `clawpool_agent_admin`: enables typed API-agent admin actions
+- `sessions.visibility = agent`: ensures the tool session context is visible to the agent runtime
+
+## Full Example
+
+```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"
+    }
+  }
+}
+```
+
+## Verification
+
+After setup, verify the plugin and tools path with:
+
+```bash
+openclaw plugins info clawpool-admin --json
+openclaw clawpool-admin doctor
+```
+
+Expected result:
+
+- `plugins info clawpool-admin` shows `enabled=true`, `status=loaded`
+- the plugin exposes `clawpool_group` and `clawpool_agent_admin`
+- `clawpool-admin doctor` can see the configured `channels.clawpool` account
+
 ## Agent Tools
 
 ### `clawpool_group`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dhfpub/clawpool-admin",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "OpenClaw admin tools plugin for ClawPool",
   "type": "module",
   "main": "./dist/index.js",

package/skills/clawpool-agent-admin/SKILL.md

@@ -1,12 +1,11 @@
 ---
 name: clawpool-agent-admin
-description: Use the typed `clawpool_agent_admin` tool to create Clawpool API agents. Trigger when users ask to create a new API agent or when `/v1/agent-api/agents/create` fails with scope or permission errors.
+description: 创建 Clawpool Agent（机器人/分身）。触发词：创建 agent、新建机器人、创建分身、新建一个号、create agent。当用户要求创建新的 Clawpool agent 时调用此技能，自动完成 API 创建和本地 OpenClaw 配置绑定。
 ---
 
 # Clawpool Agent Admin
 
-Create a new `provider_type=3` agent through Aibot Agent API.  
-This skill does not install plugins, edit local config, or restart the gateway.
+Create a new `provider_type=3` agent through Aibot Agent API, and optionally bind it to local OpenClaw config.
 
 ## Required Input
 
@@ -17,10 +16,45 @@ This skill does not install plugins, edit local config, or restart the gateway.
 
 ## Workflow
 
+### Phase 1: Create API Agent
+
 1. Ask user for `agentName` when missing.
 2. Validate `agentName` with the regex above before any tool call.
 3. Call `clawpool_agent_admin` once with `agentName` and optional `accountId` / `avatarUrl`.
-4. Return the created agent details and the explicit next-step commands for channel binding.
+4. Return the created agent details.
+
+### Phase 2: Bind to OpenClaw (Auto)
+
+After successful API agent creation, automatically bind to local OpenClaw:
+
+1. **Add Agent Config**: Add entry to `agents.list` in `~/.openclaw/openclaw.json`
+   - `id`: agentName
+   - `name`: agentName
+   - `workspace`: `~/.openclaw/workspace-{agentName}`
+   - `agentDir`: `~/.openclaw/agents/{agentName}/agent`
+   - `model`: use default model from `agents.defaults.model.primary`
+
+2. **Add Channel Account**: Add entry to `channels.clawpool.accounts`
+   - Key: agentName
+   - `name`: agentName
+   - `enabled`: true
+   - `apiKey`: from API response
+   - `wsUrl`: from API response `api_endpoint`
+   - `agentId`: from API response `id`
+
+3. **Add Binding**: Add route binding to `bindings`
+   - `type`: "route"
+   - `agentId`: agentName
+   - `match.channel`: "clawpool"
+   - `match.accountId`: agentName
+
+4. **Create Workspace**: Create workspace directory with default files
+   - Create `~/.openclaw/workspace-{agentName}/`
+   - Create `AGENTS.md` with basic agent description
+   - Create `MEMORY.md` with owner info
+   - Create `USER.md` referencing the owner
+
+5. **Restart Gateway**: Run `openclaw gateway restart` to apply changes
 
 ## Tool Contract
 
@@ -39,7 +73,44 @@ Guardrails:
 1. Treat create action as non-idempotent; never auto-retry without user confirmation.
 2. Expose `api_key` only once in success output; mask it in any later logs.
 3. Do not auto-grant extra scopes to the new agent.
-4. Do not auto-install plugins or mutate local OpenClaw config from this skill.
+4. Check if agent config already exists before adding to avoid duplicates.
+5. Backup `openclaw.json` before modification.
+
+## OpenClaw Config Template
+
+### agents.list entry:
+```json
+{
+  "id": "{agentName}",
+  "name": "{agentName}",
+  "workspace": "/Users/{username}/.openclaw/workspace-{agentName}",
+  "agentDir": "/Users/{username}/.openclaw/agents/{agentName}/agent",
+  "model": "{defaultModel}"
+}
+```
+
+### channels.clawpool.accounts entry:
+```json
+"{agentName}": {
+  "name": "{agentName}",
+  "enabled": true,
+  "apiKey": "{apiKey}",
+  "wsUrl": "{api_endpoint}",
+  "agentId": "{agent_id}"
+}
+```
+
+### bindings entry:
+```json
+{
+  "type": "route",
+  "agentId": "{agentName}",
+  "match": {
+    "channel": "clawpool",
+    "accountId": "{agentName}"
+  }
+}
+```
 
 ## Error Handling Rules
 
@@ -49,14 +120,16 @@ Guardrails:
 4. `403/10002`: caller agent inactive or invalid provider type.
 5. `409/20002`: duplicate agent name; ask user for another name.
 6. `400/20004`: owner quota exceeded; ask owner to clean up agents.
-7. Other errors: return backend `msg` and stop automatic retries.
+7. Config write failure: report error and provide manual steps.
+8. Other errors: return backend `msg` and stop automatic retries.
 
 ## Response Style
 
 1. Return `created` status first.
 2. Include `agent_id`, `agent_name`, `api_endpoint`, and `api_key_hint`.
 3. Show `api_key` once, then only show `api_key_hint`.
-4. Include the exact next steps for `openclaw channels add` and `openclaw gateway restart`.
+4. Report OpenClaw binding status: which configs were added/updated.
+5. Confirm gateway restart status.
 
 ## References