openclaw-cloudflare-plugin 0.1.2

package/README.md

@@ -0,0 +1,99 @@
+# openclaw-cloudflare-plugin
+
+![npm version](https://img.shields.io/npm/v/openclaw-cloudflare-plugin)
+![npm downloads](https://img.shields.io/npm/dm/openclaw-cloudflare-plugin)
+![license](https://img.shields.io/npm/l/openclaw-cloudflare-plugin)
+![typescript](https://img.shields.io/badge/TypeScript-supported-blue)
+![GitHub stars](https://img.shields.io/github/stars/wuyangwang/openclaw-cloudflare-plugin)
+
+Cloudflare API wrapper plugin for **OpenClaw**, built on the Cloudflare TypeScript SDK.
+
+This plugin allows OpenClaw to interact with your Cloudflare account via chat commands.
+
+## Features (Current)
+
+Currently supported:
+
+* **KV**
+
+  * List KV namespaces
+
+> More features such as D1 and Workers management will be added in the future.
+
+---
+
+# Installation
+
+You need a **Cloudflare API Token** before installing.
+
+Create one here:
+https://developers.cloudflare.com/fundamentals/api/get-started/create-token/
+
+---
+
+## Step 1 — Install Plugin
+
+```bash
+openclaw install openclaw-cloudflare-plugin
+```
+
+---
+
+## Step 2 — Login with Cloudflare Token
+
+```bash
+openclaw cloudflare login --token <YOUR_API_TOKEN>
+```
+
+Example:
+
+```bash
+openclaw cloudflare login --token abc123
+```
+
+---
+
+## Step 3 — Verify Login (Optional)
+
+```bash
+openclaw cloudflare status
+```
+
+---
+
+# Usage
+
+1. Configure a **chat channel** supported by OpenClaw
+   Examples:
+
+* Discord
+* Telegram
+* Wecom Bot (企业微信机器人)
+
+2. Send a command in your chat channel
+
+Example:
+
+```
+Please show my Cloudflare KV list
+And:
+Get top 5 keys in first namespace
+```
+
+3. OpenClaw will query Cloudflare and return your KV namespaces.
+
+---
+
+# Roadmap
+
+Planned features:
+
+* KV CRUD
+* D1 database operations
+* Workers management
+
+---
+
+# License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,11 @@
+import { OpenClawPluginApi } from "openclaw/plugin-sdk";
+
+//#region index.d.ts
+declare const plugin: {
+  id: string;
+  name: string;
+  description: string;
+  register(api: OpenClawPluginApi): void;
+};
+//#endregion
+export { plugin as default };

package/dist/index.mjs

@@ -0,0 +1,222 @@
+import Cloudflare from "cloudflare";
+import { Type } from "typebox";
+//#region src/client.ts
+let clientCache = null;
+let lastApiToken = null;
+let resolvedAccountId = null;
+function getCloudflareClient(apiToken) {
+	if (clientCache && lastApiToken === apiToken) return clientCache;
+	clientCache = new Cloudflare({ apiToken });
+	lastApiToken = apiToken;
+	resolvedAccountId = null;
+	return clientCache;
+}
+async function getOrResolveAccountId(client, configuredAccountId) {
+	if (configuredAccountId) return configuredAccountId;
+	if (resolvedAccountId) return resolvedAccountId;
+	const firstAccount = (await client.accounts.list()).result?.[0];
+	if (!firstAccount?.id) throw new Error("No Cloudflare accounts found for this token.");
+	resolvedAccountId = firstAccount.id;
+	return resolvedAccountId;
+}
+//#endregion
+//#region src/probe.ts
+async function probeCloudflare(apiToken, configuredAccountId) {
+	if (!apiToken) return {
+		ok: false,
+		error: "Missing API Token"
+	};
+	try {
+		const client = getCloudflareClient(apiToken);
+		const verify = await client.user.tokens.verify();
+		if (verify.status !== "active") return {
+			ok: false,
+			error: `Token status: ${verify.status}`
+		};
+		return {
+			ok: true,
+			accountId: await getOrResolveAccountId(client, configuredAccountId)
+		};
+	} catch (err) {
+		return {
+			ok: false,
+			error: err instanceof Error ? err.message : String(err)
+		};
+	}
+}
+//#endregion
+//#region src/config.ts
+const PLUGIN_NAME = "openclaw-cloudflare-plugin";
+//#endregion
+//#region src/cli.ts
+function registerCloudflareCli(api, program) {
+	const cf = program.command("cloudflare").description("Cloudflare plugin management");
+	cf.command("login").description("Save Cloudflare API Token to configuration").option("--token <token>", "Cloudflare API Token").action(async (options) => {
+		const token = options.token;
+		if (!token || token.trim() === "") {
+			api.logger.error("please input token.");
+			return;
+		}
+		const probe = await probeCloudflare(token.trim(), options.account);
+		if (!probe.ok) {
+			api.logger.error(`❌ Error: ${probe.error}`);
+			return;
+		}
+		api.logger.info(`✅ Token is active. Auto-detected Account ID: ${probe.accountId}`);
+		if (!options.account) {}
+		const currentConfig = await api.runtime.config.loadConfig();
+		const nextConfig = {
+			...currentConfig,
+			plugins: {
+				...currentConfig.plugins,
+				entries: {
+					...currentConfig.plugins?.entries,
+					[PLUGIN_NAME]: {
+						enabled: true,
+						config: {
+							...currentConfig.plugins?.entries?.["openclaw-cloudflare-plugin"]?.config || {},
+							apiToken: token.trim(),
+							accountId: probe.accountId?.trim() || void 0
+						}
+					}
+				}
+			}
+		};
+		await api.runtime.config.writeConfigFile(nextConfig);
+		api.logger.info("✅ Cloudflare configuration has been saved.");
+	});
+	cf.command("status").description("Check Cloudflare configuration status").action(async () => {
+		const cfg = api.runtime.config.loadConfig().plugins?.entries?.[PLUGIN_NAME]?.config;
+		if (!cfg || !cfg.apiToken) {
+			api.logger.error("❌ Cloudflare is not configured. Run 'openclaw cloudflare login' first.");
+			return;
+		}
+		const probe = await probeCloudflare(cfg.apiToken);
+		if (probe.ok) {
+			api.logger.info("✅ Cloudflare is configured and active.");
+			api.logger.info(`   Account ID: ${probe.accountId}`);
+		} else api.logger.error(`❌ Cloudflare configuration error: ${probe.error}`);
+	});
+}
+//#endregion
+//#region src/kv.ts
+const ListKvNamespacesSchema = Type.Object({
+	page: Type.Optional(Type.Number({
+		description: "Page number of paginated results",
+		default: 1
+	})),
+	per_page: Type.Optional(Type.Number({
+		description: "Number of namespaces per page",
+		default: 10,
+		maximum: 50
+	}))
+});
+const ListKvKeysSchema = Type.Object({
+	namespace_id: Type.String({ description: "Cloudflare KV Namespace ID" }),
+	limit: Type.Optional(Type.Number({
+		description: "Maximum number of keys to return",
+		default: 10,
+		maximum: 50
+	})),
+	prefix: Type.Optional(Type.String({ description: "Filter keys by prefix" })),
+	cursor: Type.Optional(Type.String({ description: "Pagination cursor" }))
+});
+const GetKvValueSchema = Type.Object({
+	namespace_id: Type.String({ description: "Cloudflare KV Namespace ID" }),
+	key: Type.String({ description: "Key name" })
+});
+function json(data) {
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify(data, null, 2)
+		}],
+		details: data
+	};
+}
+function registerCloudflareKvTools(api) {
+	const getClientAndAccount = async () => {
+		const { apiToken, accountId: configuredAccountId } = api.config.plugins?.entries?.["openclaw-cloudflare-plugin"]?.config || {};
+		if (!apiToken) {
+			api.logger.error?.("Cloudflare apiToken not configured");
+			throw new Error("Cloudflare apiToken not configured");
+		}
+		const client = getCloudflareClient(apiToken);
+		return {
+			client,
+			accountId: await getOrResolveAccountId(client, configuredAccountId)
+		};
+	};
+	api.registerTool({
+		name: "cloudflare_kv_list_namespaces",
+		label: "Cloudflare List KV Namespaces",
+		description: "List all KV namespaces in the configured Cloudflare account",
+		parameters: ListKvNamespacesSchema,
+		async execute(_toolCallId, params) {
+			try {
+				const { client, accountId } = await getClientAndAccount();
+				return json(await client.kv.namespaces.list({
+					account_id: accountId,
+					page: params.page,
+					per_page: params.per_page
+				}));
+			} catch (err) {
+				return json({ error: err instanceof Error ? err.message : String(err) });
+			}
+		}
+	}, { name: "cloudflare_kv_list_namespaces" });
+	api.registerTool({
+		name: "cloudflare_kv_list_keys",
+		label: "Cloudflare List KV Keys",
+		description: "List keys in a specific Cloudflare KV namespace",
+		parameters: ListKvKeysSchema,
+		async execute(_toolCallId, params) {
+			try {
+				const { client, accountId } = await getClientAndAccount();
+				return json(await client.kv.namespaces.keys.list(params.namespace_id, {
+					account_id: accountId,
+					limit: params.limit,
+					prefix: params.prefix,
+					cursor: params.cursor
+				}));
+			} catch (err) {
+				return json({ error: err instanceof Error ? err.message : String(err) });
+			}
+		}
+	}, { name: "cloudflare_kv_list_keys" });
+	api.registerTool({
+		name: "cloudflare_kv_get_value",
+		label: "Cloudflare Get KV Value",
+		description: "Get the value of a specific key in a Cloudflare KV namespace",
+		parameters: GetKvValueSchema,
+		async execute(_toolCallId, params) {
+			try {
+				const { client, accountId } = await getClientAndAccount();
+				const res = await client.kv.namespaces.values.get(params.namespace_id, params.key, { account_id: accountId });
+				const value = typeof res === "string" ? res : await res.text();
+				return json({
+					key: params.key,
+					value
+				});
+			} catch (err) {
+				return json({ error: err instanceof Error ? err.message : String(err) });
+			}
+		}
+	}, { name: "cloudflare_kv_get_value" });
+	api.logger.info?.("Cloudflare tools registered");
+}
+//#endregion
+//#region index.ts
+const plugin = {
+	id: "openclaw-cloudflare-plugin",
+	name: "openclaw-cloudflare-plugin",
+	description: "Cloudflare wrapper for OpenClaw (KV, Workers, etc.)",
+	register(api) {
+		registerCloudflareKvTools(api);
+		api.registerCli(({ program }) => {
+			registerCloudflareCli(api, program);
+		});
+	}
+};
+//#endregion
+export { plugin as default };

package/openclaw.plugin.json

@@ -0,0 +1,19 @@
+{
+    "id": "openclaw-cloudflare-plugin",
+    "name": "openclaw-cloudflare-plugin",
+    "skills": ["./skills"],
+    "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+            "apiToken": {
+                "type": "string",
+                "description": "Cloudflare API token"
+            },
+            "accountId": {
+                "type": "string",
+                "description": "Cloudflare account ID"
+            }
+        }
+    }
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+    "name": "openclaw-cloudflare-plugin",
+    "version": "0.1.2",
+    "description": "Cloudflare wrapper for OpenClaw (KV, Workers, etc.)",
+    "author": "tardis",
+    "type": "module",
+    "main": "./dist/index.mjs",
+    "bin": {
+        "cf": "./dist/cli.mjs"
+    },
+    "files": [
+        "dist",
+        "openclaw.plugin.json",
+        "skills"
+    ],
+    "scripts": {
+        "build": "tsdown",
+        "dev": "tsdown --watch",
+        "cli": "tsx cli.ts",
+        "publish": "pnpm run build && bumpp",
+        "lint": "biome lint .",
+        "format": "biome format . --write",
+        "check": "biome check --write ."
+    },
+    "dependencies": {
+        "cloudflare": "^4.0.0",
+        "typebox": "^1.1.6",
+        "zod": "^4.3.6"
+    },
+    "peerDependencies": {
+        "commander": "^14.0.3",
+        "openclaw": "^2026.3.8"
+    },
+    "devDependencies": {
+        "@biomejs/biome": "^2.4.6",
+        "bumpp": "^10.4.1",
+        "cac": "^7.0.0",
+        "tsdown": "0.21.2",
+        "tsx": "^4.21.0",
+        "typescript": "^5.9.3"
+    },
+    "openclaw": {
+        "extensions": [
+            "./dist/index.mjs"
+        ]
+    }
+}

package/skills/cloudflare-kv/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: cloudflare-kv
+description: |
+  Cloudflare KV (Key-Value) storage management. Use this skill to list namespaces, keys, and retrieve values from Cloudflare.
+---
+
+# Cloudflare KV Tool
+
+Use the following tools to manage Cloudflare KV storage.
+
+## Actions
+
+### List Namespaces
+List all available KV namespaces. Use this to find the `namespace_id` for other tools.
+`cloudflare_kv_list_namespaces { "page": 1, "per_page": 20 }`
+
+### List Keys
+List keys within a specific namespace.
+`cloudflare_kv_list_keys { "namespace_id": "YOUR_NAMESPACE_ID", "limit": 10 }`
+
+### Get Value
+Retrieve the text value of a specific key.
+`cloudflare_kv_get_value { "namespace_id": "YOUR_NAMESPACE_ID", "key": "YOUR_KEY" }`
+
+## Common Workflow
+1. If the user doesn't specify a namespace, call `cloudflare_kv_list_namespaces` first.
+2. If the user wants to see "cache" or "entries", call `cloudflare_kv_list_keys` with the target `namespace_id`.
+3. To show content, call `cloudflare_kv_get_value`.