Mirrors/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-04-21 08:43:37 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs(providers): improve claude-max-api-proxy, litellm, stepfun, vydra, xai with Mintlify components

Browse Source
This commit is contained in:
Vincent Koc
2026-04-12 11:17:29 +01:00
parent 5959c9927e
commit 81d32c05f4
5 changed files with 677 additions and 449 deletions
Download Patch File Download Diff File Expand all files Collapse all files

205
docs/providers/claude-max-api-proxy.md
View File

@@ -17,7 +17,7 @@ usage outside Claude Code in the past. You must decide for yourself whether to u
it and verify Anthropic's current terms before relying on it.
</Warning>
## Why Use This?
## Why use this?
| Approach | Cost | Best For |
| ----------------------- | --------------------------------------------------- | ------------------------------------------ |
@@ -26,7 +26,7 @@ it and verify Anthropic's current terms before relying on it.
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
## How it works
```
Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription)
@@ -39,71 +39,65 @@ The proxy:
2. Converts them to Claude Code CLI commands
3. Returns responses in OpenAI format (streaming supported)
## Installation
## Getting started
```bash
# Requires Node.js 20+ and Claude Code CLI
npm install -g claude-max-api-proxy
<Steps>
<Step title="Install the proxy">
Requires Node.js 20+ and Claude Code CLI.
# Verify Claude CLI is authenticated
claude --version
```
```bash
npm install -g claude-max-api-proxy
## Usage
# Verify Claude CLI is authenticated
claude --version
```
### Start the server
</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
```bash
claude-max-api
# Server runs at http://localhost:3456
```
# List models
curl http://localhost:3456/v1/models
### Test it
# Chat completion
curl http://localhost:3456/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "claude-opus-4",
"messages": [{"role": "user", "content": "Hello!"}]
}'
```
```bash
# Health check
curl http://localhost:3456/health
</Step>
<Step title="Configure OpenClaw">
Point OpenClaw at the proxy as a custom OpenAI-compatible endpoint:
# List models
curl http://localhost:3456/v1/models
```json5
{
env: {
OPENAI_API_KEY: "not-needed",
OPENAI_BASE_URL: "http://localhost:3456/v1",
},
agents: {
defaults: {
model: { primary: "openai/claude-opus-4" },
},
},
}
```
# 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>
</Steps>
### With OpenClaw
You can 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" },
},
},
}
```
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
## Available Models
## Available models
| Model ID | Maps To |
| ----------------- | --------------- |
@@ -111,38 +105,55 @@ This path uses the same proxy-style OpenAI-compatible route as other custom
| `claude-sonnet-4` | Claude Sonnet 4 |
| `claude-haiku-4` | Claude Haiku 4 |
## Auto-Start on macOS
## Advanced
Create a LaunchAgent to run the proxy automatically:
<AccordionGroup>
<Accordion title="Proxy-style OpenAI-compatible notes">
This path uses the same proxy-style OpenAI-compatible route as other custom
`/v1` backends:
```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
- 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
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
```
</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
@@ -157,7 +168,23 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
- The proxy runs locally and does not send data to any third-party servers
- Streaming responses are fully supported
## See Also
<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>
- [Anthropic provider](/providers/anthropic) - Native OpenClaw integration with Claude CLI or API keys
- [OpenAI provider](/providers/openai) - For OpenAI/Codex subscriptions
## 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>

172
docs/providers/litellm.md
View File

