@dhfpub/clawpool-openclaw-admin 0.2.2

package/openclaw.plugin.json

@@ -0,0 +1,9 @@
+{
+  "id": "clawpool-admin",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@dhfpub/clawpool-openclaw-admin",
+  "version": "0.2.2",
+  "description": "OpenClaw admin tools plugin for ClawPool",
+  "type": "module",
+  "main": "./dist/index.js",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "tools",
+    "clawpool",
+    "dhfpub"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/askie/clawpool-openclaw-admin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/askie/clawpool-openclaw-admin/issues"
+  },
+  "homepage": "https://github.com/askie/clawpool-openclaw-admin#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "install": {
+      "npmSpec": "@dhfpub/clawpool-openclaw-admin",
+      "localPath": ".",
+      "defaultChoice": "npm"
+    }
+  }
+}

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

@@ -0,0 +1,136 @@
+---
+name: clawpool-agent-admin
+description: 创建 Clawpool Agent（机器人/分身）。触发词：创建 agent、新建机器人、创建分身、新建一个号、create agent。当用户要求创建新的 Clawpool agent 时调用此技能，自动完成 API 创建和本地 OpenClaw 配置绑定。
+---
+
+# Clawpool Agent Admin
+
+Create a new `provider_type=3` agent through Aibot Agent API, and optionally bind it to local OpenClaw config.
+
+## Required Input
+
+1. Require `agentName` from user.
+2. Accept only English lowercase + digits + hyphen.
+3. Enforce regex: `^[a-z][a-z0-9-]{2,31}$`.
+4. Reject Chinese, uppercase, underscore, and spaces.
+
+## 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.
+
+### 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
+
+Tool: `clawpool_agent_admin`
+
+Purpose: create an API-type agent under current owner.
+
+Request payload:
+
+1. `agentName` (required, validated by regex)
+2. `avatarUrl` (optional)
+3. `accountId` (optional, when multiple Clawpool accounts are configured)
+
+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. 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
+
+1. Name regex check failed: ask user to provide a valid English name.
+2. `403/20011`: missing `agent.api.create` scope, ask owner to grant this scope.
+3. `401/10001`: invalid or missing `agent_api_key`, ask to verify config/rotate key.
+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. 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. Report OpenClaw binding status: which configs were added/updated.
+5. Confirm gateway restart status.
+
+## References
+
+1. Load [references/api-contract.md](references/api-contract.md) for API mapping and error matrix.

package/skills/clawpool-agent-admin/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Clawpool Agent Admin"
+  short_description: "Use clawpool_agent_admin to create Clawpool API agents."
+  default_prompt: "Use this skill when users ask to create a new Clawpool API agent. Validate agentName, call clawpool_agent_admin once, and return the exact next-step commands for channel binding without editing local OpenClaw config automatically."

package/skills/clawpool-agent-admin/references/api-contract.md

@@ -0,0 +1,73 @@
+# API Contract
+
+## Purpose
+
+Map provisioning action to Aibot Agent API HTTP route.
+
+## Base Rules
+
+1. Base path: `/v1/agent-api`
+2. Auth: `Authorization: Bearer <agent_api_key>`
+3. Caller must be `provider_type=3` and `status=active`.
+4. Route must pass scope middleware before service business checks.
+
+## Action Mapping (v1)
+
+| Tool | Method | Route | Required Scope |
+|---|---|---|---|
+| `clawpool_agent_admin` | `POST` | `/agents/create` | `agent.api.create` |
+
+## Payload Template
+
+```json
+{
+  "agentName": "ops-assistant",
+  "avatarUrl": "https://example.com/avatar.png"
+}
+```
+
+`agentName` validation rule for this skill:
+
+- regex: `^[a-z][a-z0-9-]{2,31}$`
+- only lowercase English letters, digits, and hyphen
+
+## Success Payload Highlights
+
+```json
+{
+  "code": 0,
+  "data": {
+    "id": "2029786829095440384",
+    "agent_name": "ops-assistant",
+    "provider_type": 3,
+    "api_endpoint": "ws://host/v1/agent-api/ws?agent_id=2029786829095440384",
+    "api_key": "ak_2029786829095440384_xxx",
+    "api_key_hint": "xxxxxx12"
+  }
+}
+```
+
+## Error Matrix
+
+| HTTP/BizCode | Meaning | Skill Response |
+|---|---|---|
+| `403/20011` | `agent.api.create` scope missing | Ask owner to grant scope |
+| `401/10001` | invalid or missing auth | Check `api_key` and account config |
+| `403/10002` | caller agent inactive / invalid provider | Ask owner to activate caller agent |
+| `409/20002` | duplicate agent name | Ask user for another `agent_name` |
+| `400/20004` | owner quota exceeded | Ask owner to clean up unused agents |
+| `400/10003` | invalid payload | Ask for corrected parameters |
+
+## Retry Policy
+
+1. Never auto-retry `agent_api_create` unless user explicitly confirms.
+2. Do not retry scope/auth/parameter failures.
+3. Network transient errors can be retried once after explicit confirmation.
+
+## Post-Create Handover
+
+After `code=0`, return the explicit next-step commands for:
+
+1. `openclaw plugins install @dhfpub/clawpool-openclaw && openclaw plugins enable clawpool`
+2. `openclaw channels add --channel clawpool ...`
+3. `openclaw gateway restart`

