Skip to main content

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?"
note

Claude Code must be installed and on your PATH (install from claude.com/download).

How It Works​

The ogx connect claude command:

  1. Queries the running OGX server for available models
  2. Filters out non-LLM models (embeddings, rerankers)
  3. 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
  4. 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_use blocks → OpenAI tool_calls
  • Streaming: OpenAI SSE events → Anthropic format (message_start, content_block_delta, etc.)
  • Thinking blocks: thinking is 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:

FlagDefaultDescription
--modelFirst available modelModel ID to map to all three Claude tiers
--haiku-model--model valueModel ID for the haiku (fast) tier. Overrides --model
--sonnet-model--model valueModel ID for the sonnet (balanced) tier. Overrides --model
--opus-model--model valueModel ID for the opus (capable) tier. Overrides --model
--url (group)https://localhost:8321/v1OGX 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 noneBearer API key for the OGX server. Applies to all ogx connect subcommands.
--insecure / -k (group)offAllow HTTPS connections to servers with untrusted (for example, self-signed) certificates, like curl -k. Only affects this connect invocation
--print-envoffPrint 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
note

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 thinking requests with a 400
  • ✅ Token counting: /v1/messages/count_tokens endpoint
  • ✅ 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.