OpenCode agent provider

NanoClaw runs agents in a long-lived poll loop inside the container. The backend is selected with AGENT_PROVIDER (claude | opencode | mock).

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

Pre-flight

If all of the following are already present, skip to Configuration:

• src/providers/opencode.ts
• container/agent-runner/src/providers/opencode.ts
• src/providers/opencode-registration.test.ts
• container/agent-runner/src/providers/opencode-registration.test.ts
• import './opencode.js'; line in src/providers/index.ts
• import './opencode.js'; line in container/agent-runner/src/providers/index.ts
• @opencode-ai/sdk in container/agent-runner/package.json
• opencode-ai entry in container/cli-tools.json and the manifest installer seam in container/Dockerfile

Missing pieces — continue below. All steps are idempotent; re-running is safe.

1. Fetch the providers branch

git fetch origin providers

2. Copy the OpenCode source files

Wholesale copies (owned entirely by this skill — user edits to these files won't survive a re-run, as designed):

git show origin/providers:src/providers/opencode.ts                                     > src/providers/opencode.ts
git show origin/providers:container/agent-runner/src/providers/opencode.ts              > container/agent-runner/src/providers/opencode.ts
git show origin/providers:container/agent-runner/src/providers/mcp-to-opencode.ts       > container/agent-runner/src/providers/mcp-to-opencode.ts
git show origin/providers:container/agent-runner/src/providers/mcp-to-opencode.test.ts  > container/agent-runner/src/providers/mcp-to-opencode.test.ts
git show origin/providers:container/agent-runner/src/providers/opencode.factory.test.ts > container/agent-runner/src/providers/opencode.factory.test.ts

Also copy the two barrel-registration guards — one per tree. These import the real provider barrels and assert opencode is registered, so they go red the moment a barrel import line is deleted or drifts:

git show origin/providers:src/providers/opencode-registration.test.ts                          > src/providers/opencode-registration.test.ts
git show origin/providers:container/agent-runner/src/providers/opencode-registration.test.ts   > container/agent-runner/src/providers/opencode-registration.test.ts

3. Append the self-registration imports

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

src/providers/index.ts:

import './opencode.js';

container/agent-runner/src/providers/index.ts:

import './opencode.js';

4. Add the agent-runner dependency

Pinned. Bump deliberately, not with bun update. Use the current exact OpenCode release — it must match the opencode-ai CLI version in container/cli-tools.json. The current fork pin is 1.18.25. Keep the root SDK API used by the provider (createOpencodeClient, session.create, session.promptAsync, event.subscribe, and permission responses) covered by the provider tests when bumping.

cd container/agent-runner && bun add @opencode-ai/sdk@1.18.25 && cd -

5. Pin opencode-ai in the container manifest

The Dockerfile installs global Node CLIs from container/cli-tools.json through container/install-cli-tools.sh. Update the existing exact opencode-ai entry there; do not add a Dockerfile ARG or a separate install block. Keep the CLI and SDK at the same exact version, and update versions.json so upgrades can detect the external component pin.

6. Copy the Dockerfile install guard

The opencode-ai CLI is a globally-installed binary — not importable or typed — so container/cli-tools.test.ts guards the manifest-to-Dockerfile install seam and the CLI/SDK version lockstep.

# No additional Dockerfile test file is needed; update the existing manifest
# guard if the install mechanism changes again.

7. Build and validate

pnpm run build                                                    # host
pnpm exec tsc -p container/agent-runner/tsconfig.json --noEmit    # container typecheck
pnpm exec vitest run src/providers/opencode-registration.test.ts  # host registration guard
pnpm exec vitest run container/cli-tools.test.ts                  # CLI/Dockerfile install guard
cd container/agent-runner && bun test src/providers/opencode-registration.test.ts && cd -  # container registration guard
./container/build.sh                                              # agent image

All four must be clean before proceeding. Each guards a distinct integration point:

• src/providers/opencode-registration.test.ts (host, vitest) imports the real host barrel (./index.js → listProviderContainerConfigNames) and asserts opencode is present. It goes red if the import './opencode.js'; line in src/providers/index.ts is deleted or drifts, or if that barrel fails to evaluate.
• container/agent-runner/src/providers/opencode-registration.test.ts (container, bun:test) imports the real container barrel (./index.js → listProviderNames) and asserts opencode is present. It goes red if the import './opencode.js'; line in container/agent-runner/src/providers/index.ts is deleted or drifts. Because the barrel is imported unmocked, it also pulls in opencode.ts, which imports @opencode-ai/sdk — so this test implicitly guards the step-4 dependency too: if the package isn't installed, the import throws and the test goes red.
• container/cli-tools.test.ts parses the manifest/Dockerfile install seam and asserts that the exact OpenCode CLI version matches the exact agent-runner SDK and versions.json pin. The opencode-ai CLI binary is not importable, so it is guarded by this structural test plus the container build — not the registration test.
• pnpm run build type-checks the host provider's consumption of the host-side container-config registry; the container typecheck does the same for the container provider against the agent-runner core APIs.

The pre-existing opencode.factory.test.ts imports opencode.ts directly and self-registers, so it stays green even if a barrel import is removed — it is a unit test of createProvider('opencode'), not the registration guard. Keep it; it adds factory coverage but does not stand in for the registration tests above.

Build cache gotcha: The container buildkit caches COPY steps aggressively. If provider files were already present in the build context before, the new files may not be picked up. If you see "Unknown provider: opencode" after the build, prune the builder and rebuild:

docker builder prune -f && ./container/build.sh

8. Propagate to existing per-group overlays

Each agent group has a live source overlay at data/v2-sessions/<group-id>/agent-runner-src/providers/ that overrides the image at runtime. This overlay is created when the group is first wired and never auto-updated by image rebuilds. Any group that already existed before this skill ran needs the new files copied in manually.

for overlay in data/v2-sessions/*/agent-runner-src/providers/; do
  [ -d "$overlay" ] || continue
  cp container/agent-runner/src/providers/opencode.ts "$overlay"
  cp container/agent-runner/src/providers/mcp-to-opencode.ts "$overlay"
  cp container/agent-runner/src/providers/index.ts "$overlay"
  echo "Updated: $overlay"
done

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 DB still needs agent_provider set (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 that need an explicit API endpoint. The OpenCode container provider passes this as the upstream baseURL (e.g. https://api.deepseek.com/v1 or https://openrouter.ai/api/v1). Native xai OAuth is the exception: omit this variable so OpenCode uses its native XAI transport and the mounted OAuth state.

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

Example: native XAI OAuth (no ANTHROPIC_BASE_URL)

When OPENCODE_PROVIDER is xai, keep the canonical xai/grok-* model ids and omit ANTHROPIC_BASE_URL. The native XAI provider uses the OAuth state in the group's persistent /opencode-xdg mount. Run scripts/reauth-xai.sh when the OAuth state needs to be established or refreshed.

OPENCODE_PROVIDER=xai
OPENCODE_MODEL=xai/grok-4.6
OPENCODE_SMALL_MODEL=xai/grok-4.3

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 AGENT_PROVIDER=opencode (DB agent_provider) 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}"

Per group / per session

Set "provider": "opencode" in the group's container.json (groups/<folder>/container.json) — the in-container runner reads provider from there, not from the DB. The DB columns agent_groups.agent_provider and sessions.agent_provider (session overrides group) only drive host-side provider contribution — per-session XDG mount, OPENCODE_* env passthrough — and do not propagate into container.json at spawn time. Set both, or just edit container.json; if they disagree, the runner uses container.json and the host-side resolver falls back through session → group → container.json → 'claude'.

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 registration and Dockerfile guards in step 7 verify the wiring. To confirm an end-to-end round-trip, set agent_provider = 'opencode' (or "provider": "opencode" in the group's container.json) on a test group, 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.