feat(plugins): externalize Voyage embeddings (#116785)

* feat(voyage): externalize embedding provider * fix(voyage): drop stale bundled description
2026-08-02 05:41:37 +00:00 · 2026-07-31 19:52:33 +08:00
parent 5f5a871f39
commit eb55c8ea8f
10 changed files with 117 additions and 9 deletions
--- a/docs/plugins/plugin-inventory.md
+++ b/docs/plugins/plugin-inventory.md
@@ -51,7 +51,7 @@ Each entry lists the package, distribution route, and description.

 ## Core npm package

-65 plugins
+64 plugins

 - **[admin-http-rpc](/plugins/reference/admin-http-rpc)** (`@openclaw/admin-http-rpc`) - included in OpenClaw. OpenClaw admin HTTP RPC endpoint.

@@ -169,8 +169,6 @@ Each entry lists the package, distribution route, and description.

 - **[volcengine](/plugins/reference/volcengine)** (`@openclaw/volcengine-provider`) - included in OpenClaw. Adds Volcengine, Volcengine Plan model provider support to OpenClaw.

- **[voyage](/plugins/reference/voyage)** (`@openclaw/voyage-provider`) - included in OpenClaw. Adds memory embedding provider support.
-
 - **[vydra](/plugins/reference/vydra)** (`@openclaw/vydra-provider`) - included in OpenClaw. Adds Vydra model provider support to OpenClaw.

 - **[web-readability](/plugins/reference/web-readability)** (`@openclaw/web-readability-plugin`) - included in OpenClaw. Extract readable article content from local HTML web fetch responses.
@@ -185,7 +183,7 @@ Each entry lists the package, distribution route, and description.

 ## Official external packages

-80 plugins
+81 plugins

 - **[acpx](/plugins/reference/acpx)** (`@openclaw/acpx`) - npm; ClawHub. OpenClaw ACP runtime backend with plugin-owned session and transport management.

@@ -337,6 +335,8 @@ Each entry lists the package, distribution route, and description.

 - **[voice-call](/plugins/reference/voice-call)** (`@openclaw/voice-call`) - npm; ClawHub. OpenClaw voice-call plugin for Twilio, Telnyx, and Plivo phone calls.

+- **[voyage](/plugins/reference/voyage)** (`@openclaw/voyage-provider`) - npm; ClawHub: `clawhub:@openclaw/voyage-provider`. Adds memory embedding provider support.
+
 - **[whatsapp](/plugins/reference/whatsapp)** (`@openclaw/whatsapp`) - ClawHub: `clawhub:@openclaw/whatsapp`; npm. OpenClaw WhatsApp channel plugin for WhatsApp Web chats.

 - **[zai](/plugins/reference/zai)** (`@openclaw/zai-provider`) - npm; ClawHub: `clawhub:@openclaw/zai-provider`. Adds Z.AI model provider support to OpenClaw.
--- a/docs/plugins/reference/voyage.md
+++ b/docs/plugins/reference/voyage.md
@@ -12,7 +12,7 @@ Adds memory embedding provider support.
 ## Distribution

 - Package: `@openclaw/voyage-provider`
- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/voyage-provider`

 ## Surface

--- a/extensions/voyage/README.md
+++ b/extensions/voyage/README.md
@@ -0,0 +1,14 @@
+# OpenClaw Voyage Provider
+
+Official OpenClaw memory embedding provider plugin for Voyage AI.
+
+Install from OpenClaw:
+
+```bash
+openclaw plugins install @openclaw/voyage-provider
+openclaw gateway restart
+```
+
+Set `VOYAGE_API_KEY`, then configure memory search with `provider: "voyage"`.
+See <https://docs.openclaw.ai/reference/memory-config> for setup and
+configuration.
--- a/extensions/voyage/index.ts
+++ b/extensions/voyage/index.ts
@@ -5,7 +5,7 @@ import { voyageMemoryEmbeddingProviderAdapter } from "./memory-embedding-adapter
 export default definePluginEntry({
  id: "voyage",
  name: "Voyage Embeddings",
-  description: "Bundled Voyage memory embedding provider plugin",
+  description: "Voyage memory embedding provider plugin",
  register(api) {
    api.registerMemoryEmbeddingProvider(voyageMemoryEmbeddingProviderAdapter);
  },
--- a/extensions/voyage/package.json
+++ b/extensions/voyage/package.json
@@ -1,8 +1,11 @@
 {
  "name": "@openclaw/voyage-provider",
  "version": "2026.7.2",
-  "private": true,
-  "description": "OpenClaw Voyage embedding provider plugin",
+  "description": "OpenClaw Voyage embedding provider plugin.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
  "type": "module",
  "devDependencies": {
    "@openclaw/plugin-sdk": "workspace:*"
@@ -10,6 +13,23 @@
  "openclaw": {
    "extensions": [
      "./index.ts"
-    ]
+    ],
+    "install": {
+      "clawhubSpec": "clawhub:@openclaw/voyage-provider",
+      "npmSpec": "@openclaw/voyage-provider",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.7.2"
+    },
+    "compat": {
+      "pluginApi": ">=2026.7.2"
+    },
+    "build": {
+      "openclawVersion": "2026.7.2",
+      "bundledDist": false
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
  }
 }
--- a/package.json
+++ b/package.json
@@ -316,6 +316,7 @@
    "!dist/extensions/venice/**",
    "!dist/extensions/vercel-ai-gateway/**",
    "!dist/extensions/voice-call/**",
+    "!dist/extensions/voyage/**",
    "!dist/extensions/whatsapp/**",
    "!dist/extensions/zai/**",
    "!dist/extensions/zalo/**",
--- a/scripts/lib/official-external-provider-catalog.json
+++ b/scripts/lib/official-external-provider-catalog.json
@@ -1708,6 +1708,42 @@
        }
      }
    },
+    {
+      "name": "@openclaw/voyage-provider",
+      "description": "OpenClaw Voyage embedding provider plugin.",
+      "source": "official",
+      "kind": "provider",
+      "openclaw": {
+        "plugin": {
+          "id": "voyage",
+          "label": "Voyage"
+        },
+        "providers": [
+          {
+            "id": "voyage",
+            "name": "Voyage",
+            "docs": "/reference/memory-config",
+            "categories": [
+              "cloud"
+            ],
+            "envVars": [
+              "VOYAGE_API_KEY"
+            ]
+          }
+        ],
+        "contracts": {
+          "memoryEmbeddingProviders": [
+            "voyage"
+          ]
+        },
+        "install": {
+          "clawhubSpec": "clawhub:@openclaw/voyage-provider",
+          "npmSpec": "@openclaw/voyage-provider",
+          "defaultChoice": "npm",
+          "minHostVersion": ">=2026.7.2"
+        }
+      }
+    },
    {
      "name": "@openclaw/stepfun-provider",
      "description": "OpenClaw StepFun provider plugin.",
--- a/src/cli/plugins-location-bridges.test.ts
+++ b/src/cli/plugins-location-bridges.test.ts
@@ -168,6 +168,7 @@ describe("listPersistedBundledPluginLocationBridges", () => {
    ["duckduckgo", "@openclaw/duckduckgo-plugin", false],
    ["synthetic", "@openclaw/synthetic-provider", true],
    ["teams-meetings", "@openclaw/teams-meetings", true],
+    ["voyage", "@openclaw/voyage-provider", true],
    ["zoom-meetings", "@openclaw/zoom-meetings", true],
  ] as const)(
    "externalizes the shipped bundled %s plugin using official install metadata",
--- a/src/plugins/official-external-plugin-catalog.test.ts
+++ b/src/plugins/official-external-plugin-catalog.test.ts
@@ -2000,6 +2000,26 @@ describe("official external plugin catalog", () => {
    ]);
  });

+  it("lists Voyage as an official external memory embedding provider", () => {
+    const voyage = expectCatalogEntry("voyage");
+    const manifest = getOfficialExternalPluginCatalogManifest(voyage);
+
+    expect(resolveOfficialExternalPluginId(voyage)).toBe("voyage");
+    expect(resolveOfficialExternalPluginInstall(voyage)).toEqual({
+      clawhubSpec: "clawhub:@openclaw/voyage-provider",
+      npmSpec: "@openclaw/voyage-provider",
+      defaultChoice: "npm",
+      minHostVersion: ">=2026.7.2",
+    });
+    expect(manifest?.contracts?.memoryEmbeddingProviders).toEqual(["voyage"]);
+    expect(manifest?.providers).toEqual([
+      expect.objectContaining({
+        id: "voyage",
+        envVars: ["VOYAGE_API_KEY"],
+      }),
+    ]);
+  });
+
  it.each([
    ["teams-meetings", "@openclaw/teams-meetings", "teams_meetings", "teams"],
    ["zoom-meetings", "@openclaw/zoom-meetings", "zoom_meetings", "zoom"],
@@ -2067,6 +2087,12 @@ describe("official external plugin catalog", () => {
        providerIds: new Set(["groq", "moonshot", "zai"]),
      }),
    ).toEqual(["groq", "moonshot", "zai"]);
+    expect(
+      resolveOfficialExternalProviderContractPluginIds({
+        contract: "memoryEmbeddingProviders",
+        providerIds: new Set(["voyage"]),
+      }),
+    ).toEqual(["voyage"]);
  });

  it("maps env-only web-fetch credentials to external plugin owners", () => {
@@ -2116,6 +2142,7 @@ describe("official external plugin catalog", () => {
        TOKENPLAN_API_KEY: "tokenplan-key",
        VENICE_API_KEY: "venice-key",
        AI_GATEWAY_API_KEY: "gateway-key",
+        VOYAGE_API_KEY: "voyage-key",
        ZAI_API_KEY: "zai-key",
      }),
    ).toEqual([
@@ -2138,6 +2165,7 @@ describe("official external plugin catalog", () => {
      "tencent",
      "venice",
      "vercel-ai-gateway",
+      "voyage",
      "zai",
    ]);
    expect(resolveOfficialExternalProviderPluginIdsForEnv({ GROQ_API_KEY: " " })).toEqual([]);
--- a/test/scripts/bundled-plugin-build-entries.test.ts
+++ b/test/scripts/bundled-plugin-build-entries.test.ts
@@ -375,6 +375,14 @@ describe("bundled plugin build entries", () => {
    expect(artifacts).not.toContain("dist/extensions/duckduckgo/package.json");
  });

+  it("excludes the externalized Voyage provider from bundled artifacts", () => {
+    const artifacts = listBundledPluginPackArtifacts();
+
+    expect(artifacts).not.toContain("dist/extensions/voyage/index.js");
+    expect(artifacts).not.toContain("dist/extensions/voyage/openclaw.plugin.json");
+    expect(artifacts).not.toContain("dist/extensions/voyage/package.json");
+  });
+
  it("keeps bundled channel secret contracts on packed top-level sidecars", () => {
    const artifacts = listBundledPluginPackArtifacts();
    const excludedPackageDirs = collectRootPackageExcludedExtensionDirs();