Integrate OpenCode with Docker CLIProxyAPI and RTK on Debian

Tutorial

This guide shows how to connect OpenCode to a local CLIProxyAPI instance running in Docker and use RTK to compact bash output before OpenCode reads it.

Overview Flow

OpenCode
  -> API call to http://localhost:8317/v1
CLIProxyAPI (Docker)
  -> forwards through OAuth subscription
Claude / Gemini / Codex
  <- RTK hook compacts bash output before OpenCode reads it

Step 1: Check That CLIProxyAPI Docker Is Running

docker ps | grep cliproxy

# Quick test
curl http://localhost:8317/v1/models | jq
# If you mapped a different port, replace 8317 accordingly.

If the API is up, you should get a valid response like below.

{
  "error": "Missing API key"
}

Step 2: Install RTK

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

rtk --version

This installs rtk into your local user environment and ensures it is available in your shell.

Step 3: Install the RTK Hook for OpenCode

rtk init -g --opencode
# Restart OpenCode after installation

RTK uses the OpenCode plugin tool.execute.before to automatically rewrite bash commands from:

<command>

to:

rtk <command>

before OpenCode executes them.

Step 4: Point OpenCode to CLIProxyAPI

Create or edit ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "cliproxyapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CLIProxyAPI",
      "options": {
        "baseURL": "http://localhost:8317/v1",
        "apiKey": "YOUR_API_KEY"
      },
      "models": {
        "claude-sonnet-4-5-20250929": {
          "id": "claude-sonnet-4-5-20250929",
          "name": "Claude Sonnet (via CLIProxy)",
          "limit": { "context": 200000, "output": 64000 }
        },
        "gemini-2.5-flash": {
          "id": "gemini-2.5-flash",
          "name": "Gemini 2.5 Flash (via CLIProxy)",
          "limit": { "context": 1048576, "output": 65535 }
        }
      }
    }
  }
}

Important: The model IDs must exactly match what your CLIProxyAPI instance exposes. Verify them with curl http://localhost:8317/v1/models -H "Authorization: Bearer YOUR_API_KEY".

Step 5: Test the Full Setup

# 1. Verify CLIProxyAPI returns models using the same key from your config
curl -s http://localhost:8317/v1/models \
  -H "Authorization: Bearer YOUR_API_KEY"

# 2. Send a manual test request
curl -X POST http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"model": "gemini-2.5-flash", "messages": [{"role": "user", "content": "hi"}]}'

# 3. Check whether RTK is intercepting commands
rtk gain
rtk git status   # You should see compact output

If all three checks work, OpenCode, CLIProxyAPI, and RTK are connected properly.

Important Notes

RTK only filters Bash tool calls. Since OpenCode uses bash to execute commands, the hook works well in this setup.

If you want more explicit optimization for file and search operations, use commands like these:

rtk read src/main.rs      # instead of cat
rtk grep "pattern" .      # instead of grep
rtk ls .                  # instead of ls

This gives OpenCode more compact, structured command output to work with.