15 KiB
Local OpenAI-compatible providers and skills setup
This guide covers two common offline/local workflows:
- running Claw against an OpenAI-compatible local model server such as Ollama, LM Studio, llama.cpp, or vLLM; and
- installing local skills from disk so Claw can discover them without network access.
Claw is not Claude-only
Claw Code is a Claude-Code-shaped workflow/runtime, not a Claude-only product. It supports Anthropic directly and can target OpenAI-compatible, provider-routed, and local models depending on configuration. Non-Claude providers are supported honestly: they may require stricter tool-call and response-shape compatibility, and some slash/tool workflows can be rougher than first-party Anthropic/OpenAI paths. Provider-specific identity leaks are bugs, not intended product positioning.
If you need the most polished daily-driver experience for a specific non-Claude model today, compare that provider’s native tools. If you need runtime/provider hackability, Claw’s OpenAI-compatible route is the intended extension path.
OpenAI-compatible routing basics
Set OPENAI_BASE_URL to the server’s /v1 endpoint and set OPENAI_API_KEY to either the required token or a harmless placeholder for local servers that expect an Authorization header. Authless local/private OpenAI-compatible servers can leave OPENAI_API_KEY unset. The model name must match what the server exposes.
export OPENAI_BASE_URL="http://127.0.0.1:11434/v1"
export OPENAI_API_KEY="local-dev-token"
claw --model "qwen3:latest" prompt "Reply exactly HELLO_WORLD_123"
Routing notes:
- Use the
openai/prefix for OpenAI-compatible gateways when you need prefix routing to win over ambient Anthropic credentials, for example--model "openai/gpt-4.1-mini"with OpenRouter. - For local servers, prefer the exact model ID reported by the server (
qwen3:latest,llama3.2, etc.). If your local gateway exposes slash-containing IDs, prefix the exact slug withlocal/so Claw routes through OpenAI-compatible transport while sending the rest verbatim, for example--model "local/Qwen/Qwen2.5-Coder-7B-Instruct". - When
OPENAI_BASE_URLpoints at a loopback or private-network address (localhost,127.0.0.1,10.x,192.168.x,172.16-31.x), Claw accepts any non-empty model name — bare aliases likemistralwork with no dot, colon, or slash required. This covers LM Studio and llama.cpp server setups that register models under a plain--alias, not just Ollama-style tagged names (llama3.2,qwen2.5-coder:7b).local/is still needed only to preserve slash-containing IDs verbatim (e.g. Hugging Face repo IDs for vLLM/mlx-lm). - Against a remote/hosted OpenAI-compatible gateway (not local/private), Claw keeps the stricter
provider/modelor dot/colon-tag requirement so a mistyped bare name doesn't silently route to a paid hosted API. - Tool workflows need model/server support for OpenAI-compatible tool calls. Plain prompt smoke tests can pass even when slash/tool workflows still fail because the server returns an incompatible tool-call shape.
Raw /v1/chat/completions smoke test
Before debugging Claw, verify the local server speaks the expected wire format:
curl -sS "$OPENAI_BASE_URL/chat/completions" \
-H "Authorization: Bearer ${OPENAI_API_KEY:-local-dev-token}" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3:latest",
"messages": [{"role": "user", "content": "Reply exactly HELLO_WORLD_123"}],
"stream": false
}'
Expected result: a JSON response with one assistant message containing HELLO_WORLD_123. If this fails, fix the local server, model name, or auth token before changing Claw settings.
Ollama
Start Ollama and pull a model:
ollama pull qwen3:latest
ollama serve
In another shell:
export OLLAMA_HOST="http://127.0.0.1:11434"
claw --model "qwen3:latest" prompt "Reply exactly HELLO_WORLD_123"
OLLAMA_HOST is the preferred env var for Ollama. Claw routes all models to the local OpenAI-compatible endpoint automatically when this is set, and no API key is needed. The older OPENAI_BASE_URL + OPENAI_API_KEY workaround is also supported for existing setups.
If Ollama is running without auth, unset OPENAI_API_KEY is acceptable. Use a placeholder token rather than a real cloud API key if your local server requires an Authorization header.
llama.cpp server
Start a llama.cpp OpenAI-compatible server with the model name you want Claw to send:
llama-server -m ./models/qwen2.5-coder.gguf --host 127.0.0.1 --port 8080 --alias qwen2.5-coder
Then smoke-test through Claw:
export OPENAI_BASE_URL="http://127.0.0.1:8080/v1"
export OPENAI_API_KEY="local-dev-token"
claw --model "qwen2.5-coder" prompt "Reply exactly HELLO_WORLD_123"
LM Studio
Start LM Studio's local server (Developer tab → Start Server, default port 1234), or headless via lms server start. LM Studio commonly serves models under a bare alias with no dot or colon (for example mistral-7b-instruct or a custom name set in the model settings).
export OPENAI_BASE_URL="http://127.0.0.1:1234/v1"
claw --model "mistral-7b-instruct" prompt "Reply exactly HELLO_WORLD_123"
OPENAI_API_KEY can stay unset for LM Studio's default authless local server. Use the exact model identifier LM Studio reports (check curl $OPENAI_BASE_URL/models) if the bare alias above doesn't match what you loaded.
vLLM or another OpenAI-compatible server
Start vLLM with an OpenAI-compatible API server:
vllm serve Qwen/Qwen2.5-Coder-7B-Instruct --host 127.0.0.1 --port 8000
Then route Claw to it:
export OPENAI_BASE_URL="http://127.0.0.1:8000/v1"
export OPENAI_API_KEY="local-dev-token"
claw --model "Qwen/Qwen2.5-Coder-7B-Instruct" prompt "Reply exactly HELLO_WORLD_123"
mlx-lm (Apple Silicon)
On Apple Silicon, mlx-lm gives meaningfully faster inference than llama.cpp-based backends for models under roughly 14B parameters.
Install and start the server:
pipx install mlx-lm
mlx_lm.server --model mlx-community/Qwen2.5-Coder-7B-Instruct-4bit --port 8080
Then route Claw to it:
export OPENAI_BASE_URL="http://127.0.0.1:8080/v1"
export OPENAI_API_KEY="local-dev-token"
claw --model "mlx-community/Qwen2.5-Coder-7B-Instruct-4bit" prompt "Reply exactly HELLO_WORLD_123"
mlx-lm serves models under their full Hugging Face repo ID. Use the exact id field from curl $OPENAI_BASE_URL/models for --model. A bare name like qwen2.5-coder-7b-instruct will fail model resolution before the request ever reaches the server.
OmniRoute and other remote OpenAI-compatible gateways
OmniRoute is a third-party OpenAI-compatible AI gateway that can route requests to multiple providers. To use any remote OpenAI-compatible gateway with Claw, set OPENAI_BASE_URL to the gateway's /v1 endpoint and provide your API key:
export OPENAI_BASE_URL="https://api.omniroute.ai/v1"
export OPENAI_API_KEY="your-omniroute-api-key"
claw --model "gpt-4" prompt "Reply exactly HELLO_WORLD_123"
To find the available model IDs on your gateway, use the /models endpoint:
curl -sS "$OPENAI_BASE_URL/models" \
-H "Authorization: Bearer $OPENAI_API_KEY" | jq '.data[].id'
For local configuration, see your gateway's documentation for the correct base URL, API key format, and available model IDs. The same OPENAI_BASE_URL + OPENAI_API_KEY pattern applies to any OpenAI-compatible remote gateway.
LLMTR
LLMTR is an OpenAI-compatible gateway. Use the same client: set OPENAI_BASE_URL to https://llmtr.com/v1 and OPENAI_API_KEY to a bearer key (llmtr-...).
export OPENAI_BASE_URL="https://llmtr.com/v1"
export OPENAI_API_KEY="llmtr-..."
claw --model "local/llmtr/qwen3-8-27b" prompt "Reply exactly HELLO_WORLD_123"
Send the catalog id unchanged. llmtr/qwen3-8-27b already starts with the gateway name, so that prefix stays on the wire. The local/ hatch only selects the OpenAI-compatible transport and is removed before the request. A bare qwen/ or qwen- name is a DashScope route and will not reach LLMTR, so vendor-prefixed ids need the same hatch: local/<vendor>/<model>.
Claw asks for up to 64,000 output tokens on these routes. LLMTR rejects a request whose max_tokens is above the model's output limit, so pick a model that allows at least that much. llmtr/qwen3-8-27b allows 262,144. Each model's limit is listed as top_provider.max_completion_tokens in the catalog below.
The public model list does not need a key:
curl -sS "https://llmtr.com/v1/models" \
| jq -r '.data[] | "\(.id)\t\(.top_provider.max_completion_tokens)"'
UberLLM
UberLLM is a pay-as-you-go OpenAI-compatible gateway (prepaid, no free tier). Set OPENAI_BASE_URL to https://api.uberllm.dev/v1 and OPENAI_API_KEY to a bearer key (ull_...).
export OPENAI_BASE_URL="https://api.uberllm.dev/v1"
export OPENAI_API_KEY="ull_..."
claw --model "local/deepseek/deepseek-v4-flash" prompt "Reply exactly HELLO_WORLD_123"
UberLLM ids are vendor-prefixed (deepseek/deepseek-v4-flash, moonshotai/kimi-k2.6, qwen/qwen3.8-flash). Put local/ in front of every one: the hatch selects the OpenAI-compatible transport and is removed, so the catalog id goes out unchanged. Some prefixes would otherwise pick a native route; a bare qwen/qwen3.8-flash, for example, goes to DashScope and asks for DASHSCOPE_API_KEY.
Claw asks for up to 64,000 output tokens on these routes. UberLLM does not reject that on a model with a smaller output limit (for example aion-labs/aion-3-0-mini, 32,768); the answer is simply bounded by the model's limit, listed as max_output_tokens in the catalog below.
The public model list does not need a key:
curl -sS "https://api.uberllm.dev/v1/models" \
| jq -r '.data[] | "\(.id)\t\(.max_output_tokens)"'
Standard Compute
Standard Compute is an OpenAI-compatible gateway. Set OPENAI_BASE_URL to https://api.stdcmpt.com/v1 and OPENAI_API_KEY to your Standard Compute key.
export STANDARDCOMPUTE_API_KEY="your-standardcompute-api-key"
export OPENAI_BASE_URL="https://api.stdcmpt.com/v1"
export OPENAI_API_KEY="$STANDARDCOMPUTE_API_KEY"
claw --model "local/StandardCompute" prompt "Reply exactly HELLO_WORLD_123"
StandardCompute is the routed model: the router picks from the models enabled on your account using your quality preference, so harder tasks go to stronger models and simpler ones to cheaper models (routing docs). It is a bare name on a remote gateway, so it needs the local/ hatch, which selects the OpenAI-compatible transport and is removed before the request.
To pin one model, use a vendor-prefixed id from the catalog with the same hatch, for example --model "local/deepseek/deepseek-v4-flash". A bare vendor prefix can pick a native route instead of the gateway.
The public model list does not need a key:
curl -sS "https://api.stdcmpt.com/v1/models" | jq -r '.data[].id'
See the Standard Compute docs for keys and account setup.
HopBase
HopBase is an OpenAI-compatible API for Claude, GPT, GLM, DeepSeek, Qwen, and other model families. Set OPENAI_BASE_URL to https://api.hop-base.com/v1 and OPENAI_API_KEY to your HopBase key.
export HOPBASE_API_KEY="your-hopbase-api-key"
export OPENAI_BASE_URL="https://api.hop-base.com/v1"
export OPENAI_API_KEY="$HOPBASE_API_KEY"
claw --model "local/glm-5.3-flash" prompt "Reply exactly HELLO_WORLD_123"
HopBase ids are bare names without a vendor prefix (glm-5.3-flash, gpt-5.6-luna, claude-sonnet-5-5). Put local/ in front of every one: the hatch selects the OpenAI-compatible transport and is removed, so the id goes out unchanged. Without it, a bare claude- id picks the native Anthropic route, and a bare qwen- or kimi- id goes to DashScope.
The model list needs your key and shows the ids that key can call:
curl -sS "https://api.hop-base.com/v1/models" \
-H "Authorization: Bearer $OPENAI_API_KEY" | jq -r '.data[].id'
See the HopBase docs for keys and account setup.
Local skills install from disk
Skills are discovered from Claw skill roots such as .claw/skills/ in a workspace and ~/.claw/skills/ for user-level installs. Legacy .codex/skills/ roots may also be scanned for compatibility, but new local Claw projects should prefer .claw/skills/.
A skill directory should contain a SKILL.md file with frontmatter:
my-skill/
└── SKILL.md
---
name: my-skill
description: Explain when this skill should be used.
---
# My Skill
Instructions for the agent go here.
Install a skill from a local path in the interactive REPL:
/skills install /absolute/path/to/my-skill
/skills list
/skills my-skill
Or inspect skills from the direct CLI surface:
claw skills --output-format json
Offline install checklist:
- Install the specific skill directory, not only the repository root, unless that repository root itself contains
SKILL.md. - Keep the frontmatter
namealigned with the directory name users will type. - After installing, run
/skills listorclaw skills --output-format jsonto confirm the discovered name and source path. - If a skill invocation fails with an HTTP/provider error, the skill may have installed correctly but the current model/provider call failed. Run
claw doctor, verify provider credentials, and try a simple prompt smoke test before reinstalling the skill.
Troubleshooting
| Symptom | Check |
|---|---|
| Claw still asks for Anthropic credentials | Use an explicit OpenAI-compatible model route or remove unrelated Anthropic env vars during local smoke tests. |
model not found from local server |
Use the exact model ID exposed by Ollama/llama.cpp/vLLM. |
| Plain prompt works but tools fail | Confirm the model/server supports OpenAI-compatible tool calls and response shapes. |
Skill says installed but /skills <name> fails |
Check /skills list for the discovered name and source; verify provider credentials separately with claw doctor. |
| A local docs/log file contains secrets | Redact it before using @path file context or attaching it to an issue. |
404 Repository Not Found from huggingface.co when running claw |
The --model value isn't a full Hugging Face repo ID. Use the exact id field from curl $OPENAI_BASE_URL/models, not a bare model name. |
| mlx-lm output includes a trailing `< | im_end |