@@ -10,40 +10,55 @@ read_when:
[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.
## Why use LiteLLM with OpenClaw?
<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
### Via onboarding
<Tabs>
<Tab title="Onboarding (recommended)">
**Best for:** fastest path to a working LiteLLM setup.
```bash
openclaw onboard --auth-choice litellm-api-key
```
<Steps>
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice litellm-api-key
```
</Step>
</Steps>
### Manual setup
</Tab>
1. Start LiteLLM Proxy:
<Tab title="Manual setup">
**Best for:** full control over installation and config.
```bash
pip install 'litellm[proxy]'
litellm --model claude-opus-4-6
```
<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"
2. Point OpenClaw to LiteLLM:
openclaw
```
```bash
export LITELLM_API_KEY="your-litellm-key"
That's it. OpenClaw now routes through LiteLLM.
</Step>
</Steps>
openclaw
```
That's it. OpenClaw now routes through LiteLLM.
</Tab>
</Tabs>
## Configuration
@@ -92,68 +107,91 @@ export LITELLM_API_KEY="sk-litellm-key"
}
```
## Virtual keys
## Advanced topics
Create a dedicated key for OpenClaw with spend limits:
<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"
}'
```
```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`.
Use the generated key as `LITELLM_API_KEY`.
## Model routing
</Accordion>
LiteLLM can route model requests to different backends. Configure in your LiteLLM `config.yaml`:
<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
```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
```
- 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.
OpenClaw keeps requesting `claude-opus-4-6` — LiteLLM handles the routing.
## Viewing usage
</Accordion>
Check LiteLLM's dashboard or API:
<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"
```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"
```
# Spend logs
curl "http://localhost:4000/spend/logs" \
-H "Authorization: Bearer $LITELLM_MASTER_KEY"
```
## Notes
</Accordion>
- 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 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>
## See also
<Note>
For general provider configuration and failover behavior, see [Model Providers](/concepts/model-providers).
</Note>
- [LiteLLM Docs](https://docs.litellm.ai)
- [Model Providers](/concepts/model-providers)
## 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>

294
docs/providers/stepfun.md
View File

@@ -13,49 +13,18 @@ OpenClaw includes a bundled StepFun provider plugin with two provider ids:
- `stepfun` for the standard endpoint
- `stepfun-plan` for the Step Plan endpoint
The built-in catalogs currently differ by surface:
- Standard: `step-3.5-flash`
- Step Plan: `step-3.5-flash`, `step-3.5-flash-2603`
<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
- China standard endpoint: `https://api.stepfun.com/v1`
- Global standard endpoint: `https://api.stepfun.ai/v1`
- China Step Plan endpoint: `https://api.stepfun.com/step_plan/v1`
- Global Step Plan endpoint: `https://api.stepfun.ai/step_plan/v1`
- Auth env var: `STEPFUN_API_KEY`
| 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` |
Use a China key with the `.com` endpoints and a global key with the `.ai`
endpoints.
## CLI setup
Interactive setup:
```bash
openclaw onboard
```
Choose one of these auth choices:
- `stepfun-standard-api-key-cn`
- `stepfun-standard-api-key-intl`
- `stepfun-plan-api-key-cn`
- `stepfun-plan-api-key-intl`
Non-interactive examples:
```bash
openclaw onboard --auth-choice stepfun-standard-api-key-intl --stepfun-api-key "$STEPFUN_API_KEY"
openclaw onboard --auth-choice stepfun-plan-api-key-intl --stepfun-api-key "$STEPFUN_API_KEY"
```
## Model refs
- Standard default model: `stepfun/step-3.5-flash`
- Step Plan default model: `stepfun-plan/step-3.5-flash`
- Step Plan alternate model: `stepfun-plan/step-3.5-flash-2603`
Auth env var: `STEPFUN_API_KEY`
## Built-in catalogs
@@ -72,81 +41,190 @@ Step Plan (`stepfun-plan`):
| `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 |
## Config snippets
## Getting started
Standard provider:
Choose your provider surface and follow the setup steps.
```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,
<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>
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,
<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,
},
],
},
{
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>
## Notes
<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>
- 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.
- For the broader provider overview, see [Model providers](/concepts/model-providers).
<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>

245
docs/providers/vydra.md
View File

@@ -10,134 +10,165 @@ title: "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
- 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.
## Important base URL
Use `https://www.vydra.ai/api/v1`.
<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
Interactive onboarding:
<Steps>
<Step title="Run interactive onboarding">
```bash
openclaw onboard --auth-choice vydra-api-key
```
```bash
openclaw onboard --auth-choice vydra-api-key
```
Or set the env var directly:
Or set the env var directly:
```bash
export VYDRA_API_KEY="vydra_live_..."
```
```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>
## Image generation
## Capabilities
Default image model:
<AccordionGroup>
<Accordion title="Image generation">
Default image model:
- `vydra/grok-imagine`
- `vydra/grok-imagine`
Set it as the default image provider:
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.
See [Image Generation](/tools/image-generation) for shared tool behavior.
## 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.
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"
```
See [Video Generation](/tools/video-generation) for shared tool behavior.
## Speech synthesis
Set Vydra as the speech provider:
```json5
{
messages: {
tts: {
provider: "vydra",
providers: {
vydra: {
apiKey: "${VYDRA_API_KEY}",
voiceId: "21m00Tcm4TlvDq8ikWAM",
```json5
{
agents: {
defaults: {
imageGenerationModel: {
primary: "vydra/grok-imagine",
},
},
},
},
},
}
```
}
```
Defaults:
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.
- model: `elevenlabs/tts`
- voice id: `21m00Tcm4TlvDq8ikWAM`
<Note>
See [Image Generation](/tools/image-generation) for shared tool parameters, provider selection, and failover behavior.
</Note>
The bundled plugin currently exposes one known-good default voice and returns MP3 audio files.
</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
- [Provider Directory](/providers/index)
- [Image Generation](/tools/image-generation)
- [Video Generation](/tools/video-generation)
<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>

