OpenCode Controller Skill: Setup Guide for OpenClaw Users

If you searched "opencode-controller openclaw" or "opencode-controller clawhub," you almost certainly hit our pillar essay on the OpenClaw + OpenCode workflow and bounced because it didn't show you how to actually install the thing. This post is the missing setup guide.

We've been running the opencode-controller skill in production for three months across our agency's internal tooling and a handful of client projects. What follows is the install path that actually works, the config that survived contact with real workloads, and the gotchas we hit so you don't have to.

What the skill does

The opencode-controller skill exposes /opencode slash commands inside an OpenClaw session. Without it, OpenClaw treats OpenCode as one model behind a single endpoint. With it, OpenClaw can:

• Switch between providers (OpenAI proxy, Google OAuth, Anthropic) mid-session
• Pick a specific model per task (Gemini 3 for UI mocks, Opus 4.6 for schema work, Kimi K2 for cheap iteration)
• Persist and resume sessions across restarts
• Route a sub-agent's request to a different model than the parent

The skill itself has no file-system or terminal access. That's why it's safe to install from ClawHub even before you've audited everything else in your skill library.

Prerequisites

You need:

1. OpenClaw v0.18 or later (openclaw --version). Older versions don't support the slash-command extension surface this skill uses.
2. OpenCode configured with at least one provider. If you're using the Google OAuth flow, run opencode auth google and verify with opencode models.
3. ClawHub access — local or registry. We recommend the registry; we'll cover that path here.

If openclaw skills list errors, you're on a version that predates skill support. Upgrade first.

Install from ClawHub

openclaw skills install opencode-controller

OpenClaw will fetch the manifest from ClawHub, show you the permission summary (should read "no file access, no shell access"), and prompt for confirmation. Read the permission summary every time, even on a skill you've installed before — see our ClawHub security audit guide for why this matters more than people realize.

Verify the install:

openclaw skills list | grep opencode-controller
# expected: opencode-controller@1.4.x  (verified)

If the line says (unverified), stop and re-pull. The verified Agent Trust Hub build is the one with the published audit log; community builds with the same name have shipped before.

First-run config

Drop a config file at ~/.openclaw/skills/opencode-controller/config.toml:

[default]
provider = "google"
model = "gemini-3-pro"

[providers.google]
auth = "oauth"
fallback_model = "gemini-2.5-flash"

[providers.openai]
auth = "env:OPENAI_API_KEY"
default_model = "gpt-4o"

[providers.anthropic]
auth = "env:ANTHROPIC_API_KEY"
default_model = "claude-opus-4-7"

[routing]
# Cheap, high-throughput iteration goes to Kimi K2 via the openrouter proxy
cheap_default = "openrouter:moonshotai/kimi-k2"
# Anything tagged "schema" or "migration" goes to Opus
heavy_tags = ["schema", "migration", "auth"]
heavy_model = "anthropic:claude-opus-4-7"

Restart OpenClaw. From an active session you should now see:

> /opencode models
google      gemini-3-pro, gemini-2.5-flash
openai      gpt-4o, gpt-4.1
anthropic   claude-opus-4-7, claude-sonnet-4-6
openrouter  moonshotai/kimi-k2

Daily-use commands

The five commands you'll actually type:

/opencode cost is the one we underestimated. When you can see "Gemini 3: $0.41, Opus: $3.18, Kimi K2: $0.06" mid-session, you start tagging routing more aggressively. We cut our internal tooling spend by ~62% in the first month after wiring this up — most of that came from realizing how often we were burning Opus on tasks Kimi K2 handled fine.

Routing in practice

The routing block is where the skill earns its keep. Our working ruleset for client projects:

• Default: Kimi K2 via OpenRouter. Cheap, fast, ~80% as good as Sonnet on most code tasks. See our Kimi K2 + Claude Code cost analysis for benchmarks.
• Tagged schema, migration, or auth: Opus 4.6. The places where wrong is expensive.
• Tagged ui-mock: Gemini 3 Pro. Strong at design intent.
• Tagged review: Whatever model didn't write the original code. Cheap insurance against the same model's blind spots.

Tag a sub-task with /opencode tag <tag> before kicking off the work; the skill applies the route to the next agent invocation and resets after.

Gotchas we hit

Session resume restores model but not env. If you saved a session under provider openai with OPENAI_API_KEY set and resume on a machine without that env, you'll get a silent fallback to the default provider. The skill logs it, but the log line is at info level — bump OPENCLAW_LOG=debug if model selections feel off.

OAuth tokens expire on a 1h cycle. The skill refreshes them, but only on command invocation. A long-running sub-agent that doesn't hit /opencode calls can run with a stale token and 401 mid-task. Our workaround: a no-op /opencode use $current_model heartbeat every 30 minutes for sessions that exceed an hour.

Kimi K2 via OpenRouter rate-limits aggressively. If you push more than ~40 requests/minute, expect 429s. The skill retries with jitter, but for build-loop workloads, route to a different cheap model in the burst window.

The cost command undercounts cached Anthropic prompts. Cached input tokens are billed at 10% but reported in the skill's cost view at 100% as of v1.4.2. If your bill looks suspiciously low compared to the skill's number, that's why — it's not a billing bug.

When to skip this skill

If you only ever use one model with OpenClaw, you don't need the controller skill. The startup cost (config, audit, version pinning) outweighs the benefit. The skill earns its keep when you have at least three providers configured and you're consciously routing tasks for cost or quality reasons.

For everyone else: the controller skill is the difference between OpenClaw as "another AI tool" and OpenClaw as a routing layer for your AI infrastructure.

What's next

The next post in this cluster covers free model routing with Kimi K2 inside the controller skill — that's where the cost numbers above get into real detail. If you're new to OpenClaw entirely, start with the OpenClaw + OpenCode pillar essay.

Questions or hit a config you want a second opinion on? We answer technical questions on LinkedIn and through our contact form.