Claude Code Integration
OGX includes built-in support for connecting Claude Code, Anthropic's AI coding assistant, with a single command. Your OGX server's models are discovered automatically and mapped onto Claude Code's haiku/sonnet/opus tiers.
Quick Start
1. Start OGX
ogx go --no-auth --insecure
ogx go auto-detects running inference providers (vLLM, Ollama, OpenAI via OPENAI_API_KEY, and more). For a local, non-exposed server, --no-auth turns off the API key (no OGX_API_KEY needed below) and --insecure runs without TLS, so the connect step below needs no extra flags. Both are local-development only. By default, ogx go serves HTTPS with a self-signed certificate and prints API keys — pair those with ogx connect --insecure --api-key <key>.
2. Connect Claude Code
ogx connect claude
That's it. Claude Code launches with your OGX models mapped to its haiku/sonnet/opus tiers.
3. Test it out
The launched session is already connected — just type:
> What is 2+2?
> Create a Flask hello world app
> Write a quicksort in Rust
> Add documentation and tests
For one-shot runs from the shell, forward the prompt after -- (arguments after -- go to claude):
ogx connect claude -- -p "What is 2+2?"
Claude Code must be installed and on your PATH (install from claude.com/download).
How It Works
The ogx connect claude command:
- Queries the running OGX server for available models
- Filters out non-LLM models (embeddings, rerankers)
- Maps models onto Claude Code's three tiers (haiku/sonnet/opus) — by keyword in the model name, or the first available model as a fallback
- Launches Claude Code connected to the server
ogx connect claude
|
v
GET /v1/models (discover available models)
|
v
Map models to Claude tiers (haiku/sonnet/opus)
|
v
Launch claude pointed at the OGX server
|
v
Claude Code (connected to OGX)
Claude Code sends requests to the Anthropic Messages API (/v1/messages). OGX implements this API, translating between formats as needed:
What gets translated:
- Messages format: Anthropic → OpenAI format (when provider doesn't support Messages API natively)
- Tool calls: Anthropic
tool_useblocks → OpenAItool_calls - Streaming: OpenAI SSE events → Anthropic format (
message_start,content_block_delta, etc.) - Thinking blocks:
thinkingis mapped to the backend's reasoning effort for reasoning models, and the backend's reasoning text is returned as thinking blocks (see Extended thinking)
CLI Reference
ogx connect [--url URL] claude [--model MODEL] [--haiku-model MODEL] [--sonnet-model MODEL]
[--opus-model MODEL] [--print-env] [-- CLAUDE_ARGS...]
Options:
| Flag | Default | Description |
|---|---|---|
--model | First available model | Model ID to map to all three Claude tiers |
--haiku-model | --model value | Model ID for the haiku (fast) tier. Overrides --model |
--sonnet-model | --model value | Model ID for the sonnet (balanced) tier. Overrides --model |
--opus-model | --model value | Model ID for the opus (capable) tier. Overrides --model |
--url (group) | https://localhost:8321/v1 | OGX server base URL, including /v1. Applies to all ogx connect subcommands (port defaults from OGX_PORT env var) |
--api-key (group) | OGX_API_KEY env var, or none | Bearer API key for the OGX server. Applies to all ogx connect subcommands. |
--insecure / -k (group) | off | Allow HTTPS connections to servers with untrusted (for example, self-signed) certificates, like curl -k. Only affects this connect invocation |
--print-env | off | Print shell export/unset statements instead of launching Claude Code |
Arguments after -- are forwarded to the claude command.
Model Configuration
Default behavior
With no model flags, each Claude tier is matched to an available model by keyword (haiku/sonnet/opus in the model name); tiers with no match fall back to the first available LLM model.
Setting a specific model for all tiers
ogx connect claude --model openai/gpt-4o
Setting different models per tier
ogx connect claude \
--haiku-model openai/gpt-4o-mini \
--sonnet-model openai/gpt-4o \
--opus-model openai/o1
Forwarding arguments to Claude Code
# Launch Claude Code in print mode
ogx connect claude -- -p "Write a hello world function"
# Specify a Claude model name directly
ogx connect claude -- --model claude-sonnet-4-5
Using --print-env for shell integration
Instead of launching Claude Code, print the environment variables for manual use:
# Print and eval
eval "$(ogx connect claude --print-env --model openai/gpt-4o)"
claude "Hello world"
With a Remote OGX Server
ogx connect --url http://192.168.1.100:9000/v1 claude
Some providers may return errors when Claude Code requests a max_tokens value higher than the model supports (e.g., OpenAI models). In that case, use --model to select a model that supports higher token limits, or use the per-tier flags to route different workloads to different models.
Supported Features
Core Capabilities
- ✅ All Messages API features: Multi-turn conversations, system messages, streaming
- ✅ Tool use: File operations, shell commands, code execution (via Claude Code's built-in tools)
- ✅ Extended thinking: For reasoning models (gpt-oss, DeepSeek-R1, Qwen3, QwQ, OpenAI o-series, and similar), thinking blocks for reasoning transparency. Other models reject
thinkingrequests with a 400 - ✅ Token counting:
/v1/messages/count_tokensendpoint - ✅ Prompt caching: When using providers that support it (e.g., Anthropic)
- ✅ Any inference provider: OpenAI, vLLM, Ollama, Fireworks, Together, Groq, Bedrock, etc.
Claude Agent SDK
If you're building custom agents with the Claude Agent SDK, OGX works as a drop-in backend:
from claude_agent_sdk import Agent
agent = Agent(
base_url="http://localhost:8321", # matches the quick start's ogx go --no-auth --insecure
api_key="fake", # any value works with --no-auth
model="vllm/Qwen/Qwen3-8B",
)
response = agent.send("Write a function to parse CSV files")
For more information about OGX's provider architecture, see Providers Overview. For Anthropic Messages API conformance details, see Anthropic Messages API.