diff --git a/docs/zh-CN/providers/claude-max-api-proxy.md b/docs/zh-CN/providers/claude-max-api-proxy.md index 55fbd7193..7b6f77c76 100644 --- a/docs/zh-CN/providers/claude-max-api-proxy.md +++ b/docs/zh-CN/providers/claude-max-api-proxy.md @@ -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 格式的工具中使用你的订阅。 -这条路径仅用于技术兼容性。Anthropic 过去曾阻止过一些在 Claude Code 之外的订阅 -用法。你必须自行决定是否使用它，并在依赖它之前核实 Anthropic 当前的条款。 +这条路径仅提供技术兼容性。Anthropic 过去曾阻止在 Claude Code 之外使用某些订阅用法。你必须自行决定是否使用它，并在依赖它之前核实 Anthropic 当前的条款。 ## 为什么使用这个？ -| 方式 | 成本 | 最适合 | -| ----------------------- | --------------------------------------------------- | --------------------------------------- | -| 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 + + + 需要 Node.js 20+ 和 Claude Code CLI。 -# 验证 Claude CLI 已认证 -claude --version -``` + ```bash + npm install -g claude-max-api-proxy -## 用法 + # 验证 Claude CLI 已完成身份验证 + claude --version + ``` -### 启动服务器 + + + ```bash + claude-max-api + # 服务器运行在 http://localhost:3456 + ``` + + + ```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 + + + 将 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`） + + ## 可用模型 -| 模型 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，以自动运行该代理： + + + 这条路径使用与其他自定义 `/v1` 后端相同的代理式 OpenAI 兼容路由： -```bash -cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF' - - - - - Label - com.claude-max-api - RunAtLoad - - KeepAlive - - ProgramArguments - - /usr/local/bin/node - /usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js - - EnvironmentVariables - - PATH - /usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin - - - -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 -``` + + + + 创建一个 LaunchAgent 来自动运行该代理： + + ```bash + cat > ~/Library/LaunchAgents/com.claude-max-api.plist << 'EOF' + + + + + Label + com.claude-max-api + RunAtLoad + + KeepAlive + + ProgramArguments + + /usr/local/bin/node + /usr/local/lib/node_modules/claude-max-api-proxy/dist/server/standalone.js + + EnvironmentVariables + + PATH + /usr/local/bin:/opt/homebrew/bin:~/.local/bin:/usr/bin:/bin + + + + EOF + + launchctl bootstrap gui/$(id -u) ~/Library/LaunchAgents/com.claude-max-api.plist + ``` + + + ## 链接 @@ -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 已完成身份验证 - 该代理在本地运行，不会将数据发送到任何第三方服务器 - 完全支持流式响应 -## 另请参见 + +如需通过 Claude CLI 或 API 密钥进行原生 Anthropic 集成，请参阅 [Anthropic provider](/zh-CN/providers/anthropic)。如需 OpenAI/Codex 订阅，请参阅 [OpenAI provider](/zh-CN/providers/openai)。 + -- [Anthropic 提供商](/providers/anthropic) - 使用 Claude CLI 或 API 密钥的原生 OpenClaw 集成 -- [OpenAI 提供商](/providers/openai) - 适用于 OpenAI/Codex 订阅 +## 相关内容 + + + + 通过 Claude CLI 或 API 密钥实现的原生 OpenClaw 集成。 + + + 适用于 OpenAI/Codex 订阅。 + + + 所有提供商、模型引用和故障切换行为的概览。 + + + 完整配置参考。 + + diff --git a/docs/zh-CN/providers/litellm.md b/docs/zh-CN/providers/litellm.md index c09dc96d2..b2d67e06e 100644 --- a/docs/zh-CN/providers/litellm.md +++ b/docs/zh-CN/providers/litellm.md @@ -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 一起使用？ + +**为什么将 LiteLLM 与 OpenClaw 搭配使用？** -- **成本跟踪** — 精确查看 OpenClaw 在所有模型上的花费 -- **模型路由** — 在 Claude、GPT-4、Gemini、Bedrock 之间切换，而无需更改配置 +- **成本跟踪** — 准确查看 OpenClaw 在所有模型上的支出 +- **模型路由** — 无需更改配置，即可在 Claude、GPT-4、Gemini、Bedrock 之间切换 - **虚拟密钥** — 为 OpenClaw 创建带有支出限制的密钥 - **日志记录** — 用于调试的完整请求/响应日志 -- **故障切换** — 当你的主提供商不可用时自动切换 +- **故障切换** — 如果你的主要提供商不可用，可自动切换 + ## 快速开始 -### 通过新手引导 + + + **最适合：** 以最快方式完成可用的 LiteLLM 设置。 -```bash -openclaw onboard --auth-choice litellm-api-key -``` + + + ```bash + openclaw onboard --auth-choice litellm-api-key + ``` + + -### 手动设置 + -1. 启动 LiteLLM Proxy： + + **最适合：** 完全控制安装和配置。 -```bash -pip install 'litellm[proxy]' -litellm --model claude-opus-4-6 -``` + + + ```bash + pip install 'litellm[proxy]' + litellm --model claude-opus-4-6 + ``` + + + ```bash + export LITELLM_API_KEY="your-litellm-key" -2. 将 OpenClaw 指向 LiteLLM： + openclaw + ``` -```bash -export LITELLM_API_KEY="your-litellm-key" + 就这些。OpenClaw 现在会通过 LiteLLM 进行路由。 + + -openclaw -``` - -就是这样。OpenClaw 现在会通过 LiteLLM 路由。 + + ## 配置 @@ -99,67 +114,90 @@ export LITELLM_API_KEY="sk-litellm-key" } ``` -## 虚拟密钥 +## 高级主题 -为 OpenClaw 创建一个带有支出限制的专用密钥： + + + 为 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`。 -## 模型路由 + -LiteLLM 可以将模型请求路由到不同后端。在你的 LiteLLM `config.yaml` 中进行配置： + + 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 会负责路由。 -## 查看使用情况 + -检查 LiteLLM 的仪表板或 API： + + 查看 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" + ``` -## 说明 + -- LiteLLM 默认运行在 `http://localhost:4000` -- OpenClaw 通过 LiteLLM 的代理式、兼容 OpenAI 的 `/v1` - 端点进行连接 -- 原生仅限 OpenAI 的请求整形不适用于通过 LiteLLM 的情况： - 不支持 `service_tier`、不支持 Responses `store`、不支持提示词缓存提示，也不支持 - OpenAI 推理兼容负载整形 -- 在自定义 LiteLLM 基础 URL 上，不会注入隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`） + + - LiteLLM 默认运行在 `http://localhost:4000` + - OpenClaw 通过 LiteLLM 的代理式、与 OpenAI 兼容的 `/v1` + 端点进行连接 + - 通过 LiteLLM 时，不会应用原生仅限 OpenAI 的请求整形： + 没有 `service_tier`、没有 Responses `store`、没有提示词缓存提示，也没有 + OpenAI 推理兼容负载整形 + - 在自定义 LiteLLM base URLs 上，不会注入隐藏的 OpenClaw 归因标头（`originator`、`version`、`User-Agent`） + + -## 另请参阅 + +有关通用提供商配置和故障切换行为，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。 + -- [LiteLLM 文档](https://docs.litellm.ai) -- [模型提供商](/concepts/model-providers) +## 相关内容 + + + + LiteLLM 官方文档和 API 参考。 + + + 所有提供商、模型引用和故障切换行为概览。 + + + 完整配置参考。 + + + 如何选择和配置模型。 + + diff --git a/docs/zh-CN/providers/stepfun.md b/docs/zh-CN/providers/stepfun.md index c4b6b5ac8..4de910604 100644 --- a/docs/zh-CN/providers/stepfun.md +++ b/docs/zh-CN/providers/stepfun.md @@ -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` + +标准版和 Step Plan 是**彼此独立的提供商**，具有不同的端点和模型 ref 前缀（`stepfun/...` vs `stepfun-plan/...`）。`.com` 端点请使用中国区密钥，`.ai` 端点请使用全球密钥。 + ## 区域和端点概览 -- 中国标准端点：`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, + + + **最适合：** 通过标准 StepFun 端点进行通用用途使用。 + + + + | 认证选项 | 端点 | 区域 | + | -------------------------------- | --------------------------------- | ---- | + | `stepfun-standard-api-key-intl` | `https://api.stepfun.ai/v1` | 国际 | + | `stepfun-standard-api-key-cn` | `https://api.stepfun.com/v1` | 中国 | + + + ```bash + openclaw onboard --auth-choice stepfun-standard-api-key-intl + ``` + + 或者使用中国区端点： + + ```bash + openclaw onboard --auth-choice stepfun-standard-api-key-cn + ``` + + + ```bash + openclaw onboard --auth-choice stepfun-standard-api-key-intl \ + --stepfun-api-key "$STEPFUN_API_KEY" + ``` + + + ```bash + openclaw models list --provider stepfun + ``` + + + + ### 模型 ref + + - 默认模型：`stepfun/step-3.5-flash` + + + + + **最适合：** Step Plan 推理端点。 + + + + | 认证选项 | 端点 | 区域 | + | ---------------------------- | ---------------------------------------- | ---- | + | `stepfun-plan-api-key-intl` | `https://api.stepfun.ai/step_plan/v1` | 国际 | + | `stepfun-plan-api-key-cn` | `https://api.stepfun.com/step_plan/v1` | 中国 | + + + ```bash + openclaw onboard --auth-choice stepfun-plan-api-key-intl + ``` + + 或者使用中国区端点： + + ```bash + openclaw onboard --auth-choice stepfun-plan-api-key-cn + ``` + + + ```bash + openclaw onboard --auth-choice stepfun-plan-api-key-intl \ + --stepfun-api-key "$STEPFUN_API_KEY" + ``` + + + ```bash + openclaw models list --provider stepfun-plan + ``` + + + + ### 模型 ref + + - 默认模型：`stepfun-plan/step-3.5-flash` + - 备用模型：`stepfun-plan/step-3.5-flash-2603` + + + + +## 高级用法 + + + + ```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, + }, + ], }, - ], + }, }, - }, - }, -} -``` + } + ``` + -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, + + ```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, - }, - ], + }, }, - }, - }, -} -``` + } + ``` + -## 说明 + + - 该提供商已内置于 OpenClaw，因此无需单独安装插件。 + - `step-3.5-flash-2603` 目前仅在 `stepfun-plan` 上提供。 + - 单次认证流程会为 `stepfun` 和 `stepfun-plan` 写入与区域匹配的配置，因此两个入口都可以一起被发现。 + - 使用 `openclaw models list` 和 `openclaw models set ` 来查看或切换模型。 + + -- 该提供商随 OpenClaw 内置，因此不需要单独安装插件。 -- `step-3.5-flash-2603` 当前仅在 `stepfun-plan` 上提供。 -- 单次认证流程会为 `stepfun` 和 `stepfun-plan` 写入区域匹配的配置文件，因此两个接入面都可以一起被发现。 -- 使用 `openclaw models list` 和 `openclaw models set ` 查看或切换模型。 -- 更广泛的提供商概览，请参见 [模型提供商](/zh-CN/concepts/model-providers)。 + +有关更广泛的提供商概览，请参见 [模型提供商](/zh-CN/concepts/model-providers)。 + + +## 相关内容 + + + + 所有提供商、模型 ref 和故障切换行为的概览。 + + + 提供商、模型和插件的完整配置 schema。 + + + 如何选择和配置模型。 + + + StepFun API 密钥管理和文档。 + + diff --git a/docs/zh-CN/providers/vydra.md b/docs/zh-CN/providers/vydra.md index 44cfb9038..6720846ba 100644 --- a/docs/zh-CN/providers/vydra.md +++ b/docs/zh-CN/providers/vydra.md @@ -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 + +请使用 `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，以避免这个问题。 + ## 设置 -交互式新手引导： + + + ```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_..." -``` + + + 从以下能力中选择一个或多个（图像、视频或语音），并应用对应的配置。 + + -## 图像生成 +## 能力 -默认图像模型： + + + 默认图像模型： -- `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` + + 请参阅 [Image Generation](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障切换行为。 + -内置插件当前会暴露一个已知稳定可用的默认语音，并返回 MP3 音频文件。 + + + + 已注册的视频模型： + + - `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 映射到这两个字段。 + - 内置插件保持保守，不会转发未文档化的风格控制项，例如宽高比、分辨率、水印或生成音频。 + + + 请参阅 [Video Generation](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障切换行为。 + + + + + + 提供商专属的实时覆盖范围： + + ```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" + ``` + + + + + 将 Vydra 设为语音提供商： + + ```json5 + { + messages: { + tts: { + provider: "vydra", + providers: { + vydra: { + apiKey: "${VYDRA_API_KEY}", + voiceId: "21m00Tcm4TlvDq8ikWAM", + }, + }, + }, + }, + } + ``` + + 默认值： + + - 模型：`elevenlabs/tts` + - Voice id：`21m00Tcm4TlvDq8ikWAM` + + 内置插件目前提供一个已知可用的默认语音，并返回 MP3 音频文件。 + + + ## 相关内容 -- [提供商目录](/zh-CN/providers/index) -- [图像生成](/zh-CN/tools/image-generation) -- [视频生成](/zh-CN/tools/video-generation) + + + 浏览所有可用提供商。 + + + 共享图像工具参数和提供商选择。 + + + 共享视频工具参数和提供商选择。 + + + 智能体默认值和模型配置。 + + diff --git a/docs/zh-CN/providers/xai.md b/docs/zh-CN/providers/xai.md index 278571fb7..be322481f 100644 --- a/docs/zh-CN/providers/xai.md +++ b/docs/zh-CN/providers/xai.md @@ -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`，或运行： + + + 在 [xAI 控制台](https://console.x.ai/) 中创建一个 API 密钥。 + + + 设置 `XAI_API_KEY`，或运行： -```bash -openclaw onboard --auth-choice xai-api-key -``` + ```bash + openclaw onboard --auth-choice xai-api-key + ``` -3. 选择一个模型，例如： + + + ```json5 + { + agents: { defaults: { model: { primary: "xai/grok-4" } } }, + } + ``` + + -```json5 -{ - agents: { defaults: { model: { primary: "xai/grok-4" } } }, -} -``` - -OpenClaw 现在使用 xAI Responses API 作为内置 xAI 传输层。同一个 -`XAI_API_KEY` 也可用于由 Grok 驱动的 `web_search`、原生的 `x_search`， -以及远程 `code_execution`。 + +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` 下。 + -## 当前内置模型目录 +## 内置模型目录 -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 形式时， +该插件也会继续将其转发解析。 -快速模型说明： + +`grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` 变体， +是当前内置目录中支持图像能力的 Grok 引用。 + -- `grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*` 变体，是当前内置目录中支持图像能力的 Grok 引用。 -- `/fast on` 或 `agents.defaults.models["xai/"].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/"].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` 工具注册了视频生成功能。 + + + 内置的 `grok` Web 搜索提供商也使用 `XAI_API_KEY`： -- 默认视频模型：`xai/grok-imagine-video` -- 模式：文生视频、图生视频，以及远程视频编辑/延长流程 -- 支持 `aspectRatio` 和 `resolution` -- 当前限制：不接受本地视频缓冲区；视频参考/编辑输入请使用远程 `http(s)` - URL + ```bash + openclaw config set tools.web.search.provider grok + ``` -要将 xAI 用作默认视频提供商： + -```json5 -{ - agents: { - defaults: { - videoGenerationModel: { - primary: "xai/grok-imagine-video", + + 内置的 `xai` 插件通过共享的 + `video_generate` 工具注册了视频生成功能。 + + - 默认视频模型：`xai/grok-imagine-video` + - 模式：文生视频、图生视频，以及远程视频编辑/扩展流程 + - 支持 `aspectRatio` 和 `resolution` + + + 不接受本地视频缓冲区。请对视频参考和编辑输入使用远程 `http(s)` URL。 + + + 要将 xAI 用作默认视频提供商： + + ```json5 + { + agents: { + defaults: { + videoGenerationModel: { + primary: "xai/grok-imagine-video", + }, + }, }, - }, - }, -} -``` + } + ``` -有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。 + + 有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。 + -## 已知限制 + -- 目前身份验证仅支持 API 密钥。OpenClaw 还不支持 xAI OAuth/设备代码流程。 -- `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI 提供商路径上不受支持，因为它所需的上游 API 接口与标准 OpenClaw xAI 传输层不同。 + + - 当前身份验证仅支持 API 密钥。OpenClaw 尚不支持 xAI OAuth 或设备代码流程。 + - `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI 提供商路径中不受支持，因为它所需的上游 API 接口不同于标准的 OpenClaw xAI 传输层。 + -## 说明 + + - OpenClaw 会在共享运行器路径上自动应用 xAI 特定的工具 schema 和工具调用兼容性修复。 + - 原生 xAI 请求默认使用 `tool_stream: true`。将 + `agents.defaults.models["xai/"].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)。 + + -- OpenClaw 会在共享运行器路径上自动应用 xAI 专用的工具模式和工具调用兼容性修复。 -- 原生 xAI 请求默认使用 `tool_stream: true`。将 - `agents.defaults.models["xai/"].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)。 +## 相关内容 + + + + 选择提供商、模型引用和故障切换行为。 + + + 共享视频工具参数和提供商选择。 + + + 更全面的提供商概览。 + + + 常见问题及修复方法。 + +