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-05-02 02:51:54 +00:00
parent f399315b5d
commit ab5f74dd26
9 changed files with 1129 additions and 1055 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

706
docs/zh-CN/plugins/manifest.md
View File

File diff suppressed because it is too large Load Diff

274
docs/zh-CN/plugins/sdk-overview.md
View File

@ -1,24 +1,24 @@
---
read_when:
- 你需要知道要从哪个 SDK 子路径导入
- 你需要 OpenClawPluginApi 上所有注册方法的参考。
- 你正在查找特定的 SDK 导出
- 你需要 OpenClawPluginApi 上所有注册方法的参考
- 你正在查找某个特定的 SDK 导出项
sidebarTitle: Plugin SDK overview
summary: 导入映射、注册 API 参考和 SDK 架构
title: 插件 SDK 概览
x-i18n:
generated_at: "2026-05-01T20:39:35Z"
generated_at: "2026-05-02T02:49:08Z"
model: gpt-5.5
provider: openai
source_hash: 28da709ac7dc86e6d5b553b6c8ecaed105c68de63f94804bc5aed56ebc6c5de9
source_hash: be5fa531e603fb6d87f84e3193ebd61be1431b57b8f284871ae15f34ca93fc69
source_path: plugins/sdk-overview.md
workflow: 16
---
插件 SDK 是插件与核心之间的类型化契约。本页是关于**要导入什么**和**可以注册什么**的参考。
插件 SDK 是插件与核心之间的类型化契约。本页是关于**导入内容**和**可注册内容**的参考。
<Note>
本页适用于在 OpenClaw 内部使用 `openclaw/plugin-sdk/*` 的插件作者。对于想要通过 Gateway 网关运行智能体的外部应用、脚本、仪表板、CI 作业和 IDE 扩展，请改用 [OpenClaw 应用 SDK](/zh-CN/concepts/openclaw-sdk) 和 `@openclaw/sdk` 包。
本页面面向在 OpenClaw 内部使用 `openclaw/plugin-sdk/*` 的插件作者。对于想要通过 Gateway 网关运行智能体的外部应用、脚本、仪表盘、CI 作业和 IDE 扩展，请改用 [OpenClaw 应用 SDK](/zh-CN/concepts/openclaw-sdk) 和 `@openclaw/sdk` 包。
</Note>
<Tip>
@ -34,116 +34,116 @@ import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
```
每个子路径都是一个小型、自包含的模块。这能让启动保持快速，并防止循环依赖问题。对于特定渠道的入口/构建辅助工具，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更宽泛的伞状接口以及共享辅助工具，例如 `buildChannelConfigSchema`。
每个子路径都是一个小型、自包含模块。这可以保持启动快速，并防止循环依赖问题。对于渠道专用的入口/构建辅助函数，优先使用 `openclaw/plugin-sdk/channel-core`；将 `openclaw/plugin-sdk/core` 保留给更广泛的总括表面和共享辅助函数，例如 `buildChannelConfigSchema`。
对于渠道配置，通过 `openclaw.plugin.json#channelConfigs` 发布渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享 schema 原语和通用构建器。OpenClaw 的内置插件使用 `plugin-sdk/bundled-channel-config-schema` 来保留内置渠道 schema。已弃用的兼容导出仍保留在 `plugin-sdk/channel-config-schema-legacy`；这两个内置 schema 子路径都不是新插件的模式。
对于渠道配置，请通过 `openclaw.plugin.json#channelConfigs` 发布渠道拥有的 JSON Schema。`plugin-sdk/channel-config-schema` 子路径用于共享 schema 原语和通用构建器。OpenClaw 的内置插件使用 `plugin-sdk/bundled-channel-config-schema` 来保留内置渠道 schema。已弃用的兼容性导出仍保留在 `plugin-sdk/channel-config-schema-legacy`；这两个内置 schema 子路径都不是新插件应采用的模式。
<Warning>
不要导入带有提供商或渠道品牌的便利接口（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。内置插件会在自己的 `api.ts` / `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心消费者应使用这些插件本地 barrel，或在确实存在跨渠道需求时添加一个狭窄的通用 SDK 契约。
不要导入带有提供商或渠道品牌的便利连接点（例如 `openclaw/plugin-sdk/slack`、`.../discord`、`.../signal`、`.../whatsapp`）。内置插件会在自己的 `api.ts` / `runtime-api.ts` barrel 中组合通用 SDK 子路径；核心消费者应使用这些插件本地 barrel，或者在需求确实跨渠道时添加狭窄的通用 SDK 契约。
当一小部分内置插件辅助接口有已跟踪的所有者使用时，它们仍会出现在生成的导出映射中。它们只用于内置插件维护，不建议作为新的第三方插件导入路径。
当一小部分内置插件辅助连接点有被跟踪的所有者使用时，它们仍会出现在生成的导出映射中。它们仅用于内置插件维护，不建议作为新的第三方插件导入路径。
`openclaw/plugin-sdk/discord` 和 `openclaw/plugin-sdk/telegram-account` 也作为已弃用的兼容外观保留，用于已跟踪的所有者使用。不要把这些导入路径复制到新插件中；请改用注入的运行时辅助工具和通用渠道 SDK 子路径。
`openclaw/plugin-sdk/discord` 和 `openclaw/plugin-sdk/telegram-account` 也作为已弃用的兼容性外观保留，用于被跟踪的所有者使用。不要将这些导入路径复制到新插件中；请改用注入的运行时辅助函数和通用渠道 SDK 子路径。
</Warning>
## 子路径参考
插件 SDK 以一组按领域分组的狭窄子路径公开（插件入口、渠道、提供商、认证、运行时、能力、记忆，以及预留的内置插件辅助工具）。完整目录按组归类并带有链接，请参见[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。
插件 SDK 以一组按领域分组的狭窄子路径公开（插件入口、渠道、提供商、凭证、运行时、能力、记忆和保留的内置插件辅助函数）。完整目录（已分组并带链接）请参见[插件 SDK 子路径](/zh-CN/plugins/sdk-subpaths)。
生成的 200+ 子路径列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
生成的 200+ 个子路径列表位于 `scripts/lib/plugin-sdk-entrypoints.json`。
## 注册 API
`register(api)` 回调会收到一个 `OpenClawPluginApi` 对象，其中包含这些方法：
`register(api)` 回调会接收一个包含以下方法的 `OpenClawPluginApi` 对象：
### 能力注册
| 方法 | 注册的内容 |
| ------------------------------------------------ | --------------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerAgentHarness(...)` | 实验性低层级智能体执行器 |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | Web 获取 / 抓取提供商 |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
| 方法 | 注册内容 |
| ------------------------------------------------ | ------------------------------------- |
| `api.registerProvider(...)` | 文本推理（LLM） |
| `api.registerAgentHarness(...)` | 实验性低层级智能体执行器 |
| `api.registerCliBackend(...)` | 本地 CLI 推理后端 |
| `api.registerChannel(...)` | 消息渠道 |
| `api.registerSpeechProvider(...)` | 文本转语音 / STT 合成 |
| `api.registerRealtimeTranscriptionProvider(...)` | 流式实时转录 |
| `api.registerRealtimeVoiceProvider(...)` | 双工实时语音会话 |
| `api.registerMediaUnderstandingProvider(...)` | 图像/音频/视频分析 |
| `api.registerImageGenerationProvider(...)` | 图像生成 |
| `api.registerMusicGenerationProvider(...)` | 音乐生成 |
| `api.registerVideoGenerationProvider(...)` | 视频生成 |
| `api.registerWebFetchProvider(...)` | 网页获取 / 抓取提供商 |
| `api.registerWebSearchProvider(...)` | Web 搜索 |
### 工具和命令
| 方法 | 注册的内容 |
| ------------------------------- | ------------------------------------------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
| 方法 | 注册内容 |
| ------------------------------- | --------------------------------------------- |
| `api.registerTool(tool, opts?)` | 智能体工具（必需或 `{ optional: true }`） |
| `api.registerCommand(def)` | 自定义命令（绕过 LLM） |
当智能体需要一条简短、由命令拥有的路由提示时，插件命令可以设置 `agentPromptGuidance`。该文本应只描述命令本身；不要向核心提示构建器添加提供商或插件特定策略。
当智能体需要一段简短、由命令拥有的路由提示时，插件命令可以设置 `agentPromptGuidance`。该文本应围绕命令本身；不要把提供商或插件专用策略添加到核心提示构建器中。
### 基础设施
| 方法 | 注册的内容 |
| ---------------------------------------------- | ----------------------------------- |
| `api.registerHook(events, handler, opts?)` | 事件钩子 |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关发现广播器 |
| 方法 | 注册内容 |
| ---------------------------------------------- | --------------------------------------- |
| `api.registerHook(events, handler, opts?)` | 事件钩子 |
| `api.registerHttpRoute(params)` | Gateway 网关 HTTP 端点 |
| `api.registerGatewayMethod(name, handler)` | Gateway 网关 RPC 方法 |
| `api.registerGatewayDiscoveryService(service)` | 本地 Gateway 网关设备发现广播器 |
| `api.registerCli(registrar, opts?)` | CLI 子命令 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
| `api.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 |
| `api.registerMemoryPromptSupplement(builder)` | 追加式、与记忆相邻的提示部分 |
| `api.registerMemoryCorpusSupplement(adapter)` | 追加式记忆搜索/读取语料 |
| `api.registerService(service)` | 后台服务 |
| `api.registerInteractiveHandler(registration)` | 交互式处理器 |
| `api.registerAgentToolResultMiddleware(...)` | 运行时工具结果中间件 |
| `api.registerMemoryPromptSupplement(builder)` | 附加的记忆相邻提示部分 |
| `api.registerMemoryCorpusSupplement(adapter)` | 附加的记忆搜索/读取语料库 |
### 工作流插件的主机钩子
主机钩子是 SDK 接口，适用于需要参与主机生命周期，而不是只添加提供商、渠道或工具的插件。它们是通用契约；Plan Mode 可以使用它们，审批工作流、工作区策略门禁、后台监控、设置向导和 UI 配套插件也可以使用它们。
主机钩子是 SDK 连接点，供需要参与主机生命周期而不只是添加提供商、渠道或工具的插件使用。它们是通用契约；计划模式可以使用它们，审批工作流、工作区策略门控、后台监视器、设置向导和 UI 配套插件也可以使用。
| 方法 | 拥有的契约 |
| ------------------------------------------------------------------------ | ------------------------------------------------------------------------------- |
| `api.registerSessionExtension(...)` | 插件拥有、JSON 兼容的会话状态，通过 Gateway 网关会话投射 |
| `api.enqueueNextTurnInjection(...)` | 持久的恰好一次上下文，注入到某个会话的下一个智能体轮次 |
| `api.registerTrustedToolPolicy(...)` | 内置/可信的前置插件工具策略，可阻止或重写工具参数 |
| `api.registerToolMetadata(...)` | 工具目录显示元数据，不改变工具实现 |
| `api.registerCommand(...)` | 作用域限定的插件命令；命令结果可以设置 `continueAgent: true` |
| `api.registerControlUiDescriptor(...)` | 面向会话、工具、运行或设置界面的 Control UI 贡献描述符 |
| `api.registerRuntimeLifecycle(...)` | 重置/删除/重新加载路径上插件拥有的运行时资源的清理回调 |
| `api.registerAgentEventSubscription(...)` | 面向工作流状态和监控器的已净化事件订阅 |
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次运行的插件临时状态，在终止性运行生命周期时清除 |
| `api.registerSessionSchedulerJob(...)` | 插件拥有的会话调度器作业记录，带确定性清理 |
| 方法 | 拥有的契约 |
| ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerSessionExtension(...)` | 插件拥有、JSON 兼容的会话状态，通过 Gateway 网关会话投射 |
| `api.enqueueNextTurnInjection(...)` | 针对一个会话注入到下一次智能体回合的持久、恰好一次上下文 |
| `api.registerTrustedToolPolicy(...)` | 内置/受信任的前置插件工具策略，可阻止或重写工具参数 |
| `api.registerToolMetadata(...)` | 工具目录显示元数据，不改变工具实现 |
| `api.registerCommand(...)` | 有作用域的插件命令；命令结果可以设置 `continueAgent: true`；Discord 原生命令支持 `descriptionLocalizations` |
| `api.registerControlUiDescriptor(...)` | 用于会话、工具、运行或设置界面的控制 UI 贡献描述符 |
| `api.registerRuntimeLifecycle(...)` | 在重置/删除/重载路径上清理插件拥有的运行时资源的回调 |
| `api.registerAgentEventSubscription(...)` | 用于工作流状态和监视器的已清理事件订阅 |
| `api.setRunContext(...)` / `getRunContext(...)` / `clearRunContext(...)` | 每次运行的插件暂存状态，在终止运行生命周期时清除 |
| `api.registerSessionSchedulerJob(...)` | 插件拥有的会话调度器作业记录，具备确定性清理 |
这些契约有意拆分权限：
- 外部插件可以拥有会话扩展、UI 描述符、命令、工具元数据、下一轮注入和普通钩子。
- 可信工具策略在普通 `before_tool_call` 钩子之前运行，并且仅限内置插件，因为它们参与主机安全策略。
- 预留命令所有权仅限内置插件。外部插件应使用自己的命令名称或别名。
- `allowPromptInjection=false` 会禁用会改变提示的钩子，包括 `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、旧版 `before_agent_start` 中的提示字段，以及 `enqueueNextTurnInjection`。
- 外部插件可以拥有会话扩展、UI 描述符、命令、工具元数据、下一回合注入和普通钩子。
- 受信任工具策略在普通 `before_tool_call` 钩子之前运行，并且仅限内置插件，因为它们参与主机安全策略。
- 保留命令所有权仅限内置插件。外部插件应使用自己的命令名称或别名。
- `allowPromptInjection=false` 会禁用会修改提示的钩子，包括 `agent_turn_prepare`、`before_prompt_build`、`heartbeat_prompt_contribution`、旧版 `before_agent_start` 的提示字段以及 `enqueueNextTurnInjection`。
非 Plan 使用方示例：
非计划模式消费者示例：
| 插件原型 | 使用的钩子 |
| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| 审批工作流 | 会话扩展、命令继续、下一轮注入、UI 描述符 |
| 预算/工作区策略门禁 | 可信工具策略、工具元数据、会话投射 |
| 后台生命周期监控器 | 运行时生命周期清理、智能体事件订阅、会话调度器所有权/清理、Heartbeat 提示贡献、UI 描述符 |
| 设置或新手引导向导 | 会话扩展、作用域限定命令、Control UI 描述符 |
| 插件原型 | 使用的钩子 |
| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| 审批工作流 | 会话扩展、命令延续、下一回合注入、UI 描述符 |
| 预算/工作区策略门控 | 受信任工具策略、工具元数据、会话投射 |
| 后台生命周期监视器 | 运行时生命周期清理、智能体事件订阅、会话调度器所有权/清理、Heartbeat 提示贡献、UI 描述符 |
| 设置或新手引导向导 | 会话扩展、有作用域命令、控制 UI 描述符 |
<Note>
预留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的网关方法作用域也是如此。插件拥有的方法优先使用插件特定前缀。
保留的核心管理员命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）始终保持为 `operator.admin`，即使插件尝试分配更窄的 Gateway 网关方法作用域也是如此。插件拥有的方法请优先使用插件专用前缀。
</Note>
<Accordion title="何时使用工具结果中间件">
当内置插件需要在工具执行之后、运行时将结果反馈给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是面向 tokenjuice 等异步输出规约器的可信、运行时中立接口。
当内置插件需要在执行后、运行时将工具结果反馈给模型之前重写工具结果时，可以使用 `api.registerAgentToolResultMiddleware(...)`。这是用于 tokenjuice 等异步输出归约器的受信任、运行时中立连接点。
内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件不能注册此中间件；对于不需要模型前工具结果时机的工作，请继续使用普通 OpenClaw 插件钩子。旧的仅限 Pi 的嵌入式扩展工厂注册路径已被移除。
内置插件必须为每个目标运行时声明 `contracts.agentToolResultMiddleware`，例如 `["pi", "codex"]`。外部插件不能注册此中间件；对于不需要模型前工具结果时序的工作，请继续使用普通 OpenClaw 插件钩子。旧的仅 Pi 嵌入式扩展工厂注册路径已被移除。
</Accordion>
### Gateway 网关发现注册
### Gateway 网关设备发现注册
`api.registerGatewayDiscoveryService(...)` 允许插件在 mDNS/Bonjour 等本地发现传输协议上广播活动的 Gateway 网关。当启用本地发现时，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非机密 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理器。
`api.registerGatewayDiscoveryService(...)` 允许插件通过 mDNS/Bonjour 等本地设备发现传输协议通告活动的 Gateway 网关。启用本地设备发现后，OpenClaw 会在 Gateway 网关启动期间调用该服务，传入当前 Gateway 网关端口和非机密 TXT 提示数据，并在 Gateway 网关关闭期间调用返回的 `stop` 处理程序。
```typescript
api.registerGatewayDiscoveryService({
@ -159,19 +159,16 @@ api.registerGatewayDiscoveryService({
});
```
Gateway 网关设备发现插件不得将播发的 TXT 值视为秘密或
认证。设备发现只是路由提示；Gateway 网关认证和 TLS 固定仍然
负责信任。
Gateway 网关设备发现插件不得将通告的 TXT 值视为机密或身份验证。设备发现是路由提示；Gateway 网关身份验证和 TLS 固定仍然负责信任。
### CLI 注册元数据
`api.registerCli(registrar, opts?)` 接受两类顶层元数据：
- `commands`：注册器拥有的显式命令根
- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析期命令描述符
- `descriptors`：用于根 CLI 帮助、路由和延迟插件 CLI 注册的解析时命令描述符
如果你希望插件命令在常规根 CLI 路径中保持延迟加载，
请提供覆盖该注册器暴露的每个顶层命令根的 `descriptors`。
如果你希望插件命令在正常根 CLI 路径中保持延迟加载，请提供覆盖该注册器暴露的每个顶层命令根的 `descriptors`。
```typescript
api.registerCli(
@ -191,29 +188,26 @@ api.registerCli(
);
```
仅在不需要延迟根 CLI 注册时，才单独使用 `commands`。
这个急切兼容路径仍受支持，但它不会安装由描述符支持的占位符，
用于解析期延迟加载。
只有在不需要延迟根 CLI 注册时，才单独使用 `commands`。该立即加载的兼容路径仍受支持，但它不会为解析时延迟加载安装由描述符支持的占位符。
### CLI 后端注册
`api.registerCliBackend(...)` 让插件拥有本地
AI CLI 后端（例如 `codex-cli`）的默认配置。
`api.registerCliBackend(...)` 允许插件拥有本地 AI CLI 后端（如 `codex-cli`）的默认配置。
- 后端 `id` 会成为模型引用中的提供商前缀，例如 `codex-cli/gpt-5`。
- 后端 `config` 使用与 `agents.defaults.cliBackends.<id>` 相同的形状。
- 用户配置仍然优先。OpenClaw 会在运行 CLI 之前，将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上。
- 当后端需要在合并后进行兼容性重写时，使用 `normalizeConfig`（例如规范化旧的标志形状）。
- 用户配置仍然优先。OpenClaw 会先将 `agents.defaults.cliBackends.<id>` 合并到插件默认值之上，然后再运行 CLI。
- 当后端需要在合并后执行兼容性重写时，请使用 `normalizeConfig`（例如规范化旧标志形状）。
### 独占槽位
| 方法 | 注册内容 |
| ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只能有一个处于活动状态）。`assemble()` 回调会收到 `availableTools` 和 `citationsMode`，因此引擎可以定制提示补充内容。 |
| `api.registerMemoryCapability(capability)` | 统一记忆能力 |
| `api.registerMemoryPromptSection(builder)` | 记忆提示段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | 记忆刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | 记忆运行时适配器 |
| 方法 | 注册内容 |
| ------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `api.registerContextEngine(id, factory)` | 上下文引擎（一次只激活一个）。`assemble()` 回调会接收 `availableTools` 和 `citationsMode`，以便引擎定制提示词追加内容。 |
| `api.registerMemoryCapability(capability)` | 统一记忆能力 |
| `api.registerMemoryPromptSection(builder)` | 记忆提示词区段构建器 |
| `api.registerMemoryFlushPlan(resolver)` | 记忆刷新计划解析器 |
| `api.registerMemoryRuntime(runtime)` | 记忆运行时适配器 |
### 记忆嵌入适配器
@ -222,41 +216,34 @@ AI CLI 后端（例如 `codex-cli`）的默认配置。
| `api.registerMemoryEmbeddingProvider(adapter)` | 活动插件的记忆嵌入适配器 |
- `registerMemoryCapability` 是首选的独占记忆插件 API。
- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，
以便配套插件通过 `openclaw/plugin-sdk/memory-host-core` 消费导出的记忆制品，
而不是访问某个特定记忆插件的私有布局。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和
`registerMemoryRuntime` 是兼容旧版的独占记忆插件 API。
- `MemoryFlushPlan.model` 可以将刷新轮次固定到精确的 `provider/model`
引用，例如 `ollama/qwen3:8b`，而不会继承活动的回退链。
- `registerMemoryEmbeddingProvider` 让活动记忆插件注册一个或多个
嵌入适配器 ID（例如 `openai`、`gemini`，或插件定义的自定义 ID）。
- 用户配置（例如 `agents.defaults.memorySearch.provider` 和
`agents.defaults.memorySearch.fallback`）会根据这些已注册的
适配器 ID 解析。
- `registerMemoryCapability` 也可以暴露 `publicArtifacts.listArtifacts(...)`，让配套插件通过 `openclaw/plugin-sdk/memory-host-core` 使用导出的记忆制品，而不是访问某个特定记忆插件的私有布局。
- `registerMemoryPromptSection`、`registerMemoryFlushPlan` 和 `registerMemoryRuntime` 是兼容旧版的独占记忆插件 API。
- `MemoryFlushPlan.model` 可以将刷新轮次固定到精确的 `provider/model` 引用，例如 `ollama/qwen3:8b`，而不继承活动备用链。
- `registerMemoryEmbeddingProvider` 允许活动记忆插件注册一个或多个嵌入适配器 ID（例如 `openai`、`gemini`，或自定义的插件定义 ID）。
- 用户配置（如 `agents.defaults.memorySearch.provider` 和 `agents.defaults.memorySearch.fallback`）会针对这些已注册的适配器 ID 解析。
### 事件和生命周期
| 方法 | 作用 |
| -------------------------------------------- | ---------------- |
| `api.on(hookName, handler, opts?)` | 类型化生命周期钩子 |
| `api.onConversationBindingResolved(handler)` | 对话绑定回调 |
| `api.onConversationBindingResolved(handler)` | 会话绑定回调 |
有关示例、常见钩子名称和保护语义，请参阅 [插件钩子](/zh-CN/plugins/hooks)。
示例、常见钩子名称和守卫语义请参见 [插件钩子](/zh-CN/plugins/hooks)。
### 钩子决策语义
- `before_tool_call`：返回 `{ block: true }` 是终止性的。一旦任何处理器设置它，就会跳过较低优先级的处理器。
- `before_tool_call`：返回 `{ block: true }` 是终止性决策。一旦任何处理程序设置它，较低优先级的处理程序会被跳过。
- `before_tool_call`：返回 `{ block: false }` 会被视为没有决策（与省略 `block` 相同），而不是覆盖。
- `before_install`：返回 `{ block: true }` 是终止性的。一旦任何处理器设置它，就会跳过较低优先级的处理器。
- `before_install`：返回 `{ block: true }` 是终止性决策。一旦任何处理程序设置它，较低优先级的处理程序会被跳过。
- `before_install`：返回 `{ block: false }` 会被视为没有决策（与省略 `block` 相同），而不是覆盖。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性的。一旦任何处理器声明已调度，就会跳过较低优先级的处理器以及默认模型调度路径。
- `message_sending`：返回 `{ cancel: true }` 是终止性的。一旦任何处理器设置它，就会跳过较低优先级的处理器。
- `reply_dispatch`：返回 `{ handled: true, ... }` 是终止性决策。一旦任何处理程序声明已处理分发，较低优先级的处理程序和默认模型分发路径都会被跳过。
- `message_sending`：返回 `{ cancel: true }` 是终止性决策。一旦任何处理程序设置它，较低优先级的处理程序会被跳过。
- `message_sending`：返回 `{ cancel: false }` 会被视为没有决策（与省略 `cancel` 相同），而不是覆盖。
- `message_received`：当你需要入站线程/主题路由时，请使用类型化的 `threadId` 字段。将 `metadata` 保留给渠道特定的额外信息。
- `message_sending`：先使用类型化的 `replyToId` / `threadId` 路由字段，再回退到渠道特定的 `metadata`。
- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 获取 Gateway 网关拥有的启动状态，而不是依赖内部 `gateway:startup` 钩子。
- `cron_changed`：观察 Gateway 网关拥有的 cron 生命周期变化。同步外部唤醒调度器时，使用 `event.job?.state?.nextRunAtMs` 和 `ctx.getCron?.()`，并让 OpenClaw 作为到期检查和执行的事实来源。
- `gateway_start`：使用 `ctx.config`、`ctx.workspaceDir` 和 `ctx.getCron?.()` 表示 Gateway 网关拥有的启动状态，而不是依赖内部 `gateway:startup` 钩子。
- `cron_changed`：观察 Gateway 网关拥有的 cron 生命周期变更。同步外部唤醒调度器时使用 `event.job?.state?.nextRunAtMs` 和 `ctx.getCron?.()`，并让 OpenClaw 作为到期检查和执行的事实来源。
### API 对象字段
@ -269,15 +256,15 @@ AI CLI 后端（例如 `codex-cli`）的默认配置。
| `api.source` | `string` | 插件源路径 |
| `api.rootDir` | `string?` | 插件根目录（可选） |
| `api.config` | `OpenClawConfig` | 当前配置快照（可用时为活动的内存中运行时快照） |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件特定配置 |
| `api.runtime` | `PluginRuntime` | [运行时助手](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域日志器（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口前启动/设置窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根目录的路径 |
| `api.pluginConfig` | `Record<string, unknown>` | 来自 `plugins.entries.<id>.config` 的插件特定配置 |
| `api.runtime` | `PluginRuntime` | [运行时辅助工具](/zh-CN/plugins/sdk-runtime) |
| `api.logger` | `PluginLogger` | 作用域日志记录器（`debug`、`info`、`warn`、`error`） |
| `api.registrationMode` | `PluginRegistrationMode` | 当前加载模式；`"setup-runtime"` 是轻量级的完整入口前启动/设置窗口 |
| `api.resolvePath(input)` | `(string) => string` | 解析相对于插件根的路径 |
## 内部模块约定
在你的插件中，使用本地桶文件进行内部导入：
在你的插件内，使用本地桶文件进行内部导入：
```
my-plugin/
@ -290,50 +277,43 @@ my-plugin/
<Warning>
切勿在生产代码中通过 `openclaw/plugin-sdk/<your-plugin>`
导入你自己的插件。请通过 `./api.ts` 或
`./runtime-api.ts` 路由内部导入。SDK 路径仅是外部契约。
`./runtime-api.ts` 路由内部导入。SDK 路径仅用于外部契约。
</Warning>
由门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、
`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）会在 OpenClaw 已经运行时优先使用
活动运行时配置快照。如果运行时快照尚不存在，它们会回退到磁盘上解析出的配置文件。
打包后的内置插件门面应通过 OpenClaw 的插件门面加载器加载；直接从 `dist/extensions/...`
导入会绕过清单和运行时 sidecar 检查，而这些检查是打包安装为插件拥有代码使用的。
由门面加载的内置插件公共表面（`api.ts`、`runtime-api.ts`、`index.ts`、`setup-entry.ts` 以及类似的公共入口文件）在 OpenClaw 已运行时优先使用活动运行时配置快照。如果尚不存在运行时快照，它们会回退到磁盘上已解析的配置文件。打包的内置插件门面应通过 OpenClaw 的插件门面加载器加载；直接从 `dist/extensions/...` 导入会绕过打包安装用于插件拥有代码的清单和运行时 sidecar 检查。
当某个助手有意是提供商特定的，并且尚不属于通用 SDK
子路径时，提供商插件可以暴露一个很窄的插件本地契约桶文件。内置示例：
当某个辅助工具有意特定于提供商，并且尚不属于通用 SDK 子路径时，提供商插件可以暴露一个狭窄的插件本地契约桶文件。内置示例：
- **Anthropic**：用于 Claude beta-header 和 `service_tier` 流助手的公共 `api.ts` / `contract-api.ts` 接缝。
- **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、
默认模型助手和实时提供商构建器。
- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器
以及新手引导/配置助手。
- **Anthropic**：用于 Claude beta-header 和 `service_tier` 流辅助工具的公共 `api.ts` / `contract-api.ts` 接缝。
- **`@openclaw/openai-provider`**：`api.ts` 导出提供商构建器、默认模型辅助工具和实时提供商构建器。
- **`@openclaw/openrouter-provider`**：`api.ts` 导出提供商构建器以及新手引导/配置辅助工具。
<Warning>
插件生产代码也应避免 `openclaw/plugin-sdk/<other-plugin>`
导入。如果某个助手确实是共享的，请将它提升到中立的 SDK 子路径，
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或另一个
面向能力的表面，而不是把两个插件耦合在一起。
插件生产代码也应避免导入 `openclaw/plugin-sdk/<other-plugin>`。
如果某个辅助工具确实是共享的，请将它提升到中立的 SDK 子路径，
例如 `openclaw/plugin-sdk/speech`、`.../provider-model-shared`，或其他
面向能力的表面，而不是将两个插件耦合在一起。
</Warning>
## 相关内容
## 相关
<CardGroup cols={2}>
<Card title="Entry points" icon="door-open" href="/zh-CN/plugins/sdk-entrypoints">
<Card title="入口点" icon="door-open" href="/zh-CN/plugins/sdk-entrypoints">
`definePluginEntry` 和 `defineChannelPluginEntry` 选项。
</Card>
<Card title="Runtime helpers" icon="gears" href="/zh-CN/plugins/sdk-runtime">
<Card title="运行时助手" icon="gears" href="/zh-CN/plugins/sdk-runtime">
完整的 `api.runtime` 命名空间参考。
</Card>
<Card title="Setup and config" icon="sliders" href="/zh-CN/plugins/sdk-setup">
打包、清单和配置 schema。
<Card title="设置和配置" icon="sliders" href="/zh-CN/plugins/sdk-setup">
打包、清单和配置架构。
</Card>
<Card title="Testing" icon="vial" href="/zh-CN/plugins/sdk-testing">
<Card title="测试" icon="vial" href="/zh-CN/plugins/sdk-testing">
测试工具和 lint 规则。
</Card>
<Card title="SDK migration" icon="arrows-turn-right" href="/zh-CN/plugins/sdk-migration">
从已弃用表面迁移。
<Card title="SDK 迁移" icon="arrows-turn-right" href="/zh-CN/plugins/sdk-migration">
从已弃用的表面迁移。
</Card>
<Card title="Plugin internals" icon="diagram-project" href="/zh-CN/plugins/architecture">
深入架构和能力模型。
<Card title="插件内部机制" icon="diagram-project" href="/zh-CN/plugins/architecture">
深层架构和能力模型。
</Card>
</CardGroup>

178
docs/zh-CN/plugins/sdk-setup.md
View File

@ -2,31 +2,31 @@
read_when:
- 你正在为插件添加设置向导
- 你需要理解 setup-entry.ts 与 index.ts 的区别
- 你正在定义插件配置 schema 或 package.json 的 openclaw 元数据
- 你正在定义插件配置架构或 package.json openclaw 元数据
sidebarTitle: Setup and config
summary: 设置向导、setup-entry.ts、配置模式和 package.json 元数据
summary: 设置向导、setup-entry.ts、配置 schema 和 package.json 元数据
title: 插件设置和配置
x-i18n:
generated_at: "2026-05-01T20:40:09Z"
generated_at: "2026-05-02T02:49:10Z"
model: gpt-5.5
provider: openai
source_hash: d61cbbeb3e9e303d098fcddf4ba101ff6717c232d5db4b36c28008c84bd32be8
source_hash: 322cf8988da686d5bf7577f9825f6f8decb738f91563e4022c14bf16dca22824
source_path: plugins/sdk-setup.md
workflow: 16
---
Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.plugin.json`)、设置入口和配置架构的参考。
插件打包（`package.json` 元数据）、清单（`openclaw.plugin.json`）、设置入口和配置架构的参考。
<Tip>
**想找演练？** 操作指南会在上下文中介绍打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。
**想要演练教程？** 操作指南在上下文中介绍了打包：[渠道插件](/zh-CN/plugins/sdk-channel-plugins#step-1-package-and-manifest) 和 [提供商插件](/zh-CN/plugins/sdk-provider-plugins#step-1-package-and-manifest)。
</Tip>
## 包元数据
你的 `package.json` 需要一个 `openclaw` 字段，用来告诉插件系统你的插件提供什么：
你的 `package.json` 需要一个 `openclaw` 字段，用于告诉插件系统你的插件提供什么：
<Tabs>
<Tab title="Channel plugin">
<Tab title="渠道插件">
```json
{
"name": "@myorg/openclaw-my-channel",
@ -44,7 +44,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
}
```
</Tab>
<Tab title="Provider plugin / ClawHub baseline">
<Tab title="提供商插件 / ClawHub 基线">
```json openclaw-clawhub-package.json
{
"name": "@myorg/openclaw-my-plugin",
@ -67,7 +67,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
</Tabs>
<Note>
如果你在 ClawHub 上外部发布该插件，这些 `compat` 和 `build` 字段是必需的。规范发布片段位于 `docs/snippets/plugin-publish/`。
如果你在 ClawHub 上对外发布插件，则这些 `compat` 和 `build` 字段是必需的。规范发布片段位于 `docs/snippets/plugin-publish/`。
</Note>
### `openclaw` 字段
@ -76,10 +76,10 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
入口点文件（相对于包根目录）。
</ParamField>
<ParamField path="setupEntry" type="string">
轻量级的仅设置入口（可选）。
轻量级、仅用于设置的入口（可选）。
</ParamField>
<ParamField path="channel" type="object">
用于设置、选择器、快速开始和 Status 界面的渠道目录元数据。
用于设置、选择器、快速开始和状态界面的渠道目录元数据。
</ParamField>
<ParamField path="providers" type="string[]">
此插件注册的提供商 ID。
@ -93,28 +93,28 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
### `openclaw.channel`
`openclaw.channel` 是用于在运行时加载前支持渠道发现和设置界面的低成本包元数据。
`openclaw.channel` 是用于在运行时加载前进行渠道设备发现和设置界面的轻量级包元数据。
| 字段 | 类型 | 含义 |
| -------------------------------------- | ---------- | ----------------------------------------------------------------------------- |
| `id` | `string` | 规范渠道 ID。 |
| `label` | `string` | 主要渠道标签。 |
| `selectionLabel` | `string` | 当需要不同于 `label` 时使用的选择器/设置标签。 |
| `detailLabel` | `string` | 用于更丰富的渠道目录和 Status 界面的次级详情标签。 |
| `detailLabel` | `string` | 用于更丰富渠道目录和状态界面的次要详情标签。 |
| `docsPath` | `string` | 用于设置和选择链接的文档路径。 |
| `docsLabel` | `string` | 当需要不同于渠道 ID 时，用于文档链接的覆盖标签。 |
| `docsLabel` | `string` | 当文档链接标签需要不同于渠道 ID 时使用的覆盖标签。 |
| `blurb` | `string` | 简短的新手引导/目录描述。 |
| `order` | `number` | 渠道目录中的排序顺序。 |
| `aliases` | `string[]` | 用于渠道选择的额外查找别名。 |
| `preferOver` | `string[]` | 此渠道应优先于的低优先级插件/渠道 ID。 |
| `systemImage` | `string` | 渠道 UI 目录的可选图标/系统图片名称。 |
| `preferOver` | `string[]` | 此渠道应优先于的较低优先级插件/渠道 ID。 |
| `systemImage` | `string` | 用于渠道 UI 目录的可选图标/系统图像名称。 |
| `selectionDocsPrefix` | `string` | 选择界面中文档链接前的前缀文本。 |
| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 |
| `selectionDocsOmitLabel` | `boolean` | 在选择文案中直接显示文档路径，而不是带标签的文档链接。 |
| `selectionExtras` | `string[]` | 追加到选择文案中的额外短字符串。 |
| `markdownCapable` | `boolean` | 将该渠道标记为支持 Markdown，用于出站格式化决策。 |
| `markdownCapable` | `boolean` | 将渠道标记为支持 Markdown，用于出站格式决策。 |
| `exposure` | `object` | 用于设置、已配置列表和文档界面的渠道可见性控制。 |
| `quickstartAllowFrom` | `boolean` | 将此渠道纳入标准快速开始 `allowFrom` 设置流程。 |
| `forceAccountBinding` | `boolean` | 即使只有一个账号，也要求显式绑定账号。 |
| `quickstartAllowFrom` | `boolean` | 让此渠道加入标准快速开始 `allowFrom` 设置流程。 |
| `forceAccountBinding` | `boolean` | 即使只有一个账号也要求显式绑定账号。 |
| `preferSessionLookupForAnnounceTarget` | `boolean` | 为此渠道解析公告目标时优先使用会话查找。 |
示例：
@ -149,7 +149,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
`exposure` 支持：
- `configured`：在已配置/Status 风格的列表界面中包含该渠道
- `configured`：在已配置/状态样式的列表界面中包含该渠道
- `setup`：在交互式设置/配置选择器中包含该渠道
- `docs`：在文档/导航界面中将该渠道标记为面向公众
@ -161,24 +161,24 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
`openclaw.install` 是包元数据，不是清单元数据。
| 字段 | 类型 | 含义 |
| ---------------------------- | -------------------- | -------------------------------------------------------------------------------- |
| `npmSpec` | `string` | 用于安装/更新流程的规范 npm 规格。 |
| `localPath` | `string` | 本地开发或内置安装路径。 |
| `defaultChoice` | `"npm"` \| `"local"` | 两者都可用时的首选安装来源。 |
| `minHostVersion` | `string` | 最低支持的 OpenClaw 版本，形式为 `>=x.y.z`。 |
| `expectedIntegrity` | `string` | 预期的 npm 分发完整性字符串，通常为 `sha512-...`，用于固定版本安装。 |
| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重新安装流程从特定的陈旧配置失败中恢复。 |
| 字段 | 类型 | 含义 |
| ---------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
| `npmSpec` | `string` | 用于安装/更新流程的规范 npm spec。 |
| `localPath` | `string` | 本地开发或内置安装路径。 |
| `defaultChoice` | `"npm"` \| `"local"` | 当两者都可用时首选的安装源。 |
| `minHostVersion` | `string` | 支持的最低 OpenClaw 版本，形式为 `>=x.y.z` 或 `>=x.y.z-prerelease`。 |
| `expectedIntegrity` | `string` | 预期的 npm dist 完整性字符串，通常为 `sha512-...`，用于固定版本安装。 |
| `allowInvalidConfigRecovery` | `boolean` | 允许内置插件重新安装流程从特定的陈旧配置失败中恢复。 |
<AccordionGroup>
<Accordion title="Onboarding behavior">
交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载前公开提供商认证选择或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 npm 或本地安装，安装或启用该插件，然后继续所选流程。npm 新手引导选项需要带有注册表 `npmSpec` 的可信目录元数据；精确版本和 `expectedIntegrity` 是可选固定值。如果存在 `expectedIntegrity`，安装/更新流程会强制校验它。将“显示什么”的元数据保留在 `openclaw.plugin.json` 中，将“如何安装它”的元数据保留在 `package.json` 中。
<Accordion title="新手引导行为">
交互式新手引导也会将 `openclaw.install` 用于按需安装界面。如果你的插件在运行时加载前暴露提供商认证选项或渠道设置/目录元数据，新手引导可以显示该选项，提示选择 npm 或本地安装，安装或启用插件，然后继续所选流程。Npm 新手引导选项需要受信任的目录元数据和注册表 `npmSpec`；精确版本和 `expectedIntegrity` 是可选固定项。如果存在 `expectedIntegrity`，安装/更新流程会强制校验它。请将“显示什么”的元数据放在 `openclaw.plugin.json` 中，将“如何安装它”的元数据放在 `package.json` 中。
</Accordion>
<Accordion title="minHostVersion enforcement">
如果设置了 `minHostVersion`，安装和清单注册表加载都会强制执行它。旧版主机会跳过该插件；无效的版本字符串会被拒绝。
<Accordion title="minHostVersion 强制执行">
如果设置了 `minHostVersion`，安装和非内置清单注册表加载都会强制执行它。较旧的宿主会跳过外部插件；无效的版本字符串会被拒绝。内置源插件会被假定为与宿主检出版本一致。
</Accordion>
<Accordion title="Pinned npm installs">
对于固定版本的 npm 安装，请在 `npmSpec` 中保留精确版本，并添加预期的工件完整性：
<Accordion title="固定版本 npm 安装">
对于固定版本 npm 安装，请在 `npmSpec` 中保留精确版本，并添加预期的构件完整性：
```json
{
@ -193,14 +193,14 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
```
</Accordion>
<Accordion title="allowInvalidConfigRecovery scope">
`allowInvalidConfigRecovery` 不是破损配置的通用绕过开关。它仅用于狭窄的内置插件恢复场景，让重新安装/设置可以修复已知升级残留，例如缺失的内置插件路径，或同一插件的陈旧 `channels.<id>` 条目。如果配置因无关原因损坏，安装仍会以失败关闭，并提示操作员运行 `openclaw doctor --fix`。
<Accordion title="allowInvalidConfigRecovery 范围">
`allowInvalidConfigRecovery` 不是针对损坏配置的通用绕过机制。它仅用于狭义的内置插件恢复，因此重新安装/设置可以修复已知的升级残留，例如缺失的内置插件路径，或同一插件的陈旧 `channels.<id>` 条目。如果配置因无关原因损坏，安装仍会失败关闭，并提示操作员运行 `openclaw doctor --fix`。
</Accordion>
</AccordionGroup>
### 延迟完整加载
渠道插件可以通过以下配置选择延迟加载：
渠道插件可以通过以下方式选择延迟加载：
```json
{
@ -214,17 +214,17 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
}
```
启用后，即使对于已经配置的渠道，OpenClaw 在监听前启动阶段也只加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。
启用后，即使对于已经配置的渠道，OpenClaw 也只会在监听前启动阶段加载 `setupEntry`。完整入口会在 Gateway 网关开始监听后加载。
<Warning>
仅当你的 `setupEntry` 在 Gateway 网关开始监听前注册了 Gateway 网关所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果完整入口拥有必需的启动能力，请保留默认行为。
只有当你的 `setupEntry` 注册了 Gateway 网关在开始监听前所需的一切（渠道注册、HTTP 路由、Gateway 网关方法）时，才启用延迟加载。如果完整入口拥有必需的启动能力，请保留默认行为。
</Warning>
如果你的设置/完整入口注册 Gateway 网关 RPC 方法，请将它们放在插件专用前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍由核心拥有，并始终解析为 `operator.admin`。
如果你的设置/完整入口注册了 Gateway 网关 RPC 方法，请将它们放在插件专属前缀下。保留的核心管理命名空间（`config.*`、`exec.approvals.*`、`wizard.*`、`update.*`）仍归核心所有，并且始终解析为 `operator.admin`。
## 插件清单
每个原生插件都必须在包根目录中随附一个 `openclaw.plugin.json`。OpenClaw 使用它在不执行插件代码的情况下验证配置。
每个原生插件都必须在包根目录中附带一个 `openclaw.plugin.json`。OpenClaw 会使用它在不执行插件代码的情况下验证配置。
```json
{
@ -244,7 +244,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
}
```
对于渠道插件，添加 `kind` 和 `channels`：
对于渠道插件，请添加 `kind` 和 `channels`：
```json
{
@ -259,7 +259,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
}
```
即使没有配置的插件也必须随附一个架构。空架构是有效的：
即使没有配置的插件也必须附带架构。空架构是有效的：
```json
{
@ -271,7 +271,7 @@ Reference for plugin packaging (`package.json` 元数据)、清单 (`openclaw.pl
}
```
完整架构参考见[插件清单](/zh-CN/plugins/manifest)。
完整架构参考请参阅 [插件清单](/zh-CN/plugins/manifest)。
## ClawHub 发布
@ -283,12 +283,12 @@ clawhub package publish your-org/your-plugin
```
<Note>
旧版的仅 Skills 发布别名用于 Skills。插件包应始终使用 `clawhub package publish`。
旧版仅 Skills 发布别名用于 Skills。插件包应始终使用 `clawhub package publish`。
</Note>
## 设置入口
`setup-entry.ts` 文件是 `index.ts` 的轻量级替代项，OpenClaw 在只需要设置界面时加载它（新手引导、配置修复、已禁用渠道检查）。
`setup-entry.ts` 文件是 `index.ts` 的轻量替代入口，OpenClaw 仅需要设置界面（新手引导、配置修复、已禁用渠道检查）时会加载它。
```typescript
// setup-entry.ts
@ -298,9 +298,9 @@ import { myChannelPlugin } from "./src/channel.js";
export default defineSetupPluginEntry(myChannelPlugin);
```
这可以避免在设置流程中加载繁重的运行时代码（加密库、CLI 注册、后台服务）。
这避免在设置流程中加载繁重的运行时代码（加密库、CLI 注册、后台服务）。
将设置安全导出保存在辅助模块中的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，因此设置期间的运行时接线可以保持轻量且明确。
将设置安全导出放在伴随模块中的内置工作区渠道，可以使用来自 `openclaw/plugin-sdk/channel-entry-contract` 的 `defineBundledChannelSetupEntry(...)`，而不是 `defineSetupPluginEntry(...)`。该内置契约还支持可选的 `runtime` 导出，因此设置时的运行时接线可以保持轻量且显式。
<AccordionGroup>
<Accordion title="OpenClaw 何时使用 setupEntry 而不是完整入口">
@ -321,42 +321,42 @@ export default defineSetupPluginEntry(myChannelPlugin);
- CLI 注册。
- 后台服务。
- 繁重的运行时导入（加密、SDK）。
- 仅在启动后需要的 Gateway 网关方法。
- 仅在启动后才需要的 Gateway 网关方法。
</Accordion>
</AccordionGroup>
### 窄范围设置辅助导入
### 窄设置辅助导入
对于热门的仅设置路径，如果你只需要设置界面的一部分，优先使用窄范围设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口：
对于高频设置专用路径，当你只需要设置界面的一部分时，优先使用窄设置辅助接缝，而不是更宽泛的 `plugin-sdk/setup` 总入口：
| 导入路径 | 用途 | 关键导出 |
| ---------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动中仍可用的设置期间运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | 感知环境的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置/安装 CLI/归档/文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| 导入路径 | 用途 | 关键导出 |
| ---------------------------------- | ------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `plugin-sdk/setup-runtime` | 在 `setupEntry` / 延迟渠道启动中仍可用的设置时运行时辅助工具 | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | 感知环境的账号设置适配器 | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | 设置/安装 CLI/归档/文档辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
当你需要完整的共享设置工具箱时，请使用更宽泛的 `plugin-sdk/setup` 接缝，包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具。
当你需要完整的共享设置工具箱时，使用更宽泛的 `plugin-sdk/setup` 接缝，包括 `moveSingleAccountChannelSectionToDefaultAccount(...)` 等配置补丁辅助工具。
设置补丁适配器在导入时保持热路径安全。它们的内置单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在实际使用适配器前急切加载内置契约界面发现逻辑。
设置补丁适配器在导入时保持热路径安全。它们的内置单账号提升契约界面查找是惰性的，因此导入 `plugin-sdk/setup-runtime` 不会在适配器实际使用前就提前加载内置契约界面发现。
### 渠道拥有的单账号提升
### 渠道自有的单账号提升
当渠道从单账号顶层配置升级到 `channels.<id>.accounts.*` 时，默认共享行为是将提升后的账号范围值移动到 `accounts.default`。
当渠道从单账号顶层配置升级到 `channels.<id>.accounts.*` 时，默认共享行为是将已提升的账号作用域值移动到 `accounts.default`。
内置渠道可以通过其设置契约界面缩小或覆盖该提升行为：
内置渠道可以通过它们的设置契约界面收窄或覆盖该提升行为：
- `singleAccountKeysToMove`：应移动到提升后账号中的额外顶层键
- `namedAccountPromotionKeys`：当命名账号已存在时，只有这些键会移动到提升后的账号；共享策略/投递键仍保留在渠道根部
- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收提升后的值
- `singleAccountKeysToMove`：应移动到已提升账号中的额外顶层键
- `namedAccountPromotionKeys`：当具名账号已存在时，只有这些键会移动到已提升账号中；共享策略/投递键保留在渠道根级别
- `resolveSingleAccountPromotionTarget(...)`：选择哪个现有账号接收已提升值
<Note>
Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix 账号，或者 `defaultAccount` 指向现有的非规范键（例如 `Ops`），提升会保留该账号，而不是创建新的 `accounts.default` 条目。
Matrix 是当前的内置示例。如果恰好已存在一个具名 Matrix 账号，或者 `defaultAccount` 指向了现有的非规范键（例如 `Ops`），提升会保留该账号，而不是创建新的 `accounts.default` 条目。
</Note>
## 配置架构
## 配置 schema
插件配置会根据你清单中的 JSON Schema 进行验证。用户通过以下方式配置插件：
插件配置会根据你的 manifest 中的 JSON Schema 进行验证。用户通过以下方式配置插件：
```json5
{
@ -374,7 +374,7 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix
你的插件会在注册期间以 `api.pluginConfig` 接收此配置。
对于渠道专属配置，请改用渠道配置部分：
对于渠道特定配置，请改用渠道配置区段：
```json5
{
@ -387,9 +387,9 @@ Matrix 是当前的内置示例。如果已经恰好存在一个命名 Matrix
}
```
### 构建渠道配置架构
### 构建渠道配置 schema
使用 `buildChannelConfigSchema` 将 Zod 架构转换为插件拥有的配置工件所使用的 `ChannelConfigSchema` 包装器：
使用 `buildChannelConfigSchema` 将 Zod schema 转换为插件自有配置产物使用的 `ChannelConfigSchema` 包装器：
```typescript
import { z } from "zod";
@ -405,11 +405,11 @@ const accountSchema = z.object({
const configSchema = buildChannelConfigSchema(accountSchema);
```
对于第三方插件，冷路径契约仍然是插件清单：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置架构、设置和 UI 界面就可以在不加载运行时代码的情况下检查 `channels.<id>`。
对于第三方插件，冷路径契约仍然是插件 manifest：将生成的 JSON Schema 镜像到 `openclaw.plugin.json#channelConfigs`，这样配置 schema、设置和 UI 界面就能在不加载运行时代码的情况下检查 `channels.<id>`。
## 设置向导
渠道插件可以为 `openclaw onboard` 提供交互式设置向导。该向导是 `ChannelPlugin` 上的一个 `ChannelSetupWizard` 对象：
渠道插件可以为 `openclaw onboard` 提供交互式设置向导。该向导是 `ChannelPlugin` 上的 `ChannelSetupWizard` 对象：
```typescript
import type { ChannelSetupWizard } from "openclaw/plugin-sdk/channel-setup";
@ -442,17 +442,17 @@ const setupWizard: ChannelSetupWizard = {
};
```
`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等。完整示例请参见内置插件包（例如 Discord 插件 `src/channel.setup.ts`）。
`ChannelSetupWizard` 类型支持 `credentials`、`textInputs`、`dmPolicy`、`allowFrom`、`groupAccess`、`prepare`、`finalize` 等。完整示例请参阅内置插件包（例如 Discord 插件的 `src/channel.setup.ts`）。
<AccordionGroup>
<Accordion title="共享 allowFrom 提示">
对于只需要标准 `note -> prompt -> parse -> merge -> patch` 流程的私信允许列表提示，优先使用来自 `openclaw/plugin-sdk/setup` 的共享设置辅助工具：`createPromptParsedAllowFromForAccount(...)`、`createTopLevelChannelParsedAllowFromPrompt(...)` 和 `createNestedChannelParsedAllowFromPrompt(...)`。
</Accordion>
<Accordion title="标准渠道设置 Status">
对于只按标签、分数和可选额外行变化的渠道设置 Status 块，优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。
对于仅因标签、分数和可选额外行而变化的渠道设置 Status 块，优先使用来自 `openclaw/plugin-sdk/setup` 的 `createStandardChannelSetupStatus(...)`，而不是在每个插件中手写相同的 `status` 对象。
</Accordion>
<Accordion title="可选渠道设置界面">
对于只应在特定上下文中出现的可选设置界面，请使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`：
对于只应在特定上下文中出现的可选设置界面，使用来自 `openclaw/plugin-sdk/channel-setup` 的 `createOptionalChannelSetupSurface`：
```typescript
import { createOptionalChannelSetupSurface } from "openclaw/plugin-sdk/channel-setup";
@ -466,16 +466,16 @@ const setupWizard: ChannelSetupWizard = {
// Returns { setupAdapter, setupWizard }
```
当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还公开了更低层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。
当你只需要该可选安装界面的一半时，`plugin-sdk/channel-setup` 还暴露了更底层的 `createOptionalChannelSetupAdapter(...)` 和 `createOptionalChannelSetupWizard(...)` 构建器。
生成的可选适配器/向导会在真实配置写入时关闭失败。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时附加文档链接。
生成的可选适配器/向导会在真实配置写入时默认失败。它们在 `validateInput`、`applyAccountConfig` 和 `finalize` 中复用同一条需要安装的消息，并在设置了 `docsPath` 时附加文档链接。
</Accordion>
<Accordion title="二进制支持的设置辅助工具">
对于二进制支持的设置 UI，优先使用共享的委托辅助工具，而不是将相同的二进制/Status 胶水复制到每个渠道中：
<Accordion title="二进制文件驱动的设置辅助工具">
对于二进制文件驱动的设置 UI，优先使用共享的委托辅助工具，而不是把相同的二进制文件/Status 粘合逻辑复制到每个渠道中：
- `createDetectedBinaryStatus(...)` 用于只按标签、提示、分数和二进制检测变化的 Status 块
- `createCliPathTextInput(...)` 用于路径支持的文本输入
- `createDetectedBinaryStatus(...)` 用于只因标签、提示、分数和二进制文件检测而变化的 Status 块
- `createCliPathTextInput(...)` 用于基于路径的文本输入
- 当 `setupEntry` 需要惰性转发到更重的完整向导时，使用 `createDelegatedSetupWizardStatusResolvers(...)`、`createDelegatedPrepare(...)`、`createDelegatedFinalize(...)` 和 `createDelegatedResolveConfigured(...)`
- 当 `setupEntry` 只需要委托 `textInputs[*].shouldPrompt` 决策时，使用 `createDelegatedTextInputShouldPrompt(...)`
@ -501,7 +501,7 @@ const setupWizard: ChannelSetupWizard = {
```
</Tab>
<Tab title="npm 包规格">
当包尚未迁移到 ClawHub，或者你在迁移期间需要直接的 npm 安装路径时，请使用 npm：
当包尚未迁移到 ClawHub，或者迁移期间需要直接 npm 安装路径时，使用 npm：
```bash
openclaw plugins install npm:@myorg/openclaw-my-plugin
@ -510,7 +510,7 @@ const setupWizard: ChannelSetupWizard = {
</Tab>
</Tabs>
**仓库内插件：**放置在内置插件工作区树下，它们会在构建期间被自动发现。
**仓库内插件：**放在内置插件工作区树下，它们会在构建期间被自动发现。
**用户可以安装：**
@ -519,17 +519,17 @@ openclaw plugins install <package-name>
```
<Info>
对于来自 npm 的安装，`openclaw plugins install` 会在禁用生命周期脚本的情况下将包安装到 `~/.openclaw/npm` 下。请保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
对于来自 npm 的安装，`openclaw plugins install` 会在禁用生命周期脚本的情况下将包安装到 `~/.openclaw/npm` 下。保持插件依赖树为纯 JS/TS，并避免使用需要 `postinstall` 构建的包。
</Info>
<Note>
Gateway 网关启动不会安装插件依赖。npm/git/ClawHub 安装流程负责依赖收敛；本地插件必须已经安装好其依赖。
Gateway 网关启动不会安装插件依赖。npm/git/ClawHub 安装流程负责依赖收敛；本地插件必须已安装其依赖。
</Note>
内置包元数据是显式的，不是在 Gateway 网关启动时从构建后的 JavaScript 推断出来的。运行时依赖项应放在拥有它们的插件包中；打包版 OpenClaw 启动流程绝不会修复或镜像插件依赖项。
内置包元数据是显式的，不是在 Gateway 网关启动时从构建后的 JavaScript 中推断出来的。运行时依赖应放在拥有这些依赖的插件包中；打包版 OpenClaw 启动过程永远不会修复或镜像插件依赖。
## 相关内容
- [构建插件](/zh-CN/plugins/building-plugins) — 分步入门指南
- [插件清单](/zh-CN/plugins/manifest) — 完整的清单 schema 参考
- [插件清单](/zh-CN/plugins/manifest) — 完整清单架构参考
- [SDK 入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 和 `defineChannelPluginEntry`

144
docs/zh-CN/providers/google.md
View File

@ -2,37 +2,36 @@
read_when:
- 你想在 OpenClaw 中使用 Google Gemini 模型
- 你需要 API 密钥或 OAuth 认证流程
summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、网页搜索）
title: Google (Gemini)
summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、Web 搜索）
title: Google（Gemini）
x-i18n:
generated_at: "2026-04-28T12:01:47Z"
generated_at: "2026-05-02T02:49:07Z"
model: gpt-5.5
provider: openai
source_hash: ea4b53dcea10fef67920da3baca4c85325ee4d4da780fbf708b67bc618e064a6
source_hash: 17d7694408dd02ea87d71530a544ad45e0284a973803f76313338a5065b3f7d5
source_path: providers/google.md
workflow: 16
---
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，另外还支持
图像生成、媒体理解（图像/音频/视频）、文本转语音，以及通过
Gemini Grounding 进行 Web 搜索。
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，并通过
Gemini Grounding 提供图像生成、媒体理解（图像/音频/视频）、文本转语音和 Web 搜索。
- 提供商：`google`
- 凭证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
- API：Google Gemini API
- 运行时选项：`agents.defaults.agentRuntime.id: "google-gemini-cli"`
会复用 Gemini CLI OAuth，同时将模型引用保持为规范的 `google/*`。
## 入门指南
选择你偏好的凭证方式，并按照设置步骤操作。
选择你偏好的认证方式，并按照设置步骤操作。
<Tabs>
<Tab title="API key">
**最适合：**通过 Google AI Studio 进行标准 Gemini API 访问。
**适用于：**通过 Google AI Studio 进行标准 Gemini API 访问。
<Steps>
<Step title="运行新手引导">
<Step title="Run onboarding">
```bash
openclaw onboard --auth-choice gemini-api-key
```
@ -46,7 +45,7 @@ Gemini Grounding 进行 Web 搜索。
--gemini-api-key "$GEMINI_API_KEY"
```
</Step>
<Step title="设置默认模型">
<Step title="Set a default model">
```json5
{
agents: {
@ -57,7 +56,7 @@ Gemini Grounding 进行 Web 搜索。
}
```
</Step>
<Step title="验证模型可用">
<Step title="Verify the model is available">
```bash
openclaw models list --provider google
```
@ -65,22 +64,21 @@ Gemini Grounding 进行 Web 搜索。
</Steps>
<Tip>
环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都受支持。使用你已经配置好的那个即可。
环境变量 `GEMINI_API_KEY` 和 `GOOGLE_API_KEY` 都可以使用。使用你已经配置好的那个即可。
</Tip>
</Tab>
<Tab title="Gemini CLI (OAuth)">
**最适合：**通过 PKCE OAuth 复用现有 Gemini CLI 登录，而不是使用单独的 API key。
**适用于：**通过 PKCE OAuth 复用现有的 Gemini CLI 登录，而不是单独使用 API key。
<Warning>
`google-gemini-cli` 提供商是一个非官方集成。一些用户
反馈以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。
`google-gemini-cli` 提供商是非官方集成。有些用户报告以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。
</Warning>
<Steps>
<Step title="安装 Gemini CLI">
本地 `gemini` 命令必须在 `PATH` 上可用。
<Step title="Install the Gemini CLI">
本地 `gemini` 命令必须可在 `PATH` 上使用。
```bash
# Homebrew
@ -93,12 +91,12 @@ Gemini Grounding 进行 Web 搜索。
OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括
常见的 Windows/npm 布局。
</Step>
<Step title="通过 OAuth 登录">
<Step title="Log in via OAuth">
```bash
openclaw models auth login --provider google-gemini-cli --set-default
```
</Step>
<Step title="验证模型可用">
<Step title="Verify the model is available">
```bash
openclaw models list --provider google
```
@ -109,7 +107,7 @@ Gemini Grounding 进行 Web 搜索。
- 运行时：`google-gemini-cli`
- 别名：`gemini-cli`
Gemini 3.1 Pro 的 Gemini API 模型 ID 是 `gemini-3.1-pro-preview`。OpenClaw 接受更短的 `google/gemini-3.1-pro` 作为便利别名，并在调用提供商前将其规范化。
Gemini 3.1 Pro 的 Gemini API 模型 ID 是 `gemini-3.1-pro-preview`。OpenClaw 接受较短的 `google/gemini-3.1-pro` 作为便捷别名，并会在提供商调用前对其进行规范化。
**环境变量：**
@ -124,12 +122,12 @@ Gemini Grounding 进行 Web 搜索。
</Note>
<Note>
如果登录在浏览器流程启动前失败，请确保本地 `gemini`
命令已安装并在 `PATH` 上。
如果登录在浏览器流程开始前失败，请确保本地 `gemini`
命令已安装并位于 `PATH` 上。
</Note>
`google-gemini-cli/*` 模型引用是旧版兼容别名。新的
配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时配合使用 `google-gemini-cli`
配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli`
运行时。
</Tab>
@ -151,20 +149,47 @@ Gemini Grounding 进行 Web 搜索。
| 思考/推理 | 是（Gemini 2.5+ / Gemini 3+） |
| Gemma 4 模型 | 是 |
## Web 搜索
内置的 `gemini` Web 搜索提供商使用 Gemini Google Search grounding。
在 `plugins.entries.google.config.webSearch` 下配置它：
```json5
{
plugins: {
entries: {
google: {
config: {
webSearch: {
apiKey: "AIza...", // optional if GEMINI_API_KEY is set
baseUrl: "https://generativelanguage.googleapis.com/v1beta",
model: "gemini-2.5-flash",
},
},
},
},
},
}
```
`webSearch.baseUrl` 是可选项，用于操作方代理或兼容的
Gemini API 端点。请参阅 [Gemini 搜索](/zh-CN/tools/gemini-search) 了解
提供商特定的工具行为。
<Tip>
Gemini 3 模型使用 `thinkingLevel`，而不是 `thinkingBudget`。OpenClaw 会将
Gemini 3 模型使用 `thinkingLevel` 而不是 `thinkingBudget`。OpenClaw 会将
Gemini 3、Gemini 3.1 和 `gemini-*-latest` 别名的推理控制映射到
`thinkingLevel`，因此默认/低延迟运行不会发送已禁用的
`thinkingBudget` 值。
`/think adaptive` 会保留 Google 的动态思考语义，而不是选择一个
`/think adaptive` 会保留 Google 的动态思考语义，而不是选择
固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 会省略固定的 `thinkingLevel`，以便
Google 可以选择级别；Gemini 2.5 会发送 Google 的动态哨兵值
`thinkingBudget: -1`。
Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
会为 Gemma 4 将 `thinkingBudget` 重写为受支持的 Google `thinkingLevel`。
将思考设置为 `off` 会保持思考禁用，而不是映射到
将思考设置为 `off` 会保持思考禁用状态，而不是映射到
`MINIMAL`。
</Tip>
@ -198,11 +223,11 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
## 视频生成
内置的 `google` 插件还会通过共享的
内置的 `google` 插件还通过共享的
`video_generate` 工具注册视频生成。
- 默认视频模型：`google/veo-3.1-fast-generate-preview`
- 模式：文本到视频、图像到视频，以及单视频引用流程
- 模式：文本转视频、图像转视频，以及单视频参考流程
- 支持 `aspectRatio`、`resolution` 和 `audio`
- 当前时长限制：**4 到 8 秒**
@ -226,15 +251,15 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
## 音乐生成
内置的 `google` 插件还会通过共享的
内置的 `google` 插件还通过共享的
`music_generate` 工具注册音乐生成。
- 默认音乐模型：`google/lyria-3-clip-preview`
- 还支持 `google/lyria-3-pro-preview`
- 提示词控制：`lyrics` 和 `instrumental`
- 输出格式：默认 `mp3`，`google/lyria-3-pro-preview` 另支持 `wav`
- 输出格式：默认 `mp3`，在 `google/lyria-3-pro-preview` 上还支持 `wav`
- 参考输入：最多 10 张图像
- 基于会话的运行会通过共享的任务/Status 流程分离，包括 `action: "status"`
- 由会话支撑的运行会通过共享的任务/Status 流程分离，包括 `action: "status"`
要将 Google 用作默认音乐提供商：
@ -260,9 +285,9 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
`gemini-3.1-flash-tts-preview`。
- 默认语音：`Kore`
- 凭证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
- 输出：常规 TTS 附件使用 WAV，语音备注目标使用 Opus，Talk/电话使用 PCM
- 语音备注输出：Google PCM 会封装为 WAV，并通过 `ffmpeg` 转码为 48 kHz Opus
- 认证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
- 输出：常规 TTS 附件使用 WAV，语音笔记目标使用 Opus，Talk/电话使用 PCM
- 语音笔记输出：Google PCM 会被包装为 WAV，并用 `ffmpeg` 转码为 48 kHz Opus
要将 Google 用作默认 TTS 提供商：
@ -285,12 +310,12 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
```
Gemini API TTS 使用自然语言提示词进行风格控制。设置
`audioProfile` 可在朗读文本前添加可复用的风格提示词。若你的提示词文本提到具名说话人，请设置
`audioProfile` 可在朗读文本前添加一个可复用的风格提示词。当你的提示词文本提到具名说话人时，请设置
`speakerName`。
Gemini API TTS 还接受文本中的表现性方括号音频标签，
例如 `[whispers]` 或 `[laughs]`。若要在将标签发送给 TTS 的同时避免它们出现在可见聊天回复中，
请将它们放入 `[[tts:text]]...[[/tts:text]]`
例如 `[whispers]` 或 `[laughs]`。要在将标签发送给 TTS 的同时，让标签不出现在可见聊天回复中，
请把它们放在 `[[tts:text]]...[[/tts:text]]`
块内：
```text
@ -306,21 +331,21 @@ Here is the clean reply text.
## 实时语音
内置的 `google` 插件会注册一个由
Gemini Live API 支持的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接。
内置的 `google` 插件注册了一个由
Gemini Live API 支撑的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接。
| 设置 | 配置路径 | 默认值 |
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| 模型 | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
| 语音 | `...google.voice` | `Kore` |
| 温度 | `...google.temperature` | （未设置） |
| VAD 起始灵敏度 | `...google.startSensitivity` | （未设置） |
| VAD 结束灵敏度 | `...google.endSensitivity` | （未设置） |
| VAD 开始敏感度 | `...google.startSensitivity` | （未设置） |
| VAD 结束敏感度 | `...google.endSensitivity` | （未设置） |
| 静音时长 | `...google.silenceDurationMs` | （未设置） |
| 活动处理 | `...google.activityHandling` | Google 默认值，`start-of-activity-interrupts` |
| 活动处理 | `...google.activityHandling` | Google 默认值，`start-of-activity-interrupts` |
| 轮次覆盖 | `...google.turnCoverage` | Google 默认值，`only-activity` |
| 禁用自动 VAD | `...google.automaticActivityDetectionDisabled` | `false` |
| API key | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
| API key | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
Voice Call 实时配置示例：
@ -353,21 +378,22 @@ Voice Call 实时配置示例：
<Note>
Google Live API 通过 WebSocket 使用双向音频和函数调用。
OpenClaw 会将电话/Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并
让工具调用继续使用共享的实时语音契约。除非你需要更改采样，否则不要设置 `temperature`；
OpenClaw 会省略非正值，因为 Google Live 在 `temperature: 0` 时可能返回没有音频的转录文本。
Gemini API 转录在不使用 `languageCodes` 的情况下启用；当前 Google
让工具调用继续使用共享的实时语音契约。除非需要更改采样，否则保持 `temperature`
未设置；OpenClaw 会省略非正值，
因为 Google Live 可能会在 `temperature: 0` 时返回没有音频的转写内容。
Gemini API 转写会在没有 `languageCodes` 的情况下启用；当前 Google
SDK 会拒绝此 API 路径上的语言代码提示。
</Note>
<Note>
Control UI Talk 支持使用受限一次性令牌的 Google Live 浏览器会话。
仅后端的实时语音提供商也可以通过通用
Control UI Talk 支持带受限一次性
令牌的 Google Live 浏览器会话。仅后端的实时语音提供商也可以通过通用
Gateway 网关中继传输运行，这会将提供商凭证保留在 Gateway 网关上。
</Note>
对于维护者实时验证，运行
对于维护者实时验证，请运行
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`。
Google 分支会铸造 Control
Google 分支会签发与 Control
UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket 端点，发送初始设置载荷，
并等待 `setupComplete`。
@ -378,10 +404,12 @@ UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket
对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw
会将配置的 `cachedContent` 句柄传递给 Gemini 请求。
- 使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数
- 如果两者都存在，`cachedContent` 优先
- 使用 `cachedContent` 或旧版 `cached_content`
配置按模型或全局参数
- 如果两者同时存在，`cachedContent` 优先
- 示例值：`cachedContents/prebuilt-context`
- Gemini 缓存命中用量会从上游 `cachedContentTokenCount` 规范化为 OpenClaw `cacheRead`
- Gemini 缓存命中用量会从上游 `cachedContentTokenCount`
规范化为 OpenClaw `cacheRead`
```json5
{
@ -401,7 +429,7 @@ UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket
</Accordion>
<Accordion title="Gemini CLI JSON 用量说明">
<Accordion title="Gemini CLI JSON 使用说明">
使用 `google-gemini-cli` OAuth 提供商时，OpenClaw 会按如下方式规范化
CLI JSON 输出：
@ -413,8 +441,8 @@ UI Talk 使用的相同受限 Live API 令牌形态，打开浏览器 WebSocket
</Accordion>
<Accordion title="环境与守护进程设置">
如果 Gateway 网关作为守护进程运行（launchd/systemd），请确保 `GEMINI_API_KEY`
<Accordion title="环境和守护进程设置">
如果 Gateway 网关作为守护进程（launchd/systemd）运行，请确保 `GEMINI_API_KEY`
可供该进程使用（例如，在 `~/.openclaw/.env` 中，或通过
`env.shellEnv`）。
</Accordion>

231
docs/zh-CN/providers/xai.md
View File

@ -1,19 +1,19 @@
---
read_when:
- 你想在 OpenClaw 中使用 Grok 模型
- 你正在配置 xAI 身份验证或模型 ID
- 你正在配置 xAI 凭证或模型 ID
summary: 在 OpenClaw 中使用 xAI Grok 模型
title: xAI
x-i18n:
generated_at: "2026-05-02T01:45:07Z"
generated_at: "2026-05-02T02:49:00Z"
model: gpt-5.5
provider: openai
source_hash: 9366d6a053fb515d843bbb984ee0fce2eb342a022a6d9aa60df983fc0f8d5745
source_hash: 7f36b597fd5c47b61724080deb0d545bca024aca17744fc8aa6a0eb4872d12d2
source_path: providers/xai.md
workflow: 16
---
OpenClaw 内置了一个用于 Grok 模型的 `xai` 提供商插件。
OpenClaw 随附内置的 `xai` 提供商插件，用于 Grok 模型。
## 入门指南
@ -39,11 +39,13 @@ OpenClaw 内置了一个用于 Grok 模型的 `xai` 提供商插件。
</Steps>
<Note>
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`。
如果你在 `plugins.entries.xai.config.webSearch.apiKey` 下存储 xAI key，
内置的 xAI 模型提供商也会复用该 key 作为回退。
内置 xAI 模型提供商也会将该 key 作为回退复用。
设置 `plugins.entries.xai.config.webSearch.baseUrl`，可将 Grok `web_search`
以及默认情况下的 `x_search` 路由到操作方的 xAI Responses 代理。
`code_execution` 调优位于 `plugins.entries.xai.config.codeExecution` 下。
</Note>
@ -51,7 +53,7 @@ OpenClaw 使用 xAI Responses API 作为内置的 xAI 传输协议。同一个
OpenClaw 开箱即包含这些 xAI 模型系列：
| 系列 | 模型 ID |
| 系列 | 模型 id |
| -------------- | ------------------------------------------------------------------------ |
| Grok 3 | `grok-3`, `grok-3-fast`, `grok-3-mini`, `grok-3-mini-fast` |
| Grok 4.3 | `grok-4.3` |
@ -61,41 +63,41 @@ OpenClaw 开箱即包含这些 xAI 模型系列：
| 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 形态时，该插件也会
向前解析它们。
当新的 `grok-4*` 和 `grok-code-fast*` id 遵循相同 API 形态时，
该插件也会前向解析这些 id。
<Tip>
`grok-4.3`、`grok-4-fast`、`grok-4-1-fast` 以及 `grok-4.20-beta-*`
变体是内置目录中当前支持图像能力的 Grok 引用。
`grok-4.3`、`grok-4-fast`、`grok-4-1-fast` 和 `grok-4.20-beta-*`
变体是内置目录中当前支持图像的 Grok 引用。
</Tip>
## OpenClaw 功能覆盖范围
内置插件会将 xAI 当前的公开 API 表面映射到 OpenClaw 共享的
提供商和工具契约上。不适合共享契约的能力
（例如流式 TTS 和实时语音）不会暴露，请参见下表。
内置插件会将 xAI 当前的公开 API 表面映射到 OpenClaw 的共享
提供商和工具契约。不适配共享契约的能力
（例如流式 TTS 和实时语音）不会暴露；见下表。
| xAI 能力 | OpenClaw 表面 | Status |
| -------------------------- | ----------------------------------------- | ------------------------------------------------------------------- |
| 聊天 / Responses | `xai/<model>` 模型提供商 | 是 |
| 服务端网页搜索 | `web_search` 提供商 `grok` | 是 |
| 服务端 X 搜索 | `x_search` 工具 | 是 |
| 服务端代码执行 | `code_execution` 工具 | 是 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 批量文本转语音 | `messages.tts.provider: "xai"` / `tts` | 是 |
| 流式 TTS | — | 未暴露；OpenClaw 的 TTS 契约返回完整音频缓冲区 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "xai"` | 是 |
| 实时语音 | — | 尚未暴露；使用不同的会话/WebSocket 契约 |
| 文件 / 批处理 | 仅通用模型 API 兼容性 | 不是一等 OpenClaw 工具 |
| xAI 能力 | OpenClaw 表面 | Status |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------------------- |
| 聊天 / Responses | `xai/<model>` 模型提供商 | 是 |
| 服务端 Web 搜索 | `web_search` 提供商 `grok` | 是 |
| 服务端 X 搜索 | `x_search` 工具 | 是 |
| 服务端代码执行 | `code_execution` 工具 | 是 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 批量文本转语音 | `messages.tts.provider: "xai"` / `tts` | 是 |
| 流式 TTS | — | 未暴露；OpenClaw 的 TTS 契约返回完整音频缓冲区 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "xai"` | 是 |
| 实时语音 | — | 暂未暴露；使用不同的会话/WebSocket 契约 |
| 文件 / 批处理 | 仅通用模型 API 兼容性 | 不是一等 OpenClaw 工具 |
<Note>
OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
语音和批量转录，使用 xAI 的流式 STT WebSocket 进行实时
语音通话转录，并使用 Responses API 处理模型、搜索和
语音通话转录，并使用 Responses API 进行模型、搜索和
代码执行工具。需要不同 OpenClaw 契约的功能，例如
实时语音会话，在此记录为上游能力，而不是隐藏的插件行为。
实时语音会话，在此作为上游能力记录，而不是隐藏的插件行为。
</Note>
### 快速模式映射
@ -112,9 +114,9 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
### 旧版兼容别名
旧版别名仍会规范化为内置的规范 ID：
旧版别名仍会归一化为规范的内置 id：
| 旧版别名 | 规范 ID |
| 旧版别名 | 规范 id |
| ------------------------- | ------------------------------------- |
| `grok-4-fast-reasoning` | `grok-4-fast` |
| `grok-4-1-fast-reasoning` | `grok-4-1-fast` |
@ -124,8 +126,8 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
## 功能
<AccordionGroup>
<Accordion title="网页搜索">
内置的 `grok` 网页搜索提供商也使用 `XAI_API_KEY`：
<Accordion title="Web 搜索">
内置 `grok` Web 搜索提供商也使用 `XAI_API_KEY`：
```bash
openclaw config set tools.web.search.provider grok
@ -134,22 +136,23 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
</Accordion>
<Accordion title="视频生成">
内置的 `xai` 插件通过共享的
内置 `xai` 插件通过共享的
`video_generate` 工具注册视频生成。
- 默认视频模型：`xai/grok-imagine-video`
- 模式：文本转视频、图像转视频、参考图像生成、远程
视频编辑和远程视频延展
- 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`
视频编辑和远程视频扩展
- 纵横比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`3:2`、`2:3`
- 分辨率：`480P`、`720P`
- 时长：生成/图像转视频为 1-15 秒，使用 `reference_image` 角色时为 1-10 秒，
延展为 2-10 秒
- 参考图像生成：为每张提供的图像将 `imageRoles` 设置为 `reference_image`；
xAI 最多接受 7 张此类图像
- 时长：生成/图像转视频为 1-15 秒，使用
`reference_image` 角色时为 1-10 秒，扩展为 2-10 秒
- 参考图像生成：将每个提供的图像的 `imageRoles` 设置为
`reference_image`；xAI 最多接受 7 张此类图像
<Warning>
不接受本地视频缓冲区。视频编辑/延展输入请使用远程 `http(s)` URL。
图像转视频接受本地图像缓冲区，因为 OpenClaw 可以将它们编码为供 xAI 使用的数据 URL。
不接受本地视频缓冲区。视频编辑/扩展输入请使用远程 `http(s)` URL。
图像转视频接受本地图像缓冲区，因为 OpenClaw 可以将其编码为
xAI 的数据 URL。
</Warning>
要将 xAI 用作默认视频提供商：
@ -167,27 +170,26 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
```
<Note>
参见[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、
提供商选择和故障转移行为。
有关共享工具参数、提供商选择和故障转移行为，请参阅[视频生成](/zh-CN/tools/video-generation)。
</Note>
</Accordion>
<Accordion title="图像生成">
内置的 `xai` 插件通过共享的
内置 `xai` 插件通过共享的
`image_generate` 工具注册图像生成。
- 默认图像模型：`xai/grok-imagine-image`
- 其他模型：`xai/grok-imagine-image-pro`
- 模式：文生图和参考图像编辑
- 模式：文本转图像和参考图像编辑
- 参考输入：一个 `image` 或最多五个 `images`
- 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`
- 纵横比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`
- 分辨率：`1K`、`2K`
- 数量：最多 4 张图像
OpenClaw 会向 xAI 请求 `b64_json` 图像响应，以便生成的媒体可以通过
常规渠道附件路径存储和投递。本地参考图像会转换为 data URL；远程
`http(s)` 参考会原样传递。
OpenClaw 向 xAI 请求 `b64_json` 图像响应，以便生成的媒体可以通过
常规渠道附件路径存储和交付。本地参考图像会转换为数据 URL；远程
`http(s)` 引用会原样传递。
要将 xAI 用作默认图像提供商：
@ -204,24 +206,24 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
```
<Note>
xAI 还记录了 `quality`、`mask`、`user` 以及其他原生比例，
xAI 还记录了 `quality`、`mask`、`user`，以及其他原生比例，
例如 `1:2`、`2:1`、`9:20` 和 `20:9`。OpenClaw 目前只转发
跨提供商共享的图像控制项；不支持的仅原生旋钮会有意不通过
共享的跨提供商图像控制项；不受支持的原生专用旋钮会有意不通过
`image_generate` 暴露。
</Note>
</Accordion>
<Accordion title="文本转语音">
内置的 `xai` 插件通过共享的 `tts`
内置 `xai` 插件通过共享的 `tts`
提供商表面注册文本转语音。
- 语音：`eve`、`ara`、`rex`、`sal`、`leo`、`una`
- 默认语音：`eve`
- 格式：`mp3`、`wav`、`pcm`、`mulaw`、`alaw`
- 语言：BCP-47 代码或 `auto`
- 速度：提供商原生速度覆盖
- 不支持原生 Opus 语音留言格式
- 语速：提供商原生语速覆盖
- 不支持原生 Opus 语音备注格式
要将 xAI 用作默认 TTS 提供商：
@ -241,25 +243,24 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
```
<Note>
OpenClaw 使用 xAI 的批量 `/v1/tts` 端点。xAI 也提供通过 WebSocket
进行的流式 TTS，但 OpenClaw 语音提供商契约目前要求在投递回复前
获得完整的音频缓冲区。
OpenClaw 使用 xAI 的批量 `/v1/tts` 端点。xAI 也通过 WebSocket
提供流式 TTS，但 OpenClaw 语音提供商契约目前要求在交付回复前
获得完整音频缓冲区。
</Note>
</Accordion>
<Accordion title="语音转文本">
内置的 `xai` 插件通过 OpenClaw 的
媒体理解转写表面注册批量语音转文本。
内置 `xai` 插件通过 OpenClaw 的
媒体理解转录表面注册批量语音转文本。
- 默认模型：`grok-stt`
- 端点：xAI REST `/v1/stt`
- 输入路径：multipart 音频文件上传
- 在 OpenClaw 中，只要入站音频转写使用
`tools.media.audio`，就支持该功能，包括 Discord 语音渠道片段和
渠道音频附件
- OpenClaw 中凡是入站音频转录使用 `tools.media.audio` 的地方都支持，
包括 Discord 语音渠道片段和渠道音频附件
要强制将 xAI 用于入站音频转写：
要强制 xAI 用于入站音频转录：
```json5
{
@ -279,22 +280,22 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
}
```
语言可以通过共享音频媒体配置或按调用的转写请求提供。共享的 OpenClaw
表面接受提示提示词，但 xAI REST STT 集成只转发文件、模型和语言，
因为这些可以清晰映射到当前公开的 xAI 端点。
语言可以通过共享音频媒体配置或逐次调用的转录请求提供。共享的 OpenClaw
表面接受提示词提示，但 xAI REST STT 集成只转发文件、模型和
语言，因为这些可以清晰映射到当前公开的 xAI 端点。
</Accordion>
<Accordion title="流式语音转文本">
内置的 `xai` 插件还为实时语音通话音频注册了实时转写提供商。
内置 `xai` 插件还为实时语音通话音频注册了实时转录提供商。
- 端点：xAI WebSocket `wss://api.x.ai/v1/stt`
- 默认编码：`mulaw`
- 默认采样率：`8000`
- 默认端点检测：`800ms`
- 临时转写结果：默认启用
- 临时转录：默认启用
Voice Call 的 Twilio 媒体流会发送 G.711 µ-law 音频帧，因此
Voice Call 的 Twilio 媒体流发送 G.711 µ-law 音频帧，因此
xAI 提供商可以直接转发这些帧，无需转码：
```json5
@ -321,14 +322,14 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
}
```
提供商自有配置位于
Provider 拥有的配置位于
`plugins.entries.voice-call.config.streaming.providers.xai` 下。支持的
键为 `apiKey`、`baseUrl`、`sampleRate`、`encoding`（`pcm`、`mulaw` 或
键名包括 `apiKey`、`baseUrl`、`sampleRate`、`encoding`（`pcm`、`mulaw` 或
`alaw`）、`interimResults`、`endpointingMs` 和 `language`。
<Note>
此流式传输提供商用于语音通话的实时转录路径。
Discord 语音目前会录制短片段，并改用批量
这个流式 provider 用于 Voice Call 的实时转录路径。
Discord 语音目前会录制短片段，并改用批处理
`tools.media.audio` 转录路径。
</Note>
@ -340,14 +341,15 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
配置路径：`plugins.entries.xai.config.xSearch`
| 键 | 类型 | 默认值 | 描述 |
| 键名 | 类型 | 默认值 | 描述 |
| ------------------ | ------- | ------------------ | ------------------------------------ |
| `enabled` | boolean | — | 启用或停用 x_search |
| `model` | string | `grok-4-1-fast` | 用于 x_search 请求的模型 |
| `inlineCitations` | boolean | — | 在结果中包含内联引用 |
| `maxTurns` | number | — | 最大对话轮数 |
| `timeoutSeconds` | number | — | 请求超时时间（秒） |
| `cacheTtlMinutes` | number | — | 缓存生存时间（分钟） |
| `enabled` | boolean | — | 启用或禁用 x_search |
| `model` | string | `grok-4-1-fast` | 用于 x_search 请求的模型 |
| `baseUrl` | string | — | xAI Responses 基础 URL 覆盖值 |
| `inlineCitations` | boolean | — | 在结果中包含内联引用 |
| `maxTurns` | number | — | 最大对话轮数 |
| `timeoutSeconds` | number | — | 请求超时时间（秒） |
| `cacheTtlMinutes` | number | — | 缓存存活时间（分钟） |
```json5
{
@ -358,6 +360,7 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
xSearch: {
enabled: true,
model: "grok-4-1-fast",
baseUrl: "https://api.x.ai/v1",
inlineCitations: true,
},
},
@ -370,16 +373,17 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
</Accordion>
<Accordion title="代码执行配置">
内置 xAI 插件将 `code_execution` 作为 OpenClaw 工具公开，用于在 xAI 的沙箱环境中执行远程代码。
内置 xAI 插件将 `code_execution` 作为 OpenClaw 工具公开，用于在 xAI 的沙箱环境中进行
远程代码执行。
配置路径：`plugins.entries.xai.config.codeExecution`
| 键 | 类型 | 默认值 | 描述 |
| ----------------- | ------- | ------------------ | ---------------------------------------- |
| `enabled` | boolean | `true`（如果密钥可用） | 启用或停用代码执行 |
| `model` | string | `grok-4-1-fast` | 用于代码执行请求的模型 |
| `maxTurns` | number | — | 最大对话轮数 |
| `timeoutSeconds` | number | — | 请求超时时间（秒） |
| 键名 | 类型 | 默认值 | 描述 |
| ----------------- | ------- | ------------------------ | ------------------------------------ |
| `enabled` | boolean | `true`（如果键可用） | 启用或禁用代码执行 |
| `model` | string | `grok-4-1-fast` | 用于代码执行请求的模型 |
| `maxTurns` | number | — | 最大对话轮数 |
| `timeoutSeconds` | number | — | 请求超时时间（秒） |
<Note>
这是远程 xAI 沙箱执行，不是本地 [`exec`](/zh-CN/tools/exec)。
@ -405,20 +409,28 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
</Accordion>
<Accordion title="已知限制">
- 目前身份验证仅支持 API key。OpenClaw 尚无 xAI OAuth 或设备代码流程。
- `grok-4.20-multi-agent-experimental-beta-0304` 不支持普通 xAI 提供商路径，因为它需要与标准 OpenClaw xAI 传输不同的上游 API 表面。
- xAI Realtime 语音尚未注册为 OpenClaw 提供商。它需要与批量 STT 或流式转录不同的双向语音会话契约。
- 在共享 `image_generate` 工具具备对应的跨提供商控制项之前，不会公开 xAI 图像 `quality`、图像 `mask` 以及额外的仅原生宽高比。
- 目前 Auth 仅支持 API key。OpenClaw 尚未提供 xAI OAuth 或设备代码流程。
- `grok-4.20-multi-agent-experimental-beta-0304` 在常规 xAI provider 路径上不受支持，因为它需要的上游 API
表面不同于标准 OpenClaw xAI 传输协议。
- xAI Realtime 语音尚未注册为 OpenClaw provider。它需要一种不同于批处理 STT 或
流式转录的双向语音会话契约。
- xAI 图像 `quality`、图像 `mask` 和额外的仅原生纵横比
在共享 `image_generate` 工具具备相应的跨 provider 控制项之前不会公开。
</Accordion>
<Accordion title="高级说明">
- OpenClaw 会在共享 runner 路径上自动应用 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 插件所有，而不是硬编码到核心模型运行时中。
`agents.defaults.models["xai/<model>"].params.tool_stream` 设为 `false` 可将其禁用。
- 内置 xAI wrapper 会在发送原生 xAI 请求之前移除不受支持的严格工具 schema 标志和
reasoning payload 键。
- `web_search`、`x_search` 和 `code_execution` 会作为 OpenClaw
工具公开。OpenClaw 会在每个工具请求中启用它所需的特定 xAI 内置能力，而不是将所有原生工具附加到每一轮聊天。
- Grok `web_search` 读取 `plugins.entries.xai.config.webSearch.baseUrl`。
`x_search` 读取 `plugins.entries.xai.config.xSearch.baseUrl`，然后
回退到 Grok Web 搜索基础 URL。
- `x_search` 和 `code_execution` 由内置 xAI 插件拥有，
而不是硬编码到核心模型运行时中。
- `code_execution` 是远程 xAI 沙箱执行，不是本地
[`exec`](/zh-CN/tools/exec)。
</Accordion>
@ -426,7 +438,9 @@ OpenClaw 使用 xAI 的 REST 图像/视频/TTS/STT API 进行媒体生成、
## 实时测试
xAI 媒体路径由单元测试和可选择启用的实时套件覆盖。实时命令会先从你的登录 shell 加载密钥，包括 `~/.profile`，然后再探测 `XAI_API_KEY`。
xAI 媒体路径由单元测试和可选择启用的实时测试套件覆盖。实时
命令会先从你的登录 shell（包括 `~/.profile`）加载密钥，然后再
探测 `XAI_API_KEY`。
```bash
pnpm test extensions/xai
@ -434,19 +448,22 @@ OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_TEST_QUIET=1 pnpm test:live -- extensions/xai
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_TEST_QUIET=1 OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS=xai pnpm test:live -- test/image-generation.runtime.live.test.ts
```
提供商专用实时文件会合成普通 TTS、适合电话场景的 PCM TTS，通过 xAI 批量 STT 转录音频，通过 xAI 实时 STT 流式传输同一份 PCM，生成文生图输出，并编辑一张参考图像。共享图像实时文件会通过 OpenClaw 的运行时选择、回退、归一化和媒体附件路径验证同一个 xAI 提供商。
provider 专用实时文件会合成常规 TTS、适合电话语音的 PCM
TTS，通过 xAI 批处理 STT 转录音频，通过 xAI
实时 STT 流式传输同一段 PCM，生成文生图输出，并编辑参考图像。共享图像实时文件会通过 OpenClaw 的
运行时选择、回退、规范化和媒体附件路径验证同一个 xAI provider。
## 相关内容
## 相关
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择 provider、模型引用和故障转移行为。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
共享视频工具参数和 provider 选择。
</Card>
<Card title="所有提供商" href="/zh-CN/providers/index" icon="grid-2">
更广泛的提供商概览。
<Card title="所有 provider" href="/zh-CN/providers/index" icon="grid-2">
更广泛的 provider 概览。
</Card>
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
常见问题和修复方法。

68
docs/zh-CN/tools/gemini-search.md
View File

@ -1,22 +1,22 @@
---
read_when:
- 你希望将 Gemini 用于 `web_search`
- 你需要一个 `GEMINI_API_KEY`
- 你希望使用 Google Search grounding
summary: 通过 Google Search grounding 实现的 Gemini Web 搜索
- 你想使用 Gemini 进行 web_search
- 你需要一个 GEMINI_API_KEY
- 你想要 Google Search grounding
summary: 使用 Google Search 作为依据的 Gemini 网页搜索
title: Gemini 搜索
x-i18n:
generated_at: "2026-04-23T21:08:00Z"
model: gpt-5.4
generated_at: "2026-05-02T02:49:13Z"
model: gpt-5.5
provider: openai
source_hash: 0778ae326e23ea1bb719fdc694b2accc5a6651e08658a695d4d70e20fc5943a4
source_hash: 5e36382dc6a4f9a30f12025cc81bb7ed4999e56a236fc85ee7a37444674bf798
source_path: tools/gemini-search.md
workflow: 15
workflow: 16
---
OpenClaw 支持带有内置
[Google Search grounding](https://ai.google.dev/gemini-api/docs/grounding)
的 Gemini 模型，它会返回由实时 Google 搜索结果支撑、带有引用的 AI 综合答案。
[Google Search 依据增强](https://ai.google.dev/gemini-api/docs/grounding)
的 Gemini 模型，它会返回由实时 Google Search 结果支持并附带引用的 AI 综合生成答案。
## 获取 API 密钥
@ -26,7 +26,7 @@ OpenClaw 支持带有内置
API 密钥。
</Step>
<Step title="存储密钥">
在 Gateway 网关环境中设置 `GEMINI_API_KEY`，或者通过以下方式配置：
在 Gateway 网关环境中设置 `GEMINI_API_KEY`，或通过以下方式配置：
```bash
openclaw configure --section web
@ -44,8 +44,9 @@ OpenClaw 支持带有内置
google: {
config: {
webSearch: {
apiKey: "AIza...", // 如果已设置 GEMINI_API_KEY，则可选
model: "gemini-2.5-flash", // 默认值
apiKey: "AIza...", // optional if GEMINI_API_KEY is set
baseUrl: "https://generativelanguage.googleapis.com/v1beta", // optional proxy/base URL override
model: "gemini-2.5-flash", // default
},
},
},
@ -61,42 +62,47 @@ OpenClaw 支持带有内置
}
```
**环境变量替代方式：** 在 Gateway 网关环境中设置 `GEMINI_API_KEY`。
对于 gateway 安装，请将其放到 `~/.openclaw/.env` 中。
**环境替代方案：**在 Gateway 网关环境中设置 `GEMINI_API_KEY`。
对于 gateway 安装，请将其放入 `~/.openclaw/.env`。
## 工作原理
与返回链接和摘要列表的传统搜索 providers 不同，
Gemini 使用 Google Search grounding 生成带有
内联引用的 AI 综合答案。结果同时包含综合答案和源
与返回链接和摘要列表的传统搜索提供商不同，
Gemini 使用 Google Search 依据增强来生成带有
内联引用的 AI 综合答案。结果同时包含综合生成的答案和来源
URL。
- 来自 Gemini grounding 的引用 URL 会自动从 Google
重定向 URL 解析为直链 URL。
- 重定向解析会在返回最终引用 URL 之前，先通过 SSRF 防护路径（HEAD + 重定向检查 +
http/https 验证）。
- 重定向解析使用严格的 SSRF 默认值，因此指向
私有/内部目标的重定向会被阻止。
- 来自 Gemini 依据增强的引用 URL 会自动从 Google
重定向 URL 解析为直接 URL。
- 重定向解析使用 SSRF 防护路径（HEAD + 重定向检查 +
http/https 验证），然后再返回最终引用 URL。
- 重定向解析使用严格的 SSRF 默认设置，因此会阻止重定向到
私有/内部目标。
## 支持的参数
Gemini 搜索支持 `query`。
出于共享 `web_search` 兼容性，也接受 `count`，但 Gemini grounding
仍然返回一个带引用的综合答案，而不是 N 条结果的
为兼容共享的 `web_search`，会接受 `count`，但 Gemini 依据增强
仍然返回一个带引用的综合生成答案，而不是 N 个结果的
列表。
不支持 provider 专用过滤器，例如 `country`、`language`、`freshness` 和
不支持特定于提供商的过滤器，例如 `country`、`language`、`freshness` 和
`domain_filter`。
## 模型选择
默认模型是 `gemini-2.5-flash`（速度快且性价比高）。任何支持 grounding 的 Gemini
默认模型是 `gemini-2.5-flash`（快速且成本效益高）。任何支持依据增强的 Gemini
模型都可以通过
`plugins.entries.google.config.webSearch.model` 使用。
## Base URL 覆盖
当 Gemini Web 搜索必须通过操作方代理或自定义的 Gemini 兼容端点路由时，设置 `plugins.entries.google.config.webSearch.baseUrl`。普通的 `https://generativelanguage.googleapis.com` 值会规范化为
`https://generativelanguage.googleapis.com/v1beta`；自定义代理路径会在去除末尾斜杠后按提供的形式保留。
## 相关内容
- [Web 搜索概览](/zh-CN/tools/web) —— 所有 providers 与自动检测
- [Brave Search](/zh-CN/tools/brave-search) —— 带摘要的结构化结果
- [Perplexity Search](/zh-CN/tools/perplexity-search) —— 结构化结果 + 内容提取
- [Web Search 概览](/zh-CN/tools/web) -- 所有提供商和自动检测
- [Brave Search](/zh-CN/tools/brave-search) -- 带摘要的结构化结果
- [Perplexity Search](/zh-CN/tools/perplexity-search) -- 结构化结果 + 内容提取

41
docs/zh-CN/tools/grok-search.md
View File

@ -2,31 +2,31 @@
read_when:
- 你想使用 Grok 进行 web_search
- 你需要 XAI_API_KEY 才能进行网页搜索
summary: 通过 xAI 基于网页检索的响应实现 Grok 网页搜索
summary: 通过 xAI 基于 Web 事实的响应进行 Grok Web 搜索
title: Grok 搜索
x-i18n:
generated_at: "2026-05-02T01:59:39Z"
generated_at: "2026-05-02T02:49:05Z"
model: gpt-5.5
provider: openai
source_hash: ab38ee8614ba4bab9a3bf91cb14d4565f1766513594fd2d1a280ff4b2fed1478
source_hash: 7238be2b488ba285c948065f5c1deff21898409aa11bdaa9ec893274d0eadd4a
source_path: tools/grok-search.md
workflow: 16
---
OpenClaw 支持将 Grok 作为 `web_search` 提供商，使用 xAI 基于网页的响应来生成由实时搜索结果和引用支撑的 AI 综合回答。
OpenClaw 支持将 Grok 作为 `web_search` 提供商，使用 xAI 基于网页依据的响应生成由实时搜索结果支持并带有引用的 AI 合成答案。
同一个 `XAI_API_KEY` 也可以为内置的 `x_search` 工具提供支持，用于搜索 X（前身为 Twitter）帖子。如果你将 key 存储在 `plugins.entries.xai.config.webSearch.apiKey` 下，OpenClaw 现在也会将它作为内置 xAI 模型提供商的备用值复用。
同一个 `XAI_API_KEY` 也可以为内置的 `x_search` 工具提供支持，用于 X（原 Twitter）帖子搜索。如果你将密钥存储在 `plugins.entries.xai.config.webSearch.apiKey` 下，OpenClaw 现在也会将它作为内置 xAI 模型提供商的备用密钥复用。
对于帖子级 X 指标，例如转帖、回复、书签或浏览量，优先使用带有确切帖子 URL 或状态 ID 的 `x_search`，而不是宽泛的搜索查询。
对于帖子级 X 指标，例如转发、回复、书签或浏览量，请优先使用带有确切帖子 URL 或 status ID 的 `x_search`，而不是宽泛的搜索查询。
## 新手引导和配置
如果你在以下流程中选择 **Grok**：
如果你在以下过程中选择 **Grok**：
- `openclaw onboard`
- `openclaw configure --section web`
OpenClaw 可以显示一个单独的后续步骤，用同一个 `XAI_API_KEY` 启用 `x_search`。该后续步骤：
OpenClaw 可以显示一个单独的后续步骤，使用同一个 `XAI_API_KEY` 启用 `x_search`。该后续步骤：
- 只会在你为 `web_search` 选择 Grok 后出现
- 不是单独的顶层网页搜索提供商选项
@ -37,10 +37,10 @@ OpenClaw 可以显示一个单独的后续步骤，用同一个 `XAI_API_KEY`
## 获取 API key
<Steps>
<Step title="创建 key">
<Step title="创建密钥">
从 [xAI](https://console.x.ai/) 获取 API key。
</Step>
<Step title="存储 key">
<Step title="存储密钥">
在 Gateway 网关环境中设置 `XAI_API_KEY`，或通过以下命令配置：
```bash
@ -60,6 +60,7 @@ OpenClaw 可以显示一个单独的后续步骤，用同一个 `XAI_API_KEY`
config: {
webSearch: {
apiKey: "xai-...", // optional if XAI_API_KEY is set
baseUrl: "https://api.x.ai/v1", // optional Responses API proxy/base URL override
},
},
},
@ -75,25 +76,29 @@ OpenClaw 可以显示一个单独的后续步骤，用同一个 `XAI_API_KEY`
}
```
**环境替代方案：**在 Gateway 网关环境中设置 `XAI_API_KEY`。
对于 Gateway 网关安装，将它放在 `~/.openclaw/.env` 中。
**环境替代方式：**在 Gateway 网关环境中设置 `XAI_API_KEY`。
对于 Gateway 网关安装，请将它放在 `~/.openclaw/.env` 中。
## 工作原理
Grok 使用 xAI 基于网页的响应来综合带有行内引用的回答，类似于 Gemini 的 Google 搜索 grounding 方法。
Grok 使用 xAI 基于网页依据的响应生成带有内联引用的答案，类似于 Gemini 的 Google Search grounding 方法。
## 支持的参数
Grok 搜索支持 `query`。
`count` 会被接受，以兼容共享的 `web_search`，但 Grok 仍会返回一个带引用的综合回答，而不是 N 条结果列表。
`count` 会被接受，以兼容共享的 `web_search`，但 Grok 仍会返回一个带有引用的合成答案，而不是 N 条结果列表。
目前不支持提供商特定的过滤器。
Grok 使用提供商特定的 60 秒默认超时时间，因为 xAI Responses 基于网页的搜索可能比共享的 `web_search` 默认时间运行更久。设置 `tools.web.search.timeoutSeconds` 可覆盖它。
Grok 使用提供商特定的 60 秒默认超时，因为 xAI Responses 基于网页依据的搜索可能比共享的 `web_search` 默认值运行更久。设置 `tools.web.search.timeoutSeconds` 可以覆盖它。
## Base URL 覆盖
当 Grok 网页搜索应通过操作员代理或 xAI 兼容的 Responses 端点路由时，设置 `plugins.entries.xai.config.webSearch.baseUrl`。OpenClaw 会在去除尾随斜杠后向 `<baseUrl>/responses` 发送请求。除非设置了 `plugins.entries.xai.config.xSearch.baseUrl`，否则 `x_search` 使用同一个 `webSearch.baseUrl` 作为备用值。
## 相关内容
- [网页搜索概览](/zh-CN/tools/web) -- 所有提供商和自动检测
- [网页搜索中的 x_search](/zh-CN/tools/web#x_search) -- 通过 xAI 提供一等 X 搜索
- [Gemini 搜索](/zh-CN/tools/gemini-search) -- 通过 Google grounding 提供 AI 综合回答
- [Web Search 概览](/zh-CN/tools/web) -- 所有提供商和自动检测
- [Web Search 中的 x_search](/zh-CN/tools/web#x_search) -- 通过 xAI 实现的一等 X 搜索
- [Gemini Search](/zh-CN/tools/gemini-search) -- 通过 Google grounding 生成的 AI 合成答案

273
docs/zh-CN/tools/slash-commands.md
View File

@ -3,20 +3,20 @@ read_when:
- 使用或配置聊天命令
- 调试命令路由或权限
sidebarTitle: Slash commands
summary: 斜杠命令：文本与原生、配置和支持的命令
summary: 斜杠命令：文本与原生形式、配置和支持的命令
title: 斜杠命令
x-i18n:
generated_at: "2026-05-01T10:03:13Z"
generated_at: "2026-05-02T02:49:01Z"
model: gpt-5.5
provider: openai
source_hash: cfa4c8e294080e824b15f0b54842718f7913cf6d42b7edd4ca9695c3d4113924
source_hash: 00a00619cc0eff25b81b475eab5b0b3d808bf067e6e004a491a90ec3982149b7
source_path: tools/slash-commands.md
workflow: 16
---
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是别名）。
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。仅主机的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是其别名）。
当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保留在本地：`/acp ...` 始终到达 OpenClaw ACP 命令处理器，并且只要该界面启用了命令处理，`/status` 和 `/unfocus` 就会保留在本地。
当对话或线程绑定到 ACP 会话时，普通后续文本会路由到该 ACP harness。Gateway 网关管理命令仍保留在本地：`/acp ...` 始终到达 OpenClaw ACP 命令处理器；只要该表面的命令处理已启用，`/status` 和 `/unfocus` 也会保留在本地。
有两个相关系统：
@ -27,16 +27,16 @@ x-i18n:
<Accordion title="指令">
`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
- 指令会在模型看到消息之前从消息中移除。
- 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
- 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话，并回复确认信息。
- 指令只会应用于**已授权的发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的 allowlist；否则授权来自渠道 allowlist/配对以及 `commands.useAccessGroups`。未授权的发送者会看到指令被当作普通文本处理。
- 指令会在模型看到消息前从消息中移除。
- 在普通聊天消息（非纯指令消息）中，它们会被视为“行内提示”，并且**不会**持久化会话设置。
- 在纯指令消息（消息只包含指令）中，它们会持久化到会话，并回复确认。
- 指令只会应用于**已授权发送者**。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。未授权发送者的指令会被视为纯文本。
</Accordion>
<Accordion title="内联快捷方式">
仅限 allowlist/已授权的发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
<Accordion title="行内快捷方式">
仅限允许列表内/已授权发送者：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它们会立即运行，在模型看到消息之前被移除，剩余文本继续走正常流程。
它们会立即运行，在模型看到消息前被移除，剩余文本会继续走正常流程。
</Accordion>
</AccordionGroup>
@ -69,19 +69,20 @@ x-i18n:
```
<ParamField path="commands.text" type="boolean" default="true">
在聊天消息中启用 `/...` 解析。在没有原生命令的界面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将它设为 `false`，文本命令仍然有效。
启用聊天消息中的 `/...` 解析。在没有原生命令的表面（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams）上，即使你将此项设置为 `false`，文本命令仍然可用。
</ParamField>
<ParamField path="commands.native" type='boolean | "auto"' default='"auto"'>
注册原生命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（直到你添加斜杠命令）；对没有原生支持的提供商会被忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
注册原生命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生命令的提供商忽略。设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。`false` 会在启动时清除 Discord/Telegram 上先前注册的命令。Slack 命令在 Slack 应用中管理，不会自动移除。
</ParamField>
在 Discord 上，原生命令规范可以包含 `descriptionLocalizations`，OpenClaw 会将其发布为 Discord `description_localizations`，并纳入协调比较。
<ParamField path="commands.nativeSkills" type='boolean | "auto"' default='"auto"'>
在支持时以原生方式注册 **skill** 命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
在支持时以原生方式注册 **Skills** 命令。Auto：对 Discord/Telegram 启用；对 Slack 关闭（Slack 要求为每个 Skills 创建一个斜杠命令）。设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
</ParamField>
<ParamField path="commands.bash" type="boolean" default="false">
启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` allowlist）。
启用 `! <cmd>` 以运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
</ParamField>
<ParamField path="commands.bashForegroundMs" type="number" default="2000">
控制 bash 等待多久后切换到后台模式（`0` 表示立即转到后台）。
控制 bash 在切换到后台模式前等待多久（`0` 表示立即后台运行）。
</ParamField>
<ParamField path="commands.config" type="boolean" default="false">
启用 `/config`（读取/写入 `openclaw.json`）。
@ -90,31 +91,31 @@ x-i18n:
启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
</ParamField>
<ParamField path="commands.plugins" type="boolean" default="false">
启用 `/plugins`（插件发现/Status，以及安装 + 启用/禁用控制）。
启用 `/plugins`（插件发现/Status 以及安装 + 启用/禁用控件）。
</ParamField>
<ParamField path="commands.debug" type="boolean" default="false">
启用 `/debug`（仅运行时覆盖）。
</ParamField>
<ParamField path="commands.restart" type="boolean" default="true">
启用 `/restart` 以及 gateway 网关重启工具操作。
启用 `/restart` 以及 Gateway 网关重启工具操作。
</ParamField>
<ParamField path="commands.ownerAllowFrom" type="string[]">
为仅所有者可用的命令/工具界面设置显式所有者 allowlist。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它与 `commands.allowFrom` 以及私信配对访问是分开的。
为仅所有者命令/工具表面设置显式所有者允许列表。这是可以批准危险操作并运行 `/diagnostics`、`/export-trajectory` 和 `/config` 等命令的人类操作员账号。它独立于 `commands.allowFrom`，也独立于私信配对访问。
</ParamField>
<ParamField path="channels.<channel>.commands.enforceOwnerForCommands" type="boolean" default="false">
按渠道设置：要求仅所有者命令在该界面上必须以**所有者身份**运行。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上持有内部 `operator.admin` scope。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求 —— 仅所有者命令会在该渠道上默认拒绝。如果你希望仅所有者命令只由 `ownerAllowFrom` 和标准命令 allowlist 守卫，请保持关闭。
按渠道设置：要求仅所有者命令必须以**所有者身份**在该表面运行。当为 `true` 时，发送者必须匹配已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），或者在内部消息渠道上拥有内部 `operator.admin` 作用域。渠道 `allowFrom` 中的通配符条目，或空的/未解析的所有者候选列表，**不足以**满足要求——仅所有者命令会在该渠道上默认关闭。如果你希望仅所有者命令只受 `ownerAllowFrom` 和标准命令允许列表保护，请保持此项关闭。
</ParamField>
<ParamField path="commands.ownerDisplay" type='"raw" | "hash"'>
控制所有者 id 在系统提示中的显示方式。
控制所有者 ID 在系统提示中的显示方式。
</ParamField>
<ParamField path="commands.ownerDisplaySecret" type="string">
可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC secret。
可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
</ParamField>
<ParamField path="commands.allowFrom" type="object">
命令授权的按提供商 allowlist。配置后，它就是命令和指令的唯一授权来源（渠道 allowlist/配对和 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；特定提供商键会覆盖它。
用于命令授权的按提供商允许列表。配置后，它就是命令和指令唯一的授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商特定键会覆盖它。
</ParamField>
<ParamField path="commands.useAccessGroups" type="boolean" default="true">
当未设置 `commands.allowFrom` 时，对命令强制执行 allowlist/策略。
在未设置 `commands.allowFrom` 时，对命令强制执行允许列表/策略。
</ParamField>
## 命令列表
@ -122,89 +123,88 @@ x-i18n:
当前事实来源：
- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts`
- 生成的停靠命令来自 `src/auto-reply/commands-registry.data.ts`
- 插件命令来自插件 `registerCommand()` 调用
- 你的 gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的插件
- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
- 插件命令来自插件的 `registerCommand()` 调用
- 你 Gateway 网关上的实际可用性仍取决于配置标志、渠道表面以及已安装/已启用的插件
### 核心内置命令
<AccordionGroup>
<Accordion title="会话和运行">
- `/new [model]` 启动新会话；`/reset` 是重置别名。
- `/reset soft [message]` 保留当前 transcript，丢弃复用的 CLI 后端会话 id，并在原地重新运行启动/系统提示加载。
- `/compact [instructions]` 压缩会话上下文。参见[压缩](/zh-CN/concepts/compaction)。
- `/reset soft [message]` 保留当前转录记录，丢弃复用的 CLI 后端会话 ID，并在原地重新运行启动/系统提示加载。
- `/compact [instructions]` 压缩会话上下文。参见 [Compaction](/zh-CN/concepts/compaction)。
- `/stop` 中止当前运行。
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
- `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和 transcript 时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。
- `/export-trajectory [path]` 请求 exec 批准，然后为当前会话导出 JSONL [轨迹包](/zh-CN/tools/trajectory)。当你需要一个 OpenClaw 会话的提示、工具和转录时间线时使用它。在群聊中，批准提示和导出结果会私下发送给所有者。别名：`/trajectory`。
</Accordion>
<Accordion title="模型和运行控制">
- `/think <level>` 设置 thinking 级别。选项来自活动模型的提供商 profile；常见级别是 `off`、`minimal`、`low`、`medium` 和 `high`，只有受支持的地方才有 `xhigh`、`adaptive`、`max` 等自定义级别，或二元 `on`。别名：`/thinking`、`/t`。
<Accordion title="模型和运行控件">
- `/think <level>` 设置思考级别。选项来自活动模型的提供商配置文件；常见级别包括 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 等自定义级别或二进制 `on` 只在受支持的位置可用。别名：`/thinking`、`/t`。
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
- `/trace on|off` 切换当前会话的插件 trace 输出。
- `/fast [status|on|off]` 显示或设置 fast 模式。
- `/reasoning [on|off|stream]` 切换 reasoning 可见性。别名：`/reason`。
- `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。
- `/fast [status|on|off]` 显示或设置快速模式。
- `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
- `/model [name|#|status]` 显示或设置模型。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出已配置/有可用凭证的提供商，或列出某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。
- `/queue <mode>` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`），以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见[命令队列](/zh-CN/concepts/queue)和 [Steering queue](/zh-CN/concepts/queue-steering)。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出已配置/可用凭证的提供商，或某个提供商的模型；添加 `all` 可浏览该提供商的完整目录。
- `/queue <mode>` 管理队列行为（`steer`、旧版 `queue`、`followup`、`collect`、`steer-backlog`、`interrupt`）以及 `debounce:0.5s cap:25 drop:summarize` 等选项；`/queue default` 或 `/queue reset` 会清除会话覆盖。参见 [命令队列](/zh-CN/concepts/queue) 和 [Steering queue](/zh-CN/concepts/queue-steering)。
</Accordion>
<Accordion title="设备发现和 Status">
- `/help` 显示简短帮助摘要。
- `/commands` 显示生成的命令目录。
- `/tools [compact|verbose]` 显示当前智能体现在可以使用什么。
- `/status` 显示执行/运行时 Status，包括 `Execution`/`Runtime` 标签以及可用时的提供商用量/配额。
- `/diagnostics [note]` 是针对 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 之前请求明确的 exec 批准；不要用允许全部的规则批准诊断。批准后，它会发送一份可粘贴的报告，其中包含本地包路径、manifest 摘要、隐私说明和相关会话 id。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一批准也会将相关 Codex 反馈发送到 OpenAI 服务器，并且完成后的回复会列出 OpenClaw 会话 id、Codex thread id 和 `codex resume <thread-id>` 命令。参见[诊断导出](/zh-CN/gateway/diagnostics)。
- `/tools [compact|verbose]` 显示当前智能体现在可以使用的内容。
- `/status` 显示执行/运行时 Status，包括可用时的 `Execution`/`Runtime` 标签以及提供商用量/配额。
- `/diagnostics [note]` 是 Gateway 网关 bug 和 Codex harness 运行的仅所有者支持报告流程。它每次都会在运行 `openclaw gateway diagnostics export --json` 前请求明确的 exec 批准；不要使用允许所有的规则批准诊断。批准后，它会发送一份可粘贴的报告，其中包含本地包路径、清单摘要、隐私说明和相关会话 ID。在群聊中，批准提示和报告会私下发送给所有者。当活动会话使用 OpenAI Codex harness 时，同一个批准也会将相关 Codex 反馈发送到 OpenAI 服务器，完成后的回复会列出 OpenClaw 会话 ID、Codex 线程 ID 和 `codex resume <thread-id>` 命令。参见 [诊断导出](/zh-CN/gateway/diagnostics)。
- `/crestodian <request>` 从所有者私信运行 Crestodian 设置和修复助手。
- `/tasks` 列出当前会话的活动/近期后台任务。
- `/context [list|detail|json]` 解释上下文如何组装。
- `/whoami` 显示你的发送者 id。别名：`/id`。
- `/tasks` 列出当前会话的活动/最近后台任务。
- `/context [list|detail|json]` 说明上下文如何组装。
- `/whoami` 显示你的发送者 ID。别名：`/id`。
- `/usage off|tokens|full|cost` 控制每条回复的用量页脚，或打印本地成本摘要。
</Accordion>
<Accordion title="Skills、allowlist、批准">
- `/skill <name> [input]` 按名称运行一个 skill。
- `/allowlist [list|add|remove] ...` 管理 allowlist 条目。仅文本。
<Accordion title="Skills、允许列表、批准">
- `/skill <name> [input]` 按名称运行一个 Skills。
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
- `/approve <id> <decision>` 解决 exec 批准提示。
- `/btw <question>` 提出一个旁支问题，不改变未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。
- `/btw <question>` 提出一个旁路问题，而不会更改未来会话上下文。参见 [BTW](/zh-CN/tools/btw)。
</Accordion>
<Accordion title="Subagent 和 ACP">
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的 sub-agent 运行。
<Accordion title="子智能体和 ACP">
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
- `/focus <target>` 将当前 Discord 线程或 Telegram 话题/对话绑定到会话目标。
- `/focus <target>` 将当前 Discord 线程或 Telegram 主题/对话绑定到会话目标。
- `/unfocus` 移除当前绑定。
- `/agents` 列出当前会话的线程绑定智能体。
- `/kill <id|#|all>` 中止一个或所有正在运行的 sub-agent。
- `/steer <id|#> <message>` 向正在运行的 sub-agent 发送 steering。别名：`/tell`。
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
- `/steer <id|#> <message>` 向正在运行的子智能体发送 steering。别名：`/tell`。
</Accordion>
<Accordion title="仅限所有者的写入和管理">
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 检查或变更插件状态。`/plugin` 是别名。写入仅限所有者。需要 `commands.plugins: true`。
- `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限所有者。需要 `commands.debug: true`。
- `/restart` 在启用时重启 OpenClaw。默认：已启用；设置 `commands.restart: false` 可将其禁用。
- `/send on|off|inherit` 设置发送策略。仅限所有者。
<Accordion title="仅所有者写入和管理">
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅所有者可用。需要 `commands.config: true`。
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅所有者可用。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 检查或更改插件状态。`/plugin` 是别名。写入仅所有者可用。需要 `commands.plugins: true`。
- `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅所有者可用。需要 `commands.debug: true`。
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用它。
- `/send on|off|inherit` 设置发送策略。仅所有者可用。
</Accordion>
<Accordion title="语音、TTS、渠道控制">
- `/tts on|off|status|chat|latest|provider|limit|summary|audio|help` 控制 TTS。参见 [TTS](/zh-CN/tools/tts)。
- `/activation mention|always` 设置群组激活模式。
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
- `!poll [sessionId]` 检查后台 bash 作业。
- `!stop [sessionId]` 停止后台 bash 作业。
- `!poll [sessionId]` 检查后台 bash 任务。
- `!stop [sessionId]` 停止后台 bash 任务。
</Accordion>
</AccordionGroup>
### 生成的 dock 命令
Dock 命令会将当前会话的回复路由切换到另一个已链接的
渠道。设置、示例和故障排除请参见 [渠道 docking](/zh-CN/concepts/channel-docking)。
Dock 命令会将当前会话的回复路由切换到另一个已关联的渠道。设置、示例和故障排除见[渠道 dock](/zh-CN/concepts/channel-docking)。
Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
@ -213,23 +213,23 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
- `/dock-slack`（别名：`/dock_slack`）
- `/dock-telegram`（别名：`/dock_telegram`）
在直接聊天中使用 dock 命令，将当前会话的回复路由切换到另一个已链接的渠道。智能体会保留同一个会话上下文，但该会话之后的回复会发送到选定的渠道对端。
在直接聊天中使用 dock 命令，将当前会话的回复路由切换到另一个已关联的渠道。智能体保持相同的会话上下文，但该会话之后的回复会发送到所选的渠道对端。
Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 ID 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未链接到 Discord 对端，该命令会回复设置提示，而不是落入普通聊天。
Dock 命令需要 `session.identityLinks`。来源发送者和目标对端必须位于同一个身份组中，例如 `["telegram:123", "discord:456"]`。如果 id 为 `123` 的 Telegram 用户发送 `/dock_discord`，OpenClaw 会在活动会话上存储 `lastChannel: "discord"` 和 `lastTo: "456"`。如果发送者未关联到 Discord 对端，该命令会回复设置提示，而不是落入普通聊天。
Docking 只会更改活动会话路由。它不会创建渠道账户、授予访问权限、绕过渠道允许列表，也不会把转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的 dock 命令再次切换路由。
Dock 只会更改活动会话路由。它不会创建渠道账号、授予访问权限、绕过渠道允许列表，或将转录历史移动到另一个会话。使用 `/dock-telegram`、`/dock-slack`、`/dock-mattermost` 或另一个生成的 dock 命令再次切换路由。
### 内置插件命令
内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：
内置插件可以添加更多斜杠命令。此仓库中的当前内置命令：
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [配对](/zh-CN/channels/pairing)。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时授权高风险手机节点命令。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见[配对](/zh-CN/channels/pairing)。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时武装高风险手机节点命令。
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
- `/codex status|models|threads|resume|compact|review|diagnostics|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex harness](/zh-CN/plugins/codex-harness)。
- 仅 QQBot 命令：
- 仅 QQBot 的命令：
- `/bot-ping`
- `/bot-version`
- `/bot-help`
@ -238,91 +238,92 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
### 动态 skill 命令
用户可调用的 Skills 也会作为斜杠命令暴露：
用户可调用的 Skills 也会作为斜杠命令公开：
- `/skill <name> [input]` 始终可作为通用入口点使用。
- 当 skill/插件注册时，skills 也可能以 `/prose` 这样的直接命令形式出现。
- `/skill <name> [input]` 始终可用，作为通用入口点。
- 当 skill/插件注册直接命令时，Skills 也可能显示为 `/prose` 这样的直接命令。
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
- 命令规格可以为支持本地化描述的原生界面提供 `descriptionLocalizations`，包括 Discord。
<AccordionGroup>
<Accordion title="参数和解析器说明">
- 命令接受命令和参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- 命令和参数之间可接受可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配，文本会被视为消息正文。
- 如需完整的提供商使用情况明细，请使用 `openclaw status --usage`。
- 要查看完整提供商用量明细，请使用 `openclaw status --usage`。
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
- 在多账户渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账户的 `configWrites`。
- `/usage` 控制每条回复的用量页脚；`/usage cost` 从 OpenClaw 会话日志打印本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可将其禁用。
- 在多账号渠道中，面向配置的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也遵循目标账号的 `configWrites`。
- `/usage` 控制每条回复的用量页脚；`/usage cost` 会从 OpenClaw 会话日志打印本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/归档、npm 包、`git:<repo>` 或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新插件配置，并可能提示重启。
</Accordion>
<Accordion title="渠道特定行为">
- 仅 Discord 原生命令：`/vc join|leave|status` 控制语音渠道（不可作为文本使用）。`join` 需要 guild 和已选择的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- 仅 Discord 的原生命令：`/vc join|leave|status` 控制语音渠道（不能作为文本使用）。`join` 需要一个 guild 和已选择的语音/舞台渠道。需要 `channels.discord.voice` 和原生命令。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）需要启用有效的线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- ACP 命令参考和运行时行为：[ACP 智能体](/zh-CN/tools/acp-agents)。
</Accordion>
<Accordion title="Verbose / trace / fast / reasoning 安全性">
- `/verbose` 用于调试和提供额外可见性；正常使用时保持**关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通 verbose 工具噪声关闭。
- `/fast on|off` 会持久化会话覆盖。使用会话 UI 的 `inherit` 选项清除它，并回退到配置默认值。
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公共 Anthropic 请求（包括发送到 `api.anthropic.com` 的 OAuth 认证流量）会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- `/trace` 比 `/verbose` 范围更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具噪声关闭。
- `/fast on|off` 会持久化会话覆盖。使用会话 UI 的 `inherit` 选项清除它并回退到配置默认值。
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射到 `service_tier=priority`，而直接的公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，会将其映射到 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 相关时仍会显示工具失败摘要，但详细失败文本只会在 `/verbose` 为 `on` 或 `full` 时包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组设置中有风险：它们可能暴露你无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中有风险：它们可能暴露你无意公开的内部推理、工具输出或插件诊断。建议保持关闭，尤其是在群聊中。
</Accordion>
<Accordion title="模型切换">
- `/model` 会立即持久化新的会话模型。
- 如果智能体处于空闲状态，下一次运行会立即使用它。
- 如果已有运行处于活动状态，OpenClaw 会将实时切换标记为待处理，并只会在干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续重试机会或下一次用户回合。
- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这独立于消息渠道救援模式，并且不会授予远程配置权限。
- 如果运行已经活动，OpenClaw 会将实时切换标记为待处理，并且只会在干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到之后的重试机会或下一次用户轮次。
- 在本地 TUI 中，`/crestodian [request]` 会从普通智能体 TUI 返回 Crestodian。这与消息渠道救援模式分开，并且不会授予远程配置权限。
</Accordion>
<Accordion title="快速路径和内联快捷方式">
- **快速路径：** 来自允许列表发送者的仅命令消息会立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自允许列表发送者的仅命令消息会绕过提及要求。
- **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入普通消息时也能工作，并会在模型看到剩余文本前被剥离。
- 示例：`hey /status` 触发 Status 回复，剩余文本继续走普通流程。
- **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。
- **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入普通消息时也能工作，并会在模型看到剩余文本之前被剥离。
- 示例：`hey /status` 触发状态回复，剩余文本继续走普通流程。
- 当前：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
- 未授权的仅命令消息会被静默忽略，内联 `/...` token 会被视为纯文本。
- 未授权的纯命令消息会被静默忽略，内联 `/...` token 会被视为纯文本。
</Accordion>
<Accordion title="Skill 命令和原生参数">
- **Skill 命令：** `user-invocable` Skills 会作为斜杠命令暴露。名称会清理为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。
- **Skill 命令：** `user-invocable` Skills 会作为斜杠命令公开。名称会被规范化为 `a-z0-9_`（最多 32 个字符）；冲突会获得数字后缀（例如 `_2`）。
- `/skill <name> [input]` 按名称运行 skill（当原生命令限制阻止为每个 skill 创建命令时很有用）。
- 默认情况下，skill 命令会作为普通请求转发给模型。
- Skills 可以选择声明 `command-dispatch: tool`，将命令直接路由到工具（确定性，无模型）。
- 示例：`/prose`（OpenProse 插件）— 参见 [OpenProse](/zh-CN/prose)。
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。动态选项会针对目标会话模型解析，因此模型特定选项（例如 `/think` 级别）会跟随该会话的 `/model` 覆盖。
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时使用按钮菜单）。Telegram 和 Slack 在命令支持选择项且你省略参数时显示按钮菜单。动态选择项会根据目标会话模型解析，因此 `/think` 级别等模型特定选项会遵循该会话的 `/model` 覆盖。
</Accordion>
</AccordionGroup>
## `/tools`
`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在此对话中可以使用什么**。
`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体在当前对话中现在可以使用什么**。
- 默认 `/tools` 很紧凑，并针对快速浏览优化。
- 默认 `/tools` 很紧凑，并为快速扫描优化。
- `/tools verbose` 添加简短描述。
- 支持参数的原生命令界面暴露同样的模式开关：`compact|verbose`。
- 支持参数的原生命令界面会公开相同的模式开关：`compact|verbose`。
- 结果限定于会话范围，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
- `/tools` 包含运行时实际可达的工具，包括核心工具、已连接的插件工具和渠道拥有的工具。
- `/tools` 包括运行时实际可达的工具，包括核心工具、已连接插件工具和渠道拥有的工具。
如需编辑配置文件和覆盖，请使用 Control UI Tools 面板或配置/目录界面，而不是将 `/tools` 视为静态目录。
要编辑 profile 和覆盖，请使用 Control UI Tools 面板或配置/catalog 界面，而不是把 `/tools` 当作静态 catalog。
## 用量界面（何处显示什么）
## 用量界面（哪里显示什么）
- **提供商用量/配额**（示例：“Claude 剩余 80%”）在启用用量跟踪时会出现在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口规范化为“剩余百分比”；对于 MiniMax，只返回剩余量的百分比字段会在显示前取反，而 `model_remains` 响应会优先使用聊天模型条目和带模型标签的计划标签。
- **Token/缓存行** 在 `/status` 中可能会在实时会话快照稀疏时回退到最新的转录用量条目。现有非零实时值仍然优先，转录回退还可以恢复活动运行时模型标签，以及在存储总量缺失或较小时恢复更大的面向提示词的总量。
- **执行与运行时：** `/status` 对有效沙箱路径报告 `Execution`，并对实际运行会话的主体报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。
- **每条回复的 token/成本** 由 `/usage off|tokens|full` 控制（追加到普通回复）。
- `/model status` 关注的是**模型/凭证/端点**，不是用量。
- **提供商用量/配额**（示例：“Claude 剩余 80%”）会在启用用量跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口标准化为 `% left`；对于 MiniMax，仅剩余的百分比字段会在显示前反转，`model_remains` 响应优先使用聊天模型条目以及带模型标签的 plan 标签。
- **Token/缓存行**在 `/status` 中可以在实时会话快照稀疏时回退到最新的转录用量条目。现有的非零实时值仍然优先，转录回退还可以恢复活动运行时模型标签，以及在存储总数缺失或更小时恢复更大的面向提示词的总数。
- **执行 vs 运行时：** `/status` 会为有效的沙箱路径报告 `Execution`，并为实际运行会话的一方报告 `Runtime`：`OpenClaw Pi Default`、`OpenAI Codex`、CLI 后端或 ACP 后端。
- **每条回复的 token/成本**由 `/usage off|tokens|full` 控制（追加到普通回复）。
- `/model status` 关注的是**模型/认证/端点**，不是用量。
## 模型选择（`/model`）
`/model` 作为指令实现。
`/model` 实现为 directive。
示例：
@ -337,14 +338,14 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
说明：
- `/model` 和 `/model list` 显示紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开带有提供商和模型下拉菜单以及 Submit 步骤的交互式选择器。
- `/model <#>` 从该选择器中选择（并在可能时优先使用当前提供商）。
- `/model status` 显示详细视图，包括可用时已配置的提供商端点（`baseUrl`）和 API 模式（`api`）。
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型系列 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。
- `/model <#>` 会从该选择器中选择（并在可能时优先使用当前提供商）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，如果可用）。
## Debug 覆盖
## 调试覆盖
`/debug` 允许你设置**仅运行时**的配置覆盖（内存中，不写入磁盘）。仅限所有者使用。默认禁用；使用 `commands.debug: true` 启用。
`/debug` 允许你设置**仅运行时**配置覆盖（存于内存，而非磁盘）。仅限所有者。默认禁用；使用 `commands.debug: true` 启用。
示例：
@ -360,9 +361,9 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
覆盖会立即应用到新的配置读取，但**不会**写入 `openclaw.json`。使用 `/debug reset` 清除所有覆盖并返回磁盘上的配置。
</Note>
## 插件 trace 输出
## 插件跟踪输出
`/trace` 允许你切换**会话范围的插件 trace/debug 行**，而不启用完整详细模式。
`/trace` 允许你切换**会话范围的插件跟踪/调试行**，而无需开启完整详细模式。
示例：
@ -374,16 +375,16 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
注意：
- 不带参数的 `/trace` 会显示当前会话的 trace 状态。
- `/trace on` 为当前会话启用插件 trace 行。
- 不带参数的 `/trace` 会显示当前会话的跟踪状态。
- `/trace on` 会为当前会话启用插件跟踪行。
- `/trace off` 会再次禁用它们。
- 插件 trace 行可以出现在 `/status` 中，也可以在正常的助手回复后作为后续诊断消息出现。
- 插件跟踪行可以出现在 `/status` 中，也可以在普通助手回复后作为后续诊断消息出现。
- `/trace` 不会替代 `/debug`；`/debug` 仍然管理仅运行时的配置覆盖。
- `/trace` 不会替代 `/verbose`；正常的详细工具/Status 输出仍然属于 `/verbose`。
- `/trace` 不会替代 `/verbose`；普通详细工具/Status 输出仍然属于 `/verbose`。
## 配置更新
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者使用。默认禁用；使用 `commands.config: true` 启用。
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限所有者。默认禁用；使用 `commands.config: true` 启用。
示例：
@ -401,7 +402,7 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
## MCP 更新
`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者使用。默认禁用；使用 `commands.mcp: true` 启用。
`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限所有者。默认禁用；使用 `commands.mcp: true` 启用。
示例：
@ -413,7 +414,7 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
```
<Note>
`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。运行时适配器决定哪些传输协议实际可执行。
`/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 所属的项目设置中。运行时适配器决定哪些传输协议实际可执行。
</Note>
## 插件更新
@ -431,8 +432,8 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
```
<Note>
- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的插件发现。
- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。
- `/plugins list` 和 `/plugins show` 会针对当前工作区以及磁盘上的配置执行真实的插件发现。
- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。
- 启用/禁用更改后，请重启 Gateway 网关以应用它们。
</Note>
@ -441,35 +442,35 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
<AccordionGroup>
<Accordion title="每个界面的会话">
- **文本命令**在正常聊天会话中运行（私信共享 `main`，群组有自己的会话）。
- **文本命令**会在普通聊天会话中运行（私信共享 `main`，群组有自己的会话）。
- **原生命令**使用隔离会话：
- Discord：`agent:<agentId>:discord:slash:<userId>`
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位到聊天会话）
- **`/stop`** 定位到活动聊天会话，以便它可以中止当前运行。
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位聊天会话）
- **`/stop`** 会定位到活动聊天会话，因此它可以中止当前运行。
</Accordion>
<Accordion title="Slack 细节">
对于单个 `/openclaw` 风格命令，仍然支持 `channels.slack.slashCommand`。如果启用 `commands.native`，你必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 相同）。Slack 的命令参数菜单以临时 Block Kit 按钮形式发送。
`channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果启用 `commands.native`，你必须为每个内置命令创建一个 Slack slash command（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式发送。
Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
Slack 原生例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然有效。
</Accordion>
</AccordionGroup>
## BTW 附带问题
## BTW 旁路问题
`/btw` 是关于当前会话的快速**附带问题**。
`/btw` 是关于当前会话的快速**旁路问题**。
不同于普通聊天：
与普通聊天不同：
- 它使用当前会话作为背景上下文，
- 它作为单独的**无工具**一次性调用运行，
- 它不会改变未来的会话上下文，
- 它不会写入转录历史，
- 它会作为实时附带结果发送，而不是普通的助手消息。
- 它会作为实时旁路结果发送，而不是普通助手消息。
当你希望在主任务继续进行时获得临时澄清，`/btw` 会很有用。
这使得 `/btw` 在你想要临时澄清，同时让主任务继续进行时很有用。
示例：
@ -477,9 +478,9 @@ Docking 只会更改活动会话路由。它不会创建渠道账户、授予访
/btw what are we doing right now?
```
参见 [BTW 附带问题](/zh-CN/tools/btw) 了解完整行为和客户端 UX 细节。
请参阅 [BTW 旁路问题](/zh-CN/tools/btw)，了解完整行为和客户端 UX 细节。
## 相关
## 相关内容
- [创建 Skills](/zh-CN/tools/creating-skills)
- [Skills](/zh-CN/tools/skills)

269
docs/zh-CN/tools/web.md
View File

@ -1,45 +1,43 @@
---
read_when:
- 你想启用或配置 `web_search`
- 你想启用或配置 `x_search`
- 你想启用或配置 web_search
- 你想启用或配置 x_search
- 你需要选择一个搜索提供商
- 你想了解自动检测和提供商回退机制
- 你想了解自动检测和提供商回退
sidebarTitle: Web Search
summary: '`web_search`、`x_search` 和 `web_fetch` —— 搜索 Web、搜索 X 帖子，或抓取页面内容'
title: Web 搜索
summary: web_search、x_search 和 web_fetch -- 搜索网页、搜索 X 帖文，或获取页面内容
title: 网页搜索
x-i18n:
generated_at: "2026-04-27T06:07:19Z"
model: gpt-5.4
generated_at: "2026-05-02T02:49:54Z"
model: gpt-5.5
provider: openai
source_hash: 9f8233a33f0729c6413eda59c4ebc3338a1e398e8280eb12650197225ef8981e
source_hash: 4de24a2430bbdfb0926dcec9dc3b44cc3a0af07f06ff2926e486168eac3d76d0
source_path: tools/web.md
workflow: 15
workflow: 16
---
`web_search` 工具会使用你配置的提供商搜索 Web 并返回结果。结果会按查询缓存 15 分钟（可配置）。
`web_search` 工具会使用你配置的提供商搜索网页并返回结果。结果会按查询缓存 15 分钟（可配置）。
OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及用于轻量抓取 URL 内容的 `web_fetch`。在当前阶段，`web_fetch` 保持本地执行，而 `web_search` 和 `x_search` 可以在底层使用 xAI Responses。
OpenClaw 还包含用于 X（原 Twitter）帖子的 `x_search`，以及用于轻量 URL 抓取的 `web_fetch`。在此阶段，`web_fetch` 保持本地运行，而 `web_search` 和 `x_search` 底层可以使用 xAI Responses。
<Info>
`web_search` 是一个轻量级 HTTP 工具，不是浏览器自动化。对于
重度依赖 JS 的网站或需要登录的场景，请使用 [Web Browser](/zh-CN/tools/browser)。对于
抓取特定 URL，请使用 [Web Fetch](/zh-CN/tools/web-fetch)。
`web_search` 是一个轻量 HTTP 工具，不是浏览器自动化。对于大量依赖 JS 的站点或登录场景，请使用[网页浏览器](/zh-CN/tools/browser)。要抓取特定 URL，请使用 [Web Fetch](/zh-CN/tools/web-fetch)。
</Info>
## 快速开始
<Steps>
<Step title="选择提供商">
选择一个提供商并完成所需设置。有些提供商不需要密钥，而有些则需要 API key。详情请参见下方各提供商页面。
选择一个提供商，并完成任何必需设置。有些提供商不需要密钥，而其他提供商使用 API key。详情请参阅下面的提供商页面。
</Step>
<Step title="配置">
```bash
openclaw configure --section web
```
这会保存提供商以及所需的凭证。对于基于 API 的提供商，你也可以设置环境变量（例如 `BRAVE_API_KEY`）并跳过此步骤。
这会存储提供商和任何所需凭证。你也可以设置一个环境变量（例如 `BRAVE_API_KEY`），并跳过面向 API 支持提供商的此步骤。
</Step>
<Step title="使用">
现在智能体可以调用 `web_search`：
<Step title="使用它">
智能体现在可以调用 `web_search`：
```javascript
await web_search({ query: "OpenClaw plugin SDK" });
@ -58,72 +56,72 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及
<CardGroup cols={2}>
<Card title="Brave Search" icon="shield" href="/zh-CN/tools/brave-search">
带摘要片段的结构化结果。支持 `llm-context` 模式、国家/语言过滤。提供免费层级。
带摘要的结构化结果。支持 `llm-context` 模式、国家/地区和语言过滤器。提供免费层级。
</Card>
<Card title="DuckDuckGo" icon="bird" href="/zh-CN/tools/duckduckgo-search">
无密钥回退。无需 API key。基于非官方 HTML 集成。
免密钥后备方案。无需 API key。基于非官方 HTML 的集成。
</Card>
<Card title="Exa" icon="brain" href="/zh-CN/tools/exa-search">
神经搜索 + 关键词搜索，并支持内容提取（高亮、文本、摘要）。
带内容提取（高亮、文本、摘要）的神经网络 + 关键词搜索。
</Card>
<Card title="Firecrawl" icon="flame" href="/zh-CN/tools/firecrawl">
结构化结果。最适合与 `firecrawl_search` 和 `firecrawl_scrape` 配合使用，以进行深度提取。
结构化结果。最适合与 `firecrawl_search` 和 `firecrawl_scrape` 搭配用于深度提取。
</Card>
<Card title="Gemini" icon="sparkles" href="/zh-CN/tools/gemini-search">
通过 Google Search grounding 提供带引用的 AI 综合答案。
通过 Google Search grounding 提供带引用的 AI 合成答案。
</Card>
<Card title="Grok" icon="zap" href="/zh-CN/tools/grok-search">
通过 xAI Web grounding 提供带引用的 AI 综合答案。
通过 xAI web grounding 提供带引用的 AI 合成答案。
</Card>
<Card title="Kimi" icon="moon" href="/zh-CN/tools/kimi-search">
通过 Moonshot Web 搜索提供带引用的 AI 综合答案。
通过 Moonshot 网页搜索提供带引用的 AI 合成答案。
</Card>
<Card title="MiniMax Search" icon="globe" href="/zh-CN/tools/minimax-search">
通过 MiniMax Coding Plan 搜索 API 提供结构化结果。
</Card>
<Card title="Ollama Web Search" icon="globe" href="/zh-CN/tools/ollama-search">
通过已登录的本地 Ollama 主机或托管的 Ollama API 进行搜索。
通过已登录的本地 Ollama 主机或托管的 Ollama API 搜索。
</Card>
<Card title="Perplexity" icon="search" href="/zh-CN/tools/perplexity-search">
带内容提取控制和域名过滤的结构化结果。
</Card>
<Card title="SearXNG" icon="server" href="/zh-CN/tools/searxng-search">
自托管元搜索。无需 API key。聚合 Google、Bing、DuckDuckGo 等来源。
自托管元搜索。无需 API key。聚合 Google、Bing、DuckDuckGo 等。
</Card>
<Card title="Tavily" icon="globe" href="/zh-CN/tools/tavily">
带搜索深度、主题过滤的结构化结果，并支持 `tavily_extract` 进行 URL 提取。
带搜索深度、主题过滤和用于 URL 提取的 `tavily_extract` 的结构化结果。
</Card>
</CardGroup>
### 提供商对比
| 提供商 | 结果样式 | 过滤器 | API key |
| 提供商 | 结果风格 | 过滤器 | API key |
| ----------------------------------------- | -------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------- |
| [Brave](/zh-CN/tools/brave-search) | 结构化摘要片段 | 国家、语言、时间、`llm-context` 模式 | `BRAVE_API_KEY` |
| [DuckDuckGo](/zh-CN/tools/duckduckgo-search) | 结构化摘要片段 | -- | 无（免密钥） |
| [Exa](/zh-CN/tools/exa-search) | 结构化 + 提取内容 | 神经/关键词模式、日期、内容提取 | `EXA_API_KEY` |
| [Firecrawl](/zh-CN/tools/firecrawl) | 结构化摘要片段 | 通过 `firecrawl_search` 工具 | `FIRECRAWL_API_KEY` |
| [Gemini](/zh-CN/tools/gemini-search) | AI 综合答案 + 引用 | -- | `GEMINI_API_KEY` |
| [Grok](/zh-CN/tools/grok-search) | AI 综合答案 + 引用 | -- | `XAI_API_KEY` |
| [Kimi](/zh-CN/tools/kimi-search) | AI 综合答案 + 引用 | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| [MiniMax Search](/zh-CN/tools/minimax-search) | 结构化摘要片段 | 区域（`global` / `cn`） | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` |
| [Ollama Web Search](/zh-CN/tools/ollama-search) | 结构化摘要片段 | -- | 已登录的本地主机无需；直接使用 `https://ollama.com` 搜索时需 `OLLAMA_API_KEY` |
| [Perplexity](/zh-CN/tools/perplexity-search) | 结构化摘要片段 | 国家、语言、时间、域名、内容限制 | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
| [SearXNG](/zh-CN/tools/searxng-search) | 结构化摘要片段 | 分类、语言 | 无（自托管） |
| [Tavily](/zh-CN/tools/tavily) | 结构化摘要片段 | 通过 `tavily_search` 工具 | `TAVILY_API_KEY` |
| [Brave](/zh-CN/tools/brave-search) | 结构化摘要 | 国家/地区、语言、时间、`llm-context` 模式 | `BRAVE_API_KEY` |
| [DuckDuckGo](/zh-CN/tools/duckduckgo-search) | 结构化摘要 | -- | 无（免密钥） |
| [Exa](/zh-CN/tools/exa-search) | 结构化 + 已提取内容 | 神经网络/关键词模式、日期、内容提取 | `EXA_API_KEY` |
| [Firecrawl](/zh-CN/tools/firecrawl) | 结构化摘要 | 通过 `firecrawl_search` 工具 | `FIRECRAWL_API_KEY` |
| [Gemini](/zh-CN/tools/gemini-search) | AI 合成 + 引用 | -- | `GEMINI_API_KEY` |
| [Grok](/zh-CN/tools/grok-search) | AI 合成 + 引用 | -- | `XAI_API_KEY` |
| [Kimi](/zh-CN/tools/kimi-search) | AI 合成 + 引用 | -- | `KIMI_API_KEY` / `MOONSHOT_API_KEY` |
| [MiniMax Search](/zh-CN/tools/minimax-search) | 结构化摘要 | 地区（`global` / `cn`） | `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` |
| [Ollama Web Search](/zh-CN/tools/ollama-search) | 结构化摘要 | -- | 已登录的本地主机无需；直接 `https://ollama.com` 搜索使用 `OLLAMA_API_KEY` |
| [Perplexity](/zh-CN/tools/perplexity-search) | 结构化摘要 | 国家/地区、语言、时间、域名、内容限制 | `PERPLEXITY_API_KEY` / `OPENROUTER_API_KEY` |
| [SearXNG](/zh-CN/tools/searxng-search) | 结构化摘要 | 类别、语言 | 无（自托管） |
| [Tavily](/zh-CN/tools/tavily) | 结构化摘要 | 通过 `tavily_search` 工具 | `TAVILY_API_KEY` |
## 自动检测
## 原生 OpenAI Web 搜索
## 原生 OpenAI 网页搜索
当启用了 OpenClaw Web 搜索且未固定托管提供商时，直接的 OpenAI Responses 模型会自动使用 OpenAI 托管的 `web_search` 工具。这是内置 OpenAI 插件中的提供商自有行为，仅适用于原生 OpenAI API 流量，不适用于 OpenAI 兼容代理 base URL 或 Azure 路由。将 `tools.web.search.provider` 设置为其他提供商（例如 `brave`），可让 OpenAI 模型继续使用托管的 `web_search` 工具；将 `tools.web.search.enabled: false` 则会同时禁用托管搜索和原生 OpenAI 搜索。
当 OpenClaw 网页搜索已启用且未固定托管提供商时，直接 OpenAI Responses 模型会自动使用 OpenAI 托管的 `web_search` 工具。这是内置 OpenAI 插件中由提供商拥有的行为，并且只适用于原生 OpenAI API 流量，不适用于 OpenAI 兼容代理 base URL 或 Azure 路由。将 `tools.web.search.provider` 设置为另一个提供商（例如 `brave`），即可为 OpenAI 模型保留托管的 `web_search` 工具；或设置 `tools.web.search.enabled: false` 以同时禁用托管搜索和原生 OpenAI 搜索。
## 原生 Codex Web 搜索
## 原生 Codex 网页搜索
支持 Codex 的模型可以选择使用提供商原生的 Responses `web_search` 工具，而不是 OpenClaw 托管的 `web_search` 函数。
支持 Codex 的模型可以选择使用提供商原生 Responses `web_search` 工具，而不是 OpenClaw 的托管 `web_search` 函数。
- 在 `tools.web.search.openaiCodex` 下配置
- 它仅对支持 Codex 的模型生效（`openai-codex/*` 或使用 `api: "openai-codex-responses"` 的提供商）
- 在 `tools.web.search.openaiCodex` 下配置它
- 它只会为支持 Codex 的模型激活（`openai-codex/*` 或使用 `api: "openai-codex-responses"` 的提供商）
- 托管的 `web_search` 仍适用于非 Codex 模型
- `mode: "cached"` 是默认且推荐的设置
- `tools.web.search.enabled: false` 会同时禁用托管搜索和原生搜索
@ -151,15 +149,15 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及
}
```
如果启用了原生 Codex 搜索，但当前模型并不支持 Codex，OpenClaw 会保留正常的托管 `web_search` 行为。
如果原生 Codex 搜索已启用，但当前模型不支持 Codex，OpenClaw 会保持普通托管 `web_search` 行为。
## 设置 Web 搜索
## 设置网页搜索
文档和设置流程中的提供商列表按字母顺序排列。自动检测使用单独的优先级顺序。
如果未设置 `provider`，OpenClaw 会按以下顺序检查提供商，并使用第一个已就绪的提供商：
优先检查基于 API 的提供商：
首先是 API 支持的提供商：
1. **Brave** -- `BRAVE_API_KEY` 或 `plugins.entries.brave.config.webSearch.apiKey`（顺序 10）
2. **MiniMax Search** -- `MINIMAX_CODE_PLAN_KEY` / `MINIMAX_CODING_API_KEY` 或 `plugins.entries.minimax.config.webSearch.apiKey`（顺序 15）
@ -171,21 +169,16 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及
8. **Exa** -- `EXA_API_KEY` 或 `plugins.entries.exa.config.webSearch.apiKey`（顺序 65）
9. **Tavily** -- `TAVILY_API_KEY` 或 `plugins.entries.tavily.config.webSearch.apiKey`（顺序 70）
然后是免密钥回退：
之后是免密钥后备方案：
10. **DuckDuckGo** -- 无需账户或 API key 的免密钥 HTML 回退（顺序 100）
11. **Ollama Web 搜索** -- 当你配置的本地 Ollama 主机可访问且已通过 `ollama signin` 登录时，可作为免密钥回退；如果主机需要，也可以复用 Ollama provider 的 bearer 认证；在配置了 `OLLAMA_API_KEY` 时，也可以直接调用 `https://ollama.com` 搜索（顺序 110）
10. **DuckDuckGo** -- 无需账户或 API key 的免密钥 HTML 后备方案（顺序 100）
11. **Ollama Web Search** -- 当你配置的本地 Ollama 主机可访问并通过 `ollama signin` 登录时，通过该主机提供免密钥后备方案；当主机需要时可复用 Ollama 提供商 bearer auth，并且在配置了 `OLLAMA_API_KEY` 时可调用直接 `https://ollama.com` 搜索（顺序 110）
12. **SearXNG** -- `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`（顺序 200）
如果未检测到任何提供商，它会回退到 Brave（你会收到缺少密钥的错误提示，要求你进行配置）。
如果未检测到提供商，它会回退到 Brave（你会收到缺少密钥的错误，提示你配置一个）。
<Note>
所有提供商密钥字段都支持 SecretRef 对象。位于
`plugins.entries.<plugin>.config.webSearch.apiKey` 下的插件作用域 SecretRef
可用于内置的基于 API 的 Web 搜索提供商，包括 Brave、Exa、Firecrawl、
Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily，
无论该提供商是通过 `tools.web.search.provider` 显式选择，
还是通过自动检测选中。在自动检测模式下，OpenClaw 只会解析已选提供商的密钥——未选中的 SecretRef 保持未激活，因此你可以同时配置多个提供商，而无需为未使用的提供商支付解析成本。
所有提供商密钥字段都支持 SecretRef 对象。对于内置的 API 支持网页搜索提供商，`plugins.entries.<plugin>.config.webSearch.apiKey` 下的插件作用域 SecretRef 会被解析，包括 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax、Perplexity 和 Tavily，无论该提供商是通过 `tools.web.search.provider` 显式选择，还是通过自动检测选中。在自动检测模式下，OpenClaw 只解析所选提供商密钥 -- 未选中的 SecretRef 保持非活跃状态，因此你可以配置多个提供商，而无需为未使用的提供商支付解析成本。
</Note>
## 配置
@ -195,8 +188,8 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及
tools: {
web: {
search: {
enabled: true, // 默认：true
provider: "brave", // 或省略以使用自动检测
enabled: true, // default: true
provider: "brave", // or omit for auto-detection
maxResults: 5,
timeoutSeconds: 30,
cacheTtlMinutes: 15,
@ -206,30 +199,28 @@ OpenClaw 还包含用于搜索 X（原 Twitter）帖子的 `x_search`，以及
}
```
提供商特定配置（API key、base URL、模式）位于
`plugins.entries.<plugin>.config.webSearch.*` 下。示例请参见各提供商页面。
提供商特定配置（API key、base URL、模式）位于 `plugins.entries.<plugin>.config.webSearch.*` 下。示例请参阅提供商页面。
`web_fetch` 的回退提供商选择是独立的：
`web_fetch` 后备提供商选择是独立的：
- 通过 `tools.web.fetch.provider` 选择
- 或省略该字段，让 OpenClaw 从可用凭证中自动检测第一个已就绪的 web-fetch 提供商
- 当前内置的 web-fetch 提供商是 Firecrawl，配置位于
`plugins.entries.firecrawl.config.webFetch.*`
- 使用 `tools.web.fetch.provider` 选择它
- 或省略该字段，让 OpenClaw 根据可用凭证自动检测第一个已就绪的 web-fetch 提供商
- 目前内置的 web-fetch 提供商是 Firecrawl，配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下
当你在 `openclaw onboard` 或
`openclaw configure --section web` 中选择 **Kimi** 时，OpenClaw 还可以询问：
当你在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 **Kimi** 时，OpenClaw 还可以询问：
- Moonshot API 区域（`https://api.moonshot.ai/v1` 或 `https://api.moonshot.cn/v1`）
- 默认 Kimi Web 搜索模型（默认是 `kimi-k2.6`）
- 默认 Kimi 网页搜索模型（默认值为 `kimi-k2.6`）
对于 `x_search`，请配置 `plugins.entries.xai.config.xSearch.*`。它使用与 Grok Web 搜索相同的 `XAI_API_KEY` 回退。
旧版 `tools.web.x_search.*` 配置可通过 `openclaw doctor --fix` 自动迁移。
当你在 `openclaw onboard` 或 `openclaw configure --section web` 中选择 Grok 时，
OpenClaw 还可以使用同一个密钥提供可选的 `x_search` 设置。
这是 Grok 路径中的一个单独后续步骤，不是单独的顶级
Web 搜索提供商选项。如果你选择了其他提供商，OpenClaw 不会显示 `x_search` 提示。
对于 `x_search`，配置 `plugins.entries.xai.config.xSearch.*`。它使用与 Grok web 搜索相同的 `XAI_API_KEY` 回退。
旧版 `tools.web.x_search.*` 配置会由 `openclaw doctor --fix` 自动迁移。
当你在 `openclaw onboard` 或 `openclaw configure --section web` 期间选择 Grok 时，
OpenClaw 也可以使用同一个密钥提供可选的 `x_search` 设置。
这是 Grok 路径中的一个独立后续步骤，不是一个独立的顶层
web 搜索提供商选项。如果你选择其他提供商，OpenClaw 不会
显示 `x_search` 提示。
### 存储 API key
### 存储 API 密钥
<Tabs>
<Tab title="配置文件">
@ -253,61 +244,62 @@ Web 搜索提供商选项。如果你选择了其他提供商，OpenClaw 不会
</Tab>
<Tab title="环境变量">
在 Gateway 网关 进程环境中设置提供商环境变量：
在 Gateway 网关进程环境中设置提供商环境变量：
```bash
export BRAVE_API_KEY="YOUR_KEY"
```
对于 Gateway 网关 安装，请将其放在 `~/.openclaw/.env` 中。
请参见 [环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。
对于 Gateway 网关安装，请将它放在 `~/.openclaw/.env` 中。
参见[环境变量](/zh-CN/help/faq#env-vars-and-env-loading)。
</Tab>
</Tabs>
## 工具参数
| 参数 | 说明 |
| 参数 | 描述 |
| --------------------- | ----------------------------------------------------- |
| `query` | 搜索查询（必填） |
| `count` | 返回结果数（1-10，默认：5） |
| `country` | 2 位 ISO 国家代码（例如 `"US"`、`"DE"`） |
| `language` | ISO 639-1 语言代码（例如 `"en"`、`"de"`） |
| `search_lang` | 搜索语言代码（仅 Brave） |
| `freshness` | 时间过滤：`day`、`week`、`month` 或 `year` |
| `date_after` | 返回此日期之后的结果（YYYY-MM-DD） |
| `date_before` | 返回此日期之前的结果（YYYY-MM-DD） |
| `ui_lang` | UI 语言代码（仅 Brave） |
| `domain_filter` | 域名 allowlist/denylist 数组（仅 Perplexity） |
| `max_tokens` | 总内容预算，默认 25000（仅 Perplexity） |
| `max_tokens_per_page` | 每页 token 上限，默认 2048（仅 Perplexity） |
| `query` | 搜索查询（必填） |
| `count` | 要返回的结果数（1-10，默认值：5） |
| `country` | 2 字母 ISO 国家代码（例如 "US"、"DE"） |
| `language` | ISO 639-1 语言代码（例如 "en"、"de"） |
| `search_lang` | 搜索语言代码（仅 Brave） |
| `freshness` | 时间过滤器：`day`、`week`、`month` 或 `year` |
| `date_after` | 此日期之后的结果（YYYY-MM-DD） |
| `date_before` | 此日期之前的结果（YYYY-MM-DD） |
| `ui_lang` | UI 语言代码（仅 Brave） |
| `domain_filter` | 域名允许列表/拒绝列表数组（仅 Perplexity） |
| `max_tokens` | 总内容预算，默认值 25000（仅 Perplexity） |
| `max_tokens_per_page` | 每页 token 限制，默认值 2048（仅 Perplexity） |
<Warning>
并非所有参数都适用于所有提供商。Brave 的 `llm-context` 模式
不接受 `ui_lang`、`freshness`、`date_after` 和 `date_before`。
Gemini、Grok 和 Kimi 会返回一个带引用的综合答案。
它们接受 `count` 以兼容共享工具，但这不会改变
grounding 答案的形状。
当你使用 Sonar/OpenRouter
兼容路径（`plugins.entries.perplexity.config.webSearch.baseUrl` /
`model` 或 `OPENROUTER_API_KEY`）时，Perplexity 的行为也是如此。
SearXNG 仅对受信任的私有网络或 loopback 主机接受 `http://`；
公开的 SearXNG 端点必须使用 `https://`。
Firecrawl 和 Tavily 仅通过 `web_search`
支持 `query` 和 `count`——如需高级选项，请使用它们各自的专用工具。
并非所有参数都适用于所有提供商。Brave `llm-context` 模式
会拒绝 `ui_lang`、`freshness`、`date_after` 和 `date_before`。
Gemini、Grok 和 Kimi 会返回一个带引用的合成答案。它们
接受 `count` 以兼容共享工具，但它不会改变有依据答案的形态。
当你使用 Sonar/OpenRouter 兼容路径（`plugins.entries.perplexity.config.webSearch.baseUrl` /
`model` 或 `OPENROUTER_API_KEY`）时，Perplexity 的行为相同。
SearXNG 仅对受信任的专用网络或 loopback 主机接受 `http://`；
公共 SearXNG 端点必须使用 `https://`。
Firecrawl 和 Tavily 通过 `web_search` 仅支持 `query` 和 `count`
-- 如需高级选项，请使用它们的专用工具。
</Warning>
## x_search
`x_search` 使用 xAI 查询 X（原 Twitter）帖子，并返回
带引用的 AI 综合答案。它接受自然语言查询和
可选的结构化过滤器。OpenClaw 仅会在服务此工具调用的请求上启用内置 xAI `x_search`
带引用的 AI 合成答案。它接受自然语言查询和
可选的结构化过滤器。OpenClaw 只会在服务此工具调用的请求中启用内置 xAI `x_search`
工具。
<Note>
xAI 文档说明 `x_search` 支持关键词搜索、语义搜索、用户
搜索和线程抓取。对于单条帖子的互动统计数据，例如转发、回复、收藏或浏览量，请优先对确切帖子 URL
或状态 ID 进行定向查找。广泛的关键词搜索可能找到正确的帖子，但返回的单帖元数据会不够完整。一个好的模式是：先定位帖子，然后对该确切帖子运行第二次 `x_search` 查询。
xAI 将 `x_search` 记录为支持关键词搜索、语义搜索、用户
搜索和线程获取。对于转发、回复、书签或浏览量等单帖互动统计，
请优先对精确帖子 URL 或状态 ID 进行定向查找。
宽泛的关键词搜索可能找到正确帖子，但返回的单帖元数据可能不够
完整。一个好的模式是：先定位帖子，然后
运行第二次聚焦该精确帖子的 `x_search` 查询。
</Note>
### x_search 配置
@ -321,13 +313,15 @@ Web 搜索提供商选项。如果你选择了其他提供商，OpenClaw 不会
xSearch: {
enabled: true,
model: "grok-4-1-fast-non-reasoning",
baseUrl: "https://api.x.ai/v1", // optional, overrides webSearch.baseUrl
inlineCitations: false,
maxTurns: 2,
timeoutSeconds: 30,
cacheTtlMinutes: 15,
},
webSearch: {
apiKey: "xai-...", // 如果已设置 XAI_API_KEY，则可选
apiKey: "xai-...", // optional if XAI_API_KEY is set
baseUrl: "https://api.x.ai/v1", // optional shared xAI Responses base URL
},
},
},
@ -336,17 +330,22 @@ Web 搜索提供商选项。如果你选择了其他提供商，OpenClaw 不会
}
```
当设置了 `plugins.entries.xai.config.xSearch.baseUrl` 时，
`x_search` 会发布到 `<baseUrl>/responses`。如果省略该字段，
它会回退到 `plugins.entries.xai.config.webSearch.baseUrl`，然后是
旧版 `tools.web.search.grok.baseUrl`，最后是公共 xAI 端点。
### x_search 参数
| 参数 | 说明 |
| ---------------------------- | ------------------------------------------------------ |
| `query` | 搜索查询（必填） |
| `allowed_x_handles` | 将结果限制为特定 X 账号 |
| `excluded_x_handles` | 排除特定 X 账号 |
| `from_date` | 仅包含该日期及之后的帖子（YYYY-MM-DD） |
| `to_date` | 仅包含该日期及之前的帖子（YYYY-MM-DD） |
| `enable_image_understanding` | 允许 xAI 检查匹配帖子附带的图片 |
| `enable_video_understanding` | 允许 xAI 检查匹配帖子附带的视频 |
| 参数 | 描述 |
| ---------------------------- | ----------------------------------------------------- |
| `query` | 搜索查询（必填） |
| `allowed_x_handles` | 将结果限制为特定 X handle |
| `excluded_x_handles` | 排除特定 X handle |
| `from_date` | 仅包含此日期当天或之后的帖子（YYYY-MM-DD） |
| `to_date` | 仅包含此日期当天或之前的帖子（YYYY-MM-DD） |
| `enable_image_understanding` | 让 xAI 检查匹配帖子附带的图片 |
| `enable_video_understanding` | 让 xAI 检查匹配帖子附带的视频 |
### x_search 示例
@ -359,7 +358,7 @@ await x_search({
```
```javascript
// 单帖统计：尽可能使用确切的状态 URL 或状态 ID
// Per-post stats: use the exact status URL or status ID when possible
await x_search({
query: "https://x.com/huntharo/status/1905678901234567890",
});
@ -368,45 +367,45 @@ await x_search({
## 示例
```javascript
// 基本搜索
// Basic search
await web_search({ query: "OpenClaw plugin SDK" });
// 德语定向搜索
// German-specific search
await web_search({ query: "TV online schauen", country: "DE", language: "de" });
// 最近结果（过去一周）
// Recent results (past week)
await web_search({ query: "AI developments", freshness: "week" });
// 日期范围
// Date range
await web_search({
query: "climate research",
date_after: "2024-01-01",
date_before: "2024-06-30",
});
// 域名过滤（仅 Perplexity）
// Domain filtering (Perplexity only)
await web_search({
query: "product reviews",
domain_filter: ["-reddit.com", "-pinterest.com"],
});
```
## 工具配置档
## 工具配置文件
如果你使用工具配置档或 allowlist，请添加 `web_search`、`x_search` 或 `group:web`：
如果你使用工具配置文件或允许列表，请添加 `web_search`、`x_search` 或 `group:web`：
```json5
{
tools: {
allow: ["web_search", "x_search"],
// 或：allow: ["group:web"] （包含 web_search、x_search 和 web_fetch）
// or: allow: ["group:web"] (includes web_search, x_search, and web_fetch)
},
}
```
## 相关
## 相关内容
- [Web Fetch](/zh-CN/tools/web-fetch) -- 抓取 URL 并提取可读内容
- [Web Browser](/zh-CN/tools/browser) -- 面向重度 JS 网站的完整浏览器自动化
- [Web Fetch](/zh-CN/tools/web-fetch) -- 获取 URL 并提取可读内容
- [Web Browser](/zh-CN/tools/browser) -- 面向 JS 密集型站点的完整浏览器自动化
- [Grok Search](/zh-CN/tools/grok-search) -- 将 Grok 用作 `web_search` 提供商
- [Ollama Web Search](/zh-CN/tools/ollama-search) -- 通过你的 Ollama 主机进行免密钥 Web 搜索
- [Ollama Web Search](/zh-CN/tools/ollama-search) -- 通过你的 Ollama 主机进行免密钥 web 搜索