feat(plugins): externalize OpenCode provider (#117035)

* feat(plugins): externalize OpenCode provider

* docs: refresh OpenCode provider map

docs/docs_map.md

@@ -8595,7 +8595,7 @@ Do not edit it by hand; run `pnpm docs:map:gen`.
 - Headings:
   - H2: Getting started
   - H2: Config example
-  - H2: Built-in catalogs
+  - H2: Provider catalogs
   - H3: Zen
   - H3: Go
   - H2: Advanced configuration

docs/plugins/plugin-inventory.md

@@ -51,7 +51,7 @@ Each entry lists the package, distribution route, and description.
 
 ## Core npm package
 
-57 plugins
+56 plugins
 
 - **[admin-http-rpc](/plugins/reference/admin-http-rpc)** (`@openclaw/admin-http-rpc`) - included in OpenClaw. OpenClaw admin HTTP RPC endpoint.
 
@@ -133,8 +133,6 @@ Each entry lists the package, distribution route, and description.
 
 - **[openai](/plugins/reference/openai)** (`@openclaw/openai-provider`) - included in OpenClaw. Adds OpenAI model provider support to OpenClaw.
 
-- **[opencode](/plugins/reference/opencode)** (`@openclaw/opencode-provider`) - included in OpenClaw. Adds OpenCode model provider support to OpenClaw.
-
 - **[opencode-go](/plugins/reference/opencode-go)** (`@openclaw/opencode-go-provider`) - included in OpenClaw. Adds OpenCode Go model provider support to OpenClaw.
 
 - **[openrouter](/plugins/reference/openrouter)** (`@openclaw/openrouter-provider`) - included in OpenClaw. Adds OpenRouter model provider support to OpenClaw.
@@ -169,7 +167,7 @@ Each entry lists the package, distribution route, and description.
 
 ## Official external packages
 
-88 plugins
+89 plugins
 
 - **[acpx](/plugins/reference/acpx)** (`@openclaw/acpx`) - npm; ClawHub. OpenClaw ACP runtime backend with plugin-owned session and transport management.
 
@@ -281,6 +279,8 @@ Each entry lists the package, distribution route, and description.
 
 - **[novita](/plugins/reference/novita)** (`@openclaw/novita-provider`) - npm; ClawHub: `clawhub:@openclaw/novita-provider`. Adds Novita, Novita AI, Novitaai model provider support to OpenClaw.
 
+- **[opencode](/plugins/reference/opencode)** (`@openclaw/opencode-provider`) - npm; ClawHub: `clawhub:@openclaw/opencode-provider`. Adds OpenCode model provider support to OpenClaw.
+
 - **[openshell](/plugins/reference/openshell)** (`@openclaw/openshell-sandbox`) - npm; ClawHub. OpenClaw sandbox backend for the NVIDIA OpenShell CLI with mirrored local workspaces and SSH command execution.
 
 - **[parallel](/tools/parallel-search)** (`@openclaw/parallel-plugin`) - npm; ClawHub: `clawhub:@openclaw/parallel-plugin`. Adds web search provider support.

docs/plugins/reference/opencode.md

@@ -12,7 +12,7 @@ Adds OpenCode model provider support to OpenClaw.
 ## Distribution
 
 - Package: `@openclaw/opencode-provider`
-- Install route: included in OpenClaw
+- Install route: npm; ClawHub: `clawhub:@openclaw/opencode-provider`
 
 ## Surface
 

docs/providers/opencode.md

@@ -90,7 +90,7 @@ one OpenCode setup.
 }
 ```
 
-## Built-in catalogs
+## Provider catalogs
 
 ### Zen
 

extensions/opencode/README.md

@@ -0,0 +1,16 @@
+# OpenCode Zen OpenClaw provider
+
+Official OpenClaw provider plugin for the OpenCode Zen model catalog, image
+understanding, and native OpenCode session browsing.
+
+## Install
+
+```sh
+openclaw plugins install @openclaw/opencode-provider
+openclaw gateway restart
+```
+
+## Docs
+
+See `docs/providers/opencode.md` in the OpenClaw repository, or the published
+docs at `https://docs.openclaw.ai/providers/opencode`.

extensions/opencode/index.ts

@@ -53,7 +53,7 @@ function isModernOpencodeModel(modelId: string): boolean {
 export default defineSingleProviderPluginEntry({
   id: PROVIDER_ID,
   name: "OpenCode Zen Provider",
-  description: "Bundled OpenCode Zen provider plugin",
+  description: "OpenCode Zen provider plugin",
   manifest,
   provider: {
     label: "OpenCode Zen",

extensions/opencode/package.json

@@ -1,8 +1,11 @@
 {
   "name": "@openclaw/opencode-provider",
   "version": "2026.7.2",
-  "private": true,
   "description": "OpenClaw OpenCode Zen 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/opencode-provider",
+      "npmSpec": "@openclaw/opencode-provider",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.7.2"
+    },
+    "compat": {
+      "pluginApi": ">=2026.7.2"
+    },
+    "build": {
+      "openclawVersion": "2026.7.2",
+      "bundledDist": false
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
   }
 }

package.json

@@ -294,6 +294,7 @@
     "!dist/extensions/nextcloud-talk/**",
     "!dist/extensions/nostr/**",
     "!dist/extensions/novita/**",
+    "!dist/extensions/opencode/**",
     "!dist/extensions/parallel/**",
     "!dist/extensions/perplexity/**",
     "!dist/extensions/qianfan/**",

scripts/lib/official-external-provider-catalog.json

@@ -962,6 +962,69 @@
         }
       }
     },
