chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
41ef9f8a78
commit
aefe68ac6f
@ -3,26 +3,26 @@ read_when:
|
||||
- 你在不带任何命令的情况下运行 openclaw，并且想了解 Crestodian
|
||||
- 你需要一种无配置且安全的方式来检查或修复 OpenClaw
|
||||
- 你正在设计或启用消息渠道救援模式
|
||||
summary: Crestodian 的 CLI 参考和安全模型，即这个无配置且安全的设置与修复辅助工具
|
||||
summary: Crestodian 的 CLI 参考和安全模型，即无配置且安全的设置与修复助手
|
||||
title: Crestodian
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T09:23:17Z"
|
||||
generated_at: "2026-04-25T10:04:03Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bcb9d6c81ca95d3738094143147d1a237bfb2037e530f87dc9aea20f6f528010
|
||||
source_hash: 19ee9b794152c69e3db8fa89e2876de30cc076db527ec7ee06f103e7d25a4d03
|
||||
source_path: cli/crestodian.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw crestodian`
|
||||
|
||||
Crestodian 是 OpenClaw 的本地设置、修复和配置辅助工具。它的设计目标是在正常智能体路径损坏时，仍然可以访问。
|
||||
Crestodian 是 OpenClaw 的本地设置、修复和配置助手。它旨在在正常智能体路径损坏时仍然可访问。
|
||||
|
||||
在不带任何命令的情况下运行 `openclaw` 会在交互式终端中启动 Crestodian。运行 `openclaw crestodian` 会显式启动同一个辅助工具。
|
||||
在不带任何命令的情况下运行 `openclaw` 会在交互式终端中启动 Crestodian。运行 `openclaw crestodian` 会显式启动同一个助手。
|
||||
|
||||
## Crestodian 会显示什么
|
||||
|
||||
启动时，Crestodian 会打印一个紧凑的系统概览：
|
||||
启动时，交互式 Crestodian 会打开与 `openclaw tui` 使用的相同 TUI shell，但使用 Crestodian 聊天后端。聊天日志会从一个紧凑的系统概览开始：
|
||||
|
||||
- 配置路径及其有效性
|
||||
- 已配置的智能体和默认智能体
|
||||
@ -30,14 +30,14 @@ Crestodian 是 OpenClaw 的本地设置、修复和配置辅助工具。它的
|
||||
- 本地 Codex 和 Claude Code CLI 的可用性
|
||||
- OpenAI 和 Anthropic API 密钥是否存在
|
||||
- 规划器模式（`deterministic` 或通过已配置模型进行模型辅助）
|
||||
- 本地文档路径或公共文档 URL
|
||||
- 本地文档路径或公开文档 URL
|
||||
- Git 检出时的本地源码路径，否则为 OpenClaw GitHub 源码 URL
|
||||
- Gateway 网关 可达性
|
||||
- 立即推荐的下一步操作
|
||||
|
||||
它不会为了启动而转储密钥，也不会加载插件 CLI 命令。
|
||||
它不会为了启动而转储密钥，也不会加载插件 CLI 命令。TUI 仍然提供正常的页眉、聊天日志、状态行、页脚、自动补全和编辑器控件。
|
||||
|
||||
Crestodian 使用与常规智能体相同的 OpenClaw 参考发现机制。在 Git 检出中，它会将自身指向本地 `docs/` 和本地源码树。在 npm 包安装中，它会使用随包提供的文档，并链接到 [https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)，同时明确建议你在文档不够用时查阅源码。
|
||||
Crestodian 使用与常规智能体相同的 OpenClaw 参考发现机制。在 Git 检出中，它会将自己指向本地 `docs/` 和本地源码树。在 npm 包安装中，它会使用内置的包文档，并链接到 [https://github.com/openclaw/openclaw](https://github.com/openclaw/openclaw)，同时明确指导你在文档不足时查看源码。
|
||||
|
||||
## 示例
|
||||
|
||||
@ -52,7 +52,7 @@ openclaw crestodian --message "set default model openai/gpt-5.5" --yes
|
||||
openclaw onboard --modern
|
||||
```
|
||||
|
||||
在交互式提示符中：
|
||||
在 Crestodian TUI 中：
|
||||
|
||||
```text
|
||||
status
|
||||
@ -78,18 +78,17 @@ quit
|
||||
|
||||
## 安全启动
|
||||
|
||||
Crestodian 的启动路径被刻意保持得很小。在以下情况下它也可以运行：
|
||||
Crestodian 的启动路径刻意保持精简。它可以在以下情况下运行：
|
||||
|
||||
- `openclaw.json` 缺失
|
||||
- 缺少 `openclaw.json`
|
||||
- `openclaw.json` 无效
|
||||
- Gateway 网关 已停止
|
||||
- 插件命令注册不可用
|
||||
- 尚未配置任何智能体
|
||||
|
||||
`openclaw --help` 和 `openclaw --version` 仍然使用正常的快速路径。
|
||||
非交互式 `openclaw` 会输出一条简短消息后退出，而不是打印根帮助信息，因为无命令产品形态就是 Crestodian。
|
||||
`openclaw --help` 和 `openclaw --version` 仍然使用正常的快速路径。非交互式的 `openclaw` 会以一条简短消息退出，而不是打印根帮助，因为无命令产品就是 Crestodian。
|
||||
|
||||
## 操作和批准
|
||||
## 操作与批准
|
||||
|
||||
Crestodian 使用类型化操作，而不是临时编辑配置。
|
||||
|
||||
@ -97,19 +96,19 @@ Crestodian 使用类型化操作，而不是临时编辑配置。
|
||||
|
||||
- 显示概览
|
||||
- 列出智能体
|
||||
- 显示模型/后端 Status
|
||||
- 运行 status 或 health 检查
|
||||
- 显示模型/后端状态
|
||||
- 运行 Status 或健康检查
|
||||
- 检查 Gateway 网关 可达性
|
||||
- 运行 doctor，但不执行交互式修复
|
||||
- 运行 doctor，但不进行交互式修复
|
||||
- 验证配置
|
||||
- 显示审计日志路径
|
||||
|
||||
持久化操作在交互模式下需要对话式批准，除非你为直接命令传递 `--yes`：
|
||||
持久化操作在交互模式下需要对话式批准，除非你为直接命令传入 `--yes`：
|
||||
|
||||
- 写入配置
|
||||
- 运行 `config set`
|
||||
- 通过 `config set-ref` 设置受支持的 SecretRef 值
|
||||
- 运行 setup/新手引导 引导流程
|
||||
- 运行设置/新手引导引导流程
|
||||
- 更改默认模型
|
||||
- 启动、停止或重启 Gateway 网关
|
||||
- 创建智能体
|
||||
@ -123,12 +122,11 @@ Crestodian 使用类型化操作，而不是临时编辑配置。
|
||||
|
||||
发现过程不会被审计。只有已应用的操作和写入会被记录。
|
||||
|
||||
`openclaw onboard --modern` 会将 Crestodian 作为现代新手引导预览启动。
|
||||
普通的 `openclaw onboard` 仍然运行经典新手引导。
|
||||
`openclaw onboard --modern` 会将 Crestodian 作为现代新手引导预览启动。普通的 `openclaw onboard` 仍然运行经典新手引导。
|
||||
|
||||
## 设置引导
|
||||
|
||||
`setup` 是以聊天为先的新手引导引导流程。它只会通过类型化配置操作进行写入，并且会先请求批准。
|
||||
`setup` 是一种聊天优先的新手引导引导方式。它只通过类型化配置操作写入，并且会先请求批准。
|
||||
|
||||
```text
|
||||
setup
|
||||
@ -138,29 +136,29 @@ setup workspace ~/Projects/work model openai/gpt-5.5
|
||||
|
||||
当未配置任何模型时，setup 会按以下顺序选择第一个可用后端，并告诉你它选择了什么：
|
||||
|
||||
- 已有的显式模型（如果已经配置）
|
||||
- 已存在的显式模型（如果已配置）
|
||||
- `OPENAI_API_KEY` -> `openai/gpt-5.5`
|
||||
- `ANTHROPIC_API_KEY` -> `anthropic/claude-opus-4-7`
|
||||
- Claude Code CLI -> `claude-cli/claude-opus-4-7`
|
||||
- Codex CLI -> `codex-cli/gpt-5.5`
|
||||
|
||||
如果这些都不可用，setup 仍会写入默认工作区，并将模型保持为未设置状态。安装或登录 Codex/Claude Code，或者暴露 `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`，然后再次运行 setup。
|
||||
如果这些都不可用，setup 仍会写入默认工作区，并将模型保留为未设置状态。安装或登录 Codex/Claude Code，或暴露 `OPENAI_API_KEY`/`ANTHROPIC_API_KEY`，然后再次运行 setup。
|
||||
|
||||
## 模型辅助规划器
|
||||
|
||||
Crestodian 始终以确定性模式启动。对于确定性解析器无法理解的模糊命令，本地 Crestodian 可以通过 OpenClaw 的正常运行时路径执行一次受限的规划器轮次。它会优先使用已配置的 OpenClaw 模型。如果尚无可用的已配置模型，它可以回退到机器上已存在的本地运行时：
|
||||
Crestodian 始终以确定性模式启动。对于确定性解析器无法理解的模糊命令，本地 Crestodian 可以通过 OpenClaw 的正常运行时路径进行一次受限的规划器轮次。它会优先使用已配置的 OpenClaw 模型。如果尚无可用的已配置模型，它可以回退到机器上已存在的本地运行时：
|
||||
|
||||
- Claude Code CLI：`claude-cli/claude-opus-4-7`
|
||||
- Codex app-server harness：`openai/gpt-5.5`，带 `embeddedHarness.runtime: "codex"`
|
||||
- Codex app-server harness：`openai/gpt-5.5`，使用 `embeddedHarness.runtime: "codex"`
|
||||
- Codex CLI：`codex-cli/gpt-5.5`
|
||||
|
||||
模型辅助规划器不能直接修改配置。它必须先将请求转换为 Crestodian 的某个类型化命令，然后才会应用正常的批准和审计规则。Crestodian 会在执行任何操作之前打印它使用的模型以及解释后的命令。无配置回退规划器轮次是临时的，在运行时支持的情况下会禁用工具，并使用临时工作区/会话。
|
||||
模型辅助规划器不能直接更改配置。它必须先将请求转换为 Crestodian 的某个类型化命令，然后才会应用正常的批准和审计规则。Crestodian 会在运行任何操作之前打印它所使用的模型和解释后的命令。无配置的回退规划器轮次是临时的，在运行时支持的情况下会禁用工具，并使用临时工作区/会话。
|
||||
|
||||
消息渠道救援模式不会使用模型辅助规划器。远程救援保持确定性，这样损坏或被攻陷的正常智能体路径就不能被用作配置编辑器。
|
||||
消息渠道救援模式不会使用模型辅助规划器。远程救援保持确定性，这样受损或被入侵的正常智能体路径就不能被用作配置编辑器。
|
||||
|
||||
## 切换到智能体
|
||||
|
||||
使用自然语言选择器离开 Crestodian 并打开正常 TUI：
|
||||
使用自然语言选择器可离开 Crestodian 并打开正常的 TUI：
|
||||
|
||||
```text
|
||||
talk to agent
|
||||
@ -170,18 +168,18 @@ switch to main agent
|
||||
|
||||
`openclaw tui`、`openclaw chat` 和 `openclaw terminal` 仍会直接打开正常智能体 TUI。它们不会启动 Crestodian。
|
||||
|
||||
切换到正常 TUI 后，使用 `/crestodian` 返回 Crestodian。你可以附带后续请求：
|
||||
切换到正常 TUI 后，使用 `/crestodian` 可返回 Crestodian。你可以附带后续请求：
|
||||
|
||||
```text
|
||||
/crestodian
|
||||
/crestodian restart gateway
|
||||
```
|
||||
|
||||
TUI 内部的智能体切换会留下一个提示，表明 `/crestodian` 可用。
|
||||
TUI 中的智能体切换会留下一个提示，表明 `/crestodian` 可用。
|
||||
|
||||
## 消息救援模式
|
||||
|
||||
消息救援模式是 Crestodian 的消息渠道入口点。它适用于这样的场景：你的正常智能体已失效，但像 WhatsApp 这样的可信渠道仍然可以接收命令。
|
||||
消息救援模式是 Crestodian 的消息渠道入口点。它适用于你的正常智能体已失效，但像 WhatsApp 这样的受信任渠道仍能接收命令的情况。
|
||||
|
||||
支持的文本命令：
|
||||
|
||||
@ -198,7 +196,7 @@ You: /crestodian yes
|
||||
OpenClaw: Applied. Audit entry written.
|
||||
```
|
||||
|
||||
也可以从本地提示符或救援模式中排队创建智能体：
|
||||
也可以通过本地提示或救援模式将智能体创建加入队列：
|
||||
|
||||
```text
|
||||
create agent work workspace ~/Projects/work model openai/gpt-5.5
|
||||
@ -207,17 +205,17 @@ create agent work workspace ~/Projects/work model openai/gpt-5.5
|
||||
|
||||
远程救援模式是一个管理员界面。必须将其视为远程配置修复，而不是普通聊天。
|
||||
|
||||
远程救援的安全约定：
|
||||
远程救援的安全契约：
|
||||
|
||||
- 当沙箱隔离处于活动状态时禁用。如果某个智能体/会话处于沙箱隔离状态，Crestodian 必须拒绝远程救援，并说明需要使用本地 CLI 修复。
|
||||
- 默认有效状态为 `auto`：仅在受信任的 YOLO 操作中允许远程救援，此时运行时已经具有未沙箱隔离的本地权限。
|
||||
- 需要显式的所有者身份。救援不得接受通配发送者规则、开放群组策略、未经身份验证的 webhook 或匿名渠道。
|
||||
- 默认仅限所有者 私信。群组/渠道救援需要显式选择启用，并且仍应将批准提示路由到所有者 私信。
|
||||
- 远程救援不能打开本地 TUI，也不能切换到交互式智能体会话。要进行智能体切换，请使用本地 `openclaw`。
|
||||
- 当沙箱隔离处于激活状态时禁用。如果某个智能体/会话处于沙箱隔离状态，Crestodian 必须拒绝远程救援，并说明需要本地 CLI 修复。
|
||||
- 默认有效状态是 `auto`：仅在受信任的 YOLO 操作中允许远程救援，也就是运行时已具有未沙箱隔离的本地权限时。
|
||||
- 需要显式的所有者身份。救援不得接受通配发送者规则、开放群组策略、未认证 webhook 或匿名渠道。
|
||||
- 默认仅限所有者私信。群组/渠道救援需要显式选择启用，并且仍应将批准提示路由到所有者私信。
|
||||
- 远程救援不能打开本地 TUI，也不能切换到交互式智能体会话。要进行智能体交接，请使用本地 `openclaw`。
|
||||
- 即使在救援模式下，持久化写入仍然需要批准。
|
||||
- 审计每一项已应用的救援操作，包括渠道、账户、发送者、会话键、操作、变更前配置哈希和变更后配置哈希。
|
||||
- 审计每一个已应用的救援操作，包括渠道、账户、发送者、会话键、操作、变更前配置哈希和变更后配置哈希。
|
||||
- 永远不要回显密钥。SecretRef 检查应报告可用性，而不是值。
|
||||
- 如果 Gateway 网关 存活，优先使用 Gateway 网关 类型化操作。如果 Gateway 网关 已停止，则只使用不依赖正常 Agent loop 的最小本地修复界面。
|
||||
- 如果 Gateway 网关 仍然存活，优先使用 Gateway 网关 的类型化操作。如果 Gateway 网关 已失效，则只使用不依赖正常 Agent loop 的最小本地修复界面。
|
||||
|
||||
配置结构：
|
||||
|
||||
@ -234,35 +232,35 @@ create agent work workspace ~/Projects/work model openai/gpt-5.5
|
||||
|
||||
`enabled` 应接受：
|
||||
|
||||
- `"auto"`：默认。仅当有效运行时为 YOLO 且沙箱隔离关闭时允许。
|
||||
- `"auto"`：默认值。仅当有效运行时是 YOLO 且沙箱隔离关闭时允许。
|
||||
- `false`：绝不允许消息渠道救援。
|
||||
- `true`：当所有者/渠道检查通过时显式允许救援。这仍然不得绕过沙箱隔离拒绝。
|
||||
- `true`：在所有者/渠道检查通过时显式允许救援。这仍然不能绕过沙箱隔离拒绝。
|
||||
|
||||
默认的 `"auto"` YOLO 姿态为：
|
||||
默认 `"auto"` YOLO 姿态是：
|
||||
|
||||
- 沙箱模式解析为 `off`
|
||||
- `tools.exec.security` 解析为 `full`
|
||||
- `tools.exec.ask` 解析为 `off`
|
||||
|
||||
远程救援由 Docker 通道覆盖测试：
|
||||
远程救援由 Docker 通道覆盖：
|
||||
|
||||
```bash
|
||||
pnpm test:docker:crestodian-rescue
|
||||
```
|
||||
|
||||
无配置本地规划器回退由以下测试覆盖：
|
||||
无配置本地规划器回退由以下命令覆盖：
|
||||
|
||||
```bash
|
||||
pnpm test:docker:crestodian-planner
|
||||
```
|
||||
|
||||
一个选择启用的实时渠道命令界面冒烟测试会检查 `/crestodian status`，以及通过救援处理器执行的持久化批准往返流程：
|
||||
一个选择启用的实时渠道命令界面冒烟测试会检查 `/crestodian status`，以及通过救援处理器完成的持久化批准往返：
|
||||
|
||||
```bash
|
||||
pnpm test:live:crestodian-rescue-channel
|
||||
```
|
||||
|
||||
通过 Crestodian 执行的全新无配置 setup 由以下测试覆盖：
|
||||
通过 Crestodian 进行的全新无配置设置由以下命令覆盖：
|
||||
|
||||
```bash
|
||||
pnpm test:docker:crestodian-first-run
|
||||
|
||||
@ -1,22 +1,22 @@
|
||||
---
|
||||
read_when:
|
||||
- 调整智能体默认值（模型、思考、工作区、心跳、媒体、Skills）
|
||||
- 调整智能体默认设置（模型、思考、工作区、心跳、媒体、Skills）
|
||||
- 配置多智能体路由和绑定
|
||||
- 调整会话、消息投递和 talk 模式行为
|
||||
summary: 智能体默认值、多智能体路由、会话、消息和 talk 配置
|
||||
- 调整会话、消息传递和 talk 模式行为
|
||||
summary: 智能体默认设置、多智能体路由、会话、消息和 talk 配置
|
||||
title: 配置 — 智能体
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T09:15:37Z"
|
||||
generated_at: "2026-04-25T10:04:03Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: feceed7f2ca92def3382c21de1a9245bf264cab49122b7a35157f55b7ad9932f
|
||||
source_hash: e5b3adcd4c809595a51ffd536fc62d9f72ac16fe249b6e23ee0560bc4076eba5
|
||||
source_path: gateway/config-agents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
在 `agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体作用域配置键。对于渠道、工具、Gateway 网关运行时以及其他顶层键，请参见 [配置参考](/zh-CN/gateway/configuration-reference)。
|
||||
`agents.*`、`multiAgent.*`、`session.*`、`messages.*` 和 `talk.*` 下的智能体作用域配置键。有关渠道、工具、Gateway 网关运行时以及其他顶层键，请参阅 [配置参考](/zh-CN/gateway/configuration-reference)。
|
||||
|
||||
## 智能体默认值
|
||||
## 智能体默认设置
|
||||
|
||||
### `agents.defaults.workspace`
|
||||
|
||||
@ -30,7 +30,7 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.repoRoot`
|
||||
|
||||
可选的仓库根目录，会显示在系统提示中的 Runtime 行里。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。
|
||||
可选的仓库根目录，会显示在系统提示中的 Runtime 行。如果未设置，OpenClaw 会从工作区开始向上遍历并自动检测。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -40,7 +40,8 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.skills`
|
||||
|
||||
为未设置 `agents.list[].skills` 的智能体提供可选的默认 Skills 允许列表。
|
||||
可选的默认 Skills 允许列表，用于未设置
|
||||
`agents.list[].skills` 的智能体。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -57,12 +58,13 @@ x-i18n:
|
||||
|
||||
- 省略 `agents.defaults.skills`，则默认 Skills 不受限制。
|
||||
- 省略 `agents.list[].skills` 以继承默认值。
|
||||
- 将 `agents.list[].skills: []` 设为无 Skills。
|
||||
- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它不会与默认值合并。
|
||||
- 设置 `agents.list[].skills: []` 表示不使用任何 Skills。
|
||||
- 非空的 `agents.list[].skills` 列表就是该智能体的最终集合；它
|
||||
不会与默认值合并。
|
||||
|
||||
### `agents.defaults.skipBootstrap`
|
||||
|
||||
禁用自动创建工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）。
|
||||
禁用工作区引导文件（`AGENTS.md`、`SOUL.md`、`TOOLS.md`、`IDENTITY.md`、`USER.md`、`HEARTBEAT.md`、`BOOTSTRAP.md`）的自动创建。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -74,8 +76,8 @@ x-i18n:
|
||||
|
||||
控制何时将工作区引导文件注入到系统提示中。默认值：`"always"`。
|
||||
|
||||
- `"continuation-skip"`：安全的续写轮次（在助手完成响应之后）会跳过工作区引导内容的重新注入，从而减少提示大小。Heartbeat 运行和压缩后的重试仍会重建上下文。
|
||||
- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此项（自定义上下文引擎、自行构建上下文的原生运行时，或专门的不使用引导文件的工作流）。Heartbeat 和压缩恢复轮次也会跳过注入。
|
||||
- `"continuation-skip"`：安全的续接轮次（在助手完成响应之后）会跳过工作区引导内容的重新注入，从而减小提示体积。Heartbeat 运行和压缩后的重试仍会重建上下文。
|
||||
- `"never"`：在每一轮都禁用工作区引导和上下文文件注入。仅对完全自行管理提示生命周期的智能体使用此选项（自定义上下文引擎、自行构建上下文的原生运行时，或专门的不使用引导的工作流）。Heartbeat 和压缩恢复轮次同样会跳过注入。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -85,7 +87,7 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.bootstrapMaxChars`
|
||||
|
||||
每个工作区引导文件在截断前允许的最大字符数。默认值：`12000`。
|
||||
单个工作区引导文件在截断前的最大字符数。默认值：`12000`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -95,7 +97,7 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.bootstrapTotalMaxChars`
|
||||
|
||||
所有工作区引导文件合计可注入的最大字符数。默认值：`60000`。
|
||||
所有工作区引导文件注入内容的总最大字符数。默认值：`60000`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -105,12 +107,12 @@ x-i18n:
|
||||
|
||||
### `agents.defaults.bootstrapPromptTruncationWarning`
|
||||
|
||||
控制在引导上下文被截断时，向智能体显示的警告文本。
|
||||
控制当引导上下文被截断时，向智能体显示的警告文本。
|
||||
默认值：`"once"`。
|
||||
|
||||
- `"off"`：绝不将警告文本注入系统提示。
|
||||
- `"once"`：对于每个唯一的截断签名，仅注入一次警告（推荐）。
|
||||
- `"always"`：只要存在截断，每次运行都注入警告。
|
||||
- `"off"`：绝不向系统提示中注入警告文本。
|
||||
- `"once"`：每种唯一的截断签名仅注入一次警告（推荐）。
|
||||
- `"always"`：只要存在截断，就在每次运行时都注入警告。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -118,9 +120,9 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### 上下文预算归属映射
|
||||
### 上下文预算归属图
|
||||
|
||||
OpenClaw 具有多个高容量的提示/上下文预算，它们被有意按子系统拆分，而不是统一通过一个通用开关来控制。
|
||||
OpenClaw 有多个高容量的提示/上下文预算，这些预算会按子系统有意拆分，而不是全部通过一个通用开关来控制。
|
||||
|
||||
- `agents.defaults.bootstrapMaxChars` /
|
||||
`agents.defaults.bootstrapTotalMaxChars`：
|
||||
@ -133,7 +135,7 @@ OpenClaw 具有多个高容量的提示/上下文预算，它们被有意按子
|
||||
- `agents.defaults.contextLimits.*`：
|
||||
有界的运行时摘录和由运行时拥有的注入块。
|
||||
- `memory.qmd.limits.*`：
|
||||
已索引的内存搜索片段和注入大小控制。
|
||||
已索引的 memory 搜索片段和注入大小控制。
|
||||
|
||||
仅当某个智能体需要不同预算时，才使用对应的按智能体覆盖项：
|
||||
|
||||
@ -142,7 +144,8 @@ OpenClaw 具有多个高容量的提示/上下文预算，它们被有意按子
|
||||
|
||||
#### `agents.defaults.startupContext`
|
||||
|
||||
控制在裸 `/new` 和 `/reset` 运行时注入的首轮启动前导内容。
|
||||
控制在空白 `/new` 和 `/reset`
|
||||
运行时注入的首轮启动前导内容。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -163,7 +166,7 @@ OpenClaw 具有多个高容量的提示/上下文预算，它们被有意按子
|
||||
|
||||
#### `agents.defaults.contextLimits`
|
||||
|
||||
用于有界运行时上下文面的共享默认值。
|
||||
有界运行时上下文面的共享默认值。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -180,14 +183,15 @@ OpenClaw 具有多个高容量的提示/上下文预算，它们被有意按子
|
||||
}
|
||||
```
|
||||
|
||||
- `memoryGetMaxChars`：`memory_get` 摘录的默认上限，在添加截断元数据和续写提示之前生效。
|
||||
- `memoryGetMaxChars`：`memory_get` 摘录在添加截断元数据和续接通知之前的默认上限。
|
||||
- `memoryGetDefaultLines`：当省略 `lines` 时，`memory_get` 的默认行窗口。
|
||||
- `toolResultMaxChars`：用于持久化结果和溢出恢复的实时工具结果上限。
|
||||
- `postCompactionMaxChars`：用于压缩后刷新注入期间 `AGENTS.md` 摘录的上限。
|
||||
- `postCompactionMaxChars`：在压缩后刷新注入期间使用的 `AGENTS.md` 摘录上限。
|
||||
|
||||
#### `agents.list[].contextLimits`
|
||||
|
||||
共享 `contextLimits` 开关的按智能体覆盖项。省略的字段会继承 `agents.defaults.contextLimits`。
|
||||
共享 `contextLimits` 开关的按智能体覆盖项。省略的字段会继承
|
||||
`agents.defaults.contextLimits`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -213,7 +217,8 @@ OpenClaw 具有多个高容量的提示/上下文预算，它们被有意按子
|
||||
|
||||
#### `skills.limits.maxSkillsPromptChars`
|
||||
|
||||
注入到系统提示中的精简 Skills 列表的全局上限。这不会影响按需读取 `SKILL.md` 文件。
|
||||
注入到系统提示中的精简 Skills 列表的全局上限。此项
|
||||
不会影响按需读取 `SKILL.md` 文件。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -246,11 +251,11 @@ Skills 提示预算的按智能体覆盖项。
|
||||
|
||||
### `agents.defaults.imageMaxDimensionPx`
|
||||
|
||||
在调用提供商之前，转录/工具图像块中图像最长边的最大像素尺寸。
|
||||
在调用提供商之前，transcript/tool 图像块中图像最长边的最大像素尺寸。
|
||||
默认值：`1200`。
|
||||
|
||||
较低的值通常会减少视觉 token 使用量和请求负载大小，适合大量截图的运行。
|
||||
较高的值则能保留更多视觉细节。
|
||||
较低的值通常会减少视觉 token 使用量和以截图为主的运行请求负载大小。
|
||||
较高的值会保留更多视觉细节。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -260,7 +265,7 @@ Skills 提示预算的按智能体覆盖项。
|
||||
|
||||
### `agents.defaults.userTimezone`
|
||||
|
||||
系统提示上下文所使用的时区（不影响消息时间戳）。默认回退到主机时区。
|
||||
用于系统提示上下文的时区（不是消息时间戳）。会回退到主机时区。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -308,7 +313,7 @@ Skills 提示预算的按智能体覆盖项。
|
||||
primary: "anthropic/claude-opus-4-6",
|
||||
fallbacks: ["openai/gpt-5.4-mini"],
|
||||
},
|
||||
params: { cacheRetention: "long" }, // 全局默认 provider 参数
|
||||
params: { cacheRetention: "long" }, // 全局默认提供商参数
|
||||
embeddedHarness: {
|
||||
runtime: "pi", // pi | auto | 已注册的 harness id，例如 codex
|
||||
fallback: "pi", // pi | none
|
||||
@ -327,53 +332,53 @@ Skills 提示预算的按智能体覆盖项。
|
||||
}
|
||||
```
|
||||
|
||||
- `model`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 字符串形式只设置主模型。
|
||||
- 对象形式设置主模型以及按顺序排列的故障切换模型。
|
||||
- `imageModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 作为 `image` 工具路径的视觉模型配置使用。
|
||||
- 当选定/默认模型无法接受图像输入时，也用作回退路由。
|
||||
- `imageGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 用于共享的图像生成能力，以及任何未来会生成图像的工具/插件表面。
|
||||
- 常见值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`、用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-2`。
|
||||
- 如果你直接选择某个 provider/model，也要配置匹配的提供商认证（例如，`google/*` 对应 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 对应 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 对应 `FAL_KEY`）。
|
||||
- 如果省略，`image_generate` 仍然可以推断一个基于认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的图像生成提供商。
|
||||
- `musicGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- `model`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 字符串形式仅设置主模型。
|
||||
- 对象形式设置主模型以及按顺序的故障切换模型。
|
||||
- `imageModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 用作 `image` 工具路径中的视觉模型配置。
|
||||
- 当所选/默认模型无法接受图像输入时，也用作回退路由。
|
||||
- `imageGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 用于共享的图像生成能力，以及任何未来会生成图像的工具/插件接口。
|
||||
- 典型值：用于原生 Gemini 图像生成的 `google/gemini-3.1-flash-image-preview`，用于 fal 的 `fal/fal-ai/flux/dev`，或用于 OpenAI Images 的 `openai/gpt-image-2`。
|
||||
- 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证（例如：`google/*` 使用 `GEMINI_API_KEY` 或 `GOOGLE_API_KEY`，`openai/gpt-image-2` 使用 `OPENAI_API_KEY` 或 OpenAI Codex OAuth，`fal/*` 使用 `FAL_KEY`）。
|
||||
- 如果省略，`image_generate` 仍可推断出一个基于已认证提供商的默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的图像生成提供商。
|
||||
- `musicGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 用于共享的音乐生成能力和内置的 `music_generate` 工具。
|
||||
- 常见值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.5+`。
|
||||
- 如果省略，`music_generate` 仍然可以推断一个基于认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的音乐生成提供商。
|
||||
- 如果你直接选择某个 provider/model，也要配置匹配的提供商认证/API key。
|
||||
- `videoGenerationModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 典型值：`google/lyria-3-clip-preview`、`google/lyria-3-pro-preview` 或 `minimax/music-2.6`。
|
||||
- 如果省略，`music_generate` 仍可推断出一个基于已认证提供商的默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的音乐生成提供商。
|
||||
- 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。
|
||||
- `videoGenerationModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 用于共享的视频生成能力和内置的 `video_generate` 工具。
|
||||
- 常见值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
|
||||
- 如果省略，`video_generate` 仍然可以推断一个基于认证的提供商默认值。它会先尝试当前默认提供商，然后按 provider id 顺序尝试其余已注册的视频生成提供商。
|
||||
- 如果你直接选择某个 provider/model，也要配置匹配的提供商认证/API key。
|
||||
- 典型值：`qwen/wan2.6-t2v`、`qwen/wan2.6-i2v`、`qwen/wan2.6-r2v`、`qwen/wan2.6-r2v-flash` 或 `qwen/wan2.7-r2v`。
|
||||
- 如果省略，`video_generate` 仍可推断出一个基于已认证提供商的默认值。它会先尝试当前默认提供商，然后按提供商 id 顺序尝试其余已注册的视频生成提供商。
|
||||
- 如果你直接选择某个提供商/模型，也要配置匹配的提供商凭证/API 密钥。
|
||||
- 内置的 Qwen 视频生成提供商最多支持 1 个输出视频、1 张输入图像、4 个输入视频、10 秒时长，以及提供商级别的 `size`、`aspectRatio`、`resolution`、`audio` 和 `watermark` 选项。
|
||||
- `pdfModel`：接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- `pdfModel`：可接受字符串（`"provider/model"`）或对象（`{ primary, fallbacks }`）。
|
||||
- 用于 `pdf` 工具的模型路由。
|
||||
- 如果省略，PDF 工具会先回退到 `imageModel`，再回退到已解析的会话/默认模型。
|
||||
- 如果省略，PDF 工具会回退到 `imageModel`，再回退到已解析的会话/默认模型。
|
||||
- `pdfMaxBytesMb`：当调用时未传入 `maxBytesMb` 时，`pdf` 工具的默认 PDF 大小限制。
|
||||
- `pdfMaxPages`：`pdf` 工具在提取回退模式下考虑的默认最大页数。
|
||||
- `verboseDefault`：智能体的默认详细级别。取值：`"off"`、`"on"`、`"full"`。默认值：`"off"`。
|
||||
- `elevatedDefault`：智能体的默认增强输出级别。取值：`"off"`、`"on"`、`"ask"`、`"full"`。默认值：`"on"`。
|
||||
- `model.primary`：格式为 `provider/model`（例如，使用 API key 访问时为 `openai/gpt-5.4`，或使用 Codex OAuth 时为 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此更推荐显式使用 `provider/model`）。如果该提供商不再暴露已配置的默认模型，OpenClaw 会回退到第一个已配置的 provider/model，而不是暴露一个陈旧的、已移除提供商默认值。
|
||||
- `models`：`/model` 使用的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body`/`extraBody`）。
|
||||
- 安全编辑：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加条目。除非你传入 `--replace`，否则 `config set` 会拒绝任何会移除现有允许列表条目的替换操作。
|
||||
- 作用域为提供商的配置/新手引导流程会将选定的提供商模型合并到这个映射中，并保留其他已配置提供商的不相关条目。
|
||||
- 对于直接使用的 OpenAI Responses 模型，会自动启用服务端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
|
||||
- `model.primary`：格式为 `provider/model`（例如，使用 API 密钥访问时可用 `openai/gpt-5.4`，使用 Codex OAuth 时可用 `openai-codex/gpt-5.5`）。如果你省略提供商，OpenClaw 会先尝试别名，然后尝试与该精确模型 id 唯一匹配的已配置提供商，最后才回退到已配置的默认提供商（这是已弃用的兼容行为，因此建议优先使用明确的 `provider/model`）。如果该提供商不再公开已配置的默认模型，OpenClaw 会回退到第一个已配置的提供商/模型，而不是继续使用陈旧的、已移除提供商默认值。
|
||||
- `models`：用于 `/model` 的已配置模型目录和允许列表。每个条目都可以包含 `alias`（快捷方式）和 `params`（提供商特定参数，例如 `temperature`、`maxTokens`、`cacheRetention`、`context1m`、`responsesServerCompaction`、`responsesCompactThreshold`、`extra_body`/`extraBody`）。
|
||||
- 安全编辑方式：使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 来添加条目。除非传入 `--replace`，否则 `config set` 会拒绝会移除现有允许列表条目的替换操作。
|
||||
- 提供商作用域的配置/新手引导流程会将所选提供商模型合并到此映射中，并保留已配置的其他无关提供商。
|
||||
- 对于直接使用 OpenAI Responses 的模型，会自动启用服务器端压缩。使用 `params.responsesServerCompaction: false` 可停止注入 `context_management`，或者使用 `params.responsesCompactThreshold` 覆盖阈值。参见 [OpenAI 服务器端压缩](/zh-CN/providers/openai#server-side-compaction-responses-api)。
|
||||
- `params`：应用于所有模型的全局默认提供商参数。在 `agents.defaults.params` 中设置（例如 `{ cacheRetention: "long" }`）。
|
||||
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 id）按键覆盖。详见 [Prompt Caching](/zh-CN/reference/prompt-caching)。
|
||||
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果它与生成的请求键冲突，以额外请求体为准；非原生 completions 路由之后仍会剥离仅 OpenAI 使用的 `store`。
|
||||
- `embeddedHarness`：默认的低层嵌入式智能体运行时策略。省略 `runtime` 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册插件 harness 认领受支持的模型，或使用已注册的 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。像 `codex` 这样的显式插件运行时默认是失败即关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。保持模型引用采用规范格式 `provider/model`；通过运行时配置来选择 Codex、Claude CLI、Gemini CLI 和其他执行后端，而不是使用旧式运行时提供商前缀。参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes) 了解这与 provider/model 选择的区别。
|
||||
- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及回退项 add/remove 命令）会保存规范对象形式，并尽可能保留现有回退列表。
|
||||
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍是串行）。默认值：4。
|
||||
- `params` 合并优先级（配置）：`agents.defaults.params`（全局基础）会被 `agents.defaults.models["provider/model"].params`（按模型）覆盖，然后再由 `agents.list[].params`（匹配的智能体 id）按键覆盖。详见 [提示缓存](/zh-CN/reference/prompt-caching)。
|
||||
- `params.extra_body`/`params.extraBody`：高级透传 JSON，会合并到 OpenAI 兼容代理的 `api: "openai-completions"` 请求体中。如果与生成的请求键冲突，则额外请求体优先；非原生 completions 路由之后仍会剥离仅限 OpenAI 的 `store`。
|
||||
- `embeddedHarness`：默认的底层嵌入式智能体运行时策略。省略 `runtime` 时默认使用 OpenClaw Pi。使用 `runtime: "pi"` 可强制使用内置 PI harness，使用 `runtime: "auto"` 可让已注册插件 harness 接管受支持模型，或使用已注册 harness id，例如 `runtime: "codex"`。设置 `fallback: "none"` 可禁用自动回退到 PI。像 `codex` 这样的显式插件运行时默认是失败即关闭，除非你在同一覆盖作用域中设置 `fallback: "pi"`。请将模型引用保持为规范格式 `provider/model`；应通过运行时配置来选择 Codex、Claude CLI、Gemini CLI 及其他执行后端，而不是使用旧式运行时提供商前缀。关于它与提供商/模型选择的区别，请参见 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
|
||||
- 会修改这些字段的配置写入器（例如 `/models set`、`/models set-image` 以及故障切换添加/删除命令）会保存为规范对象形式，并在可能的情况下保留现有故障切换列表。
|
||||
- `maxConcurrent`：跨会话的最大并行智能体运行数（每个会话本身仍然串行）。默认值：4。
|
||||
|
||||
### `agents.defaults.embeddedHarness`
|
||||
|
||||
`embeddedHarness` 控制哪个底层执行器运行嵌入式智能体轮次。
|
||||
大多数部署应保留默认的 OpenClaw Pi 运行时。
|
||||
当受信任的插件提供原生 harness 时使用它，例如内置的
|
||||
Codex 应用服务器 harness。其思维模型请参见
|
||||
大多数部署应保持默认的 OpenClaw Pi 运行时。
|
||||
当可信插件提供原生 harness 时，可以使用此项，例如内置的
|
||||
Codex 应用服务器 harness。关于其心智模型，请参见
|
||||
[Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
|
||||
|
||||
```json5
|
||||
@ -390,14 +395,14 @@ Codex 应用服务器 harness。其思维模型请参见
|
||||
}
|
||||
```
|
||||
|
||||
- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册的 id 为 `codex`。
|
||||
- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，如果省略，默认回退为 `"pi"`，这样旧配置在没有插件 harness 认领运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，如果省略，默认回退为 `"none"`，这样缺少 harness 时会直接失败，而不是静默使用 PI。运行时覆盖项不会从更宽的作用域继承 `fallback`；如果你确实想要这种兼容性回退，请在显式运行时旁边同时设置 `fallback: "pi"`。所选插件 harness 的失败总是会直接暴露。
|
||||
- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 覆盖该进程的 fallback。
|
||||
- 对于仅使用 Codex 的部署，设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以出于可读性显式设置 `embeddedHarness.fallback: "none"`；这是显式插件运行时的默认值。
|
||||
- 在首次嵌入式运行后，harness 选择会按每个会话 id 固定。配置/环境变量的变更只影响新会话或已重置的会话，不影响现有转录。带有转录历史但未记录固定值的旧会话会被视为固定到 PI。`/status` 会报告生效的运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
|
||||
- 这只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的 provider/model 设置。
|
||||
- `runtime`：`"auto"`、`"pi"` 或已注册的插件 harness id。内置的 Codex 插件注册为 `codex`。
|
||||
- `fallback`：`"pi"` 或 `"none"`。在 `runtime: "auto"` 中，省略 `fallback` 时默认值为 `"pi"`，这样旧配置在没有插件 harness 接管运行时仍可继续使用 PI。在显式插件运行时模式下，例如 `runtime: "codex"`，省略 `fallback` 时默认值为 `"none"`，这样缺失 harness 时会直接失败，而不是静默使用 PI。运行时覆盖项不会从更宽泛的作用域继承 `fallback`；如果你明确想要这种兼容回退，请在显式运行时旁边同时设置 `fallback: "pi"`。所选插件 harness 的失败始终会直接显示出来。
|
||||
- 环境变量覆盖：`OPENCLAW_AGENT_RUNTIME=<id|auto|pi>` 会覆盖 `runtime`；`OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` 会覆盖该进程的 `fallback`。
|
||||
- 对于仅使用 Codex 的部署，请设置 `model: "openai/gpt-5.5"` 和 `embeddedHarness.runtime: "codex"`。你也可以显式设置 `embeddedHarness.fallback: "none"` 以增强可读性；对于显式插件运行时，这是默认值。
|
||||
- 在首次嵌入式运行之后，harness 选择会按会话 id 固定。配置/环境变量变更会影响新会话或已重置的会话，不会影响现有 transcript。具有 transcript 历史但没有记录固定值的旧会话会被视为固定到 PI。`/status` 会报告生效的运行时，例如 `Runtime: OpenClaw Pi Default` 或 `Runtime: OpenAI Codex`。
|
||||
- 此项只控制嵌入式聊天 harness。媒体生成、视觉、PDF、音乐、视频和 TTS 仍使用各自的提供商/模型设置。
|
||||
|
||||
**内置别名简写**（仅当模型位于 `agents.defaults.models` 中时适用）：
|
||||
**内置别名简写**（仅在模型位于 `agents.defaults.models` 中时适用）：
|
||||
|
||||
| 别名 | 模型 |
|
||||
| ------------------- | -------------------------------------------------- |
|
||||
@ -412,13 +417,13 @@ Codex 应用服务器 harness。其思维模型请参见
|
||||
|
||||
你配置的别名始终优先于默认值。
|
||||
|
||||
Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off` 或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
|
||||
Z.AI 模型默认启用 `tool_stream` 以进行工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设为 `false` 可禁用它。
|
||||
Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `adaptive` 思考。
|
||||
Z.AI GLM-4.x 模型会自动启用思考模式，除非你设置 `--thinking off`，或自行定义 `agents.defaults.models["zai/<model>"].params.thinking`。
|
||||
Z.AI 模型默认启用 `tool_stream` 以支持工具调用流式传输。将 `agents.defaults.models["zai/<model>"].params.tool_stream` 设置为 `false` 可禁用它。
|
||||
Anthropic Claude 4.6 模型在未设置显式思考级别时，默认使用 `adaptive` 思考。
|
||||
|
||||
### `agents.defaults.cliBackends`
|
||||
|
||||
用于纯文本回退运行（无工具调用）的可选 CLI 后端。当 API 提供商失败时，它可作为备用方案。
|
||||
用于纯文本回退运行（无工具调用）的可选 CLI 后端。在 API 提供商失败时可作为备用方案。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -447,12 +452,12 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
```
|
||||
|
||||
- CLI 后端以文本为主；工具始终禁用。
|
||||
- 设置 `sessionArg` 时支持会话。
|
||||
- 设置了 `sessionArg` 时支持会话。
|
||||
- 当 `imageArg` 接受文件路径时，支持图像透传。
|
||||
|
||||
### `agents.defaults.systemPromptOverride`
|
||||
|
||||
用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体（`agents.list[].systemPromptOverride`）设置。按智能体的值优先；空值或仅空白字符的值会被忽略。适用于受控提示实验。
|
||||
用固定字符串替换整个由 OpenClaw 组装的系统提示。可在默认级别（`agents.defaults.systemPromptOverride`）或按智能体设置（`agents.list[].systemPromptOverride`）。按智能体的值优先；空值或仅包含空白字符的值会被忽略。适用于受控的提示实验。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -466,7 +471,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
|
||||
### `agents.defaults.promptOverlays`
|
||||
|
||||
按模型家族应用的、与提供商无关的提示覆盖层。GPT-5 系列模型 id 会在不同提供商之间接收共享的行为契约；`personality` 只控制友好的交互风格层。
|
||||
按模型家族应用的、与提供商无关的提示覆盖层。GPT-5 家族模型 id 会在不同提供商之间接收共享的行为契约；`personality` 仅控制友好的交互风格层。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -483,28 +488,28 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
```
|
||||
|
||||
- `"friendly"`（默认）和 `"on"` 会启用友好的交互风格层。
|
||||
- `"off"` 只会禁用友好层；带标签的 GPT-5 行为契约仍然启用。
|
||||
- 当这个共享设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality`。
|
||||
- `"off"` 仅禁用友好层；带标签的 GPT-5 行为契约仍保持启用。
|
||||
- 当这个共享设置未设置时，仍会读取旧版的 `plugins.entries.openai.config.personality`。
|
||||
|
||||
### `agents.defaults.heartbeat`
|
||||
|
||||
定期 Heartbeat 运行。
|
||||
周期性 Heartbeat 运行。
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
heartbeat: {
|
||||
every: "30m", // 0m 禁用
|
||||
every: "30m", // 0m 表示禁用
|
||||
model: "openai/gpt-5.4-mini",
|
||||
includeReasoning: false,
|
||||
includeSystemPromptSection: true, // 默认值：true；false 会从系统提示中省略 Heartbeat 部分
|
||||
lightContext: false, // 默认值：false；true 仅保留工作区引导文件中的 HEARTBEAT.md
|
||||
isolatedSession: false, // 默认值：false；true 会在全新会话中运行每次 heartbeat（无对话历史）
|
||||
includeSystemPromptSection: true, // 默认：true；false 会省略系统提示中的 Heartbeat 部分
|
||||
lightContext: false, // 默认：false；true 仅保留工作区引导文件中的 HEARTBEAT.md
|
||||
isolatedSession: false, // 默认：false；true 会让每次 heartbeat 都在全新会话中运行（无对话历史）
|
||||
session: "main",
|
||||
to: "+15555550123",
|
||||
directPolicy: "allow", // allow（默认）| block
|
||||
target: "none", // 默认值：none | 可选值：last | whatsapp | telegram | discord | ...
|
||||
target: "none", // 默认：none | 可选：last | whatsapp | telegram | discord | ...
|
||||
prompt: "Read HEARTBEAT.md if it exists...",
|
||||
ackMaxChars: 300,
|
||||
suppressToolErrorWarnings: false,
|
||||
@ -515,15 +520,15 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
}
|
||||
```
|
||||
|
||||
- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API key 认证）或 `1h`（OAuth 认证）。设为 `0m` 可禁用。
|
||||
- `includeSystemPromptSection`：为 false 时，会从系统提示中省略 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。
|
||||
- `suppressToolErrorWarnings`：为 true 时，在 Heartbeat 运行期间抑制工具错误警告负载。
|
||||
- `timeoutSeconds`：Heartbeat 智能体轮次在被中止前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。
|
||||
- `every`：时长字符串（ms/s/m/h）。默认值：`30m`（API 密钥认证）或 `1h`（OAuth 认证）。设置为 `0m` 可禁用。
|
||||
- `includeSystemPromptSection`：为 false 时，会省略系统提示中的 Heartbeat 部分，并跳过将 `HEARTBEAT.md` 注入引导上下文。默认值：`true`。
|
||||
- `suppressToolErrorWarnings`：为 true 时，会在 Heartbeat 运行期间抑制工具错误警告负载。
|
||||
- `timeoutSeconds`：在 Heartbeat 智能体轮次被中止之前允许的最长秒数。留空则使用 `agents.defaults.timeoutSeconds`。
|
||||
- `directPolicy`：直接/私信投递策略。`allow`（默认）允许直接目标投递。`block` 会抑制直接目标投递，并发出 `reason=dm-blocked`。
|
||||
- `lightContext`：为 true 时，Heartbeat 运行使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。
|
||||
- `isolatedSession`：为 true 时，每次 Heartbeat 都会在一个没有先前对话历史的全新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降低到约 2-5K token。
|
||||
- `lightContext`：为 true 时，Heartbeat 运行会使用轻量级引导上下文，并且只保留工作区引导文件中的 `HEARTBEAT.md`。
|
||||
- `isolatedSession`：为 true 时，每次 Heartbeat 都会在一个没有任何先前对话历史的新会话中运行。与 cron `sessionTarget: "isolated"` 使用相同的隔离模式。可将每次 Heartbeat 的 token 成本从约 100K 降低到约 2-5K token。
|
||||
- 按智能体设置：使用 `agents.list[].heartbeat`。当任意智能体定义了 `heartbeat` 时，**只有这些智能体**会运行 Heartbeat。
|
||||
- Heartbeat 会运行完整的智能体轮次——更短的间隔会消耗更多 token。
|
||||
- Heartbeat 会运行完整的智能体轮次——间隔越短，消耗的 token 越多。
|
||||
|
||||
### `agents.defaults.compaction`
|
||||
|
||||
@ -533,16 +538,16 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
defaults: {
|
||||
compaction: {
|
||||
mode: "safeguard", // default | safeguard
|
||||
provider: "my-provider", // 已注册的 compaction provider 插件 id（可选）
|
||||
provider: "my-provider", // 已注册 compaction 提供商插件的 id（可选）
|
||||
timeoutSeconds: 900,
|
||||
reserveTokensFloor: 24000,
|
||||
keepRecentTokens: 50000,
|
||||
identifierPolicy: "strict", // strict | off | custom
|
||||
identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // 当 identifierPolicy=custom 时使用
|
||||
qualityGuard: { enabled: true, maxRetries: 1 },
|
||||
postCompactionSections: ["Session Startup", "Red Lines"], // [] 禁用重新注入
|
||||
model: "openrouter/anthropic/claude-sonnet-4-6", // 可选的仅 compaction 使用的模型覆盖
|
||||
notifyUser: true, // 在 compaction 开始和完成时发送简短通知（默认值：false）
|
||||
postCompactionSections: ["Session Startup", "Red Lines"], // [] 表示禁用重新注入
|
||||
model: "openrouter/anthropic/claude-sonnet-4-6", // 可选，仅用于 compaction 的模型覆盖
|
||||
notifyUser: true, // 在 compaction 开始和完成时发送简短通知（默认：false）
|
||||
memoryFlush: {
|
||||
enabled: true,
|
||||
softThresholdTokens: 6000,
|
||||
@ -556,20 +561,20 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
```
|
||||
|
||||
- `mode`：`default` 或 `safeguard`（针对长历史的分块摘要）。参见 [Compaction](/zh-CN/concepts/compaction)。
|
||||
- `provider`：已注册的 compaction provider 插件 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时回退到内置实现。设置 provider 会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
|
||||
- `timeoutSeconds`：OpenClaw 在中止单次 compaction 操作前允许的最大秒数。默认值：`900`。
|
||||
- `keepRecentTokens`：Pi 切分点预算，用于原样保留最近的转录尾部。手动 `/compact` 在显式设置时会遵循它；否则手动 compaction 是一个硬检查点。
|
||||
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预置内置的不透明标识符保留指南。
|
||||
- `provider`：已注册 compaction 提供商插件的 id。设置后，会调用该提供商的 `summarize()`，而不是使用内置 LLM 摘要。失败时会回退到内置实现。设置提供商会强制使用 `mode: "safeguard"`。参见 [Compaction](/zh-CN/concepts/compaction)。
|
||||
- `timeoutSeconds`：OpenClaw 中止单次 compaction 操作前允许的最大秒数。默认值：`900`。
|
||||
- `keepRecentTokens`：Pi 截断点预算，用于按原样保留最近的 transcript 尾部。手动 `/compact` 在显式设置时会遵循此值；否则手动 compaction 是一个硬检查点。
|
||||
- `identifierPolicy`：`strict`（默认）、`off` 或 `custom`。`strict` 会在 compaction 摘要期间预先添加内置的、不透明标识符保留指导。
|
||||
- `identifierInstructions`：当 `identifierPolicy=custom` 时使用的可选自定义标识符保留文本。
|
||||
- `qualityGuard`：对 safeguard 摘要执行输出格式异常时重试检查。在 safeguard 模式下默认启用；设为 `enabled: false` 可跳过审计。
|
||||
- `postCompactionSections`：可选的 `AGENTS.md` H2/H3 小节名称，在 compaction 后重新注入。默认值为 `["Session Startup", "Red Lines"]`；设为 `[]` 可禁用重新注入。当未设置，或显式设置为这对默认值时，也接受旧版 `Every Session`/`Safety` 标题作为兼容回退。
|
||||
- `model`：仅用于 compaction 摘要的可选 `provider/model-id` 覆盖。当你希望主会话继续使用一个模型，而 compaction 摘要使用另一个模型时使用；未设置时，compaction 使用会话的主模型。
|
||||
- `notifyUser`：为 `true` 时，在 compaction 开始和完成时向用户发送简短通知（例如 “Compacting context...” 和 “Compaction complete”）。默认关闭，以保持 compaction 静默。
|
||||
- `memoryFlush`：自动 compaction 前的静默智能体轮次，用于存储持久记忆。工作区为只读时会跳过。
|
||||
- `qualityGuard`：对 safeguard 摘要进行输出格式异常时重试的检查。在 safeguard 模式下默认启用；设置 `enabled: false` 可跳过审计。
|
||||
- `postCompactionSections`：compaction 后重新注入的可选 `AGENTS.md` H2/H3 章节名称。默认值为 `["Session Startup", "Red Lines"]`；设置为 `[]` 可禁用重新注入。当未设置或明确设置为该默认组合时，旧版的 `Every Session`/`Safety` 标题也会作为兼容性回退被接受。
|
||||
- `model`：可选的 `provider/model-id` 覆盖，仅用于 compaction 摘要。当主会话应继续使用某个模型，但 compaction 摘要应使用另一个模型时，可使用此项；未设置时，compaction 会使用会话的主模型。
|
||||
- `notifyUser`：为 `true` 时，会在 compaction 开始和完成时向用户发送简短通知（例如“Compacting context...”和“Compaction complete”）。默认禁用，以保持 compaction 静默进行。
|
||||
- `memoryFlush`：自动 compaction 前的静默智能体轮次，用于存储持久 memory。当工作区为只读时会跳过。
|
||||
|
||||
### `agents.defaults.contextPruning`
|
||||
|
||||
在发送给 LLM 之前，从内存上下文中裁剪**旧的工具结果**。**不会**修改磁盘上的会话历史。
|
||||
在将内容发送给 LLM 之前，从内存上下文中修剪**旧工具结果**。**不会**修改磁盘上的会话历史。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -593,23 +598,23 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
|
||||
<Accordion title="`cache-ttl` 模式行为">
|
||||
|
||||
- `mode: "cache-ttl"` 会启用裁剪过程。
|
||||
- `ttl` 控制多久之后才能再次运行裁剪（从上次缓存触碰后开始计算）。
|
||||
- 裁剪会先对过大的工具结果进行软裁剪，然后在需要时对更旧的工具结果执行硬清除。
|
||||
- `mode: "cache-ttl"` 会启用修剪流程。
|
||||
- `ttl` 控制何时可再次运行修剪（在上次缓存触碰之后）。
|
||||
- 修剪会先对过大的工具结果进行软修剪，如仍有需要，再对更旧的工具结果执行硬清除。
|
||||
|
||||
**软裁剪**会保留开头和结尾，并在中间插入 `...`。
|
||||
**软修剪**会保留开头和结尾，并在中间插入 `...`。
|
||||
|
||||
**硬清除**会用占位符替换整个工具结果。
|
||||
|
||||
说明：
|
||||
注意：
|
||||
|
||||
- 图像块永远不会被裁剪/清除。
|
||||
- 比例按字符计算（近似），不是精确 token 数。
|
||||
- 如果助手消息少于 `keepLastAssistants` 条，则跳过裁剪。
|
||||
- 图像块永远不会被修剪/清除。
|
||||
- 比例是基于字符的（近似值），不是精确 token 计数。
|
||||
- 如果助手消息少于 `keepLastAssistants` 条，则会跳过修剪。
|
||||
|
||||
</Accordion>
|
||||
|
||||
行为细节参见 [会话裁剪](/zh-CN/concepts/session-pruning)。
|
||||
行为细节请参见 [会话修剪](/zh-CN/concepts/session-pruning)。
|
||||
|
||||
### 分块流式传输
|
||||
|
||||
@ -628,10 +633,10 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
```
|
||||
|
||||
- 非 Telegram 渠道需要显式设置 `*.blockStreaming: true` 才会启用分块回复。
|
||||
- 渠道覆盖项：`channels.<channel>.blockStreamingCoalesce`（以及按账号的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
|
||||
- `humanDelay`：分块回复之间的随机停顿。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。
|
||||
- 渠道覆盖项：`channels.<channel>.blockStreamingCoalesce`（以及按账户的变体）。Signal/Slack/Discord/Google Chat 默认 `minChars: 1500`。
|
||||
- `humanDelay`：分块回复之间的随机暂停。`natural` = 800–2500 ms。按智能体覆盖：`agents.list[].humanDelay`。
|
||||
|
||||
行为和分块细节参见 [流式传输](/zh-CN/concepts/streaming)。
|
||||
行为和分块细节请参见 [流式传输](/zh-CN/concepts/streaming)。
|
||||
|
||||
### 输入中指示器
|
||||
|
||||
@ -646,7 +651,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
}
|
||||
```
|
||||
|
||||
- 默认值：直接聊天/提及时使用 `instant`，未提及的群聊使用 `message`。
|
||||
- 默认值：直接聊天/提及时为 `instant`，未被提及的群聊中为 `message`。
|
||||
- 按会话覆盖：`session.typingMode`、`session.typingIntervalSeconds`。
|
||||
|
||||
参见 [输入中指示器](/zh-CN/concepts/typing-indicators)。
|
||||
@ -755,19 +760,19 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
**后端：**
|
||||
|
||||
- `docker`：本地 Docker 运行时（默认）
|
||||
- `ssh`：通用 SSH 支持的远程运行时
|
||||
- `ssh`：基于通用 SSH 的远程运行时
|
||||
- `openshell`：OpenShell 运行时
|
||||
|
||||
当选择 `backend: "openshell"` 时，运行时专属设置会移动到
|
||||
当选择 `backend: "openshell"` 时，运行时特定设置会移动到
|
||||
`plugins.entries.openshell.config`。
|
||||
|
||||
**SSH 后端配置：**
|
||||
|
||||
- `target`：`user@host[:port]` 形式的 SSH 目标
|
||||
- `command`：SSH 客户端命令（默认值：`ssh`）
|
||||
- `workspaceRoot`：用于按作用域工作区的远程绝对根路径
|
||||
- `command`：SSH 客户端命令（默认：`ssh`）
|
||||
- `workspaceRoot`：用于按作用域工作区的远程绝对根目录
|
||||
- `identityFile` / `certificateFile` / `knownHostsFile`：传递给 OpenSSH 的现有本地文件
|
||||
- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其实体化为临时文件
|
||||
- `identityData` / `certificateData` / `knownHostsData`：内联内容或 SecretRefs，OpenClaw 会在运行时将其写入临时文件
|
||||
- `strictHostKeyChecking` / `updateHostKeys`：OpenSSH 主机密钥策略开关
|
||||
|
||||
**SSH 认证优先级：**
|
||||
@ -775,25 +780,25 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
- `identityData` 优先于 `identityFile`
|
||||
- `certificateData` 优先于 `certificateFile`
|
||||
- `knownHostsData` 优先于 `knownHostsFile`
|
||||
- 由 SecretRef 支持的 `*Data` 值会在沙箱会话启动前，从当前激活的 secrets 运行时快照中解析
|
||||
- 由 SecretRef 支持的 `*Data` 值会在沙箱会话开始前，从当前启用的 secrets 运行时快照中解析
|
||||
|
||||
**SSH 后端行为：**
|
||||
|
||||
- 在创建或重建后对远程工作区进行一次初始化
|
||||
- 然后保持远程 SSH 工作区为规范副本
|
||||
- 在创建或重新创建后，先进行一次远程工作区初始化
|
||||
- 然后保持远程 SSH 工作区为规范工作区
|
||||
- 通过 SSH 路由 `exec`、文件工具和媒体路径
|
||||
- 不会自动将远程更改同步回主机
|
||||
- 不支持沙箱浏览器容器
|
||||
|
||||
**工作区访问：**
|
||||
|
||||
- `none`：位于 `~/.openclaw/sandboxes` 下的按作用域沙箱工作区
|
||||
- `none`：在 `~/.openclaw/sandboxes` 下使用按作用域划分的沙箱工作区
|
||||
- `ro`：沙箱工作区位于 `/workspace`，智能体工作区以只读方式挂载到 `/agent`
|
||||
- `rw`：智能体工作区以读写方式挂载到 `/workspace`
|
||||
|
||||
**作用域：**
|
||||
|
||||
- `session`：每会话一个容器 + 工作区
|
||||
- `session`：每个会话一个容器 + 工作区
|
||||
- `agent`：每个智能体一个容器 + 工作区（默认）
|
||||
- `shared`：共享容器和工作区（无跨会话隔离）
|
||||
|
||||
@ -812,7 +817,7 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
remoteAgentWorkspaceDir: "/agent",
|
||||
gateway: "lab", // 可选
|
||||
gatewayEndpoint: "https://lab.example", // 可选
|
||||
policy: "strict", // 可选的 OpenShell policy id
|
||||
policy: "strict", // 可选 OpenShell 策略 id
|
||||
providers: ["openai"], // 可选
|
||||
autoProviders: true,
|
||||
timeoutSeconds: 120,
|
||||
@ -825,29 +830,29 @@ Anthropic Claude 4.6 模型在未显式设置思考级别时，默认使用 `ada
|
||||
|
||||
**OpenShell 模式：**
|
||||
|
||||
- `mirror`：在执行前将本地内容初始化到远程，执行后再同步回本地；本地工作区保持为规范副本
|
||||
- `remote`：在创建沙箱时仅对远程进行一次初始化，然后保持远程工作区为规范副本
|
||||
- `mirror`：在执行前将本地内容初始化到远程，执行后再同步回本地；本地工作区保持为规范工作区
|
||||
- `remote`：在创建沙箱时仅将本地内容初始化到远程一次，之后保持远程工作区为规范工作区
|
||||
|
||||
在 `remote` 模式下，在 OpenClaw 之外于主机本地所做的编辑，在初始化步骤之后不会自动同步到沙箱中。
|
||||
传输方式是通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期和可选的镜像同步。
|
||||
在 `remote` 模式下，在 OpenClaw 外部于主机本地进行的编辑，在初始化步骤之后不会自动同步到沙箱中。
|
||||
传输层通过 SSH 连接到 OpenShell 沙箱，但插件负责沙箱生命周期以及可选的镜像同步。
|
||||
|
||||
**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。它需要网络出口、可写根文件系统以及 root 用户。
|
||||
**`setupCommand`** 会在容器创建后运行一次（通过 `sh -lc`）。需要网络出口、可写根文件系统和 root 用户。
|
||||
|
||||
**容器默认使用 `network: "none"`** —— 如果智能体需要出站访问，请设置为 `"bridge"`（或自定义 bridge 网络）。
|
||||
`"host"` 被阻止。默认情况下，`"container:<id>"` 也被阻止，除非你显式设置
|
||||
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（紧急破窗模式）。
|
||||
`"host"` 会被阻止。默认也会阻止 `"container:<id>"`，除非你显式设置
|
||||
`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true`（破窗操作）。
|
||||
|
||||
**入站附件** 会暂存到当前活动工作区中的 `media/inbound/*`。
|
||||
**入站附件** 会被暂存到当前工作区的 `media/inbound/*` 中。
|
||||
|
||||
**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的 binds 会合并。
|
||||
**`docker.binds`** 会挂载额外的主机目录；全局和按智能体的挂载会合并。
|
||||
|
||||
**沙箱浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。不需要在 `openclaw.json` 中启用 `browser.enabled`。
|
||||
**沙箱隔离浏览器**（`sandbox.browser.enabled`）：在容器中运行 Chromium + CDP。noVNC URL 会注入到系统提示中。无需在 `openclaw.json` 中启用 `browser.enabled`。
|
||||
noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有效的 token URL（而不是在共享 URL 中暴露密码）。
|
||||
|
||||
- `allowHostControl: false`（默认）会阻止沙箱隔离会话以主机浏览器为目标。
|
||||
- `network` 默认值为 `openclaw-sandbox-browser`（专用 bridge 网络）。仅当你明确需要全局 bridge 连通性时，才设置为 `bridge`。
|
||||
- `cdpSourceRange` 可选地将容器边缘的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。
|
||||
- `sandbox.browser.binds` 仅会将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
|
||||
- `network` 默认为 `openclaw-sandbox-browser`（专用 bridge 网络）。只有在你明确需要全局 bridge 连通性时，才设置为 `bridge`。
|
||||
- `cdpSourceRange` 可选地将容器边界处的 CDP 入站限制为某个 CIDR 范围（例如 `172.21.0.1/32`）。
|
||||
- `sandbox.browser.binds` 仅将额外的主机目录挂载到沙箱浏览器容器中。设置后（包括 `[]`），它会替换浏览器容器的 `docker.binds`。
|
||||
- 启动默认值定义在 `scripts/sandbox-browser-entrypoint.sh` 中，并针对容器主机进行了调优：
|
||||
- `--remote-debugging-address=127.0.0.1`
|
||||
- `--remote-debugging-port=<derived from OPENCLAW_BROWSER_CDP_PORT>`
|
||||
@ -867,15 +872,15 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有
|
||||
- `--metrics-recording-only`
|
||||
- `--disable-extensions`（默认启用）
|
||||
- `--disable-3d-apis`、`--disable-software-rasterizer` 和 `--disable-gpu`
|
||||
默认启用；如果你的工作流需要 WebGL/3D，可通过
|
||||
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些标志。
|
||||
- 如果你的工作流依赖扩展，使用
|
||||
`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 可重新启用扩展。
|
||||
- `--renderer-process-limit=2` 可以通过
|
||||
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 修改；设为 `0` 可使用 Chromium 的
|
||||
默认进程限制。
|
||||
- 当启用 `noSandbox` 时，还会附加 `--no-sandbox`。
|
||||
- 这些默认值属于容器镜像基线；如需更改容器默认值，请使用带自定义入口点的自定义浏览器镜像。
|
||||
默认启用；如果 WebGL/3D 使用场景需要，可通过
|
||||
`OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0` 禁用这些默认标志。
|
||||
- 如果你的工作流依赖扩展，可通过
|
||||
`OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` 重新启用扩展。
|
||||
- `--renderer-process-limit=2` 可通过
|
||||
`OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>` 修改；设置为 `0` 可使用 Chromium 的默认进程限制。
|
||||
- 此外，当启用 `noSandbox` 时还会添加 `--no-sandbox`。
|
||||
- 这些默认值是容器镜像基线；若要更改容器默认值，请使用带有自定义
|
||||
入口点的自定义浏览器镜像。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -885,7 +890,7 @@ noVNC 观察者访问默认使用 VNC 认证，OpenClaw 会发出一个短时有
|
||||
|
||||
```bash
|
||||
scripts/sandbox-setup.sh # 主沙箱镜像
|
||||
scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
scripts/sandbox-browser-setup.sh # 可选的浏览器镜像
|
||||
```
|
||||
|
||||
### `agents.list`（按智能体覆盖）
|
||||
@ -906,7 +911,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
fastModeDefault: false, // 按智能体覆盖快速模式
|
||||
embeddedHarness: { runtime: "auto", fallback: "pi" },
|
||||
params: { cacheRetention: "none" }, // 按键覆盖匹配的 defaults.models params
|
||||
skills: ["docs-search"], // 设置后替换 agents.defaults.skills
|
||||
skills: ["docs-search"], // 设置后会替换 agents.defaults.skills
|
||||
identity: {
|
||||
name: "Samantha",
|
||||
theme: "helpful sloth",
|
||||
@ -938,26 +943,26 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
```
|
||||
|
||||
- `id`：稳定的智能体 id（必填）。
|
||||
- `default`：如果设置了多个，以第一个为准（会记录警告）。如果一个都没设置，则列表中的第一个条目为默认值。
|
||||
- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖二者（`[]` 会禁用全局回退）。只覆盖 `primary` 的 cron 作业仍会继承默认回退，除非你设置 `fallbacks: []`。
|
||||
- `params`：按智能体的流参数，会合并到 `agents.defaults.models` 中选定模型条目之上。适合做智能体专属覆盖，例如 `cacheRetention`、`temperature` 或 `maxTokens`，而无需复制整个模型目录。
|
||||
- `skills`：可选的按智能体 Skills 允许列表。如果省略，在设置了 `agents.defaults.skills` 时，智能体会继承它；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。
|
||||
- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当没有按消息或按会话的覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选 provider/model 配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保留提供商自有的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
|
||||
- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。在没有按消息或按会话的推理覆盖时生效。
|
||||
- `fastModeDefault`：可选的按智能体快速模式默认值（`true | false`）。在没有按消息或按会话的快速模式覆盖时生效。
|
||||
- `embeddedHarness`：可选的按智能体低层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可使某个智能体仅使用 Codex，而其他智能体仍保留默认的 `auto` 模式 PI 回退。
|
||||
- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，使用 `type: "acp"` 和 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
|
||||
- `default`：当设置了多个时，以第一个为准（会记录警告）。如果都未设置，则列表中的第一个条目为默认值。
|
||||
- `model`：字符串形式只覆盖 `primary`；对象形式 `{ primary, fallbacks }` 会同时覆盖两者（`[]` 表示禁用全局故障切换）。只覆盖 `primary` 的 cron 作业仍会继承默认故障切换，除非你设置 `fallbacks: []`。
|
||||
- `params`：按智能体的流参数，会合并覆盖到 `agents.defaults.models` 中所选模型条目之上。用它为特定智能体覆盖如 `cacheRetention`、`temperature` 或 `maxTokens` 等参数，而无需复制整个模型目录。
|
||||
- `skills`：可选的按智能体 Skills 允许列表。如果省略，则在已设置时该智能体会继承 `agents.defaults.skills`；显式列表会替换默认值而不是合并，`[]` 表示无 Skills。
|
||||
- `thinkingDefault`：可选的按智能体默认思考级别（`off | minimal | low | medium | high | xhigh | adaptive | max`）。当未设置按消息或会话覆盖时，它会覆盖该智能体的 `agents.defaults.thinkingDefault`。所选提供商/模型配置决定哪些值有效；对于 Google Gemini，`adaptive` 会保持提供商控制的动态思考（Gemini 3/3.1 上省略 `thinkingLevel`，Gemini 2.5 上使用 `thinkingBudget: -1`）。
|
||||
- `reasoningDefault`：可选的按智能体默认推理可见性（`on | off | stream`）。在未设置按消息或会话推理覆盖时生效。
|
||||
- `fastModeDefault`：可选的按智能体默认快速模式（`true | false`）。在未设置按消息或会话快速模式覆盖时生效。
|
||||
- `embeddedHarness`：可选的按智能体底层 harness 策略覆盖。使用 `{ runtime: "codex" }` 可让某个智能体仅使用 Codex，而其他智能体继续在 `auto` 模式下使用默认的 PI 回退。
|
||||
- `runtime`：可选的按智能体运行时描述符。当智能体应默认使用 ACP harness 会话时，可使用 `type: "acp"` 以及 `runtime.acp` 默认值（`agent`、`backend`、`mode`、`cwd`）。
|
||||
- `identity.avatar`：工作区相对路径、`http(s)` URL 或 `data:` URI。
|
||||
- `identity` 会派生默认值：`ackReaction` 来自 `emoji`，`mentionPatterns` 来自 `name`/`emoji`。
|
||||
- `subagents.allowAgents`：`sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅相同智能体）。
|
||||
- 沙箱继承保护：如果请求方会话处于沙箱中，`sessions_spawn` 会拒绝那些会以非沙箱方式运行的目标。
|
||||
- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置；默认值：false）。
|
||||
- `identity` 会派生默认值：`ackReaction` 取自 `emoji`，`mentionPatterns` 取自 `name`/`emoji`。
|
||||
- `subagents.allowAgents`：用于 `sessions_spawn` 的智能体 id 允许列表（`["*"]` = 任意；默认：仅同一智能体）。
|
||||
- 沙箱继承保护：如果请求方会话处于沙箱隔离中，`sessions_spawn` 会拒绝那些会在无沙箱隔离下运行的目标。
|
||||
- `subagents.requireAgentId`：为 true 时，会阻止省略 `agentId` 的 `sessions_spawn` 调用（强制显式选择配置文件；默认：false）。
|
||||
|
||||
---
|
||||
|
||||
## 多智能体路由
|
||||
|
||||
在一个 Gateway 网关内运行多个彼此隔离的智能体。参见 [Multi-Agent](/zh-CN/concepts/multi-agent)。
|
||||
在一个 Gateway 网关中运行多个彼此隔离的智能体。参见 [多智能体](/zh-CN/concepts/multi-agent)。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -976,14 +981,14 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
|
||||
### 绑定匹配字段
|
||||
|
||||
- `type`（可选）：普通路由使用 `route`（缺失 `type` 时默认为 route），持久 ACP 对话绑定使用 `acp`。
|
||||
- `type`（可选）：普通路由用 `route`（缺失时默认即为 route），持久 ACP 对话绑定用 `acp`。
|
||||
- `match.channel`（必填）
|
||||
- `match.accountId`（可选；`*` = 任意账号；省略 = 默认账号）
|
||||
- `match.accountId`（可选；`*` = 任意账户；省略 = 默认账户）
|
||||
- `match.peer`（可选；`{ kind: direct|group|channel, id }`）
|
||||
- `match.guildId` / `match.teamId`（可选；特定渠道使用）
|
||||
- `acp`（可选；仅用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
|
||||
- `match.guildId` / `match.teamId`（可选；特定于渠道）
|
||||
- `acp`（可选；仅适用于 `type: "acp"`）：`{ mode, label, cwd, backend }`
|
||||
|
||||
**确定性匹配顺序：**
|
||||
**确定性的匹配顺序：**
|
||||
|
||||
1. `match.peer`
|
||||
2. `match.guildId`
|
||||
@ -992,9 +997,9 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
5. `match.accountId: "*"`（整个渠道范围）
|
||||
6. 默认智能体
|
||||
|
||||
在每一层中，第一个匹配的 `bindings` 条目获胜。
|
||||
在每一层级内，第一个匹配的 `bindings` 条目获胜。
|
||||
|
||||
对于 `type: "acp"` 条目，OpenClaw 按精确的对话身份（`match.channel` + 账号 + `match.peer.id`）解析，不使用上面的 route 绑定层级顺序。
|
||||
对于 `type: "acp"` 条目，OpenClaw 会按精确的对话身份（`match.channel` + account + `match.peer.id`）进行解析，不使用上述 route 绑定层级顺序。
|
||||
|
||||
### 按智能体访问配置
|
||||
|
||||
@ -1045,7 +1050,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="无文件系统访问（仅消息）">
|
||||
<Accordion title="无文件系统访问（仅消息传递）">
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -1117,7 +1122,7 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
},
|
||||
resetTriggers: ["/new", "/reset"],
|
||||
store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
|
||||
parentForkMaxTokens: 100000, // 高于此 token 数时跳过父线程分叉（0 表示禁用）
|
||||
parentForkMaxTokens: 100000, // 父线程 token 数超过此值时跳过父线程 fork（0 表示禁用）
|
||||
maintenance: {
|
||||
mode: "warn", // warn | enforce
|
||||
pruneAfter: "30d",
|
||||
@ -1129,10 +1134,10 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
},
|
||||
threadBindings: {
|
||||
enabled: true,
|
||||
idleHours: 24, // 默认按小时计算的不活动自动取消聚焦（`0` 表示禁用）
|
||||
idleHours: 24, // 默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用）
|
||||
maxAgeHours: 0, // 默认按小时计算的硬性最大时长（`0` 表示禁用）
|
||||
},
|
||||
mainKey: "main", // 旧版字段（运行时始终使用 "main"）
|
||||
mainKey: "main", // 旧字段（运行时始终使用 "main"）
|
||||
agentToAgent: { maxPingPongTurns: 5 },
|
||||
sendPolicy: {
|
||||
rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
|
||||
@ -1145,33 +1150,33 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
<Accordion title="会话字段详情">
|
||||
|
||||
- **`scope`**：群聊上下文的基础会话分组策略。
|
||||
- `per-sender`（默认）：在一个渠道上下文内，每个发送者都有独立会话。
|
||||
- `global`：渠道上下文中的所有参与者共享一个会话（仅在确实需要共享上下文时使用）。
|
||||
- `per-sender`（默认）：在一个渠道上下文内，每个发送者都有隔离的会话。
|
||||
- `global`：一个渠道上下文中的所有参与者共享同一个会话（仅在明确需要共享上下文时使用）。
|
||||
- **`dmScope`**：私信的分组方式。
|
||||
- `main`：所有私信共享主会话。
|
||||
- `per-peer`：按发送者 id 跨渠道隔离。
|
||||
- `per-peer`：按发送者 id 在跨渠道范围内隔离。
|
||||
- `per-channel-peer`：按渠道 + 发送者隔离（推荐用于多用户收件箱）。
|
||||
- `per-account-channel-peer`：按账号 + 渠道 + 发送者隔离（推荐用于多账号）。
|
||||
- `per-account-channel-peer`：按账户 + 渠道 + 发送者隔离（推荐用于多账户）。
|
||||
- **`identityLinks`**：将规范 id 映射到带提供商前缀的 peer，用于跨渠道共享会话。
|
||||
- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，以先到期者为准。
|
||||
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 可作为 `direct` 的别名。
|
||||
- **`parentForkMaxTokens`**：创建分叉线程会话时允许的父会话 `totalTokens` 最大值（默认 `100000`）。
|
||||
- 如果父会话的 `totalTokens` 高于该值，OpenClaw 会启动一个全新的线程会话，而不是继承父转录历史。
|
||||
- 设为 `0` 可禁用此保护，并始终允许父会话分叉。
|
||||
- **`mainKey`**：旧版字段。运行时始终对主直接聊天桶使用 `"main"`。
|
||||
- **`agentToAgent.maxPingPongTurns`**：在智能体到智能体交换期间，智能体之间最大往返信息轮次（整数，范围：`0`–`5`）。`0` 会禁用来回链式回复。
|
||||
- **`sendPolicy`**：可按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个拒绝规则优先。
|
||||
- **`reset`**：主重置策略。`daily` 会在本地时间 `atHour` 重置；`idle` 会在 `idleMinutes` 后重置。当两者都配置时，先到期者优先。
|
||||
- **`resetByType`**：按类型覆盖（`direct`、`group`、`thread`）。旧版 `dm` 仍可作为 `direct` 的别名。
|
||||
- **`parentForkMaxTokens`**：创建 fork 出来的线程会话时，父会话允许的最大 `totalTokens`（默认 `100000`）。
|
||||
- 如果父会话的 `totalTokens` 高于此值，OpenClaw 会启动一个新的线程会话，而不是继承父 transcript 历史。
|
||||
- 设置为 `0` 可禁用此保护，并始终允许从父会话 fork。
|
||||
- **`mainKey`**：旧字段。运行时始终对主直接聊天桶使用 `"main"`。
|
||||
- **`agentToAgent.maxPingPongTurns`**：在智能体到智能体交互期间，智能体之间允许的最大来回回复轮次（整数，范围：`0`–`5`）。`0` 表示禁用乒乓式链式回复。
|
||||
- **`sendPolicy`**：按 `channel`、`chatType`（`direct|group|channel`，旧版 `dm` 仍可作为别名）、`keyPrefix` 或 `rawKeyPrefix` 匹配。第一个 deny 优先。
|
||||
- **`maintenance`**：会话存储清理 + 保留控制。
|
||||
- `mode`：`warn` 仅发出警告；`enforce` 则应用清理。
|
||||
- `pruneAfter`：过期条目的时间阈值（默认 `30d`）。
|
||||
- `maxEntries`：`sessions.json` 中条目的最大数量（默认 `500`）。
|
||||
- `rotateBytes`：当 `sessions.json` 超过此大小时执行轮转（默认 `10mb`）。
|
||||
- `resetArchiveRetention`：`*.reset.<timestamp>` 转录归档的保留时长。默认等于 `pruneAfter`；设为 `false` 可禁用。
|
||||
- `maxDiskBytes`：可选的会话目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先移除最旧的制品/会话。
|
||||
- `mode`：`warn` 仅发出警告；`enforce` 会执行清理。
|
||||
- `pruneAfter`：过期条目的年龄截止值（默认 `30d`）。
|
||||
- `maxEntries`：`sessions.json` 中的最大条目数（默认 `500`）。
|
||||
- `rotateBytes`：当 `sessions.json` 超过此大小时进行轮转（默认 `10mb`）。
|
||||
- `resetArchiveRetention`：`*.reset.<timestamp>` transcript 归档的保留时长。默认与 `pruneAfter` 相同；设置为 `false` 可禁用。
|
||||
- `maxDiskBytes`：可选的 sessions 目录磁盘预算。在 `warn` 模式下会记录警告；在 `enforce` 模式下会优先删除最旧的产物/会话。
|
||||
- `highWaterBytes`：预算清理后的可选目标值。默认是 `maxDiskBytes` 的 `80%`。
|
||||
- **`threadBindings`**：线程绑定会话功能的全局默认值。
|
||||
- `enabled`：主默认开关（提供商可覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
|
||||
- `idleHours`：默认按小时计算的不活动自动取消聚焦（`0` 表示禁用；提供商可覆盖）
|
||||
- `enabled`：主默认开关（提供商可以覆盖；Discord 使用 `channels.discord.threadBindings.enabled`）
|
||||
- `idleHours`：默认按小时计算的不活动自动取消聚焦时间（`0` 表示禁用；提供商可覆盖）
|
||||
- `maxAgeHours`：默认按小时计算的硬性最大时长（`0` 表示禁用；提供商可覆盖）
|
||||
|
||||
</Accordion>
|
||||
@ -1210,36 +1215,36 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
|
||||
### 响应前缀
|
||||
|
||||
按渠道/账号的覆盖项：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
|
||||
按渠道/账户覆盖：`channels.<channel>.responsePrefix`、`channels.<channel>.accounts.<id>.responsePrefix`。
|
||||
|
||||
解析顺序（越具体越优先）：账号 → 渠道 → 全局。`""` 会禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。
|
||||
解析顺序（最具体者优先）：账户 → 渠道 → 全局。`""` 表示禁用并停止级联。`"auto"` 会派生为 `[{identity.name}]`。
|
||||
|
||||
**模板变量：**
|
||||
|
||||
| 变量 | 说明 | 示例 |
|
||||
| ----------------- | ---------------- | --------------------------- |
|
||||
| `{model}` | 短模型名 | `claude-opus-4-6` |
|
||||
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
|
||||
| `{provider}` | 提供商名称 | `anthropic` |
|
||||
| `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` |
|
||||
| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
|
||||
| 变量 | 说明 | 示例 |
|
||||
| ----------------- | ---------------------- | --------------------------- |
|
||||
| `{model}` | 短模型名称 | `claude-opus-4-6` |
|
||||
| `{modelFull}` | 完整模型标识符 | `anthropic/claude-opus-4-6` |
|
||||
| `{provider}` | 提供商名称 | `anthropic` |
|
||||
| `{thinkingLevel}` | 当前思考级别 | `high`、`low`、`off` |
|
||||
| `{identity.name}` | 智能体身份名称 | （与 `"auto"` 相同） |
|
||||
|
||||
变量不区分大小写。`{think}` 是 `{thinkingLevel}` 的别名。
|
||||
|
||||
### 确认反应
|
||||
|
||||
- 默认使用当前智能体的 `identity.emoji`，否则为 `"👀"`。设为 `""` 可禁用。
|
||||
- 默认为当前活动智能体的 `identity.emoji`，否则为 `"👀"`。设置 `""` 可禁用。
|
||||
- 按渠道覆盖：`channels.<channel>.ackReaction`、`channels.<channel>.accounts.<id>.ackReaction`。
|
||||
- 解析顺序：账号 → 渠道 → `messages.ackReaction` → identity 回退。
|
||||
- 作用域：`group-mentions`（默认）、`group-all`、`direct`、`all`。
|
||||
- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上，在回复后移除确认反应。
|
||||
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期 Status 反应。
|
||||
在 Slack 和 Discord 上，未设置时，如果确认反应处于启用状态，则保持 Status 反应启用。
|
||||
在 Telegram 上，必须显式将其设为 `true` 才会启用生命周期 Status 反应。
|
||||
- 解析顺序：账户 → 渠道 → `messages.ackReaction` → identity 回退。
|
||||
- 作用范围：`group-mentions`（默认）、`group-all`、`direct`、`all`。
|
||||
- `removeAckAfterReply`：在 Slack、Discord 和 Telegram 上会在回复后移除确认反应。
|
||||
- `messages.statusReactions.enabled`：在 Slack、Discord 和 Telegram 上启用生命周期状态反应。
|
||||
在 Slack 和 Discord 上，未设置时，如果确认反应处于活动状态，则状态反应保持启用。
|
||||
在 Telegram 上，需显式设置为 `true` 才会启用生命周期状态反应。
|
||||
|
||||
### 入站防抖
|
||||
|
||||
将来自同一发送者的快速纯文本消息合并为一个智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
|
||||
将来自同一发送者的快速纯文本消息批量合并为一次智能体轮次。媒体/附件会立即刷新。控制命令会绕过防抖。
|
||||
|
||||
### TTS（文本转语音）
|
||||
|
||||
@ -1289,19 +1294,19 @@ scripts/sandbox-browser-setup.sh # 可选浏览器镜像
|
||||
}
|
||||
```
|
||||
|
||||
- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可以覆盖本地偏好，`/tts status` 会显示生效状态。
|
||||
- `auto` 控制默认的自动 TTS 模式：`off`、`always`、`inbound` 或 `tagged`。`/tts on|off` 可覆盖本地偏好设置，`/tts status` 会显示实际生效状态。
|
||||
- `summaryModel` 会覆盖用于自动摘要的 `agents.defaults.model.primary`。
|
||||
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认为 `false`（需显式启用）。
|
||||
- API key 会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
|
||||
- 内置语音提供商由插件拥有。如果设置了 `plugins.allow`，请包含你想使用的每个 TTS 提供商插件，例如用于 Edge TTS 的 `microsoft`。旧版 `edge` provider id 可作为 `microsoft` 的别名使用。
|
||||
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。
|
||||
- `modelOverrides` 默认启用；`modelOverrides.allowProvider` 默认值为 `false`（需显式开启）。
|
||||
- API 密钥会回退到 `ELEVENLABS_API_KEY`/`XI_API_KEY` 和 `OPENAI_API_KEY`。
|
||||
- 内置语音提供商由插件管理。如果设置了 `plugins.allow`，请包含你要使用的每个 TTS 提供商插件，例如 Edge TTS 使用 `microsoft`。旧版提供商 id `edge` 仍可作为 `microsoft` 的别名使用。
|
||||
- `providers.openai.baseUrl` 会覆盖 OpenAI TTS 端点。解析顺序为：配置，然后是 `OPENAI_TTS_BASE_URL`，最后是 `https://api.openai.com/v1`。
|
||||
- 当 `providers.openai.baseUrl` 指向非 OpenAI 端点时，OpenClaw 会将其视为兼容 OpenAI 的 TTS 服务器，并放宽模型/语音校验。
|
||||
|
||||
---
|
||||
|
||||
## talk
|
||||
## Talk
|
||||
|
||||
Talk 模式（macOS/iOS/Android）的默认值。
|
||||
Talk 模式（macOS/iOS/Android）的默认设置。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -1329,20 +1334,20 @@ Talk 模式（macOS/iOS/Android）的默认值。
|
||||
}
|
||||
```
|
||||
|
||||
- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的一个键。
|
||||
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅用于兼容，会自动迁移到 `talk.providers.<provider>`。
|
||||
- `talk.provider` 在配置了多个 Talk 提供商时，必须匹配 `talk.providers` 中的某个键。
|
||||
- 旧版扁平 Talk 键（`talk.voiceId`、`talk.voiceAliases`、`talk.modelId`、`talk.outputFormat`、`talk.apiKey`）仅为兼容保留，会自动迁移到 `talk.providers.<provider>` 中。
|
||||
- 语音 id 会回退到 `ELEVENLABS_VOICE_ID` 或 `SAG_VOICE_ID`。
|
||||
- `providers.*.apiKey` 接受明文字符串或 SecretRef 对象。
|
||||
- `ELEVENLABS_API_KEY` 回退仅在未配置 Talk API key 时生效。
|
||||
- `providers.*.voiceAliases` 让 Talk 指令可以使用友好名称。
|
||||
- `providers.mlx.modelId` 选择 macOS 本地 MLX helper 使用的 Hugging Face 仓库。如果省略，macOS 使用 `mlx-community/Soprano-80M-bf16`。
|
||||
- macOS MLX 播放会在存在时通过内置的 `openclaw-mlx-tts` helper 运行，或者使用 `PATH` 上的可执行文件；开发时可通过 `OPENCLAW_MLX_TTS_BIN` 覆盖 helper 路径。
|
||||
- `silenceTimeoutMs` 控制 Talk 模式在用户静默后等待多久才发送转录。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
|
||||
- 仅当未配置 Talk API 密钥时，才会使用 `ELEVENLABS_API_KEY` 回退。
|
||||
- `providers.*.voiceAliases` 允许 Talk 指令使用友好名称。
|
||||
- `providers.mlx.modelId` 选择 macOS 本地 MLX helper 使用的 Hugging Face 仓库。若省略，macOS 使用 `mlx-community/Soprano-80M-bf16`。
|
||||
- macOS 上的 MLX 播放会通过内置的 `openclaw-mlx-tts` helper 运行；若其不存在，则使用 `PATH` 上的可执行文件；开发时可通过 `OPENCLAW_MLX_TTS_BIN` 覆盖 helper 路径。
|
||||
- `silenceTimeoutMs` 控制 Talk 模式在用户静音后等待多长时间再发送 transcript。未设置时会保留平台默认停顿窗口（`macOS 和 Android 为 700 ms，iOS 为 900 ms`）。
|
||||
|
||||
---
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference) — 所有其他配置键
|
||||
- [配置](/zh-CN/gateway/configuration) — 常见任务和快速设置
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference) —— 其他所有配置键
|
||||
- [配置](/zh-CN/gateway/configuration) —— 常见任务和快速设置
|
||||
- [配置示例](/zh-CN/gateway/configuration-examples)
|
||||
|
||||
@ -7,23 +7,23 @@ sidebarTitle: Live tests
|
||||
summary: 实时（涉及网络）的测试：模型矩阵、CLI 后端、ACP、媒体提供商、凭证
|
||||
title: 测试：实时套件
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T04:55:00Z"
|
||||
generated_at: "2026-04-25T10:03:59Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3a475044ae7ae914d36b2530ca204eb7b632bc578e4ed16770811617ffc05d83
|
||||
source_hash: 4c91bfba6853db576e120893b8c2a55f9d396d523ad5b5eb6a25829766ee477f
|
||||
source_path: help/testing-live.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
关于快速开始、QA 运行器、单元/集成套件以及 Docker 流程，请参见
|
||||
[测试](/zh-CN/help/testing)。本页介绍 **实时**（涉及网络）的测试
|
||||
如需了解快速开始、QA 运行器、单元 / 集成测试套件和 Docker 流程，请参阅
|
||||
[测试](/zh-CN/help/testing)。本页介绍**实时**（涉及网络）的测试
|
||||
套件：模型矩阵、CLI 后端、ACP 和媒体提供商实时测试，以及
|
||||
凭证处理。
|
||||
|
||||
## 实时：本地配置文件冒烟命令
|
||||
|
||||
在进行临时实时检查前，先加载 `~/.profile`，这样提供商密钥和本地工具路径
|
||||
才能与你的 shell 保持一致：
|
||||
在执行临时实时检查之前，先加载 `~/.profile`，这样提供商密钥和本地工具
|
||||
路径就会与你的 shell 保持一致：
|
||||
|
||||
```bash
|
||||
source ~/.profile
|
||||
@ -37,104 +37,104 @@ pnpm openclaw infer tts convert --local --json \
|
||||
--output /tmp/openclaw-live-smoke.mp3
|
||||
```
|
||||
|
||||
安全的语音呼叫就绪性冒烟测试：
|
||||
安全的语音通话就绪性冒烟测试：
|
||||
|
||||
```bash
|
||||
pnpm openclaw voicecall setup --json
|
||||
pnpm openclaw voicecall smoke --to "+15555550123"
|
||||
```
|
||||
|
||||
除非同时提供 `--yes`，否则 `voicecall smoke` 是一次演练。仅当
|
||||
你有意发起真实通知电话时才使用 `--yes`。对于 Twilio、Telnyx 和
|
||||
Plivo，成功的就绪性检查需要一个公开的 webhook URL；仅本地
|
||||
loopback/私有回退方案会按设计被拒绝。
|
||||
`voicecall smoke` 默认是演练，除非同时提供 `--yes`。只有在你明确
|
||||
想发起真实通知电话时才使用 `--yes`。对于 Twilio、Telnyx 和
|
||||
Plivo，成功的就绪性检查要求提供公共 webhook URL；仅本地的
|
||||
loopback / 私有回退方案会按设计被拒绝。
|
||||
|
||||
## 实时：Android 节点能力全面检查
|
||||
## 实时：Android 节点能力扫描
|
||||
|
||||
- 测试：`src/gateway/android-node.capabilities.live.test.ts`
|
||||
- 脚本：`pnpm android:test:integration`
|
||||
- 目标：调用已连接 Android 节点当前**通告的每一条命令**，并断言命令契约行为。
|
||||
- 目标：调用已连接 Android 节点当前**通告的每一个命令**，并断言命令契约行为。
|
||||
- 范围：
|
||||
- 需要预先满足条件/手动设置（该套件不会安装/运行/配对应用）。
|
||||
- 对所选 Android 节点逐条执行 Gateway 网关 `node.invoke` 验证。
|
||||
- 需要预先满足条件 / 手动设置（该套件不会安装 / 运行 / 配对应用）。
|
||||
- 针对所选 Android 节点，逐命令验证 Gateway 网关 `node.invoke`。
|
||||
- 必需的预先设置：
|
||||
- Android 应用已连接并已与 Gateway 网关配对。
|
||||
- 应用保持在前台运行。
|
||||
- 你期望通过的能力所需的权限/采集授权已授予。
|
||||
- 为你期望通过的能力授予权限 / 捕获同意。
|
||||
- 可选目标覆盖：
|
||||
- `OPENCLAW_ANDROID_NODE_ID` 或 `OPENCLAW_ANDROID_NODE_NAME`。
|
||||
- `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`。
|
||||
- 完整 Android 设置详情： [Android App](/zh-CN/platforms/android)
|
||||
- 完整 Android 设置详情：[Android App](/zh-CN/platforms/android)
|
||||
|
||||
## 实时：模型冒烟测试（配置文件密钥）
|
||||
|
||||
实时测试分为两层，这样我们可以隔离故障：
|
||||
|
||||
- “直接模型”用于判断提供商/模型在给定密钥下是否至少能够返回响应。
|
||||
- “Gateway 冒烟测试”用于判断该模型的完整 Gateway 网关 + 智能体流水线是否正常工作（会话、历史、工具、沙箱策略等）。
|
||||
- “Direct model” 用来确认在给定密钥下，提供商 / 模型本身是否能正常响应。
|
||||
- “Gateway smoke” 用来确认该模型的完整 Gateway 网关 + 智能体流水线是否正常工作（会话、历史、工具、沙箱策略等）。
|
||||
|
||||
### 第 1 层：直接模型补全（无 Gateway 网关）
|
||||
### 第 1 层：Direct model completion（无 Gateway 网关）
|
||||
|
||||
- 测试：`src/agents/models.profiles.live.test.ts`
|
||||
- 目标：
|
||||
- 枚举已发现的模型
|
||||
- 使用 `getApiKeyForModel` 选择你具备凭证的模型
|
||||
- 对每个模型运行一个小型补全请求（并在需要时运行定向回归测试）
|
||||
- 使用 `getApiKeyForModel` 选择你有凭证的模型
|
||||
- 对每个模型运行一个小型 completion（并在需要时运行定向回归测试）
|
||||
- 启用方式：
|
||||
- `pnpm test:live`（或如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
|
||||
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会真正运行此套件；否则它会跳过，以便让 `pnpm test:live` 专注于 Gateway 网关冒烟测试
|
||||
- 如何选择模型：
|
||||
- `OPENCLAW_LIVE_MODELS=modern` 运行现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4）
|
||||
- `OPENCLAW_LIVE_MODELS=all` 是现代允许列表的别名
|
||||
- 或者 `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."`（逗号分隔的允许列表）
|
||||
- modern/all 全量检查默认使用经过挑选的高信号上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可执行完整的 modern 全量检查，或设为正数以使用更小的上限。
|
||||
- 完整全量检查对整个直接模型测试使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 超时时间。默认值：60 分钟。
|
||||
- 直接模型探测默认使用 20 路并行；可设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 进行覆盖。
|
||||
- 如何选择提供商：
|
||||
- `pnpm test:live`（如果直接调用 Vitest，则使用 `OPENCLAW_LIVE_TEST=1`）
|
||||
- 设置 `OPENCLAW_LIVE_MODELS=modern`（或 `all`，即 modern 的别名）才会实际运行该套件；否则它会跳过，以便让 `pnpm test:live` 聚焦于 Gateway 网关冒烟测试
|
||||
- 选择模型的方法：
|
||||
- `OPENCLAW_LIVE_MODELS=modern` 运行 modern 允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4）
|
||||
- `OPENCLAW_LIVE_MODELS=all` 是 modern 允许列表的别名
|
||||
- 或 `OPENCLAW_LIVE_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,..."`（逗号分隔的允许列表）
|
||||
- modern / all 扫描默认使用精心挑选的高信号数量上限；设置 `OPENCLAW_LIVE_MAX_MODELS=0` 可进行完整的 modern 扫描，或设置为正数以使用更小的上限。
|
||||
- 完整扫描会对整个 direct-model 测试使用 `OPENCLAW_LIVE_TEST_TIMEOUT_MS` 超时。默认值：60 分钟。
|
||||
- direct-model 探测默认以 20 路并行运行；可设置 `OPENCLAW_LIVE_MODEL_CONCURRENCY` 覆盖。
|
||||
- 选择提供商的方法：
|
||||
- `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"`（逗号分隔的允许列表）
|
||||
- 密钥来源：
|
||||
- 默认：配置文件存储和环境变量回退
|
||||
- 设置 `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制**仅使用配置文件存储**
|
||||
- 存在意义：
|
||||
- 将“提供商 API 出故障 / 密钥无效”与“Gateway 网关智能体流水线出故障”区分开
|
||||
- 容纳小型、隔离的回归测试（例如：OpenAI Responses/Codex Responses 的推理回放 + 工具调用流程）
|
||||
- 该层存在的原因：
|
||||
- 将“提供商 API 已损坏 / 密钥无效”和“Gateway 网关智能体流水线损坏”区分开
|
||||
- 包含小型、隔离的回归测试（示例：OpenAI Responses / Codex Responses 推理回放 + 工具调用流程）
|
||||
|
||||
### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（即 “@openclaw” 实际执行的内容）
|
||||
### 第 2 层：Gateway 网关 + dev 智能体冒烟测试（也就是 “@openclaw” 实际执行的内容）
|
||||
|
||||
- 测试：`src/gateway/gateway-models.profiles.live.test.ts`
|
||||
- 目标：
|
||||
- 启动一个进程内 Gateway 网关
|
||||
- 创建/修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
|
||||
- 遍历带密钥的模型并断言：
|
||||
- “有意义的”响应（无工具）
|
||||
- 一次真实的工具调用可以正常工作（read 探针）
|
||||
- 可选的额外工具探针（exec+read 探针）
|
||||
- 创建 / 修补一个 `agent:dev:*` 会话（每次运行覆盖模型）
|
||||
- 遍历带密钥的模型，并断言：
|
||||
- 有“有意义”的响应（无工具）
|
||||
- 真实工具调用可正常工作（读取探针）
|
||||
- 可选的额外工具探针正常工作（exec+read 探针）
|
||||
- OpenAI 回归路径（仅工具调用 → 后续跟进）持续正常
|
||||
- 探针细节（这样你可以快速解释故障）：
|
||||
- `read` 探针：测试会在工作区中写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。
|
||||
- 探针细节（这样你可以快速解释失败原因）：
|
||||
- `read` 探针：测试会在工作区写入一个 nonce 文件，并要求智能体 `read` 该文件并回显 nonce。
|
||||
- `exec+read` 探针：测试会要求智能体通过 `exec` 将 nonce 写入临时文件，然后再 `read` 回来。
|
||||
- 图像探针：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
|
||||
- image 探针：测试会附加一个生成的 PNG（猫 + 随机代码），并期望模型返回 `cat <CODE>`。
|
||||
- 实现参考：`src/gateway/gateway-models.profiles.live.test.ts` 和 `src/gateway/live-image-probe.ts`。
|
||||
- 启用方式：
|
||||
- `pnpm test:live`（或如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
|
||||
- 如何选择模型：
|
||||
- 默认：现代允许列表（Opus/Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4）
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是现代允许列表的别名
|
||||
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号列表）以缩小范围
|
||||
- modern/all Gateway 网关全量检查默认使用经过挑选的高信号上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可执行完整的 modern 全量检查，或设为正数以使用更小的上限。
|
||||
- 如何选择提供商（避免 “OpenRouter 全部都测”）：
|
||||
- `pnpm test:live`（如果直接调用 Vitest，则使用 `OPENCLAW_LIVE_TEST=1`）
|
||||
- 选择模型的方法：
|
||||
- 默认：modern 允许列表（Opus / Sonnet 4.6+、GPT-5.2 + Codex、Gemini 3、DeepSeek V4、GLM 4.7、MiniMax M2.7、Grok 4）
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS=all` 是 modern 允许列表的别名
|
||||
- 或设置 `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"`（或逗号分隔列表）以缩小范围
|
||||
- modern / all Gateway 网关扫描默认使用精心挑选的高信号数量上限；设置 `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` 可进行完整的 modern 扫描，或设置为正数以使用更小的上限。
|
||||
- 选择提供商的方法（避免 “OpenRouter everything”）：
|
||||
- `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"`（逗号分隔的允许列表）
|
||||
- 在此实时测试中，工具 + 图像探针始终启用：
|
||||
- 工具 + image 探针在这个实时测试中始终开启：
|
||||
- `read` 探针 + `exec+read` 探针（工具压力测试）
|
||||
- 当模型声明支持图像输入时，图像探针会运行
|
||||
- 流程（高层说明）：
|
||||
- 当模型声明支持 image 输入时，运行 image 探针
|
||||
- 流程（高层概述）：
|
||||
- 测试生成一个带有 “CAT” + 随机代码的小型 PNG（`src/gateway/live-image-probe.ts`）
|
||||
- 通过 `agent` `attachments: [{ mimeType: "image/png", content: "<base64>" }]` 发送
|
||||
- Gateway 网关将附件解析为 `images[]`（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
|
||||
- 内嵌智能体将多模态用户消息转发给模型
|
||||
- Gateway 网关将附件解析到 `images[]` 中（`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`）
|
||||
- 嵌入式智能体将多模态用户消息转发给模型
|
||||
- 断言：回复包含 `cat` + 该代码（OCR 容错：允许轻微错误）
|
||||
|
||||
提示：要查看你的机器上可以测试什么（以及准确的 `provider/model` id），请运行：
|
||||
提示：如果你想查看你的机器上可以测试什么（以及精确的 `provider/model` id），请运行：
|
||||
|
||||
```bash
|
||||
openclaw models list
|
||||
@ -144,24 +144,24 @@ openclaw models list --json
|
||||
## 实时：CLI 后端冒烟测试（Claude、Codex、Gemini 或其他本地 CLI）
|
||||
|
||||
- 测试：`src/gateway/gateway-cli-backend.live.test.ts`
|
||||
- 目标：在不触碰默认配置的情况下，使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线。
|
||||
- 后端专用的默认冒烟设置位于所属扩展的 `cli-backend.ts` 定义中。
|
||||
- 目标：使用本地 CLI 后端验证 Gateway 网关 + 智能体流水线，同时不触碰你的默认配置。
|
||||
- 后端专用的冒烟测试默认值位于所属扩展的 `cli-backend.ts` 定义中。
|
||||
- 启用：
|
||||
- `pnpm test:live`（或如果你直接调用 Vitest，则设置 `OPENCLAW_LIVE_TEST=1`）
|
||||
- `pnpm test:live`（如果直接调用 Vitest，则使用 `OPENCLAW_LIVE_TEST=1`）
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND=1`
|
||||
- 默认值：
|
||||
- 默认提供商/模型：`claude-cli/claude-sonnet-4-6`
|
||||
- 命令/参数/图像行为来自所属 CLI 后端插件元数据。
|
||||
- 默认 provider / 模型：`claude-cli/claude-sonnet-4-6`
|
||||
- command / args / image 行为来自所属 CLI 后端插件元数据。
|
||||
- 覆盖项（可选）：
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.2"`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'`
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图像附件（路径会注入到提示中）。除非明确请求，否则 Docker 配方默认关闭此项。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 通过 CLI 参数传递图像文件路径，而不是通过提示注入。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）用于控制在设置 `IMAGE_ARG` 时如何传递图像参数。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` 发送真实图片附件（路径会注入到提示词中）。除非明确请求，Docker 配方默认关闭此项。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` 将图片文件路径作为 CLI 参数传递，而不是通过提示词注入。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"`（或 `"list"`）用于控制在设置 `IMAGE_ARG` 时如何传递图片参数。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` 发送第二轮消息并验证恢复流程。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 在所选模型支持切换目标时，启用 Claude Sonnet -> Opus 同会话连续性探针。为了整体稳定性，Docker 配方默认关闭此项。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 启用 MCP/工具 local loopback 探针。除非明确请求，否则 Docker 配方默认关闭此项。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=1` 在所选模型支持切换目标时，选择加入 Claude Sonnet -> Opus 同会话连续性探针。为了整体可靠性，Docker 配方默认关闭此项。
|
||||
- `OPENCLAW_LIVE_CLI_BACKEND_MCP_PROBE=1` 选择加入 MCP / 工具 local loopback 探针。除非明确请求，Docker 配方默认关闭此项。
|
||||
|
||||
示例：
|
||||
|
||||
@ -189,11 +189,11 @@ pnpm test:docker:live-cli-backend:gemini
|
||||
说明：
|
||||
|
||||
- Docker 运行器位于 `scripts/test-live-cli-backend-docker.sh`。
|
||||
- 它在仓库 Docker 镜像内以非 root 的 `node` 用户身份运行实时 CLI 后端冒烟测试。
|
||||
- 它会从所属扩展解析 CLI 冒烟元数据，然后将匹配的 Linux CLI 软件包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 指向的可写缓存前缀中（默认：`~/.cache/openclaw/docker-cli-tools`）。
|
||||
- `pnpm test:docker:live-cli-backend:claude-subscription` 需要可移植的 Claude Code 订阅 OAuth，可通过以下任一方式提供：`~/.claude/.credentials.json` 中带有 `claudeAiOauth.subscriptionType`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN`。它会先在 Docker 中验证直接 `claude -p` 可用，然后在不保留 Anthropic API 密钥环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。该订阅通道默认禁用 Claude MCP/工具和图像探针，因为 Claude 当前会通过额外使用计费来处理第三方应用使用，而不是采用普通订阅计划限制。
|
||||
- 实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图像分类轮次，然后是通过 Gateway 网关 CLI 验证的 MCP `cron` 工具调用。
|
||||
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得之前的备注。
|
||||
- 它会在仓库 Docker 镜像中以非 root 的 `node` 用户身份运行实时 CLI 后端冒烟测试。
|
||||
- 它会从所属扩展中解析 CLI 冒烟测试元数据，然后将匹配的 Linux CLI 包（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）安装到缓存的可写前缀 `OPENCLAW_DOCKER_CLI_TOOLS_DIR` 中（默认值：`~/.cache/openclaw/docker-cli-tools`）。
|
||||
- `pnpm test:docker:live-cli-backend:claude-subscription` 要求可移植的 Claude Code 订阅 OAuth，可通过带有 `claudeAiOauth.subscriptionType` 的 `~/.claude/.credentials.json`，或来自 `claude setup-token` 的 `CLAUDE_CODE_OAUTH_TOKEN` 提供。它会先在 Docker 中验证直接 `claude -p`，然后在不保留 Anthropic API 密钥环境变量的情况下运行两轮 Gateway 网关 CLI 后端测试。此订阅测试通道默认禁用 Claude MCP / 工具和 image 探针，因为 Claude 当前会将第三方应用使用量计入额外用量计费，而不是常规订阅计划限额。
|
||||
- 实时 CLI 后端冒烟测试现在会对 Claude、Codex 和 Gemini 执行相同的端到端流程：文本轮次、图片分类轮次，然后通过 Gateway 网关 CLI 验证 MCP `cron` 工具调用。
|
||||
- Claude 的默认冒烟测试还会将会话从 Sonnet 修补为 Opus，并验证恢复后的会话仍记得更早的一条备注。
|
||||
|
||||
## 实时：ACP 绑定冒烟测试（`/acp spawn ... --bind here`）
|
||||
|
||||
@ -201,7 +201,7 @@ pnpm test:docker:live-cli-backend:gemini
|
||||
- 目标：使用实时 ACP 智能体验证真实 ACP 会话绑定流程：
|
||||
- 发送 `/acp spawn <agent> --bind here`
|
||||
- 原地绑定一个合成的消息渠道会话
|
||||
- 在同一会话上发送一条普通后续消息
|
||||
- 在同一会话上发送普通后续消息
|
||||
- 验证该后续消息落入已绑定 ACP 会话的转录中
|
||||
- 启用：
|
||||
- `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts`
|
||||
@ -220,8 +220,8 @@ pnpm test:docker:live-cli-backend:gemini
|
||||
- `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.2`
|
||||
- `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.2`
|
||||
- 说明：
|
||||
- 此通道使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成来源路由字段，因此测试可以附加消息渠道上下文，而无需假装进行外部投递。
|
||||
- 当 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 未设置时，测试会对所选 ACP harness 智能体使用内嵌 `acpx` 插件的内置智能体注册表。
|
||||
- 该测试通道使用 Gateway 网关 `chat.send` 接口，并带有仅管理员可用的合成来源路由字段，因此测试可以附加消息渠道上下文，而无需假装向外部发送。
|
||||
- 当未设置 `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` 时，测试会对所选 ACP harness 智能体使用嵌入式 `acpx` 插件的内置智能体注册表。
|
||||
|
||||
示例：
|
||||
|
||||
@ -248,15 +248,15 @@ pnpm test:docker:live-acp-bind:gemini
|
||||
Docker 说明：
|
||||
|
||||
- Docker 运行器位于 `scripts/test-live-acp-bind-docker.sh`。
|
||||
- 默认情况下，它会依次对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。
|
||||
- 默认情况下，它会按顺序对所有受支持的实时 CLI 智能体运行 ACP 绑定冒烟测试：`claude`、`codex`，然后是 `gemini`。
|
||||
- 使用 `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`、`OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` 或 `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini` 可缩小矩阵范围。
|
||||
- 它会加载 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，在可写的 npm 前缀中安装 `acpx`，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。
|
||||
- 在 Docker 内，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 acpx 就能让从已加载配置文件中获得的提供商环境变量继续对其子 harness CLI 可用。
|
||||
- 它会加载 `~/.profile`，将匹配的 CLI 认证材料暂存到容器中，把 `acpx` 安装到可写的 npm 前缀里，然后在缺失时安装所请求的实时 CLI（`@anthropic-ai/claude-code`、`@openai/codex` 或 `@google/gemini-cli`）。
|
||||
- 在 Docker 内部，运行器会设置 `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`，这样 acpx 就能让来自已加载 profile 的 provider 环境变量继续提供给子 harness CLI。
|
||||
|
||||
## 实时：Codex app-server harness 冒烟测试
|
||||
|
||||
- 目标：通过常规 Gateway 网关
|
||||
`agent` 方法验证插件拥有的 Codex harness：
|
||||
- 目标：通过正常的 Gateway 网关
|
||||
`agent` 方法验证插件自有的 Codex harness：
|
||||
- 加载内置的 `codex` 插件
|
||||
- 选择 `OPENCLAW_AGENT_RUNTIME=codex`
|
||||
- 向 `openai/gpt-5.2` 发送第一轮 Gateway 网关智能体消息，并强制使用 Codex harness
|
||||
@ -264,19 +264,19 @@ Docker 说明：
|
||||
线程可以恢复
|
||||
- 通过同一个 Gateway 网关命令
|
||||
路径运行 `/codex status` 和 `/codex models`
|
||||
- 可选地运行两个经过 Guardian 审核的提权 shell 探针：一个应被批准的无害
|
||||
命令，以及一个应被拒绝的伪造秘密上传操作，
|
||||
以便智能体回头询问
|
||||
- 可选运行两个经 Guardian 审核的提权 shell 探针：一个良性
|
||||
命令应被批准，另一个伪造的密钥上传应被
|
||||
拒绝，从而让智能体回过头来询问
|
||||
- 测试：`src/gateway/gateway-codex-harness.live.test.ts`
|
||||
- 启用：`OPENCLAW_LIVE_CODEX_HARNESS=1`
|
||||
- 默认模型：`openai/gpt-5.2`
|
||||
- 可选图像探针：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
|
||||
- 可选 MCP/工具探针：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
|
||||
- 可选 image 探针：`OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1`
|
||||
- 可选 MCP / 工具探针：`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1`
|
||||
- 可选 Guardian 探针：`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1`
|
||||
- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，这样损坏的 Codex
|
||||
harness 就不能通过悄悄回退到 PI 来蒙混过关。
|
||||
- 该冒烟测试会设置 `OPENCLAW_AGENT_HARNESS_FALLBACK=none`，因此损坏的 Codex
|
||||
harness 不能通过静默回退到 PI 而蒙混过关。
|
||||
- 认证：Codex app-server 认证来自本地 Codex 订阅登录。Docker
|
||||
冒烟测试在适用时也可以提供 `OPENAI_API_KEY` 用于非 Codex 探针，
|
||||
冒烟测试在适用时还可提供 `OPENAI_API_KEY` 用于非 Codex 探针，
|
||||
另外还可选复制 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
|
||||
|
||||
本地配方：
|
||||
@ -303,8 +303,8 @@ Docker 说明：
|
||||
- Docker 运行器位于 `scripts/test-live-codex-harness-docker.sh`。
|
||||
- 它会加载挂载的 `~/.profile`，传递 `OPENAI_API_KEY`，在存在时复制 Codex CLI
|
||||
认证文件，将 `@openai/codex` 安装到可写的挂载 npm
|
||||
前缀中，暂存源码树，然后仅运行 Codex-harness 实时测试。
|
||||
- Docker 默认启用图像、MCP/工具和 Guardian 探针。需要更窄范围的调试
|
||||
前缀中，暂存源代码树，然后只运行 Codex-harness 实时测试。
|
||||
- Docker 默认启用 image、MCP / 工具和 Guardian 探针。需要更窄范围的调试
|
||||
运行时，可设置 `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` 或
|
||||
`OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` 或
|
||||
`OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`。
|
||||
@ -314,15 +314,15 @@ Docker 说明：
|
||||
|
||||
### 推荐的实时配方
|
||||
|
||||
范围窄、显式的允许列表最快，也最不容易波动：
|
||||
缩小范围、明确的允许列表速度最快，也最不容易波动：
|
||||
|
||||
- 单模型，直接测试（无 Gateway 网关）：
|
||||
- 单模型，direct（无 Gateway 网关）：
|
||||
- `OPENCLAW_LIVE_MODELS="openai/gpt-5.2" pnpm test:live src/agents/models.profiles.live.test.ts`
|
||||
|
||||
- 单模型，Gateway 网关冒烟测试：
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
- 多个提供商的工具调用：
|
||||
- 跨多个提供商的工具调用：
|
||||
- `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
- 聚焦 Google（Gemini API 密钥 + Antigravity）：
|
||||
@ -330,37 +330,38 @@ Docker 说明：
|
||||
- Antigravity（OAuth）：`OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
- Google 自适应思考冒烟测试：
|
||||
- 如果本地密钥存放在 shell 配置文件中：`source ~/.profile`
|
||||
- 如果本地密钥位于 shell profile 中：`source ~/.profile`
|
||||
- Gemini 3 动态默认值：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-3.1-pro-preview --alt-model google/gemini-3.1-pro-preview --message '/think adaptive Reply exactly: GEMINI_ADAPTIVE_OK' --timeout-ms 180000`
|
||||
- Gemini 2.5 动态预算：`pnpm openclaw qa manual --provider-mode live-frontier --model google/gemini-2.5-flash --alt-model google/gemini-2.5-flash --message '/think adaptive Reply exactly: GEMINI25_ADAPTIVE_OK' --timeout-ms 180000`
|
||||
|
||||
说明：
|
||||
|
||||
- `google/...` 使用 Gemini API（API 密钥）。
|
||||
- `google-antigravity/...` 使用 Antigravity OAuth 桥接（Cloud Code Assist 风格的智能体端点）。
|
||||
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（单独的认证 + 工具链差异）。
|
||||
- `google-antigravity/...` 使用 Antigravity OAuth 桥接（类似 Cloud Code Assist 的智能体端点）。
|
||||
- `google-gemini-cli/...` 使用你机器上的本地 Gemini CLI（独立的认证 + 工具行为差异）。
|
||||
- Gemini API 与 Gemini CLI：
|
||||
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / 配置文件认证）；这也是大多数用户提到 “Gemini” 时的含义。
|
||||
- CLI：OpenClaw 调用本地 `gemini` 二进制；它有自己的认证方式，而且行为可能不同（流式传输/工具支持/版本偏差）。
|
||||
- API：OpenClaw 通过 HTTP 调用 Google 托管的 Gemini API（API 密钥 / 配置文件认证）；这通常就是大多数用户所说的 “Gemini”。
|
||||
- CLI：OpenClaw 调用本地 `gemini` 二进制；它有自己的认证方式，而且行为可能不同（流式传输 / 工具支持 / 版本偏差）。
|
||||
|
||||
## 实时：模型矩阵（我们的覆盖范围）
|
||||
## 实时：模型矩阵（我们覆盖什么）
|
||||
|
||||
没有固定的“CI 模型列表”（实时测试是可选启用的），但这些是**推荐**你在具备密钥的开发机器上定期覆盖的模型。
|
||||
这里没有固定的 “CI 模型列表”（实时测试是选择加入的），但以下是**建议**
|
||||
在带有密钥的开发机器上定期覆盖的模型。
|
||||
|
||||
### 现代冒烟测试集合（工具调用 + 图像）
|
||||
### 现代冒烟测试集（工具调用 + image）
|
||||
|
||||
这是我们期望持续可用的“常用模型”运行集合：
|
||||
这是我们期望持续保持可用的 “常用模型” 运行集：
|
||||
|
||||
- OpenAI（非 Codex）：`openai/gpt-5.2`
|
||||
- OpenAI Codex OAuth：`openai-codex/gpt-5.2`
|
||||
- Anthropic：`anthropic/claude-opus-4-6`（或 `anthropic/claude-sonnet-4-6`）
|
||||
- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免较旧的 Gemini 2.x 模型）
|
||||
- Google（Gemini API）：`google/gemini-3.1-pro-preview` 和 `google/gemini-3-flash-preview`（避免使用较旧的 Gemini 2.x 模型）
|
||||
- Google（Antigravity）：`google-antigravity/claude-opus-4-6-thinking` 和 `google-antigravity/gemini-3-flash`
|
||||
- DeepSeek：`deepseek/deepseek-v4-flash` 和 `deepseek/deepseek-v4-pro`
|
||||
- Z.AI（GLM）：`zai/glm-4.7`
|
||||
- MiniMax：`minimax/MiniMax-M2.7`
|
||||
|
||||
运行带工具 + 图像的 Gateway 网关冒烟测试：
|
||||
运行带工具 + image 的 Gateway 网关冒烟测试：
|
||||
`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.2,openai-codex/gpt-5.2,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,deepseek/deepseek-v4-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts`
|
||||
|
||||
### 基线：工具调用（Read + 可选 Exec）
|
||||
@ -376,62 +377,62 @@ Docker 说明：
|
||||
|
||||
可选的额外覆盖（有则更好）：
|
||||
|
||||
- xAI：`xai/grok-4`（或当前最新可用版本）
|
||||
- Mistral：`mistral/`…（任选一个你已启用、支持 “tools” 的模型）
|
||||
- xAI：`xai/grok-4`（或最新可用版本）
|
||||
- Mistral：`mistral/`…（选择一个你已启用、支持 “tools” 的模型）
|
||||
- Cerebras：`cerebras/`…（如果你有访问权限）
|
||||
- LM Studio：`lmstudio/`…（本地；工具调用取决于 API 模式）
|
||||
|
||||
### 视觉：发送图像（附件 → 多模态消息）
|
||||
### Vision：发送 image（附件 → 多模态消息）
|
||||
|
||||
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持图像的模型（Claude/Gemini/OpenAI 支持视觉的变体等），以便执行图像探针。
|
||||
在 `OPENCLAW_LIVE_GATEWAY_MODELS` 中至少包含一个支持 image 的模型（Claude / Gemini / OpenAI 支持视觉的变体等），以运行 image 探针。
|
||||
|
||||
### 聚合器 / 替代 Gateway 网关
|
||||
### 聚合器 / 其他 Gateway 网关
|
||||
|
||||
如果你已启用相应密钥，我们也支持通过以下方式测试：
|
||||
如果你已启用相关密钥，我们也支持通过以下方式进行测试：
|
||||
|
||||
- OpenRouter：`openrouter/...`（数百种模型；使用 `openclaw models scan` 查找支持工具 + 图像的候选项）
|
||||
- OpenCode：`opencode/...` 用于 Zen，`opencode-go/...` 用于 Go（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
|
||||
- OpenRouter：`openrouter/...`（数百个模型；使用 `openclaw models scan` 查找支持工具 + image 的候选项）
|
||||
- OpenCode：Zen 使用 `opencode/...`，Go 使用 `opencode-go/...`（通过 `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY` 认证）
|
||||
|
||||
你还可以纳入实时矩阵的更多提供商（如果你具备相应凭证/配置）：
|
||||
你还可以纳入实时矩阵的更多提供商（如果你有凭证 / 配置）：
|
||||
|
||||
- 内置：`openai`、`openai-codex`、`anthropic`、`google`、`google-vertex`、`google-antigravity`、`google-gemini-cli`、`zai`、`openrouter`、`opencode`、`opencode-go`、`xai`、`groq`、`cerebras`、`mistral`、`github-copilot`
|
||||
- 通过 `models.providers`（自定义端点）：`minimax`（云/API），以及任何兼容 OpenAI/Anthropic 的代理（LM Studio、vLLM、LiteLLM 等）
|
||||
- 通过 `models.providers`（自定义端点）：`minimax`（云 / API），以及任何兼容 OpenAI / Anthropic 的代理（LM Studio、vLLM、LiteLLM 等）
|
||||
|
||||
提示：不要试图在文档中硬编码“所有模型”。权威列表是你机器上 `discoverModels(...)` 返回的内容 + 当前可用的密钥。
|
||||
提示：不要尝试在文档中硬编码 “所有模型”。权威列表始终是你的机器上 `discoverModels(...)` 的返回结果 + 当前可用密钥。
|
||||
|
||||
## 凭证（切勿提交）
|
||||
|
||||
实时测试发现凭证的方式与 CLI 相同。实际含义如下：
|
||||
|
||||
- 如果 CLI 可用，实时测试应该能找到相同的密钥。
|
||||
- 如果实时测试提示 “no creds”，请像调试 `openclaw models list` / 模型选择那样调试。
|
||||
- 如果 CLI 可用，实时测试也应该能找到相同的密钥。
|
||||
- 如果实时测试显示 “no creds”，请像调试 `openclaw models list` / 模型选择那样进行调试。
|
||||
|
||||
- 每个智能体的认证配置文件：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（这就是实时测试中 “profile keys” 的含义）
|
||||
- 配置：`~/.openclaw/openclaw.json`（或 `OPENCLAW_CONFIG_PATH`）
|
||||
- 旧版状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时 home 中，但它不是主配置文件密钥存储）
|
||||
- 默认情况下，本地实时运行会把当前活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的实时 home 会跳过 `workspace/` 和 `sandboxes/`，并且会去除 `agents.*.workspace` / `agentDir` 路径覆盖，这样探针就不会落到你真实主机的工作区上。
|
||||
- 旧状态目录：`~/.openclaw/credentials/`（存在时会复制到暂存的实时测试 home 中，但它不是主配置文件密钥存储）
|
||||
- 本地实时运行默认会将活动配置、每个智能体的 `auth-profiles.json` 文件、旧版 `credentials/` 以及受支持的外部 CLI 认证目录复制到临时测试 home 中；暂存的实时 home 会跳过 `workspace/` 和 `sandboxes/`，并且会移除 `agents.*.workspace` / `agentDir` 路径覆盖，这样探针就不会落到你的真实主机工作区中。
|
||||
|
||||
如果你想依赖环境变量密钥（例如在 `~/.profile` 中导出的密钥），请在本地测试前运行 `source ~/.profile`，或者使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。
|
||||
如果你想依赖环境变量密钥（例如在 `~/.profile` 中导出的密钥），请在执行本地测试前运行 `source ~/.profile`，或使用下面的 Docker 运行器（它们可以将 `~/.profile` 挂载到容器中）。
|
||||
|
||||
## Deepgram 实时测试（音频转写）
|
||||
## 实时：Deepgram（音频转录）
|
||||
|
||||
- 测试：`extensions/deepgram/audio.live.test.ts`
|
||||
- 启用：`DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts`
|
||||
|
||||
## BytePlus 编码计划实时测试
|
||||
## 实时：BytePlus 编码计划
|
||||
|
||||
- 测试：`extensions/byteplus/live.test.ts`
|
||||
- 启用：`BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts`
|
||||
- 可选模型覆盖：`BYTEPLUS_CODING_MODEL=ark-code-latest`
|
||||
|
||||
## ComfyUI 工作流媒体实时测试
|
||||
## 实时：ComfyUI 工作流媒体测试
|
||||
|
||||
- 测试：`extensions/comfy/comfy.live.test.ts`
|
||||
- 启用：`OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts`
|
||||
- 范围：
|
||||
- 覆盖内置的 comfy 图像、视频和 `music_generate` 路径
|
||||
- 除非配置了 `plugins.entries.comfy.config.<capability>`，否则会跳过各项能力
|
||||
- 在修改 comfy 工作流提交、轮询、下载或插件注册后很有用
|
||||
- 运行内置的 comfy image、video 和 `music_generate` 路径
|
||||
- 如果未配置 `plugins.entries.comfy.config.<capability>`，则跳过每项能力
|
||||
- 在修改 comfy 工作流提交、轮询、下载或插件注册后很有帮助
|
||||
|
||||
## 实时：图像生成
|
||||
|
||||
@ -439,14 +440,14 @@ Docker 说明：
|
||||
- 命令：`pnpm test:live test/image-generation.runtime.live.test.ts`
|
||||
- Harness：`pnpm test:live:media image`
|
||||
- 范围：
|
||||
- 枚举每一个已注册的图像生成提供商插件
|
||||
- 在探测前先从你的登录 shell（`~/.profile`）加载缺失的提供商环境变量
|
||||
- 默认优先使用实时/环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
|
||||
- 跳过没有可用认证/配置文件/模型的提供商
|
||||
- 通过共享图像生成运行时运行每个已配置的提供商：
|
||||
- 枚举每个已注册的图像生成 provider 插件
|
||||
- 在探测前，从你的登录 shell（`~/.profile`）加载缺失的 provider 环境变量
|
||||
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实 shell 凭证
|
||||
- 跳过没有可用认证 / 配置文件 / 模型的 provider
|
||||
- 通过共享图像生成运行时运行每个已配置 provider：
|
||||
- `<provider>:generate`
|
||||
- 当提供商声明支持编辑时，运行 `<provider>:edit`
|
||||
- 当前已覆盖的内置提供商：
|
||||
- 当 provider 声明支持 edit 时，运行 `<provider>:edit`
|
||||
- 当前覆盖的内置 provider：
|
||||
- `fal`
|
||||
- `google`
|
||||
- `minimax`
|
||||
@ -461,8 +462,8 @@ Docker 说明：
|
||||
- 可选认证行为：
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置文件存储认证，并忽略仅环境变量的覆盖
|
||||
|
||||
对于已发布的 CLI 路径，在提供商/运行时实时
|
||||
测试通过后，再添加一个 `infer` 冒烟测试：
|
||||
对于已发布的 CLI 路径，请在 provider / 运行时实时
|
||||
测试通过后再添加一个 `infer` 冒烟测试：
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_INFER_CLI_TEST=1 pnpm test:live -- test/image-generation.infer-cli.live.test.ts
|
||||
@ -474,76 +475,76 @@ openclaw infer image generate \
|
||||
--json
|
||||
```
|
||||
|
||||
这涵盖了 CLI 参数解析、配置/默认智能体解析、内置
|
||||
这涵盖了 CLI 参数解析、配置 / 默认智能体解析、内置
|
||||
插件激活、按需修复内置运行时依赖、共享
|
||||
图像生成运行时，以及实时提供商请求。
|
||||
图像生成运行时，以及实时 provider 请求。
|
||||
|
||||
## 音乐生成实时测试
|
||||
## 实时：音乐生成
|
||||
|
||||
- 测试：`extensions/music-generation-providers.live.test.ts`
|
||||
- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts`
|
||||
- Harness：`pnpm test:live:media music`
|
||||
- 范围：
|
||||
- 覆盖共享内置音乐生成提供商路径
|
||||
- 运行共享的内置音乐生成 provider 路径
|
||||
- 当前覆盖 Google 和 MiniMax
|
||||
- 在探测前先从你的登录 shell（`~/.profile`）加载提供商环境变量
|
||||
- 默认优先使用实时/环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
|
||||
- 跳过没有可用认证/配置文件/模型的提供商
|
||||
- 在探测前，从你的登录 shell（`~/.profile`）加载 provider 环境变量
|
||||
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实 shell 凭证
|
||||
- 跳过没有可用认证 / 配置文件 / 模型的 provider
|
||||
- 在可用时运行两种已声明的运行时模式：
|
||||
- 使用仅提示词输入的 `generate`
|
||||
- 当提供商声明 `capabilities.edit.enabled` 时运行 `edit`
|
||||
- 当前共享通道覆盖：
|
||||
- 当 provider 声明 `capabilities.edit.enabled` 时运行 `edit`
|
||||
- 当前共享测试通道覆盖：
|
||||
- `google`：`generate`、`edit`
|
||||
- `minimax`：`generate`
|
||||
- `comfy`：单独的 Comfy 实时文件，不属于此共享全面检查
|
||||
- `comfy`：使用单独的 Comfy 实时文件，不在这个共享扫描中
|
||||
- 可选缩小范围：
|
||||
- `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"`
|
||||
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"`
|
||||
- `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.6"`
|
||||
- 可选认证行为：
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置文件存储认证，并忽略仅环境变量的覆盖
|
||||
|
||||
## 视频生成实时测试
|
||||
## 实时：视频生成
|
||||
|
||||
- 测试：`extensions/video-generation-providers.live.test.ts`
|
||||
- 启用：`OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts`
|
||||
- Harness：`pnpm test:live:media video`
|
||||
- 范围：
|
||||
- 覆盖共享内置视频生成提供商路径
|
||||
- 默认使用对发布安全的冒烟路径：非 FAL 提供商、每个提供商一个文生视频请求、一秒龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每提供商操作上限（默认 `180000`）
|
||||
- 默认跳过 FAL，因为提供商侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行它
|
||||
- 在探测前先从你的登录 shell（`~/.profile`）加载提供商环境变量
|
||||
- 默认优先使用实时/环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实的 shell 凭证
|
||||
- 跳过没有可用认证/配置文件/模型的提供商
|
||||
- 运行共享的内置视频生成 provider 路径
|
||||
- 默认使用对发布安全的冒烟测试路径：非 FAL provider、每个 provider 一个文生视频请求、1 秒龙虾提示词，以及来自 `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` 的每 provider 操作上限（默认 `180000`）
|
||||
- 默认跳过 FAL，因为 provider 侧队列延迟可能主导发布时间；传入 `--video-providers fal` 或 `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"` 可显式运行
|
||||
- 在探测前，从你的登录 shell（`~/.profile`）加载 provider 环境变量
|
||||
- 默认优先使用实时 / 环境变量 API 密钥，而不是已存储的认证配置文件，因此 `auth-profiles.json` 中过期的测试密钥不会掩盖真实 shell 凭证
|
||||
- 跳过没有可用认证 / 配置文件 / 模型的 provider
|
||||
- 默认仅运行 `generate`
|
||||
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 可在可用时也运行已声明的变换模式：
|
||||
- 当提供商声明 `capabilities.imageToVideo.enabled`，且所选提供商/模型在共享全面检查中接受基于 buffer 的本地图像输入时，运行 `imageToVideo`
|
||||
- 当提供商声明 `capabilities.videoToVideo.enabled`，且所选提供商/模型在共享全面检查中接受基于 buffer 的本地视频输入时，运行 `videoToVideo`
|
||||
- 当前在共享全面检查中已声明但跳过的 `imageToVideo` 提供商：
|
||||
- 设置 `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1` 后，在可用时也运行已声明的转换模式：
|
||||
- 当 provider 声明 `capabilities.imageToVideo.enabled`，且所选 provider / 模型在共享扫描中接受基于 buffer 的本地图像输入时，运行 `imageToVideo`
|
||||
- 当 provider 声明 `capabilities.videoToVideo.enabled`，且所选 provider / 模型在共享扫描中接受基于 buffer 的本地视频输入时，运行 `videoToVideo`
|
||||
- 当前在共享扫描中已声明但被跳过的 `imageToVideo` provider：
|
||||
- `vydra`，因为内置 `veo3` 仅支持文本，而内置 `kling` 需要远程图像 URL
|
||||
- 提供商专用的 Vydra 覆盖：
|
||||
- provider 专用的 Vydra 覆盖：
|
||||
- `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts`
|
||||
- 该文件会运行 `veo3` 文生视频，以及默认使用远程图像 URL 固定装置的 `kling` 通道
|
||||
- 该文件会运行 `veo3` 文生视频，以及一个默认使用远程图像 URL 固件的 `kling` 通道
|
||||
- 当前 `videoToVideo` 实时覆盖：
|
||||
- 仅 `runway`，且仅当所选模型为 `runway/gen4_aleph`
|
||||
- 当前在共享全面检查中已声明但跳过的 `videoToVideo` 提供商：
|
||||
- `alibaba`、`qwen`、`xai`，因为这些路径当前需要远程 `http(s)` / MP4 参考 URL
|
||||
- `google`，因为当前共享 Gemini/Veo 通道使用的是基于本地 buffer 的输入，而该路径在共享全面检查中不被接受
|
||||
- `openai`，因为当前共享通道缺少特定组织的视频修补/重混访问保证
|
||||
- 仅 `runway`，且所选模型为 `runway/gen4_aleph`
|
||||
- 当前在共享扫描中已声明但被跳过的 `videoToVideo` provider：
|
||||
- `alibaba`、`qwen`、`xai`，因为这些路径当前要求远程 `http(s)` / MP4 参考 URL
|
||||
- `google`，因为当前共享 Gemini / Veo 通道使用基于本地 buffer 的输入，而该路径在共享扫描中不被接受
|
||||
- `openai`，因为当前共享通道缺少针对特定组织的视频修补 / 混剪访问保证
|
||||
- 可选缩小范围：
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"`
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"`
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 以在默认全面检查中包含每个提供商，包括 FAL
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 以降低每个提供商的操作上限，用于更激进的冒烟运行
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""` 可在默认扫描中包含所有 provider，包括 FAL
|
||||
- `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000` 可将每个 provider 的操作上限降低，以执行更激进的冒烟测试
|
||||
- 可选认证行为：
|
||||
- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` 可强制使用配置文件存储认证，并忽略仅环境变量的覆盖
|
||||
|
||||
## 媒体实时 harness
|
||||
## 实时：媒体 Harness
|
||||
|
||||
- 命令：`pnpm test:live:media`
|
||||
- 目的：
|
||||
- 用途：
|
||||
- 通过一个仓库原生入口点运行共享的图像、音乐和视频实时套件
|
||||
- 自动从 `~/.profile` 加载缺失的提供商环境变量
|
||||
- 默认自动将每个套件缩小到当前具有可用认证的提供商
|
||||
- 自动从 `~/.profile` 加载缺失的 provider 环境变量
|
||||
- 默认自动将每个套件缩小到当前具有可用认证的 provider
|
||||
- 复用 `scripts/test-live.mjs`，因此心跳和静默模式行为保持一致
|
||||
- 示例：
|
||||
- `pnpm test:live:media`
|
||||
|
||||
@ -5,10 +5,10 @@ read_when:
|
||||
summary: 在 OpenClaw 中使用 MiniMax 模型
|
||||
title: MiniMax
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T09:40:18Z"
|
||||
generated_at: "2026-04-25T10:04:00Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ddf6cfb68ef5fcaa360a2a7ebb9e3ce130100a59b014643091449a07654c7c6f
|
||||
source_hash: 666e8fd958a2566a66bc2262a1b23e3253f4ed1367c4e684380041fd935ab4af
|
||||
source_path: providers/minimax.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,32 +19,32 @@ MiniMax 还提供：
|
||||
|
||||
- 通过 T2A v2 内置语音合成
|
||||
- 通过 `MiniMax-VL-01` 内置图像理解
|
||||
- 通过 `music-2.5+` 内置音乐生成
|
||||
- 通过 `music-2.6` 内置音乐生成
|
||||
- 通过 MiniMax Coding Plan 搜索 API 内置 `web_search`
|
||||
|
||||
提供商拆分：
|
||||
提供商划分：
|
||||
|
||||
| Provider ID | 认证方式 | 能力 |
|
||||
| ---------------- | -------- | -------------------------------------------------------------- |
|
||||
| `minimax` | API 密钥 | 文本、图像生成、图像理解、语音、网页搜索 |
|
||||
| `minimax-portal` | OAuth | 文本、图像生成、图像理解、语音 |
|
||||
| Provider ID | 认证方式 | 能力 |
|
||||
| ---------------- | -------- | ------------------------------------------------------------ |
|
||||
| `minimax` | API 密钥 | 文本、图像生成、图像理解、语音、web 搜索 |
|
||||
| `minimax-portal` | OAuth | 文本、图像生成、图像理解、语音 |
|
||||
|
||||
## 内置目录
|
||||
|
||||
| 模型 | 类型 | 说明 |
|
||||
| ------------------------ | ---------------- | ---------------------------------------- |
|
||||
| `MiniMax-M2.7` | 聊天（推理） | 默认托管推理模型 |
|
||||
| `MiniMax-M2.7-highspeed` | 聊天（推理） | 更快的 M2.7 推理层级 |
|
||||
| `MiniMax-VL-01` | 视觉 | 图像理解模型 |
|
||||
| `image-01` | 图像生成 | 文生图和图像到图像编辑 |
|
||||
| `music-2.5+` | 音乐生成 | 默认音乐模型 |
|
||||
| `music-2.5` | 音乐生成 | 上一代音乐生成层级 |
|
||||
| `music-2.0` | 音乐生成 | 旧版音乐生成层级 |
|
||||
| `MiniMax-Hailuo-2.3` | 视频生成 | 文生视频和图像参考流程 |
|
||||
| 模型 | 类型 | 描述 |
|
||||
| ------------------------ | ---------------- | ------------------------------------ |
|
||||
| `MiniMax-M2.7` | 聊天（推理） | 默认托管推理模型 |
|
||||
| `MiniMax-M2.7-highspeed` | 聊天（推理） | 更快的 M2.7 推理层级 |
|
||||
| `MiniMax-VL-01` | 视觉 | 图像理解模型 |
|
||||
| `image-01` | 图像生成 | 文生图和图生图编辑 |
|
||||
| `music-2.6` | 音乐生成 | 默认音乐模型 |
|
||||
| `music-2.5` | 音乐生成 | 上一代音乐生成层级 |
|
||||
| `music-2.0` | 音乐生成 | 旧版音乐生成层级 |
|
||||
| `MiniMax-Hailuo-2.3` | 视频生成 | 文生视频和图像参考流程 |
|
||||
|
||||
## 入门指南
|
||||
|
||||
选择你偏好的认证方式，并按照设置步骤操作。
|
||||
选择你偏好的认证方式，然后按照设置步骤操作。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="OAuth（Coding Plan）">
|
||||
@ -86,11 +86,11 @@ MiniMax 还提供：
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
OAuth 设置使用 `minimax-portal` 提供商 id。模型引用遵循 `minimax-portal/MiniMax-M2.7` 这种格式。
|
||||
OAuth 设置使用 `minimax-portal` provider id。模型引用采用 `minimax-portal/MiniMax-M2.7` 这种形式。
|
||||
</Note>
|
||||
|
||||
<Tip>
|
||||
MiniMax Coding Plan 邀请链接（9 折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
|
||||
MiniMax Coding Plan 推荐链接（享 9 折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
|
||||
</Tip>
|
||||
|
||||
</Tab>
|
||||
@ -173,11 +173,11 @@ MiniMax 还提供：
|
||||
```
|
||||
|
||||
<Warning>
|
||||
在兼容 Anthropic 的流式传输路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。MiniMax 的流式端点会以 OpenAI 风格的 delta 分块而不是原生 Anthropic thinking 块发出 `reasoning_content`，如果在未显式配置的情况下保持启用，可能会将内部推理泄露到可见输出中。
|
||||
在兼容 Anthropic 的流式传输路径上，除非你显式自行设置 `thinking`，否则 OpenClaw 默认会禁用 MiniMax thinking。MiniMax 的流式端点会以 OpenAI 风格的 delta 分块发送 `reasoning_content`，而不是原生 Anthropic thinking blocks；如果在未明确配置的情况下启用，可能会将内部推理泄露到可见输出中。
|
||||
</Warning>
|
||||
|
||||
<Note>
|
||||
API 密钥设置使用 `minimax` 提供商 id。模型引用遵循 `minimax/MiniMax-M2.7` 这种格式。
|
||||
API 密钥设置使用 `minimax` provider id。模型引用采用 `minimax/MiniMax-M2.7` 这种形式。
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
@ -185,7 +185,7 @@ MiniMax 还提供：
|
||||
|
||||
## 通过 `openclaw configure` 配置
|
||||
|
||||
使用交互式配置向导设置 MiniMax，而无需编辑 JSON：
|
||||
使用交互式配置向导来设置 MiniMax，无需手动编辑 JSON：
|
||||
|
||||
<Steps>
|
||||
<Step title="启动向导">
|
||||
@ -194,12 +194,12 @@ MiniMax 还提供：
|
||||
```
|
||||
</Step>
|
||||
<Step title="选择模型/认证">
|
||||
从菜单中选择 **模型/认证**。
|
||||
在菜单中选择 **模型/认证**。
|
||||
</Step>
|
||||
<Step title="选择一种 MiniMax 认证选项">
|
||||
<Step title="选择一个 MiniMax 认证选项">
|
||||
选择以下可用的 MiniMax 选项之一：
|
||||
|
||||
| 认证选项 | 说明 |
|
||||
| 认证选项 | 描述 |
|
||||
| --- | --- |
|
||||
| `minimax-global-oauth` | 国际版 OAuth（Coding Plan） |
|
||||
| `minimax-cn-oauth` | 中国版 OAuth（Coding Plan） |
|
||||
@ -212,16 +212,16 @@ MiniMax 还提供：
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## 功能
|
||||
## 能力
|
||||
|
||||
### 图像生成
|
||||
|
||||
MiniMax 插件会为 `image_generate` 工具注册 `image-01` 模型。它支持：
|
||||
MiniMax 插件为 `image_generate` 工具注册了 `image-01` 模型。它支持：
|
||||
|
||||
- **文生图生成**，支持宽高比控制
|
||||
- **图像到图像编辑**（主体参考），支持宽高比控制
|
||||
- 每次请求最多 **9 张输出图像**
|
||||
- 每次编辑请求最多 **1 张参考图像**
|
||||
- **图生图编辑**（主体参考），支持宽高比控制
|
||||
- 每次请求最多输出 **9 张图像**
|
||||
- 每次编辑请求最多支持 **1 张参考图像**
|
||||
- 支持的宽高比：`1:1`、`16:9`、`4:3`、`3:2`、`2:3`、`3:4`、`9:16`、`21:9`
|
||||
|
||||
要将 MiniMax 用于图像生成，请将其设置为图像生成提供商：
|
||||
@ -236,72 +236,56 @@ MiniMax 插件会为 `image_generate` 工具注册 `image-01` 模型。它支持
|
||||
}
|
||||
```
|
||||
|
||||
该插件使用与文本模型相同的 `MINIMAX_API_KEY` 或 OAuth 认证。如果 MiniMax 已经设置完成，则无需额外配置。
|
||||
该插件与文本模型使用相同的 `MINIMAX_API_KEY` 或 OAuth 认证。如果你已经设置好了 MiniMax，则无需额外配置。
|
||||
|
||||
`minimax` 和 `minimax-portal` 都会使用相同的 `image-01` 模型注册 `image_generate`。
|
||||
API 密钥设置使用 `MINIMAX_API_KEY`；OAuth 设置则可以改用内置的
|
||||
`minimax-portal` 认证路径。
|
||||
`minimax` 和 `minimax-portal` 都会使用相同的 `image-01` 模型注册 `image_generate`。API 密钥设置使用 `MINIMAX_API_KEY`；OAuth 设置则可以改用内置的 `minimax-portal` 认证路径。
|
||||
|
||||
当新手引导或 API 密钥设置写入显式的 `models.providers.minimax`
|
||||
条目时，OpenClaw 会将 `MiniMax-M2.7` 和
|
||||
`MiniMax-M2.7-highspeed` 实体化为仅文本的聊天模型。图像理解则通过由插件拥有的 `MiniMax-VL-01` 媒体提供商单独提供。
|
||||
当新手引导或 API 密钥设置写入显式的 `models.providers.minimax` 条目时，OpenClaw 会将 `MiniMax-M2.7` 和 `MiniMax-M2.7-highspeed` 具体化为仅文本聊天模型。图像理解则通过插件自有的 `MiniMax-VL-01` 媒体提供商单独公开。
|
||||
|
||||
<Note>
|
||||
共享工具参数、提供商选择和故障切换行为请参阅 [图像生成](/zh-CN/tools/image-generation)。
|
||||
共享工具参数、提供商选择和故障切换行为，参见 [图像生成](/zh-CN/tools/image-generation)。
|
||||
</Note>
|
||||
|
||||
### 文本转语音
|
||||
|
||||
内置的 `minimax` 插件还会将 MiniMax T2A v2 注册为
|
||||
`messages.tts` 的语音提供商。
|
||||
内置的 `minimax` 插件会将 MiniMax T2A v2 注册为 `messages.tts` 的语音提供商。
|
||||
|
||||
- 默认 TTS 模型：`speech-2.8-hd`
|
||||
- 默认音色：`English_expressive_narrator`
|
||||
- 支持的内置模型 id 包括 `speech-2.8-hd`、`speech-2.8-turbo`、
|
||||
`speech-2.6-hd`、`speech-2.6-turbo`、`speech-02-hd`、
|
||||
`speech-02-turbo`、`speech-01-hd` 和 `speech-01-turbo`。
|
||||
- 认证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是
|
||||
`minimax-portal` OAuth/token 认证配置文件，再然后是 Token Plan 环境变量键
|
||||
（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、
|
||||
`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。
|
||||
- 如果未配置 TTS 主机，OpenClaw 会复用已配置的
|
||||
`minimax-portal` OAuth 主机，并去掉兼容 Anthropic 的路径后缀，
|
||||
例如 `/anthropic`。
|
||||
- 默认语音：`English_expressive_narrator`
|
||||
- 支持的内置模型 id 包括 `speech-2.8-hd`、`speech-2.8-turbo`、`speech-2.6-hd`、`speech-2.6-turbo`、`speech-02-hd`、`speech-02-turbo`、`speech-01-hd` 和 `speech-01-turbo`。
|
||||
- 认证解析顺序为 `messages.tts.providers.minimax.apiKey`，然后是 `minimax-portal` OAuth/token 认证配置文件，然后是 Token Plan 环境变量键（`MINIMAX_OAUTH_TOKEN`、`MINIMAX_CODE_PLAN_KEY`、`MINIMAX_CODING_API_KEY`），最后是 `MINIMAX_API_KEY`。
|
||||
- 如果未配置 TTS 主机，OpenClaw 会复用已配置的 `minimax-portal` OAuth 主机，并移除诸如 `/anthropic` 之类的兼容 Anthropic 路径后缀。
|
||||
- 普通音频附件保持为 MP3。
|
||||
- Feishu 和 Telegram 等语音便笺目标会通过 `ffmpeg` 从 MiniMax
|
||||
MP3 转码为 48 kHz Opus，因为 Feishu/Lark 文件 API 对原生音频消息只接受
|
||||
`file_type: "opus"`。
|
||||
- MiniMax T2A 接受小数 `speed` 和 `vol`，但 `pitch` 会以整数发送；
|
||||
OpenClaw 会在发起 API 请求前截断带小数的 `pitch` 值。
|
||||
- Feishu 和 Telegram 等语音便笺目标会通过 `ffmpeg` 将 MiniMax MP3 转码为 48 kHz Opus，因为 Feishu/Lark 文件 API 对原生音频消息仅接受 `file_type: "opus"`。
|
||||
- MiniMax T2A 接受小数 `speed` 和 `vol`，但 `pitch` 会以整数形式发送；OpenClaw 会在发起 API 请求前截断小数 `pitch` 值。
|
||||
|
||||
| 设置 | 环境变量 | 默认值 | 说明 |
|
||||
| ---------------------------------------- | ---------------------- | ----------------------------- | ---------------------------- |
|
||||
| `messages.tts.providers.minimax.baseUrl` | `MINIMAX_API_HOST` | `https://api.minimax.io` | MiniMax T2A API 主机。 |
|
||||
| `messages.tts.providers.minimax.model` | `MINIMAX_TTS_MODEL` | `speech-2.8-hd` | TTS 模型 id。 |
|
||||
| `messages.tts.providers.minimax.voiceId` | `MINIMAX_TTS_VOICE_ID` | `English_expressive_narrator` | 用于语音输出的音色 id。 |
|
||||
| `messages.tts.providers.minimax.speed` | | `1.0` | 播放速度，`0.5..2.0`。 |
|
||||
| `messages.tts.providers.minimax.vol` | | `1.0` | 音量，`(0, 10]`。 |
|
||||
| `messages.tts.providers.minimax.pitch` | | `0` | 整数音高偏移，`-12..12`。 |
|
||||
| 设置 | 环境变量 | 默认值 | 描述 |
|
||||
| ---------------------------------------- | ---------------------- | ----------------------------- | ------------------------------ |
|
||||
| `messages.tts.providers.minimax.baseUrl` | `MINIMAX_API_HOST` | `https://api.minimax.io` | MiniMax T2A API 主机。 |
|
||||
| `messages.tts.providers.minimax.model` | `MINIMAX_TTS_MODEL` | `speech-2.8-hd` | TTS 模型 id。 |
|
||||
| `messages.tts.providers.minimax.voiceId` | `MINIMAX_TTS_VOICE_ID` | `English_expressive_narrator` | 用于语音输出的 voice id。 |
|
||||
| `messages.tts.providers.minimax.speed` | | `1.0` | 播放速度，`0.5..2.0`。 |
|
||||
| `messages.tts.providers.minimax.vol` | | `1.0` | 音量，`(0, 10]`。 |
|
||||
| `messages.tts.providers.minimax.pitch` | | `0` | 整数音高偏移，`-12..12`。 |
|
||||
|
||||
### 音乐生成
|
||||
|
||||
内置的 `minimax` 插件还会通过共享的
|
||||
`music_generate` 工具注册音乐生成功能。
|
||||
内置的 `minimax` 插件还会通过共享的 `music_generate` 工具注册音乐生成能力。
|
||||
|
||||
- 默认音乐模型：`minimax/music-2.5+`
|
||||
- 还支持 `minimax/music-2.5` 和 `minimax/music-2.0`
|
||||
- 默认音乐模型：`minimax/music-2.6`
|
||||
- 也支持 `minimax/music-2.5` 和 `minimax/music-2.0`
|
||||
- 提示词控制项：`lyrics`、`instrumental`、`durationSeconds`
|
||||
- 输出格式：`mp3`
|
||||
- 基于会话的运行会通过共享的任务/Status 流程分离执行，包括 `action: "status"`
|
||||
- 基于会话的运行会通过共享任务/状态流程分离执行，包括 `action: "status"`
|
||||
|
||||
要将 MiniMax 用作默认音乐提供商：
|
||||
要将 MiniMax 设为默认音乐提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
musicGenerationModel: {
|
||||
primary: "minimax/music-2.5+",
|
||||
primary: "minimax/music-2.6",
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -309,19 +293,18 @@ API 密钥设置使用 `MINIMAX_API_KEY`；OAuth 设置则可以改用内置的
|
||||
```
|
||||
|
||||
<Note>
|
||||
共享工具参数、提供商选择和故障切换行为请参阅 [音乐生成](/zh-CN/tools/music-generation)。
|
||||
共享工具参数、提供商选择和故障切换行为，参见 [音乐生成](/zh-CN/tools/music-generation)。
|
||||
</Note>
|
||||
|
||||
### 视频生成
|
||||
|
||||
内置的 `minimax` 插件还会通过共享的
|
||||
`video_generate` 工具注册视频生成功能。
|
||||
内置的 `minimax` 插件还会通过共享的 `video_generate` 工具注册视频生成能力。
|
||||
|
||||
- 默认视频模型：`minimax/MiniMax-Hailuo-2.3`
|
||||
- 模式：文生视频和单图参考流程
|
||||
- 支持 `aspectRatio` 和 `resolution`
|
||||
|
||||
要将 MiniMax 用作默认视频提供商：
|
||||
要将 MiniMax 设为默认视频提供商：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -336,68 +319,65 @@ API 密钥设置使用 `MINIMAX_API_KEY`；OAuth 设置则可以改用内置的
|
||||
```
|
||||
|
||||
<Note>
|
||||
共享工具参数、提供商选择和故障切换行为请参阅 [视频生成](/zh-CN/tools/video-generation)。
|
||||
共享工具参数、提供商选择和故障切换行为，参见 [视频生成](/zh-CN/tools/video-generation)。
|
||||
</Note>
|
||||
|
||||
### 图像理解
|
||||
|
||||
MiniMax 插件将图像理解与文本
|
||||
目录分开注册：
|
||||
MiniMax 插件将图像理解与文本目录分开注册：
|
||||
|
||||
| Provider ID | 默认图像模型 |
|
||||
| ---------------- | ------------------- |
|
||||
| `minimax` | `MiniMax-VL-01` |
|
||||
| `minimax-portal` | `MiniMax-VL-01` |
|
||||
| Provider ID | 默认图像模型 |
|
||||
| ---------------- | ----------------- |
|
||||
| `minimax` | `MiniMax-VL-01` |
|
||||
| `minimax-portal` | `MiniMax-VL-01` |
|
||||
|
||||
这就是为什么自动媒体路由即使在内置文本提供商目录仍显示仅文本的 M2.7 聊天引用时，
|
||||
也可以使用 MiniMax 图像理解。
|
||||
这就是为什么自动媒体路由即使在内置文本提供商目录仍然只显示仅文本的 M2.7 聊天引用时，也可以使用 MiniMax 图像理解。
|
||||
|
||||
### 网页搜索
|
||||
### Web 搜索
|
||||
|
||||
MiniMax 插件还会通过 MiniMax Coding Plan
|
||||
搜索 API 注册 `web_search`。
|
||||
MiniMax 插件还通过 MiniMax Coding Plan 搜索 API 注册了 `web_search`。
|
||||
|
||||
- 提供商 id：`minimax`
|
||||
- provider id：`minimax`
|
||||
- 结构化结果：标题、URL、摘要、相关查询
|
||||
- 首选环境变量：`MINIMAX_CODE_PLAN_KEY`
|
||||
- 可接受的环境变量别名：`MINIMAX_CODING_API_KEY`
|
||||
- 兼容性回退：当 `MINIMAX_API_KEY` 已经指向 coding-plan token 时可使用它
|
||||
- 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后是 `MINIMAX_API_HOST`，再然后是 MiniMax 提供商基础 URL
|
||||
- 搜索始终保留在提供商 id `minimax` 上；OAuth 中国版/国际版设置仍可通过 `models.providers.minimax-portal.baseUrl` 间接引导区域
|
||||
- 兼容性回退：当 `MINIMAX_API_KEY` 已指向 coding-plan token 时使用它
|
||||
- 区域复用：`plugins.entries.minimax.config.webSearch.region`，然后 `MINIMAX_API_HOST`，再然后是 MiniMax 提供商基础 URL
|
||||
- 搜索始终使用 provider id `minimax`；OAuth 中国版/国际版设置仍可通过 `models.providers.minimax-portal.baseUrl` 间接引导区域
|
||||
|
||||
配置位于 `plugins.entries.minimax.config.webSearch.*` 下。
|
||||
|
||||
<Note>
|
||||
完整的网页搜索配置和用法请参阅 [MiniMax 搜索](/zh-CN/tools/minimax-search)。
|
||||
完整的 Web 搜索配置和用法，参见 [MiniMax Search](/zh-CN/tools/minimax-search)。
|
||||
</Note>
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="配置选项">
|
||||
| 选项 | 说明 |
|
||||
| 选项 | 描述 |
|
||||
| --- | --- |
|
||||
| `models.providers.minimax.baseUrl` | 优先使用 `https://api.minimax.io/anthropic`（兼容 Anthropic）；`https://api.minimax.io/v1` 可选，用于兼容 OpenAI 的负载 |
|
||||
| `models.providers.minimax.api` | 优先使用 `anthropic-messages`；`openai-completions` 可选，用于兼容 OpenAI 的负载 |
|
||||
| `models.providers.minimax.baseUrl` | 优先使用 `https://api.minimax.io/anthropic`（兼容 Anthropic）；`https://api.minimax.io/v1` 可选，用于兼容 OpenAI 的载荷 |
|
||||
| `models.providers.minimax.api` | 优先使用 `anthropic-messages`；`openai-completions` 可选，用于兼容 OpenAI 的载荷 |
|
||||
| `models.providers.minimax.apiKey` | MiniMax API 密钥（`MINIMAX_API_KEY`） |
|
||||
| `models.providers.minimax.models` | 定义 `id`、`name`、`reasoning`、`contextWindow`、`maxTokens`、`cost` |
|
||||
| `agents.defaults.models` | 为你希望加入 allowlist 的模型设置别名 |
|
||||
| `agents.defaults.models` | 为你想加入允许列表的模型设置别名 |
|
||||
| `models.mode` | 如果你想在内置模型之外添加 MiniMax，请保持为 `merge` |
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="thinking 默认值">
|
||||
在 `api: "anthropic-messages"` 上，除非参数/配置中已经显式设置了 thinking，否则 OpenClaw 会注入 `thinking: { type: "disabled" }`。
|
||||
在 `api: "anthropic-messages"` 下，除非已在 params/配置中显式设置 thinking，否则 OpenClaw 会注入 `thinking: { type: "disabled" }`。
|
||||
|
||||
这样可以防止 MiniMax 的流式端点以 OpenAI 风格的 delta 分块发出 `reasoning_content`，从而将内部推理泄露到可见输出中。
|
||||
这样可以防止 MiniMax 的流式端点以 OpenAI 风格的 delta 分块发出 `reasoning_content`，从而避免将内部推理泄露到可见输出中。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="快速模式">
|
||||
`/fast on` 或 `params.fastMode: true` 会在兼容 Anthropic 的流式路径上，将 `MiniMax-M2.7` 改写为 `MiniMax-M2.7-highspeed`。
|
||||
`/fast on` 或 `params.fastMode: true` 会在兼容 Anthropic 的流式路径上将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="回退示例">
|
||||
**最适合：** 将你最强的最新一代模型保留为主模型，并在失败时回退到 MiniMax M2.7。下面的示例使用 Opus 作为具体的主模型；你可以替换为自己偏好的最新一代主模型。
|
||||
**最适合：** 将你最强的最新一代模型保留为主模型，并在失败时回退到 MiniMax M2.7。下面的示例使用 Opus 作为具体主模型；你可以替换为你偏好的最新一代主模型。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -419,43 +399,43 @@ MiniMax 插件还会通过 MiniMax Coding Plan
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Coding Plan 使用详情">
|
||||
<Accordion title="Coding Plan 使用细节">
|
||||
- Coding Plan 用量 API：`https://api.minimaxi.com/v1/api/openplatform/coding_plan/remains`（需要 coding plan key）。
|
||||
- OpenClaw 会将 MiniMax coding-plan 用量标准化为与其他提供商相同的“剩余百分比”显示。MiniMax 原始的 `usage_percent` / `usagePercent` 字段表示的是剩余额度，而不是已消耗额度，因此 OpenClaw 会对其进行反转。若存在按次数计数的字段，则优先使用这些字段。
|
||||
- 当 API 返回 `model_remains` 时，OpenClaw 会优先选择聊天模型条目，在需要时从 `start_time` / `end_time` 推导窗口标签，并将所选模型名称包含到套餐标签中，以便更容易区分 coding-plan 窗口。
|
||||
- 用量快照会将 `minimax`、`minimax-cn` 和 `minimax-portal` 视为同一个 MiniMax 配额面，并优先使用已存储的 MiniMax OAuth，再回退到 Coding Plan key 环境变量。
|
||||
- OpenClaw 会将 MiniMax coding-plan 用量规范化为与其他提供商相同的“% 剩余”显示。MiniMax 原始的 `usage_percent` / `usagePercent` 字段表示的是剩余额度，而不是已用额度，因此 OpenClaw 会对其取反。有计数字段时，优先使用计数字段。
|
||||
- 当 API 返回 `model_remains` 时，OpenClaw 会优先选择聊天模型条目，必要时从 `start_time` / `end_time` 推导窗口标签，并将所选模型名称包含到 plan 标签中，以便更容易区分 coding-plan 窗口。
|
||||
- 用量快照会将 `minimax`、`minimax-cn` 和 `minimax-portal` 视为同一个 MiniMax 配额面，并优先使用已存储的 MiniMax OAuth，只有在此之后才会回退到 Coding Plan key 环境变量。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 说明
|
||||
## 备注
|
||||
|
||||
- 模型引用遵循认证路径：
|
||||
- API 密钥设置：`minimax/<model>`
|
||||
- OAuth 设置：`minimax-portal/<model>`
|
||||
- 默认聊天模型：`MiniMax-M2.7`
|
||||
- 备用聊天模型：`MiniMax-M2.7-highspeed`
|
||||
- 新手引导和直接 API 密钥设置会为两个 M2.7 变体写入仅文本的模型定义
|
||||
- 图像理解使用由插件拥有的 `MiniMax-VL-01` 媒体提供商
|
||||
- 新手引导和直接 API 密钥设置会为这两个 M2.7 变体写入仅文本模型定义
|
||||
- 图像理解使用插件自有的 `MiniMax-VL-01` 媒体提供商
|
||||
- 如果你需要精确的成本跟踪，请更新 `models.json` 中的定价值
|
||||
- 使用 `openclaw models list` 确认当前提供商 id，然后通过 `openclaw models set minimax/MiniMax-M2.7` 或 `openclaw models set minimax-portal/MiniMax-M2.7` 进行切换
|
||||
- 使用 `openclaw models list` 确认当前 provider id，然后使用 `openclaw models set minimax/MiniMax-M2.7` 或 `openclaw models set minimax-portal/MiniMax-M2.7` 进行切换
|
||||
|
||||
<Tip>
|
||||
MiniMax Coding Plan 邀请链接（9 折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
|
||||
MiniMax Coding Plan 推荐链接（享 9 折优惠）：[MiniMax Coding Plan](https://platform.minimax.io/subscribe/coding-plan?code=DbXJTRClnb&source=link)
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
有关提供商规则，请参阅 [模型提供商](/zh-CN/concepts/model-providers)。
|
||||
提供商规则参见 [模型提供商](/zh-CN/concepts/model-providers)。
|
||||
</Note>
|
||||
|
||||
## 故障排除
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title='"未知模型：minimax/MiniMax-M2.7"'>
|
||||
这通常意味着**MiniMax 提供商未配置**（没有匹配的提供商条目，且也未找到 MiniMax 认证配置文件/环境变量键）。此检测的修复已包含在 **2026.1.12** 中。可通过以下方式修复：
|
||||
<Accordion title='"Unknown model: minimax/MiniMax-M2.7"'>
|
||||
这通常意味着 **MiniMax 提供商尚未配置**（没有匹配的提供商条目，且未找到 MiniMax 认证配置文件/环境变量键）。此检测的修复已包含在 **2026.1.12** 中。可通过以下方式修复：
|
||||
|
||||
- 升级到 **2026.1.12**（或直接从源码 `main` 运行），然后重启 Gateway 网关。
|
||||
- 升级到 **2026.1.12**（或从源码 `main` 运行），然后重启 Gateway 网关。
|
||||
- 运行 `openclaw configure` 并选择一个 **MiniMax** 认证选项，或
|
||||
- 手动添加匹配的 `models.providers.minimax` 或 `models.providers.minimax-portal` 配置块，或
|
||||
- 手动添加匹配的 `models.providers.minimax` 或 `models.providers.minimax-portal` 块，或
|
||||
- 设置 `MINIMAX_API_KEY`、`MINIMAX_OAUTH_TOKEN` 或 MiniMax 认证配置文件，以便注入匹配的提供商。
|
||||
|
||||
请确保模型 id **区分大小写**：
|
||||
@ -491,10 +471,10 @@ MiniMax Coding Plan 邀请链接（9 折优惠）：[MiniMax Coding Plan](https:
|
||||
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
|
||||
共享视频工具参数和提供商选择。
|
||||
</Card>
|
||||
<Card title="MiniMax 搜索" href="/zh-CN/tools/minimax-search" icon="magnifying-glass">
|
||||
通过 MiniMax Coding Plan 进行网页搜索配置。
|
||||
<Card title="MiniMax Search" href="/zh-CN/tools/minimax-search" icon="magnifying-glass">
|
||||
通过 MiniMax Coding Plan 进行 Web 搜索配置。
|
||||
</Card>
|
||||
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
|
||||
常规故障排除和常见问题。
|
||||
通用故障排除和常见问题。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -6,17 +6,17 @@ read_when:
|
||||
summary: 使用共享提供商生成音乐，包括由工作流支持的插件
|
||||
title: 音乐生成
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T20:30:50Z"
|
||||
generated_at: "2026-04-25T10:03:58Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: cc6da03cd1cc5728e903b3c5bf0c47da65642842e38c1006419e2f2ce2400bda
|
||||
source_hash: fe66c6dfb54c71b1d08a486c574e8a86cf3731d5339b44b9eef121f045c13cb8
|
||||
source_path: tools/music-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
`music_generate` 工具允许智能体通过共享的音乐生成功能创建音乐或音频，并可使用已配置的提供商，例如 Google、MiniMax，以及通过工作流配置的 ComfyUI。
|
||||
`music_generate` 工具允许智能体通过共享的音乐生成能力，结合已配置的提供商（如 Google、MiniMax，以及通过工作流配置的 ComfyUI）来创建音乐或音频。
|
||||
|
||||
对于由共享提供商支持的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务台账中跟踪它，然后在音轨准备就绪时再次唤醒智能体，以便智能体将完成的音频发布回原始渠道。
|
||||
对于基于共享提供商的智能体会话，OpenClaw 会将音乐生成作为后台任务启动，在任务账本中跟踪它，然后在音轨准备就绪后再次唤醒智能体，以便智能体将完成的音频发回原始渠道。
|
||||
|
||||
<Note>
|
||||
只有在至少有一个音乐生成提供商可用时，内置共享工具才会出现。如果你在智能体的工具中看不到 `music_generate`，请配置 `agents.defaults.musicGenerationModel` 或设置提供商 API 密钥。
|
||||
@ -24,7 +24,7 @@ x-i18n:
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 由共享提供商支持的生成
|
||||
### 基于共享提供商的生成
|
||||
|
||||
1. 为至少一个提供商设置 API 密钥，例如 `GEMINI_API_KEY` 或 `MINIMAX_API_KEY`。
|
||||
2. 可选：设置你偏好的模型：
|
||||
@ -41,13 +41,13 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
3. 向智能体提问：_“生成一首欢快的 synthpop 曲目，主题是在霓虹城市中夜间驾车。”_
|
||||
3. 向智能体发出请求：_“生成一首关于夜晚驾车穿过霓虹都市的欢快 synthpop 曲目。”_
|
||||
|
||||
智能体会自动调用 `music_generate`。不需要工具 allow-listing。
|
||||
智能体会自动调用 `music_generate`。无需设置工具允许列表。
|
||||
|
||||
对于没有由会话支持的智能体运行的直接同步上下文，内置工具仍会回退到内联生成，并在工具结果中返回最终媒体路径。
|
||||
对于没有基于会话的智能体运行的直接同步上下文，内置工具仍会回退为内联生成，并在工具结果中返回最终媒体路径。
|
||||
|
||||
提示词示例：
|
||||
示例提示词：
|
||||
|
||||
```text
|
||||
Generate a cinematic piano track with soft strings and no vocals.
|
||||
@ -59,11 +59,11 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
|
||||
|
||||
### 由工作流驱动的 Comfy 生成
|
||||
|
||||
内置的 `comfy` 插件会通过音乐生成提供商注册表接入共享 `music_generate` 工具。
|
||||
内置的 `comfy` 插件通过音乐生成提供商注册表接入共享 `music_generate` 工具。
|
||||
|
||||
1. 使用工作流 JSON 以及提示词/输出节点配置 `plugins.entries.comfy.config.music`。
|
||||
1. 配置 `plugins.entries.comfy.config.music`，包括工作流 JSON 以及提示词/输出节点。
|
||||
2. 如果你使用 Comfy Cloud，请设置 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY`。
|
||||
3. 向智能体请求生成音乐，或直接调用该工具。
|
||||
3. 请求智能体生成音乐，或直接调用该工具。
|
||||
|
||||
示例：
|
||||
|
||||
@ -73,29 +73,29 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
|
||||
|
||||
## 共享内置提供商支持
|
||||
|
||||
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | 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` |
|
||||
| 提供商 | 默认模型 | 参考输入 | 支持的控制项 | 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.6` | 无 | `lyrics`、`instrumental`、`durationSeconds`、`format=mp3` | `MINIMAX_API_KEY` |
|
||||
|
||||
### 已声明的能力矩阵
|
||||
|
||||
这是 `music_generate`、契约测试以及共享实时扫描所使用的显式模式契约。
|
||||
|
||||
| 提供商 | `generate` | `edit` | 编辑限制 | 共享实时测试通道 |
|
||||
| ------ | ---------- | ------ | -------- | -------------------------------------------------------------------- |
|
||||
| ComfyUI | 是 | 是 | 1 张图像 | 不在共享扫描中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 |
|
||||
| Google | 是 | 是 | 10 张图像 | `generate`、`edit` |
|
||||
| MiniMax | 是 | 否 | 无 | `generate` |
|
||||
| 提供商 | `generate` | `edit` | 编辑限制 | 共享实时测试通道 |
|
||||
| ------ | ---------- | ------ | -------- | -------------------------------------------------------------------------- |
|
||||
| ComfyUI | 是 | 是 | 1 张图像 | 不在共享扫描中；由 `extensions/comfy/comfy.live.test.ts` 覆盖 |
|
||||
| Google | 是 | 是 | 10 张图像 | `generate`、`edit` |
|
||||
| MiniMax | 是 | 否 | 无 | `generate` |
|
||||
|
||||
使用 `action: "list"` 可在运行时查看可用的共享提供商和模型：
|
||||
使用 `action: "list"` 可在运行时检查可用的共享提供商和模型：
|
||||
|
||||
```text
|
||||
/tool music_generate action=list
|
||||
```
|
||||
|
||||
使用 `action: "status"` 可查看当前由会话支持的音乐任务：
|
||||
使用 `action: "status"` 可检查当前基于会话的音乐任务状态：
|
||||
|
||||
```text
|
||||
/tool music_generate action=status
|
||||
@ -109,44 +109,44 @@ 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 | 当提供商支持时，以秒为单位的目标时长提示 |
|
||||
| `timeoutMs` | 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 | 当提供商支持时，目标时长（秒）提示 |
|
||||
| `timeoutMs` | number | 可选的提供商请求超时时间（毫秒） |
|
||||
| `format` | string | 输出格式提示（`mp3` 或 `wav`），前提是提供商支持 |
|
||||
| `filename` | string | 输出文件名提示 |
|
||||
|
||||
并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证硬性限制，例如输入数量。当提供商支持时长但其最大值小于请求值时，OpenClaw 会自动钳制到最接近的受支持时长。对于真正不受支持的可选提示，当所选提供商或模型无法满足时，会忽略这些提示并给出警告。
|
||||
并非所有提供商都支持所有参数。OpenClaw 仍会在提交前验证硬性限制，例如输入数量。当提供商支持时长但其最大值小于请求值时，OpenClaw 会自动将其限制到最接近的受支持时长。对于真正不受支持的可选提示，当所选提供商或模型无法满足时，会忽略这些提示并给出警告。
|
||||
|
||||
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间钳制时长时，返回的 `durationSeconds` 反映的是提交值，而 `details.normalization.durationSeconds` 会显示从请求值到实际应用值的映射。
|
||||
工具结果会报告已应用的设置。当 OpenClaw 在提供商回退期间限制时长时，返回的 `durationSeconds` 反映的是提交值，而 `details.normalization.durationSeconds` 会显示从请求值到应用值的映射。
|
||||
|
||||
## 共享提供商支持路径的异步行为
|
||||
## 共享提供商路径的异步行为
|
||||
|
||||
- 由会话支持的智能体运行：`music_generate` 会创建后台任务，立即返回已启动/任务响应，并在后续智能体消息中稍后发布完成的音轨。
|
||||
- 防止重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续的 `music_generate` 调用会返回任务状态，而不是启动另一次生成。
|
||||
- 状态查询：使用 `action: "status"` 可查看当前活跃的、由会话支持的音乐任务，而不会启动新任务。
|
||||
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可查看该生成任务的排队中、运行中和终态状态。
|
||||
- 完成唤醒：OpenClaw 会将一个内部完成事件注入回同一会话，以便模型自行编写面向用户的后续消息。
|
||||
- 提示词提示：当同一会话中已有音乐任务在进行时，后续用户/手动轮次会收到一个小型运行时提示，以便模型不会盲目再次调用 `music_generate`。
|
||||
- 无会话回退：在没有真实智能体会话的直接/本地上下文中，仍会以内联方式运行，并在同一轮返回最终音频结果。
|
||||
- 基于会话的智能体运行：`music_generate` 会创建后台任务，立即返回已启动/任务响应，并稍后通过后续智能体消息发布完成的曲目。
|
||||
- 防止重复：当该后台任务仍处于 `queued` 或 `running` 状态时，同一会话中后续的 `music_generate` 调用会返回任务状态，而不是启动新的生成任务。
|
||||
- 状态查询：使用 `action: "status"` 可检查当前基于会话的音乐任务，而不会启动新任务。
|
||||
- 任务跟踪：使用 `openclaw tasks list` 或 `openclaw tasks show <taskId>` 可检查生成任务的排队、运行中和终态状态。
|
||||
- 完成唤醒：OpenClaw 会将内部完成事件注入回同一会话，以便模型自行编写面向用户的后续消息。
|
||||
- 提示词提示：当同一会话中已有音乐任务在进行时，后续用户/手动轮次会收到一个小型运行时提示，以防模型盲目再次调用 `music_generate`。
|
||||
- 无会话回退：在没有真实智能体会话的直接/本地上下文中，仍会以内联方式运行，并在同一轮中返回最终音频结果。
|
||||
|
||||
### 任务生命周期
|
||||
|
||||
每个 `music_generate` 请求会经历四个状态：
|
||||
每个 `music_generate` 请求都会经历四个状态：
|
||||
|
||||
1. **queued** —— 任务已创建，等待提供商接受。
|
||||
2. **running** —— 提供商正在处理（通常为 30 秒到 3 分钟，取决于提供商和时长）。
|
||||
3. **succeeded** —— 音轨已就绪；智能体被唤醒并将其发布到对话中。
|
||||
3. **succeeded** —— 曲目已准备就绪；智能体被唤醒并将其发布到对话中。
|
||||
4. **failed** —— 提供商错误或超时；智能体被唤醒并附带错误详情。
|
||||
|
||||
从 CLI 检查状态：
|
||||
通过 CLI 检查状态：
|
||||
|
||||
```bash
|
||||
openclaw tasks list
|
||||
@ -154,7 +154,7 @@ openclaw tasks show <taskId>
|
||||
openclaw tasks cancel <taskId>
|
||||
```
|
||||
|
||||
防止重复：如果当前会话已有音乐任务处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可显式检查状态，而不会触发新的生成。
|
||||
防止重复：如果当前会话的音乐任务已经处于 `queued` 或 `running` 状态，`music_generate` 会返回现有任务状态，而不是启动新任务。使用 `action: "status"` 可显式检查，而不会触发新的生成。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -166,7 +166,7 @@ openclaw tasks cancel <taskId>
|
||||
defaults: {
|
||||
musicGenerationModel: {
|
||||
primary: "google/lyria-3-clip-preview",
|
||||
fallbacks: ["minimax/music-2.5+"],
|
||||
fallbacks: ["minimax/music-2.6"],
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -177,21 +177,21 @@ openclaw tasks cancel <taskId>
|
||||
|
||||
生成音乐时，OpenClaw 会按以下顺序尝试提供商：
|
||||
|
||||
1. 工具调用中的 `model` 参数（如果智能体指定了）
|
||||
1. 工具调用中的 `model` 参数（如果智能体指定了该参数）
|
||||
2. 配置中的 `musicGenerationModel.primary`
|
||||
3. 按顺序使用 `musicGenerationModel.fallbacks`
|
||||
4. 仅使用由凭证支持的提供商默认值进行自动检测：
|
||||
- 先使用当前默认提供商
|
||||
- 再按 provider-id 顺序使用其余已注册的音乐生成提供商
|
||||
3. 按顺序尝试 `musicGenerationModel.fallbacks`
|
||||
4. 仅使用基于凭证的提供商默认值进行自动检测：
|
||||
- 先尝试当前默认提供商
|
||||
- 再按提供商 ID 顺序尝试其余已注册的音乐生成提供商
|
||||
|
||||
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
|
||||
如果某个提供商失败，会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详情。
|
||||
|
||||
如果你希望音乐生成仅使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
|
||||
|
||||
## 提供商说明
|
||||
|
||||
- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本和可选参考图像。
|
||||
- MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长引导和 mp3 输出。
|
||||
- Google 使用 Lyria 3 批量生成。当前内置流程支持提示词、可选歌词文本以及可选参考图像。
|
||||
- MiniMax 使用批量 `music_generation` 端点。当前内置流程支持提示词、可选歌词、器乐模式、时长控制以及 mp3 输出。
|
||||
- ComfyUI 支持由工作流驱动，并取决于已配置的图以及提示词/输出字段的节点映射。
|
||||
|
||||
## 提供商能力模式
|
||||
@ -219,17 +219,17 @@ capabilities: {
|
||||
}
|
||||
```
|
||||
|
||||
旧版扁平字段，例如 `maxInputImages`、`supportsLyrics` 和 `supportsFormat`，不足以声明编辑支持。提供商应显式声明 `generate` 和 `edit`，以便实时测试、契约测试以及共享 `music_generate` 工具能够以确定性的方式验证模式支持。
|
||||
旧版扁平字段（如 `maxInputImages`、`supportsLyrics` 和 `supportsFormat`）不足以声明编辑支持。提供商应显式声明 `generate` 和 `edit`，以便实时测试、契约测试以及共享 `music_generate` 工具能够以确定性的方式验证模式支持。
|
||||
|
||||
## 选择合适的路径
|
||||
## 选择正确路径
|
||||
|
||||
- 当你需要模型选择、提供商故障切换以及内置的异步任务/状态流时，使用由共享提供商支持的路径。
|
||||
- 当你需要自定义工作流图，或某个不属于共享内置音乐能力的提供商时，使用插件路径，例如 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
|
||||
@ -241,15 +241,15 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv
|
||||
pnpm test:live:media music
|
||||
```
|
||||
|
||||
此实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥而不是已存储的认证配置文件，并在提供商启用编辑模式时同时运行 `generate` 和已声明的 `edit` 覆盖。
|
||||
该实时测试文件会从 `~/.profile` 加载缺失的提供商环境变量，默认优先使用实时/环境 API 密钥，而不是已存储的凭证配置文件，并在提供商启用编辑模式时同时运行 `generate` 和已声明的 `edit` 覆盖。
|
||||
|
||||
目前这意味着：
|
||||
|
||||
- `google`：`generate` 加 `edit`
|
||||
- `minimax`：仅 `generate`
|
||||
- `comfy`：单独的 Comfy 实时覆盖，不属于共享提供商扫描
|
||||
- `comfy`：单独的 Comfy 实时覆盖，不在共享提供商扫描中
|
||||
|
||||
为内置 ComfyUI 音乐路径启用可选实时覆盖：
|
||||
针对内置 ComfyUI 音乐路径的可选实时覆盖：
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
|
||||
@ -264,5 +264,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) - 模型配置和故障切换
|
||||
- [Models](/zh-CN/concepts/models) - 模型配置和故障转移
|
||||
- [工具概览](/zh-CN/tools)
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要一份对新手友好的 TUI 使用指南
|
||||
- 你需要 TUI 的完整功能、命令和快捷键列表
|
||||
summary: 终端 UI（TUI）：连接到 Gateway 网关或在本地以嵌入模式运行
|
||||
title: TUI
|
||||
- 你想要一份适合初学者的终端 UI（TUI）使用指南
|
||||
- 你需要终端 UI（TUI）功能、命令和快捷键的完整列表
|
||||
summary: 终端 UI（TUI）：连接到 Gateway 网关，或以嵌入模式在本地运行
|
||||
title: 终端 UI（TUI）
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T23:06:35Z"
|
||||
generated_at: "2026-04-25T10:04:03Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 6168ab6cec8e0069f660ddcfca03275c407b613b6eb756aa6ef7e97f2312effe
|
||||
source_hash: 6eaa938fb3a50b7478341fe51cafb09e352f6d3cb402373222153ed93531a5f5
|
||||
source_path: web/tui.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -23,13 +23,13 @@ x-i18n:
|
||||
openclaw gateway
|
||||
```
|
||||
|
||||
2. 打开 TUI。
|
||||
2. 打开终端 UI（TUI）。
|
||||
|
||||
```bash
|
||||
openclaw tui
|
||||
```
|
||||
|
||||
3. 输入消息并按 Enter。
|
||||
3. 输入一条消息并按 Enter。
|
||||
|
||||
远程 Gateway 网关：
|
||||
|
||||
@ -37,58 +37,59 @@ openclaw tui
|
||||
openclaw tui --url ws://<host>:<port> --token <gateway-token>
|
||||
```
|
||||
|
||||
如果你的 Gateway 网关使用密码凭证，请使用 `--password`。
|
||||
如果你的 Gateway 网关使用密码认证，请使用 `--password`。
|
||||
|
||||
### 本地模式
|
||||
|
||||
不通过 Gateway 网关运行 TUI：
|
||||
不通过 Gateway 网关运行终端 UI（TUI）：
|
||||
|
||||
```bash
|
||||
openclaw chat
|
||||
# or
|
||||
# 或
|
||||
openclaw tui --local
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `openclaw chat` 和 `openclaw terminal` 是 `openclaw tui --local` 的别名。
|
||||
- `--local` 不能与 `--url`、`--token` 或 `--password` 组合使用。
|
||||
- 本地模式直接使用嵌入式智能体运行时。大多数本地工具都可用，但仅限 Gateway 网关的功能不可用。
|
||||
- `--local` 不能与 `--url`、`--token` 或 `--password` 一起使用。
|
||||
- 本地模式直接使用嵌入式智能体运行时。大多数本地工具都可以使用，但仅限 Gateway 网关的功能不可用。
|
||||
- `openclaw` 和 `openclaw crestodian` 也使用这个终端 UI（TUI）shell，其中 Crestodian 作为本地设置和修复聊天后端。
|
||||
|
||||
## 你会看到什么
|
||||
## 界面内容
|
||||
|
||||
- 页眉：连接 URL、当前智能体、当前会话。
|
||||
- 标题栏：连接 URL、当前智能体、当前会话。
|
||||
- 聊天日志：用户消息、助手回复、系统通知、工具卡片。
|
||||
- 状态行：连接/运行状态（connecting、running、streaming、idle、error）。
|
||||
- 状态行：连接 / 运行状态（正在连接、正在运行、流式传输中、空闲、错误）。
|
||||
- 页脚：连接状态 + 智能体 + 会话 + 模型 + think/fast/verbose/trace/reasoning + token 计数 + deliver。
|
||||
- 输入区：带自动补全的文本编辑器。
|
||||
|
||||
## 心智模型：智能体 + 会话
|
||||
|
||||
- 智能体是唯一 slug（例如 `main`、`research`）。Gateway 网关会暴露该列表。
|
||||
- 智能体是唯一的 slug（例如 `main`、`research`）。Gateway 网关会提供这个列表。
|
||||
- 会话属于当前智能体。
|
||||
- 会话键按 `agent:<agentId>:<sessionKey>` 存储。
|
||||
- 如果你输入 `/session main`，TUI 会将其展开为 `agent:<currentAgent>:main`。
|
||||
- 如果你输入 `/session agent:other:main`，你会显式切换到该智能体会话。
|
||||
- 会话键存储为 `agent:<agentId>:<sessionKey>`。
|
||||
- 如果你输入 `/session main`，终端 UI（TUI）会将其展开为 `agent:<currentAgent>:main`。
|
||||
- 如果你输入 `/session agent:other:main`，你会显式切换到那个智能体会话。
|
||||
- 会话作用域：
|
||||
- `per-sender`（默认）：每个智能体有多个会话。
|
||||
- `global`：TUI 始终使用 `global` 会话（选择器可能为空）。
|
||||
- `global`：终端 UI（TUI）始终使用 `global` 会话（选择器可能为空）。
|
||||
- 当前智能体 + 会话始终显示在页脚中。
|
||||
|
||||
## 发送 + 投递
|
||||
|
||||
- 消息会发送到 Gateway 网关；默认不会投递给提供商。
|
||||
- 开启轮次投递：
|
||||
- 开启投递：
|
||||
- `/deliver on`
|
||||
- 或在“设置”面板中开启
|
||||
- 或以 `openclaw tui --deliver` 启动
|
||||
- 或通过 `openclaw tui --deliver` 启动
|
||||
|
||||
## 选择器 + 覆盖层
|
||||
|
||||
- 模型选择器：列出可用模型并设置会话覆盖。
|
||||
- 智能体选择器：选择不同的智能体。
|
||||
- 模型选择器：列出可用模型并设置会话覆盖项。
|
||||
- 智能体选择器：选择另一个智能体。
|
||||
- 会话选择器：仅显示当前智能体的会话。
|
||||
- 设置：切换 deliver、工具输出展开和 thinking 可见性。
|
||||
- 设置：切换投递、工具输出展开，以及思考内容可见性。
|
||||
|
||||
## 键盘快捷键
|
||||
|
||||
@ -99,12 +100,12 @@ openclaw tui --local
|
||||
- Ctrl+L：模型选择器
|
||||
- Ctrl+G：智能体选择器
|
||||
- Ctrl+P：会话选择器
|
||||
- Ctrl+O：切换工具输出展开
|
||||
- Ctrl+T：切换 thinking 可见性（会重新加载历史）
|
||||
- Ctrl+O：切换工具输出展开状态
|
||||
- Ctrl+T：切换思考内容可见性（会重新加载历史记录）
|
||||
|
||||
## 斜杠命令
|
||||
|
||||
核心：
|
||||
核心命令：
|
||||
|
||||
- `/help`
|
||||
- `/status`
|
||||
@ -133,24 +134,23 @@ openclaw tui --local
|
||||
|
||||
仅本地模式：
|
||||
|
||||
- `/auth [provider]` 在 TUI 内打开提供商凭证/登录流程。
|
||||
- `/auth [provider]` 在终端 UI（TUI）内打开提供商认证 / 登录流程。
|
||||
|
||||
其他 Gateway 网关斜杠命令（例如 `/context`）会被转发到 Gateway 网关，并显示为系统输出。参见 [斜杠命令](/zh-CN/tools/slash-commands)。
|
||||
其他 Gateway 网关斜杠命令（例如 `/context`）会转发到 Gateway 网关，并显示为系统输出。参见 [Slash commands](/zh-CN/tools/slash-commands)。
|
||||
|
||||
## 本地 shell 命令
|
||||
|
||||
- 在一行前加上 `!`，即可在 TUI 主机上运行本地 shell 命令。
|
||||
- TUI 会在每个会话中提示一次，询问是否允许本地执行；如果拒绝，该会话中的 `!` 会保持禁用。
|
||||
- 命令会在 TUI 工作目录中的一个全新、非交互式 shell 中运行（不会持久保留 `cd`/环境变量）。
|
||||
- 本地 shell 命令会在其环境中收到 `OPENCLAW_SHELL=tui-local`。
|
||||
- 单独一个 `!` 会作为普通消息发送；前导空格不会触发本地 exec。
|
||||
- 在一行前加上 `!` 可在终端 UI（TUI）主机上运行本地 shell 命令。
|
||||
- 终端 UI（TUI）会在每个会话中提示一次，以允许本地执行；如果拒绝，该会话中的 `!` 将保持禁用。
|
||||
- 命令会在终端 UI（TUI）工作目录中的一个全新、非交互式 shell 中运行（`cd` / 环境变量不会持久保留）。
|
||||
- 本地 shell 命令在其环境中会收到 `OPENCLAW_SHELL=tui-local`。
|
||||
- 单独一个 `!` 会作为普通消息发送；前导空格不会触发本地执行。
|
||||
|
||||
## 从本地 TUI 修复配置
|
||||
## 从本地终端 UI（TUI）修复配置
|
||||
|
||||
当当前配置已经能够通过验证，并且你希望嵌入式智能体在同一台机器上检查它、将其与文档对比，并在不依赖正在运行的 Gateway 网关的情况下帮助修复漂移时，请使用本地模式。
|
||||
当当前配置已经通过验证，并且你希望嵌入式智能体在同一台机器上检查配置、将其与文档对比，并在不依赖运行中的 Gateway 网关的情况下帮助修复漂移时，请使用本地模式。
|
||||
|
||||
如果 `openclaw config validate` 已经失败，请先从 `openclaw configure`
|
||||
或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护。
|
||||
如果 `openclaw config validate` 已经失败，请先从 `openclaw configure` 或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护。
|
||||
|
||||
典型流程：
|
||||
|
||||
@ -176,51 +176,51 @@ Compare my gateway auth config with the docs and suggest the smallest fix.
|
||||
```
|
||||
|
||||
4. 使用 `openclaw config set` 或 `openclaw configure` 应用小范围更改，然后重新运行 `!openclaw config validate`。
|
||||
5. 如果 Doctor 建议自动迁移或修复，请先审阅，再运行 `!openclaw doctor --fix`。
|
||||
5. 如果 Doctor 建议执行自动迁移或修复，请先审查，再运行 `!openclaw doctor --fix`。
|
||||
|
||||
提示：
|
||||
|
||||
- 优先使用 `openclaw config set` 或 `openclaw configure`，而不是手动编辑 `openclaw.json`。
|
||||
- `openclaw docs "<query>"` 会从同一台机器搜索实时文档索引。
|
||||
- 当你需要结构化的 schema 和 SecretRef/可解析性错误时，`openclaw config validate --json` 很有用。
|
||||
- `openclaw docs "<query>"` 会在同一台机器上搜索实时文档索引。
|
||||
- 当你需要结构化的 schema 和 SecretRef / 可解析性错误时，`openclaw config validate --json` 很有用。
|
||||
|
||||
## 工具输出
|
||||
|
||||
- 工具调用会显示为带参数 + 结果的卡片。
|
||||
- Ctrl+O 可在折叠/展开视图之间切换。
|
||||
- 工具运行时，部分更新会流式写入同一张卡片。
|
||||
- Ctrl+O 可在折叠 / 展开视图之间切换。
|
||||
- 工具运行期间，部分更新会流式写入同一张卡片。
|
||||
|
||||
## 终端颜色
|
||||
|
||||
- TUI 会让助手正文文本保持终端默认前景色，这样深色和浅色终端都能保持可读。
|
||||
- 如果你的终端使用浅色背景且自动检测错误，请在启动 `openclaw tui` 前设置 `OPENCLAW_THEME=light`。
|
||||
- 若要改为强制使用原始深色调色板，请设置 `OPENCLAW_THEME=dark`。
|
||||
- 终端 UI（TUI）会将助手正文文本保持为你终端的默认前景色，因此深色和浅色终端都能保持可读。
|
||||
- 如果你的终端使用浅色背景而自动检测不正确，请在启动 `openclaw tui` 前设置 `OPENCLAW_THEME=light`。
|
||||
- 如果要改为强制使用原始深色配色，请设置 `OPENCLAW_THEME=dark`。
|
||||
|
||||
## 历史记录 + 流式传输
|
||||
|
||||
- 连接后，TUI 会加载最近的历史记录（默认 200 条消息）。
|
||||
- 流式回复会就地更新，直到最终完成。
|
||||
- TUI 还会监听智能体工具事件，以显示更丰富的工具卡片。
|
||||
- 连接时，终端 UI（TUI）会加载最新历史记录（默认 200 条消息）。
|
||||
- 流式响应会就地更新，直到最终完成。
|
||||
- 终端 UI（TUI）还会监听智能体工具事件，以显示更丰富的工具卡片。
|
||||
|
||||
## 连接细节
|
||||
## 连接详情
|
||||
|
||||
- TUI 会以 `mode: "tui"` 注册到 Gateway 网关。
|
||||
- 重连时会显示系统消息；事件缺口会在日志中体现。
|
||||
- 终端 UI（TUI）会以 `mode: "tui"` 的形式向 Gateway 网关注册。
|
||||
- 重连时会显示系统消息；事件缺口会在日志中提示。
|
||||
|
||||
## 选项
|
||||
|
||||
- `--local`：针对本地嵌入式智能体运行时运行
|
||||
- `--url <url>`：Gateway 网关 WebSocket URL（默认取自配置或 `ws://127.0.0.1:<port>`）
|
||||
- `--token <token>`：Gateway 网关 token（如需要）
|
||||
- `--password <password>`：Gateway 网关密码（如需要）
|
||||
- `--session <key>`：会话键（默认：`main`；如果作用域为 global，则为 `global`）
|
||||
- `--url <url>`：Gateway 网关 WebSocket URL（默认为配置中的值或 `ws://127.0.0.1:<port>`）
|
||||
- `--token <token>`：Gateway 网关 token（如果需要）
|
||||
- `--password <password>`：Gateway 网关密码（如果需要）
|
||||
- `--session <key>`：会话键（默认：`main`，若作用域为 global，则为 `global`）
|
||||
- `--deliver`：将助手回复投递给提供商（默认关闭）
|
||||
- `--thinking <level>`：为发送覆盖 thinking 级别
|
||||
- `--thinking <level>`：覆盖发送时的思考级别
|
||||
- `--message <text>`：连接后发送一条初始消息
|
||||
- `--timeout-ms <ms>`：智能体超时时间（毫秒，默认取 `agents.defaults.timeoutSeconds`）
|
||||
- `--history-limit <n>`：要加载的历史记录条数（默认 `200`）
|
||||
- `--timeout-ms <ms>`：智能体超时时间（毫秒）（默认为 `agents.defaults.timeoutSeconds`）
|
||||
- `--history-limit <n>`：要加载的历史记录条目数（默认 `200`）
|
||||
|
||||
注意：当你设置了 `--url` 时，TUI 不会回退到配置或环境变量凭证。
|
||||
注意：设置 `--url` 后，终端 UI（TUI）不会回退使用配置或环境变量中的凭证。
|
||||
请显式传入 `--token` 或 `--password`。缺少显式凭证会报错。
|
||||
在本地模式下，不要传入 `--url`、`--token` 或 `--password`。
|
||||
|
||||
@ -228,20 +228,20 @@ Compare my gateway auth config with the docs and suggest the smallest fix.
|
||||
|
||||
发送消息后没有输出：
|
||||
|
||||
- 在 TUI 中运行 `/status`，确认 Gateway 网关已连接且处于 idle/busy。
|
||||
- 在终端 UI（TUI）中运行 `/status`，确认 Gateway 网关已连接且处于空闲 / 忙碌状态。
|
||||
- 检查 Gateway 网关日志：`openclaw logs --follow`。
|
||||
- 确认智能体能够运行：`openclaw status` 和 `openclaw models status`。
|
||||
- 确认智能体可以运行：`openclaw status` 和 `openclaw models status`。
|
||||
- 如果你希望消息出现在聊天渠道中，请启用投递（`/deliver on` 或 `--deliver`）。
|
||||
|
||||
## 连接故障排除
|
||||
|
||||
- `disconnected`：请确保 Gateway 网关正在运行，并且你的 `--url/--token/--password` 正确。
|
||||
- `disconnected`：确认 Gateway 网关正在运行，并且你的 `--url/--token/--password` 正确。
|
||||
- 选择器中没有智能体：检查 `openclaw agents list` 和你的路由配置。
|
||||
- 会话选择器为空：你可能处于 global 作用域，或者还没有任何会话。
|
||||
|
||||
## 相关
|
||||
## 相关内容
|
||||
|
||||
- [Control UI](/zh-CN/web/control-ui) — 基于 Web 的控制界面
|
||||
- [配置](/zh-CN/cli/config) — 检查、验证和编辑 `openclaw.json`
|
||||
- [Doctor](/zh-CN/cli/doctor) — 引导式修复和迁移检查
|
||||
- [CLI 参考](/zh-CN/cli) — 完整 CLI 命令参考
|
||||
- [Control UI](/zh-CN/web/control-ui) —— 基于 Web 的控制界面
|
||||
- [Config](/zh-CN/cli/config) —— 检查、验证并编辑 `openclaw.json`
|
||||
- [Doctor](/zh-CN/cli/doctor) —— 引导式修复与迁移检查
|
||||
- [CLI Reference](/zh-CN/cli) —— 完整 CLI 命令参考
|
||||
|
||||
Loading…
Reference in New Issue
Block a user