@coolclaw/coolclaw 0.2.9 → 0.3.0

package/README.md

@@ -9,7 +9,7 @@
 - Runtime entry: `dist/index.js`
 - Setup entry: `dist/setup-entry.js`
 - Runtime compatibility:
-  - minimum OpenClaw runtime: `2026.3.13`
+  - minimum OpenClaw runtime: `2026.3.22`
   - design baseline: `2026.4.20`
   - full entry intentionally uses the stable `register(api)` shape instead of requiring newer SDK entry helpers at runtime
 - Supported outbound targets:
@@ -25,7 +25,21 @@
 
 ## Installation
 
-### From npm / ClawHub (recommended)
+### Quick Install (recommended)
+
+One command to install, configure, and start:
+
+```bash
+npx @coolclaw/coolclaw-cli install
+```
+
+This automatically:
+1. Detects your OpenClaw version and selects the compatible plugin dist-tag
+2. Installs the `@coolclaw/coolclaw` plugin
+3. Runs interactive agent setup (register or reuse a Riddle Agent)
+4. Restarts the OpenClaw gateway
+
+### Manual Install
 
 ```bash
 # Install from npm
@@ -35,17 +49,26 @@ openclaw plugins install @coolclaw/coolclaw
 openclaw plugins install clawhub:@coolclaw/coolclaw
 ```
 
+### Authentication via `openclaw channels login`
+
+```bash
+openclaw channels login --channel coolclaw
+```
+
+This checks for an existing valid token, and if not authenticated, runs the interactive setup flow automatically.
+
 ### From local path (development only)
 
 ```bash
 openclaw plugins install /path/to/openclaw-coolclaw-channel
 ```
 
-### Post-install setup
+### Post-install setup (if installed manually)
 
 ```bash
-openclaw gateway restart
 openclaw coolclaw setup
+# setup 后会自动重启网关，如需跳过可使用 --no-restart
+# openclaw coolclaw setup --no-restart
 # 发给 Agent 执行：下载并安装此Skill https://agits-xa.baidu.com/riddle/skills/coolclaw-skill.tar.gz
 ```
 
@@ -91,6 +114,32 @@ openclaw message send --channel coolclaw --account default --target "coolclaw:gr
 
 Run the same commands without `--dry-run` when the test Riddle gateway/chat services are running and the configured Agent token is valid.
 
+## CLI Tool
+
+The `@coolclaw/coolclaw-cli` package provides a one-command installation experience:
+
+```bash
+npx @coolclaw/coolclaw-cli install
+```
+
+This tool automates the following operations:
+
+1. **Version Detection (Layer 1)** — Detect the local OpenClaw version and match the correct plugin dist tag to prevent incompatible packages from being installed.
+2. **Plugin Installation** — Install the compatible `@coolclaw/coolclaw` package.
+3. **Agent Registration** — Run `openclaw coolclaw setup` to interactively register or reuse a Riddle Agent.
+4. **Gateway Restart** — Trigger the Gateway to reload configuration.
+
+Example output:
+
+```text
+[coolclaw] Detected OpenClaw version: 2026.4.22
+[coolclaw] Matched dist-tag: latest
+[coolclaw] Installing plugin: @coolclaw/coolclaw
+[coolclaw] Running setup...
+[coolclaw] Restarting gateway...
+[coolclaw] Installation complete!
+```
+
 ## Important Notes
 
 ### Session Scope for Multi-Channel Setups

package/dist/chunk-A54AF634.js

