OpenCode agent provider

NanoClaw runs agents in a long-lived poll loop inside the container. The backend is selected per agent group by the provider key in that group's container.json (materialized from the container_configs table) — set it with ncl groups config update --provider opencode. Default is claude.

Trunk ships with only the claude provider baked in. This skill copies the OpenCode provider files in from the providers branch, wires them into the host and container barrels, installs dependencies, and rebuilds the image.

Install

1. Copy the provider payload

Fetch the providers branch from the configured remote that carries it, then overwrite every skill-owned provider file with its canonical registry copy:

src/providers/opencode.ts
src/providers/opencode-registration.test.ts
container/agent-runner/src/providers/opencode.ts
container/agent-runner/src/providers/mcp-to-opencode.ts
container/agent-runner/src/providers/mcp-to-opencode.test.ts
container/agent-runner/src/providers/opencode-registration.test.ts
container/agent-runner/src/providers/opencode.attachments.test.ts
container/agent-runner/src/providers/opencode.compaction.test.ts
container/agent-runner/src/providers/opencode.config.test.ts
container/agent-runner/src/providers/opencode.factory.test.ts
container/agent-runner/src/providers/opencode.memory.test.ts
container/agent-runner/src/providers/opencode.question.test.ts

(cwd-shim.ts and its test are deliberately not in this payload even though mcp-to-opencode.ts imports the shim: trunk ships and owns them — the default provider imports cwd-shim.ts — and every path listed here becomes a skill-owned file that removal deletes.)

2. Register the provider in both runtimes

Each barrel gets one line appended at the end — skip if the line is already present.

import './opencode.js';

import './opencode.js';

3. Install the matched SDK and CLI pins

The agent-runner is a separate Bun package tree. Keep its SDK on the same exact version as the globally installed opencode-ai CLI:

@opencode-ai/sdk@1.4.17

{
  "name": "opencode-ai",
  "version": "1.4.17"
}

Do not use latest. OpenCode's CLI and SDK have changed their session API in lockstep before; mismatched versions can build cleanly and fail at runtime.

4. Install the pin guard

Copy the structural test that asserts the CLI manifest and SDK package stay on the same exact version:

opencode-cli-tools.test.ts -> src/opencode-cli-tools.test.ts

5. Build and validate

pnpm run build

pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit

pnpm exec vitest run src/providers/opencode-registration.test.ts src/opencode-cli-tools.test.ts

cd container/agent-runner && bun test src/providers/opencode-registration.test.ts

./container/build.sh

All checks must be clean before proceeding. The registration tests import the real host and container barrels; the pin guard covers the non-importable global CLI; the two typechecks cover both runtime API boundaries.

NanoClaw v2 mounts one shared read-only agent-runner source tree. There are no per-group source overlays to propagate or repair.

Configuration

Host .env (typical)

Set model/provider strings in the form OpenCode expects (often provider/model-id). Put comments on their own lines — a # inside a value is kept verbatim and breaks model IDs.

These variables are read on the host and passed into the container only when the effective provider is opencode. They do not switch the provider by themselves; the group still needs provider set to opencode (see Select the provider below).

• OPENCODE_PROVIDER — OpenCode provider id, e.g. openrouter, anthropic, deepseek.

• OPENCODE_MODEL — full model id in provider/model form, e.g. deepseek/deepseek-chat.

• OPENCODE_SMALL_MODEL — optional second model for lighter tasks; defaults to OPENCODE_MODEL if unset.

• ANTHROPIC_BASE_URL — required for non-anthropic providers. The opencode container provider passes this as the baseURL for the upstream provider config so requests route through OneCLI's credential proxy or directly to the provider's API. Set it to the provider's API base URL (e.g. https://api.deepseek.com/v1, https://openrouter.ai/api/v1).

• OPENCODE_MODEL_CONTEXT_LIMIT — optional context window, in tokens, declared for OPENCODE_MODEL only (not the small model); OpenCode auto-compacts as a session approaches it, and a model its registry does not know resolves to 0 and so never compacts. Anything but a positive integer is logged and treated as unset, which emits no limit and leaves behavior unchanged.

• OPENCODE_MODEL_OUTPUT_LIMIT — optional max output tokens for the same main model, only applied alongside a valid context limit (without one it is logged and ignored). Anything but a positive integer is logged and treated as unset.

• OPENCODE_MODEL_INPUT_MODALITIES — optional comma-separated subset of text,audio,image,video,pdf, declared for OPENCODE_MODEL only. OpenCode drops any file part whose modality the model does not declare, so images and PDFs never reach a registry-unknown custom model unless this is set. Unrecognized entries are logged and skipped; unset declares nothing and leaves behavior unchanged. A distinct OPENCODE_SMALL_MODEL never inherits this; it keeps the undeclared-model default regardless.

  Declaring the modality only opens OpenCode's gate. NanoClaw must also pass channel attachments to the provider as structured file parts; until that support is available, attachments remain prompt text.

Credentials: register provider API keys in OneCLI with the matching --host-pattern (e.g. api.deepseek.com, openrouter.ai). OneCLI injects them via HTTPS_PROXY in the container — the key never lives in .env or the container environment.

