---

name: add-opencode description: Use OpenCode as an agent provider. OpenRouter, OpenAI, Google, DeepSeek, etc. via OpenCode config — not the Anthropic Agent SDK. Per group via ncl groups config update --provider opencode; host passes OPENCODE_* and XDG mount when spawning containers. metadata: nanoclaw-provider: opencode nanoclaw-provider-label: OpenCode nanoclaw-provider-hint: Open-source provider router nanoclaw-provider-offered: 'true' nanoclaw-provider-image: local-required

OpenCode agent provider

Install OpenCode as an optional NanoClaw runtime. The payload is included in this skill; it needs no separate provider branch. It uses the upstream runtime, instructions, host, and setup metadata contracts. The host contract remains at version 1; the container owns its non-secret ChatGPT placeholder file.

OpenCode is offered by the standard setup provider picker. Existing installs can add or authenticate it with pnpm exec tsx setup/index.ts --step provider-auth opencode. To replace an installed payload and update its pins, append --refresh; back up local payload edits first. Ordinary re-authentication leaves installed files and the container image alone. Backend defaults are installation-wide; model and reasoning effort can be overridden per group through the existing container configuration. Per-group backend/auth selection and structured channel attachment transport are separate work.

Authentication checks the installed files, registration lines, and exact pins against this skill's declarations without launching a subprocess or container. Install and refresh run the existing provider contract verification; the build step owns image freshness. Model selection does not repeat installation checks. A working backend and account are checked separately by sending a real request.

Install

After installing this payload, run pnpm exec tsx scripts/opencode-host.ts --configure for host OpenCode setup, or use --update / --debug for the corresponding operational skill. An existing OpenCode CLI can also run directly in the checkout; it discovers .claude/skills natively. Host sign-in uses OpenCode's own settings and is independent of the container's gateway credentials. Installed setup failures use the existing provider failure-assist hook, including wizard authentication and installation-check failures. Host diagnostic context is model input and may remain in native OpenCode history; deleting its private temporary file does not erase those records. The helper requires stable OpenCode 1.18.25 or newer with --prompt and prefers the newest compatible installation it finds. Automatic help before payload installation is optional and is not part of the runtime contract.

Install and refresh require host contract version 1 and credential-connection seam version 1. The compatibility predicate below guards every subsequent step, so an unsupported core receives no partial payload or dependency changes. Update core first if it reports a missing prerequisite.

node -e "const fs=require('fs'); const p='src/provider-contracts/registry.ts', g='setup/gateways/credential-store.ts'; if(fs.existsSync(p) && /PROVIDER_HOST_CONTRACT_SEAM_VERSION = 1/.test(fs.readFileSync(p,'utf8')) && fs.existsSync(g) && /PROVIDER_CREDENTIAL_CONNECTION_SEAM_VERSION = 1/.test(fs.readFileSync(g,'utf8'))) console.log('yes'); else console.log('no')"

Copy only the files listed below from this skill's payload/ to the matching paths at the project root. Do not copy ignored dependency directories or other generated native-test files. These are skill-owned files; overwrite them together when refreshing the skill. Keep the core-owned cwd-shim.ts, registries, and contract realization files in place.

When refreshing an older installation, remove its unused opencode-memory-plugin.ts, opencode.compaction.test.ts, and dedicated opencode-managed-config tree from container/agent-runner/src/providers/. Recreate affected containers after the refresh to discard their old config symlinks. Keep other tools' settings and persisted session data.

The obsolete host Dockerfile guard must also be removed during refresh; current OpenCode installation is declared by the SDK and CLI manifests.

rm -f src/opencode-dockerfile.test.ts

