@cozeclaw/coze-openclaw-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 coze-dev
+
+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,125 @@
+# @cozeclaw/coze-openclaw-plugin
+
+OpenClaw plugin that adds Coze-powered web tools and bundled media skills.
+
+- Tools: `coze_web_search`, `coze_web_fetch`
+- Skills: `coze-tts`, `coze-asr`, `coze-image-gen`
+
+## Install
+
+```bash
+openclaw plugins install @cozeclaw/coze-openclaw-plugin
+```
+
+## Configure
+
+This plugin requires:
+
+- `plugins.entries.coze-openclaw-plugin.config.apiKey`
+
+Minimal configuration:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "coze-openclaw-plugin": {
+        enabled: true,
+        config: {
+          apiKey: "YOUR_COZE_API_KEY"
+        }
+      }
+    }
+  }
+}
+```
+
+Optional config fields:
+
+- `baseUrl`
+- `modelBaseUrl`
+- `retryTimes`
+- `retryDelay`
+- `timeout`
+
+## Replace Built-in Web Tools
+
+If you want to use this plugin instead of OpenClaw built-in web search and fetch:
+
+```json5
+{
+  plugins: {
+    entries: {
+      "coze-openclaw-plugin": {
+        enabled: true,
+        config: {
+          apiKey: "YOUR_COZE_API_KEY"
+        }
+      }
+    }
+  },
+  tools: {
+    web: {
+      search: {
+        enabled: false
+      },
+      fetch: {
+        enabled: false
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+### `coze_web_search`
+
+Search the web or images through Coze.
+
+Parameters:
+
+- `query`
+- `type`: `web` or `image`
+- `count`
+- `timeRange`
+- `sites`
+- `blockHosts`
+- `needSummary`
+- `needContent`
+
+### `coze_web_fetch`
+
+Fetch and normalize page or document content through Coze.
+
+Parameters:
+
+- `urls`
+- `format`: `text`, `markdown`, or `json`
+- `textOnly`
+
+## Skills
+
+Bundled skills:
+
+- `coze-tts`: text to speech
+- `coze-asr`: speech to text
+- `coze-image-gen`: image generation
+
+Example commands:
+
+```bash
+node {baseDir}/scripts/tts.mjs --text "Hello from Coze"
+node {baseDir}/scripts/asr.mjs --url "https://example.com/audio.mp3"
+node {baseDir}/scripts/gen.mjs --prompt "A futuristic city at sunset"
+```
+
+## Notes
+
+- The plugin requires `apiKey` in plugin config and does not fall back to `COZE_*` environment variables
+- Skill visibility depends on `plugins.entries.coze-openclaw-plugin.config.apiKey`
+- `coze_web_fetch` fetches URLs sequentially
+
+## License
+
+MIT

package/index.test.ts

@@ -0,0 +1,63 @@
+import fs from "node:fs";
+import path from "node:path";
+import { describe, expect, it, vi } from "vitest";
+import plugin from "./index.js";
+
+describe("coze-openclaw-plugin plugin", () => {
+  it("registers coze web tools", () => {
+    const registerTool = vi.fn();
+
+    plugin.register?.({
+      id: "coze-openclaw-plugin",
+      name: "Coze OpenClaw Plugin",
+      description: "Coze OpenClaw",
+      source: "test",
+      config: {},
+      pluginConfig: {},
+      runtime: {} as never,
+      logger: {
+        debug() {},
+        info() {},
+        warn() {},
+        error() {},
+      },
+      registerTool,
+      registerHook() {},
+      registerHttpRoute() {},
+      registerChannel() {},
+      registerGatewayMethod() {},
+      registerCli() {},
+      registerService() {},
+      registerProvider() {},
+      registerCommand() {},
+      registerContextEngine() {},
+      resolvePath(input: string) {
+        return input;
+      },
+      on() {},
+    });
+
+    expect(registerTool).toHaveBeenCalledTimes(2);
+    const toolNames = registerTool.mock.calls
+      .map((call) => {
+        const tool = call[0];
+        return typeof tool === "function" ? undefined : tool.name;
+      })
+      .filter(Boolean);
+    expect(toolNames).toEqual(["coze_web_search", "coze_web_fetch"]);
+  });
+
+  it("declares bundled skills in the plugin manifest", () => {
+    const manifestPath = path.join(
+      process.cwd(),
+      "extensions/coze-openclaw-plugin/openclaw.plugin.json",
+    );
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf-8")) as {
+      id: string;
+      skills?: string[];
+    };
+
+    expect(manifest.id).toBe("coze-openclaw-plugin");
+    expect(manifest.skills).toEqual(["./skills"]);
+  });
+});

package/index.ts

@@ -0,0 +1,25 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk/core";
+import { createCozeWebFetchTool } from "./src/tools/web-fetch.js";
+import { createCozeWebSearchTool } from "./src/tools/web-search.js";
+
+const plugin = {
+  id: "coze-openclaw-plugin",
+  name: "Coze OpenClaw Plugin",
+  description: "Coze web tools and bundled generation skills for OpenClaw.",
+  register(api: OpenClawPluginApi) {
+    api.registerTool(
+      createCozeWebSearchTool({
+        pluginConfig: api.pluginConfig,
+        logger: api.logger,
+      }),
+    );
+    api.registerTool(
+      createCozeWebFetchTool({
+        pluginConfig: api.pluginConfig,
+        logger: api.logger,
+      }),
+    );
+  },
+};
+
+export default plugin;

package/openclaw.plugin.json

@@ -0,0 +1,57 @@
+{
+  "id": "coze-openclaw-plugin",
+  "name": "Coze OpenClaw Plugin",
+  "description": "Coze web tools and bundled generation skills for OpenClaw.",
+  "skills": ["./skills"],
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "required": ["apiKey"],
+    "properties": {
+      "apiKey": {
+        "type": "string"
+      },
+      "baseUrl": {
+        "type": "string"
+      },
+      "modelBaseUrl": {
+        "type": "string"
+      },
+      "retryTimes": {
+        "type": "number"
+      },
+      "retryDelay": {
+        "type": "number"
+      },
+      "timeout": {
+        "type": "number"
+      }
+    }
+  },
+  "uiHints": {
+    "apiKey": {
+      "label": "Coze API Key",
+      "sensitive": true
+    },
+    "baseUrl": {
+      "label": "Coze Base URL",
+      "advanced": true
+    },
+    "modelBaseUrl": {
+      "label": "Coze Model Base URL",
+      "advanced": true
+    },
+    "retryTimes": {
+      "label": "Retry Times",
+      "advanced": true
+    },
+    "retryDelay": {
+      "label": "Retry Delay (ms)",
+      "advanced": true
+    },
+    "timeout": {
+      "label": "Request Timeout (ms)",
+      "advanced": true
+    }
+  }
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@cozeclaw/coze-openclaw-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw Coze tools and bundled skills",
+  "type": "module",
+  "devDependencies": {
+    "openclaw": "v2026.2.6"
+  },
+  "dependencies": {
+    "@sinclair/typebox": "0.34.48",
+    "coze-coding-dev-sdk": "0.7.17",
+    "json5": "2.2.3",
+    "jiti": "2.6.1"
+  },
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@cozeclaw/coze-openclaw-plugin",
+      "localPath": "extensions/coze-openclaw-plugin",
+      "defaultChoice": "npm"
+    }
+  }
+}

