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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-06 01:07:18 +00:00
parent 4e1b5f9389
commit 14bf2cc1d5
3 changed files with 147 additions and 158 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

53
docs/zh-CN/providers/comfy.md
View File

@ -1,42 +1,41 @@
---
read_when:
- 你想在 OpenClaw 中使用本地 ComfyUI 工作流
- 你想使用 Comfy Cloud 进行图像、视频或音乐工作流
- 你想将 Comfy Cloud 与图像、视频或音乐工作流一起使用
- 你需要内置 comfy 插件的配置键名
summary: OpenClaw 中 ComfyUI 工作流的图像、视频和音乐生成设置
title: ComfyUI
x-i18n:
generated_at: "2026-04-06T00:47:14Z"
generated_at: "2026-04-06T01:07:04Z"
model: gpt-5.4
provider: openai
source_hash: b15d826622787bfc5fec057007495145366c88e36100e7b4923ef581d801e2a3
source_hash: e645f32efdffdf4cd498684f1924bb953a014d3656b48f4b503d64e38c61ba9c
source_path: providers/comfy.md
workflow: 15
---
# ComfyUI
OpenClaw 内置了 `comfy` 插件，用于运行由工作流驱动的 ComfyUI。
OpenClaw 内置了一个 `comfy` 插件，用于执行由工作流驱动的 ComfyUI 运行。
- 提供商：`comfy`
- 模型：`comfy/workflow`
- 共享接口：`image_generate`、`video_generate`
- 插件工具：`music_generate`
- 凭证：本地 ComfyUI 不需要；Comfy Cloud 使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`
- API：ComfyUI `/prompt` / `/history` / `/view` 和 Comfy Cloud `/api/*`
- 共享接口：`image_generate`、`video_generate`、`music_generate`
- 凭证：本地 ComfyUI 无需凭证；Comfy Cloud 使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`
- API：ComfyUI `/prompt` / `/history` / `/view` 以及 Comfy Cloud `/api/*`
## 支持内容
- 通过工作流 JSON 生成图像
- 使用 1 张上传的参考图像编辑图像
- 通过工作流 JSON 生成视频
- 使用 1 张上传的参考图像生成视频
- 通过内置的 `music_generate` 工具生成音乐或音频
- 从已配置的节点或所有匹配的输出节点下载输出内容
- 基于工作流 JSON 的图像生成
- 使用 1 张上传参考图像进行图像编辑
- 基于工作流 JSON 的视频生成
- 使用 1 张上传参考图像进行视频生成
- 通过共享 `music_generate` 工具进行音乐或音频生成
- 从已配置节点或所有匹配的输出节点下载输出内容
该内置插件由工作流驱动，因此 OpenClaw 不会尝试将通用的
`size`、`aspectRatio`、`resolution`、`durationSeconds` 或 TTS 风格的控制项
映射到你的工作流图中。
这个内置插件由工作流驱动，因此 OpenClaw 不会尝试将通用的
`size`、`aspectRatio`、`resolution`、`durationSeconds` 或类 TTS 控制
映射到你的图中。
## 配置布局
@ -73,11 +72,11 @@ Comfy 支持共享的顶层连接设置，以及按能力划分的工作流配
共享键名：
- `mode`：`local` 或 `cloud`
- `baseUrl`：本地模式默认是 `http://127.0.0.1:8188`，云模式默认是 `https://cloud.comfy.org`
- `baseUrl`：本地模式默认值为 `http://127.0.0.1:8188`，云模式默认值为 `https://cloud.comfy.org`
- `apiKey`：可选的内联密钥，可替代环境变量
- `allowPrivateNetwork`：在云模式下允许使用私有网络 / 局域网 `baseUrl`
- `allowPrivateNetwork`：在云模式下允许使用私有网络 / LAN `baseUrl`
位于 `image`、`video` 或 `music` 下的各能力键名：
位于 `image`、`video` 或 `music` 下的按能力配置键名：
- `workflow` 或 `workflowPath`：必填
- `promptNodeId`：必填
@ -163,13 +162,13 @@ OpenClaw 会将这种旧版结构视为图像工作流配置。
}
```
Comfy 视频工作流目前支持通过已配置的工作流图进行文生视频和图生视频。
Comfy 视频工作流目前通过已配置图支持文生视频和图生视频。
OpenClaw 不会将输入视频传入 Comfy 工作流。
## 音乐工作流
该内置插件注册了一个 `music_generate` 工具，用于生成由工作流定义的音频
或音乐输出：
这个内置插件为工作流定义的音频或音乐输出注册了一个音乐生成提供商，
并通过共享 `music_generate` 工具对外提供：
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
@ -179,7 +178,7 @@ OpenClaw 不会将输入视频传入 Comfy 工作流。
## Comfy Cloud
使用 `mode: "cloud"`，再配合以下任意一种方式：
使用 `mode: "cloud"`，并搭配以下任一方式：
- `COMFY_API_KEY`
- `COMFY_CLOUD_API_KEY`
@ -189,18 +188,18 @@ OpenClaw 不会将输入视频传入 Comfy 工作流。
## 实时测试
该内置插件提供了可选启用的实时覆盖测试：
这个内置插件提供了可选启用的实时覆盖测试：
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
如果未配置对应的 Comfy 工作流配置段，实时测试会跳过单独的图像、视频或音乐用例。
除非已配置对应的 Comfy 工作流配置段，否则实时测试会跳过单独的图像、视频或音乐用例。
## 相关内容
- [图像生成](/zh-CN/tools/image-generation)
- [视频生成](/zh-CN/tools/video-generation)
- [音乐生成](/tools/music-generation)
- [音乐生成](/zh-CN/tools/music-generation)
- [提供商目录](/zh-CN/providers/index)
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults)

132
docs/zh-CN/tools/index.md
View File

@ -6,50 +6,52 @@ read_when:
summary: OpenClaw 工具和插件概览：智能体能做什么，以及如何扩展它
title: 工具和插件
x-i18n:
generated_at: "2026-04-06T01:01:08Z"
generated_at: "2026-04-06T01:07:18Z"
model: gpt-5.4
provider: openai
source_hash: ce14e03c4b090dd183db86c509c248e21e5e882ae0900676166429fa33a940b6
source_hash: b2371239316997b0fe389bfa2ec38404e1d3e177755ad81ff8035ac583d9adeb
source_path: tools/index.md
workflow: 15
---
# 工具和插件
智能体在生成文本之外所做的一切，都是通过**工具**完成的。
工具是智能体读取文件、运行命令、浏览网页、发送消息以及与设备交互的方式。
智能体所做的一切，凡是超出生成文本范围的，都通过**工具**完成。
工具是智能体读取文件、运行命令、浏览网页、发送
消息以及与设备交互的方式。
## 工具、Skills 和插件
OpenClaw 有三个协同工作的层次：
OpenClaw 有三个协同工作的层级：
<Steps>
<Step title="工具是智能体调用的内容">
工具是智能体可以调用的类型化函数（例如 `exec`、`browser`、
`web_search`、`message`）。OpenClaw 内置了一组**内置工具**，而且
插件还可以注册其他工具。
工具是智能体可调用的类型化函数（例如 `exec`、`browser`、
`web_search`、`message`）。OpenClaw 自带一组**内置工具**，并且
插件可以注册额外工具。
对智能体来说，工具是发送到模型 API 的结构化函数定义。
</Step>
<Step title="Skills 教会智能体何时以及如何使用">
Skill 是注入到系统提示词中的 Markdown 文件（`SKILL.md`）。
Skills 为智能体提供上下文、约束，以及高效使用工具的分步指导。
Skills 可以位于你的工作区、共享文件夹中，或随插件一起提供。
Skills 是注入到系统提示词中的 Markdown 文件（`SKILL.md`）。
Skills 为智能体提供上下文、约束，以及
高效使用工具的分步指导。Skills 可以位于你的工作区、共享文件夹中，
或由插件内置提供。
[Skills 参考](/zh-CN/tools/skills) | [创建 Skills](/zh-CN/tools/creating-skills)
</Step>
<Step title="插件将一切打包在一起">
插件是可以注册任意能力组合的软件包：
插件是一种软件包，可以注册任意组合的能力：
渠道、模型提供商、工具、Skills、语音、实时转写、
实时语音、媒体理解、图像生成、视频生成、
网页抓取、网页搜索等等。有些插件是**核心**插件（随
OpenClaw 一起提供），另一些则是**外部**插件（由社区发布到 npm）。
OpenClaw 一起提供），另一些是**外部**插件（由社区发布到 npm）。
[安装和配置插件](/zh-CN/tools/plugin) | [构建你自己的插件](/zh-CN/plugins/building-plugins)
[安装并配置插件](/zh-CN/tools/plugin) | [构建你自己的插件](/zh-CN/plugins/building-plugins)
</Step>
</Steps>
@ -58,70 +60,70 @@ OpenClaw 有三个协同工作的层次：
这些工具随 OpenClaw 一起提供，无需安装任何插件即可使用：
| 工具 | 功能 | 页面 |
| ------------------------------------------ | ------------------------------------------------------------- | ------------------------------------------- |
| `exec` / `process` | 运行 shell 命令，管理后台进程 | [Exec](/zh-CN/tools/exec) |
| `code_execution` | 运行沙箱隔离的远程 Python 分析 | [代码执行](/zh-CN/tools/code-execution) |
| `browser` | 控制 Chromium 浏览器（导航、点击、截图） | [浏览器](/zh-CN/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜索网页、搜索 X 帖子、抓取页面内容 | [网页](/zh-CN/tools/web) |
| `read` / `write` / `edit` | 工作区中的文件 I/O | |
| `apply_patch` | 多块文件补丁 | [应用补丁](/zh-CN/tools/apply-patch) |
| `message` | 在所有渠道中发送消息 | [智能体发送](/zh-CN/tools/agent-send) |
| `canvas` | 驱动节点 Canvas（present、eval、snapshot） | |
| `nodes` | 发现并定位已配对设备 | |
| `cron` / `gateway` | 管理定时任务；检查、修补、重启或更新 Gateway 网关 | |
| `image` / `image_generate` | 分析或生成图像 | [图像生成](/zh-CN/tools/image-generation) |
| `music_generate` | 生成音乐曲目 | [音乐生成](/zh-CN/tools/music-generation) |
| `video_generate` | 生成视频 | [视频生成](/zh-CN/tools/video-generation) |
| `tts` | 一次性文本转语音转换 | [TTS](/zh-CN/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 会话管理、状态查看和子智能体编排 | [子智能体](/zh-CN/tools/subagents) |
| `session_status` | 轻量级的 `/status` 风格回读和会话模型覆盖 | [会话工具](/zh-CN/concepts/session-tool) |
| 工具 | 作用 | 页面 |
| ------------------------------------------ | --------------------------------------------------------------------- | ------------------------------------------- |
| `exec` / `process` | 运行 shell 命令，管理后台进程 | [Exec](/zh-CN/tools/exec) |
| `code_execution` | 运行沙箱隔离的远程 Python 分析 | [代码执行](/zh-CN/tools/code-execution) |
| `browser` | 控制 Chromium 浏览器（导航、点击、截图） | [浏览器](/zh-CN/tools/browser) |
| `web_search` / `x_search` / `web_fetch` | 搜索网页、搜索 X 帖子、抓取页面内容 | [网页](/zh-CN/tools/web) |
| `read` / `write` / `edit` | 在工作区中执行文件 I/O | |
| `apply_patch` | 多段文件补丁 | [应用补丁](/zh-CN/tools/apply-patch) |
| `message` | 跨所有渠道发送消息 | [智能体发送](/zh-CN/tools/agent-send) |
| `canvas` | 驱动节点 Canvas（展示、求值、快照） | |
| `nodes` | 发现并定位已配对的设备 | |
| `cron` / `gateway` | 管理计划任务；检查、修补、重启或更新 Gateway 网关 | |
| `image` / `image_generate` | 分析或生成图像 | [图像生成](/zh-CN/tools/image-generation) |
| `music_generate` | 生成音乐轨道 | [音乐生成](/zh-CN/tools/music-generation) |
| `video_generate` | 生成视频 | [视频生成](/zh-CN/tools/video-generation) |
| `tts` | 一次性文本转语音转换 | [TTS](/zh-CN/tools/tts) |
| `sessions_*` / `subagents` / `agents_list` | 会话管理、状态查看和子智能体编排 | [子智能体](/zh-CN/tools/subagents) |
| `session_status` | 轻量级 `/status` 风格回读和会话模型覆盖 | [会话工具](/zh-CN/concepts/session-tool) |
对于图像工作，使用 `image` 进行分析，使用 `image_generate` 进行生成或编辑。如果你的目标是 `openai/*`、`google/*`、`fal/*` 或其他非默认图像提供商，请先配置该提供商的身份验证 / API 密钥。
处理图像时，使用 `image` 进行分析，使用 `image_generate` 进行生成或编辑。如果你要使用 `openai/*`、`google/*`、`fal/*` 或其他非默认图像提供商，请先配置该提供商的凭证 / API 密钥。
对于音乐工作，使用 `music_generate`。如果你的目标是 `google/*`、`minimax/*` 或其他非默认音乐提供商，请先配置该提供商的身份验证 / API 密钥。
处理音乐时，使用 `music_generate`。如果你要使用 `google/*`、`minimax/*` 或其他非默认音乐提供商，请先配置该提供商的凭证 / API 密钥。
对于视频工作，使用 `video_generate`。如果你的目标是 `qwen/*` 或其他非默认视频提供商，请先配置该提供商的身份验证 / API 密钥。
处理视频时，使用 `video_generate`。如果你要使用 `qwen/*` 或其他非默认视频提供商，请先配置该提供商的凭证 / API 密钥。
对于工作流驱动的音频生成，当某个插件（例如
ComfyUI）注册了它时，请使用 `music_generate`。这与 `tts`
不同，后者是文本转语音。
ComfyUI）注册了 `music_generate` 时，请使用它。这与 `tts` 不同，
后者用于文本转语音。
`session_status` 是 sessions 分组中的轻量级状态 / 回读工具。
它可以回答当前会话中类似 `/status` 的问题，并且可以
选择性设置按会话生效的模型覆盖；`model=default` 会清除此
覆盖。与 `/status` 一样，它可以从最新的转录使用记录中回填稀疏的
token / cache 计数器，以及当前活动运行时模型标签。
它可以回答当前会话的 `/status` 风格问题，并且
还可以选择设置会话级模型覆盖；`model=default` 会清除该
覆盖。和 `/status` 一样，它可以从最新的转录使用记录中回填稀疏的令牌 / 缓存计数，以及
当前运行时模型标签。
`gateway` 是仅所有者可用的 Gateway 网关运行时工具，用于执行 Gateway 网关操作：
`gateway` 是仅限所有者使用的 Gateway 网关运行时工具，用于执行 Gateway 网关操作：
- `config.schema.lookup`：在编辑前查看单个路径范围内的配置子树
- `config.schema.lookup`：在编辑前查看单一路径范围的配置子树
- `config.get`：获取当前配置快照 + 哈希值
- `config.patch`：执行局部配置更新并重启
- `config.patch`：执行带重启的部分配置更新
- `config.apply`：仅用于完整配置替换
- `update.run`：显式执行自更新 + 重启
对于局部更改，优先使用 `config.schema.lookup`，然后使用 `config.patch`。仅当你有意替换整个配置时，才使用
`config.apply`。
对于部分更改，优先使用 `config.schema.lookup`，然后使用 `config.patch`。仅在你有意替换整个配置时
才使用 `config.apply`。
该工具还会拒绝更改 `tools.exec.ask` 或 `tools.exec.security`；
旧版 `tools.bash.*` 别名会归一化到相同的受保护 exec 路径。
旧版 `tools.bash.*` 别名会规范化到相同的受保护 `exec` 路径。
### 插件提供的工具
插件可以注册其他工具。示例包括：
插件可以注册额外工具。示例如下：
- [Lobster](/zh-CN/tools/lobster) — 带可恢复审批的类型化工作流运行时
- [LLM Task](/zh-CN/tools/llm-task) — 仅 JSON 的 LLM 步骤，用于结构化输出
- [音乐生成](/zh-CN/tools/music-generation) — 共享的 `music_generate` 工具，以及插件提供的工作流变体
- [音乐生成](/zh-CN/tools/music-generation) — 由工作流支持的提供商共享的 `music_generate` 工具
- [Diffs](/zh-CN/tools/diffs) — 差异查看器和渲染器
- [OpenProse](/zh-CN/prose) — 以 Markdown 为优先的工作流编排
- [OpenProse](/zh-CN/prose) — 以 Markdown 为先的工作流编排
## 工具配置
### 允许和拒绝列表
### 允许列表和拒绝列表
通过配置中的 `tools.allow` / `tools.deny` 控制智能体可以调用哪些工具。
拒绝规则始终优先于允许规则。
拒绝始终优先于允许。
```json5
{
@ -134,23 +136,23 @@ token / cache 计数器，以及当前活动运行时模型标签。
### 工具配置文件
`tools.profile` 会在应用 `allow` / `deny` 之前设置基础允许列表。
`tools.profile` 会在应用 `allow` / `deny` 之前设置一个基础允许列表。
按智能体覆盖：`agents.list[].tools.profile`。
| 配置文件 | 包含内容 |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 无限制（与未设置相同） |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `full` | 不限制（与未设置相同） |
| `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `music_generate`, `video_generate` |
| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` |
| `minimal` | 仅 `session_status` |
### 工具组
### 工具分组
在允许 / 拒绝列表中使用 `group:*` 简写：
| 组 | 工具 |
| 分组 | 工具 |
| ------------------ | --------------------------------------------------------------------------------------------------------- |
| `group:runtime` | exec、process、code_execution（`bash` 可作为 `exec` 的别名使用） |
| `group:runtime` | exec、process、code_execution（`bash` 可作为 `exec` 的别名使用） |
| `group:fs` | read、write、edit、apply_patch |
| `group:sessions` | sessions_list、sessions_history、sessions_send、sessions_spawn、sessions_yield、subagents、session_status |
| `group:memory` | memory_search、memory_get |
@ -161,22 +163,22 @@ token / cache 计数器，以及当前活动运行时模型标签。
| `group:nodes` | nodes |
| `group:agents` | agents_list |
| `group:media` | image、image_generate、music_generate、video_generate、tts |
| `group:openclaw` | 所有 OpenClaw 内置工具（不包括插件工具） |
| `group:openclaw` | 所有 OpenClaw 内置工具（不包括插件工具） |
`sessions_history` 返回的是有界的、经过安全过滤的回忆视图。它会从助手文本中去除
`sessions_history` 返回受边界限制且经过安全过滤的回忆视图。它会移除
思考标签、`<relevant-memories>` 脚手架、纯文本工具调用 XML
负载（包括 `<tool_call>...</tool_call>`、
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
`<function_calls>...</function_calls>` 以及被截断的工具调用块）、
降级后的工具调用脚手架、泄露的 ASCII / 全角模型控制
token，以及格式错误的来自 MiniMax 的工具调用 XML，然后再执行
脱敏 / 截断，并在可能的情况下使用超大行占位符，而不是把它作为
原始转录转储返回。
令牌，以及助手文本中格式错误的 MiniMax 工具调用 XML，然后再执行
脱敏 / 截断，并在行内容过大时使用占位符，而不是
充当原始转录转储。
### 提供商特定限制
使用 `tools.byProvider` 可针对特定提供商限制工具，而无需
更改全局默认设置：
使用 `tools.byProvider` 为特定提供商限制工具，而无需
更改全局默认值：
```json5
{

120
docs/zh-CN/tools/music-generation.md
View File

@ -3,37 +3,30 @@ read_when:
- 通过智能体生成音乐或音频
- 配置音乐生成提供商和模型
- 了解 `music_generate` 工具参数
summary: 通过共享提供商或插件提供的工作流生成音乐
summary: 使用共享提供商生成音乐，包括基于工作流的插件
title: 音乐生成
x-i18n:
generated_at: "2026-04-06T01:00:51Z"
generated_at: "2026-04-06T01:07:11Z"
model: gpt-5.4
provider: openai
source_hash: 10a310920a34a6d2aa90b82703b00dbd9944ec349ada948c3fdb12e9d45246a0
source_hash: 7e5dc234b14aee2f5ef766985479b0ba262cceb4510596f6b1cc343a3732838c
source_path: tools/music-generation.md
workflow: 15
---
# 音乐生成
`music_generate` 工具让智能体通过以下任一方式创建音乐或音频：
`music_generate` 工具让智能体能够通过共享音乐生成能力，结合已配置的提供商（例如 Google、MiniMax 和基于工作流配置的 ComfyUI）创建音乐或音频。
- 使用共享音乐生成功能，并配合已配置的提供商，例如 Google 和 MiniMax
- 使用由插件提供的工具接口，例如通过工作流配置的 ComfyUI 图表
对于由共享提供商支持的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在曲目准备好后再次唤醒智能体，以便智能体将完成的音频回发到原始渠道中。
对于由共享提供商支持的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备就绪时再次唤醒智能体，以便智能体将完成的音频发布回原始渠道。
<Note>
只有在至少有一个音乐生成提供商可用时，内置共享工具才会显示。如果你在智能体的工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。
</Note>
<Note>
由插件提供的 `music_generate` 实现可能会暴露不同的参数或运行时行为。下面的异步任务/状态流程适用于内置的、由共享提供商支持的路径。
只有在至少有一个音乐生成提供商可用时，内置共享工具才会显示。如果你在智能体工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。
</Note>
## 快速开始
### 共享提供商支持的生成
### 由共享提供商支持的生成
1. 为至少一个提供商设置 API 密钥，例如 `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。
2. 可选：设置你偏好的模型：
@ -50,11 +43,11 @@ x-i18n:
}
```
3. 向智能体发出请求：_“生成一首关于夜晚穿行霓虹城市驾驶的欢快 synthpop 曲目。”_
3. 向智能体发出请求：_“生成一段欢快的 synthpop 音轨，主题是在霓虹都市中夜间驾车。”_
智能体会自动调用 `music_generate`。无需配置工具允许列表。
智能体会自动调用 `music_generate`。不需要工具允许列表。
对于没有会话支持的智能体运行的直接同步上下文，内置工具仍会回退到内联生成，并在工具结果中返回最终媒体路径。
对于没有会话支持的智能体运行的直接同步上下文，内置工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。
示例提示词：
@ -66,11 +59,11 @@ Generate a cinematic piano track with soft strings and no vocals.
Generate an energetic chiptune loop about launching a rocket at sunrise.
```
### 工作流驱动的插件生成
### 由工作流驱动的 Comfy 生成
内置的 `comfy` 插件也可以使用通过工作流配置的 ComfyUI 图表提供 `music_generate`。
内置的 `comfy` 插件通过音乐生成提供商注册表接入共享 `music_generate` 工具。
1. 使用工作流 JSON 以及提示词/输出节点配置 `models.providers.comfy.music`。
1. 为 `models.providers.comfy.music` 配置工作流 JSON 以及提示词/输出节点。
2. 如果你使用 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。
3. 请求智能体生成音乐，或直接调用该工具。
@ -82,24 +75,19 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## 共享内置提供商支持
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 |
| ------ | ---------------------- | ---------------- | --------------------------------------------------------- | ---------------------------------- |
| Google | `lyria-3-clip-preview` | 最多 10 张图片 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` |
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | API 密钥 |
| ------ | ---------------------- | -------------- | --------------------------------------------------------- | -------------------------------------- |
| ComfyUI | `workflow` | 最多 1 张图片 | 由工作流定义的音乐或音频 | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
| Google | `lyria-3-clip-preview` | 最多 10 张图片 | `lyrics`、`instrumental`、`format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
| MiniMax | `music-2.5+` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` |
## 插件提供的支持
| 提供商 | 模型 | 说明 |
| -------- | ---------- | ------------------------ |
| ComfyUI | `workflow` | 由工作流定义的音乐或音频 |
使用 `action: "list"` 可在运行时检查可用的共享提供商和模型：
使用 `action: "list"` 可在运行时查看可用的共享提供商和模型：
```text
/tool music_generate action=list
```
使用 `action: "status"` 可检查当前由会话支持的音乐任务：
使用 `action: "status"` 可检查当前由会话支持的活动音乐任务：
```text
/tool music_generate action=status
@ -113,30 +101,30 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
## 内置工具参数
| 参数 | 类型 | 说明 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------ |
| `prompt` | string | 音乐生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于检查提供商的 `"list"` |
| `model` | string | 提供商/模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` |
| `lyrics` | string | 当提供商支持显式歌词输入时可选填写歌词 |
| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 |
| `image` | string | 单个参考图片路径或 URL |
| `images` | string[] | 多个参考图片（最多 10 张） |
| `durationSeconds` | number | 当提供商支持时，以秒为单位指定目标时长提示 |
| `format` | string | 当提供商支持时，输出格式提示（`mp3` 或 `wav`） |
| `filename` | string | 输出文件名提示 |
| 参数 | 类型 | 描述 |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `prompt` | string | 音乐生成提示词（`action: "generate"` 时必填） |
| `action` | string | `"generate"`（默认）、用于当前会话任务的 `"status"`，或用于查看提供商的 `"list"` |
| `model` | string | 提供商/模型覆盖，例如 `google/lyria-3-pro-preview` 或 `comfy/workflow` |
| `lyrics` | string | 当提供商支持显式歌词输入时可选填写歌词 |
| `instrumental` | boolean | 当提供商支持时，请求仅器乐输出 |
| `image` | string | 单个参考图片路径或 URL |
| `images` | string[] | 多个参考图片（最多 10 张） |
| `durationSeconds` | number | 当提供商支持时长提示时，以秒为单位的目标时长 |
| `format` | string | 当提供商支持时的输出格式提示（`mp3` 或 `wav`） |
| `filename` | string | 输出文件名提示 |
并非所有提供商或插件都支持所有参数。共享内置工具会在提交请求前验证提供商能力限制。
并非所有提供商都支持所有参数。共享工具会在提交请求前验证提供商能力限制。
## 共享提供商支持路径的异步行为
- 由会话支持的智能体运行：`music_generate` 会创建后台任务，立即返回 started/task 响应，并稍后在后续智能体消息中发布完成的曲目。
- 防止重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中的后续 `music_generate` 调用会返回任务状态，而不是启动另一次生成。
- 状态查询：使用 `action: "status"` 可检查当前由会话支持的音乐任务，而不会启动新任务。
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 检查该生成任务的排队、运行和终态状态。
- 完成唤醒：OpenClaw 会将内部完成事件重新注入到同一会话中，以便模型自行编写面向用户的后续回复。
- 提示词提示：当音乐任务已在进行中时，同一会话中的后续用户/手动轮次会收到一条简短的运行时提示，以便模型不会再次盲目调用 `music_generate`。
- 无会话回退：没有真实智能体会话的直接/本地上下文仍会以内联方式运行，并在同一轮中返回最终音频结果。
- 由会话支持的智能体运行：`music_generate` 会创建后台任务，立即返回 started/task 响应，并在稍后的智能体跟进消息中发布完成的音轨。
- 防止重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续的 `music_generate` 调用会返回任务状态，而不是再次启动生成。
- 状态查询：使用 `action: "status"` 可检查当前由会话支持的活动音乐任务，而不会启动新任务。
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可检查生成任务的排队、运行中和终态状态。
- 完成唤醒：OpenClaw 会将内部完成事件注入回同一会话，以便模型自行编写面向用户的后续消息。
- 提示词提示：当音乐任务已在处理中时，同一会话中后续的用户/手动轮次会收到一个小型运行时提示，这样模型就不会盲目再次调用 `music_generate`。
- 无会话回退：在没有真实智能体会话的直接/本地上下文中，仍会以内联方式运行，并在同一轮中返回最终音频结果。
## 配置
@ -159,42 +147,42 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
生成音乐时，OpenClaw 会按以下顺序尝试提供商：
1. 工具调用中的 `model` 参数（如果智能体指定了它）
1. 工具调用中的 `model` 参数（如果智能体指定了）
2. 配置中的 `musicGenerationModel.primary`
3. 按顺序使用 `musicGenerationModel.fallbacks`
4. 仅使用基于认证支持的提供商默认值进行自动检测：
3. 按顺序尝试 `musicGenerationModel.fallbacks`
4. 仅使用基于凭证的提供商默认值进行自动检测：
- 先尝试当前默认提供商
- 再按提供商 ID 顺序尝试其余已注册的音乐生成提供商
- 再按 provider-id 顺序尝试其余已注册的音乐生成提供商
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中将包含每次尝试的详细信息。
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。
## 提供商说明
- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本以及可选参考图片。
- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本和可选参考图片。
- MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长控制以及 mp3 输出。
- ComfyUI 支持由工作流驱动，并取决于配置的图表以及提示词/输出字段的节点映射。
- ComfyUI 支持由工作流驱动，具体取决于已配置的图形以及提示词/输出字段的节点映射。
## 选择合适的路径
- 当你需要模型选择、提供商故障切换以及内置异步任务/状态流时，请使用共享提供商支持路径。
- 当你需要自定义工作流图表，或使用不属于共享内置音乐能力的提供商时，请使用插件路径，例如 ComfyUI。
- 如果你正在调试 ComfyUI 特定行为，请参阅 [ComfyUI](/zh-CN/providers/comfy)。如果你正在调试共享提供商行为，请先查看 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax)。
- 如果你希望使用模型选择、提供商故障切换和内置的异步任务/状态流程，请使用由共享提供商支持的路径。
- 如果你需要自定义工作流图，或需要使用不属于共享内置音乐能力的提供商，请使用插件路径，例如 ComfyUI。
- 如果你正在调试 ComfyUI 特定行为，请参见 [ComfyUI](/zh-CN/providers/comfy)。如果你正在调试共享提供商行为，请先查看 [Google (Gemini)](/zh-CN/providers/google) 或 [MiniMax](/zh-CN/providers/minimax)。
## 实时测试
共享内置提供商的选择性实时覆盖：
共享内置提供商的选择加入式实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
```
内置 ComfyUI 音乐路径的选择性实时覆盖：
内置 ComfyUI 音乐路径的选择加入式实时覆盖：
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
如果配置了相关部分，Comfy 实时文件还会覆盖 comfy 图片和视频工作流。
当这些部分已配置时，Comfy 实时文件也涵盖 comfy 图片和视频工作流。
## 相关内容
@ -203,5 +191,5 @@ OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.
- [ComfyUI](/zh-CN/providers/comfy)
- [Google (Gemini)](/zh-CN/providers/google)
- [MiniMax](/zh-CN/providers/minimax)
- [模型](/zh-CN/concepts/models) - 模型配置与故障切换
- [模型](/zh-CN/concepts/models) - 模型配置和故障切换
- [工具概览](/zh-CN/tools)