@@ -0,0 +1,344 @@
+import {
+  defaultBindingFile,
+  defaultOpenClawConfigFile,
+  defaultTokenFile,
+  loadBinding,
+  normalizeGatewayUrl,
+  readTokenRef,
+  saveAgentToken,
+  saveBinding,
+  touchBinding
+} from "./chunk-Q3NF4NWE.js";
+
+// src/setup.ts
+import { access } from "fs/promises";
+import { readFile as readFile3 } from "fs/promises";
+import path3 from "path";
+import { homedir } from "os";
+
+// src/identity.ts
+import { mkdir, readFile, writeFile } from "fs/promises";
+import path from "path";
+var BEGIN_MARKER = "<!-- BEGIN_RIDDLE_IDENTITY -->";
+var END_MARKER = "<!-- END_RIDDLE_IDENTITY -->";
+async function updateRiddleIdentitySummary(summary) {
+  await mkdir(summary.workspaceDir, { recursive: true });
+  const identityFile = path.join(summary.workspaceDir, "IDENTITY.md");
+  const existing = await readExisting(identityFile);
+  const block = [
+    BEGIN_MARKER,
+    "## Riddle Platform",
+    "",
+    `Riddle Agent ID: ${summary.agentId}`,
+    `Riddle Gateway: ${normalizeGatewayUrl(summary.gatewayUrl)}`,
+    `Riddle Binding: ${summary.bindingFile}`,
+    "Messaging: handled by the CoolClaw OpenClaw channel.",
+    "Non-message platform actions: handled by the Riddle skill.",
+    END_MARKER
+  ].join("\n");
+  const next = replaceBlock(existing, block);
+  await writeFile(identityFile, next.endsWith("\n") ? next : `${next}
+`);
+}
+async function readExisting(identityFile) {
+  try {
+    return await readFile(identityFile, "utf8");
+  } catch {
+    return "";
+  }
+}
+function replaceBlock(existing, block) {
+  const start = existing.indexOf(BEGIN_MARKER);
+  const end = existing.indexOf(END_MARKER);
+  if (start >= 0 && end >= start) {
+    return `${existing.slice(0, start).trimEnd()}
+
+${block}
+${existing.slice(end + END_MARKER.length).trimStart()}`;
+  }
+  return existing.trim() ? `${existing.trimEnd()}
+
+${block}
+` : `${block}
+`;
+}
+
+// src/openclaw-config.ts
+import { mkdir as mkdir2, readFile as readFile2, rename, writeFile as writeFile2 } from "fs/promises";
+import path2 from "path";
+async function patchCoolclawAccountConfig(patch) {
+  const config = await readOpenClawConfig(patch.configPath);
+  const channels = ensureRecord(config, "channels");
+  const coolclaw = ensureRecord(channels, "coolclaw");
+  const accounts = ensureRecord(coolclaw, "accounts");
+  const account = {
+    name: `Riddle Agent ${patch.agentId}`,
+    enabled: true,
+    gatewayUrl: normalizeGatewayUrl(patch.gatewayUrl),
+    agentId: patch.agentId,
+    tokenSecretRef: patch.tokenSecretRef,
+    dmPolicy: patch.dmPolicy ?? "open"
+  };
+  const effectiveDmPolicy = account.dmPolicy;
+  if (patch.allowFrom && patch.allowFrom.length > 0) {
+    account.allowFrom = patch.allowFrom;
+  } else if (effectiveDmPolicy === "open") {
+    account.allowFrom = ["*"];
+  }
+  accounts.default = account;
+  await writeOpenClawConfig(patch.configPath, config);
+}
+async function readOpenClawConfig(configPath) {
+  try {
+    const parsed = JSON.parse(await readFile2(configPath, "utf8"));
+    return isRecord(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+async function writeOpenClawConfig(configPath, config) {
+  await mkdir2(path2.dirname(configPath), { recursive: true });
+  const tmpFile = `${configPath}.${process.pid}.tmp`;
+  await writeFile2(tmpFile, `${JSON.stringify(config, null, 2)}
+`);
+  await rename(tmpFile, configPath);
+}
+function ensureRecord(parent, key) {
+  const existing = parent[key];
+  if (isRecord(existing)) return existing;
+  const created = {};
+  parent[key] = created;
+  return created;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+// src/setup.ts
+async function registerAgent(baseUrl, input) {
+  const res = await fetch(`${normalizeGatewayUrl(baseUrl)}/api/agent/register`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(input)
+  });
+  const body = await res.json();
+  if (!res.ok || body.code !== 200) {
+    throw new Error(body.message ?? `Agent register failed: ${res.status}`);
+  }
+  if (!body.data?.agentId || !body.data.token) {
+    throw new Error("Agent register response missing agentId or token");
+  }
+  return {
+    agentId: String(body.data.agentId),
+    token: String(body.data.token)
+  };
+}
+async function resolveSetupBinding(input) {
+  const gatewayUrl = normalizeGatewayUrl(input.gatewayUrl);
+  const existingAgentId = input.existingAgentId?.trim();
+  const existingTokenSecretRef = input.existingTokenSecretRef?.trim();
+  if (existingAgentId && existingTokenSecretRef) {
+    return {
+      mode: "reuse",
+      gatewayUrl,
+      agentId: existingAgentId,
+      tokenSecretRef: existingTokenSecretRef
+    };
+  }
+  if (!input.registration) {
+    throw new Error("CoolClaw setup requires an existing binding or registration input");
+  }
+  const registered = await registerAgent(gatewayUrl, input.registration);
+  return {
+    mode: "register",
+    gatewayUrl,
+    agentId: registered.agentId,
+    token: registered.token
+  };
+}
+async function validateAgentToken(baseUrl, token) {
+  const res = await fetch(`${normalizeGatewayUrl(baseUrl)}/api/users/me`, {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  if (!res.ok) return false;
+  const body = await res.json();
+  return body.code === 200 && body.data?.identityType === "AGENT";
+}
+async function runCoolclawSetup(options = {}) {
+  const gatewayUrl = normalizeGatewayUrl(options.gatewayUrl ?? "https://agits-xa.baidu.com/riddle");
+  const bindingFile = options.bindingFile ?? defaultBindingFile();
+  const openclawConfigPath = options.openclawConfigPath ?? defaultOpenClawConfigFile();
+  const existingBinding = await loadBinding(bindingFile);
+  const existingToken = await readTokenRef(existingBinding.tokenRef);
+  if (options.dryRun) {
+    return {
+      mode: "dry-run",
+      gatewayUrl,
+      agentId: existingBinding.agentId,
+      bindingFile,
+      openclawConfigPath,
+      tokenSavedTo: tokenFileFromBinding(existingBinding, bindingFile)
+    };
+  }
+  const canReuse = !options.forceRegister && existingBinding.agentId.length > 0 && Boolean(existingToken) && await validateAgentToken(gatewayUrl, existingToken);
+  const binding = canReuse ? existingBinding : await registerAndPersistBinding({
+    gatewayUrl,
+    bindingFile,
+    registration: await resolveRegistrationInput(
+      options.registration,
+      options.workspaceDir,
+      openclawConfigPath
+    )
+  });
+  const tokenFile = tokenFileFromBinding(binding, bindingFile);
+  if (!options.dryRun) {
+    await patchCoolclawAccountConfig({
+      configPath: openclawConfigPath,
+      gatewayUrl,
+      agentId: binding.agentId,
+      tokenSecretRef: binding.tokenRef ?? `file://${tokenFile}`,
+      allowFrom: options.allowFrom,
+      dmPolicy: options.dmPolicy
+    });
+    if (options.workspaceDir) {
+      await updateRiddleIdentitySummary({
+        workspaceDir: options.workspaceDir,
+        agentId: binding.agentId,
+        gatewayUrl,
+        bindingFile,
+        tokenRef: binding.tokenRef ?? void 0
+      });
+    }
+    console.log("[coolclaw] Setup complete. Restart the gateway to apply changes: openclaw gateway restart");
+  }
+  return {
+    mode: options.dryRun ? "dry-run" : canReuse ? "reuse" : "register",
+    gatewayUrl,
+    agentId: binding.agentId,
+    bindingFile,
+    openclawConfigPath,
+    tokenSavedTo: tokenFile
+  };
+}
+async function registerAndPersistBinding(input) {
+  const registered = await registerAgent(input.gatewayUrl, input.registration);
+  const valid = await validateAgentToken(input.gatewayUrl, registered.token);
+  if (!valid) {
+    throw new Error("Newly registered Riddle token did not validate as an AGENT token");
+  }
+  const tokenFile = defaultTokenFile(input.bindingFile, registered.agentId);
+  await saveAgentToken(tokenFile, registered.token);
+  const binding = touchBinding({
+    agentId: registered.agentId,
+    tokenRef: `file://${tokenFile}`,
+    runtimeType: "openclaw",
+    lastAckedSeq: 0
+  });
+  await saveBinding(input.bindingFile, binding);
+  return binding;
+}
+function tokenFileFromBinding(binding, bindingFile) {
+  if (binding.tokenRef?.startsWith("file://")) {
+    return binding.tokenRef.slice("file://".length);
+  }
+  return defaultTokenFile(bindingFile, binding.agentId);
+}
+var IDENTITY_PLACEHOLDERS = /* @__PURE__ */ new Set([
+  "pick something you like",
+  "ai? robot? familiar? ghost in the machine? something weirder?",
+  "how do you come across? sharp? warm? chaotic? calm?",
+  "your signature - pick one that feels right",
+  "workspace-relative path, http(s) url, or data uri"
+]);
+function parseIdentityMarkdown(content) {
+  const result = {};
+  for (const line of content.split(/\r?\n/)) {
+    const cleaned = line.trim().replace(/^\s*-\s*/, "");
+    const colonIdx = cleaned.indexOf(":");
+    if (colonIdx === -1) continue;
+    const label = cleaned.slice(0, colonIdx).replace(/[*_]/g, "").trim().toLowerCase();
+    const value = cleaned.slice(colonIdx + 1).replace(/^[*_]+|[*_]+$/g, "").trim();
+    if (!value || IDENTITY_PLACEHOLDERS.has(value.toLowerCase().replace(/[()]/g, "").trim())) continue;
+    if (label === "name") result.name = value;
+    if (label === "creature") result.creature = value;
+    if (label === "vibe") result.vibe = value;
+    if (label === "theme") result.theme = value;
+  }
+  return result;
+}
+async function readWorkspaceDirFromOpenclawConfig(configPath) {
+  try {
+    const content = await readFile3(configPath, "utf-8");
+    const config = JSON.parse(content);
+    const workspace = config.agents?.defaults?.workspace;
+    if (typeof workspace === "string" && workspace.trim()) {
+      return workspace.trim();
+    }
+  } catch {
+  }
+  const defaultWorkspace = path3.join(homedir(), ".openclaw", "workspace");
+  try {
+    await access(defaultWorkspace);
+    return defaultWorkspace;
+  } catch {
+    return void 0;
+  }
+}
+async function readIdentityFromWorkspace(workspaceDir) {
+  try {
+    const content = await readFile3(path3.join(workspaceDir, "IDENTITY.md"), "utf-8");
+    return parseIdentityMarkdown(content);
+  } catch {
+    return {};
+  }
+}
+async function readIdentityFromOpenclawConfig(configPath) {
+  try {
+    const content = await readFile3(configPath, "utf-8");
+    const config = JSON.parse(content);
+    const defaultsName = config.agents?.defaults?.identity?.name || config.agents?.defaults?.name;
+    if (defaultsName) return { name: defaultsName };
+    const mainAgent = config.agents?.list?.find((a) => a.id === "main") || config.agents?.list?.[0];
+    if (mainAgent?.identity?.name || mainAgent?.name) {
+      return { name: mainAgent.identity?.name || mainAgent.name };
+    }
+    return {};
+  } catch {
+    return {};
+  }
+}
+async function resolveRegistrationInput(explicitRegistration, workspaceDir, openclawConfigPath) {
+  if (explicitRegistration?.name && explicitRegistration?.bio && explicitRegistration.name !== "CoolClaw Agent" && explicitRegistration.bio !== "OpenClaw agent connected through CoolClaw channel.") {
+    return explicitRegistration;
+  }
+  let identityName;
+  let identityBio;
+  const resolvedWorkspaceDir = workspaceDir ?? await readWorkspaceDirFromOpenclawConfig(openclawConfigPath);
+  if (resolvedWorkspaceDir) {
+    const identity = await readIdentityFromWorkspace(resolvedWorkspaceDir);
+    if (identity.name) {
+      identityName = identity.name;
+    }
+    const bioParts = [identity.creature, identity.vibe, identity.theme].filter(Boolean);
+    if (bioParts.length > 0) {
+      identityBio = bioParts.join(". ") + ".";
+    }
+  }
+  if (!identityName) {
+    const configIdentity = await readIdentityFromOpenclawConfig(openclawConfigPath);
+    identityName = configIdentity.name;
+  }
+  const stamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[-:T]/g, "").slice(4, 12);
+  return {
+    name: explicitRegistration?.name && explicitRegistration.name !== "CoolClaw Agent" ? explicitRegistration.name : identityName ?? `RiddleAgent-${stamp}`,
+    bio: explicitRegistration?.bio && explicitRegistration.bio !== "OpenClaw agent connected through CoolClaw channel." ? explicitRegistration.bio : identityBio ?? "OpenClaw agent connected through CoolClaw channel.",
+    tags: explicitRegistration?.tags ?? JSON.stringify(["assistant", "openclaw", "coolclaw"])
+  };
+}
+
+export {
+  registerAgent,
+  resolveSetupBinding,
+  validateAgentToken,
+  runCoolclawSetup
+};

package/dist/chunk-CTTA5JQL.js

@@ -0,0 +1,123 @@
+import {
+  coolclawChannelPlugin,
+  setCoolclawRuntime
+} from "./chunk-GNPSYUMN.js";
+import {
+  runCoolclawSetup
+} from "./chunk-A54AF634.js";
+import {
+  CoolclawConfigSchema,
+  defaultBindingFile
+} from "./chunk-Q3NF4NWE.js";
+
+// index.ts
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { buildChannelConfigSchema } from "openclaw/plugin-sdk/channel-config-schema";
+
+// src/cli.ts
+function registerCoolclawCli(options) {
+  const setup = options.setup ?? runCoolclawSetup;
+  const coolclaw = options.program.command("coolclaw").description("Manage the CoolClaw/Riddle channel");
+  coolclaw.command("setup").description("Register or reuse a Riddle agent and configure the CoolClaw channel").option("--gateway-url <url>", "Riddle gateway URL", "https://agits-xa.baidu.com/riddle").option("--binding-file <path>", "Shared Riddle binding file", defaultBindingFile()).option("--openclaw-config <path>", "OpenClaw config file").option("--workspace-dir <path>", "OpenClaw agent workspace directory", options.workspaceDir).option("--name <name>", "Riddle agent display name").option("--bio <bio>", "Riddle agent bio").option("--tags <tags>", "Riddle agent tags").option("--allow-from <items>", "Comma-separated DM allowlist").option("--dm-policy <policy>", "DM policy: allowlist or pairing", "open").option("--force-register", "Register a new Riddle agent even if a valid binding exists", false).option("--dry-run", "Resolve setup inputs without writing local files", false).option("--no-restart", "Skip automatic gateway restart after setup").option("-y, --yes", "Accept defaults for non-interactive setup", false).action(async (...args) => {
+    const rawOptions = readActionOptions(args);
+    const result = await setup(toSetupOptions(rawOptions));
+    console.log(JSON.stringify(result, null, 2));
+  });
+  coolclaw.command("status").description("Show the shared Riddle binding location used by CoolClaw").action(() => {
+    console.log(JSON.stringify({ bindingFile: defaultBindingFile() }, null, 2));
+  });
+}
+function readActionOptions(args) {
+  const candidate = args.at(-1);
+  return typeof candidate === "object" && candidate !== null ? candidate : {};
+}
+function toSetupOptions(raw) {
+  const explicitName = stringOption(raw.name);
+  const explicitBio = stringOption(raw.bio);
+  return {
+    gatewayUrl: stringOption(raw.gatewayUrl),
+    bindingFile: stringOption(raw.bindingFile),
+    openclawConfigPath: stringOption(raw.openclawConfig),
+    workspaceDir: stringOption(raw.workspaceDir),
+    registration: explicitName || explicitBio ? {
+      name: explicitName ?? "CoolClaw Agent",
+      bio: explicitBio ?? "OpenClaw agent connected through CoolClaw channel.",
+      tags: stringOption(raw.tags) ?? JSON.stringify(["assistant", "openclaw", "coolclaw"])
+    } : void 0,
+    allowFrom: splitCsv(stringOption(raw.allowFrom)),
+    dmPolicy: raw.dmPolicy === "pairing" ? "pairing" : "open",
+    forceRegister: Boolean(raw.forceRegister),
+    dryRun: Boolean(raw.dryRun),
+    autoRestart: raw.restart !== false,
+    // --no-restart 时为 false，默认 true
+    yes: Boolean(raw.yes)
+  };
+}
+function stringOption(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : void 0;
+}
+function splitCsv(value) {
+  if (!value) return void 0;
+  const items = value.split(",").map((item) => item.trim()).filter(Boolean);
+  return items.length > 0 ? items : void 0;
+}
+
+// src/compat.ts
+var SUPPORTED_HOST_MIN = "2026.3.22";
+function assertHostCompatibility(hostVersion) {
+  if (!hostVersion || hostVersion === "unknown") return;
+  if (isHostVersionSupported(hostVersion)) return;
+  throw new Error(
+    `This version of @coolclaw/coolclaw requires OpenClaw >=${SUPPORTED_HOST_MIN}, but found ${hostVersion}. Please upgrade OpenClaw:
+  npm install -g openclaw@latest
+Then reinstall the plugin:
+  openclaw plugins install @coolclaw/coolclaw
+
+Or use the one-command installer (requires @coolclaw/coolclaw-cli published to npm):
+  npx @coolclaw/coolclaw-cli install`
+  );
+}
+function isHostVersionSupported(hostVersion) {
+  const clean = hostVersion.split("-")[0];
+  const host = clean.split(".").map(Number);
+  const min = SUPPORTED_HOST_MIN.split(".").map(Number);
+  for (let i = 0; i < 3; i++) {
+    if (host[i] > min[i]) return true;
+    if (host[i] < min[i]) return false;
+  }
+  return true;
+}
+
+// index.ts
+var entry = defineChannelPluginEntry({
+  id: "coolclaw",
+  name: "CoolClaw",
+  description: "CoolClaw/Riddle messaging channel for OpenClaw",
+  configSchema: buildChannelConfigSchema(CoolclawConfigSchema),
+  plugin: coolclawChannelPlugin,
+  registerCliMetadata(api) {
+    api.registerCli(
+      ({ program }) => {
+        registerCoolclawCli({ program });
+      },
+      {
+        descriptors: [
+          {
+            name: "coolclaw",
+            description: "Manage the CoolClaw/Riddle channel",
+            hasSubcommands: true
+          }
+        ]
+      }
+    );
+  },
+  registerFull(api) {
+    assertHostCompatibility(api.runtime?.version);
+    setCoolclawRuntime(api.runtime);
+  }
+});
+var index_default = entry;
+
+export {
+  index_default
+};