210
docs/providers/xai.md
View File

@@ -10,113 +10,167 @@ title: "xAI"
OpenClaw ships a bundled `xai` provider plugin for Grok models.
## Setup
## Getting started
1. Create an API key in the xAI console.
2. Set `XAI_API_KEY`, or run:
<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
```
```bash
openclaw onboard --auth-choice xai-api-key
```
3. Pick a model such as:
</Step>
<Step title="Pick a model">
```json5
{
agents: { defaults: { model: { primary: "xai/grok-4" } } },
}
```
</Step>
</Steps>
```json5
{
agents: { defaults: { model: { primary: "xai/grok-4" } } },
}
```
OpenClaw now uses the xAI Responses API as the bundled xAI transport. The same
<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 now reuses that key as a fallback too.
the bundled xAI model provider reuses that key as a fallback too.
`code_execution` tuning lives under `plugins.entries.xai.config.codeExecution`.
</Note>
## Current bundled model catalog
## Bundled model catalog
OpenClaw now includes these xAI model families out of the box:
OpenClaw includes these xAI model families out of the box:
- `grok-3`, `grok-3-fast`, `grok-3-mini`, `grok-3-mini-fast`
- `grok-4`, `grok-4-0709`
- `grok-4-fast`, `grok-4-fast-non-reasoning`
- `grok-4-1-fast`, `grok-4-1-fast-non-reasoning`
- `grok-4.20-beta-latest-reasoning`, `grok-4.20-beta-latest-non-reasoning`
- `grok-code-fast-1`
| 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.
Fast-model notes:
<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>
- `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.
- `/fast on` or `agents.defaults.models["xai/<model>"].params.fastMode: true`
rewrites native xAI requests as follows:
- `grok-3` -> `grok-3-fast`
- `grok-3-mini` -> `grok-3-mini-fast`
- `grok-4` -> `grok-4-fast`
- `grok-4-0709` -> `grok-4-fast`
### Fast-mode mappings
Legacy compatibility aliases still normalize to the canonical bundled ids. For
example:
`/fast on` or `agents.defaults.models["xai/<model>"].params.fastMode: true`
rewrites native xAI requests as follows:
- `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`
| 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` |
## Web search
### Legacy compatibility aliases
The bundled `grok` web-search provider uses `XAI_API_KEY` too:
Legacy aliases still normalize to the canonical bundled ids:
```bash
openclaw config set tools.web.search.provider grok
```
| 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` |
## Video generation
## Features
The bundled `xai` plugin also registers video generation through the shared
`video_generate` tool.
<AccordionGroup>
<Accordion title="Web search">
The bundled `grok` web-search provider uses `XAI_API_KEY` too:
- Default video model: `xai/grok-imagine-video`
- Modes: text-to-video, image-to-video, and remote video edit/extend flows
- Supports `aspectRatio` and `resolution`
- Current limit: local video buffers are not accepted; use remote `http(s)`
URLs for video-reference/edit inputs
```bash
openclaw config set tools.web.search.provider grok
```
To use xAI as the default video provider:
</Accordion>
```json5
{
agents: {
defaults: {
videoGenerationModel: {
primary: "xai/grok-imagine-video",
<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",
},
},
},
},
},
}
```
}
```
See [Video Generation](/tools/video-generation) for the shared tool
parameters, provider selection, and failover behavior.
<Note>
See [Video Generation](/tools/video-generation) for shared tool parameters,
provider selection, and failover behavior.
</Note>
## Known limits
</Accordion>
- Auth is API-key only today. There is no xAI OAuth/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 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>
## Notes
<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>
- 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).
- For the broader provider overview, see [Model providers](/providers/index).
## 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>