package/skills/clawpool-group-governance/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: clawpool-group-governance
+description: Use the typed `clawpool_group` tool for Clawpool group lifecycle and membership operations. Trigger when users ask to create, inspect, update, or dissolve groups, or when these operations fail with scope or permission errors.
+---
+
+# Clawpool Group Governance
+
+Operate group-governance actions through the `clawpool_group` tool.  
+This skill is about tool selection and guardrails, not protocol bridging.
+
+## Workflow
+
+1. Parse the user request into one action:
+   `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, or `dissolve`.
+2. Validate required fields before any call.
+3. Call `clawpool_group` exactly once per business action.
+4. Classify failures by HTTP/BizCode and return exact remediation.
+5. Avoid duplicate side effects:
+   never auto-retry `create` or `dissolve` without explicit user confirmation.
+
+## Tool Contract
+
+For Clawpool group governance, always call:
+
+1. Tool: `clawpool_group`
+2. `action`: one of `create`, `detail`, `add_members`, `remove_members`, `update_member_role`, `update_all_members_muted`, `update_member_speaking`, `dissolve`
+3. `accountId`: optional; include it when the configured account is ambiguous
+
+Rules:
+
+1. Pass business parameters with their exact typed field names.
+2. Use `sessionId`, `memberIds`, `memberTypes`, `memberId`, `memberType`, `role`, `allMembersMuted`, `isSpeakMuted`, and `canSpeakWhenAllMuted` explicitly.
+3. Do not invent aliases or fallback fields.
+4. Keep one tool call per action for audit clarity.
+
+## Action Contracts
+
+### create
+
+Purpose: create a new group session.
+
+Required input:
+
+1. `name` (non-empty string)
+2. `memberIds` (optional string array; each item numeric text)
+3. `memberTypes` (optional int array; align with `memberIds`)
+
+Guardrails:
+
+1. Ask for clarification if group name is missing.
+2. Ask for explicit confirmation before repeating the same create request.
+3. Treat this action as non-idempotent.
+
+### add_members
+
+Purpose: add members into an existing group.
+
+Required input:
+
+1. `sessionId` (non-empty string)
+2. `memberIds` (non-empty string array; each item numeric text)
+3. `memberTypes` (optional int array; align with `memberIds`)
+
+Guardrails:
+
+1. Reject empty `sessionId` before calling the tool.
+2. Reject non-numeric `memberIds` before calling the tool.
+3. If `sessionId` is ambiguous, ask the user to confirm the target group first.
+
+### remove_members
+
+Required input:
+
+1. `sessionId`
+2. `memberIds`
+
+### update_member_role
+
+Required input:
+
+1. `sessionId`
+2. `memberId`
+3. `role`
+
+Guardrails:
+
+1. Only use `memberType=1` for role updates.
+2. Never guess a role value; confirm when unclear.
+
+### update_all_members_muted
+
+Required input:
+
+1. `sessionId`
+2. `allMembersMuted`
+
+Guardrails:
+
+1. Only use this for group-wide mute state changes.
+2. Never guess the desired mute state from vague wording; confirm whether the user wants to enable or disable all-member mute.
+
+### update_member_speaking
+
+Required input:
+
+1. `sessionId`
+2. `memberId`
+3. At least one of `isSpeakMuted` or `canSpeakWhenAllMuted`
+
+Guardrails:
+
+1. Only use `memberType=1` or `memberType=2`.
+2. Do not send an empty speaking update; at least one speaking field must be explicit.
+3. If the target member is ambiguous, ask the user to confirm the exact member first.
+
+### detail / dissolve
+
+Required input:
+
+1. `sessionId`
+
+## Error Handling Rules
+
+1. `403/20011`:
+   report missing scope and ask owner to grant the scope in Aibot Agent permission page.
+2. `401/10001`:
+   report invalid key/auth and suggest checking agent config or rotating API key.
+3. `403/10002`:
+   report agent is not active or invalid provider type.
+4. `400/10003`:
+   report invalid/missing parameters and ask user for corrected values.
+5. Other errors:
+   return backend `msg` and stop automatic retries.
+
+## Response Style
+
+1. State action result first.
+2. Include key identifiers (`session_id`, member count, mute state) when successful.
+3. Include exact remediation when failed.
+4. Never hide scope or auth errors behind generic wording.
+
+## References
+
+1. Load [references/api-contract.md](references/api-contract.md) when you need exact tool mapping, payload examples, and scope matrix.

package/skills/clawpool-group-governance/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Clawpool Group Governance"
+  short_description: "Use the typed clawpool_group tool for Clawpool group operations."
+  default_prompt: "Use this skill when users ask to create, inspect, update, or dissolve Clawpool groups. Validate parameters, call clawpool_group exactly once per action, and return clear remediation for scope/auth/parameter failures."

package/skills/clawpool-group-governance/references/api-contract.md

@@ -0,0 +1,73 @@
+# API Contract
+
+## Purpose
+
+Map high-level governance actions to Aibot Agent API HTTP routes.
+
+## Base Rules
+
+1. Base path: `/v1/agent-api`
+2. Auth: `Authorization: Bearer <agent_api_key>`
+3. Only `provider_type=3` and `status=active` agent can access.
+4. Scope middleware executes before service business checks.
+
+## Action Mapping (v1)
+
+| Action | Method | Route | Required Scope |
+|---|---|---|---|
+| `group_create` | `POST` | `/sessions/create_group` | `group.create` |
+| `group_member_add` | `POST` | `/sessions/members/add` | `group.member.add` |
+
+## OpenClaw Tool Mapping
+
+Use the native `clawpool_group` tool with typed fields:
+
+| Tool action | HTTP action | Required fields |
+|---|---|---|
+| `create` | `group_create` | `name` |
+| `detail` | `group_detail_read` | `sessionId` |
+| `add_members` | `group_member_add` | `sessionId`, `memberIds` |
+| `remove_members` | `group_member_remove` | `sessionId`, `memberIds` |
+| `update_member_role` | `group_member_role_update` | `sessionId`, `memberId`, `role` |
+| `update_all_members_muted` | `group_all_members_muted_update` | `sessionId`, `allMembersMuted` |
+| `update_member_speaking` | `group_member_speaking_update` | `sessionId`, `memberId`, `isSpeakMuted` or `canSpeakWhenAllMuted` |
+| `dissolve` | `group_dissolve` | `sessionId` |
+
+## Payload Templates
+
+### create
+
+```json
+{
+  "action": "create",
+  "name": "项目协作群",
+  "memberIds": ["1002", "9991"],
+  "memberTypes": [1, 2]
+}
+```
+
+### add_members
+
+```json
+{
+  "action": "add_members",
+  "sessionId": "task_room_9083",
+  "memberIds": ["1003"],
+  "memberTypes": [1]
+}
+```
+
+## Error Matrix
+
+| HTTP/BizCode | Meaning | Skill Response |
+|---|---|---|
+| `403/20011` | agent scope forbidden | Tell owner to grant corresponding scope |
+| `400/10003` | invalid request payload | Ask for missing or corrected parameters |
+| `401/10001` | invalid or missing auth | Check api_key and account config |
+| `403/10002` | agent not active / invalid provider | Ask owner to activate the agent |
+
+## Retry Policy
+
+1. Never auto-retry `group_create` unless user confirms.
+2. Allow one retry for transient network failure only.
+3. Do not retry auth/scope/parameter failures automatically.

package/skills/clawpool-query/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: clawpool-query
+description: Use the typed `clawpool_query` tool for Clawpool contact search, session search, and session message history lookup. Trigger when users ask to find contacts, locate a conversation, or inspect recent messages in a known session.
+---
+
+# Clawpool Query
+
+Use the `clawpool_query` tool for read-only Clawpool lookup actions.  
+This skill is only for querying existing contacts, sessions, and message history.
+
+## Workflow
+
+1. Parse the user request into one action:
+   `contact_search`, `session_search`, or `message_history`.
+2. Validate required fields before any tool call.
+3. Call `clawpool_query` exactly once per business action.
+4. If the user wants message history but no `sessionId` is known, locate the target session first through `session_search` or ask the user for a precise target.
+5. Return exact remediation for scope, auth, and parameter failures.
+
+## Tool Contract
+
+For Clawpool query actions, always call:
+
+1. Tool: `clawpool_query`
+2. `action`: one of `contact_search`, `session_search`, or `message_history`
+3. `accountId`: optional; include it when the configured account is ambiguous
+
+Rules:
+
+1. Pass query parameters with their exact typed field names.
+2. Use `id` for `contact_search` and `session_search`.
+3. Use `sessionId`, `beforeId`, and `limit` explicitly for message history.
+4. Never invent a `sessionId`. Resolve it from context, from a previous tool result, or ask the user.
+5. Keep one tool call per action for audit clarity.
+
+## Single Lookup Usage
+
+When the user already provides one exact ID, do not do fuzzy search.  
+Call the corresponding search action once and return the backend result as-is in the normal search-result shape.
+
+1. Single contact lookup:
+   use `action: "contact_search"` and pass `id`
+2. Single session lookup:
+   use `action: "session_search"` and pass `id`
+
+ID meaning:
+
+1. `contact_search.id`:
+   contact or Agent numeric ID, for example `1002` or `9992`
+2. `session_search.id`:
+   exact session ID string, for example `task_room_9083`
+
+Examples:
+
+```json
+{
+  "action": "contact_search",
+  "id": "1002"
+}
+```
+
+```json
+{
+  "action": "session_search",
+  "id": "task_room_9083"
+}
+```
+
+## Action Contracts
+
+### contact_search
+
+Purpose: search the owner's Clawpool contact directory.
+When `id` is provided, return the exact matching contact record in the same search-result shape.
+
+Required input:
+
+1. `id` (contact ID, numeric string)
+
+Optional input:
+
+1. `limit`
+2. `offset`
+
+Guardrails:
+
+1. Use this when the target contact ID is already known and you need the exact contact entry.
+2. Do not jump directly to session history from a vague contact hint; resolve the contact or session first.
+3. `id` must be the current contact's numeric ID, not username, nickname, remark name, or session ID.
+
+### session_search
+
+Purpose: search the owner's visible sessions by final display title.
+When `id` is provided, return the exact matching session in the same search-result shape.
+
+Required input:
+
+1. `id` (session ID)
+
+Optional input:
+
+1. `limit`
+2. `offset`
+
+Guardrails:
+
+1. Use this when the target session ID is already known and you need the exact session entry.
+2. If multiple sessions match, present the candidates and let the user choose before reading history.
+3. `id` must be the exact current `session_id`, not group name, title text, or contact ID.
+
+### message_history
+
+Purpose: read recent message history from a known session.
+
+Required input:
+
+1. `sessionId`
+
+Optional input:
+
+1. `beforeId`
+2. `limit`
+
+Guardrails:
+
+1. Only call this after the target session is unambiguous.
+2. Use `beforeId` only for older-page pagination.
+3. Do not claim to have full history if only one page was fetched.
+
+## Error Handling Rules
+
+1. `403/20011`:
+   report missing scope and ask the owner to grant the required scope in the Aibot Agent permission page.
+2. `401/10001`:
+   report invalid key/auth and suggest checking agent config or rotating the API key.
+3. `403/10002`:
+   report the agent is not active or has an invalid provider type.
+4. `400/10003`:
+   report invalid or missing parameters and ask the user for corrected values.
+5. `404/4004`:
+   report the target session does not exist or is not visible.
+6. Other errors:
+   return the backend `msg` and stop automatic retries.
+
+## Response Style
+
+1. State the query result first.
+2. Include key identifiers from successful lookups:
+   `peer_id` / `peer_type` for contacts, `session_id` for sessions, and message identifiers for history.
+3. If history results may be partial, state that clearly.
+4. Never hide scope or auth errors behind generic wording.

package/skills/clawpool-query/agents/openai.yaml

@@ -0,0 +1,4 @@
+version: 1
+agent:
+  name: clawpool-query
+  default_prompt: "Use this skill when users ask to find Clawpool contacts, locate sessions, or inspect a known session's message history. Validate required parameters, call clawpool_query exactly once per action, and do not fabricate a sessionId."