openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-24 15:14:53 +00:00
parent a88039dd04
commit 74b45515fb
3 changed files with 264 additions and 277 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

252
docs/zh-CN/concepts/model-providers.md
View File

@ -1,20 +1,20 @@
---
read_when:
- 你需要一份按提供商逐一说明的模型设置参考文档
- 你需要一份按提供商分类的模型设置参考文档
- 你想要模型提供商的示例配置或 CLI 新手引导命令
summary: 模型提供商概览，包含示例配置 + CLI 流程
summary: 模型提供商概览，包含示例配置和 CLI 流程
title: 模型提供商
x-i18n:
generated_at: "2026-04-24T05:42:12Z"
generated_at: "2026-04-24T15:13:07Z"
model: gpt-5.4
provider: openai
source_hash: ac9bf48897446576d8bc339b340295691741a589863bb57b379c17a5519bffd7
source_hash: 79258cb26fae7926c65b6fe0db938c7b5736a540b33bc24c1fad5ad706ac8204
source_path: concepts/model-providers.md
workflow: 15
---
此页面介绍的是 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。
关于模型选择规则，请参阅 [/concepts/models](/zh-CN/concepts/models)。
本页介绍的是 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。
关于模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。
## 快速规则
@ -22,39 +22,38 @@ x-i18n:
- 设置后，`agents.defaults.models` 会作为允许列表。
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
- `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时生效的上限。
- 回退规则、冷却探测和会话覆盖持久化：参阅 [模型故障切换](/zh-CN/concepts/model-failover)。
- OpenAI 系列路由按前缀区分：`openai/<model>` 在 PI 中使用直连 OpenAI API 密钥提供商，`openai-codex/<model>` 在 PI 中使用 Codex OAuth，而 `openai/<model>` 配合 `agents.defaults.embeddedHarness.runtime: "codex"` 则使用原生 Codex 应用服务器 harness。参阅 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。
- 插件自动启用也遵循同样的边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件由 `embeddedHarness.runtime: "codex"` 或旧版 `codex/<model>` 引用启用。
- GPT-5.5 当前可通过订阅 / OAuth 路由使用：在 PI 中使用 `openai-codex/gpt-5.5`，或使用 Codex 应用服务器 harness 时使用 `openai/gpt-5.5`。当 OpenAI 在公开 API 上启用 GPT-5.5 后，才支持 `openai/gpt-5.5` 的直连 API 密钥路由；在此之前，对于 `OPENAI_API_KEY` 设置，请使用已支持 API 的模型，例如 `openai/gpt-5.4`。
- 回退规则、冷却探测和会话覆盖持久化：参见 [模型故障转移](/zh-CN/concepts/model-failover)。
- OpenAI 系列路由按前缀区分：`openai/<model>` 在 PI 中使用直连 OpenAI API key 提供商，`openai-codex/<model>` 在 PI 中使用 Codex OAuth，而 `openai/<model>` 加上 `agents.defaults.embeddedHarness.runtime: "codex"` 则使用原生 Codex app-server harness。参见 [OpenAI](/zh-CN/providers/openai) 和 [Codex harness](/zh-CN/plugins/codex-harness)。
- 插件自动启用也遵循相同边界：`openai-codex/<model>` 属于 OpenAI 插件，而 Codex 插件会通过 `embeddedHarness.runtime: "codex"` 或旧版 `codex/<model>` 引用启用。
- GPT-5.5 当前可通过订阅/OAuth 路由使用：在 PI 中使用 `openai-codex/gpt-5.5`，或搭配 Codex app-server harness 使用 `openai/gpt-5.5`。`openai/gpt-5.5` 的直连 API key 路由会在 OpenAI 在公共 API 上启用 GPT-5.5 后受支持；在此之前，请在 `OPENAI_API_KEY` 配置中使用已支持 API 的模型，例如 `openai/gpt-5.4`。
## 插件拥有的提供商行为
大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 负责通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输 / 配置规范化、工具模式清理、故障切换分类、OAuth 刷新、用量报告、思考 / 推理配置等。
大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保持通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输/配置规范化、工具 schema 清理、故障转移分类、OAuth 刷新、用量报告、thinking/reasoning 配置等。
提供商 SDK 钩子的完整列表以及内置插件示例，请参阅 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，那属于另一个更深层的扩展接口。
提供商 SDK 钩子的完整列表以及内置插件示例，见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，那将属于另一个更深层的扩展接口。
<Note>
提供商运行时 `capabilities` 是共享的运行器元数据（提供商家族、转录 / 工具怪癖、传输 / 缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。
提供商运行时 `capabilities` 是共享执行器元数据（提供商家族、转录/工具特性、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。
</Note>
## API 密钥轮换
## API key 轮换
- 支持为选定提供商进行通用提供商密钥轮换。
- 可通过以下方式配置多个密钥：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，优先级最高）
- 支持为选定提供商进行通用提供商轮换。
- 通过以下方式配置多个 key：
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
- `<PROVIDER>_API_KEYS`（逗号或分号分隔列表）
- `<PROVIDER>_API_KEY`（主密钥）
- `<PROVIDER>_API_KEY`（主 key）
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
- 对于 Google 提供商，`GOOGLE_API_KEY` 也会作为回退项包含在内。
- 密钥选择顺序会保留优先级并对值去重。
- 仅在收到限流响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
- 非限流失败会立即失败；不会尝试密钥轮换。
- 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。
- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项。
- key 选择顺序会保留优先级，并对值去重。
- 仅在遇到速率限制响应时，请求才会使用下一个 key 重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性的用量限制消息）。
- 非速率限制失败会立即失败；不会尝试 key 轮换。
- 当所有候选 key 都失败时，返回最后一次尝试的最终错误。
## 内置提供商（pi-ai 目录）
## 内置提供商（pi-ai catalog）
OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
`models.providers` 配置；只需设置认证信息并选择一个模型。
OpenClaw 内置了 pi‑ai catalog。这些提供商**不需要**配置 `models.providers`；只需设置认证信息并选择一个模型。
### OpenAI
@ -62,17 +61,17 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 认证：`OPENAI_API_KEY`
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-mini`
- 一旦 OpenAI 在 API 中开放 GPT-5.5，这里就可直接支持 GPT-5.5 API
- 一旦 OpenAI 在 API 中开放 GPT-5.5，这里就已为 GPT-5.5 直连 API 支持做好准备
- CLI：`openclaw onboard --auth-choice openai-api-key`
- 默认传输为 `auto`（优先 WebSocket，回退到 SSE）
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 按模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- 可通过 `agents.defaults.models["openai/<model>"].params.transport` 为每个模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- OpenAI Responses WebSocket 预热默认启用，通过 `params.openaiWsWarmup` 控制（`true`/`false`）
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
- `/fast` 和 `params.fastMode` 会将直连 `openai/*` Responses 请求映射为发送到 `api.openai.com` 的 `service_tier=priority`
- 如果你希望使用显式层级而不是共享的 `/fast` 开关，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、提示缓存提示以及 OpenAI 推理兼容负载整形；代理路由不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中会被刻意屏蔽，因为实时 OpenAI API 请求会拒绝它，而当前 Codex 目录也未公开它
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先处理
- `/fast` 和 `params.fastMode` 会将直连 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
- 当你想要显式指定层级，而不是使用共享 `/fast` 开关时，请使用 `params.serviceTier`
- 隐藏的 OpenClaw 归属请求头（`originator`、`version`、`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用 OpenAI 兼容代理
- 原生 OpenAI 路由还会保留 Responses `store`、prompt-cache 提示以及 OpenAI reasoning 兼容负载整形；代理路由则不会
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 请求会拒绝它，而当前 Codex catalog 也未暴露它
```json5
{
@ -87,9 +86,9 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
- 示例模型：`anthropic/claude-opus-4-6`
- CLI：`openclaw onboard --auth-choice apiKey`
- 直连公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将 Claude CLI 复用和 `claude -p` 用法视为该集成已获认可，除非 Anthropic 发布新的政策。
- Anthropic setup-token 仍然作为受支持的 OpenClaw 令牌路径保留，但 OpenClaw 现在在可用时优先使用 Claude CLI 复用和 `claude -p`。
- 直连公共 Anthropic 请求支持共享 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API key 和 OAuth 认证流量；OpenClaw 会将其映射到 Anthropic `service_tier`（`auto` 与 `standard_only`）
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 认为复用 Claude CLI 和使用 `claude -p` 都属于该集成的许可范围。
- Anthropic setup-token 仍然可作为 OpenClaw 支持的令牌路径，但 OpenClaw 现在在可用时优先选择复用 Claude CLI 和 `claude -p`。
```json5
{
@ -102,18 +101,18 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 提供商：`openai-codex`
- 认证：OAuth（ChatGPT）
- PI 模型引用：`openai-codex/gpt-5.5`
- 原生 Codex 应用服务器 harness 引用：`openai/gpt-5.5`，并设置 `agents.defaults.embeddedHarness.runtime: "codex"`
- 原生 Codex app-server harness 引用：`openai/gpt-5.5`，并设置 `agents.defaults.embeddedHarness.runtime: "codex"`
- 旧版模型引用：`codex/gpt-*`
- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex 应用服务器插件仅由 Codex harness 运行时或旧版 `codex/*` 引用选择
- 插件边界：`openai-codex/*` 会加载 OpenAI 插件；原生 Codex app-server 插件仅通过 Codex harness 运行时或旧版 `codex/*` 引用选择。
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
- 默认传输为 `auto`（优先 WebSocket，回退到 SSE）
- 可通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 按 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会转发到原生 Codex Responses 请求（`chatgpt.com/backend-api`）
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
- 与直连 `openai/*` 共享同样的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
- 可通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 为每个 PI 模型覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
- `params.serviceTier` 也会透传到原生 Codex Responses 请求（`chatgpt.com/backend-api`）
- 隐藏的 OpenClaw 归属请求头（`originator`、`version`、`User-Agent`）仅附加到发往 `chatgpt.com/backend-api` 的原生 Codex 流量，不适用于通用 OpenAI 兼容代理
- 与直连 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
- `openai-codex/gpt-5.5` 保留原生 `contextWindow = 1000000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
- 策略说明：OpenAI Codex OAuth 明确支持像 OpenClaw 这样的外部工具 / 工作流。
- 当前的 GPT-5.5 访问使用此 OAuth / 订阅路由，直到 OpenAI 在公开 API 中启用 GPT-5.5。
- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这样的外部工具/工作流。
- 当前 GPT-5.5 访问使用此 OAuth/订阅路由，直到 OpenAI 在公共 API 中启用 GPT-5.5。
```json5
{
@ -136,7 +135,7 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
### 其他订阅式托管选项
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API key 访问
- [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点
### OpenCode
@ -153,23 +152,21 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
}
```
### Google Gemini（API 密钥）
### Google Gemini（API key）
- 提供商：`google`
- 认证：`GEMINI_API_KEY`
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、回退 `GOOGLE_API_KEY`，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被规范化为 `google/gemini-3-flash-preview`
- 兼容性：旧版 OpenClaw 配置中使用的 `google/gemini-3.1-flash-preview` 会被规范化为 `google/gemini-3-flash-preview`
- CLI：`openclaw onboard --auth-choice gemini-api-key`
- 直连 Gemini 运行也接受 `agents.defaults.models["google/<model>"].params.cachedContent`
（或旧版 `cached_content`），用于转发提供商原生的
`cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
- 直连 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`（或旧版 `cached_content`），用于转发提供商原生的 `cachedContents/...` 句柄；Gemini 缓存命中会以 OpenClaw `cacheRead` 的形式展示
### Google Vertex 和 Gemini CLI
- 提供商：`google-vertex`、`google-gemini-cli`
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
- 注意：OpenClaw 中的 Gemini CLI OAuth 属于非官方集成。一些用户报告称，使用第三方客户端后 Google 账号会受到限制。若你选择继续，请先查看 Google 条款，并使用非关键账号。
- 注意：OpenClaw 中的 Gemini CLI OAuth 属于非官方集成。有些用户报告在使用第三方客户端后，Google 账号受到限制。若你选择继续，请查看 Google 条款，并使用非关键账号。
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
- 先安装 Gemini CLI：
- `brew install gemini-cli`
@ -179,8 +176,7 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 默认模型：`google-gemini-cli/gemini-3-flash-preview`
- 注意：你**不需要**把 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将令牌存储在 Gateway 网关主机上的认证配置文件中。
- 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
- Gemini CLI JSON 回复会从 `response` 解析；用量会回退到
`stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
- Gemini CLI JSON 回复会从 `response` 解析；用量信息会回退到 `stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
### Z.AI（GLM）
@ -205,29 +201,28 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
- 认证：`KILOCODE_API_KEY`
- 示例模型：`kilocode/kilo/auto`
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
- 基础 URL：`https://api.kilo.ai/api/gateway/`
- 静态回退目录内置 `kilocode/kilo/auto`；实时
`https://api.kilo.ai/api/gateway/models` 发现机制可以进一步扩展运行时目录。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 决定，
并非 OpenClaw 内部硬编码。
- Base URL：`https://api.kilo.ai/api/gateway/`
- 静态回退 catalog 内置 `kilocode/kilo/auto`；实时 `https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时 catalog。
- `kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 负责，不是 OpenClaw 中硬编码的。
设置详情请参阅 [/providers/kilocode](/zh-CN/providers/kilocode)。
设置详情请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
### 其他内置提供商插件
| 提供商 | Id | 认证环境变量 | 示例模型 |
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
| BytePlus（国际版） | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` |
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
| Groq | `groq` | `GROQ_API_KEY` | — |
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` |
| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` |
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
| Moonshot AI | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` |
| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` |
| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` |
| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` |
| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` |
@ -240,27 +235,28 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` |
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
值得了解的特殊点：
值得了解的特殊行为：
- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因请求头和 Anthropic `cache_control` 标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形处理（`serviceTier`、Responses `store`、提示缓存提示、OpenAI 推理兼容性）。以 Gemini 为后端的引用仅保留代理 Gemini 的 thought-signature 清理。
- **Kilo Gateway** 以 Gemini 为后端的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理推理的引用会跳过代理推理注入。
- **MiniMax** API 密钥新手引导会写入显式的 M2.7 模型定义，并设置 `input: ["text", "image"]`；在该配置具体化之前，内置目录会将聊天引用保持为纯文本。
- **xAI** 使用 xAI Responses 路径。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 改写为对应的 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
- **Cerebras** GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。
- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归属请求头和 Anthropic `cache_control` 标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形逻辑（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI reasoning 兼容）。基于 Gemini 的引用仅保留代理 Gemini thought-signature 清理。
- **Kilo Gateway** 中基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。
- **MiniMax** API key 新手引导会写入显式的 M2.7 模型定义，并设置 `input: ["text", "image"]`；在该配置具体化之前，内置 catalog 会将聊天引用保持为仅文本。
- **xAI** 使用 xAI Responses 路径。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为对应的 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
- **Cerebras** GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容 Base URL 为 `https://api.cerebras.ai/v1`。
## 通过 `models.providers` 配置的提供商（自定义 / 基础 URL）
## 通过 `models.providers` 配置的提供商（自定义/Base URL）
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或
兼容 OpenAI/Anthropic 的代理。
下面许多内置提供商插件已经发布了默认目录。
只有在你想覆盖默认基础 URL、请求头或模型列表时，才需要使用显式的
`models.providers.<id>` 条目。
下面许多内置提供商插件已经发布了默认 catalog。
只有当你想覆盖默认 base URL、请求头或模型列表时，
才需要显式使用 `models.providers.<id>` 条目。
### Moonshot AI（Kimi）
Moonshot 作为内置提供商插件提供。默认情况下请使用内置提供商，只有在你
需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
Moonshot 作为内置提供商插件提供。默认情况下请使用内置提供商，
只有在你需要覆盖 base URL 或模型元数据时，
才添加显式的 `models.providers.moonshot` 条目：
- 提供商：`moonshot`
- 认证：`MOONSHOT_API_KEY`
@ -315,13 +311,13 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
}
```
旧版 `kimi/k2p5` 仍然作为兼容性模型 ID 被接受。
旧版 `kimi/k2p5` 仍然作为兼容模型 ID 被接受。
### Volcano Engine（Doubao）
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
- 提供商：`volcengine`（编程：`volcengine-plan`）
- 提供商：`volcengine`（编程方案：`volcengine-plan`）
- 认证：`VOLCANO_ENGINE_API_KEY`
- 示例模型：`volcengine-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
@ -335,11 +331,12 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
```
新手引导默认使用编程接口，但通用 `volcengine/*`
目录也会同时注册。
catalog 也会同时注册。
在新手引导 / 配置模型选择器中，Volcengine 认证选项会优先显示
`volcengine/*` 和 `volcengine-plan/*` 两类条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。
在新手引导/配置模型选择器中，Volcengine 认证选项会优先显示
`volcengine/*` 和 `volcengine-plan/*` 条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选的 catalog，而不是显示一个空的、
按提供商范围过滤的选择器。
可用模型：
@ -361,7 +358,7 @@ OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。
- 提供商：`byteplus`（编程：`byteplus-plan`）
- 提供商：`byteplus`（编程方案：`byteplus-plan`）
- 认证：`BYTEPLUS_API_KEY`
- 示例模型：`byteplus-plan/ark-code-latest`
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
@ -375,11 +372,12 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
```
新手引导默认使用编程接口，但通用 `byteplus/*`
目录也会同时注册。
catalog 也会同时注册。
在新手引导 / 配置模型选择器中，BytePlus 认证选项会优先显示
`byteplus/*` 和 `byteplus-plan/*` 两类条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选目录，而不是显示一个空的提供商范围选择器。
在新手引导/配置模型选择器中，BytePlus（国际版）认证选项会优先显示
`byteplus/*` 和 `byteplus-plan/*` 条目。如果这些模型尚未加载，
OpenClaw 会回退到未筛选的 catalog，而不是显示一个空的、
按提供商范围过滤的选择器。
可用模型：
@ -429,22 +427,21 @@ MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
- MiniMax OAuth（全球）：`--auth-choice minimax-global-oauth`
- MiniMax OAuth（中国）：`--auth-choice minimax-cn-oauth`
- MiniMax API 密钥（全球）：`--auth-choice minimax-global-api`
- MiniMax API 密钥（中国）：`--auth-choice minimax-cn-api`
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或
`MINIMAX_API_KEY`
- MiniMax API key（全球）：`--auth-choice minimax-global-api`
- MiniMax API key（中国）：`--auth-choice minimax-cn-api`
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或 `MINIMAX_API_KEY`
设置详情、模型选项和配置片段请参阅 [/providers/minimax](/zh-CN/providers/minimax)。
设置详情、模型选项和配置片段请参见 [/providers/minimax](/zh-CN/providers/minimax)。
在 MiniMax 的 Anthropic 兼容流式路径上，OpenClaw 默认会禁用 thinking，
除非你显式设置它；而 `/fast on` 会将
`MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。
在 MiniMax 的 Anthropic 兼容流式传输路径上，OpenClaw 默认禁用 thinking，
除非你显式设置它，并且 `/fast on` 会将
`MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
插件拥有的能力拆分：
- 文本 / 聊天默认保持在 `minimax/MiniMax-M2.7`
- 图像生成为 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解在两个 MiniMax 认证路径上都使用由插件管理的 `MiniMax-VL-01`
- 文本/聊天默认保持在 `minimax/MiniMax-M2.7`
- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01`
- 图像理解在两种 MiniMax 认证路径上都使用由插件拥有的 `MiniMax-VL-01`
- Web 搜索保持使用提供商 id `minimax`
### LM Studio
@ -453,7 +450,7 @@ LM Studio 作为内置提供商插件提供，并使用原生 API：
- 提供商：`lmstudio`
- 认证：`LM_API_TOKEN`
- 默认推理基础 URL：`http://localhost:1234/v1`
- 默认推理 base URL：`http://localhost:1234/v1`
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
@ -465,9 +462,8 @@ LM Studio 作为内置提供商插件提供，并使用原生 API：
}
```
OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load`
进行发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。
设置和故障排除请参阅 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load` 进行设备发现 + 自动加载，并默认使用 `/v1/chat/completions` 进行推理。
设置和故障排除请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
### Ollama
@ -476,7 +472,7 @@ Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
- 提供商：`ollama`
- 认证：无需（本地服务器）
- 示例模型：`ollama/llama3.3`
- 安装：[https://ollama.com/download](https://ollama.com/download)
- 安装： [https://ollama.com/download](https://ollama.com/download)
```bash
# Install Ollama, then pull a model:
@ -491,22 +487,19 @@ ollama pull llama3.3
}
```
当你通过
`OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，
而内置提供商插件会将 Ollama 直接添加到
`openclaw onboard` 和模型选择器中。关于新手引导、云端 / 本地模式和自定义配置，
请参阅 [/providers/ollama](/zh-CN/providers/ollama)。
当你通过 `OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，并且内置提供商插件会将 Ollama 直接添加到
`openclaw onboard` 和模型选择器中。关于新手引导、云端/本地模式以及自定义配置，请参见 [/providers/ollama](/zh-CN/providers/ollama)。
### vLLM
vLLM 作为内置提供商插件提供，用于本地 / 自托管的 OpenAI 兼容
vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容
服务器：
- 提供商：`vllm`
- 认证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:8000/v1`
- 默认 base URL：`http://127.0.0.1:8000/v1`
要在本地启用自动发现（如果你的服务器不强制认证，任意值都可用）：
要在本地启用自动发现（如果你的服务器不强制认证，任意值都可以）：
```bash
export VLLM_API_KEY="vllm-local"
@ -522,19 +515,19 @@ export VLLM_API_KEY="vllm-local"
}
```
详情请参阅 [/providers/vllm](/zh-CN/providers/vllm)。
详情请参见 [/providers/vllm](/zh-CN/providers/vllm)。
### SGLang
SGLang 作为内置提供商插件提供，用于快速自托管的
SGLang 作为内置提供商插件提供，用于高速自托管的
OpenAI 兼容服务器：
- 提供商：`sglang`
- 认证：可选（取决于你的服务器）
- 默认基础 URL：`http://127.0.0.1:30000/v1`
- 默认 base URL：`http://127.0.0.1:30000/v1`
要在本地启用自动发现（如果你的服务器未强制
认证，任意值都可用）：
要在本地启用自动发现（如果你的服务器不
强制认证，任意值都可以）：
```bash
export SGLANG_API_KEY="sglang-local"
@ -550,7 +543,7 @@ export SGLANG_API_KEY="sglang-local"
}
```
详情请参阅 [/providers/sglang](/zh-CN/providers/sglang)。
详情请参见 [/providers/sglang](/zh-CN/providers/sglang)。
### 本地代理（LM Studio、vLLM、LiteLLM 等）
@ -589,21 +582,18 @@ export SGLANG_API_KEY="sglang-local"
说明：
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选项。
省略时，OpenClaw 默认使用：
- `reasoning: false`
- `input: ["text"]`
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
- `contextWindow: 200000`
- `maxTokens: 8192`
- 建议：设置与你的代理 / 模型限制相匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（即任意非空 `baseUrl` 且其主机不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理式 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求
整形：没有 `service_tier`、没有 Responses `store`、没有提示缓存提示、没有
OpenAI 推理兼容负载整形，也没有隐藏的 OpenClaw 归因
请求头。
- 如果 `baseUrl` 为空 / 省略，OpenClaw 会保留默认的 OpenAI 行为（即解析到 `api.openai.com`）。
- 为安全起见，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。
- 建议：设置与你的代理/模型限制匹配的显式值。
- 对于非原生端点上的 `api: "openai-completions"`（任何非空的 `baseUrl`，且其 host 不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
- 代理式 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求整形：不使用 `service_tier`、不使用 Responses `store`、不使用 prompt-cache 提示、不进行 OpenAI reasoning 兼容负载整形，也不附加隐藏的 OpenClaw 归属请求头。
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（即解析到 `api.openai.com`）。
- 出于安全考虑，即使在非原生 `openai-completions` 端点上显式设置了 `compat.supportsDeveloperRole: true`，仍会被覆盖。
## CLI 示例
@ -613,11 +603,11 @@ openclaw models set opencode/claude-opus-4-6
openclaw models list
```
另请参阅：[/gateway/configuration](/zh-CN/gateway/configuration) 了解完整配置示例。
另请参见：[/gateway/configuration](/zh-CN/gateway/configuration)，了解完整配置示例。
## 相关内容
- [Models](/zh-CN/concepts/models) — 模型配置和别名
- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [模型](/zh-CN/concepts/models) — 模型配置和别名
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为
- [配置参考](/zh-CN/gateway/config-agents#agent-defaults) — 模型配置键
- [Providers](/zh-CN/providers) — 按提供商分类的设置指南
- [提供商](/zh-CN/providers) — 按提供商分类的设置指南

239
docs/zh-CN/pi.md
View File

@ -1,48 +1,48 @@
---
read_when:
- 了解 OpenClaw 中的 Pi SDK 集成设计
- 修改 Pi 的智能体会话生命周期、工具接线或提供商接线
summary: OpenClaw 的内置 Pi 智能体集成架构与会话生命周期
- 理解 OpenClaw 中 Pi SDK 集成设计
- 修改 Pi 的智能体会话生命周期、工具链或提供商接线
summary: OpenClaw 内置 Pi 智能体集成的架构与会话生命周期
title: Pi 集成架构
x-i18n:
generated_at: "2026-04-24T04:04:41Z"
generated_at: "2026-04-24T15:13:09Z"
model: gpt-5.4
provider: openai
source_hash: 3c0c490cad121a65d557a72887ea619a7d0cff34a62220752214185c9148dc0b
source_hash: 0c0b019ff6d35f6fdcd57b56edd1945e62a96bb4b34e312d7fb0c627f01287f1
source_path: pi.md
workflow: 15
---
本文介绍 OpenClaw 如何与 [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) 及其同级包（`pi-ai`、`pi-agent-core`、`pi-tui`）集成，以提供其 AI 智能体能力。
本文档介绍了 OpenClaw 如何集成 [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) 及其同级软件包（`pi-ai`、`pi-agent-core`、`pi-tui`），以提供其 AI 智能体能力。
## 概览
OpenClaw 使用 pi SDK 将一个 AI 编码智能体嵌入到其消息 Gateway 网关架构中。OpenClaw 并不是将 pi 作为子进程启动，也不是使用 RPC 模式，而是直接导入并实例化 pi 的 `AgentSession`，方式是通过 `createAgentSession()`。这种内嵌式方法提供了：
OpenClaw 使用 pi SDK 将一个 AI 编码智能体嵌入到其消息 Gateway 网关架构中。OpenClaw 并不是将 pi 作为子进程启动，也不是使用 RPC 模式，而是通过 `createAgentSession()` 直接导入并实例化 pi 的 `AgentSession`。这种内嵌式方案提供了：
- 对会话生命周期和事件处理的完全控制
- 自定义工具注入（消息、沙箱、渠道特定操作）
- 按渠道 / 上下文定制系统提示
- 支持分支 / 压缩的会话持久化
- 带故障转移的多账户认证配置文件轮换
- 与提供商无关的模型切换
- 按渠道/上下文自定义系统提示词
- 支持分支/压缩的会话持久化
- 具备故障转移能力的多账户认证配置轮换
- 提供商无关的模型切换
## 包依赖
## 软件包依赖
```json
{
"@mariozechner/pi-agent-core": "0.68.1",
"@mariozechner/pi-ai": "0.68.1",
"@mariozechner/pi-coding-agent": "0.68.1",
"@mariozechner/pi-tui": "0.68.1"
"@mariozechner/pi-agent-core": "0.70.2",
"@mariozechner/pi-ai": "0.70.2",
"@mariozechner/pi-coding-agent": "0.70.2",
"@mariozechner/pi-tui": "0.70.2"
}
```
| Package | 用途 |
| 软件包 | 用途 |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `pi-ai` | 核心 LLM 抽象：`Model`、`streamSimple`、消息类型、提供商 API |
| `pi-agent-core` | 智能体循环、工具执行、`AgentMessage` 类型 |
| `pi-coding-agent` | 高级 SDK：`createAgentSession`、`SessionManager`、`AuthStorage`、`ModelRegistry`、内置工具 |
| `pi-tui` | 终端 UI 组件（用于 OpenClaw 的本地 TUI 模式） |
| `pi-ai` | 核心 LLM 抽象：`Model`、`streamSimple`、消息类型、提供商 API |
| `pi-agent-core` | 智能体循环、工具执行、`AgentMessage` 类型 |
| `pi-coding-agent` | 高层 SDK：`createAgentSession`、`SessionManager`、`AuthStorage`、`ModelRegistry`、内置工具 |
| `pi-tui` | 终端 UI 组件（用于 OpenClaw 的本地 TUI 模式） |
## 文件结构
@ -52,44 +52,44 @@ src/agents/
├── pi-embedded-runner/
│ ├── run.ts # 主入口：runEmbeddedPiAgent()
│ ├── run/
│ │ ├── attempt.ts # 带会话设置的单次尝试逻辑
│ │ ├── attempt.ts # 包含会话设置的单次尝试逻辑
│ │ ├── params.ts # RunEmbeddedPiAgentParams 类型
│ │ ├── payloads.ts # 从运行结果构建响应负载
│ │ ├── images.ts # Vision 模型图片注入
│ │ ├── images.ts # 视觉模型图像注入
│ │ └── types.ts # EmbeddedRunAttemptResult
│ ├── abort.ts # Abort 错误检测
│ ├── cache-ttl.ts # 用于上下文裁剪的缓存 TTL 跟踪
│ ├── compact.ts # 手动 / 自动压缩逻辑
│ ├── extensions.ts # 为内嵌运行加载 pi 扩展
│ ├── extra-params.ts # 提供商特定的流参数
│ ├── compact.ts # 手动/自动压缩逻辑
│ ├── extensions.ts # 为嵌入式运行加载 pi 扩展
│ ├── extra-params.ts # 提供商特定的流式参数
│ ├── google.ts # Google/Gemini 轮次顺序修复
│ ├── history.ts # 历史记录限制（私信 vs 群组）
│ ├── lanes.ts # 会话 / 全局命令通道
│ ├── lanes.ts # 会话/全局命令通道
│ ├── logger.ts # 子系统日志记录器
│ ├── model.ts # 通过 ModelRegistry 解析模型
│ ├── runs.ts # 活跃运行跟踪、终止、队列
│ ├── sandbox-info.ts # 用于系统提示的沙箱信息
│ ├── session-manager-cache.ts # SessionManager 实例缓存
│ ├── model.ts # 通过 ModelRegistry 进行模型解析
│ ├── runs.ts # 活跃运行跟踪、Abort、队列
│ ├── sandbox-info.ts # 用于系统提示词的沙箱信息
│ ├── session-manager-cache.ts # `SessionManager` 实例缓存
│ ├── session-manager-init.ts # 会话文件初始化
│ ├── system-prompt.ts # 系统提示构建器
│ ├── tool-split.ts # 将工具拆分为 builtIn 和 custom
│ ├── system-prompt.ts # 系统提示词构建器
│ ├── tool-split.ts # 将工具拆分为 builtIn 与 custom
│ ├── types.ts # EmbeddedPiAgentMeta、EmbeddedPiRunResult
│ └── utils.ts # ThinkLevel 映射、错误描述
├── pi-embedded-subscribe.ts # 会话事件订阅 / 分发
├── pi-embedded-subscribe.ts # 会话事件订阅/分发
├── pi-embedded-subscribe.types.ts # SubscribeEmbeddedPiSessionParams
├── pi-embedded-subscribe.handlers.ts # 事件处理器工厂
├── pi-embedded-subscribe.handlers.lifecycle.ts
├── pi-embedded-subscribe.handlers.types.ts
├── pi-embedded-block-chunker.ts # 流式块回复分块
├── pi-embedded-block-chunker.ts # 流式分块回复切块
├── pi-embedded-messaging.ts # 消息工具发送跟踪
├── pi-embedded-helpers.ts # 错误分类、轮次验证
├── pi-embedded-helpers/ # 辅助模块
├── pi-embedded-utils.ts # 格式化工具
├── pi-embedded-utils.ts # 格式化工具函数
├── pi-tools.ts # createOpenClawCodingTools()
├── pi-tools.abort.ts # 为工具包装 AbortSignal
├── pi-tools.policy.ts # 工具允许列表 / 拒绝列表策略
├── pi-tools.read.ts # read 工具自定义
├── pi-tools.schema.ts # 工具 schema 标准化
├── pi-tools.abort.ts # 面向工具的 AbortSignal 封装
├── pi-tools.policy.ts # 工具 allowlist/denylist 策略
├── pi-tools.read.ts # Read 工具自定义
├── pi-tools.schema.ts # 工具 schema 规范化
├── pi-tools.types.ts # AnyAgentTool 类型别名
├── pi-tool-definition-adapter.ts # AgentTool -> ToolDefinition 适配器
├── pi-settings.ts # 设置覆盖
@ -98,29 +98,29 @@ src/agents/
│ ├── compaction-safeguard-runtime.ts
│ ├── context-pruning.ts # 缓存 TTL 上下文裁剪扩展
│ └── context-pruning/
├── model-auth.ts # 认证配置文件解析
├── auth-profiles.ts # 配置文件存储、冷却、故障转移
├── model-auth.ts # 认证配置解析
├── auth-profiles.ts # 配置存储、冷却、故障转移
├── model-selection.ts # 默认模型解析
├── models-config.ts # models.json 生成
├── models-config.ts # `models.json` 生成
├── model-catalog.ts # 模型目录缓存
├── context-window-guard.ts # 上下文窗口验证
├── failover-error.ts # FailoverError 类
├── failover-error.ts # `FailoverError` 类
├── defaults.ts # DEFAULT_PROVIDER、DEFAULT_MODEL
├── system-prompt.ts # buildAgentSystemPrompt()
├── system-prompt-params.ts # 系统提示参数解析
├── system-prompt-params.ts # 系统提示词参数解析
├── system-prompt-report.ts # 调试报告生成
├── tool-summaries.ts # 工具描述摘要
├── tool-policy.ts # 工具策略解析
├── transcript-policy.ts # 转录验证策略
├── skills.ts # Skill 快照 / 提示构建
├── skills/ # Skill 子系统
├── skills.ts # Skills 快照/提示词构建
├── skills/ # Skills 子系统
├── sandbox.ts # 沙箱上下文解析
├── sandbox/ # 沙箱子系统
├── channel-tools.ts # 渠道特定工具注入
├── openclaw-tools.ts # OpenClaw 特定工具
├── bash-tools.ts # exec/process 工具
├── apply-patch.ts # apply_patch 工具（OpenAI）
├── tools/ # 各个工具实现
├── tools/ # 各个独立工具实现
│ ├── browser-tool.ts
│ ├── canvas-tool.ts
│ ├── cron-tool.ts
@ -134,16 +134,16 @@ src/agents/
└── ...
```
渠道特定的消息操作运行时现在位于由 plugin 拥有的扩展目录中，而不是放在 `src/agents/tools` 下，例如：
渠道特定的消息操作运行时现在位于插件所属的扩展目录中，而不再位于 `src/agents/tools` 下，例如：
- Discord plugin 操作运行时文件
- Slack plugin 操作运行时文件
- Telegram plugin 操作运行时文件
- WhatsApp plugin 操作运行时文件
- Discord 插件操作运行时文件
- Slack 插件操作运行时文件
- Telegram 插件操作运行时文件
- WhatsApp 插件操作运行时文件
## 核心集成流程
### 1. 运行内嵌智能体
### 1. 运行嵌入式智能体
主入口是 `pi-embedded-runner/run.ts` 中的 `runEmbeddedPiAgent()`：
@ -167,9 +167,9 @@ const result = await runEmbeddedPiAgent({
});
```
### 2. 创建会话
### 2. 会话创建
在 `runEmbeddedAttempt()` 内部（由 `runEmbeddedPiAgent()` 调用），使用了 pi SDK：
在 `runEmbeddedAttempt()`（由 `runEmbeddedPiAgent()` 调用）内部，使用了 pi SDK：
```typescript
import {
@ -225,13 +225,13 @@ const subscription = subscribeEmbeddedPiSession({
处理的事件包括：
- `message_start` / `message_end` / `message_update`（流式文本 / thinking）
- `message_start` / `message_end` / `message_update`（流式文本/思考）
- `tool_execution_start` / `tool_execution_update` / `tool_execution_end`
- `turn_start` / `turn_end`
- `agent_start` / `agent_end`
- `compaction_start` / `compaction_end`
### 4. 提示
### 4. 提示输入
设置完成后，会向会话发送提示：
@ -241,25 +241,23 @@ await session.prompt(effectivePrompt, { images: imageResult.images });
SDK 会处理完整的智能体循环：发送给 LLM、执行工具调用、流式传输响应。
图片注入是提示局部的：OpenClaw 会从当前提示中加载图片引用，
并仅通过 `images` 为该轮传递这些图片。它不会重新扫描更早的历史轮次，
来重新注入图片负载。
图像注入仅限当前提示：OpenClaw 会从当前提示中加载图像引用，并通过 `images` 仅传递给该轮。它不会重新扫描更早的历史轮次来重新注入图像负载。
## 工具架构
### 工具管线
### 工具流水线
1. **基础工具**：pi 的 `codingTools`（read、bash、edit、write）
2. **自定义替换**：OpenClaw 用 `exec`/`process` 替换 bash，并为沙箱定制 read/edit/write
3. **OpenClaw 工具**：消息、浏览器、canvas、会话、cron、gateway 等
2. **自定义替换**：OpenClaw 用 `exec`/`process` 替换 bash，并为沙箱自定义 read/edit/write
3. **OpenClaw 工具**：消息、浏览器、画布、会话、cron、Gateway 网关 等
4. **渠道工具**：Discord/Telegram/Slack/WhatsApp 特定操作工具
5. **策略过滤**：根据配置文件、提供商、智能体、群组、沙箱策略过滤工具
6. **Schema 标准化**：为 Gemini/OpenAI 的特殊情况清理 schema
7. **AbortSignal 包装**：包装工具以遵守 abort 信号
5. **策略过滤**：按配置、提供商、智能体、群组、沙箱策略过滤工具
6. **Schema 规范化**：针对 Gemini/OpenAI 的特殊情况清理 schema
7. **AbortSignal 封装**：封装工具以支持 abort signals
### 工具定义适配器
pi-agent-core 的 `AgentTool` 与 pi-coding-agent 的 `ToolDefinition` 在 `execute` 签名上不同。`pi-tool-definition-adapter.ts` 中的适配器负责桥接这一点：
pi-agent-core 的 `AgentTool` 与 pi-coding-agent 的 `ToolDefinition` 在 `execute` 签名上不同。`pi-tool-definition-adapter.ts` 中的适配器负责桥接这一差异：
```typescript
export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
@ -283,19 +281,19 @@ export function toToolDefinitions(tools: AnyAgentTool[]): ToolDefinition[] {
```typescript
export function splitSdkTools(options: { tools: AnyAgentTool[]; sandboxEnabled: boolean }) {
return {
builtInTools: [], // 空。我们覆盖所有内容
builtInTools: [], // 为空。我们会覆盖所有内容
customTools: toToolDefinitions(options.tools),
};
}
```
这可确保 OpenClaw 的策略过滤、沙箱集成和扩展工具集在不同提供商之间保持一致。
这可确保 OpenClaw 的策略过滤、沙箱集成和扩展工具集在各个提供商之间保持一致。
## 系统提示构建
## 系统提示词构建
系统提示在 `buildAgentSystemPrompt()`（`system-prompt.ts`）中构建。它会组装一个完整提示，其中包含 Tooling、Tool Call Style、安全护栏、OpenClaw CLI 参考、Skills、文档、工作区、沙箱、消息、回复标签、语音、静默回复、心跳、运行时元数据，以及在启用时包含 Memory 和 Reactions，还可以附加可选的上下文文件和额外系统提示内容。对于子智能体使用的最小提示模式，这些部分会被裁剪。
系统提示词在 `buildAgentSystemPrompt()`（`system-prompt.ts`）中构建。它会组装一个完整的提示词，其中包含 Tooling、Tool Call Style、安全护栏、OpenClaw CLI 参考、Skills、文档、工作区、沙箱、消息、回复标签、语气、静默回复、心跳、运行时元数据，以及在启用时包含的 Memory 和 Reactions，还可包含可选的上下文文件和额外系统提示词内容。用于子智能体的最小提示词模式会对这些部分进行裁剪。
该提示会在会话创建后通过 `applySystemPromptOverrideToSession()` 应用：
系统提示词会在创建会话后通过 `applySystemPromptOverrideToSession()` 应用：
```typescript
const systemPromptOverride = createSystemPromptOverride(appendPrompt);
@ -306,17 +304,17 @@ applySystemPromptOverrideToSession(session, systemPromptOverride);
### 会话文件
会话是带有树结构（通过 id/parentId 链接）的 JSONL 文件。Pi 的 `SessionManager` 负责持久化：
会话是具有树状结构的 JSONL 文件（通过 id/parentId 链接）。Pi 的 `SessionManager` 负责持久化：
```typescript
const sessionManager = SessionManager.open(params.sessionFile);
```
OpenClaw 使用 `guardSessionManager()` 对其进行包装，以确保工具结果安全。
OpenClaw 通过 `guardSessionManager()` 对其进行包装，以保证工具结果安全。
### 会话缓存
`session-manager-cache.ts` 会缓存 SessionManager 实例，以避免重复解析文件：
`session-manager-cache.ts` 会缓存 `SessionManager` 实例，以避免重复解析文件：
```typescript
await prewarmSessionFile(params.sessionFile);
@ -326,16 +324,11 @@ trackSessionManagerAccess(params.sessionFile);
### 历史记录限制
`limitHistoryTurns()` 会根据渠道类型（私信 vs 群组）裁剪对话历史。
`limitHistoryTurns()` 会根据渠道类型（私信 与 群组）裁剪对话历史。
### 压缩
发生上下文溢出时会触发自动压缩。常见的溢出特征
包括 `request_too_large`、`context length exceeded`、`input exceeds the
maximum number of tokens`、`input token count exceeds the maximum number of
input tokens`、`input is too long for the model` 以及 `ollama error: context
length exceeded`。`compactEmbeddedPiSessionDirect()` 负责处理手动
压缩：
当上下文溢出时会触发自动压缩。常见的溢出特征包括 `request_too_large`、`context length exceeded`、`input exceeds the maximum number of tokens`、`input token count exceeds the maximum number of input tokens`、`input is too long for the model`，以及 `ollama error: context length exceeded`。`compactEmbeddedPiSessionDirect()` 负责处理手动压缩：
```typescript
const compactResult = await compactEmbeddedPiSessionDirect({
@ -345,16 +338,16 @@ const compactResult = await compactEmbeddedPiSessionDirect({
## 认证与模型解析
### 认证配置文件
### 认证配置
OpenClaw 维护一个认证配置文件存储，可为每个提供商保存多个 API 密钥：
OpenClaw 维护一个认证配置存储，每个提供商可对应多个 API 密钥：
```typescript
const authStore = ensureAuthProfileStore(agentDir, { allowKeychainPrompt: false });
const profileOrder = resolveAuthProfileOrder({ cfg, store: authStore, provider, preferredProfile });
```
配置文件会在失败时轮换，并跟踪冷却状态：
配置在失败时会轮换，并带有冷却跟踪：
```typescript
await markAuthProfileFailure({ store, profileId, reason, cfg, agentDir });
@ -379,7 +372,7 @@ authStorage.setRuntimeApiKey(model.provider, apiKeyInfo.apiKey);
### 故障转移
配置了回退时，`FailoverError` 会触发模型回退：
配置后，`FailoverError` 会触发模型回退：
```typescript
if (fallbackConfigured && isFailoverErrorMessage(errorText)) {
@ -395,11 +388,11 @@ if (fallbackConfigured && isFailoverErrorMessage(errorText)) {
## Pi 扩展
OpenClaw 会加载自定义 Pi 扩展，以支持特定行为：
OpenClaw 会加载自定义 pi 扩展，以支持专门行为：
### 压缩保护
`src/agents/pi-hooks/compaction-safeguard.ts` 为压缩添加了保护措施，包括自适应 token 预算，以及工具失败和文件操作摘要：
`src/agents/pi-hooks/compaction-safeguard.ts` 为压缩添加护栏，包括自适应 token 预算，以及工具失败和文件操作摘要：
```typescript
if (resolveCompactionMode(params.cfg) === "safeguard") {
@ -410,7 +403,7 @@ if (resolveCompactionMode(params.cfg) === "safeguard") {
### 上下文裁剪
`src/agents/pi-hooks/context-pruning.ts` 实现了基于缓存 TTL 的上下文裁剪：
`src/agents/pi-hooks/context-pruning.ts` 实现基于缓存 TTL 的上下文裁剪：
```typescript
if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") {
@ -426,7 +419,7 @@ if (cfg?.agents?.defaults?.contextPruning?.mode === "cache-ttl") {
## 流式传输与分块回复
### 分块处理
### 分块切分
`EmbeddedBlockChunker` 负责将流式文本管理为离散的回复块：
@ -436,18 +429,18 @@ const blockChunker = blockChunking ? new EmbeddedBlockChunker(blockChunking) : n
### Thinking/Final 标签剥离
流式输出会被处理，以去除 `<think>`/`<thinking>` 块并提取 `<final>` 内容：
流式输出会经过处理，以剥离 `<think>`/`<thinking>` 块并提取 `<final>` 内容：
```typescript
const stripBlockTags = (text: string, state: { thinking: boolean; final: boolean }) => {
// 去除 <think>...</think> 内容
// 如果 enforceFinalTag，则仅返回 <final>...</final> 内容
// 剥离 <think>...</think> 内容
// 如果 enforceFinalTag 为真，则只返回 <final>...</final> 内容
};
```
### 回复指令
会解析并提取诸如 `[[media:url]]`、`[[voice]]`、`[[reply:id]]` 这样的回复指令：
会解析并提取诸如 `[[media:url]]`、`[[voice]]`、`[[reply:id]]` 之类的回复指令：
```typescript
const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDirectives(chunk);
@ -457,20 +450,20 @@ const { text: cleanedText, mediaUrls, audioAsVoice, replyToId } = consumeReplyDi
### 错误分类
`pi-embedded-helpers.ts` 会对错误进行分类，以便采取适当处理：
`pi-embedded-helpers.ts` 会对错误进行分类，以便进行适当处理：
```typescript
isContextOverflowError(errorText) // 上下文过大
isCompactionFailureError(errorText) // 压缩失败
isAuthAssistantError(lastAssistant) // 认证失败
isRateLimitAssistantError(...) // 触发速率限制
isRateLimitAssistantError(...) // 命中速率限制
isFailoverAssistantError(...) // 应进行故障转移
classifyFailoverReason(errorText) // "auth" | "rate_limit" | "quota" | "timeout" | ...
```
### Thinking 级别回退
### Thinking Level 回退
如果某个 thinking 级别不受支持，则会回退：
如果某个 Thinking Level 不受支持，则会回退：
```typescript
const fallbackThinking = pickFallbackThinkingLevel({
@ -485,7 +478,7 @@ if (fallbackThinking) {
## 沙箱集成
启用沙箱模式时，工具和路径会受到约束：
启用沙箱模式时，工具和路径都会受到约束：
```typescript
const sandbox = await resolveSandboxContext({
@ -505,51 +498,51 @@ if (sandboxRoot) {
### Anthropic
- 拒绝魔术字符串清理
- 拒绝魔法字符串清理
- 连续角色的轮次验证
- 严格的上游 Pi 工具参数验证
### Google/Gemini
- plugin 拥有的工具 schema 清理
- 插件所属的工具 schema 清理
### OpenAI
- 面向 Codex 模型的 `apply_patch` 工具
- thinking 级别降级处理
- Thinking Level 降级处理
## TUI 集成
OpenClaw 还提供本地 TUI 模式，直接使用 pi-tui 组件：
OpenClaw 还提供一种本地 TUI 模式，可直接使用 pi-tui 组件：
```typescript
// src/tui/tui.ts
import { ... } from "@mariozechner/pi-tui";
```
这提供了类似于 pi 原生模式的交互式终端体验。
这提供了与 pi 原生模式类似的交互式终端体验。
## 与 Pi CLI 的主要区别
## 与 Pi CLI 的关键差异
| 方面 | Pi CLI | OpenClaw 内嵌版 |
| ------------ | ----------------------- | ---------------------------------------------------------------------------------------------- |
| 调用方式 | `pi` 命令 / RPC | 通过 `createAgentSession()` 使用 SDK |
| 工具 | 默认编码工具 | 自定义 OpenClaw 工具套件 |
| 系统提示 | AGENTS.md + prompts | 按渠道 / 上下文动态生成 |
| 会话存储 | `~/.pi/agent/sessions/` | `~/.openclaw/agents/<agentId>/sessions/`（或 `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`） |
| 认证 | 单一凭证 | 多配置文件并带轮换 |
| 扩展 | 从磁盘加载 | 以编程方式 + 磁盘路径加载 |
| 事件处理 | TUI 渲染 | 基于回调（`onBlockReply` 等） |
| 方面 | Pi CLI | OpenClaw 内嵌式 |
| --------------- | ----------------------- | ---------------------------------------------------------------------------------------------- |
| 调用方式 | `pi` 命令 / RPC | 通过 `createAgentSession()` 使用 SDK |
| 工具 | 默认编码工具 | 自定义 OpenClaw 工具套件 |
| 系统提示词 | AGENTS.md + prompts | 按渠道/上下文动态生成 |
| 会话存储 | `~/.pi/agent/sessions/` | `~/.openclaw/agents/<agentId>/sessions/`（或 `$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/`） |
| 认证 | 单一凭证 | 支持轮换的多配置 |
| 扩展 | 从磁盘加载 | 通过编程方式 + 磁盘路径 |
| 事件处理 | TUI 渲染 | 基于回调（`onBlockReply` 等） |
## 未来考虑
可能需要重构的领域：
潜在需要重构的领域：
1. **工具签名对齐**：当前在 pi-agent-core 和 pi-coding-agent 签名之间进行适配
2. **Session manager 包装**：`guardSessionManager` 增加了安全性，但也提高了复杂度
1. **工具签名对齐**：当前仍在适配 pi-agent-core 与 pi-coding-agent 之间的签名差异
2. **Session manager 包装**：`guardSessionManager` 增加了安全性，但也提升了复杂度
3. **扩展加载**：可以更直接地使用 pi 的 `ResourceLoader`
4. **流式处理器复杂性**：`subscribeEmbeddedPiSession` 变得越来越大
5. **提供商特殊情况**：存在许多提供商特定代码路径，未来 pi 也许可以自行处理
4. **流式处理器复杂度**：`subscribeEmbeddedPiSession` 已变得较大
5. **提供商特殊处理**：存在许多提供商特定代码路径，而这些逻辑未来可能由 pi 来统一处理
## 测试
@ -567,13 +560,13 @@ Pi 集成覆盖以下测试套件：
- `src/agents/pi-settings.test.ts`
- `src/agents/pi-hooks/**/*.test.ts`
实时 / 按需启用：
实时/按需启用：
- `src/agents/pi-embedded-runner-extraparams.live.test.ts`（启用 `OPENCLAW_LIVE_TEST=1`）
关于当前运行命令，请参见 [Pi Development Workflow](/zh-CN/pi-dev)。
当前运行命令请参见 [Pi 开发工作流](/zh-CN/pi-dev)。
## 相关内容
- [Pi development workflow](/zh-CN/pi-dev)
- [Pi 开发工作流](/zh-CN/pi-dev)
- [安装概览](/zh-CN/install)

50
docs/zh-CN/providers/deepseek.md
View File

@ -1,39 +1,39 @@
---
read_when:
- 你想在 OpenClaw 中使用 DeepSeek
- 你需要 API key 环境变量或 CLI 认证方式选择
- 你需要 API 密钥环境变量或 CLI 认证选项
summary: DeepSeek 设置（认证 + 模型选择）
title: DeepSeek
x-i18n:
generated_at: "2026-04-23T20:59:55Z"
generated_at: "2026-04-24T15:13:10Z"
model: gpt-5.4
provider: openai
source_hash: ead407c67c05bd8700db1cba36defdd9d47bdc9a071c76a07c4b4fb82f6b80e2
source_hash: 5b0d2345c72328e14351d71c5784204dc6ed9dc922f919b6adfac394001c3261
source_path: providers/deepseek.md
workflow: 15
---
[DeepSeek](https://www.deepseek.com) 提供强大的 AI 模型，并带有与 OpenAI 兼容的 API。
[DeepSeek](https://www.deepseek.com) 通过与 OpenAI 兼容的 API 提供强大的 AI 模型。
| 属性 | 值 |
| 属性 | 值 |
| -------- | -------------------------- |
| 提供商 | `deepseek` |
| 认证 | `DEEPSEEK_API_KEY` |
| API | 与 OpenAI 兼容 |
| 提供商 | `deepseek` |
| 认证 | `DEEPSEEK_API_KEY` |
| API | 与 OpenAI 兼容 |
| Base URL | `https://api.deepseek.com` |
## 快速开始
## 入门指南
<Steps>
<Step title="获取你的 API key">
在 [platform.deepseek.com](https://platform.deepseek.com/api_keys) 创建一个 API key。
<Step title="获取你的 API 密钥">
在 [platform.deepseek.com](https://platform.deepseek.com/api_keys) 创建一个 API 密钥。
</Step>
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice deepseek-api-key
```
这会提示你输入 API key，并将 `deepseek/deepseek-chat` 设置为默认模型。
这会提示你输入 API 密钥，并将 `deepseek/deepseek-v4-flash` 设置为默认模型。
</Step>
<Step title="验证模型可用">
@ -60,20 +60,24 @@ x-i18n:
</AccordionGroup>
<Warning>
如果 Gateway 网关以守护进程方式运行（launchd / systemd），请确保 `DEEPSEEK_API_KEY`
对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过
`env.shellEnv` 提供）。
如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `DEEPSEEK_API_KEY`
对该进程可用（例如，在 `~/.openclaw/.env` 中或通过
`env.shellEnv`）。
</Warning>
## 内置目录
| 模型引用 | 名称 | 输入 | 上下文 | 最大输出 | 说明 |
| ---------------------------- | ----------------- | ----- | ------- | ---------- | ------------------------------------------------- |
| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | 默认模型；DeepSeek V3.2 非思考界面 |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | 启用推理的 V3.2 界面 |
| 模型引用 | 名称 | 输入 | 上下文 | 最大输出 | 说明 |
| ---------------------------- | ----------------- | ----- | ------------- | ---------- | ------------------------------------------ |
| `deepseek/deepseek-v4-flash` | DeepSeek V4 Flash | text | 1,000,000 | 384,000 | 默认模型；支持 V4 thinking 的能力表面 |
| `deepseek/deepseek-v4-pro` | DeepSeek V4 Pro | text | 1,000,000 | 384,000 | 支持 V4 thinking 的能力表面 |
| `deepseek/deepseek-chat` | DeepSeek Chat | text | 131,072 | 8,192 | DeepSeek V3.2 非 thinking 能力表面 |
| `deepseek/deepseek-reasoner` | DeepSeek Reasoner | text | 131,072 | 65,536 | 启用推理的 V3.2 能力表面 |
<Tip>
目前源码中，这两个内置模型都声明支持流式传输用量兼容性。
V4 模型支持 DeepSeek 的 `thinking` 控制。OpenClaw 还会在后续轮次中重放
DeepSeek 的 `reasoning_content`，因此带有工具调用的 thinking 会话
可以继续进行。
</Tip>
## 配置示例
@ -83,7 +87,7 @@ x-i18n:
env: { DEEPSEEK_API_KEY: "sk-..." },
agents: {
defaults: {
model: { primary: "deepseek/deepseek-chat" },
model: { primary: "deepseek/deepseek-v4-flash" },
},
},
}
@ -93,9 +97,9 @@ x-i18n:
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="配置参考" href="/zh-CN/gateway/configuration-reference" icon="gear">
智能体、模型和提供商的完整配置参考。
agents、模型和提供商的完整配置参考。
</Card>
</CardGroup>