chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
25d3a0641d
commit
6f33330176
@ -2,152 +2,160 @@
|
||||
read_when:
|
||||
- 你想将 Claude Max 订阅与兼容 OpenAI 的工具一起使用
|
||||
- 你想要一个封装 Claude Code CLI 的本地 API 服务器
|
||||
- 你想评估基于订阅和基于 API 密钥的 Anthropic 访问方式
|
||||
- 你想评估基于订阅与基于 API 密钥的 Anthropic 访问方式
|
||||
summary: 将 Claude 订阅凭证暴露为与 OpenAI 兼容端点的社区代理
|
||||
title: Claude Max API 代理
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:41:42Z"
|
||||
generated_at: "2026-04-12T10:19:18Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2e125a6a46e48371544adf1331137a1db51e93e905b8c44da482cf2fba180a09
|
||||
source_hash: 534bc3d189e68529fb090258eb0d6db6d367eb7e027ad04b1f0be55f6aa7d889
|
||||
source_path: providers/claude-max-api-proxy.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Claude Max API 代理
|
||||
|
||||
**claude-max-api-proxy** 是一个社区工具，可将你的 Claude Max/Pro 订阅暴露为与 OpenAI 兼容的 API 端点。这样你就可以在任何支持 OpenAI API 格式的工具中使用你的订阅。
|
||||
**claude-max-api-proxy** 是一个社区工具，可将你的 Claude Max/Pro 订阅暴露为与 OpenAI 兼容的 API 端点。这让你能够在任何支持 OpenAI API 格式的工具中使用你的订阅。
|
||||
|
||||
<Warning>
|
||||
这条路径仅用于技术兼容性。Anthropic 过去曾阻止过一些在 Claude Code 之外的订阅
|
||||
用法。你必须自行决定是否使用它，并在依赖它之前核实 Anthropic 当前的条款。
|
||||
这条路径仅提供技术兼容性。Anthropic 过去曾阻止在 Claude Code 之外使用某些订阅用法。你必须自行决定是否使用它，并在依赖它之前核实 Anthropic 当前的条款。
|
||||
</Warning>
|
||||
|
||||
## 为什么使用这个？
|
||||
|
||||
| 方式 | 成本 | 最适合 |
|
||||
| ----------------------- | --------------------------------------------------- | --------------------------------------- |
|
||||
| Anthropic API | 按 token 付费（Opus 约为输入 $15/M，输出 $75/M） | 生产应用、高调用量 |
|
||||
| Claude Max 订阅 | 每月固定 $200 | 个人使用、开发、无限使用量 |
|
||||
| 方式 | 成本 | 最适合 |
|
||||
| ----------------------- | --------------------------------------------------- | ------------------------------------------ |
|
||||
| Anthropic API | 按 token 付费（Opus 约为输入 $15/M、输出 $75/M） | 生产应用、高使用量 |
|
||||
| Claude Max subscription | 每月固定 $200 | 个人使用、开发、无限使用 |
|
||||
|
||||
如果你有 Claude Max 订阅，并希望将其与兼容 OpenAI 的工具一起使用，那么这个代理可能会降低某些工作流的成本。对于生产用途，API 密钥仍然是更明确的策略路径。
|
||||
如果你有 Claude Max 订阅，并希望将它与兼容 OpenAI 的工具一起使用，这个代理可能会在某些工作流中降低成本。对于生产用途，API 密钥仍然是政策上更明确的路径。
|
||||
|
||||
## 工作原理
|
||||
|
||||
```
|
||||
你的应用 → claude-max-api-proxy → Claude Code CLI → Anthropic（通过订阅）
|
||||
（OpenAI 格式） （转换格式） （使用你的登录）
|
||||
Your App → claude-max-api-proxy → Claude Code CLI → Anthropic (via subscription)
|
||||
(OpenAI format) (converts format) (uses your login)
|
||||
```
|
||||
|
||||
该代理会：
|
||||
|
||||
1. 在 `http://localhost:3456/v1/chat/completions` 接收 OpenAI 格式请求
|
||||
1. 在 `http://localhost:3456/v1/chat/completions` 接收 OpenAI 格式的请求
|
||||
2. 将它们转换为 Claude Code CLI 命令
|
||||
3. 以 OpenAI 格式返回响应（支持流式传输）
|
||||
|
||||
## 安装
|
||||
## 入门指南
|
||||
|
||||
```bash
|
||||
# 需要 Node.js 20+ 和 Claude Code CLI
|
||||
npm install -g claude-max-api-proxy
|
||||
<Steps>
|
||||
<Step title="安装代理">
|
||||
需要 Node.js 20+ 和 Claude Code CLI。
|
||||
|
||||
# 验证 Claude CLI 已认证
|
||||
claude --version
|
||||
```
|
||||
```bash
|
||||
npm install -g claude-max-api-proxy
|
||||
|
||||
## 用法
|
||||
# 验证 Claude CLI 已完成身份验证
|
||||
claude --version
|
||||
```
|
||||
|
||||
### 启动服务器
|
||||
</Step>
|
||||
<Step title="启动服务器">
|
||||
```bash
|
||||
claude-max-api
|
||||
# 服务器运行在 http://localhost:3456
|
||||
```
|
||||
</Step>
|
||||
<Step title="测试代理">
|
||||
```bash
|
||||
# 健康检查
|
||||
curl http://localhost:3456/health
|
||||
|
||||
```bash
|
||||
claude-max-api
|
||||
# 服务器运行在 http://localhost:3456
|
||||
```
|
||||
# 列出模型
|
||||
curl http://localhost:3456/v1/models
|
||||
|
||||
### 测试
|
||||
# 聊天补全
|
||||
curl http://localhost:3456/v1/chat/completions \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"model": "claude-opus-4",
|
||||
"messages": [{"role": "user", "content": "Hello!"}]
|
||||
}'
|
||||
```
|
||||
|
||||
```bash
|
||||
# 健康检查
|
||||
curl http://localhost:3456/health
|
||||
</Step>
|
||||
<Step title="配置 OpenClaw">
|
||||
将 OpenClaw 指向该代理，作为一个自定义的与 OpenAI 兼容的端点：
|
||||
|
||||
# 列出模型
|
||||
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!"}]
|
||||
}'
|
||||
```
|
||||
|
||||
### 配合 OpenClaw 使用
|
||||
|
||||
你可以将 OpenClaw 指向该代理，把它当作自定义的 OpenAI 兼容端点：
|
||||
|
||||
```json5
|
||||
{
|
||||
env: {
|
||||
OPENAI_API_KEY: "not-needed",
|
||||
OPENAI_BASE_URL: "http://localhost:3456/v1",
|
||||
},
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "openai/claude-opus-4" },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
这条路径使用与其他自定义
|
||||
`/v1` 后端相同的代理式 OpenAI 兼容路由：
|
||||
|
||||
- 不适用原生 OpenAI 专属请求塑形
|
||||
- 没有 `service_tier`、没有 Responses `store`、没有 prompt-cache 提示，也没有
|
||||
OpenAI reasoning-compat 载荷塑形
|
||||
- 不会在代理 URL 上注入隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 可用模型
|
||||
|
||||
| 模型 ID | 映射到 |
|
||||
| ------------------ | ---------------- |
|
||||
| `claude-opus-4` | Claude Opus 4 |
|
||||
| `claude-sonnet-4` | Claude Sonnet 4 |
|
||||
| `claude-haiku-4` | Claude Haiku 4 |
|
||||
| 模型 ID | 映射到 |
|
||||
| ----------------- | --------------- |
|
||||
| `claude-opus-4` | Claude Opus 4 |
|
||||
| `claude-sonnet-4` | Claude Sonnet 4 |
|
||||
| `claude-haiku-4` | Claude Haiku 4 |
|
||||
|
||||
## 在 macOS 上自动启动
|
||||
## 高级
|
||||
|
||||
创建一个 LaunchAgent，以自动运行该代理：
|
||||
<AccordionGroup>
|
||||
<Accordion title="代理式 OpenAI 兼容说明">
|
||||
这条路径使用与其他自定义 `/v1` 后端相同的代理式 OpenAI 兼容路由：
|
||||
|
||||
```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
|
||||
- 不适用 OpenAI 原生专用的请求整形
|
||||
- 不支持 `service_tier`、不支持 Responses `store`、不支持提示缓存提示，也不支持 OpenAI 推理兼容负载整形
|
||||
- 不会在代理 URL 上注入隐藏的 OpenClaw 归属头（`originator`、`version`、`User-Agent`）
|
||||
|
||||
launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
|
||||
```
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="在 macOS 上使用 LaunchAgent 自动启动">
|
||||
创建一个 LaunchAgent 来自动运行该代理：
|
||||
|
||||
```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>
|
||||
|
||||
## 链接
|
||||
|
||||
@ -158,11 +166,27 @@ launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist
|
||||
## 说明
|
||||
|
||||
- 这是一个**社区工具**，并非 Anthropic 或 OpenClaw 官方支持
|
||||
- 需要有效的 Claude Max/Pro 订阅，并且 Claude Code CLI 已完成认证
|
||||
- 需要已激活的 Claude Max/Pro 订阅，并且 Claude Code CLI 已完成身份验证
|
||||
- 该代理在本地运行，不会将数据发送到任何第三方服务器
|
||||
- 完全支持流式响应
|
||||
|
||||
## 另请参见
|
||||
<Note>
|
||||
如需通过 Claude CLI 或 API 密钥进行原生 Anthropic 集成，请参阅 [Anthropic provider](/zh-CN/providers/anthropic)。如需 OpenAI/Codex 订阅，请参阅 [OpenAI provider](/zh-CN/providers/openai)。
|
||||
</Note>
|
||||
|
||||
- [Anthropic 提供商](/providers/anthropic) - 使用 Claude CLI 或 API 密钥的原生 OpenClaw 集成
|
||||
- [OpenAI 提供商](/providers/openai) - 适用于 OpenAI/Codex 订阅
|
||||
## 相关内容
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Anthropic provider" href="/zh-CN/providers/anthropic" icon="bolt">
|
||||
通过 Claude CLI 或 API 密钥实现的原生 OpenClaw 集成。
|
||||
</Card>
|
||||
<Card title="OpenAI provider" href="/zh-CN/providers/openai" icon="robot">
|
||||
适用于 OpenAI/Codex 订阅。
|
||||
</Card>
|
||||
<Card title="Model providers" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
所有提供商、模型引用和故障切换行为的概览。
|
||||
</Card>
|
||||
<Card title="Configuration" href="/zh-CN/gateway/configuration" icon="gear">
|
||||
完整配置参考。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,56 +1,71 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想通过 LiteLLM 代理转发 OpenClaw
|
||||
- 你需要通过 LiteLLM 进行成本跟踪、日志记录或模型路由
|
||||
summary: 通过 LiteLLM Proxy 运行 OpenClaw，以实现统一模型访问和成本跟踪
|
||||
- 你想通过 LiteLLM 代理来路由 OpenClaw
|
||||
- 你需要通过 LiteLLM 实现成本跟踪、日志记录或模型路由
|
||||
summary: 通过 LiteLLM Proxy 运行 OpenClaw，以实现统一的模型访问和成本跟踪
|
||||
title: LiteLLM
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:42:26Z"
|
||||
generated_at: "2026-04-12T10:19:22Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4e8ca73458186285bc06967b397b8a008791dc58eea1159d6c358e1a794982d1
|
||||
source_hash: 766692eb83a1be83811d8e09a970697530ffdd4f3392247cfb2927fd590364a0
|
||||
source_path: providers/litellm.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# LiteLLM
|
||||
|
||||
[LiteLLM](https://litellm.ai) 是一个开源 LLM 网关，为 100 多个模型提供商提供统一 API。通过 LiteLLM 转发 OpenClaw，你可以获得集中式成本跟踪、日志记录，以及在不更改 OpenClaw 配置的情况下切换后端的灵活性。
|
||||
[LiteLLM](https://litellm.ai) 是一个开源的 LLM 网关，为 100 多家模型提供商提供统一 API。通过 LiteLLM 路由 OpenClaw，你可以获得集中的成本跟踪、日志记录，以及在不更改 OpenClaw 配置的情况下切换后端的灵活性。
|
||||
|
||||
## 为什么将 LiteLLM 与 OpenClaw 一起使用？
|
||||
<Tip>
|
||||
**为什么将 LiteLLM 与 OpenClaw 搭配使用？**
|
||||
|
||||
- **成本跟踪** — 精确查看 OpenClaw 在所有模型上的花费
|
||||
- **模型路由** — 在 Claude、GPT-4、Gemini、Bedrock 之间切换，而无需更改配置
|
||||
- **成本跟踪** — 准确查看 OpenClaw 在所有模型上的支出
|
||||
- **模型路由** — 无需更改配置，即可在 Claude、GPT-4、Gemini、Bedrock 之间切换
|
||||
- **虚拟密钥** — 为 OpenClaw 创建带有支出限制的密钥
|
||||
- **日志记录** — 用于调试的完整请求/响应日志
|
||||
- **故障切换** — 当你的主提供商不可用时自动切换
|
||||
- **故障切换** — 如果你的主要提供商不可用，可自动切换
|
||||
</Tip>
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 通过新手引导
|
||||
<Tabs>
|
||||
<Tab title="新手引导（推荐）">
|
||||
**最适合：** 以最快方式完成可用的 LiteLLM 设置。
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice litellm-api-key
|
||||
```
|
||||
<Steps>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
openclaw onboard --auth-choice litellm-api-key
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 手动设置
|
||||
</Tab>
|
||||
|
||||
1. 启动 LiteLLM Proxy：
|
||||
<Tab title="手动设置">
|
||||
**最适合：** 完全控制安装和配置。
|
||||
|
||||
```bash
|
||||
pip install 'litellm[proxy]'
|
||||
litellm --model claude-opus-4-6
|
||||
```
|
||||
<Steps>
|
||||
<Step title="启动 LiteLLM Proxy">
|
||||
```bash
|
||||
pip install 'litellm[proxy]'
|
||||
litellm --model claude-opus-4-6
|
||||
```
|
||||
</Step>
|
||||
<Step title="将 OpenClaw 指向 LiteLLM">
|
||||
```bash
|
||||
export LITELLM_API_KEY="your-litellm-key"
|
||||
|
||||
2. 将 OpenClaw 指向 LiteLLM：
|
||||
openclaw
|
||||
```
|
||||
|
||||
```bash
|
||||
export LITELLM_API_KEY="your-litellm-key"
|
||||
就这些。OpenClaw 现在会通过 LiteLLM 进行路由。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
openclaw
|
||||
```
|
||||
|
||||
就是这样。OpenClaw 现在会通过 LiteLLM 路由。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 配置
|
||||
|
||||
@ -99,67 +114,90 @@ export LITELLM_API_KEY="sk-litellm-key"
|
||||
}
|
||||
```
|
||||
|
||||
## 虚拟密钥
|
||||
## 高级主题
|
||||
|
||||
为 OpenClaw 创建一个带有支出限制的专用密钥：
|
||||
<AccordionGroup>
|
||||
<Accordion title="虚拟密钥">
|
||||
为 OpenClaw 创建一个带有支出限制的专用密钥：
|
||||
|
||||
```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"
|
||||
}'
|
||||
```
|
||||
|
||||
使用生成的密钥作为 `LITELLM_API_KEY`。
|
||||
使用生成的密钥作为 `LITELLM_API_KEY`。
|
||||
|
||||
## 模型路由
|
||||
</Accordion>
|
||||
|
||||
LiteLLM 可以将模型请求路由到不同后端。在你的 LiteLLM `config.yaml` 中进行配置：
|
||||
<Accordion title="模型路由">
|
||||
LiteLLM 可以将模型请求路由到不同后端。在你的 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 会持续请求 `claude-opus-4-6` —— 路由由 LiteLLM 处理。
|
||||
OpenClaw 会继续请求 `claude-opus-4-6`——LiteLLM 会负责路由。
|
||||
|
||||
## 查看使用情况
|
||||
</Accordion>
|
||||
|
||||
检查 LiteLLM 的仪表板或 API：
|
||||
<Accordion title="查看用量">
|
||||
查看 LiteLLM 的仪表板或 API：
|
||||
|
||||
```bash
|
||||
# 密钥信息
|
||||
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"
|
||||
|
||||
# 支出日志
|
||||
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"
|
||||
```
|
||||
|
||||
## 说明
|
||||
</Accordion>
|
||||
|
||||
- LiteLLM 默认运行在 `http://localhost:4000`
|
||||
- OpenClaw 通过 LiteLLM 的代理式、兼容 OpenAI 的 `/v1`
|
||||
端点进行连接
|
||||
- 原生仅限 OpenAI 的请求整形不适用于通过 LiteLLM 的情况：
|
||||
不支持 `service_tier`、不支持 Responses `store`、不支持提示词缓存提示，也不支持
|
||||
OpenAI 推理兼容负载整形
|
||||
- 在自定义 LiteLLM 基础 URL 上，不会注入隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）
|
||||
<Accordion title="代理行为说明">
|
||||
- LiteLLM 默认运行在 `http://localhost:4000`
|
||||
- OpenClaw 通过 LiteLLM 的代理式、与 OpenAI 兼容的 `/v1`
|
||||
端点进行连接
|
||||
- 通过 LiteLLM 时，不会应用原生仅限 OpenAI 的请求整形：
|
||||
没有 `service_tier`、没有 Responses `store`、没有提示词缓存提示，也没有
|
||||
OpenAI 推理兼容负载整形
|
||||
- 在自定义 LiteLLM base URLs 上，不会注入隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`）
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 另请参阅
|
||||
<Note>
|
||||
有关通用提供商配置和故障切换行为，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
|
||||
</Note>
|
||||
|
||||
- [LiteLLM 文档](https://docs.litellm.ai)
|
||||
- [模型提供商](/concepts/model-providers)
|
||||
## 相关内容
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="LiteLLM 文档" href="https://docs.litellm.ai" icon="book">
|
||||
LiteLLM 官方文档和 API 参考。
|
||||
</Card>
|
||||
<Card title="模型提供商" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
所有提供商、模型引用和故障切换行为概览。
|
||||
</Card>
|
||||
<Card title="配置" href="/zh-CN/gateway/configuration" icon="gear">
|
||||
完整配置参考。
|
||||
</Card>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/models" icon="brain">
|
||||
如何选择和配置模型。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 OpenClaw 中使用 StepFun 模型
|
||||
- 你需要 StepFun 设置指南
|
||||
- 你需要 StepFun 设置指导
|
||||
summary: 在 OpenClaw 中使用 StepFun 模型
|
||||
title: StepFun
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T10:06:58Z"
|
||||
generated_at: "2026-04-12T10:19:19Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3154852556577b4cfb387a2de281559f2b173c774bfbcaea996abe5379ae684a
|
||||
source_hash: a463bed0951d33802dcdb3a7784406272ee206b731e9864ea020323e67b4d159
|
||||
source_path: providers/stepfun.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,143 +17,221 @@ x-i18n:
|
||||
|
||||
OpenClaw 内置了一个 StepFun 提供商插件，包含两个提供商 id：
|
||||
|
||||
- `stepfun` 用于标准端点
|
||||
- `stepfun-plan` 用于 Step Plan 端点
|
||||
- 标准端点使用 `stepfun`
|
||||
- Step Plan 端点使用 `stepfun-plan`
|
||||
|
||||
当前内置目录按接入面有所不同：
|
||||
|
||||
- 标准：`step-3.5-flash`
|
||||
- Step Plan：`step-3.5-flash`、`step-3.5-flash-2603`
|
||||
<Warning>
|
||||
标准版和 Step Plan 是**彼此独立的提供商**，具有不同的端点和模型 ref 前缀（`stepfun/...` vs `stepfun-plan/...`）。`.com` 端点请使用中国区密钥，`.ai` 端点请使用全球密钥。
|
||||
</Warning>
|
||||
|
||||
## 区域和端点概览
|
||||
|
||||
- 中国标准端点：`https://api.stepfun.com/v1`
|
||||
- 全球标准端点：`https://api.stepfun.ai/v1`
|
||||
- 中国 Step Plan 端点：`https://api.stepfun.com/step_plan/v1`
|
||||
- 全球 Step Plan 端点：`https://api.stepfun.ai/step_plan/v1`
|
||||
- 认证环境变量：`STEPFUN_API_KEY`
|
||||
| 端点 | 中国区（`.com`） | 全球（`.ai`） |
|
||||
| --------- | -------------------------------------- | ------------------------------------- |
|
||||
| 标准版 | `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` |
|
||||
|
||||
`.com` 端点请使用中国区密钥，`.ai`
|
||||
端点请使用全球密钥。
|
||||
|
||||
## CLI 设置
|
||||
|
||||
交互式设置：
|
||||
|
||||
```bash
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
选择以下认证方式之一：
|
||||
|
||||
- `stepfun-standard-api-key-cn`
|
||||
- `stepfun-standard-api-key-intl`
|
||||
- `stepfun-plan-api-key-cn`
|
||||
- `stepfun-plan-api-key-intl`
|
||||
|
||||
非交互式示例：
|
||||
|
||||
```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"
|
||||
```
|
||||
|
||||
## 模型引用
|
||||
|
||||
- 标准默认模型：`stepfun/step-3.5-flash`
|
||||
- Step Plan 默认模型：`stepfun-plan/step-3.5-flash`
|
||||
- Step Plan 备用模型：`stepfun-plan/step-3.5-flash-2603`
|
||||
认证环境变量：`STEPFUN_API_KEY`
|
||||
|
||||
## 内置目录
|
||||
|
||||
标准（`stepfun`）：
|
||||
标准版（`stepfun`）：
|
||||
|
||||
| 模型引用 | 上下文 | 最大输出 | 说明 |
|
||||
| ------------------------ | ------- | -------- | -------------- |
|
||||
| 模型 ref | 上下文 | 最大输出 | 说明 |
|
||||
| ------------------------ | ------ | -------- | -------------- |
|
||||
| `stepfun/step-3.5-flash` | 262,144 | 65,536 | 默认标准模型 |
|
||||
|
||||
Step Plan（`stepfun-plan`）：
|
||||
|
||||
| 模型引用 | 上下文 | 最大输出 | 说明 |
|
||||
| ---------------------------------- | ------- | -------- | -------------------- |
|
||||
| 模型 ref | 上下文 | 最大输出 | 说明 |
|
||||
| ---------------------------------- | ------ | -------- | -------------------- |
|
||||
| `stepfun-plan/step-3.5-flash` | 262,144 | 65,536 | 默认 Step Plan 模型 |
|
||||
| `stepfun-plan/step-3.5-flash-2603` | 262,144 | 65,536 | 其他 Step Plan 模型 |
|
||||
| `stepfun-plan/step-3.5-flash-2603` | 262,144 | 65,536 | 额外的 Step Plan 模型 |
|
||||
|
||||
## 配置片段
|
||||
## 入门指南
|
||||
|
||||
标准提供商：
|
||||
选择你的提供商入口，并按照设置步骤进行操作。
|
||||
|
||||
```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="标准版">
|
||||
**最适合：** 通过标准 StepFun 端点进行通用用途使用。
|
||||
|
||||
<Steps>
|
||||
<Step title="选择你的端点区域">
|
||||
| 认证选项 | 端点 | 区域 |
|
||||
| -------------------------------- | --------------------------------- | ---- |
|
||||
| `stepfun-standard-api-key-intl` | `https://api.stepfun.ai/v1` | 国际 |
|
||||
| `stepfun-standard-api-key-cn` | `https://api.stepfun.com/v1` | 中国 |
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
openclaw onboard --auth-choice stepfun-standard-api-key-intl
|
||||
```
|
||||
|
||||
或者使用中国区端点：
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice stepfun-standard-api-key-cn
|
||||
```
|
||||
</Step>
|
||||
<Step title="非交互式替代方案">
|
||||
```bash
|
||||
openclaw onboard --auth-choice stepfun-standard-api-key-intl \
|
||||
--stepfun-api-key "$STEPFUN_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="验证模型可用">
|
||||
```bash
|
||||
openclaw models list --provider stepfun
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 模型 ref
|
||||
|
||||
- 默认模型：`stepfun/step-3.5-flash`
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Step Plan">
|
||||
**最适合：** Step Plan 推理端点。
|
||||
|
||||
<Steps>
|
||||
<Step title="选择你的端点区域">
|
||||
| 认证选项 | 端点 | 区域 |
|
||||
| ---------------------------- | ---------------------------------------- | ---- |
|
||||
| `stepfun-plan-api-key-intl` | `https://api.stepfun.ai/step_plan/v1` | 国际 |
|
||||
| `stepfun-plan-api-key-cn` | `https://api.stepfun.com/step_plan/v1` | 中国 |
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
openclaw onboard --auth-choice stepfun-plan-api-key-intl
|
||||
```
|
||||
|
||||
或者使用中国区端点：
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice stepfun-plan-api-key-cn
|
||||
```
|
||||
</Step>
|
||||
<Step title="非交互式替代方案">
|
||||
```bash
|
||||
openclaw onboard --auth-choice stepfun-plan-api-key-intl \
|
||||
--stepfun-api-key "$STEPFUN_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="验证模型可用">
|
||||
```bash
|
||||
openclaw models list --provider stepfun-plan
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 模型 ref
|
||||
|
||||
- 默认模型：`stepfun-plan/step-3.5-flash`
|
||||
- 备用模型：`stepfun-plan/step-3.5-flash-2603`
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 高级用法
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="完整配置：标准提供商">
|
||||
```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 提供商：
|
||||
|
||||
```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="完整配置：Step Plan 提供商">
|
||||
```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>
|
||||
|
||||
## 说明
|
||||
<Accordion title="说明">
|
||||
- 该提供商已内置于 OpenClaw，因此无需单独安装插件。
|
||||
- `step-3.5-flash-2603` 目前仅在 `stepfun-plan` 上提供。
|
||||
- 单次认证流程会为 `stepfun` 和 `stepfun-plan` 写入与区域匹配的配置，因此两个入口都可以一起被发现。
|
||||
- 使用 `openclaw models list` 和 `openclaw models set <provider/model>` 来查看或切换模型。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
- 该提供商随 OpenClaw 内置，因此不需要单独安装插件。
|
||||
- `step-3.5-flash-2603` 当前仅在 `stepfun-plan` 上提供。
|
||||
- 单次认证流程会为 `stepfun` 和 `stepfun-plan` 写入区域匹配的配置文件，因此两个接入面都可以一起被发现。
|
||||
- 使用 `openclaw models list` 和 `openclaw models set <provider/model>` 查看或切换模型。
|
||||
- 更广泛的提供商概览，请参见 [模型提供商](/zh-CN/concepts/model-providers)。
|
||||
<Note>
|
||||
有关更广泛的提供商概览，请参见 [模型提供商](/zh-CN/concepts/model-providers)。
|
||||
</Note>
|
||||
|
||||
## 相关内容
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型提供商" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
所有提供商、模型 ref 和故障切换行为的概览。
|
||||
</Card>
|
||||
<Card title="配置参考" href="/zh-CN/gateway/configuration-reference" icon="gear">
|
||||
提供商、模型和插件的完整配置 schema。
|
||||
</Card>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/models" icon="brain">
|
||||
如何选择和配置模型。
|
||||
</Card>
|
||||
<Card title="StepFun Platform" href="https://platform.stepfun.com" icon="globe">
|
||||
StepFun API 密钥管理和文档。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -5,17 +5,17 @@ read_when:
|
||||
summary: 在 OpenClaw 中使用 Vydra 图像、视频和语音
|
||||
title: Vydra
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T18:49:20Z"
|
||||
generated_at: "2026-04-12T10:19:18Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 24006a687ed6f9792e7b2b10927cc7ad71c735462a92ce03d5fa7c2b2ee2fcc2
|
||||
source_hash: ab623d14b656ce0b68d648a6393fcee3bb880077d6583e0d5c1012e91757f20e
|
||||
source_path: providers/vydra.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Vydra
|
||||
|
||||
内置的 Vydra 插件新增了以下功能：
|
||||
内置的 Vydra 插件新增了：
|
||||
|
||||
- 通过 `vydra/grok-imagine` 进行图像生成
|
||||
- 通过 `vydra/veo3` 和 `vydra/kling` 进行视频生成
|
||||
@ -23,128 +23,159 @@ x-i18n:
|
||||
|
||||
OpenClaw 对这三种能力都使用同一个 `VYDRA_API_KEY`。
|
||||
|
||||
## 重要基础 URL
|
||||
<Warning>
|
||||
请使用 `https://www.vydra.ai/api/v1` 作为基础 URL。
|
||||
|
||||
使用 `https://www.vydra.ai/api/v1`。
|
||||
|
||||
Vydra 的顶级主机（`https://vydra.ai/api/v1`）当前会重定向到 `www`。某些 HTTP 客户端会在这种跨主机重定向时丢弃 `Authorization`，从而让有效的 API 密钥表现成具有误导性的认证失败。内置插件会直接使用 `www` 基础 URL 以避免这个问题。
|
||||
Vydra 的顶级主机（`https://vydra.ai/api/v1`）目前会重定向到 `www`。某些 HTTP 客户端会在这种跨主机重定向时丢弃 `Authorization`，从而让有效的 API 密钥看起来像是误导性的认证失败。内置插件会直接使用 `www` 基础 URL，以避免这个问题。
|
||||
</Warning>
|
||||
|
||||
## 设置
|
||||
|
||||
交互式新手引导：
|
||||
<Steps>
|
||||
<Step title="运行交互式新手引导">
|
||||
```bash
|
||||
openclaw onboard --auth-choice vydra-api-key
|
||||
```
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice vydra-api-key
|
||||
```
|
||||
或者直接设置环境变量：
|
||||
|
||||
或者直接设置环境变量：
|
||||
```bash
|
||||
export VYDRA_API_KEY="vydra_live_..."
|
||||
```
|
||||
|
||||
```bash
|
||||
export VYDRA_API_KEY="vydra_live_..."
|
||||
```
|
||||
</Step>
|
||||
<Step title="选择默认能力">
|
||||
从以下能力中选择一个或多个（图像、视频或语音），并应用对应的配置。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 图像生成
|
||||
## 能力
|
||||
|
||||
默认图像模型：
|
||||
<AccordionGroup>
|
||||
<Accordion title="图像生成">
|
||||
默认图像模型：
|
||||
|
||||
- `vydra/grok-imagine`
|
||||
- `vydra/grok-imagine`
|
||||
|
||||
将其设为默认图像提供商：
|
||||
将它设为默认图像提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
imageGenerationModel: {
|
||||
primary: "vydra/grok-imagine",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
当前内置支持仅限文生图。Vydra 托管的编辑路由需要远程图像 URL，而 OpenClaw 在内置插件中尚未添加 Vydra 专用的上传桥接。
|
||||
|
||||
共享工具行为请参见 [图像生成](/zh-CN/tools/image-generation)。
|
||||
|
||||
## 视频生成
|
||||
|
||||
已注册的视频模型：
|
||||
|
||||
- `vydra/veo3` 用于文生视频
|
||||
- `vydra/kling` 用于图生视频
|
||||
|
||||
将 Vydra 设为默认视频提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
videoGenerationModel: {
|
||||
primary: "vydra/veo3",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
注意：
|
||||
|
||||
- `vydra/veo3` 在内置中仅作为文生视频提供。
|
||||
- `vydra/kling` 当前需要远程图像 URL 引用。本地文件上传会被直接拒绝。
|
||||
- Vydra 当前的 `kling` HTTP 路由在是否要求 `image_url` 或 `video_url` 方面表现并不一致；内置提供商会将同一个远程图像 URL 同时映射到这两个字段。
|
||||
- 内置插件保持保守处理，不会转发诸如宽高比、分辨率、水印或生成音频等未文档化的样式控制参数。
|
||||
|
||||
提供商专属的实时覆盖：
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 \
|
||||
OPENCLAW_LIVE_VYDRA_VIDEO=1 \
|
||||
pnpm test:live -- extensions/vydra/vydra.live.test.ts
|
||||
```
|
||||
|
||||
内置的 Vydra 实时测试文件现在覆盖：
|
||||
|
||||
- `vydra/veo3` 文生视频
|
||||
- 使用远程图像 URL 的 `vydra/kling` 图生视频
|
||||
|
||||
需要时可覆盖远程图像测试夹具：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_LIVE_VYDRA_KLING_IMAGE_URL="https://example.com/reference.png"
|
||||
```
|
||||
|
||||
共享工具行为请参见 [视频生成](/zh-CN/tools/video-generation)。
|
||||
|
||||
## 语音合成
|
||||
|
||||
将 Vydra 设为语音提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
provider: "vydra",
|
||||
providers: {
|
||||
vydra: {
|
||||
apiKey: "${VYDRA_API_KEY}",
|
||||
voiceId: "21m00Tcm4TlvDq8ikWAM",
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
imageGenerationModel: {
|
||||
primary: "vydra/grok-imagine",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
默认值：
|
||||
当前内置支持仅限文生图。Vydra 托管的编辑路由需要远程图像 URL，而 OpenClaw 目前尚未在内置插件中添加 Vydra 专用的上传桥接。
|
||||
|
||||
- 模型：`elevenlabs/tts`
|
||||
- 语音 ID：`21m00Tcm4TlvDq8ikWAM`
|
||||
<Note>
|
||||
请参阅 [Image Generation](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障切换行为。
|
||||
</Note>
|
||||
|
||||
内置插件当前会暴露一个已知稳定可用的默认语音，并返回 MP3 音频文件。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="视频生成">
|
||||
已注册的视频模型：
|
||||
|
||||
- `vydra/veo3` 用于文生视频
|
||||
- `vydra/kling` 用于图生视频
|
||||
|
||||
将 Vydra 设为默认视频提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
videoGenerationModel: {
|
||||
primary: "vydra/veo3",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `vydra/veo3` 内置时仅支持文生视频。
|
||||
- `vydra/kling` 目前需要远程图像 URL 引用。会在前端直接拒绝本地文件上传。
|
||||
- Vydra 当前的 `kling` HTTP 路由在是否需要 `image_url` 还是 `video_url` 方面一直不太一致；内置提供商会将同一个远程图像 URL 映射到这两个字段。
|
||||
- 内置插件保持保守，不会转发未文档化的风格控制项，例如宽高比、分辨率、水印或生成音频。
|
||||
|
||||
<Note>
|
||||
请参阅 [Video Generation](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障切换行为。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="视频实时测试">
|
||||
提供商专属的实时覆盖范围：
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 \
|
||||
OPENCLAW_LIVE_VYDRA_VIDEO=1 \
|
||||
pnpm test:live -- extensions/vydra/vydra.live.test.ts
|
||||
```
|
||||
|
||||
内置的 Vydra 实时测试文件现在覆盖：
|
||||
|
||||
- `vydra/veo3` 文生视频
|
||||
- `vydra/kling` 使用远程图像 URL 的图生视频
|
||||
|
||||
如有需要，可覆盖远程图像夹具：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_LIVE_VYDRA_KLING_IMAGE_URL="https://example.com/reference.png"
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="语音合成">
|
||||
将 Vydra 设为语音提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
messages: {
|
||||
tts: {
|
||||
provider: "vydra",
|
||||
providers: {
|
||||
vydra: {
|
||||
apiKey: "${VYDRA_API_KEY}",
|
||||
voiceId: "21m00Tcm4TlvDq8ikWAM",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
默认值：
|
||||
|
||||
- 模型：`elevenlabs/tts`
|
||||
- Voice id：`21m00Tcm4TlvDq8ikWAM`
|
||||
|
||||
内置插件目前提供一个已知可用的默认语音，并返回 MP3 音频文件。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [提供商目录](/zh-CN/providers/index)
|
||||
- [图像生成](/zh-CN/tools/image-generation)
|
||||
- [视频生成](/zh-CN/tools/video-generation)
|
||||
<CardGroup cols={2}>
|
||||
<Card title="提供商目录" href="/zh-CN/providers/index" icon="list">
|
||||
浏览所有可用提供商。
|
||||
</Card>
|
||||
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
|
||||
共享图像工具参数和提供商选择。
|
||||
</Card>
|
||||
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
|
||||
共享视频工具参数和提供商选择。
|
||||
</Card>
|
||||
<Card title="配置参考" href="/zh-CN/gateway/configuration-reference#agent-defaults" icon="gear">
|
||||
智能体默认值和模型配置。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 OpenClaw 中使用 Grok 模型
|
||||
- 你正在配置 xAI 身份验证或模型 ID
|
||||
- 你正在配置 xAI 的身份验证或模型 ID
|
||||
summary: 在 OpenClaw 中使用 xAI Grok 模型
|
||||
title: xAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T22:23:12Z"
|
||||
generated_at: "2026-04-12T10:19:18Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 64bc899655427cc10bdc759171c7d1ec25ad9f1e4f9d803f1553d3d586c6d71d
|
||||
source_hash: 064aa758f9791f704dc6b0cc0059bb73b7de68ae2edd731bb87dbc26730eea9f
|
||||
source_path: providers/xai.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,109 +17,157 @@ x-i18n:
|
||||
|
||||
OpenClaw 内置了一个用于 Grok 模型的 `xai` 提供商插件。
|
||||
|
||||
## 设置
|
||||
## 入门指南
|
||||
|
||||
1. 在 xAI 控制台中创建一个 API 密钥。
|
||||
2. 设置 `XAI_API_KEY`，或运行：
|
||||
<Steps>
|
||||
<Step title="创建 API 密钥">
|
||||
在 [xAI 控制台](https://console.x.ai/) 中创建一个 API 密钥。
|
||||
</Step>
|
||||
<Step title="设置你的 API 密钥">
|
||||
设置 `XAI_API_KEY`，或运行：
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice xai-api-key
|
||||
```
|
||||
```bash
|
||||
openclaw onboard --auth-choice xai-api-key
|
||||
```
|
||||
|
||||
3. 选择一个模型，例如：
|
||||
</Step>
|
||||
<Step title="选择一个模型">
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "xai/grok-4" } } },
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "xai/grok-4" } } },
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 现在使用 xAI Responses API 作为内置 xAI 传输层。同一个
|
||||
`XAI_API_KEY` 也可用于由 Grok 驱动的 `web_search`、原生的 `x_search`，
|
||||
以及远程 `code_execution`。
|
||||
<Note>
|
||||
OpenClaw 使用 xAI Responses API 作为内置的 xAI 传输层。相同的
|
||||
`XAI_API_KEY` 也可用于由 Grok 驱动的 `web_search`、原生
|
||||
`x_search` 以及远程 `code_execution`。
|
||||
如果你将 xAI 密钥存储在 `plugins.entries.xai.config.webSearch.apiKey` 下，
|
||||
内置的 xAI 模型提供商现在也会将该密钥作为回退复用。
|
||||
内置的 xAI 模型提供商也会将该密钥复用为回退值。
|
||||
`code_execution` 调优配置位于 `plugins.entries.xai.config.codeExecution` 下。
|
||||
</Note>
|
||||
|
||||
## 当前内置模型目录
|
||||
## 内置模型目录
|
||||
|
||||
OpenClaw 现在开箱即用地包含以下 xAI 模型系列：
|
||||
OpenClaw 开箱即用地包含以下 xAI 模型家族：
|
||||
|
||||
- `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`
|
||||
| 家族 | 模型 ID |
|
||||
| -------------- | ------------------------------------------------------------------------ |
|
||||
| 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` |
|
||||
|
||||
当较新的 `grok-4*` 和 `grok-code-fast*` ID 遵循相同的 API 形态时，
|
||||
该插件也会转发解析这些 ID。
|
||||
当较新的 `grok-4*` 和 `grok-code-fast*` ID 遵循相同的 API 形式时，
|
||||
该插件也会继续将其转发解析。
|
||||
|
||||
快速模型说明：
|
||||
<Tip>
|
||||
`grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` 变体，
|
||||
是当前内置目录中支持图像能力的 Grok 引用。
|
||||
</Tip>
|
||||
|
||||
- `grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` 变体，是当前内置目录中支持图像能力的 Grok 引用。
|
||||
- `/fast on` 或 `agents.defaults.models["xai/<model>"].params.fastMode: true`
|
||||
会将原生 xAI 请求按如下方式重写：
|
||||
- `grok-3` -> `grok-3-fast`
|
||||
- `grok-3-mini` -> `grok-3-mini-fast`
|
||||
- `grok-4` -> `grok-4-fast`
|
||||
- `grok-4-0709` -> `grok-4-fast`
|
||||
### 快速模式映射
|
||||
|
||||
旧版兼容别名仍会规范化为内置的规范 ID。例如：
|
||||
`/fast on` 或 `agents.defaults.models["xai/<model>"].params.fastMode: true`
|
||||
会按如下方式重写原生 xAI 请求：
|
||||
|
||||
- `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`
|
||||
| 源模型 | 快速模式目标 |
|
||||
| ------------- | ------------------ |
|
||||
| `grok-3` | `grok-3-fast` |
|
||||
| `grok-3-mini` | `grok-3-mini-fast` |
|
||||
| `grok-4` | `grok-4-fast` |
|
||||
| `grok-4-0709` | `grok-4-fast` |
|
||||
|
||||
## 网页搜索
|
||||
### 旧版兼容别名
|
||||
|
||||
内置的 `grok` 网页搜索提供商也使用 `XAI_API_KEY`：
|
||||
旧版别名仍会规范化为标准的内置 ID：
|
||||
|
||||
```bash
|
||||
openclaw config set tools.web.search.provider grok
|
||||
```
|
||||
| 旧版别名 | 标准 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` |
|
||||
|
||||
## 视频生成
|
||||
## 功能
|
||||
|
||||
内置的 `xai` 插件还通过共享的
|
||||
`video_generate` 工具注册了视频生成功能。
|
||||
<AccordionGroup>
|
||||
<Accordion title="Web 搜索">
|
||||
内置的 `grok` Web 搜索提供商也使用 `XAI_API_KEY`：
|
||||
|
||||
- 默认视频模型：`xai/grok-imagine-video`
|
||||
- 模式：文生视频、图生视频，以及远程视频编辑/延长流程
|
||||
- 支持 `aspectRatio` 和 `resolution`
|
||||
- 当前限制：不接受本地视频缓冲区；视频参考/编辑输入请使用远程 `http(s)`
|
||||
URL
|
||||
```bash
|
||||
openclaw config set tools.web.search.provider grok
|
||||
```
|
||||
|
||||
要将 xAI 用作默认视频提供商：
|
||||
</Accordion>
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
videoGenerationModel: {
|
||||
primary: "xai/grok-imagine-video",
|
||||
<Accordion title="视频生成">
|
||||
内置的 `xai` 插件通过共享的
|
||||
`video_generate` 工具注册了视频生成功能。
|
||||
|
||||
- 默认视频模型：`xai/grok-imagine-video`
|
||||
- 模式：文生视频、图生视频，以及远程视频编辑/扩展流程
|
||||
- 支持 `aspectRatio` 和 `resolution`
|
||||
|
||||
<Warning>
|
||||
不接受本地视频缓冲区。请对视频参考和编辑输入使用远程 `http(s)` URL。
|
||||
</Warning>
|
||||
|
||||
要将 xAI 用作默认视频提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
videoGenerationModel: {
|
||||
primary: "xai/grok-imagine-video",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
|
||||
<Note>
|
||||
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
|
||||
</Note>
|
||||
|
||||
## 已知限制
|
||||
</Accordion>
|
||||
|
||||
- 目前身份验证仅支持 API 密钥。OpenClaw 还不支持 xAI OAuth/设备代码流程。
|
||||
- `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI 提供商路径上不受支持，因为它所需的上游 API 接口与标准 OpenClaw xAI 传输层不同。
|
||||
<Accordion title="已知限制">
|
||||
- 当前身份验证仅支持 API 密钥。OpenClaw 尚不支持 xAI OAuth 或设备代码流程。
|
||||
- `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI 提供商路径中不受支持，因为它所需的上游 API 接口不同于标准的 OpenClaw xAI 传输层。
|
||||
</Accordion>
|
||||
|
||||
## 说明
|
||||
<Accordion title="高级说明">
|
||||
- OpenClaw 会在共享运行器路径上自动应用 xAI 特定的工具 schema 和工具调用兼容性修复。
|
||||
- 原生 xAI 请求默认使用 `tool_stream: true`。将
|
||||
`agents.defaults.models["xai/<model>"].params.tool_stream` 设为 `false`
|
||||
可禁用它。
|
||||
- 内置的 xAI 包装器会在发送原生 xAI 请求前，去除不受支持的严格工具 schema 标志和推理负载键。
|
||||
- `web_search`、`x_search` 和 `code_execution` 以 OpenClaw 工具的形式公开。OpenClaw 会在每次工具请求中启用它所需的特定 xAI 内置能力，而不是在每次聊天轮次中附加所有原生工具。
|
||||
- `x_search` 和 `code_execution` 由内置的 xAI 插件负责，而不是硬编码在核心模型运行时中。
|
||||
- `code_execution` 是远程 xAI 沙箱执行，不是本地的
|
||||
[`exec`](/zh-CN/tools/exec)。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
- OpenClaw 会在共享运行器路径上自动应用 xAI 专用的工具模式和工具调用兼容性修复。
|
||||
- 原生 xAI 请求默认使用 `tool_stream: true`。将
|
||||
`agents.defaults.models["xai/<model>"].params.tool_stream` 设置为 `false`
|
||||
可禁用它。
|
||||
- 内置的 xAI 包装器会在发送原生 xAI 请求前，移除不受支持的严格工具模式标志和推理负载键。
|
||||
- `web_search`、`x_search` 和 `code_execution` 会作为 OpenClaw 工具暴露。OpenClaw 会在每次工具请求中启用所需的特定 xAI 内置功能，而不是在每次聊天轮次中附加所有原生工具。
|
||||
- `x_search` 和 `code_execution` 由内置 xAI 插件负责，而不是硬编码在核心模型运行时中。
|
||||
- `code_execution` 是远程 xAI 沙箱执行，不是本地的 [`exec`](/zh-CN/tools/exec)。
|
||||
- 关于更广泛的提供商概览，请参见 [模型提供商](/zh-CN/providers/index)。
|
||||
## 相关内容
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
选择提供商、模型引用和故障切换行为。
|
||||
</Card>
|
||||
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
|
||||
共享视频工具参数和提供商选择。
|
||||
</Card>
|
||||
<Card title="所有提供商" href="/zh-CN/providers/index" icon="grid-2">
|
||||
更全面的提供商概览。
|
||||
</Card>
|
||||
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
|
||||
常见问题及修复方法。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user