package/skills/coze-asr/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: coze-asr
+description: Convert speech audio to text using Coze ASR. Use when you need to transcribe spoken content from a remote audio URL or a local audio file into plain text.
+homepage: https://www.coze.com
+metadata: { "openclaw": { "emoji": "🎙️", "requires": { "bins": ["node"], "config": ["plugins.entries.coze-openclaw-plugin.config.apiKey"] } } }
+---
+
+# Coze ASR
+
+Transcribe audio from a URL or local file using Coze ASR.
+
+## Quick start
+
+```bash
+node {baseDir}/scripts/asr.mjs --url "https://example.com/audio.mp3"
+node {baseDir}/scripts/asr.mjs --file ./recording.mp3
+```
+
+## Options
+
+- `--url <url>` remote audio URL
+- `--file <path>` local audio file
+
+## Notes
+
+- The skill runtime requires `plugins.entries.coze-openclaw-plugin.config.apiKey`.
+- Local files are read and uploaded as base64 audio content.

package/skills/coze-asr/scripts/asr.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import createJiti from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const { runAsrCli } = await jiti.import("../../../src/skill-cli.ts");
+
+const code = await runAsrCli(process.argv.slice(2), process.env);
+process.exit(code);

package/skills/coze-image-gen/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: coze-image-gen
+description: Generate one or more images from text prompts using Coze image generation. Use when you need to create images from a natural-language prompt, produce multiple image variants, or generate sequential frames from the same prompt.
+homepage: https://www.coze.com
+metadata: { "openclaw": { "emoji": "🎨", "requires": { "bins": ["node"], "config": ["plugins.entries.coze-openclaw-plugin.config.apiKey"] } } }
+---
+
+# Coze Image Generation
+
+Generate one or more images from a prompt using Coze.
+
+## Quick start
+
+```bash
+node {baseDir}/scripts/gen.mjs --prompt "A futuristic city at sunset"
+node {baseDir}/scripts/gen.mjs --prompt "A serene mountain landscape" --count 2 --size 4K
+node {baseDir}/scripts/gen.mjs --prompt "A hero's journey through magical lands" --sequential --max-sequential 5
+```
+
+## Options
+
+- `--prompt <text>` required prompt text
+- `--count <n>` number of generations, default `1`
+- `--size <size>` image size, default `2K`
+- `--sequential` enable sequential image generation
+- `--max-sequential <n>` max sequential frames, default `5`
+
+## Notes
+
+- The skill runtime requires `plugins.entries.coze-openclaw-plugin.config.apiKey`.
+- URLs are printed directly and are suitable for immediate use.

