opencode

opencode is an OSS terminal coding agent with pluggable providers. Because it supports any OpenAI-compatible or Anthropic-compatible endpoint, you can point it at the LangWatch AI Gateway and pick up budgets, guardrails, policy-rule filters, and trace propagation without changing the agent itself.

Setup

opencode reads ~/.config/opencode/opencode.json (or the project-local opencode.json). Configure the gateway as a custom provider:

{
  "provider": {
    "langwatch-gateway": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LangWatch Gateway",
      "options": {
        "baseURL": "https://gateway.langwatch.ai/v1",
        "apiKey": "{env:LANGWATCH_VK}"
      },
      "models": {
        "gpt-5-mini": { "name": "GPT-5 mini (via gateway)" },
        "claude-haiku-4-5-20251001": { "name": "Claude Haiku 4.5 (via gateway)" },
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6 (via gateway)" }
      }
    }
  }
}

Then set your virtual key and run opencode:

export LANGWATCH_VK="vk-lw-01HZX..."
opencode

Pick the gateway provider in the model picker (Ctrl-X M).

Using Anthropic-shape models via `/v1/messages`

If you want opencode to hit the Anthropic-native endpoint (preserves cache_control blocks byte-for-byte), use the @ai-sdk/anthropic provider instead:

{
  "provider": {
    "langwatch-gateway-anthropic": {
      "npm": "@ai-sdk/anthropic",
      "name": "LangWatch Gateway (Anthropic)",
      "options": {
        "baseURL": "https://gateway.langwatch.ai",
        "apiKey": "{env:LANGWATCH_VK}"
      },
      "models": {
        "claude-sonnet-4-6": { "name": "Claude Sonnet 4.6 (cache-aware)" }
      }
    }
  }
}

The gateway serves both /v1/chat/completions and /v1/messages on the same VK. Pick the shape opencode knows how to emit for your model family.

Trace propagation

opencode passes request-level headers through its provider config. To make gateway spans nest under the opencode trace:

{
  "provider": {
    "langwatch-gateway": {
      "options": {
        "headers": {
          "traceparent": "{env:OPENCODE_TRACEPARENT}",
          "X-LangWatch-Thread-Id": "{env:OPENCODE_SESSION_ID}"
        }
      }
    }
  }
}

If OPENCODE_TRACEPARENT is set by the shell wrapper, the gateway parents its span under that trace and the cost is attributed to the opencode session, no double counting. See SDKs → trace propagation for the header shape.

Governance recipes

Hackday mode: disable cache, warn on spend

{
  "provider": {
    "langwatch-gateway": {
      "options": {
        "headers": { "X-LangWatch-Cache": "disable" }
      }
    }
  }
}

Pair with a principal budget on the hackday VK: window day, limit $20, on_breach: warn. Engineers see a warning but aren’t blocked mid-experiment.

Block dangerous shell tools

VK policy_rules.tools: ["bash", "shell", "exec"]. opencode requests a tool with that name → 403 tool_not_allowed before it ever leaves the gateway. See Policy Rules.

Troubleshooting

Model picker shows only stock providers: ensure opencode.json is in ~/.config/opencode/ or $PWD. opencode logs the loaded config path on startup.
401 invalid_api_key, {env:LANGWATCH_VK} didn’t expand. Export the env var before launching opencode.
Streaming hangs mid-response: check X-LangWatch-Request-Id against the LangWatch trace; gateway emits a terminal event: error on mid-stream failures (it won’t silently switch providers). See Streaming.
opencode run hangs indefinitely on custom provider (1.14.x), confirmed regression in opencode 1.14.22: opencode models correctly lists the custom provider’s models, but opencode run -m custom-provider/model only emits the proxy-startup log line then hangs (no instance creation, no HTTP call to the gateway, exit 124 at any timeout). Reproduces across cwd opencode.json and global ~/.config/opencode/opencode.json, with and without npm: "@ai-sdk/openai-compatible", with and without the package pre-installed at ~/.config/opencode/node_modules/@ai-sdk/openai-compatible/. Workarounds: pin opencode 1.13.x (pre-bug); or run via opencode --attach <server-url> against a long-running opencode serve instance instead of opencode run. Track upstream opencode-ai/opencode#5674 for fix.

Working configuration verified end-to-end

These steps were last validated against opencode 1.13.x + LangWatch AI Gateway feat/ai-gateway tip:

# 1. Mint a VK in LangWatch UI bound to your OpenAI provider credential
export LANGWATCH_VK=vk-lw-…

# 2. Configure opencode (one-shot)
mkdir -p ~/.config/opencode
cat > ~/.config/opencode/opencode.json <<'EOF'
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "langwatch": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LangWatch Gateway",
      "options": {
        "baseURL": "https://gateway.langwatch.ai/v1",
        "apiKey": "{env:LANGWATCH_VK}"
      },
      "models": {
        "gpt-4o-mini": { "name": "GPT-4o mini (via gateway)" }
      }
    }
  }
}
EOF

# 3. Run a task (or open the TUI without -m)
opencode run -m langwatch/gpt-4o-mini "Reply with the word: ok"

Trace lands in LangWatch with langwatch.virtual_key_id, gen_ai.usage.*, captured cost, and the full session attributed to the langwatch-gateway provider.

Get Started

SDK Integration

Coding CLI Integrations

Virtual Keys & Budgets

Governance

Providers

Features

API Reference

Self-Hosting

Cookbooks

Setup

Using Anthropic-shape models via `/v1/messages`

Trace propagation

Governance recipes

Hackday mode: disable cache, warn on spend

Block dangerous shell tools

Troubleshooting

Working configuration verified end-to-end

​Setup

​Using Anthropic-shape models via /v1/messages

​Trace propagation

​Governance recipes

​Hackday mode: disable cache, warn on spend

​Block dangerous shell tools

​Troubleshooting

​Working configuration verified end-to-end

Setup

Using Anthropic-shape models via `/v1/messages`

Trace propagation

Governance recipes

Hackday mode: disable cache, warn on spend

Block dangerous shell tools

Troubleshooting

Working configuration verified end-to-end