@dhfpub/clawpool-admin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 askie and contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,46 @@
+# OpenClaw ClawPool Admin Plugin
+
+This plugin provides typed optional admin tools and an operator CLI for Clawpool.
+
+It is intentionally separate from the channel transport plugin:
+
+- `@dhfpub/clawpool`: channel transport only
+- `@dhfpub/clawpool-admin`: admin tools and CLI only
+
+## Install
+
+```bash
+openclaw plugins install @dhfpub/clawpool-admin
+openclaw plugins enable clawpool-admin
+openclaw gateway restart
+```
+
+The admin plugin reads credentials from the configured `channels.clawpool` account. Install and configure `@dhfpub/clawpool` first.
+
+## Agent Tools
+
+### `clawpool_group`
+
+Typed group governance tool with these actions:
+
+- `create`
+- `detail`
+- `add_members`
+- `remove_members`
+- `update_member_role`
+- `dissolve`
+
+### `clawpool_agent_admin`
+
+Typed admin tool for creating API agents.
+
+This tool only creates the remote Clawpool API agent. It does not edit local OpenClaw config.
+
+## Operator CLI
+
+```bash
+openclaw clawpool-admin doctor
+openclaw clawpool-admin create-agent --agent-name ops-assistant
+```
+
+`create-agent` prints the created agent payload plus the exact `openclaw channels add` and `openclaw gateway restart` next steps.

package/dist/index.js