package/skills/coze-image-gen/scripts/gen.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import createJiti from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const { runImageCli } = await jiti.import("../../../src/skill-cli.ts");
+
+const code = await runImageCli(process.argv.slice(2), process.env);
+process.exit(code);

package/skills/coze-tts/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: coze-tts
+description: Convert text to speech using Coze TTS. Use when you need to synthesize spoken audio from one text input or multiple text segments, optionally with a specific speaker, format, sample rate, or speech settings.
+homepage: https://www.coze.com
+metadata: { "openclaw": { "emoji": "🔊", "requires": { "bins": ["node"], "config": ["plugins.entries.coze-openclaw-plugin.config.apiKey"] } } }
+---
+
+# Coze TTS
+
+Generate speech audio URLs from text using Coze TTS.
+
+## Quick start
+
+```bash
+node {baseDir}/scripts/tts.mjs --text "Hello, welcome to our service"
+node {baseDir}/scripts/tts.mjs --texts "Chapter 1" "Chapter 2" --speaker zh_male_m191_uranus_bigtts
+node {baseDir}/scripts/tts.mjs --text "Fast announcement" --speech-rate 30 --format mp3 --sample-rate 48000
+```
+
+## Options
+
+- `--text <text>` single text input
+- `--texts <texts...>` multiple text inputs
+- `--speaker <id>` speaker id
+- `--format <fmt>` `mp3`, `pcm`, or `ogg_opus`
+- `--sample-rate <hz>` sample rate
+- `--speech-rate <n>` speech rate adjustment
+- `--loudness-rate <n>` loudness adjustment
+
+## Notes
+
+- The skill runtime requires `plugins.entries.coze-openclaw-plugin.config.apiKey`.
+- The script prints one audio URL per generated segment.

package/skills/coze-tts/scripts/tts.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import createJiti from "jiti";
+
+const jiti = createJiti(import.meta.url);
+const { runTtsCli } = await jiti.import("../../../src/skill-cli.ts");
+
+const code = await runTtsCli(process.argv.slice(2), process.env);
+process.exit(code);

package/src/client.ts

