Guide

Quick Start

From zero to your first Blue Claw call in a few minutes. Change one setting; keep your stack.

Blue Claw serves native OpenAI and Anthropic routes, and TypeSafe's System One route for decision models. If your agent already talks to one of these APIs, you're most of the way there. Swap the base URL, drop in a key, and your recurring workloads run on lower-cost open models.

1. Get an API key

Sign in to the console with your email. We send a 6-digit code, with no password. Buy prepaid credits under Billing, then create a key that starts with bc_ under API Keys and keep it somewhere safe. It's the only credential your client needs.

2. Pick a model

Each model lists the endpoints it supports, and Blue Claw doesn't translate between protocols. Replace MODEL_ID in the samples below with an ID from the Models page that lists the route your client uses: an Anthropic client needs /v1/messages, and Codex needs /v1/responses.

3. Make your first call

Send a normal chat completion. Streaming works exactly as it does on OpenAI. If it comes back, you're live.

curl https://staging-api.blueclaw.network/v1/chat/completions \
  -H "Authorization: Bearer bc_your-key-here" \
  -H "Content-Type: application/json" \
  -d '{"model": "MODEL_ID", "messages": [{"role": "user", "content": "Hello, Blue Claw!"}]}'

4. Set up your SDK or coding agent

These setups cover the official OpenAI and Anthropic SDKs, TypeSafe's SDK for decision models, Claude Code, Codex, and opencode, along with other tools that read the same settings.

OpenAI SDK
from openai import OpenAI

client = OpenAI(
    base_url="https://staging-api.blueclaw.network/v1",
    api_key="your-api-key",
)

response = client.chat.completions.create(
    model="MODEL_ID",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)
Anthropic SDK
from anthropic import Anthropic

client = Anthropic(
    base_url="https://staging-api.blueclaw.network",
    api_key="your-api-key",
)

message = client.messages.create(
    model="MODEL_ID",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content[0].text)

Anthropic clients take the API's root as their base URL. Use a model that lists /v1/messages.

TypeSafe SDK
from typesafe_sdk import Noul, RetryPolicy, TypeSafeClient

client = TypeSafeClient(
    base_url="https://staging-api.blueclaw.network",
    api_key="your-api-key",
    model="MODEL_ID",
    retry=RetryPolicy(max_retries=0),
    compression=False,
)

result = client.system_one(
    state="The parcel arrived damaged.",
    questions={"needs_help": Noul(instructions="Does the customer need help?")},
)
print(result.nouls["needs_help"].noul)

TypeSafe's SDK retries a failed call and compresses a large body by default. Each retry is another paid call, and the API refuses compressed bodies, so turn both off. Pass images with extra_body, and use a model that lists /v1/systemone.

Claude Code
export ANTHROPIC_BASE_URL="https://staging-api.blueclaw.network"
export ANTHROPIC_AUTH_TOKEN="your-api-key"
export ANTHROPIC_MODEL="MODEL_ID"
export ANTHROPIC_DEFAULT_OPUS_MODEL="MODEL_ID"
export ANTHROPIC_DEFAULT_SONNET_MODEL="MODEL_ID"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="MODEL_ID"
# Removes pre-release betas and their fields from each request.
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1

claude

Anthropic says it doesn't support routing Claude Code to non-Claude models through any gateway. The protocol is documented and this setup uses it, but a Claude Code update could break it, and neither we nor Anthropic can promise otherwise. Use a model that lists /v1/messages.

Codex
# ~/.codex/config.toml
model = "MODEL_ID"
model_provider = "blueclaw"

[model_providers.blueclaw]
name = "Blue Claw"
base_url = "https://staging-api.blueclaw.network/v1"
env_key = "BLUECLAW_API_KEY"
wire_api = "responses"

Codex speaks only the Responses route, so use a model that lists /v1/responses. Its web_search tool does nothing here, because the model server silently drops it. Leave apply_patch off, because the model server rejects its grammar.

opencode
// ~/.config/opencode/opencode.json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "blueclaw": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Blue Claw",
      "options": {
        "baseURL": "https://staging-api.blueclaw.network/v1",
        "apiKey": "{env:BLUECLAW_API_KEY}"
      },
      "models": {
        "MODEL_ID": {
          "name": "MODEL_ID",
          "limit": { "context": 128000, "output": 8192 }
        }
      }
    }
  },
  "model": "blueclaw/MODEL_ID"
}

Set limit.output to a sensible cap. The default can reach 256k tokens, which inflates the hold on your balance. This sample uses @ai-sdk/openai-compatible for chat. Use @ai-sdk/openai for Responses or @ai-sdk/anthropic for Messages. Don't name the provider vllm, because opencode then replaces your configured models.

OpenClaw
// ~/.openclaw/openclaw.json
// OpenClaw uses JSON5, so comments are supported.
{
  "agents": {
    "defaults": {
      "model": {
        "primary": "blueclaw/MODEL_ID"
      }
    }
  },

  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback"
  },

  "models": {
    "mode": "merge",
    "providers": {
      "blueclaw": {
        "baseUrl": "https://staging-api.blueclaw.network/v1",
        "apiKey": "${BLUECLAW_API_KEY}",
        "api": "openai-completions",
        "headers": {
          "User-Agent": "OpenClaw/BlueClaw"
        },
        "authHeader": true,
        "models": [
          {
            "id": "MODEL_ID",
            "name": "MODEL_ID",
            "api": "openai-completions",
            "input": ["text"]
          }
        ]
      }
    }
  }
}
Hermes / env
# Hermes-style agents, LiteLLM routers, and most
# tools that speak the OpenAI API read these variables:

export OPENAI_BASE_URL="https://staging-api.blueclaw.network/v1"
export OPENAI_API_KEY="your-api-key"

# Then point your agent at a model that lists /v1/chat/completions:
#   model = "MODEL_ID"
curl
curl https://staging-api.blueclaw.network/v1/chat/completions \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "MODEL_ID",
    "messages": [{"role": "user", "content": "Hello!"}]
  }'

Coding agents need tool calls. Use a model we've marked ready for agents, which means it passed a paid tool-calling test.

Claude Code on other models isn't supported by Anthropic. Anthropic says it doesn't support routing Claude Code to non-Claude models through any gateway. The protocol is documented and this setup uses it, but a Claude Code update could break it, and neither we nor Anthropic can promise otherwise.

OpenClaw, Hermes-style agents, LiteLLM routers, and other tools that speak the OpenAI API work the same way: set the base URL and API key in the tool's config, pick a model, and point your recurring passes at Blue Claw. Keep another API on hand for the few calls that truly need frontier quality.

What you can call today

  • Chat completions, Responses, and Messages, including streaming.
  • Models, to list what your key can reach.
  • Embeddings for search, RAG, and indexing.
  • Image generation on open image models.
  • Text-to-speech and speech-to-text.
  • Decisions through TypeSafe's System One API, for models that answer typed questions with probabilities.

Durable async jobs and video AI tools are in development.

This is a starting point. Deeper, per-tool recipes are on the way. Stuck on something? Ask in the Discord.