payload/container/agent-runner/src/provider-contracts/opencode.ts -> container/agent-runner/src/provider-contracts/opencode.ts
payload/container/agent-runner/src/providers/mcp-to-opencode.test.ts -> container/agent-runner/src/providers/mcp-to-opencode.test.ts
payload/container/agent-runner/src/providers/mcp-to-opencode.ts -> container/agent-runner/src/providers/mcp-to-opencode.ts
payload/container/agent-runner/src/providers/opencode-config.ts -> container/agent-runner/src/providers/opencode-config.ts
payload/container/agent-runner/src/providers/opencode-memory.ts -> container/agent-runner/src/providers/opencode-memory.ts
payload/container/agent-runner/src/providers/opencode-registration.test.ts -> container/agent-runner/src/providers/opencode-registration.test.ts
payload/container/agent-runner/src/providers/opencode-turn.ts -> container/agent-runner/src/providers/opencode-turn.ts
payload/container/agent-runner/src/providers/opencode.attachments.test.ts -> container/agent-runner/src/providers/opencode.attachments.test.ts
payload/container/agent-runner/src/providers/opencode.config.test.ts -> container/agent-runner/src/providers/opencode.config.test.ts
payload/container/agent-runner/src/providers/opencode.conformance.test.ts -> container/agent-runner/src/providers/opencode.conformance.test.ts
payload/container/agent-runner/src/providers/opencode.empty-resume.test.ts -> container/agent-runner/src/providers/opencode.empty-resume.test.ts
payload/container/agent-runner/src/providers/opencode.factory.test.ts -> container/agent-runner/src/providers/opencode.factory.test.ts
payload/container/agent-runner/src/providers/opencode.memory.test.ts -> container/agent-runner/src/providers/opencode.memory.test.ts
payload/container/agent-runner/src/providers/opencode.native.test.ts -> container/agent-runner/src/providers/opencode.native.test.ts
payload/container/agent-runner/src/providers/opencode.question.test.ts -> container/agent-runner/src/providers/opencode.question.test.ts
payload/container/agent-runner/src/providers/opencode.shared-runtime.test.ts -> container/agent-runner/src/providers/opencode.shared-runtime.test.ts
payload/container/agent-runner/src/providers/opencode.sse-cleanup.test.ts -> container/agent-runner/src/providers/opencode.sse-cleanup.test.ts
payload/container/agent-runner/src/providers/opencode.ts -> container/agent-runner/src/providers/opencode.ts
payload/container/agent-runner/src/providers/opencode-auth.ts -> container/agent-runner/src/providers/opencode-auth.ts
payload/container/agent-runner/src/providers/opencode-auth.test.ts -> container/agent-runner/src/providers/opencode-auth.test.ts
payload/scripts/opencode-auth-config.test.ts -> scripts/opencode-auth-config.test.ts
payload/scripts/opencode-auth.test.ts -> scripts/opencode-auth.test.ts
payload/scripts/opencode-auth.ts -> scripts/opencode-auth.ts
payload/scripts/opencode-gateway.test.ts -> scripts/opencode-gateway.test.ts
payload/scripts/opencode-host.ts -> scripts/opencode-host.ts
payload/scripts/opencode-host.test.ts -> scripts/opencode-host.test.ts
payload/scripts/opencode-model-config.ts -> scripts/opencode-model-config.ts
payload/scripts/opencode-models.test.ts -> scripts/opencode-models.test.ts
payload/scripts/opencode-models.ts -> scripts/opencode-models.ts
payload/scripts/opencode-vault.test.ts -> scripts/opencode-vault.test.ts
payload/scripts/opencode-vault.ts -> scripts/opencode-vault.ts
payload/scripts/tsconfig.opencode-auth.json -> scripts/tsconfig.opencode-auth.json
payload/setup/providers/opencode.test.ts -> setup/providers/opencode.test.ts
payload/setup/providers/opencode.ts -> setup/providers/opencode.ts
payload/src/provider-contracts/opencode.ts -> src/provider-contracts/opencode.ts
payload/src/providers/opencode-auth-stub.ts -> src/providers/opencode-auth-stub.ts
payload/src/providers/opencode-registration.test.ts -> src/providers/opencode-registration.test.ts
payload/src/providers/opencode.ts -> src/providers/opencode.ts

Append import './opencode.js'; once to each of the five setup, provider, and contract barrels below. Keep all existing imports.

import './opencode.js';

import './opencode.js';

import './opencode.js';

import './opencode.js';

import './opencode.js';

Install the SDK in the runner's Bun package and add the matching CLI manifest entry with trusted postinstall enabled. Both pins must remain exactly 1.18.25. When refreshing an existing install, replace both old pin entries; presence alone does not establish compatibility. This updates the runner package and lockfile; there is no host SDK dependency.

@opencode-ai/sdk@1.18.25

{"name":"opencode-ai","version":"1.18.25","onlyBuilt":true}

Run the host build, runner typecheck, host/auth tests, and all provider tests. The tests exercise real barrel registration and the provider-owned contract conformance suite. All checks must pass before rebuilding the agent image.

pnpm run build

pnpm exec tsc -p scripts/tsconfig.opencode-auth.json

cd container/agent-runner && bun run typecheck

pnpm exec vitest run src/providers/opencode-registration.test.ts scripts/opencode-auth*.test.ts scripts/opencode-gateway.test.ts scripts/opencode-host.test.ts scripts/opencode-models.test.ts scripts/opencode-vault.test.ts setup/providers

cd container/agent-runner && bun test --isolate src/providers/opencode*.test.ts src/providers/mcp-to-opencode.test.ts

Build the local image with ./container/build.sh build. The new SDK dependency requires a full local build; a CLI-only overlay cannot supply it. This switches a published-image installation to locally built images.

./container/build.sh build

Authenticate and select a group

Run pnpm exec tsx setup/index.ts --step provider-auth opencode from the project root to install a missing payload and image, then choose authentication. If the provider is already installed, this command leaves its files and image alone; append --refresh only when intentionally replacing its payload and pins. Choose ChatGPT sign-in, a local OpenAI-compatible endpoint, OpenRouter, DeepSeek, or a supported native backend. Automatic API-key configuration supports OpenAI, OpenRouter, DeepSeek, Google, and Anthropic; other native authentication schemes require separate integration. The command stores credentials in the configured credential gateway selected by NANOCLAW_GATEWAY_PROVIDER and backend defaults in .env. The full setup wizard also offers this flow and selects OpenCode for new groups only after configuration succeeds. The standalone command leaves the instance default unchanged.

For ChatGPT, native OpenCode sign-in runs