OpenCode Zen and Go Catalogs in OpenClaw

OpenClaw surfaces two hosted catalogs from OpenCode:

A single OpenCode API key setup serves both catalogs (OPENCODE_API_KEY, alias OPENCODE_ZEN_API_KEY). Go is still gated behind its own paid subscription: a Zen key alone does not give you Go access. The runtime provider ids are kept distinct in OpenClaw so that per-model routing upstream remains accurate.

On requests to https://opencode.ai, OpenClaw includes a stable x-opencode-session conversation header over the Anthropic, Gemini, OpenAI Chat Completions, and OpenAI Responses transports. That header stays on even when prompt caching is turned off. Callers working directly with SDK streams should set sessionId in their stream options.

For Zen and Go discovery and model requests on the OpenAI-compatible, Anthropic, and Gemini transports, the client identifies itself as openclaw/<version> at its native endpoints. This covers the current /inference/... routes that upstream discovery returns as well as the retained /zen/... aliases. Proxy URLs you define yourself do not get this attribution. OpenClaw never pretends to be the OpenCode client.

Each standalone openclaw infer model run --local call, and the prepared completion helper, builds a new routing header per invocation whenever no routing header or session identifier is given explicitly. The generated value lives only in the header: it neither opens a conversation nor turns on session-based caching. Routing headers set explicitly by the model or the caller are kept no matter what casing their names use.

Getting started

Zen catalog

Best for: the curated OpenCode multi-model proxy (Claude, GPT, Gemini, GLM, DeepSeek, Kimi, MiniMax, Qwen).

Run onboarding

openclaw onboard --auth-choice opencode-zen

Or pass the key directly:

openclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY"

Set a Zen model as the default

openclaw config set agents.defaults.model.primary "opencode/gpt-5.6-sol"

Verify models are available

openclaw models list --provider opencode

Go catalog

Best for: the separately subscribed Go lineup across DeepSeek, GLM, GPT, Grok, Hy3, Kimi, MiMo, MiniMax, and Qwen.

Use the bundled Go catalog

OpenCode Go ships with OpenClaw, so you need neither a separate plugin install nor a Gateway restart.

Run onboarding

openclaw onboard --auth-choice opencode-go

Or pass the key directly:

openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"

Set a Go model as the default

openclaw config set agents.defaults.model.primary "opencode-go/kimi-k3"

Verify models are available

openclaw models list --provider opencode-go

Config example

{
  env: { vars: { OPENCODE_API_KEY: "sk-..." } },
  agents: { defaults: { model: { primary: "opencode/gpt-5.6-sol" } } },
}

Provider catalogs

Zen

Run openclaw models list --provider opencode to see the list that is currently active. Model availability and promotional routes may change without any OpenClaw release.

Live discovery merges the models your OpenCode account can reach with authoritative model metadata from https://models.opencode.ai/api.json. That catalog is fetched and cached only when OpenCode Zen or Go is configured, or when it is picked explicitly with OpenCode credentials; startup and unrelated providers never download it. Newly listed chat models work without updating OpenClaw. Where metadata is trusted, models keep their upstream transport and capabilities; listed IDs lacking metadata fall back to Zen's native OpenAI-compatible route with default limits. A key-scoped response may leave out models that the workspace cannot use. Metadata and lifecycle status are refreshed together; deprecated models drop out of active discovery and its offline fallback. Existing configurations can still resolve deprecated explicit refs, but those refs no longer appear as current recommendations.

When the account list fails, the catalog outcome is a failure rather than a successful seed list. An account response that succeeds but is empty or fully filtered stays empty. If the separate public metadata feed is unreachable, it may still draw on trusted offline metadata; the account-list request is neither replaced nor retried by that.

Certain Zen free-tier models accept requests only from the OpenCode client. A 403 FreeTierError indicates a restricted free tier for that model, not an expired saved key. Pick a different model, or switch to a paid plan that permits API access. Signing in again or changing the User-Agent will not grant access. The refusal marks just the selected model unavailable; your credential is not put into cooldown for other models. An ID appearing in the account listing does not by itself prove the model can run in OpenClaw. The listing carries no free-tier flag, so OpenClaw does not infer access from model names. A 402 insufficient-funds response means the account needs more credit; it does not mean the model ID is unknown.

Price estimates refresh too, via the hosted model catalog, which draws on the same public OpenCode pricing feed that live discovery uses. Hosted updates take effect after the next Gateway restart; the bundled snapshot still works offline. Prices you set explicitly in your configuration, or in agent-local models.json, take precedence. These figures are advertised-price estimates, not verified invoice totals.

Kimi K3 thinking

For opencode/kimi-k3, pick Off, Low, High, or Max. The provider default is High. Off sends reasoning_effort: "none" explicitly; leaving the effort out does not turn off reasoning on Zen. These settings govern the Zen route only, not other Kimi providers. The picker may additionally list Ultra, which is a separate harness mode.

Go

Consult OpenCode Go for discovery, routing, and access requirements. Go's model-list endpoint advertises the general lineup; a model being listed does not prove your account can run it.

Advanced configuration

API key aliases

OPENCODE_ZEN_API_KEY is also accepted as an alias for OPENCODE_API_KEY.

Shared credentials

If you enter one OpenCode key during setup, credentials for both runtime providers can be stored. That neither creates a Go subscription nor grants Go entitlement; subscribe to Go in the OpenCode console before using it.

Getting an API key

Register for an OpenCode account, then create an API key at opencode.ai/auth. The OpenCode dashboard is where billing and catalog availability get managed.

Gemini replay behavior

Refs for OpenCode models backed by Gemini continue to use the proxy-Gemini path. As a result, OpenClaw applies its Gemini thought-signature sanitation there, and native Gemini replay validation and bootstrap rewrites stay disabled.

Non-Gemini replay behavior

For OpenCode refs that are not Gemini, the minimal OpenAI-compatible replay policy applies.

Pricing and privacy

Billing, retention, and training policies differ by model. Consult the current OpenCode Zen pricing and policy before you pick a route. Models offered free of charge may be temporary feedback programs.

Related

• OpenCode Go, Catalog discovery and access requirements for Go.

• Model selection, How to choose providers and model refs, plus failover behavior.

• Configuration reference, The complete config reference covering agents, models, and providers.

• OpenCode plugin reference, Native sessions, the session catalog toggle, and plugin config keys.