hansjone/oclaw
1
0
Fork 0
mirror of https://github.com/hansjone/oclaw.git synced 2026-10-10 20:50:52 +08:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

重构主控编排与运行时预热链路，统一工作区提示词/专家调度协议并补齐 wiki 记忆注入与写回闭环。

Browse source 
同时收敛启动与运维脚本默认行为（含 wiki worker）、更新 Admin 可观测性与相关测试，降低首轮时延并提高运行稳定性。

Made-with: Cursor
This commit is contained in:
oliver 2026-04-26 08:34:33 +08:00
parent 4a23b715a2
commit dbbe3add6a
14438 changed files with 2693620 additions and 2546 deletions
Download patch file Download diff file Expand all files Collapse all files

116
openclaw/docs/providers/alibaba.md Normal file
View file

@ -0,0 +1,116 @@
---
title: "Alibaba Model Studio"
summary: "Alibaba Model Studio Wan video generation in OpenClaw"
read_when:
- You want to use Alibaba Wan video generation in OpenClaw
- You need Model Studio or DashScope API key setup for video generation
---
# Alibaba Model Studio
OpenClaw ships a bundled `alibaba` video-generation provider for Wan models on
Alibaba Model Studio / DashScope.
- Provider: `alibaba`
- Preferred auth: `MODELSTUDIO_API_KEY`
- Also accepted: `DASHSCOPE_API_KEY`, `QWEN_API_KEY`
- API: DashScope / Model Studio async video generation
## Getting started
<Steps>
<Step title="Set an API key">
```bash
openclaw onboard --auth-choice qwen-standard-api-key
```
</Step>
<Step title="Set a default video model">
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "alibaba/wan2.6-t2v",
},
},
},
}
```
</Step>
<Step title="Verify the provider is available">
```bash
openclaw models list --provider alibaba
```
</Step>
</Steps>
<Note>
Any of the accepted auth keys (`MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY`, `QWEN_API_KEY`) will work. The `qwen-standard-api-key` onboarding choice configures the shared DashScope credential.
</Note>
## Built-in Wan models
The bundled `alibaba` provider currently registers:
| Model ref | Mode |
| -------------------------- | ------------------------- |
| `alibaba/wan2.6-t2v` | Text-to-video |
| `alibaba/wan2.6-i2v` | Image-to-video |
| `alibaba/wan2.6-r2v` | Reference-to-video |
| `alibaba/wan2.6-r2v-flash` | Reference-to-video (fast) |
| `alibaba/wan2.7-r2v` | Reference-to-video |
## Current limits
| Parameter | Limit |
| --------------------- | --------------------------------------------------------- |
| Output videos | Up to **1** per request |
| Input images | Up to **1** |
| Input videos | Up to **4** |
| Duration | Up to **10 seconds** |
| Supported controls | `size`, `aspectRatio`, `resolution`, `audio`, `watermark` |
| Reference image/video | Remote `http(s)` URLs only |
<Warning>
Reference image/video mode currently requires **remote http(s) URLs**. Local file paths are not supported for reference inputs.
</Warning>
## Advanced configuration
<AccordionGroup>
<Accordion title="Relationship to Qwen">
The bundled `qwen` provider also uses Alibaba-hosted DashScope endpoints for
Wan video generation. Use:
- `qwen/...` when you want the canonical Qwen provider surface
- `alibaba/...` when you want the direct vendor-owned Wan video surface
See the [Qwen provider docs](/providers/qwen) for more detail.
</Accordion>
<Accordion title="Auth key priority">
OpenClaw checks for auth keys in this order:
1. `MODELSTUDIO_API_KEY` (preferred)
2. `DASHSCOPE_API_KEY`
3. `QWEN_API_KEY`
Any of these will authenticate the `alibaba` provider.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video tool parameters and provider selection.
</Card>
<Card title="Qwen" href="/providers/qwen" icon="microchip">
Qwen provider setup and DashScope integration.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference#agent-defaults" icon="gear">
Agent defaults and model configuration.
</Card>
</CardGroup>

310
openclaw/docs/providers/anthropic.md Normal file
View file

@ -0,0 +1,310 @@
---
summary: "Use Anthropic Claude via API keys or Claude CLI in OpenClaw"
read_when:
- You want to use Anthropic models in OpenClaw
title: "Anthropic"
---
# Anthropic (Claude)
Anthropic builds the **Claude** model family. OpenClaw supports two auth routes:
- **API key** — direct Anthropic API access with usage-based billing (`anthropic/*` models)
- **Claude CLI** — reuse an existing Claude CLI login on the same host
<Warning>
Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again, so
OpenClaw treats Claude CLI reuse and `claude -p` usage as sanctioned unless
Anthropic publishes a new policy.
For long-lived gateway hosts, Anthropic API keys are still the clearest and
most predictable production path.
Anthropic's current public docs:
- [Claude Code CLI reference](https://code.claude.com/docs/en/cli-reference)
- [Claude Agent SDK overview](https://platform.claude.com/docs/en/agent-sdk/overview)
- [Using Claude Code with your Pro or Max plan](https://support.claude.com/en/articles/11145838-using-claude-code-with-your-pro-or-max-plan)
- [Using Claude Code with your Team or Enterprise plan](https://support.anthropic.com/en/articles/11845131-using-claude-code-with-your-team-or-enterprise-plan/)
</Warning>
## Getting started
<Tabs>
<Tab title="API key">
**Best for:** standard API access and usage-based billing.
<Steps>
<Step title="Get your API key">
Create an API key in the [Anthropic Console](https://console.anthropic.com/).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard
# choose: Anthropic API key
```
Or pass the key directly:
```bash
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider anthropic
```
</Step>
</Steps>
### Config example
```json5
{
env: { ANTHROPIC_API_KEY: "sk-ant-..." },
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```
</Tab>
<Tab title="Claude CLI">
**Best for:** reusing an existing Claude CLI login without a separate API key.
<Steps>
<Step title="Ensure Claude CLI is installed and logged in">
Verify with:
```bash
claude --version
```
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard
# choose: Claude CLI
```
OpenClaw detects and reuses the existing Claude CLI credentials.
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider anthropic
```
</Step>
</Steps>
<Note>
Setup and runtime details for the Claude CLI backend are in [CLI Backends](/gateway/cli-backends).
</Note>
<Tip>
If you want the clearest billing path, use an Anthropic API key instead. OpenClaw also supports subscription-style options from [OpenAI Codex](/providers/openai), [Qwen Cloud](/providers/qwen), [MiniMax](/providers/minimax), and [Z.AI / GLM](/providers/glm).
</Tip>
</Tab>
</Tabs>
## Thinking defaults (Claude 4.6)
Claude 4.6 models default to `adaptive` thinking in OpenClaw when no explicit thinking level is set.
Override per-message with `/think:<level>` or in model params:
```json5
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": {
params: { thinking: "adaptive" },
},
},
},
},
}
```
<Note>
Related Anthropic docs:
- [Adaptive thinking](https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking)
- [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking)
</Note>
## Prompt caching
OpenClaw supports Anthropic's prompt caching feature for API-key auth.
| Value | Cache duration | Description |
| ------------------- | -------------- | -------------------------------------- |
| `"short"` (default) | 5 minutes | Applied automatically for API-key auth |
| `"long"` | 1 hour | Extended cache |
| `"none"` | No caching | Disable prompt caching |
```json5
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": {
params: { cacheRetention: "long" },
},
},
},
},
}
```
<AccordionGroup>
<Accordion title="Per-agent cache overrides">
Use model-level params as your baseline, then override specific agents via `agents.list[].params`:
```json5
{
agents: {
defaults: {
model: { primary: "anthropic/claude-opus-4-6" },
models: {
"anthropic/claude-opus-4-6": {
params: { cacheRetention: "long" },
},
},
},
list: [
{ id: "research", default: true },
{ id: "alerts", params: { cacheRetention: "none" } },
],
},
}
```
Config merge order:
1. `agents.defaults.models["provider/model"].params`
2. `agents.list[].params` (matching `id`, overrides by key)
This lets one agent keep a long-lived cache while another agent on the same model disables caching for bursty/low-reuse traffic.
</Accordion>
<Accordion title="Bedrock Claude notes">
- Anthropic Claude models on Bedrock (`amazon-bedrock/*anthropic.claude*`) accept `cacheRetention` pass-through when configured.
- Non-Anthropic Bedrock models are forced to `cacheRetention: "none"` at runtime.
- API-key smart defaults also seed `cacheRetention: "short"` for Claude-on-Bedrock refs when no explicit value is set.
</Accordion>
</AccordionGroup>
## Advanced configuration
<AccordionGroup>
<Accordion title="Fast mode">
OpenClaw's shared `/fast` toggle supports direct Anthropic traffic (API-key and OAuth to `api.anthropic.com`).
| Command | Maps to |
|---------|---------|
| `/fast on` | `service_tier: "auto"` |
| `/fast off` | `service_tier: "standard_only"` |
```json5
{
agents: {
defaults: {
models: {
"anthropic/claude-sonnet-4-6": {
params: { fastMode: true },
},
},
},
},
}
```
<Note>
- Only injected for direct `api.anthropic.com` requests. Proxy routes leave `service_tier` untouched.
- Explicit `serviceTier` or `service_tier` params override `/fast` when both are set.
- On accounts without Priority Tier capacity, `service_tier: "auto"` may resolve to `standard`.
</Note>
</Accordion>
<Accordion title="Media understanding (image and PDF)">
The bundled Anthropic plugin registers image and PDF understanding. OpenClaw
auto-resolves media capabilities from the configured Anthropic auth — no
additional config is needed.
| Property | Value |
| -------------- | -------------------- |
| Default model | `claude-opus-4-6` |
| Supported input | Images, PDF documents |
When an image or PDF is attached to a conversation, OpenClaw automatically
routes it through the Anthropic media understanding provider.
</Accordion>
<Accordion title="1M context window (beta)">
Anthropic's 1M context window is beta-gated. Enable it per model:
```json5
{
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": {
params: { context1m: true },
},
},
},
},
}
```
OpenClaw maps this to `anthropic-beta: context-1m-2025-08-07` on requests.
<Warning>
Requires long-context access on your Anthropic credential. Legacy token auth (`sk-ant-oat-*`) is rejected for 1M context requests — OpenClaw logs a warning and falls back to the standard context window.
</Warning>
</Accordion>
</AccordionGroup>
## Troubleshooting
<AccordionGroup>
<Accordion title="401 errors / token suddenly invalid">
Anthropic token auth can expire or be revoked. For new setups, migrate to an Anthropic API key.
</Accordion>
<Accordion title='No API key found for provider "anthropic"'>
Auth is **per agent**. New agents don't inherit the main agent's keys. Re-run onboarding for that agent, or configure an API key on the gateway host, then verify with `openclaw models status`.
</Accordion>
<Accordion title='No credentials found for profile "anthropic:default"'>
Run `openclaw models status` to see which auth profile is active. Re-run onboarding, or configure an API key for that profile path.
</Accordion>
<Accordion title="No available auth profile (all in cooldown)">
Check `openclaw models status --json` for `auth.unusableProfiles`. Anthropic rate-limit cooldowns can be model-scoped, so a sibling Anthropic model may still be usable. Add another Anthropic profile or wait for cooldown.
</Accordion>
</AccordionGroup>
<Note>
More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq).
</Note>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="CLI backends" href="/gateway/cli-backends" icon="terminal">
Claude CLI backend setup and runtime details.
</Card>
<Card title="Prompt caching" href="/reference/prompt-caching" icon="database">
How prompt caching works across providers.
</Card>
<Card title="OAuth and auth" href="/gateway/authentication" icon="key">
Auth details and credential reuse rules.
</Card>
</CardGroup>

146
openclaw/docs/providers/arcee.md Normal file
View file

@ -0,0 +1,146 @@
---
title: "Arcee AI"
summary: "Arcee AI setup (auth + model selection)"
read_when:
- You want to use Arcee AI with OpenClaw
- You need the API key env var or CLI auth choice
---
# Arcee AI
[Arcee AI](https://arcee.ai) provides access to the Trinity family of mixture-of-experts models through an OpenAI-compatible API. All Trinity models are Apache 2.0 licensed.
Arcee AI models can be accessed directly via the Arcee platform or through [OpenRouter](/providers/openrouter).
| Property | Value |
| -------- | ------------------------------------------------------------------------------------- |
| Provider | `arcee` |
| Auth | `ARCEEAI_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter) |
| API | OpenAI-compatible |
| Base URL | `https://api.arcee.ai/api/v1` (direct) or `https://openrouter.ai/api/v1` (OpenRouter) |
## Getting started
<Tabs>
<Tab title="Direct (Arcee platform)">
<Steps>
<Step title="Get an API key">
Create an API key at [Arcee AI](https://chat.arcee.ai/).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice arceeai-api-key
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "arcee/trinity-large-thinking" },
},
},
}
```
</Step>
</Steps>
</Tab>
<Tab title="Via OpenRouter">
<Steps>
<Step title="Get an API key">
Create an API key at [OpenRouter](https://openrouter.ai/keys).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice arceeai-openrouter
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "arcee/trinity-large-thinking" },
},
},
}
```
The same model refs work for both direct and OpenRouter setups (for example `arcee/trinity-large-thinking`).
</Step>
</Steps>
</Tab>
</Tabs>
## Non-interactive setup
<Tabs>
<Tab title="Direct (Arcee platform)">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice arceeai-api-key \
--arceeai-api-key "$ARCEEAI_API_KEY"
```
</Tab>
<Tab title="Via OpenRouter">
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice arceeai-openrouter \
--openrouter-api-key "$OPENROUTER_API_KEY"
```
</Tab>
</Tabs>
## Built-in catalog
OpenClaw currently ships this bundled Arcee catalog:
| Model ref | Name | Input | Context | Cost (in/out per 1M) | Notes |
| ------------------------------ | ---------------------- | ----- | ------- | -------------------- | ----------------------------------------- |
| `arcee/trinity-large-thinking` | Trinity Large Thinking | text | 256K | $0.25 / $0.90 | Default model; reasoning enabled |
| `arcee/trinity-large-preview` | Trinity Large Preview | text | 128K | $0.25 / $1.00 | General-purpose; 400B params, 13B active |
| `arcee/trinity-mini` | Trinity Mini 26B | text | 128K | $0.045 / $0.15 | Fast and cost-efficient; function calling |
<Tip>
The onboarding preset sets `arcee/trinity-large-thinking` as the default model.
</Tip>
## Supported features
| Feature | Supported |
| --------------------------------------------- | ---------------------------- |
| Streaming | Yes |
| Tool use / function calling | Yes |
| Structured output (JSON mode and JSON schema) | Yes |
| Extended thinking | Yes (Trinity Large Thinking) |
<AccordionGroup>
<Accordion title="Environment note">
If the Gateway runs as a daemon (launchd/systemd), make sure `ARCEEAI_API_KEY`
(or `OPENROUTER_API_KEY`) is available to that process (for example, in
`~/.openclaw/.env` or via `env.shellEnv`).
</Accordion>
<Accordion title="OpenRouter routing">
When using Arcee models via OpenRouter, the same `arcee/*` model refs apply.
OpenClaw handles routing transparently based on your auth choice. See the
[OpenRouter provider docs](/providers/openrouter) for OpenRouter-specific
configuration details.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="OpenRouter" href="/providers/openrouter" icon="shuffle">
Access Arcee models and many others through a single API key.
</Card>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
</CardGroup>

177
openclaw/docs/providers/bedrock-mantle.md Normal file
View file

@ -0,0 +1,177 @@
---
summary: "Use Amazon Bedrock Mantle (OpenAI-compatible) models with OpenClaw"
read_when:
- You want to use Bedrock Mantle hosted OSS models with OpenClaw
- You need the Mantle OpenAI-compatible endpoint for GPT-OSS, Qwen, Kimi, or GLM
title: "Amazon Bedrock Mantle"
---
# Amazon Bedrock Mantle
OpenClaw includes a bundled **Amazon Bedrock Mantle** provider that connects to
the Mantle OpenAI-compatible endpoint. Mantle hosts open-source and
third-party models (GPT-OSS, Qwen, Kimi, GLM, and similar) through a standard
`/v1/chat/completions` surface backed by Bedrock infrastructure.
| Property | Value |
| -------------- | ----------------------------------------------------------------------------------- |
| Provider ID | `amazon-bedrock-mantle` |
| API | `openai-completions` (OpenAI-compatible) |
| Auth | Explicit `AWS_BEARER_TOKEN_BEDROCK` or IAM credential-chain bearer-token generation |
| Default region | `us-east-1` (override with `AWS_REGION` or `AWS_DEFAULT_REGION`) |
## Getting started
Choose your preferred auth method and follow the setup steps.
<Tabs>
<Tab title="Explicit bearer token">
**Best for:** environments where you already have a Mantle bearer token.
<Steps>
<Step title="Set the bearer token on the gateway host">
```bash
export AWS_BEARER_TOKEN_BEDROCK="..."
```
Optionally set a region (defaults to `us-east-1`):
```bash
export AWS_REGION="us-west-2"
```
</Step>
<Step title="Verify models are discovered">
```bash
openclaw models list
```
Discovered models appear under the `amazon-bedrock-mantle` provider. No
additional config is required unless you want to override defaults.
</Step>
</Steps>
</Tab>
<Tab title="IAM credentials">
**Best for:** using AWS SDK-compatible credentials (shared config, SSO, web identity, instance or task roles).
<Steps>
<Step title="Configure AWS credentials on the gateway host">
Any AWS SDK-compatible auth source works:
```bash
export AWS_PROFILE="default"
export AWS_REGION="us-west-2"
```
</Step>
<Step title="Verify models are discovered">
```bash
openclaw models list
```
OpenClaw generates a Mantle bearer token from the credential chain automatically.
</Step>
</Steps>
<Tip>
When `AWS_BEARER_TOKEN_BEDROCK` is not set, OpenClaw mints the bearer token for you from the AWS default credential chain, including shared credentials/config profiles, SSO, web identity, and instance or task roles.
</Tip>
</Tab>
</Tabs>
## Automatic model discovery
When `AWS_BEARER_TOKEN_BEDROCK` is set, OpenClaw uses it directly. Otherwise,
OpenClaw attempts to generate a Mantle bearer token from the AWS default
credential chain. It then discovers available Mantle models by querying the
region's `/v1/models` endpoint.
| Behavior | Detail |
| ----------------- | ------------------------- |
| Discovery cache | Results cached for 1 hour |
| IAM token refresh | Hourly |
<Note>
The bearer token is the same `AWS_BEARER_TOKEN_BEDROCK` used by the standard [Amazon Bedrock](/providers/bedrock) provider.
</Note>
### Supported regions
`us-east-1`, `us-east-2`, `us-west-2`, `ap-northeast-1`,
`ap-south-1`, `ap-southeast-3`, `eu-central-1`, `eu-west-1`, `eu-west-2`,
`eu-south-1`, `eu-north-1`, `sa-east-1`.
## Manual configuration
If you prefer explicit config instead of auto-discovery:
```json5
{
models: {
providers: {
"amazon-bedrock-mantle": {
baseUrl: "https://bedrock-mantle.us-east-1.api.aws/v1",
api: "openai-completions",
auth: "api-key",
apiKey: "env:AWS_BEARER_TOKEN_BEDROCK",
models: [
{
id: "gpt-oss-120b",
name: "GPT-OSS 120B",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 32000,
maxTokens: 4096,
},
],
},
},
},
}
```
## Advanced notes
<AccordionGroup>
<Accordion title="Reasoning support">
Reasoning support is inferred from model IDs containing patterns like
`thinking`, `reasoner`, or `gpt-oss-120b`. OpenClaw sets `reasoning: true`
automatically for matching models during discovery.
</Accordion>
<Accordion title="Endpoint unavailability">
If the Mantle endpoint is unavailable or returns no models, the provider is
silently skipped. OpenClaw does not error; other configured providers
continue to work normally.
</Accordion>
<Accordion title="Relationship to Amazon Bedrock provider">
Bedrock Mantle is a separate provider from the standard
[Amazon Bedrock](/providers/bedrock) provider. Mantle uses an
OpenAI-compatible `/v1` surface, while the standard Bedrock provider uses
the native Bedrock API.
Both providers share the same `AWS_BEARER_TOKEN_BEDROCK` credential when
present.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Amazon Bedrock" href="/providers/bedrock" icon="cloud">
Native Bedrock provider for Anthropic Claude, Titan, and other models.
</Card>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="OAuth and auth" href="/gateway/authentication" icon="key">
Auth details and credential reuse rules.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
Common issues and how to resolve them.
</Card>
</CardGroup>

362
openclaw/docs/providers/bedrock.md Normal file
View file

@ -0,0 +1,362 @@
---
summary: "Use Amazon Bedrock (Converse API) models with OpenClaw"
read_when:
- You want to use Amazon Bedrock models with OpenClaw
- You need AWS credential/region setup for model calls
title: "Amazon Bedrock"
---
# Amazon Bedrock
OpenClaw can use **Amazon Bedrock** models via pi-ai's **Bedrock Converse**
streaming provider. Bedrock auth uses the **AWS SDK default credential chain**,
not an API key.
| Property | Value |
| -------- | ----------------------------------------------------------- |
| Provider | `amazon-bedrock` |
| API | `bedrock-converse-stream` |
| Auth | AWS credentials (env vars, shared config, or instance role) |
| Region | `AWS_REGION` or `AWS_DEFAULT_REGION` (default: `us-east-1`) |
## Getting started
Choose your preferred auth method and follow the setup steps.
<Tabs>
<Tab title="Access keys / env vars">
**Best for:** developer machines, CI, or hosts where you manage AWS credentials directly.
<Steps>
<Step title="Set AWS credentials on the gateway host">
```bash
export AWS_ACCESS_KEY_ID="AKIA..."
export AWS_SECRET_ACCESS_KEY="..."
export AWS_REGION="us-east-1"
# Optional:
export AWS_SESSION_TOKEN="..."
export AWS_PROFILE="your-profile"
# Optional (Bedrock API key/bearer token):
export AWS_BEARER_TOKEN_BEDROCK="..."
```
</Step>
<Step title="Add a Bedrock provider and model to your config">
No `apiKey` is required. Configure the provider with `auth: "aws-sdk"`:
```json5
{
models: {
providers: {
"amazon-bedrock": {
baseUrl: "https://bedrock-runtime.us-east-1.amazonaws.com",
api: "bedrock-converse-stream",
auth: "aws-sdk",
models: [
{
id: "us.anthropic.claude-opus-4-6-v1:0",
name: "Claude Opus 4.6 (Bedrock)",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 200000,
maxTokens: 8192,
},
],
},
},
},
agents: {
defaults: {
model: { primary: "amazon-bedrock/us.anthropic.claude-opus-4-6-v1:0" },
},
},
}
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list
```
</Step>
</Steps>
<Tip>
With env-marker auth (`AWS_ACCESS_KEY_ID`, `AWS_PROFILE`, or `AWS_BEARER_TOKEN_BEDROCK`), OpenClaw auto-enables the implicit Bedrock provider for model discovery without extra config.
</Tip>
</Tab>
<Tab title="EC2 instance roles (IMDS)">
**Best for:** EC2 instances with an IAM role attached, using the instance metadata service for authentication.
<Steps>
<Step title="Enable discovery explicitly">
When using IMDS, OpenClaw cannot detect AWS auth from env markers alone, so you must opt in:
```bash
openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1
```
</Step>
<Step title="Optionally add an env marker for auto mode">
If you also want the env-marker auto-detection path to work (for example, for `openclaw status` surfaces):
```bash
export AWS_PROFILE=default
export AWS_REGION=us-east-1
```
You do **not** need a fake API key.
</Step>
<Step title="Verify models are discovered">
```bash
openclaw models list
```
</Step>
</Steps>
<Warning>
The IAM role attached to your EC2 instance must have the following permissions:
- `bedrock:InvokeModel`
- `bedrock:InvokeModelWithResponseStream`
- `bedrock:ListFoundationModels` (for automatic discovery)
- `bedrock:ListInferenceProfiles` (for inference profile discovery)
Or attach the managed policy `AmazonBedrockFullAccess`.
</Warning>
<Note>
You only need `AWS_PROFILE=default` if you specifically want an env marker for auto mode or status surfaces. The actual Bedrock runtime auth path uses the AWS SDK default chain, so IMDS instance-role auth works even without env markers.
</Note>
</Tab>
</Tabs>
## Automatic model discovery
OpenClaw can automatically discover Bedrock models that support **streaming**
and **text output**. Discovery uses `bedrock:ListFoundationModels` and
`bedrock:ListInferenceProfiles`, and results are cached (default: 1 hour).
How the implicit provider is enabled:
- If `plugins.entries.amazon-bedrock.config.discovery.enabled` is `true`,
OpenClaw will try discovery even when no AWS env marker is present.
- If `plugins.entries.amazon-bedrock.config.discovery.enabled` is unset,
OpenClaw only auto-adds the
implicit Bedrock provider when it sees one of these AWS auth markers:
`AWS_BEARER_TOKEN_BEDROCK`, `AWS_ACCESS_KEY_ID` +
`AWS_SECRET_ACCESS_KEY`, or `AWS_PROFILE`.
- The actual Bedrock runtime auth path still uses the AWS SDK default chain, so
shared config, SSO, and IMDS instance-role auth can work even when discovery
needed `enabled: true` to opt in.
<Note>
For explicit `models.providers["amazon-bedrock"]` entries, OpenClaw can still resolve Bedrock env-marker auth early from AWS env markers such as `AWS_BEARER_TOKEN_BEDROCK` without forcing full runtime auth loading. The actual model-call auth path still uses the AWS SDK default chain.
</Note>
<AccordionGroup>
<Accordion title="Discovery config options">
Config options live under `plugins.entries.amazon-bedrock.config.discovery`:
```json5
{
plugins: {
entries: {
"amazon-bedrock": {
config: {
discovery: {
enabled: true,
region: "us-east-1",
providerFilter: ["anthropic", "amazon"],
refreshInterval: 3600,
defaultContextWindow: 32000,
defaultMaxTokens: 4096,
},
},
},
},
},
}
```
| Option | Default | Description |
| ------ | ------- | ----------- |
| `enabled` | auto | In auto mode, OpenClaw only enables the implicit Bedrock provider when it sees a supported AWS env marker. Set `true` to force discovery. |
| `region` | `AWS_REGION` / `AWS_DEFAULT_REGION` / `us-east-1` | AWS region used for discovery API calls. |
| `providerFilter` | (all) | Matches Bedrock provider names (for example `anthropic`, `amazon`). |
| `refreshInterval` | `3600` | Cache duration in seconds. Set to `0` to disable caching. |
| `defaultContextWindow` | `32000` | Context window used for discovered models (override if you know your model limits). |
| `defaultMaxTokens` | `4096` | Max output tokens used for discovered models (override if you know your model limits). |
</Accordion>
</AccordionGroup>
## Quick setup (AWS path)
This walkthrough creates an IAM role, attaches Bedrock permissions, associates
the instance profile, and enables OpenClaw discovery on the EC2 host.
```bash
# 1. Create IAM role and instance profile
aws iam create-role --role-name EC2-Bedrock-Access \
--assume-role-policy-document '{
"Version": "2012-10-17",
"Statement": [{
"Effect": "Allow",
"Principal": {"Service": "ec2.amazonaws.com"},
"Action": "sts:AssumeRole"
}]
}'
aws iam attach-role-policy --role-name EC2-Bedrock-Access \
--policy-arn arn:aws:iam::aws:policy/AmazonBedrockFullAccess
aws iam create-instance-profile --instance-profile-name EC2-Bedrock-Access
aws iam add-role-to-instance-profile \
--instance-profile-name EC2-Bedrock-Access \
--role-name EC2-Bedrock-Access
# 2. Attach to your EC2 instance
aws ec2 associate-iam-instance-profile \
--instance-id i-xxxxx \
--iam-instance-profile Name=EC2-Bedrock-Access
# 3. On the EC2 instance, enable discovery explicitly
openclaw config set plugins.entries.amazon-bedrock.config.discovery.enabled true
openclaw config set plugins.entries.amazon-bedrock.config.discovery.region us-east-1
# 4. Optional: add an env marker if you want auto mode without explicit enable
echo 'export AWS_PROFILE=default' >> ~/.bashrc
echo 'export AWS_REGION=us-east-1' >> ~/.bashrc
source ~/.bashrc
# 5. Verify models are discovered
openclaw models list
```
## Advanced configuration
<AccordionGroup>
<Accordion title="Inference profiles">
OpenClaw discovers **regional and global inference profiles** alongside
foundation models. When a profile maps to a known foundation model, the
profile inherits that model's capabilities (context window, max tokens,
reasoning, vision) and the correct Bedrock request region is injected
automatically. This means cross-region Claude profiles work without manual
provider overrides.
Inference profile IDs look like `us.anthropic.claude-opus-4-6-v1:0` (regional)
or `anthropic.claude-opus-4-6-v1:0` (global). If the backing model is already
in the discovery results, the profile inherits its full capability set;
otherwise safe defaults apply.
No extra configuration is needed. As long as discovery is enabled and the IAM
principal has `bedrock:ListInferenceProfiles`, profiles appear alongside
foundation models in `openclaw models list`.
</Accordion>
<Accordion title="Guardrails">
You can apply [Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html)
to all Bedrock model invocations by adding a `guardrail` object to the
`amazon-bedrock` plugin config. Guardrails let you enforce content filtering,
topic denial, word filters, sensitive information filters, and contextual
grounding checks.
```json5
{
plugins: {
entries: {
"amazon-bedrock": {
config: {
guardrail: {
guardrailIdentifier: "abc123", // guardrail ID or full ARN
guardrailVersion: "1", // version number or "DRAFT"
streamProcessingMode: "sync", // optional: "sync" or "async"
trace: "enabled", // optional: "enabled", "disabled", or "enabled_full"
},
},
},
},
},
}
```
| Option | Required | Description |
| ------ | -------- | ----------- |
| `guardrailIdentifier` | Yes | Guardrail ID (e.g. `abc123`) or full ARN (e.g. `arn:aws:bedrock:us-east-1:123456789012:guardrail/abc123`). |
| `guardrailVersion` | Yes | Published version number, or `"DRAFT"` for the working draft. |
| `streamProcessingMode` | No | `"sync"` or `"async"` for guardrail evaluation during streaming. If omitted, Bedrock uses its default. |
| `trace` | No | `"enabled"` or `"enabled_full"` for debugging; omit or set `"disabled"` for production. |
<Warning>
The IAM principal used by the gateway must have the `bedrock:ApplyGuardrail` permission in addition to the standard invoke permissions.
</Warning>
</Accordion>
<Accordion title="Embeddings for memory search">
Bedrock can also serve as the embedding provider for
[memory search](/concepts/memory-search). This is configured separately from the
inference provider -- set `agents.defaults.memorySearch.provider` to `"bedrock"`:
```json5
{
agents: {
defaults: {
memorySearch: {
provider: "bedrock",
model: "amazon.titan-embed-text-v2:0", // default
},
},
},
}
```
Bedrock embeddings use the same AWS SDK credential chain as inference (instance
roles, SSO, access keys, shared config, and web identity). No API key is
needed. When `provider` is `"auto"`, Bedrock is auto-detected if that
credential chain resolves successfully.
Supported embedding models include Amazon Titan Embed (v1, v2), Amazon Nova
Embed, Cohere Embed (v3, v4), and TwelveLabs Marengo. See
[Memory configuration reference -- Bedrock](/reference/memory-config#bedrock-embedding-config)
for the full model list and dimension options.
</Accordion>
<Accordion title="Notes and caveats">
- Bedrock requires **model access** enabled in your AWS account/region.
- Automatic discovery needs the `bedrock:ListFoundationModels` and
`bedrock:ListInferenceProfiles` permissions.
- If you rely on auto mode, set one of the supported AWS auth env markers on the
gateway host. If you prefer IMDS/shared-config auth without env markers, set
`plugins.entries.amazon-bedrock.config.discovery.enabled: true`.
- OpenClaw surfaces the credential source in this order: `AWS_BEARER_TOKEN_BEDROCK`,
then `AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`, then `AWS_PROFILE`, then the
default AWS SDK chain.
- Reasoning support depends on the model; check the Bedrock model card for
current capabilities.
- If you prefer a managed key flow, you can also place an OpenAI-compatible
proxy in front of Bedrock and configure it as an OpenAI provider instead.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Memory search" href="/concepts/memory-search" icon="magnifying-glass">
Bedrock embeddings for memory search configuration.
</Card>
<Card title="Memory config reference" href="/reference/memory-config#bedrock-embedding-config" icon="database">
Full Bedrock embedding model list and dimension options.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
General troubleshooting and FAQ.
</Card>
</CardGroup>

154
openclaw/docs/providers/chutes.md Normal file
View file

@ -0,0 +1,154 @@
---
title: "Chutes"
summary: "Chutes setup (OAuth or API key, model discovery, aliases)"
read_when:
- You want to use Chutes with OpenClaw
- You need the OAuth or API key setup path
- You want the default model, aliases, or discovery behavior
---
# Chutes
[Chutes](https://chutes.ai) exposes open-source model catalogs through an
OpenAI-compatible API. OpenClaw supports both browser OAuth and direct API-key
auth for the bundled `chutes` provider.
| Property | Value |
| -------- | ---------------------------- |
| Provider | `chutes` |
| API | OpenAI-compatible |
| Base URL | `https://llm.chutes.ai/v1` |
| Auth | OAuth or API key (see below) |
## Getting started
<Tabs>
<Tab title="OAuth">
<Steps>
<Step title="Run the OAuth onboarding flow">
```bash
openclaw onboard --auth-choice chutes
```
OpenClaw launches the browser flow locally, or shows a URL + redirect-paste
flow on remote/headless hosts. OAuth tokens auto-refresh through OpenClaw auth
profiles.
</Step>
<Step title="Verify the default model">
After onboarding, the default model is set to
`chutes/zai-org/GLM-4.7-TEE` and the bundled Chutes catalog is
registered.
</Step>
</Steps>
</Tab>
<Tab title="API key">
<Steps>
<Step title="Get an API key">
Create a key at
[chutes.ai/settings/api-keys](https://chutes.ai/settings/api-keys).
</Step>
<Step title="Run the API key onboarding flow">
```bash
openclaw onboard --auth-choice chutes-api-key
```
</Step>
<Step title="Verify the default model">
After onboarding, the default model is set to
`chutes/zai-org/GLM-4.7-TEE` and the bundled Chutes catalog is
registered.
</Step>
</Steps>
</Tab>
</Tabs>
<Note>
Both auth paths register the bundled Chutes catalog and set the default model to
`chutes/zai-org/GLM-4.7-TEE`. Runtime environment variables: `CHUTES_API_KEY`,
`CHUTES_OAUTH_TOKEN`.
</Note>
## Discovery behavior
When Chutes auth is available, OpenClaw queries the Chutes catalog with that
credential and uses the discovered models. If discovery fails, OpenClaw falls
back to a bundled static catalog so onboarding and startup still work.
## Default aliases
OpenClaw registers three convenience aliases for the bundled Chutes catalog:
| Alias | Target model |
| --------------- | ----------------------------------------------------- |
| `chutes-fast` | `chutes/zai-org/GLM-4.7-FP8` |
| `chutes-pro` | `chutes/deepseek-ai/DeepSeek-V3.2-TEE` |
| `chutes-vision` | `chutes/chutesai/Mistral-Small-3.2-24B-Instruct-2506` |
## Built-in starter catalog
The bundled fallback catalog includes current Chutes refs:
| Model ref |
| ----------------------------------------------------- |
| `chutes/zai-org/GLM-4.7-TEE` |
| `chutes/zai-org/GLM-5-TEE` |
| `chutes/deepseek-ai/DeepSeek-V3.2-TEE` |
| `chutes/deepseek-ai/DeepSeek-R1-0528-TEE` |
| `chutes/moonshotai/Kimi-K2.5-TEE` |
| `chutes/chutesai/Mistral-Small-3.2-24B-Instruct-2506` |
| `chutes/Qwen/Qwen3-Coder-Next-TEE` |
| `chutes/openai/gpt-oss-120b-TEE` |
## Config example
```json5
{
agents: {
defaults: {
model: { primary: "chutes/zai-org/GLM-4.7-TEE" },
models: {
"chutes/zai-org/GLM-4.7-TEE": { alias: "Chutes GLM 4.7" },
"chutes/deepseek-ai/DeepSeek-V3.2-TEE": { alias: "Chutes DeepSeek V3.2" },
},
},
},
}
```
<AccordionGroup>
<Accordion title="OAuth overrides">
You can customize the OAuth flow with optional environment variables:
| Variable | Purpose |
| -------- | ------- |
| `CHUTES_CLIENT_ID` | Custom OAuth client ID |
| `CHUTES_CLIENT_SECRET` | Custom OAuth client secret |
| `CHUTES_OAUTH_REDIRECT_URI` | Custom redirect URI |
| `CHUTES_OAUTH_SCOPES` | Custom OAuth scopes |
See the [Chutes OAuth docs](https://chutes.ai/docs/sign-in-with-chutes/overview)
for redirect-app requirements and help.
</Accordion>
<Accordion title="Notes">
- API-key and OAuth discovery both use the same `chutes` provider id.
- Chutes models are registered as `chutes/<model-id>`.
- If discovery fails at startup, the bundled static catalog is used automatically.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Provider rules, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config schema including provider settings.
</Card>
<Card title="Chutes" href="https://chutes.ai" icon="arrow-up-right-from-square">
Chutes dashboard and API docs.
</Card>
<Card title="Chutes API keys" href="https://chutes.ai/settings/api-keys" icon="key">
Create and manage Chutes API keys.
</Card>
</CardGroup>

190
openclaw/docs/providers/claude-max-api-proxy.md Normal file
View file

@ -0,0 +1,190 @@
---
summary: "Community proxy to expose Claude subscription credentials as an OpenAI-compatible endpoint"
read_when:
- You want to use Claude Max subscription with OpenAI-compatible tools
- You want a local API server that wraps Claude Code CLI
- You want to evaluate subscription-based vs API-key-based Anthropic access
title: "Claude Max API Proxy"
---
# Claude Max API Proxy
**claude-max-api-proxy** is a community tool that exposes your Claude Max/Pro subscription as an OpenAI-compatible API endpoint. This allows you to use your subscription with any tool that supports the OpenAI API format.
<Warning>
This path is technical compatibility only. Anthropic has blocked some subscription
usage outside Claude Code in the past. You must decide for yourself whether to use
it and verify Anthropic's current terms before relying on it.
</Warning>
## Why use this?
| Approach | Cost | Best For |
| ----------------------- | --------------------------------------------------- | ------------------------------------------ |
| Anthropic API | Pay per token (~$15/M input, $75/M output for Opus) | Production apps, high volume |
| Claude Max subscription | $200/month flat | Personal use, development, unlimited usage |
If you have a Claude Max subscription and want to use it with OpenAI-compatible tools, this proxy may reduce cost for some workflows. API keys remain the clearer policy path for production use.
## How it works
```
Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription)
(OpenAI format) (converts format) (uses your login)
```
The proxy:
1. Accepts OpenAI-format requests at `http://localhost:3456/v1/chat/completions`
2. Converts them to Claude Code CLI commands
3. Returns responses in OpenAI format (streaming supported)
## Getting started
<Steps>
<Step title="Install the proxy">
Requires Node.js 20+ and Claude Code CLI.
```bash
npm install -g claude-max-api-proxy
# Verify Claude CLI is authenticated
claude --version
```
</Step>
<Step title="Start the server">
```bash
claude-max-api
# Server runs at http://localhost:3456
```
</Step>
<Step title="Test the proxy">
```bash
# Health check
curl http://localhost:3456/health
# List models
curl http://localhost:3456/v1/models
# Chat completion
curl http://localhost:3456/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-4",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
</Step>
<Step title="Configure OpenClaw">
Point OpenClaw at the proxy as a custom OpenAI-compatible endpoint:
```json5
{
env: {
OPENAI_API_KEY: "not-needed",
OPENAI_BASE_URL: "http://localhost:3456/v1",
},
agents: {
defaults: {
model: { primary: "openai/claude-opus-4" },
},
},
}
```
</Step>
</Steps>
## Available models
| Model ID | Maps To |
| ----------------- | --------------- |
| `claude-opus-4` | Claude Opus 4 |
| `claude-sonnet-4` | Claude Sonnet 4 |
| `claude-haiku-4` | Claude Haiku 4 |
## Advanced
<AccordionGroup>
<Accordion title="Proxy-style OpenAI-compatible notes">
This path uses the same proxy-style OpenAI-compatible route as other custom
`/v1` backends:
- Native OpenAI-only request shaping does not apply
- No `service_tier`, no Responses `store`, no prompt-cache hints, and no
OpenAI reasoning-compat payload shaping
- Hidden OpenClaw attribution headers (`originator`, `version`, `User-Agent`)
are not injected on the proxy URL
</Accordion>
<Accordion title="Auto-start on macOS with LaunchAgent">
Create a LaunchAgent to run the proxy automatically:
```bash
cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.claude-max-api</string>
<key>RunAtLoad</key>
<true/>
<key>KeepAlive</key>
<true/>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/node</string>
<string>/usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js</string>
</array>
<key>EnvironmentVariables</key>
<dict>
<key>PATH</key>
<string>/usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin</string>
</dict>
</dict>
</plist>
EOF
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
```
</Accordion>
</AccordionGroup>
## Links
- **npm:** [https://www.npmjs.com/package/claude-max-api-proxy](https://www.npmjs.com/package/claude-max-api-proxy)
- **GitHub:** [https://github.com/atalovesyou/claude-max-api-proxy](https://github.com/atalovesyou/claude-max-api-proxy)
- **Issues:** [https://github.com/atalovesyou/claude-max-api-proxy/issues](https://github.com/atalovesyou/claude-max-api-proxy/issues)
## Notes
- This is a **community tool**, not officially supported by Anthropic or OpenClaw
- Requires an active Claude Max/Pro subscription with Claude Code CLI authenticated
- The proxy runs locally and does not send data to any third-party servers
- Streaming responses are fully supported
<Note>
For native Anthropic integration with Claude CLI or API keys, see [Anthropic provider](/providers/anthropic). For OpenAI/Codex subscriptions, see [OpenAI provider](/providers/openai).
</Note>
## Related
<CardGroup cols={2}>
<Card title="Anthropic provider" href="/providers/anthropic" icon="bolt">
Native OpenClaw integration with Claude CLI or API keys.
</Card>
<Card title="OpenAI provider" href="/providers/openai" icon="robot">
For OpenAI/Codex subscriptions.
</Card>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Overview of all providers, model refs, and failover behavior.
</Card>
<Card title="Configuration" href="/gateway/configuration" icon="gear">
Full config reference.
</Card>
</CardGroup>

116
openclaw/docs/providers/cloudflare-ai-gateway.md Normal file
View file

@ -0,0 +1,116 @@
---
title: "Cloudflare AI Gateway"
summary: "Cloudflare AI Gateway setup (auth + model selection)"
read_when:
- You want to use Cloudflare AI Gateway with OpenClaw
- You need the account ID, gateway ID, or API key env var
---
# Cloudflare AI Gateway
Cloudflare AI Gateway sits in front of provider APIs and lets you add analytics, caching, and controls. For Anthropic, OpenClaw uses the Anthropic Messages API through your Gateway endpoint.
| Property | Value |
| ------------- | ---------------------------------------------------------------------------------------- |
| Provider | `cloudflare-ai-gateway` |
| Base URL | `https://gateway.ai.cloudflare.com/v1/<account_id>/<gateway_id>/anthropic` |
| Default model | `cloudflare-ai-gateway/claude-sonnet-4-5` |
| API key | `CLOUDFLARE_AI_GATEWAY_API_KEY` (your provider API key for requests through the Gateway) |
<Note>
For Anthropic models routed through Cloudflare AI Gateway, use your **Anthropic API key** as the provider key.
</Note>
## Getting started
<Steps>
<Step title="Set the provider API key and Gateway details">
Run onboarding and choose the Cloudflare AI Gateway auth option:
```bash
openclaw onboard --auth-choice cloudflare-ai-gateway-api-key
```
This prompts for your account ID, gateway ID, and API key.
</Step>
<Step title="Set a default model">
Add the model to your OpenClaw config:
```json5
{
agents: {
defaults: {
model: { primary: "cloudflare-ai-gateway/claude-sonnet-4-5" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider cloudflare-ai-gateway
```
</Step>
</Steps>
## Non-interactive example
For scripted or CI setups, pass all values on the command line:
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice cloudflare-ai-gateway-api-key \
--cloudflare-ai-gateway-account-id "your-account-id" \
--cloudflare-ai-gateway-gateway-id "your-gateway-id" \
--cloudflare-ai-gateway-api-key "$CLOUDFLARE_AI_GATEWAY_API_KEY"
```
## Advanced configuration
<AccordionGroup>
<Accordion title="Authenticated gateways">
If you enabled Gateway authentication in Cloudflare, add the `cf-aig-authorization` header. This is **in addition to** your provider API key.
```json5
{
models: {
providers: {
"cloudflare-ai-gateway": {
headers: {
"cf-aig-authorization": "Bearer <cloudflare-ai-gateway-token>",
},
},
},
},
}
```
<Tip>
The `cf-aig-authorization` header authenticates with the Cloudflare Gateway itself, while the provider API key (for example, your Anthropic key) authenticates with the upstream provider.
</Tip>
</Accordion>
<Accordion title="Environment note">
If the Gateway runs as a daemon (launchd/systemd), make sure `CLOUDFLARE_AI_GATEWAY_API_KEY` is available to that process.
<Warning>
A key sitting only in `~/.profile` will not help a launchd/systemd daemon unless that environment is imported there as well. Set the key in `~/.openclaw/.env` or via `env.shellEnv` to ensure the gateway process can read it.
</Warning>
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
General troubleshooting and FAQ.
</Card>
</CardGroup>

354
openclaw/docs/providers/comfy.md Normal file
View file

@ -0,0 +1,354 @@
---
title: "ComfyUI"
summary: "ComfyUI workflow image, video, and music generation setup in OpenClaw"
read_when:
- You want to use local ComfyUI workflows with OpenClaw
- You want to use Comfy Cloud with image, video, or music workflows
- You need the bundled comfy plugin config keys
---
# ComfyUI
OpenClaw ships a bundled `comfy` plugin for workflow-driven ComfyUI runs. The plugin is entirely workflow-driven, so OpenClaw does not try to map generic `size`, `aspectRatio`, `resolution`, `durationSeconds`, or TTS-style controls onto your graph.
| Property | Detail |
| --------------- | -------------------------------------------------------------------------------- |
| Provider | `comfy` |
| Models | `comfy/workflow` |
| Shared surfaces | `image_generate`, `video_generate`, `music_generate` |
| Auth | None for local ComfyUI; `COMFY_API_KEY` or `COMFY_CLOUD_API_KEY` for Comfy Cloud |
| API | ComfyUI `/prompt` / `/history` / `/view` and Comfy Cloud `/api/*` |
## What it supports
- Image generation from a workflow JSON
- Image editing with 1 uploaded reference image
- Video generation from a workflow JSON
- Video generation with 1 uploaded reference image
- Music or audio generation through the shared `music_generate` tool
- Output download from a configured node or all matching output nodes
## Getting started
Choose between running ComfyUI on your own machine or using Comfy Cloud.
<Tabs>
<Tab title="Local">
**Best for:** running your own ComfyUI instance on your machine or LAN.
<Steps>
<Step title="Start ComfyUI locally">
Make sure your local ComfyUI instance is running (defaults to `http://127.0.0.1:8188`).
</Step>
<Step title="Prepare your workflow JSON">
Export or create a ComfyUI workflow JSON file. Note the node IDs for the prompt input node and the output node you want OpenClaw to read from.
</Step>
<Step title="Configure the provider">
Set `mode: "local"` and point at your workflow file. Here is a minimal image example:
```json5
{
models: {
providers: {
comfy: {
mode: "local",
baseUrl: "http://127.0.0.1:8188",
image: {
workflowPath: "./workflows/flux-api.json",
promptNodeId: "6",
outputNodeId: "9",
},
},
},
},
}
```
</Step>
<Step title="Set the default model">
Point OpenClaw at the `comfy/workflow` model for the capability you configured:
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "comfy/workflow",
},
},
},
}
```
</Step>
<Step title="Verify">
```bash
openclaw models list --provider comfy
```
</Step>
</Steps>
</Tab>
<Tab title="Comfy Cloud">
**Best for:** running workflows on Comfy Cloud without managing local GPU resources.
<Steps>
<Step title="Get an API key">
Sign up at [comfy.org](https://comfy.org) and generate an API key from your account dashboard.
</Step>
<Step title="Set the API key">
Provide your key through one of these methods:
```bash
# Environment variable (preferred)
export COMFY_API_KEY="your-key"
# Alternative environment variable
export COMFY_CLOUD_API_KEY="your-key"
# Or inline in config
openclaw config set models.providers.comfy.apiKey "your-key"
```
</Step>
<Step title="Prepare your workflow JSON">
Export or create a ComfyUI workflow JSON file. Note the node IDs for the prompt input node and the output node.
</Step>
<Step title="Configure the provider">
Set `mode: "cloud"` and point at your workflow file:
```json5
{
models: {
providers: {
comfy: {
mode: "cloud",
image: {
workflowPath: "./workflows/flux-api.json",
promptNodeId: "6",
outputNodeId: "9",
},
},
},
},
}
```
<Tip>
Cloud mode defaults `baseUrl` to `https://cloud.comfy.org`. You only need to set `baseUrl` if you use a custom cloud endpoint.
</Tip>
</Step>
<Step title="Set the default model">
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "comfy/workflow",
},
},
},
}
```
</Step>
<Step title="Verify">
```bash
openclaw models list --provider comfy
```
</Step>
</Steps>
</Tab>
</Tabs>
## Configuration
Comfy supports shared top-level connection settings plus per-capability workflow sections (`image`, `video`, `music`):
```json5
{
models: {
providers: {
comfy: {
mode: "local",
baseUrl: "http://127.0.0.1:8188",
image: {
workflowPath: "./workflows/flux-api.json",
promptNodeId: "6",
outputNodeId: "9",
},
video: {
workflowPath: "./workflows/video-api.json",
promptNodeId: "12",
outputNodeId: "21",
},
music: {
workflowPath: "./workflows/music-api.json",
promptNodeId: "3",
outputNodeId: "18",
},
},
},
},
}
```
### Shared keys
| Key | Type | Description |
| --------------------- | ---------------------- | ------------------------------------------------------------------------------------- |
| `mode` | `"local"` or `"cloud"` | Connection mode. |
| `baseUrl` | string | Defaults to `http://127.0.0.1:8188` for local or `https://cloud.comfy.org` for cloud. |
| `apiKey` | string | Optional inline key, alternative to `COMFY_API_KEY` / `COMFY_CLOUD_API_KEY` env vars. |
| `allowPrivateNetwork` | boolean | Allow a private/LAN `baseUrl` in cloud mode. |
### Per-capability keys
These keys apply inside the `image`, `video`, or `music` sections:
| Key | Required | Default | Description |
| ---------------------------- | -------- | -------- | ---------------------------------------------------------------------------- |
| `workflow` or `workflowPath` | Yes | -- | Path to the ComfyUI workflow JSON file. |
| `promptNodeId` | Yes | -- | Node ID that receives the text prompt. |
| `promptInputName` | No | `"text"` | Input name on the prompt node. |
| `outputNodeId` | No | -- | Node ID to read output from. If omitted, all matching output nodes are used. |
| `pollIntervalMs` | No | -- | Polling interval in milliseconds for job completion. |
| `timeoutMs` | No | -- | Timeout in milliseconds for the workflow run. |
The `image` and `video` sections also support:
| Key | Required | Default | Description |
| --------------------- | ------------------------------------ | --------- | --------------------------------------------------- |
| `inputImageNodeId` | Yes (when passing a reference image) | -- | Node ID that receives the uploaded reference image. |
| `inputImageInputName` | No | `"image"` | Input name on the image node. |
## Workflow details
<AccordionGroup>
<Accordion title="Image workflows">
Set the default image model to `comfy/workflow`:
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "comfy/workflow",
},
},
},
}
```
**Reference-image editing example:**
To enable image editing with an uploaded reference image, add `inputImageNodeId` to your image config:
```json5
{
models: {
providers: {
comfy: {
image: {
workflowPath: "./workflows/edit-api.json",
promptNodeId: "6",
inputImageNodeId: "7",
inputImageInputName: "image",
outputNodeId: "9",
},
},
},
},
}
```
</Accordion>
<Accordion title="Video workflows">
Set the default video model to `comfy/workflow`:
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "comfy/workflow",
},
},
},
}
```
Comfy video workflows support text-to-video and image-to-video through the configured graph.
<Note>
OpenClaw does not pass input videos into Comfy workflows. Only text prompts and single reference images are supported as inputs.
</Note>
</Accordion>
<Accordion title="Music workflows">
The bundled plugin registers a music-generation provider for workflow-defined audio or music outputs, surfaced through the shared `music_generate` tool:
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
Use the `music` config section to point at your audio workflow JSON and output node.
</Accordion>
<Accordion title="Backward compatibility">
Existing top-level image config (without the nested `image` section) still works:
```json5
{
models: {
providers: {
comfy: {
workflowPath: "./workflows/flux-api.json",
promptNodeId: "6",
outputNodeId: "9",
},
},
},
}
```
OpenClaw treats that legacy shape as the image workflow config. You do not need to migrate immediately, but the nested `image` / `video` / `music` sections are recommended for new setups.
<Tip>
If you only use image generation, the legacy flat config and the new nested `image` section are functionally equivalent.
</Tip>
</Accordion>
<Accordion title="Live tests">
Opt-in live coverage exists for the bundled plugin:
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
The live test skips individual image, video, or music cases unless the matching Comfy workflow section is configured.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Image Generation" href="/tools/image-generation" icon="image">
Image generation tool configuration and usage.
</Card>
<Card title="Video Generation" href="/tools/video-generation" icon="video">
Video generation tool configuration and usage.
</Card>
<Card title="Music Generation" href="/tools/music-generation" icon="music">
Music and audio generation tool setup.
</Card>
<Card title="Provider Directory" href="/providers/index" icon="layers">
Overview of all providers and model refs.
</Card>
<Card title="Configuration Reference" href="/gateway/configuration-reference#agent-defaults" icon="gear">
Full config reference including agent defaults.
</Card>
</CardGroup>

142
openclaw/docs/providers/deepgram.md Normal file
View file

@ -0,0 +1,142 @@
---
summary: "Deepgram transcription for inbound voice notes"
read_when:
- You want Deepgram speech-to-text for audio attachments
- You need a quick Deepgram config example
title: "Deepgram"
---
# Deepgram (Audio Transcription)
Deepgram is a speech-to-text API. In OpenClaw it is used for **inbound audio/voice note
transcription** via `tools.media.audio`.
When enabled, OpenClaw uploads the audio file to Deepgram and injects the transcript
into the reply pipeline (`{{Transcript}}` + `[Audio]` block). This is **not streaming**;
it uses the pre-recorded transcription endpoint.
| Detail | Value |
| ------------- | ---------------------------------------------------------- |
| Website | [deepgram.com](https://deepgram.com) |
| Docs | [developers.deepgram.com](https://developers.deepgram.com) |
| Auth | `DEEPGRAM_API_KEY` |
| Default model | `nova-3` |
## Getting started
<Steps>
<Step title="Set your API key">
Add your Deepgram API key to the environment:
```
DEEPGRAM_API_KEY=dg_...
```
</Step>
<Step title="Enable the audio provider">
```json5
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "deepgram", model: "nova-3" }],
},
},
},
}
```
</Step>
<Step title="Send a voice note">
Send an audio message through any connected channel. OpenClaw transcribes it
via Deepgram and injects the transcript into the reply pipeline.
</Step>
</Steps>
## Configuration options
| Option | Path | Description |
| ----------------- | ------------------------------------------------------------ | ------------------------------------- |
| `model` | `tools.media.audio.models[].model` | Deepgram model id (default: `nova-3`) |
| `language` | `tools.media.audio.models[].language` | Language hint (optional) |
| `detect_language` | `tools.media.audio.providerOptions.deepgram.detect_language` | Enable language detection (optional) |
| `punctuate` | `tools.media.audio.providerOptions.deepgram.punctuate` | Enable punctuation (optional) |
| `smart_format` | `tools.media.audio.providerOptions.deepgram.smart_format` | Enable smart formatting (optional) |
<Tabs>
<Tab title="With language hint">
```json5
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "deepgram", model: "nova-3", language: "en" }],
},
},
},
}
```
</Tab>
<Tab title="With Deepgram options">
```json5
{
tools: {
media: {
audio: {
enabled: true,
providerOptions: {
deepgram: {
detect_language: true,
punctuate: true,
smart_format: true,
},
},
models: [{ provider: "deepgram", model: "nova-3" }],
},
},
},
}
```
</Tab>
</Tabs>
## Notes
<AccordionGroup>
<Accordion title="Authentication">
Authentication follows the standard provider auth order. `DEEPGRAM_API_KEY` is
the simplest path.
</Accordion>
<Accordion title="Proxy and custom endpoints">
Override endpoints or headers with `tools.media.audio.baseUrl` and
`tools.media.audio.headers` when using a proxy.
</Accordion>
<Accordion title="Output behavior">
Output follows the same audio rules as other providers (size caps, timeouts,
transcript injection).
</Accordion>
</AccordionGroup>
<Note>
Deepgram transcription is **pre-recorded only** (not real-time streaming). OpenClaw
uploads the complete audio file and waits for the full transcript before injecting
it into the conversation.
</Note>
## Related
<CardGroup cols={2}>
<Card title="Media tools" href="/tools/media" icon="photo-film">
Audio, image, and video processing pipeline overview.
</Card>
<Card title="Configuration" href="/configuration" icon="gear">
Full config reference including media tool settings.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
Common issues and debugging steps.
</Card>
<Card title="FAQ" href="/help/faq" icon="circle-question">
Frequently asked questions about OpenClaw setup.
</Card>
</CardGroup>

96
openclaw/docs/providers/deepseek.md Normal file
View file

@ -0,0 +1,96 @@
---
title: "DeepSeek"
summary: "DeepSeek setup (auth + model selection)"
read_when:
- You want to use DeepSeek with OpenClaw
- You need the API key env var or CLI auth choice
---
# DeepSeek
[DeepSeek](https://www.deepseek.com) provides powerful AI models with an OpenAI-compatible API.
| Property | Value |
| -------- | -------------------------- |
| Provider | `deepseek` |
| Auth | `DEEPSEEK_API_KEY` |
| API | OpenAI-compatible |
| Base URL | `https://api.deepseek.com` |
## Getting started
<Steps>
<Step title="Get your API key">
Create an API key at [platform.deepseek.com](https://platform.deepseek.com/api_keys).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice deepseek-api-key
```
This will prompt for your API key and set `deepseek/deepseek-chat` as the default model.
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider deepseek
```
</Step>
</Steps>
<AccordionGroup>
<Accordion title="Non-interactive setup">
For scripted or headless installations, pass all flags directly:
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice deepseek-api-key \
--deepseek-api-key "$DEEPSEEK_API_KEY" \
--skip-health \
--accept-risk
```
</Accordion>
</AccordionGroup>
<Warning>
If the Gateway runs as a daemon (launchd/systemd), make sure `DEEPSEEK_API_KEY`
is available to that process (for example, in `~/.openclaw/.env` or via
`env.shellEnv`).
</Warning>
## Built-in catalog
| Model ref | Name | Input | Context | Max output | Notes |
| ---------------------------- | ----------------- | ----- | ------- | ---------- | ------------------------------------------------- |
| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | Default model; DeepSeek V3.2 non-thinking surface |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | Reasoning-enabled V3.2 surface |
<Tip>
Both bundled models currently advertise streaming usage compatibility in source.
</Tip>
## Config example
```json5
{
env: { DEEPSEEK_API_KEY: "sk-..." },
agents: {
defaults: {
model: { primary: "deepseek/deepseek-chat" },
},
},
}
```
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config reference for agents, models, and providers.
</Card>
</CardGroup>

145
openclaw/docs/providers/fal.md Normal file
View file

@ -0,0 +1,145 @@
---
title: "fal"
summary: "fal image and video generation setup in OpenClaw"
read_when:
- You want to use fal image generation in OpenClaw
- You need the FAL_KEY auth flow
- You want fal defaults for image_generate or video_generate
---
# fal
OpenClaw ships a bundled `fal` provider for hosted image and video generation.
| Property | Value |
| -------- | ------------------------------------------------------------- |
| Provider | `fal` |
| Auth | `FAL_KEY` (canonical; `FAL_API_KEY` also works as a fallback) |
| API | fal model endpoints |
## Getting started
<Steps>
<Step title="Set the API key">
```bash
openclaw onboard --auth-choice fal-api-key
```
</Step>
<Step title="Set a default image model">
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "fal/fal-ai/flux/dev",
},
},
},
}
```
</Step>
</Steps>
## Image generation
The bundled `fal` image-generation provider defaults to
`fal/fal-ai/flux/dev`.
| Capability | Value |
| -------------- | -------------------------- |
| Max images | 4 per request |
| Edit mode | Enabled, 1 reference image |
| Size overrides | Supported |
| Aspect ratio | Supported |
| Resolution | Supported |
<Warning>
The fal image edit endpoint does **not** support `aspectRatio` overrides.
</Warning>
To use fal as the default image provider:
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "fal/fal-ai/flux/dev",
},
},
},
}
```
## Video generation
The bundled `fal` video-generation provider defaults to
`fal/fal-ai/minimax/video-01-live`.
| Capability | Value |
| ---------- | ------------------------------------------------------------ |
| Modes | Text-to-video, single-image reference |
| Runtime | Queue-backed submit/status/result flow for long-running jobs |
<AccordionGroup>
<Accordion title="Available video models">
**HeyGen video-agent:**
- `fal/fal-ai/heygen/v2/video-agent`
**Seedance 2.0:**
- `fal/bytedance/seedance-2.0/fast/text-to-video`
- `fal/bytedance/seedance-2.0/fast/image-to-video`
- `fal/bytedance/seedance-2.0/text-to-video`
- `fal/bytedance/seedance-2.0/image-to-video`
</Accordion>
<Accordion title="Seedance 2.0 config example">
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "fal/bytedance/seedance-2.0/fast/text-to-video",
},
},
},
}
```
</Accordion>
<Accordion title="HeyGen video-agent config example">
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "fal/fal-ai/heygen/v2/video-agent",
},
},
},
}
```
</Accordion>
</AccordionGroup>
<Tip>
Use `openclaw models list --provider fal` to see the full list of available fal
models, including any recently added entries.
</Tip>
## Related
<CardGroup cols={2}>
<Card title="Image generation" href="/tools/image-generation" icon="image">
Shared image tool parameters and provider selection.
</Card>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video tool parameters and provider selection.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference#agent-defaults" icon="gear">
Agent defaults including image and video model selection.
</Card>
</CardGroup>

108
openclaw/docs/providers/fireworks.md Normal file
View file

@ -0,0 +1,108 @@
---
title: "Fireworks"
summary: "Fireworks setup (auth + model selection)"
read_when:
- You want to use Fireworks with OpenClaw
- You need the Fireworks API key env var or default model id
---
# Fireworks
[Fireworks](https://fireworks.ai) exposes open-weight and routed models through an OpenAI-compatible API. OpenClaw includes a bundled Fireworks provider plugin.
| Property | Value |
| ------------- | ------------------------------------------------------ |
| Provider | `fireworks` |
| Auth | `FIREWORKS_API_KEY` |
| API | OpenAI-compatible chat/completions |
| Base URL | `https://api.fireworks.ai/inference/v1` |
| Default model | `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` |
## Getting started
<Steps>
<Step title="Set up Fireworks auth through onboarding">
```bash
openclaw onboard --auth-choice fireworks-api-key
```
This stores your Fireworks key in OpenClaw config and sets the Fire Pass starter model as the default.
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider fireworks
```
</Step>
</Steps>
## Non-interactive example
For scripted or CI setups, pass all values on the command line:
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice fireworks-api-key \
--fireworks-api-key "$FIREWORKS_API_KEY" \
--skip-health \
--accept-risk
```
## Built-in catalog
| Model ref | Name | Input | Context | Max output | Notes |
| ------------------------------------------------------ | --------------------------- | ---------- | ------- | ---------- | ------------------------------------------ |
| `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo` | Kimi K2.5 Turbo (Fire Pass) | text,image | 256,000 | 256,000 | Default bundled starter model on Fireworks |
<Tip>
If Fireworks publishes a newer model such as a fresh Qwen or Gemma release, you can switch to it directly by using its Fireworks model id without waiting for a bundled catalog update.
</Tip>
## Custom Fireworks model ids
OpenClaw accepts dynamic Fireworks model ids too. Use the exact model or router id shown by Fireworks and prefix it with `fireworks/`.
```json5
{
agents: {
defaults: {
model: {
primary: "fireworks/accounts/fireworks/routers/kimi-k2p5-turbo",
},
},
},
}
```
<AccordionGroup>
<Accordion title="How model id prefixing works">
Every Fireworks model ref in OpenClaw starts with `fireworks/` followed by the exact id or router path from the Fireworks platform. For example:
- Router model: `fireworks/accounts/fireworks/routers/kimi-k2p5-turbo`
- Direct model: `fireworks/accounts/fireworks/models/<model-name>`
OpenClaw strips the `fireworks/` prefix when building the API request and sends the remaining path to the Fireworks endpoint.
</Accordion>
<Accordion title="Environment note">
If the Gateway runs outside your interactive shell, make sure `FIREWORKS_API_KEY` is available to that process too.
<Warning>
A key sitting only in `~/.profile` will not help a launchd/systemd daemon unless that environment is imported there as well. Set the key in `~/.openclaw/.env` or via `env.shellEnv` to ensure the gateway process can read it.
</Warning>
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
General troubleshooting and FAQ.
</Card>
</CardGroup>

173
openclaw/docs/providers/github-copilot.md Normal file
View file

@ -0,0 +1,173 @@
---
summary: "Sign in to GitHub Copilot from OpenClaw using the device flow"
read_when:
- You want to use GitHub Copilot as a model provider
- You need the `openclaw models auth login-github-copilot` flow
title: "GitHub Copilot"
---
# GitHub Copilot
GitHub Copilot is GitHub's AI coding assistant. It provides access to Copilot
models for your GitHub account and plan. OpenClaw can use Copilot as a model
provider in two different ways.
## Two ways to use Copilot in OpenClaw
<Tabs>
<Tab title="Built-in provider (github-copilot)">
Use the native device-login flow to obtain a GitHub token, then exchange it for
Copilot API tokens when OpenClaw runs. This is the **default** and simplest path
because it does not require VS Code.
<Steps>
<Step title="Run the login command">
```bash
openclaw models auth login-github-copilot
```
You will be prompted to visit a URL and enter a one-time code. Keep the
terminal open until it completes.
</Step>
<Step title="Set a default model">
```bash
openclaw models set github-copilot/claude-opus-4.6
```
Or in config:
```json5
{
agents: {
defaults: { model: { primary: "github-copilot/claude-opus-4.6" } },
},
}
```
</Step>
</Steps>
</Tab>
<Tab title="Copilot Proxy plugin (copilot-proxy)">
Use the **Copilot Proxy** VS Code extension as a local bridge. OpenClaw talks to
the proxy's `/v1` endpoint and uses the model list you configure there.
<Note>
Choose this when you already run Copilot Proxy in VS Code or need to route
through it. You must enable the plugin and keep the VS Code extension running.
</Note>
</Tab>
</Tabs>
## Optional flags
| Flag | Description |
| --------------- | --------------------------------------------------- |
| `--yes` | Skip the confirmation prompt |
| `--set-default` | Also apply the provider's recommended default model |
```bash
# Skip confirmation
openclaw models auth login-github-copilot --yes
# Login and set the default model in one step
openclaw models auth login --provider github-copilot --method device --set-default
```
<AccordionGroup>
<Accordion title="Interactive TTY required">
The device-login flow requires an interactive TTY. Run it directly in a
terminal, not in a non-interactive script or CI pipeline.
</Accordion>
<Accordion title="Model availability depends on your plan">
Copilot model availability depends on your GitHub plan. If a model is
rejected, try another ID (for example `github-copilot/gpt-4.1`).
</Accordion>
<Accordion title="Transport selection">
Claude model IDs use the Anthropic Messages transport automatically. GPT,
o-series, and Gemini models keep the OpenAI Responses transport. OpenClaw
selects the correct transport based on the model ref.
</Accordion>
<Accordion title="Environment variable resolution order">
OpenClaw resolves Copilot auth from environment variables in the following
priority order:
| Priority | Variable | Notes |
| -------- | --------------------- | -------------------------------- |
| 1 | `COPILOT_GITHUB_TOKEN` | Highest priority, Copilot-specific |
| 2 | `GH_TOKEN` | GitHub CLI token (fallback) |
| 3 | `GITHUB_TOKEN` | Standard GitHub token (lowest) |
When multiple variables are set, OpenClaw uses the highest-priority one.
The device-login flow (`openclaw models auth login-github-copilot`) stores
its token in the auth profile store and takes precedence over all environment
variables.
</Accordion>
<Accordion title="Token storage">
The login stores a GitHub token in the auth profile store and exchanges it
for a Copilot API token when OpenClaw runs. You do not need to manage the
token manually.
</Accordion>
</AccordionGroup>
<Warning>
Requires an interactive TTY. Run the login command directly in a terminal, not
inside a headless script or CI job.
</Warning>
## Memory search embeddings
GitHub Copilot can also serve as an embedding provider for
[memory search](/concepts/memory-search). If you have a Copilot subscription and
have logged in, OpenClaw can use it for embeddings without a separate API key.
### Auto-detection
When `memorySearch.provider` is `"auto"` (the default), GitHub Copilot is tried
at priority 15 -- after local embeddings but before OpenAI and other paid
providers. If a GitHub token is available, OpenClaw discovers available
embedding models from the Copilot API and picks the best one automatically.
### Explicit config
```json5
{
agents: {
defaults: {
memorySearch: {
provider: "github-copilot",
// Optional: override the auto-discovered model
model: "text-embedding-3-small",
},
},
},
}
```
### How it works
1. OpenClaw resolves your GitHub token (from env vars or auth profile).
2. Exchanges it for a short-lived Copilot API token.
3. Queries the Copilot `/models` endpoint to discover available embedding models.
4. Picks the best model (prefers `text-embedding-3-small`).
5. Sends embedding requests to the Copilot `/embeddings` endpoint.
Model availability depends on your GitHub plan. If no embedding models are
available, OpenClaw skips Copilot and tries the next provider.
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="OAuth and auth" href="/gateway/authentication" icon="key">
Auth details and credential reuse rules.
</Card>
</CardGroup>

110
openclaw/docs/providers/glm.md Normal file
View file

@ -0,0 +1,110 @@
---
summary: "GLM model family overview + how to use it in OpenClaw"
read_when:
- You want GLM models in OpenClaw
- You need the model naming convention and setup
title: "GLM (Zhipu)"
---
# GLM models
GLM is a **model family** (not a company) available through the Z.AI platform. In OpenClaw, GLM
models are accessed via the `zai` provider and model IDs like `zai/glm-5`.
## Getting started
<Steps>
<Step title="Choose an auth route and run onboarding">
Pick the onboarding choice that matches your Z.AI plan and region:
| Auth choice | Best for |
| ----------- | -------- |
| `zai-api-key` | Generic API-key setup with endpoint auto-detection |
| `zai-coding-global` | Coding Plan users (global) |
| `zai-coding-cn` | Coding Plan users (China region) |
| `zai-global` | General API (global) |
| `zai-cn` | General API (China region) |
```bash
# Example: generic auto-detect
openclaw onboard --auth-choice zai-api-key
# Example: Coding Plan global
openclaw onboard --auth-choice zai-coding-global
```
</Step>
<Step title="Set GLM as the default model">
```bash
openclaw config set agents.defaults.model.primary "zai/glm-5.1"
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider zai
```
</Step>
</Steps>
## Config example
```json5
{
env: { ZAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
}
```
<Tip>
`zai-api-key` lets OpenClaw detect the matching Z.AI endpoint from the key and
apply the correct base URL automatically. Use the explicit regional choices when
you want to force a specific Coding Plan or general API surface.
</Tip>
## Bundled GLM models
OpenClaw currently seeds the bundled `zai` provider with these GLM refs:
| Model | Model |
| --------------- | ---------------- |
| `glm-5.1` | `glm-4.7` |
| `glm-5` | `glm-4.7-flash` |
| `glm-5-turbo` | `glm-4.7-flashx` |
| `glm-5v-turbo` | `glm-4.6` |
| `glm-4.5` | `glm-4.6v` |
| `glm-4.5-air` | |
| `glm-4.5-flash` | |
| `glm-4.5v` | |
<Note>
The default bundled model ref is `zai/glm-5.1`. GLM versions and availability
can change; check Z.AI's docs for the latest.
</Note>
## Advanced notes
<AccordionGroup>
<Accordion title="Endpoint auto-detection">
When you use the `zai-api-key` auth choice, OpenClaw inspects the key format
to determine the correct Z.AI base URL. Explicit regional choices
(`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`) override
auto-detection and pin the endpoint directly.
</Accordion>
<Accordion title="Provider details">
GLM models are served by the `zai` runtime provider. For full provider
configuration, regional endpoints, and additional capabilities, see
[Z.AI provider docs](/providers/zai).
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Z.AI provider" href="/providers/zai" icon="server">
Full Z.AI provider configuration and regional endpoints.
</Card>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
</CardGroup>

352
openclaw/docs/providers/google.md Normal file
View file

@ -0,0 +1,352 @@
---
title: "Google (Gemini)"
summary: "Google Gemini setup (API key + OAuth, image generation, media understanding, TTS, web search)"
read_when:
- You want to use Google Gemini models with OpenClaw
- You need the API key or OAuth auth flow
---
# Google (Gemini)
The Google plugin provides access to Gemini models through Google AI Studio, plus
image generation, media understanding (image/audio/video), text-to-speech, and web search via
Gemini Grounding.
- Provider: `google`
- Auth: `GEMINI_API_KEY` or `GOOGLE_API_KEY`
- API: Google Gemini API
- Alternative provider: `google-gemini-cli` (OAuth)
## Getting started
Choose your preferred auth method and follow the setup steps.
<Tabs>
<Tab title="API key">
**Best for:** standard Gemini API access through Google AI Studio.
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice gemini-api-key
```
Or pass the key directly:
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice gemini-api-key \
--gemini-api-key "$GEMINI_API_KEY"
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "google/gemini-3.1-pro-preview" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider google
```
</Step>
</Steps>
<Tip>
The environment variables `GEMINI_API_KEY` and `GOOGLE_API_KEY` are both accepted. Use whichever you already have configured.
</Tip>
</Tab>
<Tab title="Gemini CLI (OAuth)">
**Best for:** reusing an existing Gemini CLI login via PKCE OAuth instead of a separate API key.
<Warning>
The `google-gemini-cli` provider is an unofficial integration. Some users
report account restrictions when using OAuth this way. Use at your own risk.
</Warning>
<Steps>
<Step title="Install the Gemini CLI">
The local `gemini` command must be available on `PATH`.
```bash
# Homebrew
brew install gemini-cli
# or npm
npm install -g @google/gemini-cli
```
OpenClaw supports both Homebrew installs and global npm installs, including
common Windows/npm layouts.
</Step>
<Step title="Log in via OAuth">
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider google-gemini-cli
```
</Step>
</Steps>
- Default model: `google-gemini-cli/gemini-3-flash-preview`
- Alias: `gemini-cli`
**Environment variables:**
- `OPENCLAW_GEMINI_OAUTH_CLIENT_ID`
- `OPENCLAW_GEMINI_OAUTH_CLIENT_SECRET`
(Or the `GEMINI_CLI_*` variants.)
<Note>
If Gemini CLI OAuth requests fail after login, set `GOOGLE_CLOUD_PROJECT` or
`GOOGLE_CLOUD_PROJECT_ID` on the gateway host and retry.
</Note>
<Note>
If login fails before the browser flow starts, make sure the local `gemini`
command is installed and on `PATH`.
</Note>
The OAuth-only `google-gemini-cli` provider is a separate text-inference
surface. Image generation, media understanding, and Gemini Grounding stay on
the `google` provider id.
</Tab>
</Tabs>
## Capabilities
| Capability | Supported |
| ---------------------- | ----------------------------- |
| Chat completions | Yes |
| Image generation | Yes |
| Music generation | Yes |
| Text-to-speech | Yes |
| Image understanding | Yes |
| Audio transcription | Yes |
| Video understanding | Yes |
| Web search (Grounding) | Yes |
| Thinking/reasoning | Yes (Gemini 2.5+ / Gemini 3+) |
| Gemma 4 models | Yes |
<Tip>
Gemini 3 models use `thinkingLevel` rather than `thinkingBudget`. OpenClaw maps
Gemini 3, Gemini 3.1, and `gemini-*-latest` alias reasoning controls to
`thinkingLevel` so default/low-latency runs do not send disabled
`thinkingBudget` values.
Gemma 4 models (for example `gemma-4-26b-a4b-it`) support thinking mode. OpenClaw
rewrites `thinkingBudget` to a supported Google `thinkingLevel` for Gemma 4.
Setting thinking to `off` preserves thinking disabled instead of mapping to
`MINIMAL`.
</Tip>
## Image generation
The bundled `google` image-generation provider defaults to
`google/gemini-3.1-flash-image-preview`.
- Also supports `google/gemini-3-pro-image-preview`
- Generate: up to 4 images per request
- Edit mode: enabled, up to 5 input images
- Geometry controls: `size`, `aspectRatio`, and `resolution`
To use Google as the default image provider:
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "google/gemini-3.1-flash-image-preview",
},
},
},
}
```
<Note>
See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
## Video generation
The bundled `google` plugin also registers video generation through the shared
`video_generate` tool.
- Default video model: `google/veo-3.1-fast-generate-preview`
- Modes: text-to-video, image-to-video, and single-video reference flows
- Supports `aspectRatio`, `resolution`, and `audio`
- Current duration clamp: **4 to 8 seconds**
To use Google as the default video provider:
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "google/veo-3.1-fast-generate-preview",
},
},
},
}
```
<Note>
See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
## Music generation
The bundled `google` plugin also registers music generation through the shared
`music_generate` tool.
- Default music model: `google/lyria-3-clip-preview`
- Also supports `google/lyria-3-pro-preview`
- Prompt controls: `lyrics` and `instrumental`
- Output format: `mp3` by default, plus `wav` on `google/lyria-3-pro-preview`
- Reference inputs: up to 10 images
- Session-backed runs detach through the shared task/status flow, including `action: "status"`
To use Google as the default music provider:
```json5
{
agents: {
defaults: {
musicGenerationModel: {
primary: "google/lyria-3-clip-preview",
},
},
},
}
```
<Note>
See [Music Generation](/tools/music-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
## Text-to-speech
The bundled `google` speech provider uses the Gemini API TTS path with
`gemini-3.1-flash-tts-preview`.
- Default voice: `Kore`
- Auth: `messages.tts.providers.google.apiKey`, `models.providers.google.apiKey`, `GEMINI_API_KEY`, or `GOOGLE_API_KEY`
- Output: WAV for regular TTS attachments, PCM for Talk/telephony
- Native voice-note output: not supported on this Gemini API path because the API returns PCM rather than Opus
To use Google as the default TTS provider:
```json5
{
messages: {
tts: {
auto: "always",
provider: "google",
providers: {
google: {
model: "gemini-3.1-flash-tts-preview",
voiceName: "Kore",
},
},
},
},
}
```
Gemini API TTS accepts expressive square-bracket audio tags in the text, such as
`[whispers]` or `[laughs]`. To keep tags out of the visible chat reply while
sending them to TTS, put them inside a `[[tts:text]]...[[/tts:text]]` block:
```text
Here is the clean reply text.
[[tts:text]][whispers] Here is the spoken version.[[/tts:text]]
```
<Note>
A Google Cloud Console API key restricted to the Gemini API is valid for this
provider. This is not the separate Cloud Text-to-Speech API path.
</Note>
## Advanced configuration
<AccordionGroup>
<Accordion title="Direct Gemini cache reuse">
For direct Gemini API runs (`api: "google-generative-ai"`), OpenClaw
passes a configured `cachedContent` handle through to Gemini requests.
- Configure per-model or global params with either
`cachedContent` or legacy `cached_content`
- If both are present, `cachedContent` wins
- Example value: `cachedContents/prebuilt-context`
- Gemini cache-hit usage is normalized into OpenClaw `cacheRead` from
upstream `cachedContentTokenCount`
```json5
{
agents: {
defaults: {
models: {
"google/gemini-2.5-pro": {
params: {
cachedContent: "cachedContents/prebuilt-context",
},
},
},
},
},
}
```
</Accordion>
<Accordion title="Gemini CLI JSON usage notes">
When using the `google-gemini-cli` OAuth provider, OpenClaw normalizes
the CLI JSON output as follows:
- Reply text comes from the CLI JSON `response` field.
- Usage falls back to `stats` when the CLI leaves `usage` empty.
- `stats.cached` is normalized into OpenClaw `cacheRead`.
- If `stats.input` is missing, OpenClaw derives input tokens from
`stats.input_tokens - stats.cached`.
</Accordion>
<Accordion title="Environment and daemon setup">
If the Gateway runs as a daemon (launchd/systemd), make sure `GEMINI_API_KEY`
is available to that process (for example, in `~/.openclaw/.env` or via
`env.shellEnv`).
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Image generation" href="/tools/image-generation" icon="image">
Shared image tool parameters and provider selection.
</Card>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video tool parameters and provider selection.
</Card>
<Card title="Music generation" href="/tools/music-generation" icon="music">
Shared music tool parameters and provider selection.
</Card>
</CardGroup>

134
openclaw/docs/providers/groq.md Normal file
View file

@ -0,0 +1,134 @@
---
title: "Groq"
summary: "Groq setup (auth + model selection)"
read_when:
- You want to use Groq with OpenClaw
- You need the API key env var or CLI auth choice
---
# Groq
[Groq](https://groq.com) provides ultra-fast inference on open-source models
(Llama, Gemma, Mistral, and more) using custom LPU hardware. OpenClaw connects
to Groq through its OpenAI-compatible API.
| Property | Value |
| -------- | ----------------- |
| Provider | `groq` |
| Auth | `GROQ_API_KEY` |
| API | OpenAI-compatible |
## Getting started
<Steps>
<Step title="Get an API key">
Create an API key at [console.groq.com/keys](https://console.groq.com/keys).
</Step>
<Step title="Set the API key">
```bash
export GROQ_API_KEY="gsk_..."
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "groq/llama-3.3-70b-versatile" },
},
},
}
```
</Step>
</Steps>
### Config file example
```json5
{
env: { GROQ_API_KEY: "gsk_..." },
agents: {
defaults: {
model: { primary: "groq/llama-3.3-70b-versatile" },
},
},
}
```
## Available models
Groq's model catalog changes frequently. Run `openclaw models list | grep groq`
to see currently available models, or check
[console.groq.com/docs/models](https://console.groq.com/docs/models).
| Model | Notes |
| --------------------------- | ---------------------------------- |
| **Llama 3.3 70B Versatile** | General-purpose, large context |
| **Llama 3.1 8B Instant** | Fast, lightweight |
| **Gemma 2 9B** | Compact, efficient |
| **Mixtral 8x7B** | MoE architecture, strong reasoning |
<Tip>
Use `openclaw models list --provider groq` for the most up-to-date list of
models available on your account.
</Tip>
## Audio transcription
Groq also provides fast Whisper-based audio transcription. When configured as a
media-understanding provider, OpenClaw uses Groq's `whisper-large-v3-turbo`
model to transcribe voice messages through the shared `tools.media.audio`
surface.
```json5
{
tools: {
media: {
audio: {
models: [{ provider: "groq" }],
},
},
},
}
```
<AccordionGroup>
<Accordion title="Audio transcription details">
| Property | Value |
|----------|-------|
| Shared config path | `tools.media.audio` |
| Default base URL | `https://api.groq.com/openai/v1` |
| Default model | `whisper-large-v3-turbo` |
| API endpoint | OpenAI-compatible `/audio/transcriptions` |
</Accordion>
<Accordion title="Environment note">
If the Gateway runs as a daemon (launchd/systemd), make sure `GROQ_API_KEY` is
available to that process (for example, in `~/.openclaw/.env` or via
`env.shellEnv`).
<Warning>
Keys set only in your interactive shell are not visible to daemon-managed
gateway processes. Use `~/.openclaw/.env` or `env.shellEnv` config for
persistent availability.
</Warning>
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config schema including provider and audio settings.
</Card>
<Card title="Groq Console" href="https://console.groq.com" icon="arrow-up-right-from-square">
Groq dashboard, API docs, and pricing.
</Card>
<Card title="Groq model list" href="https://console.groq.com/docs/models" icon="list">
Official Groq model catalog.
</Card>
</CardGroup>

237
openclaw/docs/providers/huggingface.md Normal file
View file

@ -0,0 +1,237 @@
---
summary: "Hugging Face Inference setup (auth + model selection)"
read_when:
- You want to use Hugging Face Inference with OpenClaw
- You need the HF token env var or CLI auth choice
title: "Hugging Face (Inference)"
---
# Hugging Face (Inference)
[Hugging Face Inference Providers](https://huggingface.co/docs/inference-providers) offer OpenAI-compatible chat completions through a single router API. You get access to many models (DeepSeek, Llama, and more) with one token. OpenClaw uses the **OpenAI-compatible endpoint** (chat completions only); for text-to-image, embeddings, or speech use the [HF inference clients](https://huggingface.co/docs/api-inference/quicktour) directly.
- Provider: `huggingface`
- Auth: `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` (fine-grained token with **Make calls to Inference Providers**)
- API: OpenAI-compatible (`https://router.huggingface.co/v1`)
- Billing: Single HF token; [pricing](https://huggingface.co/docs/inference-providers/pricing) follows provider rates with a free tier.
## Getting started
<Steps>
<Step title="Create a fine-grained token">
Go to [Hugging Face Settings Tokens](https://huggingface.co/settings/tokens/new?ownUserPermissions=inference.serverless.write&tokenType=fineGrained) and create a new fine-grained token.
<Warning>
The token must have the **Make calls to Inference Providers** permission enabled or API requests will be rejected.
</Warning>
</Step>
<Step title="Run onboarding">
Choose **Hugging Face** in the provider dropdown, then enter your API key when prompted:
```bash
openclaw onboard --auth-choice huggingface-api-key
```
</Step>
<Step title="Select a default model">
In the **Default Hugging Face model** dropdown, pick the model you want. The list is loaded from the Inference API when you have a valid token; otherwise a built-in list is shown. Your choice is saved as the default model.
You can also set or change the default model later in config:
```json5
{
agents: {
defaults: {
model: { primary: "huggingface/deepseek-ai/DeepSeek-R1" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider huggingface
```
</Step>
</Steps>
### Non-interactive setup
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice huggingface-api-key \
--huggingface-api-key "$HF_TOKEN"
```
This will set `huggingface/deepseek-ai/DeepSeek-R1` as the default model.
## Model IDs
Model refs use the form `huggingface/<org>/<model>` (Hub-style IDs). The list below is from **GET** `https://router.huggingface.co/v1/models`; your catalog may include more.
| Model | Ref (prefix with `huggingface/`) |
| ---------------------- | ----------------------------------- |
| DeepSeek R1 | `deepseek-ai/DeepSeek-R1` |
| DeepSeek V3.2 | `deepseek-ai/DeepSeek-V3.2` |
| Qwen3 8B | `Qwen/Qwen3-8B` |
| Qwen2.5 7B Instruct | `Qwen/Qwen2.5-7B-Instruct` |
| Qwen3 32B | `Qwen/Qwen3-32B` |
| Llama 3.3 70B Instruct | `meta-llama/Llama-3.3-70B-Instruct` |
| Llama 3.1 8B Instruct | `meta-llama/Llama-3.1-8B-Instruct` |
| GPT-OSS 120B | `openai/gpt-oss-120b` |
| GLM 4.7 | `zai-org/GLM-4.7` |
| Kimi K2.5 | `moonshotai/Kimi-K2.5` |
<Tip>
You can append `:fastest` or `:cheapest` to any model id. Set your default order in [Inference Provider settings](https://hf.co/settings/inference-providers); see [Inference Providers](https://huggingface.co/docs/inference-providers) and **GET** `https://router.huggingface.co/v1/models` for the full list.
</Tip>
## Advanced details
<AccordionGroup>
<Accordion title="Model discovery and onboarding dropdown">
OpenClaw discovers models by calling the **Inference endpoint directly**:
```bash
GET https://router.huggingface.co/v1/models
```
(Optional: send `Authorization: Bearer $HUGGINGFACE_HUB_TOKEN` or `$HF_TOKEN` for the full list; some endpoints return a subset without auth.) The response is OpenAI-style `{ "object": "list", "data": [ { "id": "Qwen/Qwen3-8B", "owned_by": "Qwen", ... }, ... ] }`.
When you configure a Hugging Face API key (via onboarding, `HUGGINGFACE_HUB_TOKEN`, or `HF_TOKEN`), OpenClaw uses this GET to discover available chat-completion models. During **interactive setup**, after you enter your token you see a **Default Hugging Face model** dropdown populated from that list (or the built-in catalog if the request fails). At runtime (e.g. Gateway startup), when a key is present, OpenClaw again calls **GET** `https://router.huggingface.co/v1/models` to refresh the catalog. The list is merged with a built-in catalog (for metadata like context window and cost). If the request fails or no key is set, only the built-in catalog is used.
</Accordion>
<Accordion title="Model names, aliases, and policy suffixes">
- **Name from API:** The model display name is **hydrated from GET /v1/models** when the API returns `name`, `title`, or `display_name`; otherwise it is derived from the model id (e.g. `deepseek-ai/DeepSeek-R1` becomes "DeepSeek R1").
- **Override display name:** You can set a custom label per model in config so it appears the way you want in the CLI and UI:
```json5
{
agents: {
defaults: {
models: {
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1 (fast)" },
"huggingface/deepseek-ai/DeepSeek-R1:cheapest": { alias: "DeepSeek R1 (cheap)" },
},
},
},
}
```
- **Policy suffixes:** OpenClaw's bundled Hugging Face docs and helpers currently treat these two suffixes as the built-in policy variants:
- **`:fastest`** — highest throughput.
- **`:cheapest`** — lowest cost per output token.
You can add these as separate entries in `models.providers.huggingface.models` or set `model.primary` with the suffix. You can also set your default provider order in [Inference Provider settings](https://hf.co/settings/inference-providers) (no suffix = use that order).
- **Config merge:** Existing entries in `models.providers.huggingface.models` (e.g. in `models.json`) are kept when config is merged. So any custom `name`, `alias`, or model options you set there are preserved.
</Accordion>
<Accordion title="Environment and daemon setup">
If the Gateway runs as a daemon (launchd/systemd), make sure `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` is available to that process (for example, in `~/.openclaw/.env` or via `env.shellEnv`).
<Note>
OpenClaw accepts both `HUGGINGFACE_HUB_TOKEN` and `HF_TOKEN` as env var aliases. Either one works; if both are set, `HUGGINGFACE_HUB_TOKEN` takes precedence.
</Note>
</Accordion>
<Accordion title="Config: DeepSeek R1 with Qwen fallback">
```json5
{
agents: {
defaults: {
model: {
primary: "huggingface/deepseek-ai/DeepSeek-R1",
fallbacks: ["huggingface/Qwen/Qwen3-8B"],
},
models: {
"huggingface/deepseek-ai/DeepSeek-R1": { alias: "DeepSeek R1" },
"huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
},
},
},
}
```
</Accordion>
<Accordion title="Config: Qwen with cheapest and fastest variants">
```json5
{
agents: {
defaults: {
model: { primary: "huggingface/Qwen/Qwen3-8B" },
models: {
"huggingface/Qwen/Qwen3-8B": { alias: "Qwen3 8B" },
"huggingface/Qwen/Qwen3-8B:cheapest": { alias: "Qwen3 8B (cheapest)" },
"huggingface/Qwen/Qwen3-8B:fastest": { alias: "Qwen3 8B (fastest)" },
},
},
},
}
```
</Accordion>
<Accordion title="Config: DeepSeek + Llama + GPT-OSS with aliases">
```json5
{
agents: {
defaults: {
model: {
primary: "huggingface/deepseek-ai/DeepSeek-V3.2",
fallbacks: [
"huggingface/meta-llama/Llama-3.3-70B-Instruct",
"huggingface/openai/gpt-oss-120b",
],
},
models: {
"huggingface/deepseek-ai/DeepSeek-V3.2": { alias: "DeepSeek V3.2" },
"huggingface/meta-llama/Llama-3.3-70B-Instruct": { alias: "Llama 3.3 70B" },
"huggingface/openai/gpt-oss-120b": { alias: "GPT-OSS 120B" },
},
},
},
}
```
</Accordion>
<Accordion title="Config: Multiple Qwen and DeepSeek with policy suffixes">
```json5
{
agents: {
defaults: {
model: { primary: "huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest" },
models: {
"huggingface/Qwen/Qwen2.5-7B-Instruct": { alias: "Qwen2.5 7B" },
"huggingface/Qwen/Qwen2.5-7B-Instruct:cheapest": { alias: "Qwen2.5 7B (cheap)" },
"huggingface/deepseek-ai/DeepSeek-R1:fastest": { alias: "DeepSeek R1 (fast)" },
"huggingface/meta-llama/Llama-3.1-8B-Instruct": { alias: "Llama 3.1 8B" },
},
},
},
}
```
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Overview of all providers, model refs, and failover behavior.
</Card>
<Card title="Model selection" href="/concepts/models" icon="brain">
How to choose and configure models.
</Card>
<Card title="Inference Providers docs" href="https://huggingface.co/docs/inference-providers" icon="book">
Official Hugging Face Inference Providers documentation.
</Card>
<Card title="Configuration" href="/gateway/configuration" icon="gear">
Full config reference.
</Card>
</CardGroup>

91
openclaw/docs/providers/index.md Normal file
View file

@ -0,0 +1,91 @@
---
summary: "Model providers (LLMs) supported by OpenClaw"
read_when:
- You want to choose a model provider
- You need a quick overview of supported LLM backends
title: "Provider Directory"
---
# Model Providers
OpenClaw can use many LLM providers. Pick a provider, authenticate, then set the
default model as `provider/model`.
Looking for chat channel docs (WhatsApp/Telegram/Discord/Slack/Mattermost (plugin)/etc.)? See [Channels](/channels).
## Quick start
1. Authenticate with the provider (usually via `openclaw onboard`).
2. Set the default model:
```json5
{
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```
## Provider docs
- [Alibaba Model Studio](/providers/alibaba)
- [Amazon Bedrock](/providers/bedrock)
- [Anthropic (API + Claude CLI)](/providers/anthropic)
- [Arcee AI (Trinity models)](/providers/arcee)
- [BytePlus (International)](/concepts/model-providers#byteplus-international)
- [Chutes](/providers/chutes)
- [ComfyUI](/providers/comfy)
- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
- [DeepSeek](/providers/deepseek)
- [fal](/providers/fal)
- [Fireworks](/providers/fireworks)
- [GitHub Copilot](/providers/github-copilot)
- [GLM models](/providers/glm)
- [Google (Gemini)](/providers/google)
- [Groq (LPU inference)](/providers/groq)
- [Hugging Face (Inference)](/providers/huggingface)
- [inferrs (local models)](/providers/inferrs)
- [Kilocode](/providers/kilocode)
- [LiteLLM (unified gateway)](/providers/litellm)
- [LM Studio (local models)](/providers/lmstudio)
- [MiniMax](/providers/minimax)
- [Mistral](/providers/mistral)
- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
- [NVIDIA](/providers/nvidia)
- [Ollama (cloud + local models)](/providers/ollama)
- [OpenAI (API + Codex)](/providers/openai)
- [OpenCode](/providers/opencode)
- [OpenCode Go](/providers/opencode-go)
- [OpenRouter](/providers/openrouter)
- [Perplexity (web search)](/providers/perplexity-provider)
- [Qianfan](/providers/qianfan)
- [Qwen Cloud](/providers/qwen)
- [Runway](/providers/runway)
- [SGLang (local models)](/providers/sglang)
- [StepFun](/providers/stepfun)
- [Synthetic](/providers/synthetic)
- [Together AI](/providers/together)
- [Venice (Venice AI, privacy-focused)](/providers/venice)
- [Vercel AI Gateway](/providers/vercel-ai-gateway)
- [Vydra](/providers/vydra)
- [vLLM (local models)](/providers/vllm)
- [Volcengine (Doubao)](/providers/volcengine)
- [xAI](/providers/xai)
- [Xiaomi](/providers/xiaomi)
- [Z.AI](/providers/zai)
## Shared overview pages
- [Additional bundled variants](/providers/models#additional-bundled-provider-variants) - Anthropic Vertex, Copilot Proxy, and Gemini CLI OAuth
- [Image Generation](/tools/image-generation) - Shared `image_generate` tool, provider selection, and failover
- [Music Generation](/tools/music-generation) - Shared `music_generate` tool, provider selection, and failover
- [Video Generation](/tools/video-generation) - Shared `video_generate` tool, provider selection, and failover
## Transcription providers
- [Deepgram (audio transcription)](/providers/deepgram)
## Community tools
- [Claude Max API Proxy](/providers/claude-max-api-proxy) - Community proxy for Claude subscription credentials (verify Anthropic policy/terms before use)
For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
see [Model providers](/concepts/model-providers).

210
openclaw/docs/providers/inferrs.md Normal file
View file

@ -0,0 +1,210 @@
---
summary: "Run OpenClaw through inferrs (OpenAI-compatible local server)"
read_when:
- You want to run OpenClaw against a local inferrs server
- You are serving Gemma or another model through inferrs
- You need the exact OpenClaw compat flags for inferrs
title: "inferrs"
---
# inferrs
[inferrs](https://github.com/ericcurtin/inferrs) can serve local models behind an
OpenAI-compatible `/v1` API. OpenClaw works with `inferrs` through the generic
`openai-completions` path.
`inferrs` is currently best treated as a custom self-hosted OpenAI-compatible
backend, not a dedicated OpenClaw provider plugin.
## Getting started
<Steps>
<Step title="Start inferrs with a model">
```bash
inferrs serve google/gemma-4-E2B-it \
--host 127.0.0.1 \
--port 8080 \
--device metal
```
</Step>
<Step title="Verify the server is reachable">
```bash
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/models
```
</Step>
<Step title="Add an OpenClaw provider entry">
Add an explicit provider entry and point your default model at it. See the full config example below.
</Step>
</Steps>
## Full config example
This example uses Gemma 4 on a local `inferrs` server.
```json5
{
agents: {
defaults: {
model: { primary: "inferrs/google/gemma-4-E2B-it" },
models: {
"inferrs/google/gemma-4-E2B-it": {
alias: "Gemma 4 (inferrs)",
},
},
},
},
models: {
mode: "merge",
providers: {
inferrs: {
baseUrl: "http://127.0.0.1:8080/v1",
apiKey: "inferrs-local",
api: "openai-completions",
models: [
{
id: "google/gemma-4-E2B-it",
name: "Gemma 4 E2B (inferrs)",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 131072,
maxTokens: 4096,
compat: {
requiresStringContent: true,
},
},
],
},
},
},
}
```
## Advanced
<AccordionGroup>
<Accordion title="Why requiresStringContent matters">
Some `inferrs` Chat Completions routes accept only string
`messages[].content`, not structured content-part arrays.
<Warning>
If OpenClaw runs fail with an error like:
```text
messages[1].content: invalid type: sequence, expected a string
```
set `compat.requiresStringContent: true` in your model entry.
</Warning>
```json5
compat: {
requiresStringContent: true
}
```
OpenClaw will flatten pure text content parts into plain strings before sending
the request.
</Accordion>
<Accordion title="Gemma and tool-schema caveat">
Some current `inferrs` + Gemma combinations accept small direct
`/v1/chat/completions` requests but still fail on full OpenClaw agent-runtime
turns.
If that happens, try this first:
```json5
compat: {
requiresStringContent: true,
supportsTools: false
}
```
That disables OpenClaw's tool schema surface for the model and can reduce prompt
pressure on stricter local backends.
If tiny direct requests still work but normal OpenClaw agent turns continue to
crash inside `inferrs`, the remaining issue is usually upstream model/server
behavior rather than OpenClaw's transport layer.
</Accordion>
<Accordion title="Manual smoke test">
Once configured, test both layers:
```bash
curl http://127.0.0.1:8080/v1/chat/completions \
-H 'content-type: application/json' \
-d '{"model":"google/gemma-4-E2B-it","messages":[{"role":"user","content":"What is 2 + 2?"}],"stream":false}'
```
```bash
openclaw infer model run \
--model inferrs/google/gemma-4-E2B-it \
--prompt "What is 2 + 2? Reply with one short sentence." \
--json
```
If the first command works but the second fails, check the troubleshooting section below.
</Accordion>
<Accordion title="Proxy-style behavior">
`inferrs` is treated as a proxy-style OpenAI-compatible `/v1` backend, not a
native OpenAI endpoint.
- Native OpenAI-only request shaping does not apply here
- No `service_tier`, no Responses `store`, no prompt-cache hints, and no
OpenAI reasoning-compat payload shaping
- Hidden OpenClaw attribution headers (`originator`, `version`, `User-Agent`)
are not injected on custom `inferrs` base URLs
</Accordion>
</AccordionGroup>
## Troubleshooting
<AccordionGroup>
<Accordion title="curl /v1/models fails">
`inferrs` is not running, not reachable, or not bound to the expected
host/port. Make sure the server is started and listening on the address you
configured.
</Accordion>
<Accordion title="messages[].content expected a string">
Set `compat.requiresStringContent: true` in the model entry. See the
`requiresStringContent` section above for details.
</Accordion>
<Accordion title="Direct /v1/chat/completions calls pass but openclaw infer model run fails">
Try setting `compat.supportsTools: false` to disable the tool schema surface.
See the Gemma tool-schema caveat above.
</Accordion>
<Accordion title="inferrs still crashes on larger agent turns">
If OpenClaw no longer gets schema errors but `inferrs` still crashes on larger
agent turns, treat it as an upstream `inferrs` or model limitation. Reduce
prompt pressure or switch to a different local backend or model.
</Accordion>
</AccordionGroup>
<Tip>
For general help, see [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq).
</Tip>
## See also
<CardGroup cols={2}>
<Card title="Local models" href="/gateway/local-models" icon="server">
Running OpenClaw against local model servers.
</Card>
<Card title="Gateway troubleshooting" href="/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail" icon="wrench">
Debugging local OpenAI-compatible backends that pass probes but fail agent runs.
</Card>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Overview of all providers, model refs, and failover behavior.
</Card>
</CardGroup>

136
openclaw/docs/providers/kilocode.md Normal file
View file

@ -0,0 +1,136 @@
---
title: "Kilocode"
summary: "Use Kilo Gateway's unified API to access many models in OpenClaw"
read_when:
- You want a single API key for many LLMs
- You want to run models via Kilo Gateway in OpenClaw
---
# Kilo Gateway
Kilo Gateway provides a **unified API** that routes requests to many models behind a single
endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
| Property | Value |
| -------- | ---------------------------------- |
| Provider | `kilocode` |
| Auth | `KILOCODE_API_KEY` |
| API | OpenAI-compatible |
| Base URL | `https://api.kilo.ai/api/gateway/` |
## Getting started
<Steps>
<Step title="Create an account">
Go to [app.kilo.ai](https://app.kilo.ai), sign in or create an account, then navigate to API Keys and generate a new key.
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice kilocode-api-key
```
Or set the environment variable directly:
```bash
export KILOCODE_API_KEY="<your-kilocode-api-key>" # pragma: allowlist secret
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider kilocode
```
</Step>
</Steps>
## Default model
The default model is `kilocode/kilo/auto`, a provider-owned smart-routing
model managed by Kilo Gateway.
<Note>
OpenClaw treats `kilocode/kilo/auto` as the stable default ref, but does not
publish a source-backed task-to-upstream-model mapping for that route. Exact
upstream routing behind `kilocode/kilo/auto` is owned by Kilo Gateway, not
hard-coded in OpenClaw.
</Note>
## Available models
OpenClaw dynamically discovers available models from the Kilo Gateway at startup. Use
`/models kilocode` to see the full list of models available with your account.
Any model available on the gateway can be used with the `kilocode/` prefix:
| Model ref | Notes |
| -------------------------------------- | ---------------------------------- |
| `kilocode/kilo/auto` | Default — smart routing |
| `kilocode/anthropic/claude-sonnet-4` | Anthropic via Kilo |
| `kilocode/openai/gpt-5.4` | OpenAI via Kilo |
| `kilocode/google/gemini-3-pro-preview` | Google via Kilo |
| ...and many more | Use `/models kilocode` to list all |
<Tip>
At startup, OpenClaw queries `GET https://api.kilo.ai/api/gateway/models` and merges
discovered models ahead of the static fallback catalog. The bundled fallback always
includes `kilocode/kilo/auto` (`Kilo Auto`) with `input: ["text", "image"]`,
`reasoning: true`, `contextWindow: 1000000`, and `maxTokens: 128000`.
</Tip>
## Config example
```json5
{
env: { KILOCODE_API_KEY: "<your-kilocode-api-key>" }, // pragma: allowlist secret
agents: {
defaults: {
model: { primary: "kilocode/kilo/auto" },
},
},
}
```
<AccordionGroup>
<Accordion title="Transport and compatibility">
Kilo Gateway is documented in source as OpenRouter-compatible, so it stays on
the proxy-style OpenAI-compatible path rather than native OpenAI request shaping.
- Gemini-backed Kilo refs stay on the proxy-Gemini path, so OpenClaw keeps
Gemini thought-signature sanitation there without enabling native Gemini
replay validation or bootstrap rewrites.
- Kilo Gateway uses a Bearer token with your API key under the hood.
</Accordion>
<Accordion title="Stream wrapper and reasoning">
Kilo's shared stream wrapper adds the provider app header and normalizes
proxy reasoning payloads for supported concrete model refs.
<Warning>
`kilocode/kilo/auto` and other proxy-reasoning-unsupported hints skip reasoning
injection. If you need reasoning support, use a concrete model ref such as
`kilocode/anthropic/claude-sonnet-4`.
</Warning>
</Accordion>
<Accordion title="Troubleshooting">
- If model discovery fails at startup, OpenClaw falls back to the bundled static catalog containing `kilocode/kilo/auto`.
- Confirm your API key is valid and that your Kilo account has the desired models enabled.
- When the Gateway runs as a daemon, ensure `KILOCODE_API_KEY` is available to that process (for example in `~/.openclaw/.env` or via `env.shellEnv`).
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration" icon="gear">
Full OpenClaw configuration reference.
</Card>
<Card title="Kilo Gateway" href="https://app.kilo.ai" icon="arrow-up-right-from-square">
Kilo Gateway dashboard, API keys, and account management.
</Card>
</CardGroup>

197
openclaw/docs/providers/litellm.md Normal file
View file

@ -0,0 +1,197 @@
---
title: "LiteLLM"
summary: "Run OpenClaw through LiteLLM Proxy for unified model access and cost tracking"
read_when:
- You want to route OpenClaw through a LiteLLM proxy
- You need cost tracking, logging, or model routing through LiteLLM
---
# LiteLLM
[LiteLLM](https://litellm.ai) is an open-source LLM gateway that provides a unified API to 100+ model providers. Route OpenClaw through LiteLLM to get centralized cost tracking, logging, and the flexibility to switch backends without changing your OpenClaw config.
<Tip>
**Why use LiteLLM with OpenClaw?**
- **Cost tracking** — See exactly what OpenClaw spends across all models
- **Model routing** — Switch between Claude, GPT-4, Gemini, Bedrock without config changes
- **Virtual keys** — Create keys with spend limits for OpenClaw
- **Logging** — Full request/response logs for debugging
- **Fallbacks** — Automatic failover if your primary provider is down
</Tip>
## Quick start
<Tabs>
<Tab title="Onboarding (recommended)">
**Best for:** fastest path to a working LiteLLM setup.
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice litellm-api-key
```
</Step>
</Steps>
</Tab>
<Tab title="Manual setup">
**Best for:** full control over installation and config.
<Steps>
<Step title="Start LiteLLM Proxy">
```bash
pip install 'litellm[proxy]'
litellm --model claude-opus-4-6
```
</Step>
<Step title="Point OpenClaw to LiteLLM">
```bash
export LITELLM_API_KEY="your-litellm-key"
openclaw
```
That's it. OpenClaw now routes through LiteLLM.
</Step>
</Steps>
</Tab>
</Tabs>
## Configuration
### Environment variables
```bash
export LITELLM_API_KEY="sk-litellm-key"
```
### Config file
```json5
{
models: {
providers: {
litellm: {
baseUrl: "http://localhost:4000",
apiKey: "${LITELLM_API_KEY}",
api: "openai-completions",
models: [
{
id: "claude-opus-4-6",
name: "Claude Opus 4.6",
reasoning: true,
input: ["text", "image"],
contextWindow: 200000,
maxTokens: 64000,
},
{
id: "gpt-4o",
name: "GPT-4o",
reasoning: false,
input: ["text", "image"],
contextWindow: 128000,
maxTokens: 8192,
},
],
},
},
},
agents: {
defaults: {
model: { primary: "litellm/claude-opus-4-6" },
},
},
}
```
## Advanced topics
<AccordionGroup>
<Accordion title="Virtual keys">
Create a dedicated key for OpenClaw with spend limits:
```bash
curl -X POST "http://localhost:4000/key/generate" \
-H "Authorization: Bearer $LITELLM_MASTER_KEY" \
-H "Content-Type: application/json" \
-d '{
"key_alias": "openclaw",
"max_budget": 50.00,
"budget_duration": "monthly"
}'
```
Use the generated key as `LITELLM_API_KEY`.
</Accordion>
<Accordion title="Model routing">
LiteLLM can route model requests to different backends. Configure in your LiteLLM `config.yaml`:
```yaml
model_list:
- model_name: claude-opus-4-6
litellm_params:
model: claude-opus-4-6
api_key: os.environ/ANTHROPIC_API_KEY
- model_name: gpt-4o
litellm_params:
model: gpt-4o
api_key: os.environ/OPENAI_API_KEY
```
OpenClaw keeps requesting `claude-opus-4-6` — LiteLLM handles the routing.
</Accordion>
<Accordion title="Viewing usage">
Check LiteLLM's dashboard or API:
```bash
# Key info
curl "http://localhost:4000/key/info" \
-H "Authorization: Bearer sk-litellm-key"
# Spend logs
curl "http://localhost:4000/spend/logs" \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"
```
</Accordion>
<Accordion title="Proxy behavior notes">
- LiteLLM runs on `http://localhost:4000` by default
- OpenClaw connects through LiteLLM's proxy-style OpenAI-compatible `/v1`
endpoint
- Native OpenAI-only request shaping does not apply through LiteLLM:
no `service_tier`, no Responses `store`, no prompt-cache hints, and no
OpenAI reasoning-compat payload shaping
- Hidden OpenClaw attribution headers (`originator`, `version`, `User-Agent`)
are not injected on custom LiteLLM base URLs
</Accordion>
</AccordionGroup>
<Note>
For general provider configuration and failover behavior, see [Model Providers](/concepts/model-providers).
</Note>
## Related
<CardGroup cols={2}>
<Card title="LiteLLM Docs" href="https://docs.litellm.ai" icon="book">
Official LiteLLM documentation and API reference.
</Card>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Overview of all providers, model refs, and failover behavior.
</Card>
<Card title="Configuration" href="/gateway/configuration" icon="gear">
Full config reference.
</Card>
<Card title="Model selection" href="/concepts/models" icon="brain">
How to choose and configure models.
</Card>
</CardGroup>

159
openclaw/docs/providers/lmstudio.md Normal file
View file

@ -0,0 +1,159 @@
---
summary: "Run OpenClaw with LM Studio"
read_when:
- You want to run OpenClaw with open source models via LM Studio
- You want to set up and configure LM Studio
title: "LM Studio"
---
# LM Studio
LM Studio is a friendly yet powerful app for running open-weight models on your own hardware. It lets you run llama.cpp (GGUF) or MLX models (Apple Silicon). Comes in a GUI package or headless daemon (`llmster`). For product and setup docs, see [lmstudio.ai](https://lmstudio.ai/).
## Quick start
1. Install LM Studio (desktop) or `llmster` (headless), then start the local server:
```bash
curl -fsSL https://lmstudio.ai/install.sh | bash
```
2. Start the server
Make sure you either start the desktop app or run the daemon using the following command:
```bash
lms daemon up
```
```bash
lms server start --port 1234
```
If you are using the app, make sure you have JIT enabled for a smooth experience. Learn more in the [LM Studio JIT and TTL guide](https://lmstudio.ai/docs/developer/core/ttl-and-auto-evict).
3. OpenClaw requires an LM Studio token value. Set `LM_API_TOKEN`:
```bash
export LM_API_TOKEN="your-lm-studio-api-token"
```
If LM Studio authentication is disabled, use any non-empty token value:
```bash
export LM_API_TOKEN="placeholder-key"
```
For LM Studio auth setup details, see [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication).
4. Run onboarding and choose `LM Studio`:
```bash
openclaw onboard
```
5. In onboarding, use the `Default model` prompt to pick your LM Studio model.
You can also set or change it later:
```bash
openclaw models set lmstudio/qwen/qwen3.5-9b
```
LM Studio model keys follow a `author/model-name` format (e.g. `qwen/qwen3.5-9b`). OpenClaw
model refs prepend the provider name: `lmstudio/qwen/qwen3.5-9b`. You can find the exact key for
a model by running `curl http://localhost:1234/api/v1/models` and looking at the `key` field.
## Non-interactive onboarding
Use non-interactive onboarding when you want to script setup (CI, provisioning, remote bootstrap):
```bash
openclaw onboard \
--non-interactive \
--accept-risk \
--auth-choice lmstudio
```
Or specify base URL or model with API key:
```bash
openclaw onboard \
--non-interactive \
--accept-risk \
--auth-choice lmstudio \
--custom-base-url http://localhost:1234/v1 \
--lmstudio-api-key "$LM_API_TOKEN" \
--custom-model-id qwen/qwen3.5-9b
```
`--custom-model-id` takes the model key as returned by LM Studio (e.g. `qwen/qwen3.5-9b`), without
the `lmstudio/` provider prefix.
Non-interactive onboarding requires `--lmstudio-api-key` (or `LM_API_TOKEN` in env).
For unauthenticated LM Studio servers, any non-empty token value works.
`--custom-api-key` remains supported for compatibility, but `--lmstudio-api-key` is preferred for LM Studio.
This writes `models.providers.lmstudio`, sets the default model to
`lmstudio/<custom-model-id>`, and writes the `lmstudio:default` auth profile.
Interactive setup can prompt for an optional preferred load context length and applies it across the discovered LM Studio models it saves into config.
## Configuration
### Explicit configuration
```json5
{
models: {
providers: {
lmstudio: {
baseUrl: "http://localhost:1234/v1",
apiKey: "${LM_API_TOKEN}",
api: "openai-completions",
models: [
{
id: "qwen/qwen3-coder-next",
name: "Qwen 3 Coder Next",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 8192,
},
],
},
},
},
}
```
## Troubleshooting
### LM Studio not detected
Make sure LM Studio is running and that you set `LM_API_TOKEN` (for unauthenticated servers, any non-empty token value works):
```bash
# Start via desktop app, or headless:
lms server start --port 1234
```
Verify the API is accessible:
```bash
curl http://localhost:1234/api/v1/models
```
### Authentication errors (HTTP 401)
If setup reports HTTP 401, verify your API key:
- Check that `LM_API_TOKEN` matches the key configured in LM Studio.
- For LM Studio auth setup details, see [LM Studio Authentication](https://lmstudio.ai/docs/developer/core/authentication).
- If your server does not require authentication, use any non-empty token value for `LM_API_TOKEN`.
### Just-in-time model loading
LM Studio supports just-in-time (JIT) model loading, where models are loaded on first request. Make sure you have this enabled to avoid 'Model not loaded' errors.

466
openclaw/docs/providers/minimax.md Normal file
View file

@ -0,0 +1,466 @@
---
summary: "Use MiniMax models in OpenClaw"
read_when:
- You want MiniMax models in OpenClaw
- You need MiniMax setup guidance
title: "MiniMax"
---
# MiniMax
OpenClaw's MiniMax provider defaults to **MiniMax M2.7**.
MiniMax also provides:
- Bundled speech synthesis via T2A v2
- Bundled image understanding via `MiniMax-VL-01`
- Bundled music generation via `music-2.5+`
- Bundled `web_search` through the MiniMax Coding Plan search API
Provider split:
| Provider ID | Auth | Capabilities |
| ---------------- | ------- | --------------------------------------------------------------- |
| `minimax` | API key | Text, image generation, image understanding, speech, web search |
| `minimax-portal` | OAuth | Text, image generation, image understanding |
## Model lineup
| Model | Type | Description |
| ------------------------ | ---------------- | ---------------------------------------- |
| `MiniMax-M2.7` | Chat (reasoning) | Default hosted reasoning model |
| `MiniMax-M2.7-highspeed` | Chat (reasoning) | Faster M2.7 reasoning tier |
| `MiniMax-VL-01` | Vision | Image understanding model |
| `image-01` | Image generation | Text-to-image and image-to-image editing |
| `music-2.5+` | Music generation | Default music model |
| `music-2.5` | Music generation | Previous music generation tier |
| `music-2.0` | Music generation | Legacy music generation tier |
| `MiniMax-Hailuo-2.3` | Video generation | Text-to-video and image reference flows |
## Getting started
Choose your preferred auth method and follow the setup steps.
<Tabs>
<Tab title="OAuth (Coding Plan)">
**Best for:** quick setup with MiniMax Coding Plan via OAuth, no API key required.
<Tabs>
<Tab title="International">
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice minimax-global-oauth
```
This authenticates against `api.minimax.io`.
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider minimax-portal
```
</Step>
</Steps>
</Tab>
<Tab title="China">
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice minimax-cn-oauth
```
This authenticates against `api.minimaxi.com`.
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider minimax-portal
```
</Step>
</Steps>
</Tab>
</Tabs>
<Note>
OAuth setups use the `minimax-portal` provider id. Model refs follow the form `minimax-portal/MiniMax-M2.7`.
</Note>
<Tip>
Referral link for MiniMax Coding Plan (10% off): [MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
</Tip>
</Tab>
<Tab title="API key">
**Best for:** hosted MiniMax with Anthropic-compatible API.
<Tabs>
<Tab title="International">
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice minimax-global-api
```
This configures `api.minimax.io` as the base URL.
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider minimax
```
</Step>
</Steps>
</Tab>
<Tab title="China">
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice minimax-cn-api
```
This configures `api.minimaxi.com` as the base URL.
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider minimax
```
</Step>
</Steps>
</Tab>
</Tabs>
### Config example
```json5
{
env: { MINIMAX_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "minimax/MiniMax-M2.7" } } },
models: {
mode: "merge",
providers: {
minimax: {
baseUrl: "https://api.minimax.io/anthropic",
apiKey: "${MINIMAX_API_KEY}",
api: "anthropic-messages",
models: [
{
id: "MiniMax-M2.7",
name: "MiniMax M2.7",
reasoning: true,
input: ["text", "image"],
cost: { input: 0.3, output: 1.2, cacheRead: 0.06, cacheWrite: 0.375 },
contextWindow: 204800,
maxTokens: 131072,
},
{
id: "MiniMax-M2.7-highspeed",
name: "MiniMax M2.7 Highspeed",
reasoning: true,
input: ["text", "image"],
cost: { input: 0.6, output: 2.4, cacheRead: 0.06, cacheWrite: 0.375 },
contextWindow: 204800,
maxTokens: 131072,
},
],
},
},
},
}
```
<Warning>
On the Anthropic-compatible streaming path, OpenClaw disables MiniMax thinking by default unless you explicitly set `thinking` yourself. MiniMax's streaming endpoint emits `reasoning_content` in OpenAI-style delta chunks instead of native Anthropic thinking blocks, which can leak internal reasoning into visible output if left enabled implicitly.
</Warning>
<Note>
API-key setups use the `minimax` provider id. Model refs follow the form `minimax/MiniMax-M2.7`.
</Note>
</Tab>
</Tabs>
## Configure via `openclaw configure`
Use the interactive config wizard to set MiniMax without editing JSON:
<Steps>
<Step title="Launch the wizard">
```bash
openclaw configure
```
</Step>
<Step title="Select Model/auth">
Choose **Model/auth** from the menu.
</Step>
<Step title="Choose a MiniMax auth option">
Pick one of the available MiniMax options:
| Auth choice | Description |
| --- | --- |
| `minimax-global-oauth` | International OAuth (Coding Plan) |
| `minimax-cn-oauth` | China OAuth (Coding Plan) |
| `minimax-global-api` | International API key |
| `minimax-cn-api` | China API key |
</Step>
<Step title="Pick your default model">
Select your default model when prompted.
</Step>
</Steps>
## Capabilities
### Image generation
The MiniMax plugin registers the `image-01` model for the `image_generate` tool. It supports:
- **Text-to-image generation** with aspect ratio control
- **Image-to-image editing** (subject reference) with aspect ratio control
- Up to **9 output images** per request
- Up to **1 reference image** per edit request
- Supported aspect ratios: `1:1`, `16:9`, `4:3`, `3:2`, `2:3`, `3:4`, `9:16`, `21:9`
To use MiniMax for image generation, set it as the image generation provider:
```json5
{
agents: {
defaults: {
imageGenerationModel: { primary: "minimax/image-01" },
},
},
}
```
The plugin uses the same `MINIMAX_API_KEY` or OAuth auth as the text models. No additional configuration is needed if MiniMax is already set up.
Both `minimax` and `minimax-portal` register `image_generate` with the same
`image-01` model. API-key setups use `MINIMAX_API_KEY`; OAuth setups can use
the bundled `minimax-portal` auth path instead.
When onboarding or API-key setup writes explicit `models.providers.minimax`
entries, OpenClaw materializes `MiniMax-M2.7` and
`MiniMax-M2.7-highspeed` with `input: ["text", "image"]`.
The built-in bundled MiniMax text catalog itself stays text-only metadata until
that explicit provider config exists. Image understanding is exposed separately
through the plugin-owned `MiniMax-VL-01` media provider.
<Note>
See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
### Music generation
The bundled `minimax` plugin also registers music generation through the shared
`music_generate` tool.
- Default music model: `minimax/music-2.5+`
- Also supports `minimax/music-2.5` and `minimax/music-2.0`
- Prompt controls: `lyrics`, `instrumental`, `durationSeconds`
- Output format: `mp3`
- Session-backed runs detach through the shared task/status flow, including `action: "status"`
To use MiniMax as the default music provider:
```json5
{
agents: {
defaults: {
musicGenerationModel: {
primary: "minimax/music-2.5+",
},
},
},
}
```
<Note>
See [Music Generation](/tools/music-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
### Video generation
The bundled `minimax` plugin also registers video generation through the shared
`video_generate` tool.
- Default video model: `minimax/MiniMax-Hailuo-2.3`
- Modes: text-to-video and single-image reference flows
- Supports `aspectRatio` and `resolution`
To use MiniMax as the default video provider:
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "minimax/MiniMax-Hailuo-2.3",
},
},
},
}
```
<Note>
See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
### Image understanding
The MiniMax plugin registers image understanding separately from the text
catalog:
| Provider ID | Default image model |
| ---------------- | ------------------- |
| `minimax` | `MiniMax-VL-01` |
| `minimax-portal` | `MiniMax-VL-01` |
That is why automatic media routing can use MiniMax image understanding even
when the bundled text-provider catalog still shows text-only M2.7 chat refs.
### Web search
The MiniMax plugin also registers `web_search` through the MiniMax Coding Plan
search API.
- Provider id: `minimax`
- Structured results: titles, URLs, snippets, related queries
- Preferred env var: `MINIMAX_CODE_PLAN_KEY`
- Accepted env alias: `MINIMAX_CODING_API_KEY`
- Compatibility fallback: `MINIMAX_API_KEY` when it already points at a coding-plan token
- Region reuse: `plugins.entries.minimax.config.webSearch.region`, then `MINIMAX_API_HOST`, then MiniMax provider base URLs
- Search stays on provider id `minimax`; OAuth CN/global setup can still steer region indirectly through `models.providers.minimax-portal.baseUrl`
Config lives under `plugins.entries.minimax.config.webSearch.*`.
<Note>
See [MiniMax Search](/tools/minimax-search) for full web search configuration and usage.
</Note>
## Advanced configuration
<AccordionGroup>
<Accordion title="Configuration options">
| Option | Description |
| --- | --- |
| `models.providers.minimax.baseUrl` | Prefer `https://api.minimax.io/anthropic` (Anthropic-compatible); `https://api.minimax.io/v1` is optional for OpenAI-compatible payloads |
| `models.providers.minimax.api` | Prefer `anthropic-messages`; `openai-completions` is optional for OpenAI-compatible payloads |
| `models.providers.minimax.apiKey` | MiniMax API key (`MINIMAX_API_KEY`) |
| `models.providers.minimax.models` | Define `id`, `name`, `reasoning`, `contextWindow`, `maxTokens`, `cost` |
| `agents.defaults.models` | Alias models you want in the allowlist |
| `models.mode` | Keep `merge` if you want to add MiniMax alongside built-ins |
</Accordion>
<Accordion title="Thinking defaults">
On `api: "anthropic-messages"`, OpenClaw injects `thinking: { type: "disabled" }` unless thinking is already explicitly set in params/config.
This prevents MiniMax's streaming endpoint from emitting `reasoning_content` in OpenAI-style delta chunks, which would leak internal reasoning into visible output.
</Accordion>
<Accordion title="Fast mode">
`/fast on` or `params.fastMode: true` rewrites `MiniMax-M2.7` to `MiniMax-M2.7-highspeed` on the Anthropic-compatible stream path.
</Accordion>
<Accordion title="Fallback example">
**Best for:** keep your strongest latest-generation model as primary, fail over to MiniMax M2.7. Example below uses Opus as a concrete primary; swap to your preferred latest-gen primary model.
```json5
{
env: { MINIMAX_API_KEY: "sk-..." },
agents: {
defaults: {
models: {
"anthropic/claude-opus-4-6": { alias: "primary" },
"minimax/MiniMax-M2.7": { alias: "minimax" },
},
model: {
primary: "anthropic/claude-opus-4-6",
fallbacks: ["minimax/MiniMax-M2.7"],
},
},
},
}
```
</Accordion>
<Accordion title="Coding Plan usage details">
- Coding Plan usage API: `https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains` (requires a coding plan key).
- OpenClaw normalizes MiniMax coding-plan usage to the same `% left` display used by other providers. MiniMax's raw `usage_percent` / `usagePercent` fields are remaining quota, not consumed quota, so OpenClaw inverts them. Count-based fields win when present.
- When the API returns `model_remains`, OpenClaw prefers the chat-model entry, derives the window label from `start_time` / `end_time` when needed, and includes the selected model name in the plan label so coding-plan windows are easier to distinguish.
- Usage snapshots treat `minimax`, `minimax-cn`, and `minimax-portal` as the same MiniMax quota surface, and prefer stored MiniMax OAuth before falling back to Coding Plan key env vars.
</Accordion>
</AccordionGroup>
## Notes
- Model refs follow the auth path:
- API-key setup: `minimax/<model>`
- OAuth setup: `minimax-portal/<model>`
- Default chat model: `MiniMax-M2.7`
- Alternate chat model: `MiniMax-M2.7-highspeed`
- Onboarding and direct API-key setup write explicit model definitions with `input: ["text", "image"]` for both M2.7 variants
- The bundled provider catalog currently exposes the chat refs as text-only metadata until explicit MiniMax provider config exists
- Update pricing values in `models.json` if you need exact cost tracking
- Use `openclaw models list` to confirm the current provider id, then switch with `openclaw models set minimax/MiniMax-M2.7` or `openclaw models set minimax-portal/MiniMax-M2.7`
<Tip>
Referral link for MiniMax Coding Plan (10% off): [MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
</Tip>
<Note>
See [Model providers](/concepts/model-providers) for provider rules.
</Note>
## Troubleshooting
<AccordionGroup>
<Accordion title='"Unknown model: minimax/MiniMax-M2.7"'>
This usually means the **MiniMax provider is not configured** (no matching provider entry and no MiniMax auth profile/env key found). A fix for this detection is in **2026.1.12**. Fix by:
- Upgrading to **2026.1.12** (or run from source `main`), then restarting the gateway.
- Running `openclaw configure` and selecting a **MiniMax** auth option, or
- Adding the matching `models.providers.minimax` or `models.providers.minimax-portal` block manually, or
- Setting `MINIMAX_API_KEY`, `MINIMAX_OAUTH_TOKEN`, or a MiniMax auth profile so the matching provider can be injected.
Make sure the model id is **case-sensitive**:
- API-key path: `minimax/MiniMax-M2.7` or `minimax/MiniMax-M2.7-highspeed`
- OAuth path: `minimax-portal/MiniMax-M2.7` or `minimax-portal/MiniMax-M2.7-highspeed`
Then recheck with:
```bash
openclaw models list
```
</Accordion>
</AccordionGroup>
<Note>
More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq).
</Note>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Image generation" href="/tools/image-generation" icon="image">
Shared image tool parameters and provider selection.
</Card>
<Card title="Music generation" href="/tools/music-generation" icon="music">
Shared music tool parameters and provider selection.
</Card>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video tool parameters and provider selection.
</Card>
<Card title="MiniMax Search" href="/tools/minimax-search" icon="magnifying-glass">
Web search configuration via MiniMax Coding Plan.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
General troubleshooting and FAQ.
</Card>
</CardGroup>

134
openclaw/docs/providers/mistral.md Normal file
View file

@ -0,0 +1,134 @@
---
summary: "Use Mistral models and Voxtral transcription with OpenClaw"
read_when:
- You want to use Mistral models in OpenClaw
- You need Mistral API key onboarding and model refs
title: "Mistral"
---
# Mistral
OpenClaw supports Mistral for both text/image model routing (`mistral/...`) and
audio transcription via Voxtral in media understanding.
Mistral can also be used for memory embeddings (`memorySearch.provider = "mistral"`).
- Provider: `mistral`
- Auth: `MISTRAL_API_KEY`
- API: Mistral Chat Completions (`https://api.mistral.ai/v1`)
## Getting started
<Steps>
<Step title="Get your API key">
Create an API key in the [Mistral Console](https://console.mistral.ai/).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice mistral-api-key
```
Or pass the key directly:
```bash
openclaw onboard --mistral-api-key "$MISTRAL_API_KEY"
```
</Step>
<Step title="Set a default model">
```json5
{
env: { MISTRAL_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "mistral/mistral-large-latest" } } },
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider mistral
```
</Step>
</Steps>
## Built-in LLM catalog
OpenClaw currently ships this bundled Mistral catalog:
| Model ref | Input | Context | Max output | Notes |
| -------------------------------- | ----------- | ------- | ---------- | ---------------------------------------------------------------- |
| `mistral/mistral-large-latest` | text, image | 262,144 | 16,384 | Default model |
| `mistral/mistral-medium-2508` | text, image | 262,144 | 8,192 | Mistral Medium 3.1 |
| `mistral/mistral-small-latest` | text, image | 128,000 | 16,384 | Mistral Small 4; adjustable reasoning via API `reasoning_effort` |
| `mistral/pixtral-large-latest` | text, image | 128,000 | 32,768 | Pixtral |
| `mistral/codestral-latest` | text | 256,000 | 4,096 | Coding |
| `mistral/devstral-medium-latest` | text | 262,144 | 32,768 | Devstral 2 |
| `mistral/magistral-small` | text | 128,000 | 40,000 | Reasoning-enabled |
## Audio transcription (Voxtral)
Use Voxtral for audio transcription through the media understanding pipeline.
```json5
{
tools: {
media: {
audio: {
enabled: true,
models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
},
},
},
}
```
<Tip>
The media transcription path uses `/v1/audio/transcriptions`. The default audio model for Mistral is `voxtral-mini-latest`.
</Tip>
## Advanced configuration
<AccordionGroup>
<Accordion title="Adjustable reasoning (mistral-small-latest)">
`mistral/mistral-small-latest` maps to Mistral Small 4 and supports [adjustable reasoning](https://docs.mistral.ai/capabilities/reasoning/adjustable) on the Chat Completions API via `reasoning_effort` (`none` minimizes extra thinking in the output; `high` surfaces full thinking traces before the final answer).
OpenClaw maps the session **thinking** level to Mistral's API:
| OpenClaw thinking level | Mistral `reasoning_effort` |
| ------------------------------------------------ | -------------------------- |
| **off** / **minimal** | `none` |
| **low** / **medium** / **high** / **xhigh** / **adaptive** | `high` |
<Note>
Other bundled Mistral catalog models do not use this parameter. Keep using `magistral-*` models when you want Mistral's native reasoning-first behavior.
</Note>
</Accordion>
<Accordion title="Memory embeddings">
Mistral can serve memory embeddings via `/v1/embeddings` (default model: `mistral-embed`).
```json5
{
memorySearch: { provider: "mistral" },
}
```
</Accordion>
<Accordion title="Auth and base URL">
- Mistral auth uses `MISTRAL_API_KEY`.
- Provider base URL defaults to `https://api.mistral.ai/v1`.
- Onboarding default model is `mistral/mistral-large-latest`.
- Z.AI uses Bearer auth with your API key.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Media understanding" href="/tools/media-understanding" icon="microphone">
Audio transcription setup and provider selection.
</Card>
</CardGroup>

60
openclaw/docs/providers/models.md Normal file
View file

@ -0,0 +1,60 @@
---
summary: "Model providers (LLMs) supported by OpenClaw"
read_when:
- You want to choose a model provider
- You want quick setup examples for LLM auth + model selection
title: "Model Provider Quickstart"
---
# Model Providers
OpenClaw can use many LLM providers. Pick one, authenticate, then set the default
model as `provider/model`.
## Quick start (two steps)
1. Authenticate with the provider (usually via `openclaw onboard`).
2. Set the default model:
```json5
{
agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}
```
## Supported providers (starter set)
- [Alibaba Model Studio](/providers/alibaba)
- [Anthropic (API + Claude CLI)](/providers/anthropic)
- [Amazon Bedrock](/providers/bedrock)
- [BytePlus (International)](/concepts/model-providers#byteplus-international)
- [Chutes](/providers/chutes)
- [ComfyUI](/providers/comfy)
- [Cloudflare AI Gateway](/providers/cloudflare-ai-gateway)
- [fal](/providers/fal)
- [Fireworks](/providers/fireworks)
- [GLM models](/providers/glm)
- [MiniMax](/providers/minimax)
- [Mistral](/providers/mistral)
- [Moonshot AI (Kimi + Kimi Coding)](/providers/moonshot)
- [OpenAI (API + Codex)](/providers/openai)
- [OpenCode (Zen + Go)](/providers/opencode)
- [OpenRouter](/providers/openrouter)
- [Qianfan](/providers/qianfan)
- [Qwen](/providers/qwen)
- [Runway](/providers/runway)
- [StepFun](/providers/stepfun)
- [Synthetic](/providers/synthetic)
- [Vercel AI Gateway](/providers/vercel-ai-gateway)
- [Venice (Venice AI)](/providers/venice)
- [xAI](/providers/xai)
- [Z.AI](/providers/zai)
## Additional bundled provider variants
- `anthropic-vertex` - implicit Anthropic on Google Vertex support when Vertex credentials are available; no separate onboarding auth choice
- `copilot-proxy` - local VS Code Copilot Proxy bridge; use `openclaw onboard --auth-choice copilot-proxy`
- `google-gemini-cli` - unofficial Gemini CLI OAuth flow; requires a local `gemini` install (`brew install gemini-cli` or `npm install -g @google/gemini-cli`); default model `google-gemini-cli/gemini-3-flash-preview`; use `openclaw onboard --auth-choice google-gemini-cli` or `openclaw models auth login --provider google-gemini-cli --set-default`
For the full provider catalog (xAI, Groq, Mistral, etc.) and advanced configuration,
see [Model providers](/concepts/model-providers).

331
openclaw/docs/providers/moonshot.md Normal file
View file

@ -0,0 +1,331 @@
---
summary: "Configure Moonshot K2 vs Kimi Coding (separate providers + keys)"
read_when:
- You want Moonshot K2 (Moonshot Open Platform) vs Kimi Coding setup
- You need to understand separate endpoints, keys, and model refs
- You want copy/paste config for either provider
title: "Moonshot AI"
---
# Moonshot AI (Kimi)
Moonshot provides the Kimi API with OpenAI-compatible endpoints. Configure the
provider and set the default model to `moonshot/kimi-k2.5`, or use
Kimi Coding with `kimi/kimi-code`.
<Warning>
Moonshot and Kimi Coding are **separate providers**. Keys are not interchangeable, endpoints differ, and model refs differ (`moonshot/...` vs `kimi/...`).
</Warning>
## Built-in model catalog
[//]: # "moonshot-kimi-k2-ids:start"
| Model ref | Name | Reasoning | Input | Context | Max output |
| --------------------------------- | ---------------------- | --------- | ----------- | ------- | ---------- |
| `moonshot/kimi-k2.5` | Kimi K2.5 | No | text, image | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking` | Kimi K2 Thinking | Yes | text | 262,144 | 262,144 |
| `moonshot/kimi-k2-thinking-turbo` | Kimi K2 Thinking Turbo | Yes | text | 262,144 | 262,144 |
| `moonshot/kimi-k2-turbo` | Kimi K2 Turbo | No | text | 256,000 | 16,384 |
[//]: # "moonshot-kimi-k2-ids:end"
## Getting started
Choose your provider and follow the setup steps.
<Tabs>
<Tab title="Moonshot API">
**Best for:** Kimi K2 models via the Moonshot Open Platform.
<Steps>
<Step title="Choose your endpoint region">
| Auth choice | Endpoint | Region |
| ---------------------- | ------------------------------ | ------------- |
| `moonshot-api-key` | `https://api.moonshot.ai/v1` | International |
| `moonshot-api-key-cn` | `https://api.moonshot.cn/v1` | China |
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice moonshot-api-key
```
Or for the China endpoint:
```bash
openclaw onboard --auth-choice moonshot-api-key-cn
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "moonshot/kimi-k2.5" },
},
},
}
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider moonshot
```
</Step>
</Steps>
### Config example
```json5
{
env: { MOONSHOT_API_KEY: "sk-..." },
agents: {
defaults: {
model: { primary: "moonshot/kimi-k2.5" },
models: {
// moonshot-kimi-k2-aliases:start
"moonshot/kimi-k2.5": { alias: "Kimi K2.5" },
"moonshot/kimi-k2-thinking": { alias: "Kimi K2 Thinking" },
"moonshot/kimi-k2-thinking-turbo": { alias: "Kimi K2 Thinking Turbo" },
"moonshot/kimi-k2-turbo": { alias: "Kimi K2 Turbo" },
// moonshot-kimi-k2-aliases:end
},
},
},
models: {
mode: "merge",
providers: {
moonshot: {
baseUrl: "https://api.moonshot.ai/v1",
apiKey: "${MOONSHOT_API_KEY}",
api: "openai-completions",
models: [
// moonshot-kimi-k2-models:start
{
id: "kimi-k2.5",
name: "Kimi K2.5",
reasoning: false,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 262144,
},
{
id: "kimi-k2-thinking",
name: "Kimi K2 Thinking",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 262144,
},
{
id: "kimi-k2-thinking-turbo",
name: "Kimi K2 Thinking Turbo",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 262144,
},
{
id: "kimi-k2-turbo",
name: "Kimi K2 Turbo",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 256000,
maxTokens: 16384,
},
// moonshot-kimi-k2-models:end
],
},
},
},
}
```
</Tab>
<Tab title="Kimi Coding">
**Best for:** code-focused tasks via the Kimi Coding endpoint.
<Note>
Kimi Coding uses a different API key and provider prefix (`kimi/...`) than Moonshot (`moonshot/...`). Legacy model ref `kimi/k2p5` remains accepted as a compatibility id.
</Note>
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice kimi-code-api-key
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "kimi/kimi-code" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider kimi
```
</Step>
</Steps>
### Config example
```json5
{
env: { KIMI_API_KEY: "sk-..." },
agents: {
defaults: {
model: { primary: "kimi/kimi-code" },
models: {
"kimi/kimi-code": { alias: "Kimi" },
},
},
},
}
```
</Tab>
</Tabs>
## Kimi web search
OpenClaw also ships **Kimi** as a `web_search` provider, backed by Moonshot web
search.
<Steps>
<Step title="Run interactive web search setup">
```bash
openclaw configure --section web
```
Choose **Kimi** in the web-search section to store
`plugins.entries.moonshot.config.webSearch.*`.
</Step>
<Step title="Configure the web search region and model">
Interactive setup prompts for:
| Setting | Options |
| ------------------- | -------------------------------------------------------------------- |
| API region | `https://api.moonshot.ai/v1` (international) or `https://api.moonshot.cn/v1` (China) |
| Web search model | Defaults to `kimi-k2.5` |
</Step>
</Steps>
Config lives under `plugins.entries.moonshot.config.webSearch`:
```json5
{
plugins: {
entries: {
moonshot: {
config: {
webSearch: {
apiKey: "sk-...", // or use KIMI_API_KEY / MOONSHOT_API_KEY
baseUrl: "https://api.moonshot.ai/v1",
model: "kimi-k2.5",
},
},
},
},
},
tools: {
web: {
search: {
provider: "kimi",
},
},
},
}
```
## Advanced
<AccordionGroup>
<Accordion title="Native thinking mode">
Moonshot Kimi supports binary native thinking:
- `thinking: { type: "enabled" }`
- `thinking: { type: "disabled" }`
Configure it per model via `agents.defaults.models.<provider/model>.params`:
```json5
{
agents: {
defaults: {
models: {
"moonshot/kimi-k2.5": {
params: {
thinking: { type: "disabled" },
},
},
},
},
},
}
```
OpenClaw also maps runtime `/think` levels for Moonshot:
| `/think` level | Moonshot behavior |
| -------------------- | -------------------------- |
| `/think off` | `thinking.type=disabled` |
| Any non-off level | `thinking.type=enabled` |
<Warning>
When Moonshot thinking is enabled, `tool_choice` must be `auto` or `none`. OpenClaw normalizes incompatible `tool_choice` values to `auto` for compatibility.
</Warning>
</Accordion>
<Accordion title="Streaming usage compatibility">
Native Moonshot endpoints (`https://api.moonshot.ai/v1` and
`https://api.moonshot.cn/v1`) advertise streaming usage compatibility on the
shared `openai-completions` transport. OpenClaw keys that off endpoint
capabilities, so compatible custom provider ids targeting the same native
Moonshot hosts inherit the same streaming-usage behavior.
</Accordion>
<Accordion title="Endpoint and model ref reference">
| Provider | Model ref prefix | Endpoint | Auth env var |
| ---------- | ---------------- | ----------------------------- | ------------------- |
| Moonshot | `moonshot/` | `https://api.moonshot.ai/v1` | `MOONSHOT_API_KEY` |
| Moonshot CN| `moonshot/` | `https://api.moonshot.cn/v1` | `MOONSHOT_API_KEY` |
| Kimi Coding| `kimi/` | Kimi Coding endpoint | `KIMI_API_KEY` |
| Web search | N/A | Same as Moonshot API region | `KIMI_API_KEY` or `MOONSHOT_API_KEY` |
- Kimi web search uses `KIMI_API_KEY` or `MOONSHOT_API_KEY`, and defaults to `https://api.moonshot.ai/v1` with model `kimi-k2.5`.
- Override pricing and context metadata in `models.providers` if needed.
- If Moonshot publishes different context limits for a model, adjust `contextWindow` accordingly.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Web search" href="/tools/web-search" icon="magnifying-glass">
Configuring web search providers including Kimi.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config schema for providers, models, and plugins.
</Card>
<Card title="Moonshot Open Platform" href="https://platform.moonshot.ai" icon="globe">
Moonshot API key management and documentation.
</Card>
</CardGroup>

103
openclaw/docs/providers/nvidia.md Normal file
View file

@ -0,0 +1,103 @@
---
summary: "Use NVIDIA's OpenAI-compatible API in OpenClaw"
read_when:
- You want to use open models in OpenClaw for free
- You need NVIDIA_API_KEY setup
title: "NVIDIA"
---
# NVIDIA
NVIDIA provides an OpenAI-compatible API at `https://integrate.api.nvidia.com/v1` for
open models for free. Authenticate with an API key from
[build.nvidia.com](https://build.nvidia.com/settings/api-keys).
## Getting started
<Steps>
<Step title="Get your API key">
Create an API key at [build.nvidia.com](https://build.nvidia.com/settings/api-keys).
</Step>
<Step title="Export the key and run onboarding">
```bash
export NVIDIA_API_KEY="nvapi-..."
openclaw onboard --auth-choice skip
```
</Step>
<Step title="Set an NVIDIA model">
```bash
openclaw models set nvidia/nvidia/nemotron-3-super-120b-a12b
```
</Step>
</Steps>
<Warning>
If you pass `--token` instead of the env var, the value lands in shell history and
`ps` output. Prefer the `NVIDIA_API_KEY` environment variable when possible.
</Warning>
## Config example
```json5
{
env: { NVIDIA_API_KEY: "nvapi-..." },
models: {
providers: {
nvidia: {
baseUrl: "https://integrate.api.nvidia.com/v1",
api: "openai-completions",
},
},
},
agents: {
defaults: {
model: { primary: "nvidia/nvidia/nemotron-3-super-120b-a12b" },
},
},
}
```
## Built-in catalog
| Model ref | Name | Context | Max output |
| ------------------------------------------ | ---------------------------- | ------- | ---------- |
| `nvidia/nvidia/nemotron-3-super-120b-a12b` | NVIDIA Nemotron 3 Super 120B | 262,144 | 8,192 |
| `nvidia/moonshotai/kimi-k2.5` | Kimi K2.5 | 262,144 | 8,192 |
| `nvidia/minimaxai/minimax-m2.5` | Minimax M2.5 | 196,608 | 8,192 |
| `nvidia/z-ai/glm5` | GLM 5 | 202,752 | 8,192 |
## Advanced notes
<AccordionGroup>
<Accordion title="Auto-enable behavior">
The provider auto-enables when the `NVIDIA_API_KEY` environment variable is set.
No explicit provider config is required beyond the key.
</Accordion>
<Accordion title="Catalog and pricing">
The bundled catalog is static. Costs default to `0` in source since NVIDIA
currently offers free API access for the listed models.
</Accordion>
<Accordion title="OpenAI-compatible endpoint">
NVIDIA uses the standard `/v1` completions endpoint. Any OpenAI-compatible
tooling should work out of the box with the NVIDIA base URL.
</Accordion>
</AccordionGroup>
<Tip>
NVIDIA models are currently free to use. Check
[build.nvidia.com](https://build.nvidia.com/) for the latest availability and
rate-limit details.
</Tip>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config reference for agents, models, and providers.
</Card>
</CardGroup>

483
openclaw/docs/providers/ollama.md Normal file
View file

@ -0,0 +1,483 @@
---
summary: "Run OpenClaw with Ollama (cloud and local models)"
read_when:
- You want to run OpenClaw with cloud or local models via Ollama
- You need Ollama setup and configuration guidance
title: "Ollama"
---
# Ollama
OpenClaw integrates with Ollama's native API (`/api/chat`) for hosted cloud models and local/self-hosted Ollama servers. You can use Ollama in three modes: `Cloud + Local` through a reachable Ollama host, `Cloud only` against `https://ollama.com`, or `Local only` against a reachable Ollama host.
<Warning>
**Remote Ollama users**: Do not use the `/v1` OpenAI-compatible URL (`http://host:11434/v1`) with OpenClaw. This breaks tool calling and models may output raw tool JSON as plain text. Use the native Ollama API URL instead: `baseUrl: "http://host:11434"` (no `/v1`).
</Warning>
## Getting started
Choose your preferred setup method and mode.
<Tabs>
<Tab title="Onboarding (recommended)">
**Best for:** fastest path to a working Ollama cloud or local setup.
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard
```
Select **Ollama** from the provider list.
</Step>
<Step title="Choose your mode">
- **Cloud + Local** — local Ollama host plus cloud models routed through that host
- **Cloud only** — hosted Ollama models via `https://ollama.com`
- **Local only** — local models only
</Step>
<Step title="Select a model">
`Cloud only` prompts for `OLLAMA_API_KEY` and suggests hosted cloud defaults. `Cloud + Local` and `Local only` ask for an Ollama base URL, discover available models, and auto-pull the selected local model if it is not available yet. `Cloud + Local` also checks whether that Ollama host is signed in for cloud access.
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider ollama
```
</Step>
</Steps>
### Non-interactive mode
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--accept-risk
```
Optionally specify a custom base URL or model:
```bash
openclaw onboard --non-interactive \
--auth-choice ollama \
--custom-base-url "http://ollama-host:11434" \
--custom-model-id "qwen3.5:27b" \
--accept-risk
```
</Tab>
<Tab title="Manual setup">
**Best for:** full control over cloud or local setup.
<Steps>
<Step title="Choose cloud or local">
- **Cloud + Local**: install Ollama, sign in with `ollama signin`, and route cloud requests through that host
- **Cloud only**: use `https://ollama.com` with an `OLLAMA_API_KEY`
- **Local only**: install Ollama from [ollama.com/download](https://ollama.com/download)
</Step>
<Step title="Pull a local model (local only)">
```bash
ollama pull gemma4
# or
ollama pull gpt-oss:20b
# or
ollama pull llama3.3
```
</Step>
<Step title="Enable Ollama for OpenClaw">
For `Cloud only`, use your real `OLLAMA_API_KEY`. For host-backed setups, any placeholder value works:
```bash
# Cloud
export OLLAMA_API_KEY="your-ollama-api-key"
# Local-only
export OLLAMA_API_KEY="ollama-local"
# Or configure in your config file
openclaw config set models.providers.ollama.apiKey "OLLAMA_API_KEY"
```
</Step>
<Step title="Inspect and set your model">
```bash
openclaw models list
openclaw models set ollama/gemma4
```
Or set the default in config:
```json5
{
agents: {
defaults: {
model: { primary: "ollama/gemma4" },
},
},
}
```
</Step>
</Steps>
</Tab>
</Tabs>
## Cloud models
<Tabs>
<Tab title="Cloud + Local">
`Cloud + Local` uses a reachable Ollama host as the control point for both local and cloud models. This is Ollama's preferred hybrid flow.
Use **Cloud + Local** during setup. OpenClaw prompts for the Ollama base URL, discovers local models from that host, and checks whether the host is signed in for cloud access with `ollama signin`. When the host is signed in, OpenClaw also suggests hosted cloud defaults such as `kimi-k2.5:cloud`, `minimax-m2.7:cloud`, and `glm-5.1:cloud`.
If the host is not signed in yet, OpenClaw keeps the setup local-only until you run `ollama signin`.
</Tab>
<Tab title="Cloud only">
`Cloud only` runs against Ollama's hosted API at `https://ollama.com`.
Use **Cloud only** during setup. OpenClaw prompts for `OLLAMA_API_KEY`, sets `baseUrl: "https://ollama.com"`, and seeds the hosted cloud model list. This path does **not** require a local Ollama server or `ollama signin`.
</Tab>
<Tab title="Local only">
In local-only mode, OpenClaw discovers models from the configured Ollama instance. This path is for local or self-hosted Ollama servers.
OpenClaw currently suggests `gemma4` as the local default.
</Tab>
</Tabs>
## Model discovery (implicit provider)
When you set `OLLAMA_API_KEY` (or an auth profile) and **do not** define `models.providers.ollama`, OpenClaw discovers models from the local Ollama instance at `http://127.0.0.1:11434`.
| Behavior | Detail |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Catalog query | Queries `/api/tags` |
| Capability detection | Uses best-effort `/api/show` lookups to read `contextWindow` and detect capabilities (including vision) |
| Vision models | Models with a `vision` capability reported by `/api/show` are marked as image-capable (`input: ["text", "image"]`), so OpenClaw auto-injects images into the prompt |
| Reasoning detection | Marks `reasoning` with a model-name heuristic (`r1`, `reasoning`, `think`) |
| Token limits | Sets `maxTokens` to the default Ollama max-token cap used by OpenClaw |
| Costs | Sets all costs to `0` |
This avoids manual model entries while keeping the catalog aligned with the local Ollama instance.
```bash
# See what models are available
ollama list
openclaw models list
```
To add a new model, simply pull it with Ollama:
```bash
ollama pull mistral
```
The new model will be automatically discovered and available to use.
<Note>
If you set `models.providers.ollama` explicitly, auto-discovery is skipped and you must define models manually. See the explicit config section below.
</Note>
## Configuration
<Tabs>
<Tab title="Basic (implicit discovery)">
The simplest local-only enablement path is via environment variable:
```bash
export OLLAMA_API_KEY="ollama-local"
```
<Tip>
If `OLLAMA_API_KEY` is set, you can omit `apiKey` in the provider entry and OpenClaw will fill it for availability checks.
</Tip>
</Tab>
<Tab title="Explicit (manual models)">
Use explicit config when you want hosted cloud setup, Ollama runs on another host/port, you want to force specific context windows or model lists, or you want fully manual model definitions.
```json5
{
models: {
providers: {
ollama: {
baseUrl: "https://ollama.com",
apiKey: "OLLAMA_API_KEY",
api: "ollama",
models: [
{
id: "kimi-k2.5:cloud",
name: "kimi-k2.5:cloud",
reasoning: false,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 8192
}
]
}
}
}
}
```
</Tab>
<Tab title="Custom base URL">
If Ollama is running on a different host or port (explicit config disables auto-discovery, so define models manually):
```json5
{
models: {
providers: {
ollama: {
apiKey: "ollama-local",
baseUrl: "http://ollama-host:11434", // No /v1 - use native Ollama API URL
api: "ollama", // Set explicitly to guarantee native tool-calling behavior
},
},
},
}
```
<Warning>
Do not add `/v1` to the URL. The `/v1` path uses OpenAI-compatible mode, where tool calling is not reliable. Use the base Ollama URL without a path suffix.
</Warning>
</Tab>
</Tabs>
### Model selection
Once configured, all your Ollama models are available:
```json5
{
agents: {
defaults: {
model: {
primary: "ollama/gpt-oss:20b",
fallbacks: ["ollama/llama3.3", "ollama/qwen2.5-coder:32b"],
},
},
},
}
```
## Ollama Web Search
OpenClaw supports **Ollama Web Search** as a bundled `web_search` provider.
| Property | Detail |
| ----------- | ----------------------------------------------------------------------------------------------------------------- |
| Host | Uses your configured Ollama host (`models.providers.ollama.baseUrl` when set, otherwise `http://127.0.0.1:11434`) |
| Auth | Key-free |
| Requirement | Ollama must be running and signed in with `ollama signin` |
Choose **Ollama Web Search** during `openclaw onboard` or `openclaw configure --section web`, or set:
```json5
{
tools: {
web: {
search: {
provider: "ollama",
},
},
},
}
```
<Note>
For the full setup and behavior details, see [Ollama Web Search](/tools/ollama-search).
</Note>
## Advanced configuration
<AccordionGroup>
<Accordion title="Legacy OpenAI-compatible mode">
<Warning>
**Tool calling is not reliable in OpenAI-compatible mode.** Use this mode only if you need OpenAI format for a proxy and do not depend on native tool calling behavior.
</Warning>
If you need to use the OpenAI-compatible endpoint instead (for example, behind a proxy that only supports OpenAI format), set `api: "openai-completions"` explicitly:
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: true, // default: true
apiKey: "ollama-local",
models: [...]
}
}
}
}
```
This mode may not support streaming and tool calling simultaneously. You may need to disable streaming with `params: { streaming: false }` in model config.
When `api: "openai-completions"` is used with Ollama, OpenClaw injects `options.num_ctx` by default so Ollama does not silently fall back to a 4096 context window. If your proxy/upstream rejects unknown `options` fields, disable this behavior:
```json5
{
models: {
providers: {
ollama: {
baseUrl: "http://ollama-host:11434/v1",
api: "openai-completions",
injectNumCtxForOpenAICompat: false,
apiKey: "ollama-local",
models: [...]
}
}
}
}
```
</Accordion>
<Accordion title="Context windows">
For auto-discovered models, OpenClaw uses the context window reported by Ollama when available, otherwise it falls back to the default Ollama context window used by OpenClaw.
You can override `contextWindow` and `maxTokens` in explicit provider config:
```json5
{
models: {
providers: {
ollama: {
models: [
{
id: "llama3.3",
contextWindow: 131072,
maxTokens: 65536,
}
]
}
}
}
}
```
</Accordion>
<Accordion title="Reasoning models">
OpenClaw treats models with names such as `deepseek-r1`, `reasoning`, or `think` as reasoning-capable by default.
```bash
ollama pull deepseek-r1:32b
```
No additional configuration is needed -- OpenClaw marks them automatically.
</Accordion>
<Accordion title="Model costs">
Ollama is free and runs locally, so all model costs are set to $0. This applies to both auto-discovered and manually defined models.
</Accordion>
<Accordion title="Memory embeddings">
The bundled Ollama plugin registers a memory embedding provider for
[memory search](/concepts/memory). It uses the configured Ollama base URL
and API key.
| Property | Value |
| ------------- | ------------------- |
| Default model | `nomic-embed-text` |
| Auto-pull | Yes — the embedding model is pulled automatically if not present locally |
To select Ollama as the memory search embedding provider:
```json5
{
agents: {
defaults: {
memorySearch: { provider: "ollama" },
},
},
}
```
</Accordion>
<Accordion title="Streaming configuration">
OpenClaw's Ollama integration uses the **native Ollama API** (`/api/chat`) by default, which fully supports streaming and tool calling simultaneously. No special configuration is needed.
<Tip>
If you need to use the OpenAI-compatible endpoint, see the "Legacy OpenAI-compatible mode" section above. Streaming and tool calling may not work simultaneously in that mode.
</Tip>
</Accordion>
</AccordionGroup>
## Troubleshooting
<AccordionGroup>
<Accordion title="Ollama not detected">
Make sure Ollama is running and that you set `OLLAMA_API_KEY` (or an auth profile), and that you did **not** define an explicit `models.providers.ollama` entry:
```bash
ollama serve
```
Verify that the API is accessible:
```bash
curl http://localhost:11434/api/tags
```
</Accordion>
<Accordion title="No models available">
If your model is not listed, either pull the model locally or define it explicitly in `models.providers.ollama`.
```bash
ollama list # See what's installed
ollama pull gemma4
ollama pull gpt-oss:20b
ollama pull llama3.3 # Or another model
```
</Accordion>
<Accordion title="Connection refused">
Check that Ollama is running on the correct port:
```bash
# Check if Ollama is running
ps aux | grep ollama
# Or restart Ollama
ollama serve
```
</Accordion>
</AccordionGroup>
<Note>
More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq).
</Note>
## Related
<CardGroup cols={2}>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Overview of all providers, model refs, and failover behavior.
</Card>
<Card title="Model selection" href="/concepts/models" icon="brain">
How to choose and configure models.
</Card>
<Card title="Ollama Web Search" href="/tools/ollama-search" icon="magnifying-glass">
Full setup and behavior details for Ollama-powered web search.
</Card>
<Card title="Configuration" href="/gateway/configuration" icon="gear">
Full config reference.
</Card>
</CardGroup>

544
openclaw/docs/providers/openai.md Normal file
View file

@ -0,0 +1,544 @@
---
summary: "Use OpenAI via API keys or Codex subscription in OpenClaw"
read_when:
- You want to use OpenAI models in OpenClaw
- You want Codex subscription auth instead of API keys
- You need stricter GPT-5 agent execution behavior
title: "OpenAI"
---
# OpenAI
OpenAI provides developer APIs for GPT models. OpenClaw supports two auth routes:
- **API key** — direct OpenAI Platform access with usage-based billing (`openai/*` models)
- **Codex subscription** — ChatGPT/Codex sign-in with subscription access (`openai-codex/*` models)
OpenAI explicitly supports subscription OAuth usage in external tools and workflows like OpenClaw.
## Getting started
Choose your preferred auth method and follow the setup steps.
<Tabs>
<Tab title="API key (OpenAI Platform)">
**Best for:** direct API access and usage-based billing.
<Steps>
<Step title="Get your API key">
Create or copy an API key from the [OpenAI Platform dashboard](https://platform.openai.com/api-keys).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice openai-api-key
```
Or pass the key directly:
```bash
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider openai
```
</Step>
</Steps>
### Route summary
| Model ref | Route | Auth |
|-----------|-------|------|
| `openai/gpt-5.4` | Direct OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-pro` | Direct OpenAI Platform API | `OPENAI_API_KEY` |
<Note>
ChatGPT/Codex sign-in is routed through `openai-codex/*`, not `openai/*`.
</Note>
### Config example
```json5
{
env: { OPENAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}
```
<Warning>
OpenClaw does **not** expose `openai/gpt-5.3-codex-spark` on the direct API path. Live OpenAI API requests reject that model. Spark is Codex-only.
</Warning>
</Tab>
<Tab title="Codex subscription">
**Best for:** using your ChatGPT/Codex subscription instead of a separate API key. Codex cloud requires ChatGPT sign-in.
<Steps>
<Step title="Run Codex OAuth">
```bash
openclaw onboard --auth-choice openai-codex
```
Or run OAuth directly:
```bash
openclaw models auth login --provider openai-codex
```
</Step>
<Step title="Set the default model">
```bash
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider openai-codex
```
</Step>
</Steps>
### Route summary
| Model ref | Route | Auth |
|-----------|-------|------|
| `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex sign-in |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex sign-in (entitlement-dependent) |
<Note>
This route is intentionally separate from `openai/gpt-5.4`. Use `openai/*` with an API key for direct Platform access, and `openai-codex/*` for Codex subscription access.
</Note>
### Config example
```json5
{
agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}
```
<Tip>
If onboarding reuses an existing Codex CLI login, those credentials stay managed by Codex CLI. On expiry, OpenClaw re-reads the external Codex source first and writes the refreshed credential back to Codex storage.
</Tip>
### Context window cap
OpenClaw treats model metadata and the runtime context cap as separate values.
For `openai-codex/gpt-5.4`:
- Native `contextWindow`: `1050000`
- Default runtime `contextTokens` cap: `272000`
The smaller default cap has better latency and quality characteristics in practice. Override it with `contextTokens`:
```json5
{
models: {
providers: {
"openai-codex": {
models: [{ id: "gpt-5.4", contextTokens: 160000 }],
},
},
},
}
```
<Note>
Use `contextWindow` to declare native model metadata. Use `contextTokens` to limit the runtime context budget.
</Note>
</Tab>
</Tabs>
## Image generation
The bundled `openai` plugin registers image generation through the `image_generate` tool.
| Capability | Value |
| ------------------------- | ---------------------------------- |
| Default model | `openai/gpt-image-1` |
| Max images per request | 4 |
| Edit mode | Enabled (up to 5 reference images) |
| Size overrides | Supported |
| Aspect ratio / resolution | Not forwarded to OpenAI Images API |
```json5
{
agents: {
defaults: {
imageGenerationModel: { primary: "openai/gpt-image-1" },
},
},
}
```
<Note>
See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
## Video generation
The bundled `openai` plugin registers video generation through the `video_generate` tool.
| Capability | Value |
| ---------------- | --------------------------------------------------------------------------------- |
| Default model | `openai/sora-2` |
| Modes | Text-to-video, image-to-video, single-video edit |
| Reference inputs | 1 image or 1 video |
| Size overrides | Supported |
| Other overrides | `aspectRatio`, `resolution`, `audio`, `watermark` are ignored with a tool warning |
```json5
{
agents: {
defaults: {
videoGenerationModel: { primary: "openai/sora-2" },
},
},
}
```
<Note>
See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
## Personality overlay
OpenClaw adds a small OpenAI-specific prompt overlay for `openai/*` and `openai-codex/*` runs. The overlay keeps the assistant warm, collaborative, concise, and a little more emotionally expressive without replacing the base system prompt.
| Value | Effect |
| ---------------------- | ---------------------------------- |
| `"friendly"` (default) | Enable the OpenAI-specific overlay |
| `"on"` | Alias for `"friendly"` |
| `"off"` | Use base OpenClaw prompt only |
<Tabs>
<Tab title="Config">
```json5
{
plugins: {
entries: {
openai: { config: { personality: "friendly" } },
},
},
}
```
</Tab>
<Tab title="CLI">
```bash
openclaw config set plugins.entries.openai.config.personality off
```
</Tab>
</Tabs>
<Tip>
Values are case-insensitive at runtime, so `"Off"` and `"off"` both disable the overlay.
</Tip>
## Voice and speech
<AccordionGroup>
<Accordion title="Speech synthesis (TTS)">
The bundled `openai` plugin registers speech synthesis for the `messages.tts` surface.
| Setting | Config path | Default |
|---------|------------|---------|
| Model | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| Voice | `messages.tts.providers.openai.voice` | `coral` |
| Speed | `messages.tts.providers.openai.speed` | (unset) |
| Instructions | `messages.tts.providers.openai.instructions` | (unset, `gpt-4o-mini-tts` only) |
| Format | `messages.tts.providers.openai.responseFormat` | `opus` for voice notes, `mp3` for files |
| API key | `messages.tts.providers.openai.apiKey` | Falls back to `OPENAI_API_KEY` |
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
Available models: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Available voices: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`.
```json5
{
messages: {
tts: {
providers: {
openai: { model: "gpt-4o-mini-tts", voice: "coral" },
},
},
},
}
```
<Note>
Set `OPENAI_TTS_BASE_URL` to override the TTS base URL without affecting the chat API endpoint.
</Note>
</Accordion>
<Accordion title="Realtime transcription">
The bundled `openai` plugin registers realtime transcription for the Voice Call plugin.
| Setting | Config path | Default |
|---------|------------|---------|
| Model | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| Silence duration | `...openai.silenceDurationMs` | `800` |
| VAD threshold | `...openai.vadThreshold` | `0.5` |
| API key | `...openai.apiKey` | Falls back to `OPENAI_API_KEY` |
<Note>
Uses a WebSocket connection to `wss://api.openai.com/v1/realtime` with G.711 u-law audio.
</Note>
</Accordion>
<Accordion title="Realtime voice">
The bundled `openai` plugin registers realtime voice for the Voice Call plugin.
| Setting | Config path | Default |
|---------|------------|---------|
| Model | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` |
| Voice | `...openai.voice` | `alloy` |
| Temperature | `...openai.temperature` | `0.8` |
| VAD threshold | `...openai.vadThreshold` | `0.5` |
| Silence duration | `...openai.silenceDurationMs` | `500` |
| API key | `...openai.apiKey` | Falls back to `OPENAI_API_KEY` |
<Note>
Supports Azure OpenAI via `azureEndpoint` and `azureDeployment` config keys. Supports bidirectional tool calling. Uses G.711 u-law audio format.
</Note>
</Accordion>
</AccordionGroup>
## Advanced configuration
<AccordionGroup>
<Accordion title="Transport (WebSocket vs SSE)">
OpenClaw uses WebSocket-first with SSE fallback (`"auto"`) for both `openai/*` and `openai-codex/*`.
In `"auto"` mode, OpenClaw:
- Retries one early WebSocket failure before falling back to SSE
- After a failure, marks WebSocket as degraded for ~60 seconds and uses SSE during cool-down
- Attaches stable session and turn identity headers for retries and reconnects
- Normalizes usage counters (`input_tokens` / `prompt_tokens`) across transport variants
| Value | Behavior |
|-------|----------|
| `"auto"` (default) | WebSocket first, SSE fallback |
| `"sse"` | Force SSE only |
| `"websocket"` | Force WebSocket only |
```json5
{
agents: {
defaults: {
models: {
"openai-codex/gpt-5.4": {
params: { transport: "auto" },
},
},
},
},
}
```
Related OpenAI docs:
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
</Accordion>
<Accordion title="WebSocket warm-up">
OpenClaw enables WebSocket warm-up by default for `openai/*` to reduce first-turn latency.
```json5
// Disable warm-up
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: { openaiWsWarmup: false },
},
},
},
},
}
```
</Accordion>
<Accordion title="Fast mode">
OpenClaw exposes a shared fast-mode toggle for both `openai/*` and `openai-codex/*`:
- **Chat/UI:** `/fast status|on|off`
- **Config:** `agents.defaults.models["<provider>/<model>"].params.fastMode`
When enabled, OpenClaw maps fast mode to OpenAI priority processing (`service_tier = "priority"`). Existing `service_tier` values are preserved, and fast mode does not rewrite `reasoning` or `text.verbosity`.
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": { params: { fastMode: true } },
"openai-codex/gpt-5.4": { params: { fastMode: true } },
},
},
},
}
```
<Note>
Session overrides win over config. Clearing the session override in the Sessions UI returns the session to the configured default.
</Note>
</Accordion>
<Accordion title="Priority processing (service_tier)">
OpenAI's API exposes priority processing via `service_tier`. Set it per model in OpenClaw:
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": { params: { serviceTier: "priority" } },
"openai-codex/gpt-5.4": { params: { serviceTier: "priority" } },
},
},
},
}
```
Supported values: `auto`, `default`, `flex`, `priority`.
<Warning>
`serviceTier` is only forwarded to native OpenAI endpoints (`api.openai.com`) and native Codex endpoints (`chatgpt.com/backend-api`). If you route either provider through a proxy, OpenClaw leaves `service_tier` untouched.
</Warning>
</Accordion>
<Accordion title="Server-side compaction (Responses API)">
For direct OpenAI Responses models (`openai/*` on `api.openai.com`), OpenClaw auto-enables server-side compaction:
- Forces `store: true` (unless model compat sets `supportsStore: false`)
- Injects `context_management: [{ type: "compaction", compact_threshold: ... }]`
- Default `compact_threshold`: 70% of `contextWindow` (or `80000` when unavailable)
<Tabs>
<Tab title="Enable explicitly">
Useful for compatible endpoints like Azure OpenAI Responses:
```json5
{
agents: {
defaults: {
models: {
"azure-openai-responses/gpt-5.4": {
params: { responsesServerCompaction: true },
},
},
},
},
}
```
</Tab>
<Tab title="Custom threshold">
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: {
responsesServerCompaction: true,
responsesCompactThreshold: 120000,
},
},
},
},
},
}
```
</Tab>
<Tab title="Disable">
```json5
{
agents: {
defaults: {
models: {
"openai/gpt-5.4": {
params: { responsesServerCompaction: false },
},
},
},
},
}
```
</Tab>
</Tabs>
<Note>
`responsesServerCompaction` only controls `context_management` injection. Direct OpenAI Responses models still force `store: true` unless compat sets `supportsStore: false`.
</Note>
</Accordion>
<Accordion title="Strict-agentic GPT mode">
For GPT-5-family runs on `openai/*` and `openai-codex/*`, OpenClaw can use a stricter embedded execution contract:
```json5
{
agents: {
defaults: {
embeddedPi: { executionContract: "strict-agentic" },
},
},
}
```
With `strict-agentic`, OpenClaw:
- No longer treats a plan-only turn as successful progress when a tool action is available
- Retries the turn with an act-now steer
- Auto-enables `update_plan` for substantial work
- Surfaces an explicit blocked state if the model keeps planning without acting
<Note>
Scoped to OpenAI and Codex GPT-5-family runs only. Other providers and older model families keep default behavior.
</Note>
</Accordion>
<Accordion title="Native vs OpenAI-compatible routes">
OpenClaw treats direct OpenAI, Codex, and Azure OpenAI endpoints differently from generic OpenAI-compatible `/v1` proxies:
**Native routes** (`openai/*`, `openai-codex/*`, Azure OpenAI):
- Keep `reasoning: { effort: "none" }` intact when reasoning is explicitly disabled
- Default tool schemas to strict mode
- Attach hidden attribution headers on verified native hosts only
- Keep OpenAI-only request shaping (`service_tier`, `store`, reasoning-compat, prompt-cache hints)
**Proxy/compatible routes:**
- Use looser compat behavior
- Do not force strict tool schemas or native-only headers
Azure OpenAI uses native transport and compat behavior but does not receive the hidden attribution headers.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Image generation" href="/tools/image-generation" icon="image">
Shared image tool parameters and provider selection.
</Card>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video tool parameters and provider selection.
</Card>
<Card title="OAuth and auth" href="/gateway/authentication" icon="key">
Auth details and credential reuse rules.
</Card>
</CardGroup>

110
openclaw/docs/providers/opencode-go.md Normal file
View file

@ -0,0 +1,110 @@
---
summary: "Use the OpenCode Go catalog with the shared OpenCode setup"
read_when:
- You want the OpenCode Go catalog
- You need the runtime model refs for Go-hosted models
title: "OpenCode Go"
---
# OpenCode Go
OpenCode Go is the Go catalog within [OpenCode](/providers/opencode).
It uses the same `OPENCODE_API_KEY` as the Zen catalog, but keeps the runtime
provider id `opencode-go` so upstream per-model routing stays correct.
| Property | Value |
| ---------------- | ------------------------------- |
| Runtime provider | `opencode-go` |
| Auth | `OPENCODE_API_KEY` |
| Parent setup | [OpenCode](/providers/opencode) |
## Supported models
| Model ref | Name |
| -------------------------- | ------------ |
| `opencode-go/kimi-k2.5` | Kimi K2.5 |
| `opencode-go/glm-5` | GLM 5 |
| `opencode-go/minimax-m2.5` | MiniMax M2.5 |
## Getting started
<Tabs>
<Tab title="Interactive">
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice opencode-go
```
</Step>
<Step title="Set a Go model as default">
```bash
openclaw config set agents.defaults.model.primary "opencode-go/kimi-k2.5"
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider opencode-go
```
</Step>
</Steps>
</Tab>
<Tab title="Non-interactive">
<Steps>
<Step title="Pass the key directly">
```bash
openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider opencode-go
```
</Step>
</Steps>
</Tab>
</Tabs>
## Config example
```json5
{
env: { OPENCODE_API_KEY: "YOUR_API_KEY_HERE" }, // pragma: allowlist secret
agents: { defaults: { model: { primary: "opencode-go/kimi-k2.5" } } },
}
```
## Advanced notes
<AccordionGroup>
<Accordion title="Routing behavior">
OpenClaw handles per-model routing automatically when the model ref uses
`opencode-go/...`. No additional provider config is required.
</Accordion>
<Accordion title="Runtime ref convention">
Runtime refs stay explicit: `opencode/...` for Zen, `opencode-go/...` for Go.
This keeps upstream per-model routing correct across both catalogs.
</Accordion>
<Accordion title="Shared credentials">
The same `OPENCODE_API_KEY` is used by both the Zen and Go catalogs. Entering
the key during setup stores credentials for both runtime providers.
</Accordion>
</AccordionGroup>
<Tip>
See [OpenCode](/providers/opencode) for the shared onboarding overview and the full
Zen + Go catalog reference.
</Tip>
## Related
<CardGroup cols={2}>
<Card title="OpenCode (parent)" href="/providers/opencode" icon="server">
Shared onboarding, catalog overview, and advanced notes.
</Card>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
</CardGroup>

151
openclaw/docs/providers/opencode.md Normal file
View file

@ -0,0 +1,151 @@
---
summary: "Use OpenCode Zen and Go catalogs with OpenClaw"
read_when:
- You want OpenCode-hosted model access
- You want to pick between the Zen and Go catalogs
title: "OpenCode"
---
# OpenCode
OpenCode exposes two hosted catalogs in OpenClaw:
| Catalog | Prefix | Runtime provider |
| ------- | ----------------- | ---------------- |
| **Zen** | `opencode/...` | `opencode` |
| **Go** | `opencode-go/...` | `opencode-go` |
Both catalogs use the same OpenCode API key. OpenClaw keeps the runtime provider ids
split so upstream per-model routing stays correct, but onboarding and docs treat them
as one OpenCode setup.
## Getting started
<Tabs>
<Tab title="Zen catalog">
**Best for:** the curated OpenCode multi-model proxy (Claude, GPT, Gemini).
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice opencode-zen
```
Or pass the key directly:
```bash
openclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
```
</Step>
<Step title="Set a Zen model as the default">
```bash
openclaw config set agents.defaults.model.primary "opencode/claude-opus-4-6"
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider opencode
```
</Step>
</Steps>
</Tab>
<Tab title="Go catalog">
**Best for:** the OpenCode-hosted Kimi, GLM, and MiniMax lineup.
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice opencode-go
```
Or pass the key directly:
```bash
openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
```
</Step>
<Step title="Set a Go model as the default">
```bash
openclaw config set agents.defaults.model.primary "opencode-go/kimi-k2.5"
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider opencode-go
```
</Step>
</Steps>
</Tab>
</Tabs>
## Config example
```json5
{
env: { OPENCODE_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "opencode/claude-opus-4-6" } } },
}
```
## Catalogs
### Zen
| Property | Value |
| ---------------- | ----------------------------------------------------------------------- |
| Runtime provider | `opencode` |
| Example models | `opencode/claude-opus-4-6`, `opencode/gpt-5.4`, `opencode/gemini-3-pro` |
### Go
| Property | Value |
| ---------------- | ------------------------------------------------------------------------ |
| Runtime provider | `opencode-go` |
| Example models | `opencode-go/kimi-k2.5`, `opencode-go/glm-5`, `opencode-go/minimax-m2.5` |
## Advanced notes
<AccordionGroup>
<Accordion title="API key aliases">
`OPENCODE_ZEN_API_KEY` is also supported as an alias for `OPENCODE_API_KEY`.
</Accordion>
<Accordion title="Shared credentials">
Entering one OpenCode key during setup stores credentials for both runtime
providers. You do not need to onboard each catalog separately.
</Accordion>
<Accordion title="Billing and dashboard">
You sign in to OpenCode, add billing details, and copy your API key. Billing
and catalog availability are managed from the OpenCode dashboard.
</Accordion>
<Accordion title="Gemini replay behavior">
Gemini-backed OpenCode refs stay on the proxy-Gemini path, so OpenClaw keeps
Gemini thought-signature sanitation there without enabling native Gemini
replay validation or bootstrap rewrites.
</Accordion>
<Accordion title="Non-Gemini replay behavior">
Non-Gemini OpenCode refs keep the minimal OpenAI-compatible replay policy.
</Accordion>
</AccordionGroup>
<Tip>
Entering one OpenCode key during setup stores credentials for both the Zen and
Go runtime providers, so you only need to onboard once.
</Tip>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config reference for agents, models, and providers.
</Card>
</CardGroup>

115
openclaw/docs/providers/openrouter.md Normal file
View file

@ -0,0 +1,115 @@
---
summary: "Use OpenRouter's unified API to access many models in OpenClaw"
read_when:
- You want a single API key for many LLMs
- You want to run models via OpenRouter in OpenClaw
title: "OpenRouter"
---
# OpenRouter
OpenRouter provides a **unified API** that routes requests to many models behind a single
endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
## Getting started
<Steps>
<Step title="Get your API key">
Create an API key at [openrouter.ai/keys](https://openrouter.ai/keys).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice openrouter-api-key
```
</Step>
<Step title="(Optional) Switch to a specific model">
Onboarding defaults to `openrouter/auto`. Pick a concrete model later:
```bash
openclaw models set openrouter/<provider>/<model>
```
</Step>
</Steps>
## Config example
```json5
{
env: { OPENROUTER_API_KEY: "sk-or-..." },
agents: {
defaults: {
model: { primary: "openrouter/auto" },
},
},
}
```
## Model references
<Note>
Model refs follow the pattern `openrouter/<provider>/<model>`. For the full list of
available providers and models, see [/concepts/model-providers](/concepts/model-providers).
</Note>
## Authentication and headers
OpenRouter uses a Bearer token with your API key under the hood.
On real OpenRouter requests (`https://openrouter.ai/api/v1`), OpenClaw also adds
OpenRouter's documented app-attribution headers:
| Header | Value |
| ------------------------- | --------------------- |
| `HTTP-Referer` | `https://openclaw.ai` |
| `X-OpenRouter-Title` | `OpenClaw` |
| `X-OpenRouter-Categories` | `cli-agent` |
<Warning>
If you repoint the OpenRouter provider at some other proxy or base URL, OpenClaw
does **not** inject those OpenRouter-specific headers or Anthropic cache markers.
</Warning>
## Advanced notes
<AccordionGroup>
<Accordion title="Anthropic cache markers">
On verified OpenRouter routes, Anthropic model refs keep the
OpenRouter-specific Anthropic `cache_control` markers that OpenClaw uses for
better prompt-cache reuse on system/developer prompt blocks.
</Accordion>
<Accordion title="Thinking / reasoning injection">
On supported non-`auto` routes, OpenClaw maps the selected thinking level to
OpenRouter proxy reasoning payloads. Unsupported model hints and
`openrouter/auto` skip that reasoning injection.
</Accordion>
<Accordion title="OpenAI-only request shaping">
OpenRouter still runs through the proxy-style OpenAI-compatible path, so
native OpenAI-only request shaping such as `serviceTier`, Responses `store`,
OpenAI reasoning-compat payloads, and prompt-cache hints is not forwarded.
</Accordion>
<Accordion title="Gemini-backed routes">
Gemini-backed OpenRouter refs stay on the proxy-Gemini path: OpenClaw keeps
Gemini thought-signature sanitation there, but does not enable native Gemini
replay validation or bootstrap rewrites.
</Accordion>
<Accordion title="Provider routing metadata">
If you pass OpenRouter provider routing under model params, OpenClaw forwards
it as OpenRouter routing metadata before the shared stream wrappers run.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config reference for agents, models, and providers.
</Card>
</CardGroup>

126
openclaw/docs/providers/perplexity-provider.md Normal file
View file

@ -0,0 +1,126 @@
---
title: "Perplexity"
summary: "Perplexity web search provider setup (API key, search modes, filtering)"
read_when:
- You want to configure Perplexity as a web search provider
- You need the Perplexity API key or OpenRouter proxy setup
---
# Perplexity (Web Search Provider)
The Perplexity plugin provides web search capabilities through the Perplexity
Search API or Perplexity Sonar via OpenRouter.
<Note>
This page covers the Perplexity **provider** setup. For the Perplexity
**tool** (how the agent uses it), see [Perplexity tool](/tools/perplexity-search).
</Note>
| Property | Value |
| ----------- | ---------------------------------------------------------------------- |
| Type | Web search provider (not a model provider) |
| Auth | `PERPLEXITY_API_KEY` (direct) or `OPENROUTER_API_KEY` (via OpenRouter) |
| Config path | `plugins.entries.perplexity.config.webSearch.apiKey` |
## Getting started
<Steps>
<Step title="Set the API key">
Run the interactive web-search configuration flow:
```bash
openclaw configure --section web
```
Or set the key directly:
```bash
openclaw config set plugins.entries.perplexity.config.webSearch.apiKey "pplx-xxxxxxxxxxxx"
```
</Step>
<Step title="Start searching">
The agent will automatically use Perplexity for web searches once the key is
configured. No additional steps are required.
</Step>
</Steps>
## Search modes
The plugin auto-selects the transport based on API key prefix:
<Tabs>
<Tab title="Native Perplexity API (pplx-)">
When your key starts with `pplx-`, OpenClaw uses the native Perplexity Search
API. This transport returns structured results and supports domain, language,
and date filters (see filtering options below).
</Tab>
<Tab title="OpenRouter / Sonar (sk-or-)">
When your key starts with `sk-or-`, OpenClaw routes through OpenRouter using
the Perplexity Sonar model. This transport returns AI-synthesized answers with
citations.
</Tab>
</Tabs>
| Key prefix | Transport | Features |
| ---------- | ---------------------------- | ------------------------------------------------ |
| `pplx-` | Native Perplexity Search API | Structured results, domain/language/date filters |
| `sk-or-` | OpenRouter (Sonar) | AI-synthesized answers with citations |
## Native API filtering
<Note>
Filtering options are only available when using the native Perplexity API
(`pplx-` key). OpenRouter/Sonar searches do not support these parameters.
</Note>
When using the native Perplexity API, searches support the following filters:
| Filter | Description | Example |
| -------------- | -------------------------------------- | ----------------------------------- |
| Country | 2-letter country code | `us`, `de`, `jp` |
| Language | ISO 639-1 language code | `en`, `fr`, `zh` |
| Date range | Recency window | `day`, `week`, `month`, `year` |
| Domain filters | Allowlist or denylist (max 20 domains) | `example.com` |
| Content budget | Token limits per response / per page | `max_tokens`, `max_tokens_per_page` |
## Advanced notes
<AccordionGroup>
<Accordion title="Environment variable for daemon processes">
If the OpenClaw Gateway runs as a daemon (launchd/systemd), make sure
`PERPLEXITY_API_KEY` is available to that process.
<Warning>
A key set only in `~/.profile` will not be visible to a launchd/systemd
daemon unless that environment is explicitly imported. Set the key in
`~/.openclaw/.env` or via `env.shellEnv` to ensure the gateway process can
read it.
</Warning>
</Accordion>
<Accordion title="OpenRouter proxy setup">
If you prefer to route Perplexity searches through OpenRouter, set an
`OPENROUTER_API_KEY` (prefix `sk-or-`) instead of a native Perplexity key.
OpenClaw will detect the prefix and switch to the Sonar transport
automatically.
<Tip>
The OpenRouter transport is useful if you already have an OpenRouter account
and want consolidated billing across multiple providers.
</Tip>
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Perplexity search tool" href="/tools/perplexity-search" icon="magnifying-glass">
How the agent invokes Perplexity searches and interprets results.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full configuration reference including plugin entries.
</Card>
</CardGroup>

133
openclaw/docs/providers/qianfan.md Normal file
View file

@ -0,0 +1,133 @@
---
summary: "Use Qianfan's unified API to access many models in OpenClaw"
read_when:
- You want a single API key for many LLMs
- You need Baidu Qianfan setup guidance
title: "Qianfan"
---
# Qianfan
Qianfan is Baidu's MaaS platform, providing a **unified API** that routes requests to many models behind a single
endpoint and API key. It is OpenAI-compatible, so most OpenAI SDKs work by switching the base URL.
| Property | Value |
| -------- | --------------------------------- |
| Provider | `qianfan` |
| Auth | `QIANFAN_API_KEY` |
| API | OpenAI-compatible |
| Base URL | `https://qianfan.baidubce.com/v2` |
## Getting started
<Steps>
<Step title="Create a Baidu Cloud account">
Sign up or log in at the [Qianfan Console](https://console.bce.baidu.com/qianfan/ais/console/apiKey) and ensure you have Qianfan API access enabled.
</Step>
<Step title="Generate an API key">
Create a new application or select an existing one, then generate an API key. The key format is `bce-v3/ALTAK-...`.
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice qianfan-api-key
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider qianfan
```
</Step>
</Steps>
## Available models
| Model ref | Input | Context | Max output | Reasoning | Notes |
| ------------------------------------ | ----------- | ------- | ---------- | --------- | ------------- |
| `qianfan/deepseek-v3.2` | text | 98,304 | 32,768 | Yes | Default model |
| `qianfan/ernie-5.0-thinking-preview` | text, image | 119,000 | 64,000 | Yes | Multimodal |
<Tip>
The default bundled model ref is `qianfan/deepseek-v3.2`. You only need to override `models.providers.qianfan` when you need a custom base URL or model metadata.
</Tip>
## Config example
```json5
{
env: { QIANFAN_API_KEY: "bce-v3/ALTAK-..." },
agents: {
defaults: {
model: { primary: "qianfan/deepseek-v3.2" },
models: {
"qianfan/deepseek-v3.2": { alias: "QIANFAN" },
},
},
},
models: {
providers: {
qianfan: {
baseUrl: "https://qianfan.baidubce.com/v2",
api: "openai-completions",
models: [
{
id: "deepseek-v3.2",
name: "DEEPSEEK V3.2",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 98304,
maxTokens: 32768,
},
{
id: "ernie-5.0-thinking-preview",
name: "ERNIE-5.0-Thinking-Preview",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 119000,
maxTokens: 64000,
},
],
},
},
},
}
```
<AccordionGroup>
<Accordion title="Transport and compatibility">
Qianfan runs through the OpenAI-compatible transport path, not native OpenAI request shaping. This means standard OpenAI SDK features work, but provider-specific parameters may not be forwarded.
</Accordion>
<Accordion title="Catalog and overrides">
The bundled catalog currently includes `deepseek-v3.2` and `ernie-5.0-thinking-preview`. Add or override `models.providers.qianfan` only when you need a custom base URL or model metadata.
<Note>
Model refs use the `qianfan/` prefix (for example `qianfan/deepseek-v3.2`).
</Note>
</Accordion>
<Accordion title="Troubleshooting">
- Ensure your API key starts with `bce-v3/ALTAK-` and has Qianfan API access enabled in the Baidu Cloud console.
- If models are not listed, confirm your account has the Qianfan service activated.
- The default base URL is `https://qianfan.baidubce.com/v2`. Only change it if you use a custom endpoint or proxy.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration" icon="gear">
Full OpenClaw configuration reference.
</Card>
<Card title="Agent setup" href="/concepts/agent" icon="robot">
Configuring agent defaults and model assignments.
</Card>
<Card title="Qianfan API docs" href="https://cloud.baidu.com/doc/qianfan-api/s/3m7of64lb" icon="arrow-up-right-from-square">
Official Qianfan API documentation.
</Card>
</CardGroup>

315
openclaw/docs/providers/qwen.md Normal file
View file

@ -0,0 +1,315 @@
---
summary: "Use Qwen Cloud via OpenClaw's bundled qwen provider"
read_when:
- You want to use Qwen with OpenClaw
- You previously used Qwen OAuth
title: "Qwen"
---
# Qwen
<Warning>
**Qwen OAuth has been removed.** The free-tier OAuth integration
(`qwen-portal`) that used `portal.qwen.ai` endpoints is no longer available.
See [Issue #49557](https://github.com/openclaw/openclaw/issues/49557) for
background.
</Warning>
OpenClaw now treats Qwen as a first-class bundled provider with canonical id
`qwen`. The bundled provider targets the Qwen Cloud / Alibaba DashScope and
Coding Plan endpoints and keeps legacy `modelstudio` ids working as a
compatibility alias.
- Provider: `qwen`
- Preferred env var: `QWEN_API_KEY`
- Also accepted for compatibility: `MODELSTUDIO_API_KEY`, `DASHSCOPE_API_KEY`
- API style: OpenAI-compatible
<Tip>
If you want `qwen3.6-plus`, prefer the **Standard (pay-as-you-go)** endpoint.
Coding Plan support can lag behind the public catalog.
</Tip>
## Getting started
Choose your plan type and follow the setup steps.
<Tabs>
<Tab title="Coding Plan (subscription)">
**Best for:** subscription-based access through the Qwen Coding Plan.
<Steps>
<Step title="Get your API key">
Create or copy an API key from [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys).
</Step>
<Step title="Run onboarding">
For the **Global** endpoint:
```bash
openclaw onboard --auth-choice qwen-api-key
```
For the **China** endpoint:
```bash
openclaw onboard --auth-choice qwen-api-key-cn
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "qwen/qwen3.5-plus" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider qwen
```
</Step>
</Steps>
<Note>
Legacy `modelstudio-*` auth-choice ids and `modelstudio/...` model refs still
work as compatibility aliases, but new setup flows should prefer the canonical
`qwen-*` auth-choice ids and `qwen/...` model refs.
</Note>
</Tab>
<Tab title="Standard (pay-as-you-go)">
**Best for:** pay-as-you-go access through the Standard Model Studio endpoint, including models like `qwen3.6-plus` that may not be available on the Coding Plan.
<Steps>
<Step title="Get your API key">
Create or copy an API key from [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys).
</Step>
<Step title="Run onboarding">
For the **Global** endpoint:
```bash
openclaw onboard --auth-choice qwen-standard-api-key
```
For the **China** endpoint:
```bash
openclaw onboard --auth-choice qwen-standard-api-key-cn
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "qwen/qwen3.5-plus" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider qwen
```
</Step>
</Steps>
<Note>
Legacy `modelstudio-*` auth-choice ids and `modelstudio/...` model refs still
work as compatibility aliases, but new setup flows should prefer the canonical
`qwen-*` auth-choice ids and `qwen/...` model refs.
</Note>
</Tab>
</Tabs>
## Plan types and endpoints
| Plan | Region | Auth choice | Endpoint |
| -------------------------- | ------ | -------------------------- | ------------------------------------------------ |
| Standard (pay-as-you-go) | China | `qwen-standard-api-key-cn` | `dashscope.aliyuncs.com/compatible-mode/v1` |
| Standard (pay-as-you-go) | Global | `qwen-standard-api-key` | `dashscope-intl.aliyuncs.com/compatible-mode/v1` |
| Coding Plan (subscription) | China | `qwen-api-key-cn` | `coding.dashscope.aliyuncs.com/v1` |
| Coding Plan (subscription) | Global | `qwen-api-key` | `coding-intl.dashscope.aliyuncs.com/v1` |
The provider auto-selects the endpoint based on your auth choice. Canonical
choices use the `qwen-*` family; `modelstudio-*` remains compatibility-only.
You can override with a custom `baseUrl` in config.
<Tip>
**Manage keys:** [home.qwencloud.com/api-keys](https://home.qwencloud.com/api-keys) |
**Docs:** [docs.qwencloud.com](https://docs.qwencloud.com/developer-guides/getting-started/introduction)
</Tip>
## Built-in catalog
OpenClaw currently ships this bundled Qwen catalog. The configured catalog is
endpoint-aware: Coding Plan configs omit models that are only known to work on
the Standard endpoint.
| Model ref | Input | Context | Notes |
| --------------------------- | ----------- | --------- | -------------------------------------------------- |
| `qwen/qwen3.5-plus` | text, image | 1,000,000 | Default model |
| `qwen/qwen3.6-plus` | text, image | 1,000,000 | Prefer Standard endpoints when you need this model |
| `qwen/qwen3-max-2026-01-23` | text | 262,144 | Qwen Max line |
| `qwen/qwen3-coder-next` | text | 262,144 | Coding |
| `qwen/qwen3-coder-plus` | text | 1,000,000 | Coding |
| `qwen/MiniMax-M2.5` | text | 1,000,000 | Reasoning enabled |
| `qwen/glm-5` | text | 202,752 | GLM |
| `qwen/glm-4.7` | text | 202,752 | GLM |
| `qwen/kimi-k2.5` | text, image | 262,144 | Moonshot AI via Alibaba |
<Note>
Availability can still vary by endpoint and billing plan even when a model is
present in the bundled catalog.
</Note>
## Multimodal add-ons
The `qwen` extension also exposes multimodal capabilities on the **Standard**
DashScope endpoints (not the Coding Plan endpoints):
- **Video understanding** via `qwen-vl-max-latest`
- **Wan video generation** via `wan2.6-t2v` (default), `wan2.6-i2v`, `wan2.6-r2v`, `wan2.6-r2v-flash`, `wan2.7-r2v`
To use Qwen as the default video provider:
```json5
{
agents: {
defaults: {
videoGenerationModel: { primary: "qwen/wan2.6-t2v" },
},
},
}
```
<Note>
See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
## Advanced
<AccordionGroup>
<Accordion title="Image and video understanding">
The bundled Qwen plugin registers media understanding for images and video
on the **Standard** DashScope endpoints (not the Coding Plan endpoints).
| Property | Value |
| ------------- | --------------------- |
| Model | `qwen-vl-max-latest` |
| Supported input | Images, video |
Media understanding is auto-resolved from the configured Qwen auth — no
additional config is needed. Ensure you are using a Standard (pay-as-you-go)
endpoint for media understanding support.
</Accordion>
<Accordion title="Qwen 3.6 Plus availability">
`qwen3.6-plus` is available on the Standard (pay-as-you-go) Model Studio
endpoints:
- China: `dashscope.aliyuncs.com/compatible-mode/v1`
- Global: `dashscope-intl.aliyuncs.com/compatible-mode/v1`
If the Coding Plan endpoints return an "unsupported model" error for
`qwen3.6-plus`, switch to Standard (pay-as-you-go) instead of the Coding Plan
endpoint/key pair.
</Accordion>
<Accordion title="Capability plan">
The `qwen` extension is being positioned as the vendor home for the full Qwen
Cloud surface, not just coding/text models.
- **Text/chat models:** bundled now
- **Tool calling, structured output, thinking:** inherited from the OpenAI-compatible transport
- **Image generation:** planned at the provider-plugin layer
- **Image/video understanding:** bundled now on the Standard endpoint
- **Speech/audio:** planned at the provider-plugin layer
- **Memory embeddings/reranking:** planned through the embedding adapter surface
- **Video generation:** bundled now through the shared video-generation capability
</Accordion>
<Accordion title="Video generation details">
For video generation, OpenClaw maps the configured Qwen region to the matching
DashScope AIGC host before submitting the job:
- Global/Intl: `https://dashscope-intl.aliyuncs.com`
- China: `https://dashscope.aliyuncs.com`
That means a normal `models.providers.qwen.baseUrl` pointing at either the
Coding Plan or Standard Qwen hosts still keeps video generation on the correct
regional DashScope video endpoint.
Current bundled Qwen video-generation limits:
- Up to **1** output video per request
- Up to **1** input image
- Up to **4** input videos
- Up to **10 seconds** duration
- Supports `size`, `aspectRatio`, `resolution`, `audio`, and `watermark`
- Reference image/video mode currently requires **remote http(s) URLs**. Local
file paths are rejected up front because the DashScope video endpoint does not
accept uploaded local buffers for those references.
</Accordion>
<Accordion title="Streaming usage compatibility">
Native Model Studio endpoints advertise streaming usage compatibility on the
shared `openai-completions` transport. OpenClaw keys that off endpoint
capabilities now, so DashScope-compatible custom provider ids targeting the
same native hosts inherit the same streaming-usage behavior instead of
requiring the built-in `qwen` provider id specifically.
Native-streaming usage compatibility applies to both the Coding Plan hosts and
the Standard DashScope-compatible hosts:
- `https://coding.dashscope.aliyuncs.com/v1`
- `https://coding-intl.dashscope.aliyuncs.com/v1`
- `https://dashscope.aliyuncs.com/compatible-mode/v1`
- `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
</Accordion>
<Accordion title="Multimodal endpoint regions">
Multimodal surfaces (video understanding and Wan video generation) use the
**Standard** DashScope endpoints, not the Coding Plan endpoints:
- Global/Intl Standard base URL: `https://dashscope-intl.aliyuncs.com/compatible-mode/v1`
- China Standard base URL: `https://dashscope.aliyuncs.com/compatible-mode/v1`
</Accordion>
<Accordion title="Environment and daemon setup">
If the Gateway runs as a daemon (launchd/systemd), make sure `QWEN_API_KEY` is
available to that process (for example, in `~/.openclaw/.env` or via
`env.shellEnv`).
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video tool parameters and provider selection.
</Card>
<Card title="Alibaba (ModelStudio)" href="/providers/alibaba" icon="cloud">
Legacy ModelStudio provider and migration notes.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
General troubleshooting and FAQ.
</Card>
</CardGroup>

13
openclaw/docs/providers/qwen_modelstudio.md Normal file
View file

@ -0,0 +1,13 @@
---
title: "Qwen / Model Studio"
summary: "Redirect to /providers/qwen"
read_when:
- You followed an older Model Studio link
- You want the canonical Qwen provider page
---
# Qwen / Model Studio
This page moved to [Qwen](/providers/qwen). See [Qwen](/providers/qwen) for
the canonical provider setup, endpoint details, compatibility aliases, and Wan
video-generation notes.

93
openclaw/docs/providers/runway.md Normal file
View file

@ -0,0 +1,93 @@
---
title: "Runway"
summary: "Runway video generation setup in OpenClaw"
read_when:
- You want to use Runway video generation in OpenClaw
- You need the Runway API key/env setup
- You want to make Runway the default video provider
---
# Runway
OpenClaw ships a bundled `runway` provider for hosted video generation.
| Property | Value |
| ----------- | ----------------------------------------------------------------- |
| Provider id | `runway` |
| Auth | `RUNWAYML_API_SECRET` (canonical) or `RUNWAY_API_KEY` |
| API | Runway task-based video generation (`GET /v1/tasks/{id}` polling) |
## Getting started
<Steps>
<Step title="Set the API key">
```bash
openclaw onboard --auth-choice runway-api-key
```
</Step>
<Step title="Set Runway as the default video provider">
```bash
openclaw config set agents.defaults.videoGenerationModel.primary "runway/gen4.5"
```
</Step>
<Step title="Generate a video">
Ask the agent to generate a video. Runway will be used automatically.
</Step>
</Steps>
## Supported modes
| Mode | Model | Reference input |
| -------------- | ------------------ | ----------------------- |
| Text-to-video | `gen4.5` (default) | None |
| Image-to-video | `gen4.5` | 1 local or remote image |
| Video-to-video | `gen4_aleph` | 1 local or remote video |
<Note>
Local image and video references are supported via data URIs. Text-only runs
currently expose `16:9` and `9:16` aspect ratios.
</Note>
<Warning>
Video-to-video currently requires `runway/gen4_aleph` specifically.
</Warning>
## Configuration
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "runway/gen4.5",
},
},
},
}
```
## Advanced notes
<AccordionGroup>
<Accordion title="Environment variable aliases">
OpenClaw recognizes both `RUNWAYML_API_SECRET` (canonical) and `RUNWAY_API_KEY`.
Either variable will authenticate the Runway provider.
</Accordion>
<Accordion title="Task polling">
Runway uses a task-based API. After submitting a generation request, OpenClaw
polls `GET /v1/tasks/{id}` until the video is ready. No additional
configuration is needed for the polling behavior.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared tool parameters, provider selection, and async behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference#agent-defaults" icon="gear">
Agent default settings including video generation model.
</Card>
</CardGroup>

152
openclaw/docs/providers/sglang.md Normal file
View file

@ -0,0 +1,152 @@
---
summary: "Run OpenClaw with SGLang (OpenAI-compatible self-hosted server)"
read_when:
- You want to run OpenClaw against a local SGLang server
- You want OpenAI-compatible /v1 endpoints with your own models
title: "SGLang"
---
# SGLang
SGLang can serve open-source models via an **OpenAI-compatible** HTTP API.
OpenClaw can connect to SGLang using the `openai-completions` API.
OpenClaw can also **auto-discover** available models from SGLang when you opt
in with `SGLANG_API_KEY` (any value works if your server does not enforce auth)
and you do not define an explicit `models.providers.sglang` entry.
## Getting started
<Steps>
<Step title="Start SGLang">
Launch SGLang with an OpenAI-compatible server. Your base URL should expose
`/v1` endpoints (for example `/v1/models`, `/v1/chat/completions`). SGLang
commonly runs on:
- `http://127.0.0.1:30000/v1`
</Step>
<Step title="Set an API key">
Any value works if no auth is configured on your server:
```bash
export SGLANG_API_KEY="sglang-local"
```
</Step>
<Step title="Run onboarding or set a model directly">
```bash
openclaw onboard
```
Or configure the model manually:
```json5
{
agents: {
defaults: {
model: { primary: "sglang/your-model-id" },
},
},
}
```
</Step>
</Steps>
## Model discovery (implicit provider)
When `SGLANG_API_KEY` is set (or an auth profile exists) and you **do not**
define `models.providers.sglang`, OpenClaw will query:
- `GET http://127.0.0.1:30000/v1/models`
and convert the returned IDs into model entries.
<Note>
If you set `models.providers.sglang` explicitly, auto-discovery is skipped and
you must define models manually.
</Note>
## Explicit configuration (manual models)
Use explicit config when:
- SGLang runs on a different host/port.
- You want to pin `contextWindow`/`maxTokens` values.
- Your server requires a real API key (or you want to control headers).
```json5
{
models: {
providers: {
sglang: {
baseUrl: "http://127.0.0.1:30000/v1",
apiKey: "${SGLANG_API_KEY}",
api: "openai-completions",
models: [
{
id: "your-model-id",
name: "Local SGLang Model",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 8192,
},
],
},
},
},
}
```
## Advanced configuration
<AccordionGroup>
<Accordion title="Proxy-style behavior">
SGLang is treated as a proxy-style OpenAI-compatible `/v1` backend, not a
native OpenAI endpoint.
| Behavior | SGLang |
|----------|--------|
| OpenAI-only request shaping | Not applied |
| `service_tier`, Responses `store`, prompt-cache hints | Not sent |
| Reasoning-compat payload shaping | Not applied |
| Hidden attribution headers (`originator`, `version`, `User-Agent`) | Not injected on custom SGLang base URLs |
</Accordion>
<Accordion title="Troubleshooting">
**Server not reachable**
Verify the server is running and responding:
```bash
curl http://127.0.0.1:30000/v1/models
```
**Auth errors**
If requests fail with auth errors, set a real `SGLANG_API_KEY` that matches
your server configuration, or configure the provider explicitly under
`models.providers.sglang`.
<Tip>
If you run SGLang without authentication, any non-empty value for
`SGLANG_API_KEY` is sufficient to opt in to model discovery.
</Tip>
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config schema including provider entries.
</Card>
</CardGroup>

230
openclaw/docs/providers/stepfun.md Normal file
View file

@ -0,0 +1,230 @@
---
summary: "Use StepFun models with OpenClaw"
read_when:
- You want StepFun models in OpenClaw
- You need StepFun setup guidance
title: "StepFun"
---
# StepFun
OpenClaw includes a bundled StepFun provider plugin with two provider ids:
- `stepfun` for the standard endpoint
- `stepfun-plan` for the Step Plan endpoint
<Warning>
Standard and Step Plan are **separate providers** with different endpoints and model ref prefixes (`stepfun/...` vs `stepfun-plan/...`). Use a China key with the `.com` endpoints and a global key with the `.ai` endpoints.
</Warning>
## Region and endpoint overview
| Endpoint | China (`.com`) | Global (`.ai`) |
| --------- | -------------------------------------- | ------------------------------------- |
| Standard | `https://api.stepfun.com/v1` | `https://api.stepfun.ai/v1` |
| Step Plan | `https://api.stepfun.com/step_plan/v1` | `https://api.stepfun.ai/step_plan/v1` |
Auth env var: `STEPFUN_API_KEY`
## Built-in catalogs
Standard (`stepfun`):
| Model ref | Context | Max output | Notes |
| ------------------------ | ------- | ---------- | ---------------------- |
| `stepfun/step-3.5-flash` | 262,144 | 65,536 | Default standard model |
Step Plan (`stepfun-plan`):
| Model ref | Context | Max output | Notes |
| ---------------------------------- | ------- | ---------- | -------------------------- |
| `stepfun-plan/step-3.5-flash` | 262,144 | 65,536 | Default Step Plan model |
| `stepfun-plan/step-3.5-flash-2603` | 262,144 | 65,536 | Additional Step Plan model |
## Getting started
Choose your provider surface and follow the setup steps.
<Tabs>
<Tab title="Standard">
**Best for:** general-purpose use via the standard StepFun endpoint.
<Steps>
<Step title="Choose your endpoint region">
| Auth choice | Endpoint | Region |
| -------------------------------- | -------------------------------- | ------------- |
| `stepfun-standard-api-key-intl` | `https://api.stepfun.ai/v1` | International |
| `stepfun-standard-api-key-cn` | `https://api.stepfun.com/v1` | China |
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice stepfun-standard-api-key-intl
```
Or for the China endpoint:
```bash
openclaw onboard --auth-choice stepfun-standard-api-key-cn
```
</Step>
<Step title="Non-interactive alternative">
```bash
openclaw onboard --auth-choice stepfun-standard-api-key-intl \
--stepfun-api-key "$STEPFUN_API_KEY"
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider stepfun
```
</Step>
</Steps>
### Model refs
- Default model: `stepfun/step-3.5-flash`
</Tab>
<Tab title="Step Plan">
**Best for:** Step Plan reasoning endpoint.
<Steps>
<Step title="Choose your endpoint region">
| Auth choice | Endpoint | Region |
| ---------------------------- | --------------------------------------- | ------------- |
| `stepfun-plan-api-key-intl` | `https://api.stepfun.ai/step_plan/v1` | International |
| `stepfun-plan-api-key-cn` | `https://api.stepfun.com/step_plan/v1` | China |
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice stepfun-plan-api-key-intl
```
Or for the China endpoint:
```bash
openclaw onboard --auth-choice stepfun-plan-api-key-cn
```
</Step>
<Step title="Non-interactive alternative">
```bash
openclaw onboard --auth-choice stepfun-plan-api-key-intl \
--stepfun-api-key "$STEPFUN_API_KEY"
```
</Step>
<Step title="Verify models are available">
```bash
openclaw models list --provider stepfun-plan
```
</Step>
</Steps>
### Model refs
- Default model: `stepfun-plan/step-3.5-flash`
- Alternate model: `stepfun-plan/step-3.5-flash-2603`
</Tab>
</Tabs>
## Advanced
<AccordionGroup>
<Accordion title="Full config: Standard provider">
```json5
{
env: { STEPFUN_API_KEY: "your-key" },
agents: { defaults: { model: { primary: "stepfun/step-3.5-flash" } } },
models: {
mode: "merge",
providers: {
stepfun: {
baseUrl: "https://api.stepfun.ai/v1",
api: "openai-completions",
apiKey: "${STEPFUN_API_KEY}",
models: [
{
id: "step-3.5-flash",
name: "Step 3.5 Flash",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 65536,
},
],
},
},
},
}
```
</Accordion>
<Accordion title="Full config: Step Plan provider">
```json5
{
env: { STEPFUN_API_KEY: "your-key" },
agents: { defaults: { model: { primary: "stepfun-plan/step-3.5-flash" } } },
models: {
mode: "merge",
providers: {
"stepfun-plan": {
baseUrl: "https://api.stepfun.ai/step_plan/v1",
api: "openai-completions",
apiKey: "${STEPFUN_API_KEY}",
models: [
{
id: "step-3.5-flash",
name: "Step 3.5 Flash",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 65536,
},
{
id: "step-3.5-flash-2603",
name: "Step 3.5 Flash 2603",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 65536,
},
],
},
},
},
}
```
</Accordion>
<Accordion title="Notes">
- The provider is bundled with OpenClaw, so there is no separate plugin install step.
- `step-3.5-flash-2603` is currently exposed only on `stepfun-plan`.
- A single auth flow writes region-matched profiles for both `stepfun` and `stepfun-plan`, so both surfaces can be discovered together.
- Use `openclaw models list` and `openclaw models set <provider/model>` to inspect or switch models.
</Accordion>
</AccordionGroup>
<Note>
For the broader provider overview, see [Model providers](/concepts/model-providers).
</Note>
## Related
<CardGroup cols={2}>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Overview of all providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config schema for providers, models, and plugins.
</Card>
<Card title="Model selection" href="/concepts/models" icon="brain">
How to choose and configure models.
</Card>
<Card title="StepFun Platform" href="https://platform.stepfun.com" icon="globe">
StepFun API key management and documentation.
</Card>
</CardGroup>

156
openclaw/docs/providers/synthetic.md Normal file
View file

@ -0,0 +1,156 @@
---
summary: "Use Synthetic's Anthropic-compatible API in OpenClaw"
read_when:
- You want to use Synthetic as a model provider
- You need a Synthetic API key or base URL setup
title: "Synthetic"
---
# Synthetic
[Synthetic](https://synthetic.new) exposes Anthropic-compatible endpoints.
OpenClaw registers it as the `synthetic` provider and uses the Anthropic
Messages API.
| Property | Value |
| -------- | ------------------------------------- |
| Provider | `synthetic` |
| Auth | `SYNTHETIC_API_KEY` |
| API | Anthropic Messages |
| Base URL | `https://api.synthetic.new/anthropic` |
## Getting started
<Steps>
<Step title="Get an API key">
Obtain a `SYNTHETIC_API_KEY` from your Synthetic account, or let the
onboarding wizard prompt you for one.
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice synthetic-api-key
```
</Step>
<Step title="Verify the default model">
After onboarding the default model is set to:
```
synthetic/hf:MiniMaxAI/MiniMax-M2.5
```
</Step>
</Steps>
<Warning>
OpenClaw's Anthropic client appends `/v1` to the base URL automatically, so use
`https://api.synthetic.new/anthropic` (not `/anthropic/v1`). If Synthetic
changes its base URL, override `models.providers.synthetic.baseUrl`.
</Warning>
## Config example
```json5
{
env: { SYNTHETIC_API_KEY: "sk-..." },
agents: {
defaults: {
model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
},
},
models: {
mode: "merge",
providers: {
synthetic: {
baseUrl: "https://api.synthetic.new/anthropic",
apiKey: "${SYNTHETIC_API_KEY}",
api: "anthropic-messages",
models: [
{
id: "hf:MiniMaxAI/MiniMax-M2.5",
name: "MiniMax M2.5",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 192000,
maxTokens: 65536,
},
],
},
},
},
}
```
## Model catalog
All Synthetic models use cost `0` (input/output/cache).
| Model ID | Context window | Max tokens | Reasoning | Input |
| ------------------------------------------------------ | -------------- | ---------- | --------- | ------------ |
| `hf:MiniMaxAI/MiniMax-M2.5` | 192,000 | 65,536 | no | text |
| `hf:moonshotai/Kimi-K2-Thinking` | 256,000 | 8,192 | yes | text |
| `hf:zai-org/GLM-4.7` | 198,000 | 128,000 | no | text |
| `hf:deepseek-ai/DeepSeek-R1-0528` | 128,000 | 8,192 | no | text |
| `hf:deepseek-ai/DeepSeek-V3-0324` | 128,000 | 8,192 | no | text |
| `hf:deepseek-ai/DeepSeek-V3.1` | 128,000 | 8,192 | no | text |
| `hf:deepseek-ai/DeepSeek-V3.1-Terminus` | 128,000 | 8,192 | no | text |
| `hf:deepseek-ai/DeepSeek-V3.2` | 159,000 | 8,192 | no | text |
| `hf:meta-llama/Llama-3.3-70B-Instruct` | 128,000 | 8,192 | no | text |
| `hf:meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | 524,000 | 8,192 | no | text |
| `hf:moonshotai/Kimi-K2-Instruct-0905` | 256,000 | 8,192 | no | text |
| `hf:moonshotai/Kimi-K2.5` | 256,000 | 8,192 | yes | text + image |
| `hf:openai/gpt-oss-120b` | 128,000 | 8,192 | no | text |
| `hf:Qwen/Qwen3-235B-A22B-Instruct-2507` | 256,000 | 8,192 | no | text |
| `hf:Qwen/Qwen3-Coder-480B-A35B-Instruct` | 256,000 | 8,192 | no | text |
| `hf:Qwen/Qwen3-VL-235B-A22B-Instruct` | 250,000 | 8,192 | no | text + image |
| `hf:zai-org/GLM-4.5` | 128,000 | 128,000 | no | text |
| `hf:zai-org/GLM-4.6` | 198,000 | 128,000 | no | text |
| `hf:zai-org/GLM-5` | 256,000 | 128,000 | yes | text + image |
| `hf:deepseek-ai/DeepSeek-V3` | 128,000 | 8,192 | no | text |
| `hf:Qwen/Qwen3-235B-A22B-Thinking-2507` | 256,000 | 8,192 | yes | text |
<Tip>
Model refs use the form `synthetic/<modelId>`. Use
`openclaw models list --provider synthetic` to see all models available on your
account.
</Tip>
<AccordionGroup>
<Accordion title="Model allowlist">
If you enable a model allowlist (`agents.defaults.models`), add every
Synthetic model you plan to use. Models not in the allowlist will be hidden
from the agent.
</Accordion>
<Accordion title="Base URL override">
If Synthetic changes its API endpoint, override the base URL in your config:
```json5
{
models: {
providers: {
synthetic: {
baseUrl: "https://new-api.synthetic.new/anthropic",
},
},
},
}
```
Remember that OpenClaw appends `/v1` automatically.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Provider rules, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config schema including provider settings.
</Card>
<Card title="Synthetic" href="https://synthetic.new" icon="arrow-up-right-from-square">
Synthetic dashboard and API docs.
</Card>
</CardGroup>

142
openclaw/docs/providers/together.md Normal file
View file

@ -0,0 +1,142 @@
---
title: "Together AI"
summary: "Together AI setup (auth + model selection)"
read_when:
- You want to use Together AI with OpenClaw
- You need the API key env var or CLI auth choice
---
# Together AI
[Together AI](https://together.ai) provides access to leading open-source
models including Llama, DeepSeek, Kimi, and more through a unified API.
| Property | Value |
| -------- | ----------------------------- |
| Provider | `together` |
| Auth | `TOGETHER_API_KEY` |
| API | OpenAI-compatible |
| Base URL | `https://api.together.xyz/v1` |
## Getting started
<Steps>
<Step title="Get an API key">
Create an API key at
[api.together.ai/settings/api-keys](https://api.together.ai/settings/api-keys).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice together-api-key
```
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "together/moonshotai/Kimi-K2.5" },
},
},
}
```
</Step>
</Steps>
### Non-interactive example
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice together-api-key \
--together-api-key "$TOGETHER_API_KEY"
```
<Note>
The onboarding preset sets `together/moonshotai/Kimi-K2.5` as the default
model.
</Note>
## Built-in catalog
OpenClaw ships this bundled Together catalog:
| Model ref | Name | Input | Context | Notes |
| ------------------------------------------------------------ | -------------------------------------- | ----------- | ---------- | -------------------------------- |
| `together/moonshotai/Kimi-K2.5` | Kimi K2.5 | text, image | 262,144 | Default model; reasoning enabled |
| `together/zai-org/GLM-4.7` | GLM 4.7 Fp8 | text | 202,752 | General-purpose text model |
| `together/meta-llama/Llama-3.3-70B-Instruct-Turbo` | Llama 3.3 70B Instruct Turbo | text | 131,072 | Fast instruction model |
| `together/meta-llama/Llama-4-Scout-17B-16E-Instruct` | Llama 4 Scout 17B 16E Instruct | text, image | 10,000,000 | Multimodal |
| `together/meta-llama/Llama-4-Maverick-17B-128E-Instruct-FP8` | Llama 4 Maverick 17B 128E Instruct FP8 | text, image | 20,000,000 | Multimodal |
| `together/deepseek-ai/DeepSeek-V3.1` | DeepSeek V3.1 | text | 131,072 | General text model |
| `together/deepseek-ai/DeepSeek-R1` | DeepSeek R1 | text | 131,072 | Reasoning model |
| `together/moonshotai/Kimi-K2-Instruct-0905` | Kimi K2-Instruct 0905 | text | 262,144 | Secondary Kimi text model |
## Video generation
The bundled `together` plugin also registers video generation through the
shared `video_generate` tool.
| Property | Value |
| -------------------- | ------------------------------------- |
| Default video model | `together/Wan-AI/Wan2.2-T2V-A14B` |
| Modes | text-to-video, single-image reference |
| Supported parameters | `aspectRatio`, `resolution` |
To use Together as the default video provider:
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "together/Wan-AI/Wan2.2-T2V-A14B",
},
},
},
}
```
<Tip>
See [Video Generation](/tools/video-generation) for the shared tool parameters,
provider selection, and failover behavior.
</Tip>
<AccordionGroup>
<Accordion title="Environment note">
If the Gateway runs as a daemon (launchd/systemd), make sure
`TOGETHER_API_KEY` is available to that process (for example, in
`~/.openclaw/.env` or via `env.shellEnv`).
<Warning>
Keys set only in your interactive shell are not visible to daemon-managed
gateway processes. Use `~/.openclaw/.env` or `env.shellEnv` config for
persistent availability.
</Warning>
</Accordion>
<Accordion title="Troubleshooting">
- Verify your key works: `openclaw models list --provider together`
- If models are not appearing, confirm the API key is set in the correct
environment for your Gateway process.
- Model refs use the form `together/<model-id>`.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model providers" href="/concepts/model-providers" icon="layers">
Provider rules, model refs, and failover behavior.
</Card>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video generation tool parameters and provider selection.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference" icon="gear">
Full config schema including provider settings.
</Card>
<Card title="Together AI" href="https://together.ai" icon="arrow-up-right-from-square">
Together AI dashboard, API docs, and pricing.
</Card>
</CardGroup>

308
openclaw/docs/providers/venice.md Normal file
View file

@ -0,0 +1,308 @@
---
summary: "Use Venice AI privacy-focused models in OpenClaw"
read_when:
- You want privacy-focused inference in OpenClaw
- You want Venice AI setup guidance
title: "Venice AI"
---
# Venice AI
Venice AI provides **privacy-focused AI inference** with support for uncensored models and access to major proprietary models through their anonymized proxy. All inference is private by default — no training on your data, no logging.
## Why Venice in OpenClaw
- **Private inference** for open-source models (no logging).
- **Uncensored models** when you need them.
- **Anonymized access** to proprietary models (Opus/GPT/Gemini) when quality matters.
- OpenAI-compatible `/v1` endpoints.
## Privacy modes
Venice offers two privacy levels — understanding this is key to choosing your model:
| Mode | Description | Models |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| **Private** | Fully private. Prompts/responses are **never stored or logged**. Ephemeral. | Llama, Qwen, DeepSeek, Kimi, MiniMax, Venice Uncensored, etc. |
| **Anonymized** | Proxied through Venice with metadata stripped. The underlying provider (OpenAI, Anthropic, Google, xAI) sees anonymized requests. | Claude, GPT, Gemini, Grok |
<Warning>
Anonymized models are **not** fully private. Venice strips metadata before forwarding, but the underlying provider (OpenAI, Anthropic, Google, xAI) still processes the request. Choose **Private** models when full privacy is required.
</Warning>
## Features
- **Privacy-focused**: Choose between "private" (fully private) and "anonymized" (proxied) modes
- **Uncensored models**: Access to models without content restrictions
- **Major model access**: Use Claude, GPT, Gemini, and Grok via Venice's anonymized proxy
- **OpenAI-compatible API**: Standard `/v1` endpoints for easy integration
- **Streaming**: Supported on all models
- **Function calling**: Supported on select models (check model capabilities)
- **Vision**: Supported on models with vision capability
- **No hard rate limits**: Fair-use throttling may apply for extreme usage
## Getting started
<Steps>
<Step title="Get your API key">
1. Sign up at [venice.ai](https://venice.ai)
2. Go to **Settings > API Keys > Create new key**
3. Copy your API key (format: `vapi_xxxxxxxxxxxx`)
</Step>
<Step title="Configure OpenClaw">
Choose your preferred setup method:
<Tabs>
<Tab title="Interactive (recommended)">
```bash
openclaw onboard --auth-choice venice-api-key
```
This will:
1. Prompt for your API key (or use existing `VENICE_API_KEY`)
2. Show all available Venice models
3. Let you pick your default model
4. Configure the provider automatically
</Tab>
<Tab title="Environment variable">
```bash
export VENICE_API_KEY="vapi_xxxxxxxxxxxx"
```
</Tab>
<Tab title="Non-interactive">
```bash
openclaw onboard --non-interactive \
--auth-choice venice-api-key \
--venice-api-key "vapi_xxxxxxxxxxxx"
```
</Tab>
</Tabs>
</Step>
<Step title="Verify setup">
```bash
openclaw agent --model venice/kimi-k2-5 --message "Hello, are you working?"
```
</Step>
</Steps>
## Model selection
After setup, OpenClaw shows all available Venice models. Pick based on your needs:
- **Default model**: `venice/kimi-k2-5` for strong private reasoning plus vision.
- **High-capability option**: `venice/claude-opus-4-6` for the strongest anonymized Venice path.
- **Privacy**: Choose "private" models for fully private inference.
- **Capability**: Choose "anonymized" models to access Claude, GPT, Gemini via Venice's proxy.
Change your default model anytime:
```bash
openclaw models set venice/kimi-k2-5
openclaw models set venice/claude-opus-4-6
```
List all available models:
```bash
openclaw models list | grep venice
```
You can also run `openclaw configure`, select **Model/auth**, and choose **Venice AI**.
<Tip>
Use the table below to pick the right model for your use case.
| Use Case | Recommended Model | Why |
| -------------------------- | -------------------------------- | -------------------------------------------- |
| **General chat (default)** | `kimi-k2-5` | Strong private reasoning plus vision |
| **Best overall quality** | `claude-opus-4-6` | Strongest anonymized Venice option |
| **Privacy + coding** | `qwen3-coder-480b-a35b-instruct` | Private coding model with large context |
| **Private vision** | `kimi-k2-5` | Vision support without leaving private mode |
| **Fast + cheap** | `qwen3-4b` | Lightweight reasoning model |
| **Complex private tasks** | `deepseek-v3.2` | Strong reasoning, but no Venice tool support |
| **Uncensored** | `venice-uncensored` | No content restrictions |
</Tip>
## Available models (41 total)
<AccordionGroup>
<Accordion title="Private models (26) — fully private, no logging">
| Model ID | Name | Context | Features |
| -------------------------------------- | ----------------------------------- | ------- | -------------------------- |
| `kimi-k2-5` | Kimi K2.5 | 256k | Default, reasoning, vision |
| `kimi-k2-thinking` | Kimi K2 Thinking | 256k | Reasoning |
| `llama-3.3-70b` | Llama 3.3 70B | 128k | General |
| `llama-3.2-3b` | Llama 3.2 3B | 128k | General |
| `hermes-3-llama-3.1-405b` | Hermes 3 Llama 3.1 405B | 128k | General, tools disabled |
| `qwen3-235b-a22b-thinking-2507` | Qwen3 235B Thinking | 128k | Reasoning |
| `qwen3-235b-a22b-instruct-2507` | Qwen3 235B Instruct | 128k | General |
| `qwen3-coder-480b-a35b-instruct` | Qwen3 Coder 480B | 256k | Coding |
| `qwen3-coder-480b-a35b-instruct-turbo` | Qwen3 Coder 480B Turbo | 256k | Coding |
| `qwen3-5-35b-a3b` | Qwen3.5 35B A3B | 256k | Reasoning, vision |
| `qwen3-next-80b` | Qwen3 Next 80B | 256k | General |
| `qwen3-vl-235b-a22b` | Qwen3 VL 235B (Vision) | 256k | Vision |
| `qwen3-4b` | Venice Small (Qwen3 4B) | 32k | Fast, reasoning |
| `deepseek-v3.2` | DeepSeek V3.2 | 160k | Reasoning, tools disabled |
| `venice-uncensored` | Venice Uncensored (Dolphin-Mistral) | 32k | Uncensored, tools disabled |
| `mistral-31-24b` | Venice Medium (Mistral) | 128k | Vision |
| `google-gemma-3-27b-it` | Google Gemma 3 27B Instruct | 198k | Vision |
| `openai-gpt-oss-120b` | OpenAI GPT OSS 120B | 128k | General |
| `nvidia-nemotron-3-nano-30b-a3b` | NVIDIA Nemotron 3 Nano 30B | 128k | General |
| `olafangensan-glm-4.7-flash-heretic` | GLM 4.7 Flash Heretic | 128k | Reasoning |
| `zai-org-glm-4.6` | GLM 4.6 | 198k | General |
| `zai-org-glm-4.7` | GLM 4.7 | 198k | Reasoning |
| `zai-org-glm-4.7-flash` | GLM 4.7 Flash | 128k | Reasoning |
| `zai-org-glm-5` | GLM 5 | 198k | Reasoning |
| `minimax-m21` | MiniMax M2.1 | 198k | Reasoning |
| `minimax-m25` | MiniMax M2.5 | 198k | Reasoning |
</Accordion>
<Accordion title="Anonymized models (15) — via Venice proxy">
| Model ID | Name | Context | Features |
| ------------------------------- | ------------------------------ | ------- | ------------------------- |
| `claude-opus-4-6` | Claude Opus 4.6 (via Venice) | 1M | Reasoning, vision |
| `claude-opus-4-5` | Claude Opus 4.5 (via Venice) | 198k | Reasoning, vision |
| `claude-sonnet-4-6` | Claude Sonnet 4.6 (via Venice) | 1M | Reasoning, vision |
| `claude-sonnet-4-5` | Claude Sonnet 4.5 (via Venice) | 198k | Reasoning, vision |
| `openai-gpt-54` | GPT-5.4 (via Venice) | 1M | Reasoning, vision |
| `openai-gpt-53-codex` | GPT-5.3 Codex (via Venice) | 400k | Reasoning, vision, coding |
| `openai-gpt-52` | GPT-5.2 (via Venice) | 256k | Reasoning |
| `openai-gpt-52-codex` | GPT-5.2 Codex (via Venice) | 256k | Reasoning, vision, coding |
| `openai-gpt-4o-2024-11-20` | GPT-4o (via Venice) | 128k | Vision |
| `openai-gpt-4o-mini-2024-07-18` | GPT-4o Mini (via Venice) | 128k | Vision |
| `gemini-3-1-pro-preview` | Gemini 3.1 Pro (via Venice) | 1M | Reasoning, vision |
| `gemini-3-pro-preview` | Gemini 3 Pro (via Venice) | 198k | Reasoning, vision |
| `gemini-3-flash-preview` | Gemini 3 Flash (via Venice) | 256k | Reasoning, vision |
| `grok-41-fast` | Grok 4.1 Fast (via Venice) | 1M | Reasoning, vision |
| `grok-code-fast-1` | Grok Code Fast 1 (via Venice) | 256k | Reasoning, coding |
</Accordion>
</AccordionGroup>
## Model discovery
OpenClaw automatically discovers models from the Venice API when `VENICE_API_KEY` is set. If the API is unreachable, it falls back to a static catalog.
The `/models` endpoint is public (no auth needed for listing), but inference requires a valid API key.
## Streaming and tool support
| Feature | Support |
| -------------------- | ---------------------------------------------------- |
| **Streaming** | All models |
| **Function calling** | Most models (check `supportsFunctionCalling` in API) |
| **Vision/Images** | Models marked with "Vision" feature |
| **JSON mode** | Supported via `response_format` |
## Pricing
Venice uses a credit-based system. Check [venice.ai/pricing](https://venice.ai/pricing) for current rates:
- **Private models**: Generally lower cost
- **Anonymized models**: Similar to direct API pricing + small Venice fee
### Venice (anonymized) vs direct API
| Aspect | Venice (Anonymized) | Direct API |
| ------------ | ----------------------------- | ------------------- |
| **Privacy** | Metadata stripped, anonymized | Your account linked |
| **Latency** | +10-50ms (proxy) | Direct |
| **Features** | Most features supported | Full features |
| **Billing** | Venice credits | Provider billing |
## Usage examples
```bash
# Use the default private model
openclaw agent --model venice/kimi-k2-5 --message "Quick health check"
# Use Claude Opus via Venice (anonymized)
openclaw agent --model venice/claude-opus-4-6 --message "Summarize this task"
# Use uncensored model
openclaw agent --model venice/venice-uncensored --message "Draft options"
# Use vision model with image
openclaw agent --model venice/qwen3-vl-235b-a22b --message "Review attached image"
# Use coding model
openclaw agent --model venice/qwen3-coder-480b-a35b-instruct --message "Refactor this function"
```
## Troubleshooting
<AccordionGroup>
<Accordion title="API key not recognized">
```bash
echo $VENICE_API_KEY
openclaw models list | grep venice
```
Ensure the key starts with `vapi_`.
</Accordion>
<Accordion title="Model not available">
The Venice model catalog updates dynamically. Run `openclaw models list` to see currently available models. Some models may be temporarily offline.
</Accordion>
<Accordion title="Connection issues">
Venice API is at `https://api.venice.ai/api/v1`. Ensure your network allows HTTPS connections.
</Accordion>
</AccordionGroup>
<Note>
More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq).
</Note>
## Advanced configuration
<AccordionGroup>
<Accordion title="Config file example">
```json5
{
env: { VENICE_API_KEY: "vapi_..." },
agents: { defaults: { model: { primary: "venice/kimi-k2-5" } } },
models: {
mode: "merge",
providers: {
venice: {
baseUrl: "https://api.venice.ai/api/v1",
apiKey: "${VENICE_API_KEY}",
api: "openai-completions",
models: [
{
id: "kimi-k2-5",
name: "Kimi K2.5",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 256000,
maxTokens: 65536,
},
],
},
},
},
}
```
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Venice AI" href="https://venice.ai" icon="globe">
Venice AI homepage and account signup.
</Card>
<Card title="API documentation" href="https://docs.venice.ai" icon="book">
Venice API reference and developer docs.
</Card>
<Card title="Pricing" href="https://venice.ai/pricing" icon="credit-card">
Current Venice credit rates and plans.
</Card>
</CardGroup>

119
openclaw/docs/providers/vercel-ai-gateway.md Normal file
View file

@ -0,0 +1,119 @@
---
title: "Vercel AI Gateway"
summary: "Vercel AI Gateway setup (auth + model selection)"
read_when:
- You want to use Vercel AI Gateway with OpenClaw
- You need the API key env var or CLI auth choice
---
# Vercel AI Gateway
The [Vercel AI Gateway](https://vercel.com/ai-gateway) provides a unified API to
access hundreds of models through a single endpoint.
| Property | Value |
| ------------- | -------------------------------- |
| Provider | `vercel-ai-gateway` |
| Auth | `AI_GATEWAY_API_KEY` |
| API | Anthropic Messages compatible |
| Model catalog | Auto-discovered via `/v1/models` |
<Tip>
OpenClaw auto-discovers the Gateway `/v1/models` catalog, so
`/models vercel-ai-gateway` includes current model refs such as
`vercel-ai-gateway/openai/gpt-5.4`.
</Tip>
## Getting started
<Steps>
<Step title="Set the API key">
Run onboarding and choose the AI Gateway auth option:
```bash
openclaw onboard --auth-choice ai-gateway-api-key
```
</Step>
<Step title="Set a default model">
Add the model to your OpenClaw config:
```json5
{
agents: {
defaults: {
model: { primary: "vercel-ai-gateway/anthropic/claude-opus-4.6" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider vercel-ai-gateway
```
</Step>
</Steps>
## Non-interactive example
For scripted or CI setups, pass all values on the command line:
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice ai-gateway-api-key \
--ai-gateway-api-key "$AI_GATEWAY_API_KEY"
```
## Model ID shorthand
OpenClaw accepts Vercel Claude shorthand model refs and normalizes them at
runtime:
| Shorthand input | Normalized model ref |
| ----------------------------------- | --------------------------------------------- |
| `vercel-ai-gateway/claude-opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
| `vercel-ai-gateway/opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4-6` |
<Tip>
You can use either the shorthand or the fully qualified model ref in your
configuration. OpenClaw resolves the canonical form automatically.
</Tip>
## Advanced notes
<AccordionGroup>
<Accordion title="Environment variable for daemon processes">
If the OpenClaw Gateway runs as a daemon (launchd/systemd), make sure
`AI_GATEWAY_API_KEY` is available to that process.
<Warning>
A key set only in `~/.profile` will not be visible to a launchd/systemd
daemon unless that environment is explicitly imported. Set the key in
`~/.openclaw/.env` or via `env.shellEnv` to ensure the gateway process can
read it.
</Warning>
</Accordion>
<Accordion title="Provider routing">
Vercel AI Gateway routes requests to the upstream provider based on the model
ref prefix. For example, `vercel-ai-gateway/anthropic/claude-opus-4.6` routes
through Anthropic, while `vercel-ai-gateway/openai/gpt-5.4` routes through
OpenAI. Your single `AI_GATEWAY_API_KEY` handles authentication for all
upstream providers.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
General troubleshooting and FAQ.
</Card>
</CardGroup>

204
openclaw/docs/providers/vllm.md Normal file
View file

@ -0,0 +1,204 @@
---
summary: "Run OpenClaw with vLLM (OpenAI-compatible local server)"
read_when:
- You want to run OpenClaw against a local vLLM server
- You want OpenAI-compatible /v1 endpoints with your own models
title: "vLLM"
---
# vLLM
vLLM can serve open-source (and some custom) models via an **OpenAI-compatible** HTTP API. OpenClaw connects to vLLM using the `openai-completions` API.
OpenClaw can also **auto-discover** available models from vLLM when you opt in with `VLLM_API_KEY` (any value works if your server does not enforce auth) and you do not define an explicit `models.providers.vllm` entry.
| Property | Value |
| ---------------- | ---------------------------------------- |
| Provider ID | `vllm` |
| API | `openai-completions` (OpenAI-compatible) |
| Auth | `VLLM_API_KEY` environment variable |
| Default base URL | `http://127.0.0.1:8000/v1` |
## Getting started
<Steps>
<Step title="Start vLLM with an OpenAI-compatible server">
Your base URL should expose `/v1` endpoints (e.g. `/v1/models`, `/v1/chat/completions`). vLLM commonly runs on:
```
http://127.0.0.1:8000/v1
```
</Step>
<Step title="Set the API key environment variable">
Any value works if your server does not enforce auth:
```bash
export VLLM_API_KEY="vllm-local"
```
</Step>
<Step title="Select a model">
Replace with one of your vLLM model IDs:
```json5
{
agents: {
defaults: {
model: { primary: "vllm/your-model-id" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider vllm
```
</Step>
</Steps>
## Model discovery (implicit provider)
When `VLLM_API_KEY` is set (or an auth profile exists) and you **do not** define `models.providers.vllm`, OpenClaw queries:
```
GET http://127.0.0.1:8000/v1/models
```
and converts the returned IDs into model entries.
<Note>
If you set `models.providers.vllm` explicitly, auto-discovery is skipped and you must define models manually.
</Note>
## Explicit configuration (manual models)
Use explicit config when:
- vLLM runs on a different host or port
- You want to pin `contextWindow` or `maxTokens` values
- Your server requires a real API key (or you want to control headers)
```json5
{
models: {
providers: {
vllm: {
baseUrl: "http://127.0.0.1:8000/v1",
apiKey: "${VLLM_API_KEY}",
api: "openai-completions",
models: [
{
id: "your-model-id",
name: "Local vLLM Model",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 128000,
maxTokens: 8192,
},
],
},
},
},
}
```
## Advanced notes
<AccordionGroup>
<Accordion title="Proxy-style behavior">
vLLM is treated as a proxy-style OpenAI-compatible `/v1` backend, not a native
OpenAI endpoint. This means:
| Behavior | Applied? |
|----------|----------|
| Native OpenAI request shaping | No |
| `service_tier` | Not sent |
| Responses `store` | Not sent |
| Prompt-cache hints | Not sent |
| OpenAI reasoning-compat payload shaping | Not applied |
| Hidden OpenClaw attribution headers | Not injected on custom base URLs |
</Accordion>
<Accordion title="Custom base URL">
If your vLLM server runs on a non-default host or port, set `baseUrl` in the explicit provider config:
```json5
{
models: {
providers: {
vllm: {
baseUrl: "http://192.168.1.50:9000/v1",
apiKey: "${VLLM_API_KEY}",
api: "openai-completions",
models: [
{
id: "my-custom-model",
name: "Remote vLLM Model",
reasoning: false,
input: ["text"],
contextWindow: 64000,
maxTokens: 4096,
},
],
},
},
},
}
```
</Accordion>
</AccordionGroup>
## Troubleshooting
<AccordionGroup>
<Accordion title="Server not reachable">
Check that the vLLM server is running and accessible:
```bash
curl http://127.0.0.1:8000/v1/models
```
If you see a connection error, verify the host, port, and that vLLM started with the OpenAI-compatible server mode.
</Accordion>
<Accordion title="Auth errors on requests">
If requests fail with auth errors, set a real `VLLM_API_KEY` that matches your server configuration, or configure the provider explicitly under `models.providers.vllm`.
<Tip>
If your vLLM server does not enforce auth, any non-empty value for `VLLM_API_KEY` works as an opt-in signal for OpenClaw.
</Tip>
</Accordion>
<Accordion title="No models discovered">
Auto-discovery requires `VLLM_API_KEY` to be set **and** no explicit `models.providers.vllm` config entry. If you have defined the provider manually, OpenClaw skips discovery and uses only your declared models.
</Accordion>
</AccordionGroup>
<Warning>
More help: [Troubleshooting](/help/troubleshooting) and [FAQ](/help/faq).
</Warning>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="OpenAI" href="/providers/openai" icon="bolt">
Native OpenAI provider and OpenAI-compatible route behavior.
</Card>
<Card title="OAuth and auth" href="/gateway/authentication" icon="key">
Auth details and credential reuse rules.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
Common issues and how to resolve them.
</Card>
</CardGroup>

143
openclaw/docs/providers/volcengine.md Normal file
View file

@ -0,0 +1,143 @@
---
title: "Volcengine (Doubao)"
summary: "Volcano Engine setup (Doubao models, general + coding endpoints)"
read_when:
- You want to use Volcano Engine or Doubao models with OpenClaw
- You need the Volcengine API key setup
---
# Volcengine (Doubao)
The Volcengine provider gives access to Doubao models and third-party models
hosted on Volcano Engine, with separate endpoints for general and coding
workloads.
| Detail | Value |
| --------- | --------------------------------------------------- |
| Providers | `volcengine` (general) + `volcengine-plan` (coding) |
| Auth | `VOLCANO_ENGINE_API_KEY` |
| API | OpenAI-compatible |
## Getting started
<Steps>
<Step title="Set the API key">
Run interactive onboarding:
```bash
openclaw onboard --auth-choice volcengine-api-key
```
This registers both the general (`volcengine`) and coding (`volcengine-plan`) providers from a single API key.
</Step>
<Step title="Set a default model">
```json5
{
agents: {
defaults: {
model: { primary: "volcengine-plan/ark-code-latest" },
},
},
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider volcengine
openclaw models list --provider volcengine-plan
```
</Step>
</Steps>
<Tip>
For non-interactive setup (CI, scripting), pass the key directly:
```bash
openclaw onboard --non-interactive \
--mode local \
--auth-choice volcengine-api-key \
--volcengine-api-key "$VOLCANO_ENGINE_API_KEY"
```
</Tip>
## Providers and endpoints
| Provider | Endpoint | Use case |
| ----------------- | ----------------------------------------- | -------------- |
| `volcengine` | `ark.cn-beijing.volces.com/api/v3` | General models |
| `volcengine-plan` | `ark.cn-beijing.volces.com/api/coding/v3` | Coding models |
<Note>
Both providers are configured from a single API key. Setup registers both automatically.
</Note>
## Available models
<Tabs>
<Tab title="General (volcengine)">
| Model ref | Name | Input | Context |
| -------------------------------------------- | ------------------------------- | ----------- | ------- |
| `volcengine/doubao-seed-1-8-251228` | Doubao Seed 1.8 | text, image | 256,000 |
| `volcengine/doubao-seed-code-preview-251028` | doubao-seed-code-preview-251028 | text, image | 256,000 |
| `volcengine/kimi-k2-5-260127` | Kimi K2.5 | text, image | 256,000 |
| `volcengine/glm-4-7-251222` | GLM 4.7 | text, image | 200,000 |
| `volcengine/deepseek-v3-2-251201` | DeepSeek V3.2 | text, image | 128,000 |
</Tab>
<Tab title="Coding (volcengine-plan)">
| Model ref | Name | Input | Context |
| ------------------------------------------------- | ------------------------ | ----- | ------- |
| `volcengine-plan/ark-code-latest` | Ark Coding Plan | text | 256,000 |
| `volcengine-plan/doubao-seed-code` | Doubao Seed Code | text | 256,000 |
| `volcengine-plan/glm-4.7` | GLM 4.7 Coding | text | 200,000 |
| `volcengine-plan/kimi-k2-thinking` | Kimi K2 Thinking | text | 256,000 |
| `volcengine-plan/kimi-k2.5` | Kimi K2.5 Coding | text | 256,000 |
| `volcengine-plan/doubao-seed-code-preview-251028` | Doubao Seed Code Preview | text | 256,000 |
</Tab>
</Tabs>
## Advanced notes
<AccordionGroup>
<Accordion title="Default model after onboarding">
`openclaw onboard --auth-choice volcengine-api-key` currently sets
`volcengine-plan/ark-code-latest` as the default model while also registering
the general `volcengine` catalog.
</Accordion>
<Accordion title="Model picker fallback behavior">
During onboarding/configure model selection, the Volcengine auth choice prefers
both `volcengine/*` and `volcengine-plan/*` rows. If those models are not
loaded yet, OpenClaw falls back to the unfiltered catalog instead of showing an
empty provider-scoped picker.
</Accordion>
<Accordion title="Environment variables for daemon processes">
If the Gateway runs as a daemon (launchd/systemd), make sure
`VOLCANO_ENGINE_API_KEY` is available to that process (for example, in
`~/.openclaw/.env` or via `env.shellEnv`).
</Accordion>
</AccordionGroup>
<Warning>
When running OpenClaw as a background service, environment variables set in your
interactive shell are not automatically inherited. See the daemon note above.
</Warning>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration" href="/configuration" icon="gear">
Full config reference for agents, models, and providers.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
Common issues and debugging steps.
</Card>
<Card title="FAQ" href="/help/faq" icon="circle-question">
Frequently asked questions about OpenClaw setup.
</Card>
</CardGroup>

174
openclaw/docs/providers/vydra.md Normal file
View file

@ -0,0 +1,174 @@
---
summary: "Use Vydra image, video, and speech in OpenClaw"
read_when:
- You want Vydra media generation in OpenClaw
- You need Vydra API key setup guidance
title: "Vydra"
---
# Vydra
The bundled Vydra plugin adds:
- Image generation via `vydra/grok-imagine`
- Video generation via `vydra/veo3` and `vydra/kling`
- Speech synthesis via Vydra's ElevenLabs-backed TTS route
OpenClaw uses the same `VYDRA_API_KEY` for all three capabilities.
<Warning>
Use `https://www.vydra.ai/api/v1` as the base URL.
Vydra's apex host (`https://vydra.ai/api/v1`) currently redirects to `www`. Some HTTP clients drop `Authorization` on that cross-host redirect, which turns a valid API key into a misleading auth failure. The bundled plugin uses the `www` base URL directly to avoid that.
</Warning>
## Setup
<Steps>
<Step title="Run interactive onboarding">
```bash
openclaw onboard --auth-choice vydra-api-key
```
Or set the env var directly:
```bash
export VYDRA_API_KEY="vydra_live_..."
```
</Step>
<Step title="Choose a default capability">
Pick one or more of the capabilities below (image, video, or speech) and apply the matching configuration.
</Step>
</Steps>
## Capabilities
<AccordionGroup>
<Accordion title="Image generation">
Default image model:
- `vydra/grok-imagine`
Set it as the default image provider:
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "vydra/grok-imagine",
},
},
},
}
```
Current bundled support is text-to-image only. Vydra's hosted edit routes expect remote image URLs, and OpenClaw does not add a Vydra-specific upload bridge in the bundled plugin yet.
<Note>
See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
</Accordion>
<Accordion title="Video generation">
Registered video models:
- `vydra/veo3` for text-to-video
- `vydra/kling` for image-to-video
Set Vydra as the default video provider:
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "vydra/veo3",
},
},
},
}
```
Notes:
- `vydra/veo3` is bundled as text-to-video only.
- `vydra/kling` currently requires a remote image URL reference. Local file uploads are rejected up front.
- Vydra's current `kling` HTTP route has been inconsistent about whether it requires `image_url` or `video_url`; the bundled provider maps the same remote image URL into both fields.
- The bundled plugin stays conservative and does not forward undocumented style knobs such as aspect ratio, resolution, watermark, or generated audio.
<Note>
See [Video Generation](/tools/video-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
</Accordion>
<Accordion title="Video live tests">
Provider-specific live coverage:
```bash
OPENCLAW_LIVE_TEST=1 \
OPENCLAW_LIVE_VYDRA_VIDEO=1 \
pnpm test:live -- extensions/vydra/vydra.live.test.ts
```
The bundled Vydra live file now covers:
- `vydra/veo3` text-to-video
- `vydra/kling` image-to-video using a remote image URL
Override the remote image fixture when needed:
```bash
export OPENCLAW_LIVE_VYDRA_KLING_IMAGE_URL="https://example.com/reference.png"
```
</Accordion>
<Accordion title="Speech synthesis">
Set Vydra as the speech provider:
```json5
{
messages: {
tts: {
provider: "vydra",
providers: {
vydra: {
apiKey: "${VYDRA_API_KEY}",
voiceId: "21m00Tcm4TlvDq8ikWAM",
},
},
},
},
}
```
Defaults:
- Model: `elevenlabs/tts`
- Voice id: `21m00Tcm4TlvDq8ikWAM`
The bundled plugin currently exposes one known-good default voice and returns MP3 audio files.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Provider directory" href="/providers/index" icon="list">
Browse all available providers.
</Card>
<Card title="Image generation" href="/tools/image-generation" icon="image">
Shared image tool parameters and provider selection.
</Card>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video tool parameters and provider selection.
</Card>
<Card title="Configuration reference" href="/gateway/configuration-reference#agent-defaults" icon="gear">
Agent defaults and model configuration.
</Card>
</CardGroup>

247
openclaw/docs/providers/xai.md Normal file
View file

@ -0,0 +1,247 @@
---
summary: "Use xAI Grok models in OpenClaw"
read_when:
- You want to use Grok models in OpenClaw
- You are configuring xAI auth or model ids
title: "xAI"
---
# xAI
OpenClaw ships a bundled `xai` provider plugin for Grok models.
## Getting started
<Steps>
<Step title="Create an API key">
Create an API key in the [xAI console](https://console.x.ai/).
</Step>
<Step title="Set your API key">
Set `XAI_API_KEY`, or run:
```bash
openclaw onboard --auth-choice xai-api-key
```
</Step>
<Step title="Pick a model">
```json5
{
agents: { defaults: { model: { primary: "xai/grok-4" } } },
}
```
</Step>
</Steps>
<Note>
OpenClaw uses the xAI Responses API as the bundled xAI transport. The same
`XAI_API_KEY` can also power Grok-backed `web_search`, first-class `x_search`,
and remote `code_execution`.
If you store an xAI key under `plugins.entries.xai.config.webSearch.apiKey`,
the bundled xAI model provider reuses that key as a fallback too.
`code_execution` tuning lives under `plugins.entries.xai.config.codeExecution`.
</Note>
## Bundled model catalog
OpenClaw includes these xAI model families out of the box:
| Family | Model ids |
| -------------- | ------------------------------------------------------------------------ |
| Grok 3 | `grok-3`, `grok-3-fast`, `grok-3-mini`, `grok-3-mini-fast` |
| Grok 4 | `grok-4`, `grok-4-0709` |
| Grok 4 Fast | `grok-4-fast`, `grok-4-fast-non-reasoning` |
| Grok 4.1 Fast | `grok-4-1-fast`, `grok-4-1-fast-non-reasoning` |
| Grok 4.20 Beta | `grok-4.20-beta-latest-reasoning`, `grok-4.20-beta-latest-non-reasoning` |
| Grok Code | `grok-code-fast-1` |
The plugin also forward-resolves newer `grok-4*` and `grok-code-fast*` ids when
they follow the same API shape.
<Tip>
`grok-4-fast`, `grok-4-1-fast`, and the `grok-4.20-beta-*` variants are the
current image-capable Grok refs in the bundled catalog.
</Tip>
### Fast-mode mappings
`/fast on` or `agents.defaults.models["xai/<model>"].params.fastMode: true`
rewrites native xAI requests as follows:
| Source model | Fast-mode target |
| ------------- | ------------------ |
| `grok-3` | `grok-3-fast` |
| `grok-3-mini` | `grok-3-mini-fast` |
| `grok-4` | `grok-4-fast` |
| `grok-4-0709` | `grok-4-fast` |
### Legacy compatibility aliases
Legacy aliases still normalize to the canonical bundled ids:
| Legacy alias | Canonical id |
| ------------------------- | ------------------------------------- |
| `grok-4-fast-reasoning` | `grok-4-fast` |
| `grok-4-1-fast-reasoning` | `grok-4-1-fast` |
| `grok-4.20-reasoning` | `grok-4.20-beta-latest-reasoning` |
| `grok-4.20-non-reasoning` | `grok-4.20-beta-latest-non-reasoning` |
## Features
<AccordionGroup>
<Accordion title="Web search">
The bundled `grok` web-search provider uses `XAI_API_KEY` too:
```bash
openclaw config set tools.web.search.provider grok
```
</Accordion>
<Accordion title="Video generation">
The bundled `xai` plugin registers video generation through the shared
`video_generate` tool.
- Default video model: `xai/grok-imagine-video`
- Modes: text-to-video, image-to-video, and remote video edit/extend flows
- Supports `aspectRatio` and `resolution`
<Warning>
Local video buffers are not accepted. Use remote `http(s)` URLs for
video-reference and edit inputs.
</Warning>
To use xAI as the default video provider:
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "xai/grok-imagine-video",
},
},
},
}
```
<Note>
See [Video Generation](/tools/video-generation) for shared tool parameters,
provider selection, and failover behavior.
</Note>
</Accordion>
<Accordion title="x_search configuration">
The bundled xAI plugin exposes `x_search` as an OpenClaw tool for searching
X (formerly Twitter) content via Grok.
Config path: `plugins.entries.xai.config.xSearch`
| Key | Type | Default | Description |
| ------------------ | ------- | ------------------ | ------------------------------------ |
| `enabled` | boolean | — | Enable or disable x_search |
| `model` | string | `grok-4-1-fast` | Model used for x_search requests |
| `inlineCitations` | boolean | — | Include inline citations in results |
| `maxTurns` | number | — | Maximum conversation turns |
| `timeoutSeconds` | number | — | Request timeout in seconds |
| `cacheTtlMinutes` | number | — | Cache time-to-live in minutes |
```json5
{
plugins: {
entries: {
xai: {
config: {
xSearch: {
enabled: true,
model: "grok-4-1-fast",
inlineCitations: true,
},
},
},
},
},
}
```
</Accordion>
<Accordion title="Code execution configuration">
The bundled xAI plugin exposes `code_execution` as an OpenClaw tool for
remote code execution in xAI's sandbox environment.
Config path: `plugins.entries.xai.config.codeExecution`
| Key | Type | Default | Description |
| ----------------- | ------- | ------------------ | ---------------------------------------- |
| `enabled` | boolean | `true` (if key available) | Enable or disable code execution |
| `model` | string | `grok-4-1-fast` | Model used for code execution requests |
| `maxTurns` | number | — | Maximum conversation turns |
| `timeoutSeconds` | number | — | Request timeout in seconds |
<Note>
This is remote xAI sandbox execution, not local [`exec`](/tools/exec).
</Note>
```json5
{
plugins: {
entries: {
xai: {
config: {
codeExecution: {
enabled: true,
model: "grok-4-1-fast",
},
},
},
},
},
}
```
</Accordion>
<Accordion title="Known limits">
- Auth is API-key only today. There is no xAI OAuth or device-code flow in
OpenClaw yet.
- `grok-4.20-multi-agent-experimental-beta-0304` is not supported on the
normal xAI provider path because it requires a different upstream API
surface than the standard OpenClaw xAI transport.
</Accordion>
<Accordion title="Advanced notes">
- OpenClaw applies xAI-specific tool-schema and tool-call compatibility fixes
automatically on the shared runner path.
- Native xAI requests default `tool_stream: true`. Set
`agents.defaults.models["xai/<model>"].params.tool_stream` to `false` to
disable it.
- The bundled xAI wrapper strips unsupported strict tool-schema flags and
reasoning payload keys before sending native xAI requests.
- `web_search`, `x_search`, and `code_execution` are exposed as OpenClaw
tools. OpenClaw enables the specific xAI built-in it needs inside each tool
request instead of attaching all native tools to every chat turn.
- `x_search` and `code_execution` are owned by the bundled xAI plugin rather
than hardcoded into the core model runtime.
- `code_execution` is remote xAI sandbox execution, not local
[`exec`](/tools/exec).
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Video generation" href="/tools/video-generation" icon="video">
Shared video tool parameters and provider selection.
</Card>
<Card title="All providers" href="/providers/index" icon="grid-2">
The broader provider overview.
</Card>
<Card title="Troubleshooting" href="/help/troubleshooting" icon="wrench">
Common issues and fixes.
</Card>
</CardGroup>

145
openclaw/docs/providers/xiaomi.md Normal file
View file

@ -0,0 +1,145 @@
---
summary: "Use Xiaomi MiMo models with OpenClaw"
read_when:
- You want Xiaomi MiMo models in OpenClaw
- You need XIAOMI_API_KEY setup
title: "Xiaomi MiMo"
---
# Xiaomi MiMo
Xiaomi MiMo is the API platform for **MiMo** models. OpenClaw uses the Xiaomi
OpenAI-compatible endpoint with API-key authentication.
| Property | Value |
| -------- | ------------------------------- |
| Provider | `xiaomi` |
| Auth | `XIAOMI_API_KEY` |
| API | OpenAI-compatible |
| Base URL | `https://api.xiaomimimo.com/v1` |
## Getting started
<Steps>
<Step title="Get an API key">
Create an API key in the [Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys).
</Step>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice xiaomi-api-key
```
Or pass the key directly:
```bash
openclaw onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY"
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider xiaomi
```
</Step>
</Steps>
## Available models
| Model ref | Input | Context | Max output | Reasoning | Notes |
| ---------------------- | ----------- | --------- | ---------- | --------- | ------------- |
| `xiaomi/mimo-v2-flash` | text | 262,144 | 8,192 | No | Default model |
| `xiaomi/mimo-v2-pro` | text | 1,048,576 | 32,000 | Yes | Large context |
| `xiaomi/mimo-v2-omni` | text, image | 262,144 | 32,000 | Yes | Multimodal |
<Tip>
The default model ref is `xiaomi/mimo-v2-flash`. The provider is injected automatically when `XIAOMI_API_KEY` is set or an auth profile exists.
</Tip>
## Config example
```json5
{
env: { XIAOMI_API_KEY: "your-key" },
agents: { defaults: { model: { primary: "xiaomi/mimo-v2-flash" } } },
models: {
mode: "merge",
providers: {
xiaomi: {
baseUrl: "https://api.xiaomimimo.com/v1",
api: "openai-completions",
apiKey: "XIAOMI_API_KEY",
models: [
{
id: "mimo-v2-flash",
name: "Xiaomi MiMo V2 Flash",
reasoning: false,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 8192,
},
{
id: "mimo-v2-pro",
name: "Xiaomi MiMo V2 Pro",
reasoning: true,
input: ["text"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 1048576,
maxTokens: 32000,
},
{
id: "mimo-v2-omni",
name: "Xiaomi MiMo V2 Omni",
reasoning: true,
input: ["text", "image"],
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
contextWindow: 262144,
maxTokens: 32000,
},
],
},
},
},
}
```
<AccordionGroup>
<Accordion title="Auto-injection behavior">
The `xiaomi` provider is injected automatically when `XIAOMI_API_KEY` is set in your environment or an auth profile exists. You do not need to manually configure the provider unless you want to override model metadata or the base URL.
</Accordion>
<Accordion title="Model details">
- **mimo-v2-flash** — lightweight and fast, ideal for general-purpose text tasks. No reasoning support.
- **mimo-v2-pro** — supports reasoning with a 1M token context window for long-document workloads.
- **mimo-v2-omni** — reasoning-enabled multimodal model that accepts both text and image inputs.
<Note>
All models use the `xiaomi/` prefix (for example `xiaomi/mimo-v2-pro`).
</Note>
</Accordion>
<Accordion title="Troubleshooting">
- If models do not appear, confirm `XIAOMI_API_KEY` is set and valid.
- When the Gateway runs as a daemon, ensure the key is available to that process (for example in `~/.openclaw/.env` or via `env.shellEnv`).
<Warning>
Keys set only in your interactive shell are not visible to daemon-managed gateway processes. Use `~/.openclaw/.env` or `env.shellEnv` config for persistent availability.
</Warning>
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
<Card title="Configuration reference" href="/gateway/configuration" icon="gear">
Full OpenClaw configuration reference.
</Card>
<Card title="Xiaomi MiMo console" href="https://platform.xiaomimimo.com" icon="arrow-up-right-from-square">
Xiaomi MiMo dashboard and API key management.
</Card>
</CardGroup>

165
openclaw/docs/providers/zai.md Normal file
View file

@ -0,0 +1,165 @@
---
summary: "Use Z.AI (GLM models) with OpenClaw"
read_when:
- You want Z.AI / GLM models in OpenClaw
- You need a simple ZAI_API_KEY setup
title: "Z.AI"
---
# Z.AI
Z.AI is the API platform for **GLM** models. It provides REST APIs for GLM and uses API keys
for authentication. Create your API key in the Z.AI console. OpenClaw uses the `zai` provider
with a Z.AI API key.
- Provider: `zai`
- Auth: `ZAI_API_KEY`
- API: Z.AI Chat Completions (Bearer auth)
## Getting started
<Tabs>
<Tab title="Auto-detect endpoint">
**Best for:** most users. OpenClaw detects the matching Z.AI endpoint from the key and applies the correct base URL automatically.
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice zai-api-key
```
</Step>
<Step title="Set a default model">
```json5
{
env: { ZAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider zai
```
</Step>
</Steps>
</Tab>
<Tab title="Explicit regional endpoint">
**Best for:** users who want to force a specific Coding Plan or general API surface.
<Steps>
<Step title="Pick the right onboarding choice">
```bash
# Coding Plan Global (recommended for Coding Plan users)
openclaw onboard --auth-choice zai-coding-global
# Coding Plan CN (China region)
openclaw onboard --auth-choice zai-coding-cn
# General API
openclaw onboard --auth-choice zai-global
# General API CN (China region)
openclaw onboard --auth-choice zai-cn
```
</Step>
<Step title="Set a default model">
```json5
{
env: { ZAI_API_KEY: "sk-..." },
agents: { defaults: { model: { primary: "zai/glm-5.1" } } },
}
```
</Step>
<Step title="Verify the model is available">
```bash
openclaw models list --provider zai
```
</Step>
</Steps>
</Tab>
</Tabs>
## Bundled GLM catalog
OpenClaw currently seeds the bundled `zai` provider with:
| Model ref | Notes |
| -------------------- | ------------- |
| `zai/glm-5.1` | Default model |
| `zai/glm-5` | |
| `zai/glm-5-turbo` | |
| `zai/glm-5v-turbo` | |
| `zai/glm-4.7` | |
| `zai/glm-4.7-flash` | |
| `zai/glm-4.7-flashx` | |
| `zai/glm-4.6` | |
| `zai/glm-4.6v` | |
| `zai/glm-4.5` | |
| `zai/glm-4.5-air` | |
| `zai/glm-4.5-flash` | |
| `zai/glm-4.5v` | |
<Tip>
GLM models are available as `zai/<model>` (example: `zai/glm-5`). The default bundled model ref is `zai/glm-5.1`.
</Tip>
## Advanced configuration
<AccordionGroup>
<Accordion title="Forward-resolving unknown GLM-5 models">
Unknown `glm-5*` ids still forward-resolve on the bundled provider path by
synthesizing provider-owned metadata from the `glm-4.7` template when the id
matches the current GLM-5 family shape.
</Accordion>
<Accordion title="Tool-call streaming">
`tool_stream` is enabled by default for Z.AI tool-call streaming. To disable it:
```json5
{
agents: {
defaults: {
models: {
"zai/<model>": {
params: { tool_stream: false },
},
},
},
},
}
```
</Accordion>
<Accordion title="Image understanding">
The bundled Z.AI plugin registers image understanding.
| Property | Value |
| ------------- | ----------- |
| Model | `glm-4.6v` |
Image understanding is auto-resolved from the configured Z.AI auth — no
additional config is needed.
</Accordion>
<Accordion title="Auth details">
- Z.AI uses Bearer auth with your API key.
- The `zai-api-key` onboarding choice auto-detects the matching Z.AI endpoint from the key prefix.
- Use the explicit regional choices (`zai-coding-global`, `zai-coding-cn`, `zai-global`, `zai-cn`) when you want to force a specific API surface.
</Accordion>
</AccordionGroup>
## Related
<CardGroup cols={2}>
<Card title="GLM model family" href="/providers/glm" icon="microchip">
Model family overview for GLM.
</Card>
<Card title="Model selection" href="/concepts/model-providers" icon="layers">
Choosing providers, model refs, and failover behavior.
</Card>
</CardGroup>