+    {
+      "name": "@openclaw/opencode-provider",
+      "description": "OpenClaw OpenCode Zen provider plugin",
+      "source": "official",
+      "kind": "provider",
+      "openclaw": {
+        "plugin": {
+          "id": "opencode",
+          "label": "OpenCode Zen"
+        },
+        "providerEndpoints": [
+          {
+            "endpointClass": "opencode-native",
+            "hostSuffixes": [
+              "opencode.ai"
+            ]
+          }
+        ],
+        "providers": [
+          {
+            "id": "opencode",
+            "name": "OpenCode Zen",
+            "docs": "/providers/opencode",
+            "categories": [
+              "cloud",
+              "llm"
+            ],
+            "envVars": [
+              "OPENCODE_API_KEY",
+              "OPENCODE_ZEN_API_KEY"
+            ],
+            "authChoices": [
+              {
+                "method": "api-key",
+                "choiceId": "opencode-zen",
+                "choiceLabel": "OpenCode Zen catalog",
+                "groupId": "opencode",
+                "groupLabel": "OpenCode",
+                "groupHint": "Shared API key for Zen + Go catalogs",
+                "optionKey": "opencodeZenApiKey",
+                "cliFlag": "--opencode-zen-api-key",
+                "cliOption": "--opencode-zen-api-key <key>",
+                "cliDescription": "OpenCode API key (Zen catalog)",
+                "onboardingScopes": [
+                  "text-inference"
+                ]
+              }
+            ]
+          }
+        ],
+        "contracts": {
+          "mediaUnderstandingProviders": [
+            "opencode"
+          ]
+        },
+        "install": {
+          "clawhubSpec": "clawhub:@openclaw/opencode-provider",
+          "npmSpec": "@openclaw/opencode-provider",
+          "defaultChoice": "npm",
+          "minHostVersion": ">=2026.7.2"
+        }
+      }
+    },
     {
       "name": "@openclaw/groq-provider",
       "description": "OpenClaw Groq media-understanding provider.",

src/cli/plugins-location-bridges.test.ts

@@ -169,6 +169,7 @@ describe("listPersistedBundledPluginLocationBridges", () => {
     ["duckduckgo", "@openclaw/duckduckgo-plugin", false],
     ["mistral", "@openclaw/mistral-provider", true],
     ["novita", "@openclaw/novita-provider", true],
+    ["opencode", "@openclaw/opencode-provider", true],
     ["synthetic", "@openclaw/synthetic-provider", true],
     ["teams-meetings", "@openclaw/teams-meetings", true],
     ["volcengine", "@openclaw/volcengine-provider", true],

src/plugins/official-external-plugin-catalog.test.ts

@@ -1960,6 +1960,27 @@ describe("official external plugin catalog", () => {
     });
   });
 
+  it("lists OpenCode Zen with its model and media install surfaces", () => {
+    const opencode = expectCatalogEntry("opencode");
+    const manifest = getOfficialExternalPluginCatalogManifest(opencode);
+
+    expect(resolveOfficialExternalPluginId(opencode)).toBe("opencode");
+    expect(resolveOfficialExternalPluginInstall(opencode)).toEqual({
+      clawhubSpec: "clawhub:@openclaw/opencode-provider",
+      npmSpec: "@openclaw/opencode-provider",
+      defaultChoice: "npm",
+      minHostVersion: ">=2026.7.2",
+    });
+    expect(manifest?.providers?.map((provider) => provider.id)).toEqual(["opencode"]);
+    expect(manifest?.contracts?.mediaUnderstandingProviders).toEqual(["opencode"]);
+    expect(manifest?.providerEndpoints).toEqual([
+      {
+        endpointClass: "opencode-native",
+        hostSuffixes: ["opencode.ai"],
+      },
+    ]);
+  });
+
   it("lists Synthetic as an official external provider", () => {
     const synthetic = expectCatalogEntry("synthetic");
 

test/scripts/bundled-plugin-build-entries.test.ts

@@ -342,7 +342,15 @@ describe("bundled plugin build entries", () => {
   it("excludes externalized model providers from bundled artifacts", () => {
     const artifacts = listBundledPluginPackArtifacts();
 
-    for (const pluginId of ["byteplus", "cohere", "meta", "mistral", "novita", "xiaomi"]) {
+    for (const pluginId of [
+      "byteplus",
+      "cohere",
+      "meta",
+      "mistral",
+      "novita",
+      "opencode",
+      "xiaomi",
+    ]) {
       expect(artifacts).not.toContain(`dist/extensions/${pluginId}/index.js`);
       expect(artifacts).not.toContain(`dist/extensions/${pluginId}/openclaw.plugin.json`);
       expect(artifacts).not.toContain(`dist/extensions/${pluginId}/package.json`);