@@ -0,0 +1,825 @@
+// index.ts
+import { emptyPluginConfigSchema } from "openclaw/plugin-sdk/core";
+
+// src/agent-api-actions.ts
+var AGENT_NAME_RE = /^[a-z][a-z0-9-]{2,31}$/;
+function readRawParam(params, key) {
+  if (Object.hasOwn(params, key)) {
+    return params[key];
+  }
+  return void 0;
+}
+function readStringParam(params, key) {
+  const raw = readRawParam(params, key);
+  if (typeof raw === "string") {
+    return raw.trim();
+  }
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return String(raw);
+  }
+  return "";
+}
+function readRequiredStringParam(params, key) {
+  const value = readStringParam(params, key);
+  if (!value) {
+    throw new Error(`Clawpool action requires ${key}.`);
+  }
+  return value;
+}
+function readArrayParam(params, key) {
+  const raw = readRawParam(params, key);
+  if (raw == null) {
+    return void 0;
+  }
+  if (!Array.isArray(raw)) {
+    throw new Error(`Clawpool action requires ${key} as array.`);
+  }
+  return raw;
+}
+function readNumericIDArray(params, key, required) {
+  const values = readArrayParam(params, key);
+  if (!values || values.length == 0) {
+    if (required) {
+      throw new Error(`Clawpool action requires non-empty ${key}.`);
+    }
+    return [];
+  }
+  const normalized = [];
+  for (const item of values) {
+    const value = typeof item === "string" ? item.trim() : typeof item === "number" && Number.isFinite(item) ? String(Math.trunc(item)) : "";
+    if (!/^\d+$/.test(value)) {
+      throw new Error(`Clawpool action ${key} must contain numeric IDs.`);
+    }
+    normalized.push(value);
+  }
+  return normalized;
+}
+function readIntArray(params, key) {
+  const values = readArrayParam(params, key);
+  if (!values || values.length == 0) {
+    return [];
+  }
+  const normalized = [];
+  for (const item of values) {
+    const num = typeof item === "number" ? item : Number(String(item ?? "").trim());
+    if (!Number.isInteger(num)) {
+      throw new Error(`Clawpool action ${key} must contain integers.`);
+    }
+    normalized.push(num);
+  }
+  return normalized;
+}
+function readOptionalInt(params, key) {
+  const raw = readRawParam(params, key);
+  if (raw == null) {
+    return void 0;
+  }
+  const num = typeof raw === "number" ? raw : Number(String(raw).trim());
+  if (!Number.isInteger(num)) {
+    throw new Error(`Clawpool action ${key} must be an integer.`);
+  }
+  return num;
+}
+function readRequiredInt(params, key) {
+  const value = readOptionalInt(params, key);
+  if (value == null) {
+    throw new Error(`Clawpool action requires ${key}.`);
+  }
+  return value;
+}
+function ensureMemberTypes(types) {
+  for (const memberType of types) {
+    if (memberType !== 1 && memberType !== 2) {
+      throw new Error("Clawpool action member_types only supports 1 (human) or 2 (agent).");
+    }
+  }
+}
+function ensureMemberType(memberType) {
+  if (memberType !== 1) {
+    throw new Error("Clawpool action member_type only supports 1 for role update.");
+  }
+}
+function buildGroupCreateRequest(params) {
+  const name = readRequiredStringParam(params, "name");
+  const memberIDs = readNumericIDArray(params, "memberIds", false);
+  const memberTypes = readIntArray(params, "memberTypes");
+  if (memberTypes.length > 0) {
+    ensureMemberTypes(memberTypes);
+    if (memberIDs.length == 0 || memberTypes.length !== memberIDs.length) {
+      throw new Error("Clawpool action memberTypes length must match memberIds.");
+    }
+  }
+  const body = { name };
+  if (memberIDs.length > 0) {
+    body.member_ids = memberIDs;
+  }
+  if (memberTypes.length > 0) {
+    body.member_types = memberTypes;
+  }
+  return {
+    actionName: "group_create",
+    method: "POST",
+    path: "/sessions/create_group",
+    body
+  };
+}
+function buildGroupMemberAddRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  const memberIDs = readNumericIDArray(params, "memberIds", true);
+  const memberTypes = readIntArray(params, "memberTypes");
+  if (memberTypes.length > 0) {
+    ensureMemberTypes(memberTypes);
+    if (memberTypes.length !== memberIDs.length) {
+      throw new Error("Clawpool action memberTypes length must match memberIds.");
+    }
+  }
+  const body = {
+    session_id: sessionID,
+    member_ids: memberIDs
+  };
+  if (memberTypes.length > 0) {
+    body.member_types = memberTypes;
+  }
+  return {
+    actionName: "group_member_add",
+    method: "POST",
+    path: "/sessions/members/add",
+    body
+  };
+}
+function buildGroupMemberRemoveRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  const memberIDs = readNumericIDArray(params, "memberIds", true);
+  const memberTypes = readIntArray(params, "memberTypes");
+  if (memberTypes.length > 0) {
+    ensureMemberTypes(memberTypes);
+    if (memberTypes.length !== memberIDs.length) {
+      throw new Error("Clawpool action memberTypes length must match memberIds.");
+    }
+  }
+  const body = {
+    session_id: sessionID,
+    member_ids: memberIDs
+  };
+  if (memberTypes.length > 0) {
+    body.member_types = memberTypes;
+  }
+  return {
+    actionName: "group_member_remove",
+    method: "POST",
+    path: "/sessions/members/remove",
+    body
+  };
+}
+function buildGroupMemberRoleUpdateRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  const memberID = readRequiredStringParam(params, "memberId");
+  if (!/^\d+$/.test(memberID)) {
+    throw new Error("Clawpool action memberId must be numeric.");
+  }
+  const role = readRequiredInt(params, "role");
+  if (role !== 1 && role !== 2) {
+    throw new Error("Clawpool action role only supports 1 or 2.");
+  }
+  const memberType = readOptionalInt(params, "memberType") ?? 1;
+  ensureMemberType(memberType);
+  return {
+    actionName: "group_member_role_update",
+    method: "POST",
+    path: "/sessions/members/role",
+    body: {
+      session_id: sessionID,
+      member_id: memberID,
+      member_type: memberType,
+      role
+    }
+  };
+}
+function buildGroupDissolveRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  return {
+    actionName: "group_dissolve",
+    method: "POST",
+    path: "/sessions/dissolve",
+    body: {
+      session_id: sessionID
+    }
+  };
+}
+function buildGroupDetailReadRequest(params) {
+  const sessionID = readRequiredStringParam(params, "sessionId");
+  return {
+    actionName: "group_detail_read",
+    method: "GET",
+    path: "/sessions/group/detail",
+    query: {
+      session_id: sessionID
+    }
+  };
+}
+function buildAgentAPICreateRequest(params) {
+  const agentName = readRequiredStringParam(params, "agentName");
+  if (!AGENT_NAME_RE.test(agentName)) {
+    throw new Error("Clawpool action agentName must match ^[a-z][a-z0-9-]{2,31}$.");
+  }
+  const avatarURL = readStringParam(params, "avatarUrl");
+  const body = {
+    agent_name: agentName
+  };
+  if (avatarURL) {
+    body.avatar_url = avatarURL;
+  }
+  return {
+    actionName: "agent_api_create",
+    method: "POST",
+    path: "/agents/create",
+    body
+  };
+}
+function buildAgentHTTPRequest(action, params) {
+  switch (action) {
+    case "group_create":
+      return buildGroupCreateRequest(params);
+    case "group_member_add":
+      return buildGroupMemberAddRequest(params);
+    case "group_member_remove":
+      return buildGroupMemberRemoveRequest(params);
+    case "group_member_role_update":
+      return buildGroupMemberRoleUpdateRequest(params);
+    case "group_dissolve":
+      return buildGroupDissolveRequest(params);
+    case "group_detail_read":
+      return buildGroupDetailReadRequest(params);
+    case "agent_api_create":
+      return buildAgentAPICreateRequest(params);
+    default:
+      throw new Error(`Clawpool action ${action} is not supported.`);
+  }
+}
+
+// src/agent-api-http.ts
+var DEFAULT_HTTP_TIMEOUT_MS = 15e3;
+function trimTrailingSlash(value) {
+  return value.replace(/\/+$/, "");
+}
+function resolveExplicitAgentAPIBase() {
+  const base = String(
+    process.env.CLAWPOOL_AGENT_API_BASE ?? process.env.AIBOT_AGENT_API_BASE ?? ""
+  ).trim();
+  if (!base) {
+    return "";
+  }
+  return trimTrailingSlash(base);
+}
+function deriveAgentAPIBaseFromWsUrl(wsUrl) {
+  const normalizedWsUrl = String(wsUrl ?? "").trim();
+  if (!normalizedWsUrl) {
+    throw new Error("Clawpool account wsUrl is missing");
+  }
+  let parsed;
+  try {
+    parsed = new URL(normalizedWsUrl);
+  } catch {
+    throw new Error(`Clawpool wsUrl is invalid: ${normalizedWsUrl}`);
+  }
+  const protocol = parsed.protocol === "wss:" ? "https:" : parsed.protocol === "ws:" ? "http:" : "";
+  if (!protocol) {
+    throw new Error(`Clawpool wsUrl must start with ws:// or wss://: ${normalizedWsUrl}`);
+  }
+  const marker = "/v1/agent-api/ws";
+  const markerIndex = parsed.pathname.indexOf(marker);
+  const basePath = markerIndex >= 0 ? parsed.pathname.slice(0, markerIndex) : parsed.pathname;
+  return trimTrailingSlash(`${protocol}//${parsed.host}${basePath}`) + "/v1/agent-api";
+}
+function deriveLocalAgentAPIBaseFromWsUrl(wsUrl) {
+  const normalizedWsUrl = String(wsUrl ?? "").trim();
+  if (!normalizedWsUrl) {
+    return "";
+  }
+  let parsed;
+  try {
+    parsed = new URL(normalizedWsUrl);
+  } catch {
+    return "";
+  }
+  const host = String(parsed.hostname ?? "").trim().toLowerCase();
+  const localHosts = /* @__PURE__ */ new Set(["127.0.0.1", "localhost", "::1"]);
+  if (!localHosts.has(host)) {
+    return "";
+  }
+  const wsPort = Number(parsed.port || (parsed.protocol === "wss:" ? 443 : 80));
+  if (!Number.isFinite(wsPort) || wsPort <= 0) {
+    return "";
+  }
+  const apiPort = wsPort % 10 === 9 ? wsPort - 9 : 27180;
+  const protocol = parsed.protocol === "wss:" ? "https:" : "http:";
+  return trimTrailingSlash(`${protocol}//${parsed.hostname}:${apiPort}`) + "/v1/agent-api";
+}
+function resolveAgentAPIBase(account) {
+  const explicit = resolveExplicitAgentAPIBase();
+  if (explicit) {
+    return explicit;
+  }
+  const local = deriveLocalAgentAPIBaseFromWsUrl(account.wsUrl);
+  if (local) {
+    return local;
+  }
+  return deriveAgentAPIBaseFromWsUrl(account.wsUrl);
+}
+function buildRequestURL(base, path, query) {
+  const normalizedPath = path.startsWith("/") ? path : `/${path}`;
+  const url = new URL(`${trimTrailingSlash(base)}${normalizedPath}`);
+  if (query) {
+    for (const [key, value] of Object.entries(query)) {
+      const normalizedValue = String(value ?? "").trim();
+      if (!normalizedValue) {
+        continue;
+      }
+      url.searchParams.set(key, normalizedValue);
+    }
+  }
+  return url.toString();
+}
+function normalizeStatusCode(raw) {
+  const n = Number(raw);
+  if (Number.isFinite(n)) {
+    return Math.floor(n);
+  }
+  return 0;
+}
+function normalizeBizCode(raw) {
+  const n = Number(raw);
+  if (Number.isFinite(n)) {
+    return Math.floor(n);
+  }
+  return -1;
+}
+function normalizeMessage(raw) {
+  const message = String(raw ?? "").trim();
+  if (!message) {
+    return "unknown error";
+  }
+  return message;
+}
+function extractNetworkErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message || String(error);
+  }
+  return String(error);
+}
+async function callAgentAPI(params) {
+  const base = resolveAgentAPIBase(params.account);
+  const url = buildRequestURL(base, params.path, params.query);
+  const timeoutMs = Number.isFinite(params.timeoutMs) ? Math.max(1e3, Math.floor(params.timeoutMs)) : DEFAULT_HTTP_TIMEOUT_MS;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let resp;
+  try {
+    resp = await fetch(url, {
+      method: params.method,
+      headers: {
+        Authorization: `Bearer ${params.account.apiKey}`,
+        ...params.method === "POST" ? { "Content-Type": "application/json" } : {}
+      },
+      body: params.method === "POST" ? JSON.stringify(params.body ?? {}) : void 0,
+      signal: controller.signal
+    });
+  } catch (error) {
+    clearTimeout(timer);
+    throw new Error(
+      `Clawpool ${params.actionName} network error: ${extractNetworkErrorMessage(error)}`
+    );
+  }
+  clearTimeout(timer);
+  const status = normalizeStatusCode(resp.status);
+  const rawBody = await resp.text();
+  let envelope;
+  try {
+    envelope = JSON.parse(rawBody);
+  } catch {
+    throw new Error(
+      `Clawpool ${params.actionName} invalid response: status=${status} body=${rawBody.slice(0, 256)}`
+    );
+  }
+  const bizCode = normalizeBizCode(envelope.code);
+  if (!resp.ok || bizCode !== 0) {
+    const message = normalizeMessage(envelope.msg);
+    throw new Error(
+      `Clawpool ${params.actionName} failed: status=${status} code=${bizCode} msg=${message}`
+    );
+  }
+  return envelope.data;
+}
+
+// src/accounts.ts
+var DEFAULT_ACCOUNT_ID = "default";
+function normalizeAccountId(value) {
+  const normalized = String(value ?? "").trim();
+  return normalized || DEFAULT_ACCOUNT_ID;
+}
+function normalizeOptionalAccountId(value) {
+  const normalized = String(value ?? "").trim();
+  return normalized || void 0;
+}
+function rawClawpoolConfig(cfg) {
+  return cfg.channels?.clawpool ?? {};
+}
+function listConfiguredAccountIds(cfg) {
+  const accounts = rawClawpoolConfig(cfg).accounts;
+  if (!accounts || typeof accounts !== "object") {
+    return [];
+  }
+  return Object.keys(accounts).filter(Boolean);
+}
+function normalizeNonEmpty(value) {
+  return String(value ?? "").trim();
+}
+function appendAgentIdToWsUrl(rawWsUrl, agentId) {
+  if (!rawWsUrl) {
+    return "";
+  }
+  const direct = rawWsUrl.replaceAll("{agent_id}", encodeURIComponent(agentId));
+  if (!agentId) {
+    return direct;
+  }
+  try {
+    const parsed = new URL(direct);
+    if (!parsed.searchParams.get("agent_id")) {
+      parsed.searchParams.set("agent_id", agentId);
+    }
+    return parsed.toString();
+  } catch {
+    if (direct.includes("agent_id=")) {
+      return direct;
+    }
+    return direct.includes("?") ? `${direct}&agent_id=${encodeURIComponent(agentId)}` : `${direct}?agent_id=${encodeURIComponent(agentId)}`;
+  }
+}
+function resolveWsUrl(merged, agentId) {
+  const envWs = normalizeNonEmpty(process.env.CLAWPOOL_WS_URL);
+  const cfgWs = normalizeNonEmpty(merged.wsUrl);
+  const ws = cfgWs || envWs;
+  if (ws) {
+    return appendAgentIdToWsUrl(ws, agentId);
+  }
+  if (!agentId) {
+    return "";
+  }
+  return `ws://127.0.0.1:27189/v1/agent-api/ws?agent_id=${encodeURIComponent(agentId)}`;
+}
+function resolveMergedAccountConfig(cfg, accountId) {
+  const clawpoolCfg = rawClawpoolConfig(cfg);
+  const { accounts: _ignoredAccounts, defaultAccount: _ignoredDefault, ...base } = clawpoolCfg;
+  const account = clawpoolCfg.accounts?.[accountId] ?? {};
+  return {
+    ...base,
+    ...account
+  };
+}
+function listClawpoolAccountIds(cfg) {
+  const ids = listConfiguredAccountIds(cfg);
+  if (ids.length === 0) {
+    return [DEFAULT_ACCOUNT_ID];
+  }
+  return ids.toSorted((a, b) => a.localeCompare(b));
+}
+function resolveDefaultClawpoolAccountId(cfg) {
+  const clawpoolCfg = rawClawpoolConfig(cfg);
+  const preferred = normalizeOptionalAccountId(clawpoolCfg.defaultAccount);
+  if (preferred && listClawpoolAccountIds(cfg).some((accountId) => normalizeAccountId(accountId) === preferred)) {
+    return preferred;
+  }
+  const ids = listClawpoolAccountIds(cfg);
+  if (ids.includes(DEFAULT_ACCOUNT_ID)) {
+    return DEFAULT_ACCOUNT_ID;
+  }
+  return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+function resolveClawpoolAccount(params) {
+  const accountId = params.accountId == null || String(params.accountId).trim() === "" ? resolveDefaultClawpoolAccountId(params.cfg) : normalizeAccountId(params.accountId);
+  const merged = resolveMergedAccountConfig(params.cfg, accountId);
+  const baseEnabled = rawClawpoolConfig(params.cfg).enabled !== false;
+  const accountEnabled = merged.enabled !== false;
+  const enabled = baseEnabled && accountEnabled;
+  const agentId = normalizeNonEmpty(merged.agentId || process.env.CLAWPOOL_AGENT_ID);
+  const apiKey = normalizeNonEmpty(merged.apiKey || process.env.CLAWPOOL_API_KEY);
+  const wsUrl = resolveWsUrl(merged, agentId);
+  const configured = Boolean(wsUrl && agentId && apiKey);
+  return {
+    accountId,
+    name: normalizeNonEmpty(merged.name) || void 0,
+    enabled,
+    configured,
+    wsUrl,
+    agentId,
+    apiKey,
+    config: merged
+  };
+}
+function summarizeClawpoolAccounts(cfg) {
+  return listClawpoolAccountIds(cfg).map((accountId) => {
+    const account = resolveClawpoolAccount({ cfg, accountId });
+    return {
+      accountId: account.accountId,
+      name: account.name ?? null,
+      enabled: account.enabled,
+      configured: account.configured,
+      wsUrl: account.wsUrl || null,
+      agentId: account.agentId || null
+    };
+  });
+}
+
+// src/agent-admin-service.ts
+function buildChannelBootstrapCommand(params) {
+  return [
+    "openclaw channels add",
+    "--channel clawpool",
+    `--name ${JSON.stringify(params.channelName)}`,
+    `--http-url ${JSON.stringify(params.apiEndpoint)}`,
+    `--user-id ${JSON.stringify(params.agentId)}`,
+    `--token ${JSON.stringify(params.apiKey)}`
+  ].join(" ");
+}
+async function createClawpoolApiAgent(params) {
+  const account = resolveClawpoolAccount({
+    cfg: params.cfg,
+    accountId: params.toolParams.accountId
+  });
+  if (!account.enabled) {
+    throw new Error(`Clawpool account "${account.accountId}" is disabled.`);
+  }
+  if (!account.configured) {
+    throw new Error(`Clawpool account "${account.accountId}" is not configured.`);
+  }
+  const request = buildAgentHTTPRequest("agent_api_create", params.toolParams);
+  const data = await callAgentAPI({
+    account,
+    actionName: request.actionName,
+    method: request.method,
+    path: request.path,
+    query: request.query,
+    body: request.body
+  });
+  const agentName = String(data.agent_name ?? params.toolParams.agentName ?? "").trim();
+  const apiEndpoint = String(data.api_endpoint ?? "").trim();
+  const agentId = String(data.id ?? "").trim();
+  const apiKey = String(data.api_key ?? "").trim();
+  return {
+    ok: true,
+    accountId: account.accountId,
+    action: "create_api_agent",
+    data,
+    nextSteps: agentName && apiEndpoint && agentId && apiKey ? [
+      "Install and enable the channel plugin if it is not installed yet: `openclaw plugins install @dhfpub/clawpool && openclaw plugins enable clawpool`.",
+      `Bind the new API agent to OpenClaw with: \`${buildChannelBootstrapCommand({
+        channelName: `clawpool-${agentName}`,
+        apiEndpoint,
+        agentId,
+        apiKey
+      })}\``,
+      "Restart the gateway after adding the channel: `openclaw gateway restart`."
+    ] : []
+  };
+}
+function inspectClawpoolAdminConfig(cfg) {
+  return {
+    accounts: summarizeClawpoolAccounts(cfg),
+    defaultAccountId: resolveClawpoolAccount({ cfg }).accountId
+  };
+}
+
+// src/cli.ts
+function registerClawpoolAdminCli(params) {
+  const root = params.program.command("clawpool-admin").description("Clawpool admin utilities").addHelpText(
+    "after",
+    "\nThis CLI is for operator workflows. Agent tools stay scoped to typed remote admin actions only.\n"
+  );
+  root.command("doctor").description("Show the Clawpool accounts visible from the current OpenClaw config").action(() => {
+    console.log(JSON.stringify(inspectClawpoolAdminConfig(params.api.config), null, 2));
+  });
+  root.command("create-agent").description("Create a Clawpool API agent and print the exact next steps for channel binding").requiredOption("--agent-name <name>", "New API agent name").option("--account-id <id>", "Configured Clawpool account id").option("--avatar-url <url>", "Optional avatar URL").action(
+    async (options) => {
+      const result = await createClawpoolApiAgent({
+        cfg: params.api.config,
+        toolParams: options
+      });
+      console.log(JSON.stringify(result, null, 2));
+    }
+  );
+}
+
+// src/json-result.ts
+function jsonToolResult(payload) {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload, null, 2) }],
+    details: payload
+  };
+}
+
+// src/agent-admin-tool.ts
+var ClawpoolAgentAdminToolSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    accountId: { type: "string", minLength: 1 },
+    agentName: {
+      type: "string",
+      pattern: "^[a-z][a-z0-9-]{2,31}$",
+      description: "Lowercase API agent name."
+    },
+    avatarUrl: { type: "string", minLength: 1 }
+  },
+  required: ["agentName"]
+};
+function createClawpoolAgentAdminTool(api) {
+  return {
+    name: "clawpool_agent_admin",
+    label: "Clawpool Agent Admin",
+    description: "Create Clawpool API agents with typed parameters. This tool does not modify local OpenClaw channel config.",
+    parameters: ClawpoolAgentAdminToolSchema,
+    async execute(_toolCallId, params) {
+      try {
+        return jsonToolResult(
+          await createClawpoolApiAgent({
+            cfg: api.config,
+            toolParams: params
+          })
+        );
+      } catch (err) {
+        return jsonToolResult({
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  };
+}
+
+// src/group-service.ts
+function mapGroupActionToRequestAction(action) {
+  switch (action) {
+    case "create":
+      return "group_create";
+    case "detail":
+      return "group_detail_read";
+    case "add_members":
+      return "group_member_add";
+    case "remove_members":
+      return "group_member_remove";
+    case "update_member_role":
+      return "group_member_role_update";
+    case "dissolve":
+      return "group_dissolve";
+    default:
+      action;
+      throw new Error(`Unsupported Clawpool group action: ${String(action)}`);
+  }
+}
+async function runClawpoolGroupAction(params) {
+  const account = resolveClawpoolAccount({
+    cfg: params.cfg,
+    accountId: params.toolParams.accountId
+  });
+  if (!account.enabled) {
+    throw new Error(`Clawpool account "${account.accountId}" is disabled.`);
+  }
+  if (!account.configured) {
+    throw new Error(`Clawpool account "${account.accountId}" is not configured.`);
+  }
+  const requestAction = mapGroupActionToRequestAction(params.toolParams.action);
+  const request = buildAgentHTTPRequest(requestAction, params.toolParams);
+  const data = await callAgentAPI({
+    account,
+    actionName: request.actionName,
+    method: request.method,
+    path: request.path,
+    query: request.query,
+    body: request.body
+  });
+  return {
+    ok: true,
+    accountId: account.accountId,
+    action: params.toolParams.action,
+    data
+  };
+}
+
+// src/group-tool.ts
+var numericIdSchema = {
+  type: "string",
+  pattern: "^[0-9]+$"
+};
+var ClawpoolGroupToolSchema = {
+  oneOf: [
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "create" },
+        accountId: { type: "string", minLength: 1 },
+        name: { type: "string", minLength: 1 },
+        memberIds: { type: "array", items: numericIdSchema },
+        memberTypes: { type: "array", items: { type: "integer", enum: [1, 2] } }
+      },
+      required: ["action", "name"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "detail" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 }
+      },
+      required: ["action", "sessionId"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "add_members" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 },
+        memberIds: { type: "array", items: numericIdSchema, minItems: 1 },
+        memberTypes: { type: "array", items: { type: "integer", enum: [1, 2] } }
+      },
+      required: ["action", "sessionId", "memberIds"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "remove_members" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 },
+        memberIds: { type: "array", items: numericIdSchema, minItems: 1 },
+        memberTypes: { type: "array", items: { type: "integer", enum: [1, 2] } }
+      },
+      required: ["action", "sessionId", "memberIds"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "update_member_role" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 },
+        memberId: numericIdSchema,
+        memberType: { type: "integer", enum: [1] },
+        role: { type: "integer", enum: [1, 2] }
+      },
+      required: ["action", "sessionId", "memberId", "role"]
+    },
+    {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        action: { const: "dissolve" },
+        accountId: { type: "string", minLength: 1 },
+        sessionId: { type: "string", minLength: 1 }
+      },
+      required: ["action", "sessionId"]
+    }
+  ]
+};
+function createClawpoolGroupTool(api) {
+  return {
+    name: "clawpool_group",
+    label: "Clawpool Group",
+    description: "Manage Clawpool groups through typed admin operations. This tool only handles group lifecycle and membership changes.",
+    parameters: ClawpoolGroupToolSchema,
+    async execute(_toolCallId, params) {
+      try {
+        return jsonToolResult(
+          await runClawpoolGroupAction({
+            cfg: api.config,
+            toolParams: params
+          })
+        );
+      } catch (err) {
+        return jsonToolResult({
+          error: err instanceof Error ? err.message : String(err)
+        });
+      }
+    }
+  };
+}
+
+// index.ts
+var plugin = {
+  id: "clawpool-admin",
+  name: "Clawpool Admin",
+  description: "Typed optional admin tools and operator CLI for Clawpool",
+  configSchema: emptyPluginConfigSchema(),
+  register(api) {
+    api.registerTool(createClawpoolGroupTool(api), { optional: true });
+    api.registerTool(createClawpoolAgentAdminTool(api), { optional: true });
+    api.registerCli(({ program }) => registerClawpoolAdminCli({ api, program }), {
+      commands: ["clawpool-admin"]
+    });
+  }
+};
+var index_default = plugin;
+export {
+  index_default as default
+};

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,58 @@
+{
+  "name": "@dhfpub/clawpool-admin",
+  "version": "0.1.0",
+  "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/aibot.git",
+    "directory": "openclaw_plugins/clawpool-admin"
+  },
+  "bugs": {
+    "url": "https://github.com/askie/aibot/issues"
+  },
+  "homepage": "https://github.com/askie/aibot/tree/main/openclaw_plugins/clawpool-admin#readme",
+  "files": [
+    "LICENSE",
+    "README.md",
+    "openclaw.plugin.json",
+    "dist/index.js",
+    "skills"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "clean": "node -e \"const fs=require('node:fs'); fs.rmSync('dist', { recursive: true, force: true });\"",
+    "build": "npm run clean && esbuild index.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/index.js --external:openclaw --external:openclaw/*",
+    "pack:dry-run": "npm run build && npm pack --dry-run --ignore-scripts",
+    "prepack": "npm run build",
+    "test": "node --test src/*.test.ts"
+  },
+  "devDependencies": {
+    "esbuild": "0.27.4"
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ],
+    "install": {
+      "npmSpec": "@dhfpub/clawpool-admin",
+      "localPath": "openclaw_plugins/clawpool-admin",
+      "defaultChoice": "npm"
+    }
+  }
+}

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

@@ -0,0 +1,63 @@
+---
+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.
+---
+
+# 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.
+
+## 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
+
+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.
+
+## 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. Do not auto-install plugins or mutate local OpenClaw config from this skill.
+
+## 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. 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`.
+
+## 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 plugins enable clawpool`
+2. `openclaw channels add --channel clawpool ...`
+3. `openclaw gateway restart`

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

@@ -0,0 +1,118 @@
+---
+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`, 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`, `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`, and `role` 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.
+
+### 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) 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,71 @@
+# 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` |
+| `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.