After adding a secret, grant the agent access — agents in selective mode only receive secrets they've been explicitly assigned:

Use the safe merge pattern — set-secrets replaces the entire list, so always read first:

AGENT_ID=$(onecli agents list | jq -r '.data[] | select(.identifier=="<agentGroupId>") | .id')
CURRENT=$(onecli agents secrets --id "$AGENT_ID" | jq -r '[.data[]] | join(",")')
MERGED=$(printf '%s' "$CURRENT,<new-secret-id>" | tr ',' '\n' | sort -u | paste -sd ',' -)
onecli agents set-secrets --id "$AGENT_ID" --secret-ids "$MERGED"
onecli agents secrets --id "$AGENT_ID"

Example: DeepSeek

OPENCODE_PROVIDER=deepseek
OPENCODE_MODEL=deepseek/deepseek-chat
OPENCODE_SMALL_MODEL=deepseek/deepseek-chat
ANTHROPIC_BASE_URL=https://api.deepseek.com/v1

Register the key:

onecli secrets create --name "DeepSeek" --type generic \
  --value YOUR_KEY --host-pattern "api.deepseek.com" \
  --header-name "Authorization" --value-format "Bearer {value}"

Example: OpenRouter

OPENCODE_PROVIDER=openrouter
OPENCODE_MODEL=openrouter/anthropic/claude-sonnet-4
OPENCODE_SMALL_MODEL=openrouter/anthropic/claude-haiku-4.5
ANTHROPIC_BASE_URL=https://openrouter.ai/api/v1

Register the key:

onecli secrets create --name "OpenRouter" --type generic \
  --value YOUR_KEY --host-pattern "openrouter.ai" \
  --header-name "Authorization" --value-format "Bearer {value}"

Example: Anthropic (no ANTHROPIC_BASE_URL needed)

When OPENCODE_PROVIDER is anthropic, OpenCode uses normal Anthropic env inside the container — the proxy + placeholder key pattern is unchanged and ANTHROPIC_BASE_URL is not required.

OPENCODE_PROVIDER=anthropic
OPENCODE_MODEL=anthropic/claude-sonnet-4-20250514
OPENCODE_SMALL_MODEL=anthropic/claude-haiku-4-5-20251001

OpenCode Zen (x-api-key, not Bearer)

Zen's HTTP API (e.g. POST …/zen/v1/messages) expects the key in the x-api-key header. If OneCLI injects Authorization: Bearer … only, Zen often returns 401 / "Missing API key" even though the gateway is working.

Naming: NanoClaw's provider: opencode (the container.json key, set via ncl groups config update --provider opencode) means "run the OpenCode agent provider." Separately, OPENCODE_PROVIDER=opencode in .env is OpenCode's Zen provider id inside the OpenCode config (see Zen docs).

Host .env (typical Zen shape):

OPENCODE_PROVIDER=opencode
OPENCODE_MODEL=opencode/big-pickle
OPENCODE_SMALL_MODEL=opencode/big-pickle
ANTHROPIC_BASE_URL=https://opencode.ai/zen/v1

Use a real Zen model id from the docs; big-pickle is one example.

OneCLI: register the Zen key with x-api-key, not Bearer:

onecli secrets create --name "OpenCode Zen" --type generic \
  --value YOUR_ZEN_KEY --host-pattern opencode.ai \
  --header-name "x-api-key" --value-format "{value}"

Select the provider

Per group, from the host:

ncl groups config update --id <group-id> --provider opencode
ncl groups restart --id <group-id>

ncl groups config update --provider writes the provider value into the container_configs table; the host materializes it into groups/<folder>/container.json at spawn time and the in-container runner reads provider from there (defaulting to claude). The restart picks up the change. Switching is an operator action — run it from the host. Memory does NOT carry over automatically between providers — run /migrate-memory to carry it across.

Extra MCP servers still come from NANOCLAW_MCP_SERVERS / container_config.mcpServers on the host; the runner merges them into the same mcpServers object passed to both Claude and OpenCode providers.

Operational notes

• OpenCode keeps a local opencode serve process and SSE subscription; the provider tears down with stream.return and SIGKILL on the server process on abort() / shared runtime reset to avoid MCP/zombie hangs.
• Session continuation uses UUID format (SDK 1.4.x / CLI 1.4.x). Stale sessions are cleared by isSessionInvalid on OpenCode-specific error patterns. If you see UUID-related errors after an accidental CLI upgrade, clear session_state in outbound.db and wipe the opencode-xdg directory under the session folder.
• NO_PROXY for localhost matters when the OpenCode client talks to 127.0.0.1 inside the container while HTTP(S)_PROXY is set (e.g. OneCLI).

Next steps

The host/container registration tests and the CLI/SDK pin guard verify the static wiring. To confirm a live round-trip, switch a test group with ncl groups config update --id <group-id> --provider opencode && ncl groups restart --id <group-id>, register the matching provider key in OneCLI, and send a message. A clean exchange returns the model's reply with no Unknown provider: opencode error and no UUID/session warnings in the logs.

To remove this provider, see REMOVE.md.