AI Provider Setup

OpenCrabs supports 15 providers (14 built-in + Custom OpenAI-Compatible). Configure them through the onboarding wizard or manually via config.toml and keys.toml at ~/.opencrabs/.

Setup via Onboarding Wizard

The fastest way to configure a provider is the interactive wizard. Run /onboard:provider (or /onboard and navigate to step 3).

Keyboard Navigation

Live-Fetch Providers (recommended)

For providers with a /v1/models API endpoint, the wizard fetches the model list live after you enter your API key.

Supported: Anthropic, OpenAI, OpenRouter, Gemini, MiniMax, Qwen (DashScope), Ollama, z.ai GLM

Flow:

1. Use ↑/↓ to select your provider (e.g. OpenRouter)
2. Press Enter — advances to the API key field
3. Paste your API key (e.g. sk-or-...)
4. Press Enter — triggers a live fetch from the provider’s /v1/models endpoint
5. Use ↑/↓ to browse models, or type to filter (case-insensitive substring match)
6. Press Enter on your chosen model — saves config and advances

Tip: If you’ve already configured a key, the wizard detects it (shown as ••••••••) and skips straight to the model picker. Press Enter to re-fetch models with the existing key.

OAuth Providers (GitHub Copilot, Codex)

No API key needed — authenticate through your browser.

Flow:

1. Select GitHub Copilot or Codex
2. Press Enter — starts the device-code PKCE flow
3. A user code and URL appear (e.g. github.com/login/device)
4. Open the URL in your browser, enter the code, and authorize
5. Tokens are saved automatically to ~/.opencrabs/auth/
6. Models are fetched live — pick one and press Enter

CLI Providers (Claude CLI, OpenCode CLI, Codex CLI)

Use your existing CLI subscription — no separate API key.

Flow:

1. Select the CLI provider (e.g. Claude CLI)
2. Press Enter — skips the API key field (none needed)
3. Models are fetched from the local binary (claude models, opencode models, etc.)
4. Pick a model and press Enter

Requirements: The CLI binary must be installed and authenticated in your PATH.

z.ai GLM (Zhipu AI)

z.ai has two endpoint types. The wizard asks which one before the API key.

Flow:

1. Select z.ai GLM
2. Press Enter — advances to Endpoint Type selector
3. Use ↑/↓ to choose API (general) or Coding (CodeGeeX)
4. Press Enter — advances to API key field
5. Paste your key, press Enter — fetches models
6. Pick a model and press Enter

Custom OpenAI-Compatible

For Ollama, LM Studio, LocalAI, Groq, NVIDIA, vLLM, or any OpenAI-compatible endpoint.

Flow:

1. Select Custom OpenAI-Compatible (last in the list)
2. Press Enter — advances to Name field
3. Name — type a provider identifier (e.g. ollama, lm-studio, nvidia). Press Enter — normalized to a TOML-safe key
4. Base URL — paste your endpoint (e.g. http://localhost:1234/v1). Press Enter
5. API Key — paste if required, or leave empty for local endpoints. Press Enter
6. Model — you have two options:
   • Type or paste a model name — use this for newly-launched models not yet available on the live API (e.g. qwen3.6-35b-a3b-gguf)
   • Press Enter on empty field — triggers a live fetch from {base_url}/models, then pick from the list
7. Context Window — enter the token limit (e.g. 128000). Press Enter — saves and advances

Context Window Recommendation: Set to 200000 (200k tokens) for best results. OpenCrabs handles large contexts gracefully with smart auto-compaction that keeps you always up to date without manual intervention.

Local LLMs: No API key needed — just set base URL and model name. If the model is already running, paste the name directly. If you want to browse available models, leave the Model field empty and press Enter to fetch the list from your local server.

Re-running Provider Setup

Manual Configuration (advanced)

If you prefer editing files directly, configure providers in config.toml and keys.toml.

Anthropic Claude

Models: claude-opus-4-6, claude-sonnet-4-5, claude-haiku-4-5, and legacy models — fetched live from the API.

# keys.toml
[providers.anthropic]
api_key = "sk-ant-..."

# config.toml
[providers.anthropic]
enabled = true
default_model = "claude-sonnet-4-20250514"

Features: Streaming, tool use, extended thinking, vision, 200K context window.

OpenAI

Models: GPT-5 Turbo, GPT-5, and others — fetched live.

# keys.toml
[providers.openai]
api_key = "sk-YOUR_KEY"

OpenRouter — 400+ Models

Access 400+ models from every major provider through a single API key. Includes free models (DeepSeek-R1, Llama 3.3, Gemma 2, Mistral 7B).

# keys.toml
[providers.openrouter]
api_key = "sk-or-YOUR_KEY"

Get a key at openrouter.ai/keys. Model list is fetched live — no binary update needed when new models are added.

Google Gemini

Models: gemini-2.5-flash, gemini-2.0-flash, gemini-1.5-pro — fetched live.

# keys.toml
[providers.gemini]
api_key = "AIza..."

# config.toml
[providers.gemini]
enabled = true
default_model = "gemini-2.5-flash"

Features: Streaming, tool use, vision, 1M+ token context window.

Gemini also powers the separate image generation and vision tools. See Image Generation & Vision.

GitHub Copilot

Use your existing GitHub Copilot subscription — no separate API charges. Authenticates via OAuth device flow.

# config.toml
[providers.github_copilot]
enabled = true

Setup: Run /onboard:providers → select GitHub Copilot → follow the device code flow at github.com/login/device. Models are fetched live from the Copilot API.

Requirements: An active GitHub Copilot subscription (Individual, Business, or Enterprise).

z.ai (Zhipu AI)

Models: GLM-4-Plus, GLM-4-Flash, GLM-4-0520, CodeGeeX — fetched live. Two endpoint types: General API and Coding API.

# keys.toml
[providers.zai]
api_key = "your-api-key"

# config.toml
[providers.zai]
enabled = true
default_model = "glm-4-plus"

Get your API key at open.bigmodel.cn.

Claude CLI

Use your existing Claude Code subscription through the local claude binary — no separate API key needed. Supports streaming and extended thinking.

# config.toml
[providers.claude_cli]
enabled = true

Requirements: The claude CLI must be installed and authenticated. Models are detected automatically.

Ollama

Run any Ollama model natively — no custom provider setup needed. Supports both local (localhost:11434) and cloud (api.ollama.com) instances.

# config.toml
[providers.ollama]
enabled = true
default_model = "llama3"

# keys.toml (optional — only for cloud Ollama)
[providers.ollama]
api_key = "your-api-key"

Features: Streaming, tool use, local model tool-call extraction from text. Models are fetched live from the Ollama API.

Requirements: Ollama must be running locally (ollama serve) or you must have a cloud Ollama API key.

OpenCode CLI

Use the local opencode binary for free LLM completions — no API key or subscription needed. Supports NDJSON streaming and extended thinking.

# config.toml
[providers.opencode_cli]
enabled = true

Requirements: The opencode binary must be installed and available in your PATH. Models are fetched live via opencode models.

Codex CLI

Use OpenAI’s @openai/codex CLI as a native provider. User authenticates once via codex CLI; OpenCrabs piggybacks on cached credentials — zero API key handling. Non-interactive mode via codex exec --json with JSONL streaming.

# config.toml
[providers.codex_cli]
enabled = true

Models: GPT-5.5, GPT-5.4, GPT-5.3-Codex

Requirements: The codex CLI must be installed (npm install -g @openai/codex) and authenticated. Models are detected automatically.

Codex OAuth

Native OpenAI Codex subscription auth via device-code PKCE flow. No CLI dependency, no API key. User authenticates through browser once; tokens stored in ~/.opencrabs/auth/codex.json with automatic refresh and background rotation.

# config.toml
[providers.codex]
enabled = true

Models: GPT-5.5, GPT-5.4, GPT-5.3-Codex (curated GPT-5 model list)

Setup: Run /onboard:provider → select Codex OAuth → follow the device code flow at auth.openai.com/codex/device. Two-step PKCE exchange: device auth poll → authorization code → token exchange.

Requirements: An active OpenAI Codex subscription. No CLI installation needed.

MiniMax

Models: MiniMax-M2.7, MiniMax-M2.5, MiniMax-M2.1, MiniMax-Text-01

# keys.toml
[providers.minimax]
api_key = "your-api-key"

Get your API key from platform.minimax.io. Model list comes from config.toml (no /models endpoint).

Custom (OpenAI-Compatible)

Use for Ollama, LM Studio, LocalAI, Groq, or any OpenAI-compatible API.

# config.toml
[providers.custom.lm_studio]
enabled = true
base_url = "http://localhost:1234/v1"
default_model = "qwen2.5-coder-7b-instruct"
models = ["qwen2.5-coder-7b-instruct", "llama-3-8B"]

Local LLMs: No API key needed — just set base_url and default_model.

Remote APIs (Groq, etc.): Add the key in keys.toml:

[providers.custom.groq]
api_key = "your-api-key"

Multiple Custom Providers

Define as many as you need with different names:

[providers.custom.lm_studio]
enabled = true
base_url = "http://localhost:1234/v1"
default_model = "qwen2.5-coder-7b-instruct"

[providers.custom.ollama]
enabled = false
base_url = "http://localhost:11434/v1"
default_model = "mistral"

Free Prototyping with NVIDIA API

Kimi K2.5 is available for free on the NVIDIA API Catalog — no billing required.

# config.toml
[providers.custom.nvidia]
enabled = true
base_url = "https://integrate.api.nvidia.com/v1"
default_model = "moonshotai/kimi-k2.5"

# keys.toml
[providers.custom.nvidia]
api_key = "nvapi-..."

Fallback Provider Chain

Configure automatic failover when the primary provider fails (rate limits, outages, errors). Fallbacks are tried in order until one succeeds.

# config.toml
[providers.fallback]
enabled = true
providers = ["openrouter", "anthropic"]  # Tried in order on failure

Each fallback provider must have its API key configured in keys.toml. Both complete() and stream() calls are retried transparently — no changes needed downstream.

Single fallback shorthand:

[providers.fallback]
enabled = true
provider = "openrouter"

Or just ask your Crab: “Set up fallback providers using openrouter and anthropic” — it will configure config.toml for you at runtime.

Vision Model

When your default chat model doesn’t support vision, set vision_model to a vision-capable model on the same provider. This registers a vision tool that the agent can call — it sends the image to the vision model, gets a description back, and the chat model uses that context to reply.

# config.toml
[providers.minimax]
enabled = true
default_model = "MiniMax-M2.5"
vision_model = "MiniMax-Text-01"  # Agent calls vision tool → this model describes image → M2.5 replies

[providers.openai]
enabled = true
default_model = "gpt-5-nano"
vision_model = "gpt-5-nano"

MiniMax auto-configures vision_model = "MiniMax-Text-01" on first run. You can also ask your Crab to set it up: “Configure vision model for MiniMax” — it will update config.toml at runtime.

This is separate from the Gemini image tools which provide dedicated generate_image and analyze_image tools.

Per-Session Providers

Each session remembers its provider and model. Switch to Claude in one session, Gemini in another — switching sessions restores the provider automatically.