@@ -0,0 +1,71 @@
+import type { CozeConfig } from "coze-coding-dev-sdk";
+
+type CozeSdkModule = typeof import("coze-coding-dev-sdk");
+type ConfigurableClientConstructor<TClient> = new (
+  config: InstanceType<CozeSdkModule["Config"]>,
+) => TClient;
+
+let sdkPromise: Promise<CozeSdkModule> | null = null;
+
+export type CozeClientFactoryParams = {
+  config: CozeConfig;
+};
+
+export async function loadCozeSdk(): Promise<CozeSdkModule> {
+  if (!sdkPromise) {
+    sdkPromise = import("coze-coding-dev-sdk");
+  }
+  return sdkPromise;
+}
+
+async function createClient<TClient>(
+  params: CozeClientFactoryParams,
+  resolveCtor: (sdk: CozeSdkModule) => ConfigurableClientConstructor<TClient>,
+): Promise<TClient> {
+  const sdk = await loadCozeSdk();
+  const Client = resolveCtor(sdk);
+  return new Client(new sdk.Config(params.config));
+}
+
+export async function createSearchClient(
+  params: CozeClientFactoryParams,
+): Promise<InstanceType<CozeSdkModule["SearchClient"]>> {
+  return createClient(params, (sdk) => sdk.SearchClient);
+}
+
+export async function createFetchClient(
+  params: CozeClientFactoryParams,
+): Promise<InstanceType<CozeSdkModule["FetchClient"]>> {
+  return createClient(params, (sdk) => sdk.FetchClient);
+}
+
+export async function createImageGenerationClient(
+  params: CozeClientFactoryParams,
+): Promise<InstanceType<CozeSdkModule["ImageGenerationClient"]>> {
+  return createClient(params, (sdk) => sdk.ImageGenerationClient);
+}
+
+export async function createTtsClient(
+  params: CozeClientFactoryParams,
+): Promise<InstanceType<CozeSdkModule["TTSClient"]>> {
+  return createClient(params, (sdk) => sdk.TTSClient);
+}
+
+export async function createAsrClient(
+  params: CozeClientFactoryParams,
+): Promise<InstanceType<CozeSdkModule["ASRClient"]>> {
+  return createClient(params, (sdk) => sdk.ASRClient);
+}
+
+export function formatCozeError(error: unknown): string {
+  if (error && typeof error === "object" && "message" in error) {
+    const message = String(error.message);
+    const status =
+      "statusCode" in error && typeof error.statusCode === "number" ? ` (${error.statusCode})` : "";
+    return `${message}${status}`;
+  }
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

package/src/config.test.ts

@@ -0,0 +1,130 @@
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  loadCozePluginConfigFromOpenClawConfig,
+  resolveCozeClientConfig,
+  resolveOpenClawConfigPath,
+} from "./config.js";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  await Promise.all(tempDirs.splice(0, tempDirs.length).map((dir) => fs.rm(dir, { recursive: true, force: true })));
+});
+
+describe("resolveCozeClientConfig", () => {
+  it("reads values from plugin config", () => {
+    const result = resolveCozeClientConfig(
+      {
+        apiKey: "plugin-key",
+        baseUrl: "https://plugin.example.com",
+        modelBaseUrl: "https://plugin-model.example.com",
+        timeout: 3000,
+      },
+      {} as NodeJS.ProcessEnv,
+    );
+
+    expect(result).toMatchObject({
+      apiKey: "plugin-key",
+      baseUrl: "https://plugin.example.com",
+      modelBaseUrl: "https://plugin-model.example.com",
+      timeout: 3000,
+    });
+  });
+
+  it("does not fall back to environment variables", () => {
+    const result = resolveCozeClientConfig({}, {
+      COZE_API_KEY: "env-key",
+      COZE_BASE_URL: "https://env.example.com",
+      COZE_MODEL_BASE_URL: "https://env-model.example.com",
+      COZE_RETRY_TIMES: "3",
+      COZE_RETRY_DELAY: "100",
+      COZE_TIMEOUT: "3000",
+    } as NodeJS.ProcessEnv);
+
+    expect(result).toEqual({
+      apiKey: undefined,
+      baseUrl: undefined,
+      modelBaseUrl: undefined,
+      retryTimes: undefined,
+      retryDelay: undefined,
+      timeout: undefined,
+    });
+  });
+
+  it("resolves the OpenClaw config path from OPENCLAW_CONFIG_PATH", () => {
+    expect(
+      resolveOpenClawConfigPath({
+        OPENCLAW_CONFIG_PATH: "~/custom/openclaw.json",
+        HOME: "/tmp/example-home",
+      } as NodeJS.ProcessEnv),
+    ).toBe(path.join("/tmp/example-home", "custom", "openclaw.json"));
+  });
+
+  it("loads plugin config from the OpenClaw config file", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "coze-openclaw-plugin-config-"));
+    tempDirs.push(tempDir);
+    const configPath = path.join(tempDir, "openclaw.json");
+
+    await fs.writeFile(
+      configPath,
+      `{
+        plugins: {
+          entries: {
+            "coze-openclaw-plugin": {
+              config: {
+                apiKey: "plugin-key",
+                baseUrl: "https://plugin.example.com",
+              },
+            },
+          },
+        },
+      }`,
+      "utf-8",
+    );
+
+    const result = await loadCozePluginConfigFromOpenClawConfig({
+      OPENCLAW_CONFIG_PATH: configPath,
+    } as NodeJS.ProcessEnv);
+
+    expect(result).toEqual({
+      apiKey: "plugin-key",
+      baseUrl: "https://plugin.example.com",
+      modelBaseUrl: undefined,
+      retryTimes: undefined,
+      retryDelay: undefined,
+      timeout: undefined,
+    });
+  });
+
+  it("resolves env templates from the OpenClaw config file", async () => {
+    const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "coze-openclaw-plugin-config-"));
+    tempDirs.push(tempDir);
+    const configPath = path.join(tempDir, "openclaw.json");
+
+    await fs.writeFile(
+      configPath,
+      `{
+        plugins: {
+          entries: {
+            "coze-openclaw-plugin": {
+              config: {
+                apiKey: "\${COZE_WORKLOAD_IDENTITY_API_KEY}",
+              },
+            },
+          },
+        },
+      }`,
+      "utf-8",
+    );
+
+    const result = await loadCozePluginConfigFromOpenClawConfig({
+      OPENCLAW_CONFIG_PATH: configPath,
+      COZE_WORKLOAD_IDENTITY_API_KEY: "workload-key",
+    } as NodeJS.ProcessEnv);
+
+    expect(result?.apiKey).toBe("workload-key");
+  });
+});