chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
1c4174a499
commit
9d59081832
@ -1,27 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- 调度后台任务或唤醒操作
|
||||
- 将外部触发器（webhook、Gmail）接入 OpenClaw
|
||||
- 调度后台作业或唤醒任务
|
||||
- 将外部触发器（webhooks、Gmail）接入 OpenClaw
|
||||
- 为计划任务决定使用 heartbeat 还是 cron
|
||||
summary: 用于 Gateway 网关调度器的计划任务、webhook 和 Gmail PubSub 触发器
|
||||
summary: 用于 Gateway 网关调度器的计划任务、webhooks 和 Gmail PubSub 触发器
|
||||
title: 计划任务
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T07:03:26Z"
|
||||
generated_at: "2026-04-23T19:23:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c9565b73efc151c991ee6a1029c887c35d8673736913ddc5cdcfae09a4652f86
|
||||
source_hash: 023e8a73e028d0b5a466e9d933b8033604ba1066641cf29c8415ba9e5ac12447
|
||||
source_path: automation/cron-jobs.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 计划任务（Cron）
|
||||
|
||||
Cron 是 Gateway 网关内置的调度器。它会持久化任务，在正确的时间唤醒智能体，并可将输出回传到聊天渠道或 webhook 端点。
|
||||
Cron 是 Gateway 网关内置的调度器。它会持久化作业，在正确的时间唤醒智能体，并且可以将输出回传到聊天渠道或 webhook 端点。
|
||||
|
||||
## 快速开始
|
||||
|
||||
```bash
|
||||
# 添加一个一次性提醒
|
||||
# 添加一次性提醒
|
||||
openclaw cron add \
|
||||
--name "Reminder" \
|
||||
--at "2026-02-01T16:00:00Z" \
|
||||
@ -30,7 +30,7 @@ openclaw cron add \
|
||||
--wake now \
|
||||
--delete-after-run
|
||||
|
||||
# 查看你的任务
|
||||
# 检查你的作业
|
||||
openclaw cron list
|
||||
openclaw cron show <job-id>
|
||||
|
||||
@ -40,98 +40,99 @@ openclaw cron runs --id <job-id>
|
||||
|
||||
## Cron 的工作方式
|
||||
|
||||
- Cron 在 **Gateway 网关** 进程**内部**运行（不在模型内部）。
|
||||
- 任务定义持久化保存在 `~/.openclaw/cron/jobs.json`，因此重启不会丢失调度计划。
|
||||
- 运行时执行状态保存在旁边的 `~/.openclaw/cron/jobs-state.json` 中。如果你用 git 跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 加入 `.gitignore`。
|
||||
- 拆分之后，旧版 OpenClaw 可以读取 `jobs.json`，但可能会将任务视为全新任务，因为运行时字段现在位于 `jobs-state.json` 中。
|
||||
- Cron **运行在 Gateway 网关进程内部**（而不是运行在模型内部）。
|
||||
- 作业定义会持久化到 `~/.openclaw/cron/jobs.json`，因此重启不会丢失调度计划。
|
||||
- 运行时执行状态会持久化到旁边的 `~/.openclaw/cron/jobs-state.json`。如果你用 git 跟踪 cron 定义，请跟踪 `jobs.json`，并将 `jobs-state.json` 加入 `.gitignore`。
|
||||
- 在拆分之后，旧版本的 OpenClaw 仍然可以读取 `jobs.json`，但可能会将作业视为全新作业，因为运行时字段现在存放在 `jobs-state.json` 中。
|
||||
- 所有 cron 执行都会创建[后台任务](/zh-CN/automation/tasks)记录。
|
||||
- 一次性任务（`--at`）默认在成功后自动删除。
|
||||
- 独立 cron 运行会在运行完成时尽力关闭其 `cron:<jobId>` 会话所跟踪的浏览器标签页/进程，这样分离的浏览器自动化就不会留下孤儿进程。
|
||||
- 独立 cron 运行还会防止过时的确认回复。如果第一个结果只是中间状态更新（如 `on it`、`pulling everything together` 以及类似提示），并且没有任何后代子智能体运行仍负责最终答案，OpenClaw 会在投递前再次提示一次，以获取实际结果。
|
||||
- 一次性作业（`--at`）默认会在成功后自动删除。
|
||||
- 独立的 cron 运行会在执行完成后尽力关闭其 `cron:<jobId>` 会话所跟踪的浏览器标签页/进程，因此分离式浏览器自动化不会留下孤儿进程。
|
||||
- 独立的 cron 运行还会防止过期的确认回复。如果第一个结果只是中间状态更新（例如 `on it`、`pulling everything together` 以及类似提示），并且没有任何后代子智能体运行仍负责给出最终答案，OpenClaw 会在投递前再提示一次以获取实际结果。
|
||||
|
||||
<a id="maintenance"></a>
|
||||
|
||||
Cron 的任务协调由运行时负责：只要 cron 运行时仍将该任务跟踪为正在运行，对应的活动 cron 任务就会保持存活，即使仍存在旧的子会话行记录也是如此。一旦运行时不再拥有该任务，且 5 分钟宽限期到期，维护流程就可以将该任务标记为 `lost`。
|
||||
Cron 的任务协调由运行时负责：只要 cron 运行时仍将该作业标记为正在运行，对应的活动 cron 任务就会保持存活，即使旧的子会话记录仍然存在也是如此。
|
||||
一旦运行时不再拥有该作业，并且 5 分钟宽限窗口到期，维护流程就可以将该任务标记为 `lost`。
|
||||
|
||||
## 调度类型
|
||||
|
||||
| 类型 | CLI 标志 | 描述 |
|
||||
| ------- | -------- | --------------------------------------------------- |
|
||||
| `at` | `--at` | 一次性时间戳（ISO 8601 或类似 `20m` 的相对时间） |
|
||||
| `every` | `--every`| 固定间隔 |
|
||||
| `cron` | `--cron` | 5 字段或 6 字段的 cron 表达式，可选搭配 `--tz` 使用 |
|
||||
| 类型 | CLI 标志 | 说明 |
|
||||
| ------- | -------- | -------------------------------------------------- |
|
||||
| `at` | `--at` | 一次性时间戳（ISO 8601 或类似 `20m` 的相对时间） |
|
||||
| `every` | `--every`| 固定间隔 |
|
||||
| `cron` | `--cron` | 5 字段或 6 字段的 cron 表达式，可选配 `--tz` |
|
||||
|
||||
不带时区的时间戳会被视为 UTC。添加 `--tz America/New_York` 可按本地墙上时钟时间进行调度。
|
||||
|
||||
循环的整点表达式会自动错开最多 5 分钟，以减少负载尖峰。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定明确的错开窗口。
|
||||
每小时整点的循环表达式会自动错峰最多 5 分钟，以减少负载尖峰。使用 `--exact` 可强制精确时间，或使用 `--stagger 30s` 指定显式错峰窗口。
|
||||
|
||||
### 月中的某天与星期几使用 OR 逻辑
|
||||
### day-of-month 和 day-of-week 使用 OR 逻辑
|
||||
|
||||
Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当“月中的某天”和“星期几”字段都不是通配符时，croner 会在**任一**字段匹配时触发，而不是两个都匹配时才触发。这是标准的 Vixie cron 行为。
|
||||
Cron 表达式由 [croner](https://github.com/Hexagon/croner) 解析。当 day-of-month 和 day-of-week 字段都不是通配符时，croner 会在**任一**字段匹配时触发，而不是要求两者都匹配。这是标准的 Vixie cron 行为。
|
||||
|
||||
```
|
||||
# 预期："每月 15 日上午 9 点，且仅当这一天是周一"
|
||||
# 实际："每个 15 日上午 9 点，以及每个周一上午 9 点"
|
||||
# 预期："15 号上午 9 点，但前提是这一天是周一"
|
||||
# 实际："每个 15 号上午 9 点，外加每个周一上午 9 点"
|
||||
0 9 15 * 1
|
||||
```
|
||||
|
||||
这样每月会触发约 5–6 次，而不是 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件都满足，请使用 Croner 的 `+` 星期几修饰符（`0 9 15 * +1`），或仅按一个字段调度，再在任务的提示词或命令中对另一个条件进行判断。
|
||||
这会导致它每月触发约 5–6 次，而不是每月 0–1 次。OpenClaw 在这里使用 Croner 默认的 OR 行为。若要同时要求两个条件都成立，请使用 Croner 的 `+` day-of-week 修饰符（`0 9 15 * +1`），或者只按一个字段调度，并在作业的提示词或命令中对另一个条件进行判断。
|
||||
|
||||
## 执行方式
|
||||
|
||||
| 方式 | `--session` 值 | 运行位置 | 最适合 |
|
||||
| --------------- | ------------------- | ------------------------ | ----------------------------- |
|
||||
| 主会话 | `main` | 下一次 heartbeat 轮次 | 提醒、系统事件 |
|
||||
| 独立 | `isolated` | 专用 `cron:<jobId>` | 报告、后台杂务 |
|
||||
| 当前会话 | `current` | 绑定到创建时的会话 | 依赖上下文的循环工作 |
|
||||
| 自定义会话 | `session:custom-id` | 持久化命名会话 | 基于历史逐步推进的工作流 |
|
||||
| 方式 | `--session` 值 | 运行位置 | 最适合 |
|
||||
| -------------- | ------------------ | ------------------------ | -------------------------- |
|
||||
| 主会话 | `main` | 下一次 heartbeat 轮次 | 提醒、系统事件 |
|
||||
| 独立 | `isolated` | 专用 `cron:<jobId>` | 报告、后台杂务 |
|
||||
| 当前会话 | `current` | 在创建时绑定 | 感知上下文的循环工作 |
|
||||
| 自定义会话 | `session:custom-id`| 持久化命名会话 | 基于历史逐步累积的工作流 |
|
||||
|
||||
**主会话**任务会入队一个系统事件，并可选择唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。**独立**任务会在一个全新会话中运行专用的智能体轮次。**自定义会话**（`session:xxx`）会在多次运行之间保留上下文，从而支持诸如基于前一天摘要继续推进的每日站会等工作流。
|
||||
**主会话**作业会排入一个系统事件，并可选择唤醒 heartbeat（`--wake now` 或 `--wake next-heartbeat`）。**独立**作业会使用一个全新的专用会话运行一次独立的智能体轮次。**自定义会话**（`session:xxx`）会在多次运行之间保留上下文，从而支持例如基于先前摘要持续累积的每日日报工作流。
|
||||
|
||||
对于独立任务，运行时拆除现在包含了该 cron 会话的尽力式浏览器清理。清理失败会被忽略，以确保实际的 cron 结果仍然优先。
|
||||
对于独立作业，运行时拆除现在包含针对该 cron 会话的尽力浏览器清理。清理失败会被忽略，因此实际的 cron 结果仍然优先。
|
||||
|
||||
独立 cron 运行还会通过共享的运行时清理路径，释放为该任务创建的所有内置 MCP 运行时实例。这与主会话和自定义会话的 MCP 客户端拆除方式一致，因此独立 cron 任务不会在多次运行之间泄漏 stdio 子进程或长期存活的 MCP 连接。
|
||||
独立的 cron 运行还会通过共享的运行时清理路径，释放为该作业创建的所有内置 MCP 运行时实例。这与主会话和自定义会话的 MCP 客户端拆除方式保持一致，因此独立的 cron 作业不会在多次运行之间泄漏 stdio 子进程或长期存在的 MCP 连接。
|
||||
|
||||
当独立 cron 运行编排子智能体时，投递逻辑也会优先使用最终的后代输出，而不是过时的父级中间文本。如果后代仍在运行，OpenClaw 会抑制该父级的部分更新，而不是直接播报它。
|
||||
当独立的 cron 运行编排子智能体时，投递也会优先使用最终后代输出，而不是过期的父级中间文本。如果后代仍在运行，OpenClaw 会抑制该不完整的父级更新，而不是将其宣告出去。
|
||||
|
||||
### 独立任务的负载选项
|
||||
### 独立作业的负载选项
|
||||
|
||||
- `--message`：提示文本（独立任务必填）
|
||||
- `--message`：提示文本（独立模式必需）
|
||||
- `--model` / `--thinking`：模型和思考级别覆盖
|
||||
- `--light-context`：跳过工作区引导文件注入
|
||||
- `--tools exec,read`：限制任务可使用的工具
|
||||
- `--tools exec,read`：限制作业可使用的工具
|
||||
|
||||
`--model` 会为该任务使用所选的允许模型。如果请求的模型不被允许，cron 会记录一条警告，并回退到该任务的智能体/默认模型选择。已配置的回退链仍然适用，但如果只是普通的模型覆盖，且没有显式的逐任务回退列表，就不再把智能体主模型作为隐藏的额外重试目标附加进去。
|
||||
`--model` 会为该作业使用所选的允许模型。如果请求的模型不被允许，cron 会记录一条警告，并回退到该作业的智能体/默认模型选择。已配置的回退链仍然会生效，但仅指定模型覆盖、且没有显式的按作业回退列表时，不会再把智能体主模型作为隐藏的额外重试目标附加进去。
|
||||
|
||||
独立任务的模型选择优先级如下：
|
||||
独立作业的模型选择优先级如下：
|
||||
|
||||
1. Gmail hook 模型覆盖（当运行来自 Gmail 且该覆盖被允许时）
|
||||
2. 每个任务负载中的 `model`
|
||||
2. 按作业负载中的 `model`
|
||||
3. 已存储的 cron 会话模型覆盖
|
||||
4. 智能体/默认模型选择
|
||||
|
||||
快速模式也会遵循解析后的 live 选择。如果所选模型配置包含 `params.fastMode`，独立 cron 默认就会使用该设置。已存储的会话 `fastMode` 覆盖在两个方向上都仍然优先生效。
|
||||
快速模式也会遵循解析后的实时选择。如果所选模型配置包含 `params.fastMode`，独立 cron 默认会使用它。已存储的会话 `fastMode` 覆盖仍然会在任一方向上优先于配置。
|
||||
|
||||
如果独立运行遇到 live 模型切换交接，cron 会使用切换后的 provider/模型重试，并在重试前持久化该 live 选择。如果切换同时携带新的凭证配置文件，cron 也会持久化该凭证配置文件覆盖。重试次数是有限的：在初始尝试加上 2 次切换重试之后，cron 会中止，而不是无限循环。
|
||||
如果独立运行遇到实时模型切换交接，cron 会使用切换后的提供商/模型重试，并在重试前持久化该实时选择。当切换同时携带新的 auth profile 时，cron 也会持久化该 auth profile 覆盖。重试是有边界的：在初始尝试再加 2 次切换重试之后，cron 会中止，而不是无限循环。
|
||||
|
||||
## 投递与输出
|
||||
## 投递和输出
|
||||
|
||||
| 模式 | 行为说明 |
|
||||
| ---------- | ------------------------------------------------------------- |
|
||||
| `announce` | 如果智能体未发送，则回退投递最终文本到目标 |
|
||||
| `webhook` | 将完成事件负载以 POST 方式发送到某个 URL |
|
||||
| `none` | 运行器不执行回退投递 |
|
||||
| 模式 | 行为说明 |
|
||||
| ---------- | ------------------------------------------------------------ |
|
||||
| `announce` | 如果智能体未主动发送，则回退并将最终文本投递到目标 |
|
||||
| `webhook` | 将完成事件负载以 POST 方式发送到某个 URL |
|
||||
| `none` | 运行器不执行任何回退投递 |
|
||||
|
||||
使用 `--announce --channel telegram --to "-1001234567890"` 可投递到渠道。对于 Telegram 论坛话题，请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:<id>`、`user:<id>`）。
|
||||
使用 `--announce --channel telegram --to "-1001234567890"` 可投递到渠道。对于 Telegram forum topics，请使用 `-1001234567890:topic:123`。Slack/Discord/Mattermost 目标应使用显式前缀（`channel:<id>`、`user:<id>`）。
|
||||
|
||||
对于独立任务，聊天投递是共享的。如果聊天路由可用，智能体即使在任务使用 `--no-deliver` 时也可以使用 `message` 工具。如果智能体发送到了已配置/当前目标，OpenClaw 就会跳过回退 announce。否则，`announce`、`webhook` 和 `none` 只控制运行器在智能体轮次结束后如何处理最终回复。
|
||||
对于独立作业，聊天投递是共享的。如果存在可用的聊天路由，即使作业使用了 `--no-deliver`，智能体也可以使用 `message` 工具。如果智能体发送到了已配置/当前目标，OpenClaw 会跳过回退 announce。否则，`announce`、`webhook` 和 `none` 只控制运行器在智能体轮次结束后如何处理最终回复。
|
||||
|
||||
失败通知遵循单独的目标路径：
|
||||
|
||||
- `cron.failureDestination` 设置失败通知的全局默认值。
|
||||
- `job.delivery.failureDestination` 可按任务覆盖该设置。
|
||||
- 如果两者都未设置，而该任务本身已通过 `announce` 投递，则失败通知现在会回退到该主 announce 目标。
|
||||
- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 的任务上受支持，除非主投递模式是 `webhook`。
|
||||
- `cron.failureDestination` 为失败通知设置全局默认值。
|
||||
- `job.delivery.failureDestination` 按作业覆盖该设置。
|
||||
- 如果两者都未设置，并且作业本身已通过 `announce` 投递，失败通知现在会回退到该主 announce 目标。
|
||||
- `delivery.failureDestination` 仅在 `sessionTarget="isolated"` 的作业上受支持，除非主投递模式是 `webhook`。
|
||||
|
||||
## CLI 示例
|
||||
|
||||
@ -146,7 +147,7 @@ openclaw cron add \
|
||||
--wake now
|
||||
```
|
||||
|
||||
带投递的循环独立任务：
|
||||
带投递的循环独立作业：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@ -160,7 +161,7 @@ openclaw cron add \
|
||||
--to "channel:C1234567890"
|
||||
```
|
||||
|
||||
带模型和思考覆盖的独立任务：
|
||||
带模型和思考覆盖的独立作业：
|
||||
|
||||
```bash
|
||||
openclaw cron add \
|
||||
@ -176,7 +177,7 @@ openclaw cron add \
|
||||
|
||||
## Webhooks
|
||||
|
||||
Gateway 网关可以暴露 HTTP webhook 端点，用于外部触发器。在配置中启用：
|
||||
Gateway 网关可以暴露 HTTP webhook 端点以接收外部触发器。在配置中启用：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -199,7 +200,7 @@ Gateway 网关可以暴露 HTTP webhook 端点，用于外部触发器。在配
|
||||
|
||||
### POST /hooks/wake
|
||||
|
||||
为主会话入队一个系统事件：
|
||||
为主会话排入一个系统事件：
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:18789/hooks/wake \
|
||||
@ -208,35 +209,35 @@ curl -X POST http://127.0.0.1:18789/hooks/wake \
|
||||
-d '{"text":"New email received","mode":"now"}'
|
||||
```
|
||||
|
||||
- `text`（必填）：事件描述
|
||||
- `text`（必需）：事件描述
|
||||
- `mode`（可选）：`now`（默认）或 `next-heartbeat`
|
||||
|
||||
### POST /hooks/agent
|
||||
|
||||
运行一个独立的智能体轮次：
|
||||
运行一次独立的智能体轮次：
|
||||
|
||||
```bash
|
||||
curl -X POST http://127.0.0.1:18789/hooks/agent \
|
||||
-H 'Authorization: Bearer SECRET' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.4-mini"}'
|
||||
-d '{"message":"Summarize inbox","name":"Email","model":"openai/gpt-5.5"}'
|
||||
```
|
||||
|
||||
字段：`message`（必填）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`thinking`、`timeoutSeconds`。
|
||||
字段：`message`（必需）、`name`、`agentId`、`wakeMode`、`deliver`、`channel`、`to`、`model`、`thinking`、`timeoutSeconds`。
|
||||
|
||||
### 映射 hook（POST /hooks/\<name\>）
|
||||
### 映射 hooks（POST /hooks/\<name\>）
|
||||
|
||||
自定义 hook 名称会通过配置中的 `hooks.mappings` 解析。映射可以通过模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。
|
||||
自定义 hook 名称会通过配置中的 `hooks.mappings` 进行解析。映射可以使用模板或代码转换，将任意负载转换为 `wake` 或 `agent` 动作。
|
||||
|
||||
### 安全性
|
||||
|
||||
- 将 hook 端点放在 loopback、tailnet 或受信任的反向代理之后。
|
||||
- 将 hook 端点保留在 loopback、tailnet 或受信任的反向代理之后。
|
||||
- 使用专用的 hook token；不要复用 gateway 身份验证 token。
|
||||
- 将 `hooks.path` 放在专用子路径下；`/` 会被拒绝。
|
||||
- 将 `hooks.path` 保持在专用子路径下；`/` 会被拒绝。
|
||||
- 设置 `hooks.allowedAgentIds` 以限制显式 `agentId` 路由。
|
||||
- 除非你确实需要由调用方选择会话，否则请保持 `hooks.allowRequestSessionKey=false`。
|
||||
- 如果你启用了 `hooks.allowRequestSessionKey`，也要同时设置 `hooks.allowedSessionKeyPrefixes`，以约束允许的会话键形态。
|
||||
- 默认情况下，hook 负载会被安全边界包装。
|
||||
- 如果你启用了 `hooks.allowRequestSessionKey`，还应设置 `hooks.allowedSessionKeyPrefixes` 以约束允许的会话键形状。
|
||||
- 默认情况下，hook 负载会被安全边界包裹。
|
||||
|
||||
## Gmail PubSub 集成
|
||||
|
||||
@ -250,11 +251,11 @@ curl -X POST http://127.0.0.1:18789/hooks/agent \
|
||||
openclaw webhooks gmail setup --account openclaw@gmail.com
|
||||
```
|
||||
|
||||
这会写入 `hooks.gmail` 配置，启用 Gmail 预设，并使用 Tailscale Funnel 作为推送端点。
|
||||
这会写入 `hooks.gmail` 配置，启用 Gmail 预设，并为 push 端点使用 Tailscale Funnel。
|
||||
|
||||
### Gateway 网关自动启动
|
||||
|
||||
当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关会在启动时启动 `gog gmail watch serve`，并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出此行为。
|
||||
当 `hooks.enabled=true` 且设置了 `hooks.gmail.account` 时，Gateway 网关会在启动时运行 `gog gmail watch serve` 并自动续订 watch。设置 `OPENCLAW_SKIP_GMAIL_WATCHER=1` 可选择退出。
|
||||
|
||||
### 手动一次性设置
|
||||
|
||||
@ -266,7 +267,7 @@ gcloud config set project <project-id>
|
||||
gcloud services enable gmail.googleapis.com pubsub.googleapis.com
|
||||
```
|
||||
|
||||
2. 创建主题并授予 Gmail 推送权限：
|
||||
2. 创建 topic 并授予 Gmail push 访问权限：
|
||||
|
||||
```bash
|
||||
gcloud pubsub topics create gog-gmail-watch
|
||||
@ -297,19 +298,19 @@ gog gmail watch start \
|
||||
}
|
||||
```
|
||||
|
||||
## 管理任务
|
||||
## 管理作业
|
||||
|
||||
```bash
|
||||
# 列出所有任务
|
||||
# 列出所有作业
|
||||
openclaw cron list
|
||||
|
||||
# 显示单个任务，包括解析后的投递路由
|
||||
# 显示单个作业，包括解析后的投递路由
|
||||
openclaw cron show <jobId>
|
||||
|
||||
# 编辑任务
|
||||
# 编辑作业
|
||||
openclaw cron edit <jobId> --message "Updated prompt" --model "opus"
|
||||
|
||||
# 立即强制运行任务
|
||||
# 立即强制运行作业
|
||||
openclaw cron run <jobId>
|
||||
|
||||
# 仅在到期时运行
|
||||
@ -318,7 +319,7 @@ openclaw cron run <jobId> --due
|
||||
# 查看运行历史
|
||||
openclaw cron runs --id <jobId> --limit 50
|
||||
|
||||
# 删除任务
|
||||
# 删除作业
|
||||
openclaw cron remove <jobId>
|
||||
|
||||
# 智能体选择（多智能体设置）
|
||||
@ -328,10 +329,10 @@ openclaw cron edit <jobId> --clear-agent
|
||||
|
||||
模型覆盖说明：
|
||||
|
||||
- `openclaw cron add|edit --model ...` 会更改任务所选的模型。
|
||||
- 如果该模型被允许，独立智能体运行将使用这个精确的 provider/模型。
|
||||
- 如果不被允许，cron 会发出警告，并回退到任务的智能体/默认模型选择。
|
||||
- 已配置的回退链仍然适用，但普通的 `--model` 覆盖如果没有显式的逐任务回退列表，就不再静默回落到智能体主模型作为额外的重试目标。
|
||||
- `openclaw cron add|edit --model ...` 会更改作业选定的模型。
|
||||
- 如果该模型被允许，那个确切的 provider/model 会传递给独立智能体运行。
|
||||
- 如果它不被允许，cron 会发出警告，并回退到该作业的智能体/默认模型选择。
|
||||
- 已配置的回退链仍然会生效，但单独的 `--model` 覆盖在没有显式按作业回退列表时，不会再悄悄回退到智能体主模型作为额外重试目标。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -353,19 +354,19 @@ openclaw cron edit <jobId> --clear-agent
|
||||
}
|
||||
```
|
||||
|
||||
运行时状态 sidecar 由 `cron.store` 推导而来：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而没有 `.json` 后缀的存储路径则会追加 `-state.json`。
|
||||
运行时状态 sidecar 由 `cron.store` 派生：像 `~/clawd/cron/jobs.json` 这样的 `.json` 存储会使用 `~/clawd/cron/jobs-state.json`，而没有 `.json` 后缀的存储路径则会追加 `-state.json`。
|
||||
|
||||
禁用 cron：`cron.enabled: false` 或 `OPENCLAW_SKIP_CRON=1`。
|
||||
|
||||
**一次性任务重试**：瞬时错误（速率限制、过载、网络、服务器错误）最多重试 3 次，并使用指数退避。永久性错误会立即禁用。
|
||||
**一次性重试**：暂时性错误（速率限制、过载、网络、服务器错误）最多重试 3 次，并采用指数退避。永久性错误会立即禁用。
|
||||
|
||||
**循环任务重试**：重试之间使用指数退避（30 秒到 60 分钟）。下一次成功运行后会重置退避状态。
|
||||
**循环重试**：重试之间采用指数退避（30 秒到 60 分钟）。在下一次成功运行后，退避会重置。
|
||||
|
||||
**维护**：`cron.sessionRetention`（默认 `24h`）会清理独立运行的会话条目。`cron.runLog.maxBytes` / `cron.runLog.keepLines` 会自动清理运行日志文件。
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 命令排查顺序
|
||||
### 命令梯
|
||||
|
||||
```bash
|
||||
openclaw status
|
||||
@ -378,30 +379,30 @@ openclaw logs --follow
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
### Cron 未触发
|
||||
### Cron 没有触发
|
||||
|
||||
- 检查 `cron.enabled` 和 `OPENCLAW_SKIP_CRON` 环境变量。
|
||||
- 确认 Gateway 网关正在持续运行。
|
||||
- 对于 `cron` 调度，请核对时区（`--tz`）与主机时区是否一致。
|
||||
- 运行输出中的 `reason: not-due` 表示你通过 `openclaw cron run <jobId> --due` 检查了手动运行，但该任务尚未到期。
|
||||
- 确认 Gateway 网关持续处于运行状态。
|
||||
- 对于 `cron` 调度，验证时区（`--tz`）与主机时区是否一致。
|
||||
- 运行输出中的 `reason: not-due` 表示使用 `openclaw cron run <jobId> --due` 检查了手动运行，但该作业尚未到期。
|
||||
|
||||
### Cron 已触发但没有投递
|
||||
|
||||
- 投递模式为 `none` 表示不应期待运行器执行回退发送。如果聊天路由可用，智能体仍可通过 `message` 工具直接发送。
|
||||
- 投递目标缺失/无效（`channel`/`to`）表示已跳过出站发送。
|
||||
- 投递模式 `none` 表示不应期待运行器执行回退发送。当有可用聊天路由时，智能体仍然可以通过 `message` 工具直接发送。
|
||||
- 投递目标缺失/无效（`channel`/`to`）意味着出站发送已被跳过。
|
||||
- 渠道身份验证错误（`unauthorized`、`Forbidden`）表示投递被凭证阻止。
|
||||
- 如果独立运行只返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接的出站投递，也会抑制回退的排队摘要路径，因此不会有任何内容发回聊天。
|
||||
- 如果智能体应自行向用户发送消息，请检查该任务是否具有可用路由（带有先前聊天记录的 `channel: "last"`，或显式的渠道/目标）。
|
||||
- 如果独立运行只返回静默 token（`NO_REPLY` / `no_reply`），OpenClaw 会抑制直接出站投递，也会抑制回退排队摘要路径，因此不会向聊天回发任何内容。
|
||||
- 如果应该由智能体自行给用户发消息，请检查该作业是否有可用路由（带有先前聊天记录的 `channel: "last"`，或显式渠道/目标）。
|
||||
|
||||
### 时区注意事项
|
||||
|
||||
- 不带 `--tz` 的 cron 会使用 Gateway 网关主机时区。
|
||||
- 不带 `--tz` 的 cron 使用 gateway 主机时区。
|
||||
- 不带时区的 `at` 调度会被视为 UTC。
|
||||
- Heartbeat 的 `activeHours` 使用已配置的时区解析。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [自动化与任务](/zh-CN/automation) — 一览所有自动化机制
|
||||
- [后台任务](/zh-CN/automation/tasks) — cron 执行的任务账本
|
||||
- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性的主会话轮次
|
||||
- [时区](/zh-CN/concepts/timezone) — 时区配置
|
||||
- [Automation & Tasks](/zh-CN/automation) —— 所有自动化机制总览
|
||||
- [Background Tasks](/zh-CN/automation/tasks) —— cron 执行的任务账本
|
||||
- [Heartbeat](/zh-CN/gateway/heartbeat) —— 周期性的主会话轮次
|
||||
- [Timezone](/zh-CN/concepts/timezone) —— 时区配置
|
||||
|
||||
@ -1,20 +1,18 @@
|
||||
---
|
||||
read_when:
|
||||
- 设置 Slack 或调试 Slack 的 socket/HTTP 模式
|
||||
- 设置 Slack 或调试 Slack socket/HTTP 模式
|
||||
summary: Slack 设置与运行时行为（Socket Mode + HTTP 请求 URL）
|
||||
title: Slack
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T15:05:04Z"
|
||||
generated_at: "2026-04-23T19:23:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 19d87dfc1fd655c3849fd66053826f6d054b9d3150e6321f7f7252ab8409edb8
|
||||
source_hash: 530514e9da8ff611eada0bbdd6d274c2c21c5d14cac55346641389fec065c0b4
|
||||
source_path: channels/slack.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Slack
|
||||
|
||||
状态：可通过 Slack 应用集成在私信和渠道中投入生产使用。默认模式为 Socket Mode；也支持 HTTP 请求 URL。
|
||||
通过 Slack 应用集成即可为私信和渠道提供生产可用支持。默认模式为 Socket Mode；也支持 HTTP 请求 URL。
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
|
||||
@ -24,7 +22,7 @@ x-i18n:
|
||||
原生命令行为和命令目录。
|
||||
</Card>
|
||||
<Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
|
||||
跨渠道诊断和修复操作手册。
|
||||
跨渠道诊断与修复操作手册。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -38,8 +36,8 @@ x-i18n:
|
||||
|
||||
- 选择 **from a manifest**，并为你的应用选择一个工作区
|
||||
- 粘贴下方的[示例清单](#manifest-and-scope-checklist)，然后继续创建
|
||||
- 生成一个具有 `connections:write` 权限的 **App-Level Token**（`xapp-...`）
|
||||
- 安装应用并复制显示出的 **Bot Token**（`xoxb-...`）
|
||||
- 生成带有 `connections:write` 权限的 **App-Level Token**（`xapp-...`）
|
||||
- 安装应用，并复制显示的 **Bot Token**（`xoxb-...`）
|
||||
</Step>
|
||||
|
||||
<Step title="配置 OpenClaw">
|
||||
@ -83,9 +81,9 @@ openclaw gateway
|
||||
在 Slack 应用设置中，点击 **[Create New App](https://api.slack.com/apps/new)** 按钮：
|
||||
|
||||
- 选择 **from a manifest**，并为你的应用选择一个工作区
|
||||
- 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新这些 URL
|
||||
- 保存用于请求验证的 **Signing Secret**
|
||||
- 安装应用并复制显示出的 **Bot Token**（`xoxb-...`）
|
||||
- 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL
|
||||
- 保存用于请求校验的 **Signing Secret**
|
||||
- 安装应用，并复制显示的 **Bot Token**（`xoxb-...`）
|
||||
|
||||
</Step>
|
||||
|
||||
@ -106,9 +104,9 @@ openclaw gateway
|
||||
```
|
||||
|
||||
<Note>
|
||||
为多账户 HTTP 使用唯一的 webhook 路径
|
||||
对多账户 HTTP 使用唯一的 webhook 路径
|
||||
|
||||
为每个账户提供不同的 `webhookPath`（默认是 `/slack/events`），以免注册发生冲突。
|
||||
为每个账户分配不同的 `webhookPath`（默认是 `/slack/events`），这样注册就不会冲突。
|
||||
</Note>
|
||||
|
||||
</Step>
|
||||
@ -125,9 +123,9 @@ openclaw gateway
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 清单与作用域检查清单
|
||||
## 清单和 scope 检查清单
|
||||
|
||||
Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只有 `settings` 代码块（以及 slash command 的 `url`）不同。
|
||||
基础 Slack 应用清单在 Socket Mode 和 HTTP 请求 URL 中相同。只有 `settings` 块（以及斜杠命令的 `url`）不同。
|
||||
|
||||
基础清单（Socket Mode 默认）：
|
||||
|
||||
@ -201,7 +199,7 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只
|
||||
}
|
||||
```
|
||||
|
||||
对于 **HTTP 请求 URL 模式**，请将 `settings` 替换为 HTTP 变体，并为每个 slash command 添加 `url`。需要公开 URL：
|
||||
对于 **HTTP 请求 URL 模式**，请将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公共 URL：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -233,17 +231,17 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只
|
||||
|
||||
### 其他清单设置
|
||||
|
||||
展示可扩展上述默认值的不同功能。
|
||||
展示可扩展上述默认设置的不同功能。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="可选原生斜杠命令">
|
||||
|
||||
可以使用多个[原生斜杠命令](#commands-and-slash-behavior)，而不是单个已配置命令，但有一些细节需要注意：
|
||||
可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个已配置命令，但有一些细节需要注意：
|
||||
|
||||
- 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已被保留。
|
||||
- 同时可用的斜杠命令不能超过 25 个。
|
||||
- 同时最多只能提供 25 个斜杠命令。
|
||||
|
||||
将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的一个子集：
|
||||
请将你现有的 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)中的一个子集：
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Socket Mode（默认）">
|
||||
@ -363,140 +361,22 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只
|
||||
|
||||
</Tab>
|
||||
<Tab title="HTTP 请求 URL">
|
||||
使用与上方 Socket Mode 相同的 `slash_commands` 列表，并为每一项添加 `"url": "https://gateway-host.example.com/slack/events"`。示例：
|
||||
|
||||
```json
|
||||
"slash_commands": [
|
||||
{
|
||||
"command": "/new",
|
||||
"description": "开始新会话",
|
||||
"description": "Start a new session",
|
||||
"usage_hint": "[model]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/reset",
|
||||
"description": "重置当前会话",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/compact",
|
||||
"description": "压缩会话上下文",
|
||||
"usage_hint": "[instructions]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/stop",
|
||||
"description": "停止当前运行",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/session",
|
||||
"description": "管理线程绑定过期时间",
|
||||
"usage_hint": "idle <duration|off> 或 max-age <duration|off>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/think",
|
||||
"description": "设置思考级别",
|
||||
"usage_hint": "<level>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/verbose",
|
||||
"description": "切换详细输出",
|
||||
"usage_hint": "on|off|full",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/fast",
|
||||
"description": "显示或设置快速模式",
|
||||
"usage_hint": "[status|on|off]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/reasoning",
|
||||
"description": "切换推理可见性",
|
||||
"usage_hint": "[on|off|stream]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/elevated",
|
||||
"description": "切换提升模式",
|
||||
"usage_hint": "[on|off|ask|full]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/exec",
|
||||
"description": "显示或设置 exec 默认值",
|
||||
"usage_hint": "host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/model",
|
||||
"description": "显示或设置模型",
|
||||
"usage_hint": "[name|#|status]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/models",
|
||||
"description": "列出提供商，或列出某个提供商的模型",
|
||||
"usage_hint": "[provider] [page] [limit=<n>|size=<n>|all]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/help",
|
||||
"description": "显示简短帮助摘要",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/commands",
|
||||
"description": "显示生成的命令目录",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/tools",
|
||||
"description": "显示当前智能体此刻可使用的内容",
|
||||
"usage_hint": "[compact|verbose]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/agentstatus",
|
||||
"description": "显示运行时状态，包括可用时的提供商使用量/配额",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/tasks",
|
||||
"description": "列出当前会话中活跃/最近的后台任务",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/context",
|
||||
"description": "说明上下文是如何组装的",
|
||||
"usage_hint": "[list|detail|json]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/whoami",
|
||||
"description": "显示你的发送者身份",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/skill",
|
||||
"description": "按名称运行 skill",
|
||||
"usage_hint": "<name> [input]",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/btw",
|
||||
"description": "在不更改会话上下文的情况下提出一个旁支问题",
|
||||
"usage_hint": "<question>",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
},
|
||||
{
|
||||
"command": "/usage",
|
||||
"description": "控制 usage 页脚或显示成本摘要",
|
||||
"usage_hint": "off|tokens|full|cost",
|
||||
"description": "Show the short help summary",
|
||||
"url": "https://gateway-host.example.com/slack/events"
|
||||
}
|
||||
// ...为每个命令重复添加相同的 `url` 值
|
||||
]
|
||||
```
|
||||
|
||||
@ -504,14 +384,14 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只
|
||||
</Tabs>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="可选作者身份作用域（写入操作）">
|
||||
如果你希望发出的消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。
|
||||
<Accordion title="可选署名 scope（写入操作）">
|
||||
如果你希望出站消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot scope。
|
||||
|
||||
如果你使用 emoji 图标，Slack 要求采用 `:emoji_name:` 语法。
|
||||
如果你使用表情符号图标，Slack 要求使用 `:emoji_name:` 语法。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="可选用户令牌作用域（读取操作）">
|
||||
如果你配置了 `channels.slack.userToken`，典型的读取作用域包括：
|
||||
<Accordion title="可选 user-token scope（读取操作）">
|
||||
如果你配置了 `channels.slack.userToken`，常见的读取 scope 包括：
|
||||
|
||||
- `channels:history`、`groups:history`、`im:history`、`mpim:history`
|
||||
- `channels:read`、`groups:read`、`im:read`、`mpim:read`
|
||||
@ -524,41 +404,41 @@ Slack 应用的基础清单在 Socket Mode 和 HTTP 请求 URL 中相同。只
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 令牌模型
|
||||
## Token 模型
|
||||
|
||||
- Socket Mode 需要 `botToken` + `appToken`。
|
||||
- HTTP 模式需要 `botToken` + `signingSecret`。
|
||||
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。
|
||||
- 配置中的令牌会覆盖环境变量回退。
|
||||
- 配置中的 token 会覆盖环境变量回退值。
|
||||
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账户。
|
||||
- `userToken`（`xoxp-...`）仅支持通过配置提供（无环境变量回退），并且默认是只读行为（`userTokenReadOnly: true`）。
|
||||
- `userToken`（`xoxp-...`）仅支持通过配置提供（无环境变量回退），且默认是只读行为（`userTokenReadOnly: true`）。
|
||||
|
||||
状态快照行为：
|
||||
|
||||
- Slack 账户检查会跟踪每个凭证对应的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。
|
||||
- 状态可以是 `available`、`configured_unavailable` 或 `missing`。
|
||||
- `configured_unavailable` 表示该账户通过 SecretRef 或其他非内联密钥来源进行了配置，但当前命令/运行时路径无法解析出实际值。
|
||||
- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需的一对状态字段是 `botTokenStatus` + `appTokenStatus`。
|
||||
- Slack 账户检查会按凭证跟踪各自的 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。
|
||||
- 状态值可以是 `available`、`configured_unavailable` 或 `missing`。
|
||||
- `configured_unavailable` 表示账户通过 SecretRef 或其他非内联 secret 来源完成了配置，但当前命令/运行时路径无法解析出实际值。
|
||||
- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需组合是 `botTokenStatus` + `appTokenStatus`。
|
||||
|
||||
<Tip>
|
||||
对于 actions/目录读取，如果配置了用户令牌，则可以优先使用它。对于写入，仍优先使用 bot 令牌；仅当 `userTokenReadOnly: false` 且 bot 令牌不可用时，才允许使用用户令牌写入。
|
||||
对于操作/目录读取，如果配置了 user token，则可以优先使用它。对于写入，仍然优先使用 bot token；只有在 `userTokenReadOnly: false` 且 bot token 不可用时，才允许使用 user-token 写入。
|
||||
</Tip>
|
||||
|
||||
## Actions 和门控
|
||||
## 操作与门控
|
||||
|
||||
Slack actions 由 `channels.slack.actions.*` 控制。
|
||||
Slack 操作由 `channels.slack.actions.*` 控制。
|
||||
|
||||
当前 Slack 工具中可用的 action 分组：
|
||||
当前 Slack 工具中的可用操作组：
|
||||
|
||||
| Group | Default |
|
||||
| 组 | 默认值 |
|
||||
| ---------- | ------- |
|
||||
| messages | enabled |
|
||||
| reactions | enabled |
|
||||
| pins | enabled |
|
||||
| memberInfo | enabled |
|
||||
| emojiList | enabled |
|
||||
| messages | 已启用 |
|
||||
| reactions | 已启用 |
|
||||
| pins | 已启用 |
|
||||
| memberInfo | 已启用 |
|
||||
| emojiList | 已启用 |
|
||||
|
||||
当前 Slack 消息 actions 包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。
|
||||
当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。
|
||||
|
||||
## 访问控制与路由
|
||||
|
||||
@ -577,12 +457,12 @@ Slack actions 由 `channels.slack.actions.*` 控制。
|
||||
- `channels.slack.allowFrom`（推荐）
|
||||
- `dm.allowFrom`（旧版）
|
||||
- `dm.groupEnabled`（群组私信默认 false）
|
||||
- `dm.groupChannels`（可选的 MPIM allowlist）
|
||||
- `dm.groupChannels`（可选 MPIM allowlist）
|
||||
|
||||
多账户优先级：
|
||||
|
||||
- `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账户。
|
||||
- 当命名账户自己的 `allowFrom` 未设置时，会继承 `channels.slack.allowFrom`。
|
||||
- 当命名账户自身未设置 `allowFrom` 时，会继承 `channels.slack.allowFrom`。
|
||||
- 命名账户不会继承 `channels.slack.accounts.default.allowFrom`。
|
||||
|
||||
在私信中进行配对时，使用 `openclaw pairing approve slack <code>`。
|
||||
@ -598,26 +478,26 @@ Slack actions 由 `channels.slack.actions.*` 控制。
|
||||
|
||||
渠道 allowlist 位于 `channels.slack.channels` 下，并且应使用稳定的渠道 ID。
|
||||
|
||||
运行时说明：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退到 `groupPolicy="allowlist"` 并记录一条警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。
|
||||
运行时说明：如果 `channels.slack` 完全缺失（仅环境变量设置），运行时会回退为 `groupPolicy="allowlist"` 并记录一条警告（即使设置了 `channels.defaults.groupPolicy` 也是如此）。
|
||||
|
||||
名称/ID 解析：
|
||||
|
||||
- 当令牌访问权限允许时，渠道 allowlist 条目和私信 allowlist 条目会在启动时解析
|
||||
- 无法解析的渠道名称条目会按配置保留，但默认会在路由中被忽略
|
||||
- 入站授权和渠道路由默认采用 ID 优先；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
- 渠道 allowlist 条目和私信 allowlist 条目会在启动时、在 token 访问权限允许的情况下进行解析
|
||||
- 无法解析的渠道名称条目会按配置保留，但默认不会参与路由
|
||||
- 入站授权和渠道路由默认优先按 ID 处理；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true`
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="提及和渠道用户">
|
||||
渠道消息默认受提及门控。
|
||||
<Tab title="提及与渠道用户">
|
||||
默认情况下，渠道消息受 mention 门控控制。
|
||||
|
||||
提及来源：
|
||||
mention 来源：
|
||||
|
||||
- 显式应用提及（`<@botId>`）
|
||||
- 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
|
||||
- 隐式回复给 bot 的线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
|
||||
- mention 正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
|
||||
- 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
|
||||
|
||||
每渠道控制（`channels.slack.channels.<id>`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 支持）：
|
||||
每渠道控制（`channels.slack.channels.<id>`；名称仅通过启动时解析或 `dangerouslyAllowNameMatching` 支持）：
|
||||
|
||||
- `requireMention`
|
||||
- `users`（allowlist）
|
||||
@ -626,37 +506,37 @@ Slack actions 由 `channels.slack.actions.*` 控制。
|
||||
- `systemPrompt`
|
||||
- `tools`、`toolsBySender`
|
||||
- `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符
|
||||
（旧版无前缀键仍仅映射到 `id:`）
|
||||
（旧版无前缀键仍然只映射到 `id:`）
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 线程、会话和回复标签
|
||||
## 线程、会话与回复标签
|
||||
|
||||
- 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。
|
||||
- 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。
|
||||
- 渠道会话：`agent:<agentId>:slack:channel:<channelId>`。
|
||||
- 在线程回复适用时，可以创建带线程会话后缀的回复（`:thread:<threadTs>`）。
|
||||
- 在线程回复适用时，可以创建带线程会话后缀（`:thread:<threadTs>`）的会话。
|
||||
- `channels.slack.thread.historyScope` 默认为 `thread`；`thread.inheritParent` 默认为 `false`。
|
||||
- `channels.slack.thread.initialHistoryLimit` 控制新线程会话开始时抓取多少现有线程消息（默认 `20`；设为 `0` 可禁用）。
|
||||
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当设为 `true` 时，会抑制隐式线程提及，因此 bot 即使已经参与了线程，也只会响应线程中的显式 `@bot` 提及。若不启用此项，在 bot 已参与的线程中进行回复时会绕过 `requireMention` 门控。
|
||||
- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时要抓取多少条现有线程消息（默认 `20`；设为 `0` 可禁用）。
|
||||
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：设为 `true` 时，会抑制隐式线程提及，因此机器人即使已经参与该线程，也只会响应线程内显式的 `@bot` 提及。不启用此项时，在机器人已参与的线程中的回复会绕过 `requireMention` 门控。
|
||||
|
||||
回复线程控制：
|
||||
|
||||
- `channels.slack.replyToMode`：`off|first|all|batched`（默认 `off`）
|
||||
- `channels.slack.replyToModeByChatType`：按 `direct|group|channel` 分别设置
|
||||
- 私聊的旧版回退：`channels.slack.dm.replyToMode`
|
||||
- `channels.slack.replyToModeByChatType`：按 `direct|group|channel`
|
||||
- 直聊旧版回退：`channels.slack.dm.replyToMode`
|
||||
|
||||
支持手动回复标签：
|
||||
|
||||
- `[[reply_to_current]]`
|
||||
- `[[reply_to:<id>]]`
|
||||
|
||||
注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程行为，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同；在 Telegram 中，即使在 `"off"` 模式下，显式标签仍会被遵循——Slack 线程会将消息隐藏在渠道视图之外，而 Telegram 回复仍以内联形式可见。
|
||||
注意：`replyToMode="off"` 会禁用 Slack 中**所有**回复线程功能，包括显式 `[[reply_to_*]]` 标签。这与 Telegram 不同，在 Telegram 中，即使在 `"off"` 模式下，显式标签仍会生效——Slack 线程会把消息隐藏在渠道中，而 Telegram 回复仍以内联形式可见。
|
||||
|
||||
## Ack reactions
|
||||
|
||||
`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。
|
||||
`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认表情。
|
||||
|
||||
解析顺序：
|
||||
|
||||
@ -668,7 +548,7 @@ Slack actions 由 `channels.slack.actions.*` 控制。
|
||||
说明：
|
||||
|
||||
- Slack 期望使用短代码（例如 `"eyes"`）。
|
||||
- 使用 `""` 可为 Slack 账户或全局禁用该 reaction。
|
||||
- 使用 `""` 可为某个 Slack 账户或全局禁用该 reaction。
|
||||
|
||||
## 文本流式传输
|
||||
|
||||
@ -676,18 +556,18 @@ Slack actions 由 `channels.slack.actions.*` 控制。
|
||||
|
||||
- `off`：禁用实时预览流式传输。
|
||||
- `partial`（默认）：用最新的部分输出替换预览文本。
|
||||
- `block`：追加分块的预览更新。
|
||||
- `progress`：在生成期间显示进度状态文本，然后发送最终文本。
|
||||
- `block`：追加分块预览更新。
|
||||
- `progress`：生成期间显示进度状态文本，然后发送最终文本。
|
||||
- `streaming.preview.toolProgress`：当草稿预览启用时，将工具/进度更新路由到同一条被编辑的预览消息中（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。
|
||||
|
||||
`channels.slack.streaming.nativeTransport` 控制当 `channels.slack.streaming.mode` 为 `partial` 时 Slack 原生文本流式传输的行为（默认：`true`）。
|
||||
当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。
|
||||
|
||||
- 必须有可用的回复线程，Slack 原生文本流式传输和 Slack assistant 线程状态才会显示。线程选择仍遵循 `replyToMode`。
|
||||
- 必须有可用的回复线程，才能显示原生文本流式传输和 Slack assistant 线程状态。线程选择仍遵循 `replyToMode`。
|
||||
- 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。
|
||||
- 顶层 Slack 私信默认保持非线程模式，因此不会显示线程样式的预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。
|
||||
- 顶层 Slack 私信默认保持非线程状态，因此不会显示线程式预览；如果你希望在那里看到可见进度，请使用线程回复或 `typingReaction`。
|
||||
- 媒体和非文本负载会回退到普通投递。
|
||||
- 媒体/错误类最终消息会取消待处理的预览编辑；符合条件的文本/块最终消息仅会在能够原地编辑预览时刷新。
|
||||
- 如果流式传输在回复中途失败，OpenClaw 会对剩余负载回退为普通投递。
|
||||
- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/块最终消息只有在可以原地编辑预览时才会刷新。
|
||||
- 如果流式传输在回复过程中失败，OpenClaw 会对剩余负载回退到普通投递。
|
||||
|
||||
使用草稿预览而不是 Slack 原生文本流式传输：
|
||||
|
||||
@ -704,15 +584,15 @@ Slack actions 由 `channels.slack.actions.*` 控制。
|
||||
}
|
||||
```
|
||||
|
||||
旧版键名：
|
||||
旧版键：
|
||||
|
||||
- `channels.slack.streamMode`（`replace | status_final | append`）会自动迁移到 `channels.slack.streaming.mode`。
|
||||
- 布尔型 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。
|
||||
- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。
|
||||
- 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。
|
||||
|
||||
## Typing reaction 回退
|
||||
|
||||
`typingReaction` 会在 OpenClaw 处理回复期间为入站 Slack 消息添加一个临时 reaction，并在运行结束后将其移除。这在线程回复之外尤其有用，因为线程回复会使用默认的“正在输入...”状态指示器。
|
||||
`typingReaction` 会在 OpenClaw 处理回复期间，给入站 Slack 消息添加一个临时 reaction，并在运行结束时移除它。这在非线程回复场景中特别有用，因为线程回复会使用默认的 “is typing...” 状态指示器。
|
||||
|
||||
解析顺序：
|
||||
|
||||
@ -722,39 +602,39 @@ Slack actions 由 `channels.slack.actions.*` 控制。
|
||||
说明：
|
||||
|
||||
- Slack 期望使用短代码（例如 `"hourglass_flowing_sand"`）。
|
||||
- 该 reaction 属于尽力而为，回复完成或失败路径结束后会自动尝试清理。
|
||||
- 该 reaction 采用尽力而为方式，回复完成或失败路径结束后会自动尝试清理。
|
||||
|
||||
## 媒体、分块与投递
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="入站附件">
|
||||
Slack 文件附件会从 Slack 托管的私有 URL 下载（基于令牌认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。
|
||||
Slack 文件附件会从 Slack 托管的私有 URL 下载（基于 token 认证的请求流程），并在抓取成功且大小限制允许时写入媒体存储。
|
||||
|
||||
运行时入站大小上限默认是 `20MB`，除非通过 `channels.slack.mediaMaxMb` 覆盖。
|
||||
运行时入站大小上限默认为 `20MB`，除非被 `channels.slack.mediaMaxMb` 覆盖。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="出站文本和文件">
|
||||
<Accordion title="出站文本与文件">
|
||||
- 文本分块使用 `channels.slack.textChunkLimit`（默认 4000）
|
||||
- `channels.slack.chunkMode="newline"` 启用按段落优先拆分
|
||||
- 文件发送使用 Slack 上传 API，并可包含线程回复（`thread_ts`）
|
||||
- 配置了 `channels.slack.mediaMaxMb` 时，出站媒体上限遵循该值；否则渠道发送使用媒体流水线中的 MIME 类型默认值
|
||||
- 出站媒体上限在配置了 `channels.slack.mediaMaxMb` 时遵循该值；否则渠道发送使用媒体管道中的 MIME 类型默认值
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="投递目标">
|
||||
推荐的显式目标：
|
||||
|
||||
- 私信使用 `user:<id>`
|
||||
- 渠道使用 `channel:<id>`
|
||||
- 私信用 `user:<id>`
|
||||
- 渠道用 `channel:<id>`
|
||||
|
||||
向用户目标发送时，Slack 私信会通过 Slack conversation API 打开。
|
||||
当向用户目标发送时，Slack 私信会通过 Slack 会话 API 打开。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 命令与 slash 行为
|
||||
## 命令与斜杠行为
|
||||
|
||||
Slack 中的 slash command 可以表现为单个已配置命令，或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值：
|
||||
斜杠命令在 Slack 中会显示为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值：
|
||||
|
||||
- `enabled: false`
|
||||
- `name: "openclaw"`
|
||||
@ -765,30 +645,30 @@ Slack 中的 slash command 可以表现为单个已配置命令，或多个原
|
||||
/openclaw /help
|
||||
```
|
||||
|
||||
原生命令需要你在 Slack 应用中配置[其他清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。
|
||||
原生命令需要在你的 Slack 应用中进行[其他清单设置](#additional-manifest-settings)，并通过 `channels.slack.commands.native: true` 或全局配置中的 `commands.native: true` 启用。
|
||||
|
||||
- 对于 Slack，原生命令自动模式默认是 **off**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。
|
||||
- 对 Slack 而言，原生命令自动模式默认**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。
|
||||
|
||||
```txt
|
||||
/help
|
||||
```
|
||||
|
||||
原生参数菜单使用自适应渲染策略，在分发所选选项值之前会先显示确认模态框：
|
||||
原生参数菜单使用自适应渲染策略，会在分发所选选项值之前显示确认模态框：
|
||||
|
||||
- 最多 5 个选项：按钮块
|
||||
- 6-100 个选项：静态选择菜单
|
||||
- 超过 100 个选项：当可用 interactivity 选项处理器时，使用带异步选项过滤的外部选择
|
||||
- 超出 Slack 限制时：已编码的选项值会回退为按钮
|
||||
- 超过 100 个选项：如果可用 interactivity 选项处理器，则使用带异步选项过滤的外部选择
|
||||
- 超出 Slack 限制：编码后的选项值会回退为按钮
|
||||
|
||||
```txt
|
||||
/think
|
||||
```
|
||||
|
||||
slash 会话使用类似 `agent:<agentId>:slack:slash:<userId>` 的隔离键，但仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。
|
||||
斜杠会话使用类似 `agent:<agentId>:slack:slash:<userId>` 的隔离键，但仍会通过 `CommandTargetSessionKey` 将命令执行路由到目标对话会话。
|
||||
|
||||
## 交互式回复
|
||||
|
||||
Slack 可以渲染由智能体编写的交互式回复控件，但此功能默认禁用。
|
||||
Slack 可以渲染由智能体编写的交互式回复控件，但此功能默认关闭。
|
||||
|
||||
全局启用：
|
||||
|
||||
@ -804,7 +684,7 @@ Slack 可以渲染由智能体编写的交互式回复控件，但此功能默
|
||||
}
|
||||
```
|
||||
|
||||
或仅为某个 Slack 账户启用：
|
||||
或者仅为一个 Slack 账户启用：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -822,39 +702,39 @@ Slack 可以渲染由智能体编写的交互式回复控件，但此功能默
|
||||
}
|
||||
```
|
||||
|
||||
启用后，智能体可以发出仅适用于 Slack 的回复指令：
|
||||
启用后，智能体可以输出仅限 Slack 的回复指令：
|
||||
|
||||
- `[[slack_buttons: Approve:approve, Reject:reject]]`
|
||||
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
|
||||
|
||||
这些指令会编译为 Slack Block Kit，并将点击或选择通过现有的 Slack 交互事件路径路由回来。
|
||||
这些指令会编译为 Slack Block Kit，并将点击或选择通过现有 Slack 交互事件路径路由回来。
|
||||
|
||||
说明：
|
||||
|
||||
- 这是 Slack 专用 UI。其他渠道不会将 Slack Block Kit 指令转换为自己的按钮系统。
|
||||
- 交互回调值是 OpenClaw 生成的不透明令牌，而不是智能体编写的原始值。
|
||||
- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的 blocks 负载。
|
||||
- 这是 Slack 特有的 UI。其他渠道不会将 Slack Block Kit 指令转换为它们自己的按钮系统。
|
||||
- 交互式回调值是 OpenClaw 生成的不透明 token，不是智能体原始编写的值。
|
||||
- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的块负载。
|
||||
|
||||
## Slack 中的 exec 审批
|
||||
## Slack 中的 Exec 审批
|
||||
|
||||
Slack 可以作为原生审批客户端，使用交互式按钮和交互，而不是回退到 Web UI 或终端。
|
||||
|
||||
- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。
|
||||
- 如果请求已经落在 Slack 中且审批 ID 类型为 `plugin:`，插件审批仍可通过同一套 Slack 原生按钮界面完成。
|
||||
- 审批人授权仍会被强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。
|
||||
- 当请求已经到达 Slack 且审批 ID 类型为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面进行处理。
|
||||
- 审批人授权仍然会被强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。
|
||||
|
||||
这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接以 Block Kit 按钮形式渲染在对话中。
|
||||
这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接在对话中渲染为 Block Kit 按钮。
|
||||
当这些按钮存在时，它们就是主要的审批 UX；只有当工具结果表明聊天审批不可用，或手动审批是唯一途径时，OpenClaw
|
||||
才应包含手动 `/approve` 命令。
|
||||
|
||||
配置路径：
|
||||
|
||||
- `channels.slack.execApprovals.enabled`
|
||||
- `channels.slack.execApprovals.approvers`（可选；尽可能回退到 `commands.ownerAllowFrom`）
|
||||
- `channels.slack.execApprovals.approvers`（可选；在可能时回退到 `commands.ownerAllowFrom`）
|
||||
- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`）
|
||||
- `agentFilter`、`sessionFilter`
|
||||
|
||||
当 `enabled` 未设置或为 `"auto"`，且至少解析出一名审批人时，Slack 会自动启用原生 exec 审批。将 `enabled: false` 设为显式禁用 Slack 作为原生审批客户端。
|
||||
当 `enabled` 未设置或为 `"auto"`，且至少解析出一个审批人时，Slack 会自动启用原生 exec 审批。将 `enabled: false` 设为显式禁用 Slack 作为原生审批客户端。
|
||||
将 `enabled: true` 设为在审批人可解析时强制启用原生审批。
|
||||
|
||||
在没有显式 Slack exec 审批配置时的默认行为：
|
||||
@ -867,7 +747,7 @@ Slack 可以作为原生审批客户端，使用交互式按钮和交互，而
|
||||
}
|
||||
```
|
||||
|
||||
只有当你想覆盖审批人、添加过滤器或选择将消息投递到来源聊天时，才需要显式 Slack 原生配置：
|
||||
只有在你想覆盖审批人、添加过滤器，或选择加入源聊天投递时，才需要显式 Slack 原生配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -883,42 +763,43 @@ Slack 可以作为原生审批客户端，使用交互式按钮和交互，而
|
||||
}
|
||||
```
|
||||
|
||||
共享 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是独立的；当这些请求已落在 Slack 中时，Slack 原生按钮仍可处理插件审批。
|
||||
共享 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是独立的；当这些请求已经到达 Slack 时，Slack 原生按钮仍然可以处理插件审批。
|
||||
|
||||
同聊天中的 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整的审批转发模型请参见[Exec approvals](/zh-CN/tools/exec-approvals)。
|
||||
同一聊天中的 `/approve` 在已经支持命令的 Slack 渠道和私信中也可用。完整的审批转发模型请参见 [Exec approvals](/zh-CN/tools/exec-approvals)。
|
||||
|
||||
## 事件与运行行为
|
||||
|
||||
- 消息编辑/删除/线程广播会映射为系统事件。
|
||||
- reaction 添加/移除事件会映射为系统事件。
|
||||
- 成员加入/离开、渠道创建/重命名，以及 pin 添加/移除事件会映射为系统事件。
|
||||
- 当启用了 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。
|
||||
- 渠道 topic/purpose 元数据被视为不受信任的上下文，并可注入到路由上下文中。
|
||||
- 在线程发起者和初始线程历史上下文植入过程中，会在适用时按已配置的发送者 allowlist 进行过滤。
|
||||
- Block action 和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并携带丰富的负载字段：
|
||||
- block action：选中值、标签、选择器值，以及 `workflow_*` 元数据
|
||||
- 模态 `view_submission` 和 `view_closed` 事件，带有已路由的渠道元数据和表单输入
|
||||
- 当启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。
|
||||
- 渠道 topic/purpose 元数据被视为不可信上下文，并可注入路由上下文。
|
||||
- 在线程发起者和初始线程历史上下文播种中，当适用时会根据已配置的发送者 allowlist 进行过滤。
|
||||
- 块操作和模态交互会发出结构化的 `Slack interaction: ...` 系统事件，并带有丰富的负载字段：
|
||||
- 块操作：所选值、标签、选择器值以及 `workflow_*` 元数据
|
||||
- 模态 `view_submission` 和 `view_closed` 事件，带有路由后的渠道元数据和表单输入
|
||||
|
||||
## 配置参考指引
|
||||
## 配置参考
|
||||
|
||||
主要参考：
|
||||
主参考： [配置参考 - Slack](/zh-CN/gateway/configuration-reference#slack)。
|
||||
|
||||
- [配置参考 - Slack](/zh-CN/gateway/configuration-reference#slack)
|
||||
<Accordion title="高信号 Slack 字段">
|
||||
|
||||
高信号 Slack 字段：
|
||||
- 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
|
||||
- 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels`
|
||||
- 兼容性开关：`dangerouslyAllowNameMatching`（紧急兜底；除非确有需要，否则保持关闭）
|
||||
- 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention`
|
||||
- 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
|
||||
- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress`
|
||||
- 运维/功能：`configWrites`、`commands.native`、`slashCommand.*`、`actions.*`、`userToken`、`userTokenReadOnly`
|
||||
- mode/auth：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
|
||||
- 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels`
|
||||
- 兼容性开关：`dangerouslyAllowNameMatching`（紧急兜底开关；除非必要否则保持关闭）
|
||||
- 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention`
|
||||
- 线程/历史记录：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
|
||||
- 投递：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress`
|
||||
- 运维/功能：`configWrites`、`commands.native`、`slashCommand.*`、`actions.*`、`userToken`、`userTokenReadOnly`
|
||||
|
||||
</Accordion>
|
||||
|
||||
## 故障排除
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="渠道中没有回复">
|
||||
按顺序检查：
|
||||
请按顺序检查：
|
||||
|
||||
- `groupPolicy`
|
||||
- 渠道 allowlist（`channels.slack.channels`）
|
||||
@ -948,47 +829,58 @@ openclaw pairing list slack
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Socket mode 未连接">
|
||||
验证 bot + app 令牌，以及 Slack 应用设置中是否启用了 Socket Mode。
|
||||
<Accordion title="Socket 模式未连接">
|
||||
验证 bot token、app token 以及 Slack 应用设置中的 Socket Mode 是否已启用。
|
||||
|
||||
如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或
|
||||
`appTokenStatus: "configured_unavailable"`，则说明 Slack 账户
|
||||
已完成配置，但当前运行时无法解析由 SecretRef 支持的
|
||||
实际值。
|
||||
`appTokenStatus: "configured_unavailable"`，说明 Slack 账户已完成配置，
|
||||
但当前运行时无法解析由 SecretRef 支持的实际值。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="HTTP 模式未接收事件">
|
||||
<Accordion title="HTTP 模式未接收到事件">
|
||||
验证：
|
||||
|
||||
- signing secret
|
||||
- webhook 路径
|
||||
- Slack 请求 URL（Events + Interactivity + Slash Commands）
|
||||
- Slack Request URL（Events + Interactivity + Slash Commands）
|
||||
- 每个 HTTP 账户使用唯一的 `webhookPath`
|
||||
|
||||
如果账户快照中出现 `signingSecretStatus: "configured_unavailable"`，
|
||||
则说明该 HTTP 账户已完成配置，但当前运行时无法
|
||||
解析由 SecretRef 支持的 signing secret 实际值。
|
||||
说明 HTTP 账户已完成配置，但当前运行时无法解析由 SecretRef 支持的 signing secret。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="原生命令/slash command 未触发">
|
||||
验证你是否本意要使用：
|
||||
<Accordion title="原生命令/斜杠命令未触发">
|
||||
确认你原本想使用的是：
|
||||
|
||||
- 原生命令模式（`channels.slack.commands.native: true`），并确保已在 Slack 中注册匹配的 slash command
|
||||
- 或单个 slash command 模式（`channels.slack.slashCommand.enabled: true`）
|
||||
- 原生命令模式（`channels.slack.commands.native: true`），并且在 Slack 中注册了匹配的斜杠命令
|
||||
- 或单斜杠命令模式（`channels.slack.slashCommand.enabled: true`）
|
||||
|
||||
还要检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。
|
||||
同时检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [配对](/zh-CN/channels/pairing)
|
||||
- [群组](/zh-CN/channels/groups)
|
||||
- [安全性](/zh-CN/gateway/security)
|
||||
- [渠道路由](/zh-CN/channels/channel-routing)
|
||||
- [故障排除](/zh-CN/channels/troubleshooting)
|
||||
- [配置](/zh-CN/gateway/configuration)
|
||||
- [斜杠命令](/zh-CN/tools/slash-commands)
|
||||
<CardGroup cols={2}>
|
||||
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
|
||||
将 Slack 用户与 Gateway 网关配对。
|
||||
</Card>
|
||||
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
|
||||
渠道和群组私信行为。
|
||||
</Card>
|
||||
<Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
|
||||
将入站消息路由到智能体。
|
||||
</Card>
|
||||
<Card title="安全" icon="shield" href="/zh-CN/gateway/security">
|
||||
威胁模型与加固。
|
||||
</Card>
|
||||
<Card title="配置" icon="sliders" href="/zh-CN/gateway/configuration">
|
||||
配置布局与优先级。
|
||||
</Card>
|
||||
<Card title="斜杠命令" icon="terminal" href="/zh-CN/tools/slash-commands">
|
||||
命令目录与行为。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -4,23 +4,23 @@ read_when:
|
||||
summary: '`openclaw config` 的 CLI 参考（get/set/unset/file/schema/validate）'
|
||||
title: 配置
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T18:44:46Z"
|
||||
generated_at: "2026-04-23T19:23:47Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c3b08d4f288cb00021509817e8552370bcf326b0f70b49abf8c26d6508801aab
|
||||
source_hash: ec16221cc977eb2108c4310eab6b49e74220de50425ab12201cf97d275ab5a65
|
||||
source_path: cli/config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# `openclaw config`
|
||||
|
||||
用于在 `openclaw.json` 中进行非交互式编辑的配置辅助命令：按路径获取/设置/取消设置/输出文件/输出 schema/验证值，并打印当前生效的配置文件。不带子命令运行时，会打开配置向导（与 `openclaw configure` 相同）。
|
||||
用于在 `openclaw.json` 中进行非交互式编辑的配置辅助工具：按路径获取/设置/取消设置/file/schema/validate 值，并打印当前生效的配置文件。不带子命令运行时，会打开配置向导（与 `openclaw configure` 相同）。
|
||||
|
||||
根选项：
|
||||
|
||||
- `--section <section>`：当你在不带子命令的情况下运行 `openclaw config` 时，可重复使用的引导式设置分区过滤器
|
||||
|
||||
支持的引导式分区：
|
||||
支持的引导分区：
|
||||
|
||||
- `workspace`
|
||||
- `model`
|
||||
@ -43,7 +43,7 @@ openclaw config get browser.executablePath
|
||||
openclaw config set browser.executablePath "/usr/bin/google-chrome"
|
||||
openclaw config set agents.defaults.heartbeat.every "2h"
|
||||
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
|
||||
openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge
|
||||
openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge
|
||||
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN
|
||||
openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json
|
||||
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
|
||||
@ -54,26 +54,26 @@ openclaw config validate --json
|
||||
|
||||
### `config schema`
|
||||
|
||||
将为 `openclaw.json` 生成的 JSON schema 以 JSON 形式输出到 stdout。
|
||||
将为 `openclaw.json` 生成的 JSON schema 以 JSON 形式打印到 stdout。
|
||||
|
||||
其包含内容：
|
||||
它包含：
|
||||
|
||||
- 当前根配置 schema，以及一个用于编辑器工具的根 `$schema` 字符串字段
|
||||
- 当前的根配置 schema，以及一个用于编辑器工具的根 `$schema` 字符串字段
|
||||
- Control UI 使用的字段 `title` 和 `description` 文档元数据
|
||||
- 嵌套对象、通配符（`*`）和数组项（`[]`）节点，在存在匹配字段文档时会继承相同的 `title` / `description` 元数据
|
||||
- `anyOf` / `oneOf` / `allOf` 分支在存在匹配字段文档时也会继承相同的文档元数据
|
||||
- 在可加载运行时清单时，尽力提供实时的 plugin 和渠道 schema 元数据
|
||||
- 即使当前配置无效，也会提供一个干净的后备 schema
|
||||
- 当存在匹配的字段文档时，嵌套对象、通配符（`*`）和数组项（`[]`）节点会继承相同的 `title` / `description` 元数据
|
||||
- 当存在匹配的字段文档时，`anyOf` / `oneOf` / `allOf` 分支也会继承相同的文档元数据
|
||||
- 当可以加载运行时清单时，尽力提供实时的插件 + 渠道 schema 元数据
|
||||
- 即使当前配置无效，也会提供一个干净的回退 schema
|
||||
|
||||
相关运行时 RPC：
|
||||
|
||||
- `config.schema.lookup` 会返回一个标准化后的配置路径，以及一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配的 UI 提示元数据和直接子项摘要。可用于 Control UI 或自定义客户端中按路径范围逐层查看。
|
||||
- `config.schema.lookup` 返回一个标准化的配置路径，其中包含一个浅层 schema 节点（`title`、`description`、`type`、`enum`、`const`、常见边界）、匹配到的 UI 提示元数据以及直接子项摘要。可将其用于 Control UI 或自定义客户端中的路径范围钻取。
|
||||
|
||||
```bash
|
||||
openclaw config schema
|
||||
```
|
||||
|
||||
如果你想用其他工具检查或验证它，可以将其导入文件：
|
||||
当你想用其他工具检查或验证它时，可将其输出到文件：
|
||||
|
||||
```bash
|
||||
openclaw config schema > openclaw.schema.json
|
||||
@ -97,7 +97,7 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name"
|
||||
|
||||
## 值
|
||||
|
||||
值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 可强制要求进行 JSON5 解析。`--json` 仍然作为旧别名受支持。
|
||||
值会尽可能按 JSON5 解析；否则会被视为字符串。使用 `--strict-json` 可强制要求进行 JSON5 解析。`--json` 仍作为旧版别名受支持。
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.heartbeat.every "0m"
|
||||
@ -105,18 +105,18 @@ openclaw config set gateway.port 19001 --strict-json
|
||||
openclaw config set channels.whatsapp.groups '["*"]' --strict-json
|
||||
```
|
||||
|
||||
`config get <path> --json` 会将原始值以 JSON 形式输出，而不是输出终端格式化文本。
|
||||
`config get <path> --json` 会将原始值作为 JSON 打印，而不是终端格式化文本。
|
||||
|
||||
默认情况下，对象赋值会替换目标路径。对于常用于保存用户添加条目的受保护映射/列表路径，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 和 `auth.profiles`，如果替换操作会删除现有条目，则会被拒绝，除非你传入 `--replace`。
|
||||
默认情况下，对象赋值会替换目标路径。对那些通常保存用户添加条目的受保护映射/列表路径，例如 `agents.defaults.models`、`models.providers`、`models.providers.<id>.models`、`plugins.entries` 和 `auth.profiles`，如果替换会删除现有条目，则会拒绝执行，除非你传入 `--replace`。
|
||||
|
||||
向这些映射中添加条目时，请使用 `--merge`：
|
||||
向这些映射添加条目时，请使用 `--merge`：
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge
|
||||
openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge
|
||||
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge
|
||||
```
|
||||
|
||||
仅当你明确希望所提供的值成为完整目标值时，才使用 `--replace`。
|
||||
仅当你明确希望提供的值成为完整目标值时，才使用 `--replace`。
|
||||
|
||||
## `config set` 模式
|
||||
|
||||
@ -164,12 +164,12 @@ openclaw config set --batch-file ./config-set.batch.json --dry-run
|
||||
|
||||
策略说明：
|
||||
|
||||
- 在不支持运行时可变更的表面上，SecretRef 赋值会被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook token，以及 WhatsApp creds JSON）。参见 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)。
|
||||
- 在不受支持的运行时可变表面上，SecretRef 赋值会被拒绝（例如 `hooks.token`、`commands.ownerDisplaySecret`、Discord 线程绑定 webhook token，以及 WhatsApp creds JSON）。参见 [SecretRef 凭证表面](/zh-CN/reference/secretref-credential-surface)。
|
||||
|
||||
批处理解析始终将批处理负载（`--batch-json`/`--batch-file`）视为唯一真实来源。
|
||||
批处理解析始终将批处理载荷（`--batch-json`/`--batch-file`）作为事实来源。
|
||||
`--strict-json` / `--json` 不会改变批处理解析行为。
|
||||
|
||||
JSON 路径/值模式对 SecretRef 和提供商也同样受支持：
|
||||
JSON 路径/值模式对 SecretRefs 和提供商都仍受支持：
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
@ -190,7 +190,7 @@ openclaw config set secrets.providers.vaultfile \
|
||||
- `--provider-source <env|file|exec>`
|
||||
- `--provider-timeout-ms <ms>`（`file`、`exec`）
|
||||
|
||||
Env 提供商（`--provider-source env`）：
|
||||
环境提供商（`--provider-source env`）：
|
||||
|
||||
- `--provider-allowlist <ENV_VAR>`（可重复）
|
||||
|
||||
@ -214,7 +214,7 @@ Exec 提供商（`--provider-source exec`）：
|
||||
- `--provider-allow-insecure-path`
|
||||
- `--provider-allow-symlink-command`
|
||||
|
||||
加固后的 exec 提供商示例：
|
||||
加固的 Exec 提供商示例：
|
||||
|
||||
```bash
|
||||
openclaw config set secrets.providers.vault \
|
||||
@ -228,9 +228,9 @@ openclaw config set secrets.providers.vault \
|
||||
--provider-timeout-ms 5000
|
||||
```
|
||||
|
||||
## Dry run
|
||||
## 试运行
|
||||
|
||||
使用 `--dry-run` 在不写入 `openclaw.json` 的情况下验证更改。
|
||||
使用 `--dry-run` 可在不写入 `openclaw.json` 的情况下验证更改。
|
||||
|
||||
```bash
|
||||
openclaw config set channels.discord.token \
|
||||
@ -254,25 +254,25 @@ openclaw config set channels.discord.token \
|
||||
--allow-exec
|
||||
```
|
||||
|
||||
Dry-run 行为：
|
||||
试运行行为：
|
||||
|
||||
- 构建器模式：对已更改的 ref/提供商运行 SecretRef 可解析性检查。
|
||||
- 构建器模式：对已更改的 refs/providers 运行 SecretRef 可解析性检查。
|
||||
- JSON 模式（`--strict-json`、`--json` 或批处理模式）：运行 schema 验证以及 SecretRef 可解析性检查。
|
||||
- 对已知不受支持的 SecretRef 目标表面也会运行策略验证。
|
||||
- 策略检查会评估更改后的完整配置，因此写入父对象（例如将 `hooks` 设置为对象）不能绕过不受支持表面的验证。
|
||||
- 为避免命令副作用，dry-run 期间默认会跳过 Exec SecretRef 检查。
|
||||
- 若要启用 exec SecretRef 检查，请在 `--dry-run` 时同时使用 `--allow-exec`（这可能会执行提供商命令）。
|
||||
- `--allow-exec` 仅可用于 dry-run；如果未配合 `--dry-run` 使用则会报错。
|
||||
- 对已知不受支持的 SecretRef 目标表面，也会运行策略验证。
|
||||
- 策略检查会评估变更后的完整配置，因此写入父对象（例如将 `hooks` 设置为对象）无法绕过不受支持表面的验证。
|
||||
- 为避免命令副作用，试运行期间默认会跳过 Exec SecretRef 检查。
|
||||
- 使用 `--allow-exec` 搭配 `--dry-run` 可选择启用 Exec SecretRef 检查（这可能会执行提供商命令）。
|
||||
- `--allow-exec` 仅适用于试运行；如果未搭配 `--dry-run` 使用则会报错。
|
||||
|
||||
`--dry-run --json` 会输出机器可读报告：
|
||||
`--dry-run --json` 会打印机器可读的报告：
|
||||
|
||||
- `ok`：dry-run 是否通过
|
||||
- `ok`：试运行是否通过
|
||||
- `operations`：已评估的赋值数量
|
||||
- `checks`：是否运行了 schema/可解析性检查
|
||||
- `checks.resolvabilityComplete`：可解析性检查是否完整运行完毕（当跳过 exec refs 时为 false）
|
||||
- `refsChecked`：dry-run 期间实际已解析的 ref 数量
|
||||
- `skippedExecRefs`：因未设置 `--allow-exec` 而跳过的 exec ref 数量
|
||||
- `errors`：当 `ok=false` 时的结构化 schema/可解析性失败信息
|
||||
- `checks.resolvabilityComplete`：可解析性检查是否完整执行（当跳过 exec refs 时为 false）
|
||||
- `refsChecked`：试运行期间实际解析的 ref 数量
|
||||
- `skippedExecRefs`：由于未设置 `--allow-exec` 而跳过的 exec ref 数量
|
||||
- `errors`：当 `ok=false` 时，结构化的 schema/可解析性失败信息
|
||||
|
||||
### JSON 输出结构
|
||||
|
||||
@ -293,7 +293,7 @@ Dry-run 行为：
|
||||
{
|
||||
kind: "schema" | "resolvability",
|
||||
message: string,
|
||||
ref?: string, // 出现可解析性错误时存在
|
||||
ref?: string, // 对于可解析性错误时存在
|
||||
},
|
||||
],
|
||||
}
|
||||
@ -342,20 +342,20 @@ Dry-run 行为：
|
||||
}
|
||||
```
|
||||
|
||||
如果 dry-run 失败：
|
||||
如果试运行失败：
|
||||
|
||||
- `config schema validation failed`：更改后的配置结构无效；请修正路径/值或提供商/ref 对象结构。
|
||||
- `config schema validation failed`：你变更后的配置结构无效；请修复路径/值或 provider/ref 对象结构。
|
||||
- `Config policy validation failed: unsupported SecretRef usage`：请将该凭证移回明文/字符串输入，并仅在受支持的表面上使用 SecretRefs。
|
||||
- `SecretRef assignment(s) could not be resolved`：当前引用的提供商/ref 无法解析（缺少环境变量、文件指针无效、exec 提供商失败，或提供商/来源不匹配）。
|
||||
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：dry-run 跳过了 exec refs；如果你需要验证 exec 可解析性，请使用 `--allow-exec` 重新运行。
|
||||
- 对于批处理模式，请修复失败的条目，然后在写入前重新运行 `--dry-run`。
|
||||
- `SecretRef assignment(s) could not be resolved`：被引用的 provider/ref 当前无法解析（缺少环境变量、文件指针无效、exec 提供商失败，或 provider/source 不匹配）。
|
||||
- `Dry run note: skipped <n> exec SecretRef resolvability check(s)`：试运行跳过了 exec refs；如果你需要验证 exec 可解析性，请使用 `--allow-exec` 重新运行。
|
||||
- 对于批处理模式，请修复失败条目，并在写入前重新运行 `--dry-run`。
|
||||
|
||||
## 写入安全
|
||||
|
||||
`openclaw config set` 和其他由 OpenClaw 管理的配置写入器，会在提交到磁盘前验证完整的更改后配置。如果新负载未通过 schema 验证，或看起来像是破坏性的覆盖，当前生效的配置将保持不变，被拒绝的负载会保存到其旁边，命名为 `openclaw.json.rejected.*`。
|
||||
当前生效的配置路径必须是常规文件。不支持通过符号链接形式的 `openclaw.json` 布局进行写入；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
|
||||
`openclaw config set` 和其他由 OpenClaw 管理的配置写入器，在将完整的变更后配置提交到磁盘前，会先进行验证。如果新载荷未通过 schema 验证，或看起来像是破坏性覆盖，则当前生效的配置会保持不变，而被拒绝的载荷会保存在其旁边，命名为 `openclaw.json.rejected.*`。
|
||||
生效配置路径必须是常规文件。写入不支持使用符号链接形式的 `openclaw.json` 布局；请改用 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
|
||||
|
||||
对于小范围编辑，优先使用 CLI 写入：
|
||||
小型编辑建议优先使用 CLI 写入：
|
||||
|
||||
```bash
|
||||
openclaw config set gateway.reload.mode hybrid --dry-run
|
||||
@ -363,7 +363,7 @@ openclaw config set gateway.reload.mode hybrid
|
||||
openclaw config validate
|
||||
```
|
||||
|
||||
如果写入被拒绝，请检查已保存的负载并修正完整配置结构：
|
||||
如果写入被拒绝，请检查保存的载荷并修复完整配置结构：
|
||||
|
||||
```bash
|
||||
CONFIG="$(openclaw config file)"
|
||||
@ -371,7 +371,7 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head
|
||||
openclaw config validate
|
||||
```
|
||||
|
||||
仍然允许直接使用编辑器写入，但正在运行的 Gateway 网关 会在这些更改通过验证之前将其视为不可信。无效的直接编辑可能会在启动或热重载期间，从“最后一次已知正常”的备份中恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
|
||||
仍然允许直接使用编辑器写入，但正在运行的 Gateway 网关会在这些更改通过验证前将其视为不受信任。无效的直接编辑可在启动或热重载期间从最后一次已知正常的备份中恢复。参见 [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
|
||||
|
||||
## 子命令
|
||||
|
||||
@ -379,7 +379,7 @@ openclaw config validate
|
||||
|
||||
编辑后请重启 Gateway 网关。
|
||||
|
||||
## 验证
|
||||
## validate
|
||||
|
||||
在不启动 Gateway 网关的情况下，根据当前生效的 schema 验证当前配置。
|
||||
|
||||
@ -388,9 +388,9 @@ openclaw config validate
|
||||
openclaw config validate --json
|
||||
```
|
||||
|
||||
当 `openclaw config validate` 通过后，你可以使用本地 TUI，让一个内嵌智能体在同一终端中，在你验证每一项更改时，对照文档比较当前生效配置：
|
||||
当 `openclaw config validate` 通过后，你可以使用本地 TUI，让一个内嵌智能体在你从同一个终端验证每项更改时，将当前生效的配置与文档进行对比：
|
||||
|
||||
如果验证已经失败，请先从 `openclaw configure` 或 `openclaw doctor --fix` 开始。`openclaw chat` 不会绕过无效配置保护机制。
|
||||
如果当前验证已经失败，请先使用 `openclaw configure` 或 `openclaw doctor --fix`。`openclaw chat` 不会绕过无效配置保护。
|
||||
|
||||
```bash
|
||||
openclaw chat
|
||||
@ -407,7 +407,7 @@ openclaw chat
|
||||
|
||||
典型修复流程：
|
||||
|
||||
- 让智能体将你当前的配置与相关文档页面进行比较，并建议最小修复方案。
|
||||
- 让智能体将你当前的配置与相关文档页面进行对比，并建议最小化修复方案。
|
||||
- 使用 `openclaw config set` 或 `openclaw configure` 应用有针对性的编辑。
|
||||
- 每次更改后重新运行 `openclaw config validate`。
|
||||
- 如果验证通过但运行时仍然不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 以获取迁移和修复帮助。
|
||||
- 如果验证通过但运行时仍不健康，请运行 `openclaw doctor` 或 `openclaw doctor --fix` 以获取迁移和修复帮助。
|
||||
|
||||
@ -2,40 +2,40 @@
|
||||
read_when:
|
||||
- 添加或修改 `openclaw infer` 命令
|
||||
- 设计稳定的无头能力自动化
|
||||
summary: 面向由提供商支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的推理优先 CLI
|
||||
summary: 面向由提供商支持的模型、图像、音频、TTS、视频、网页和嵌入工作流的 infer-first CLI
|
||||
title: 推理 CLI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T06:17:43Z"
|
||||
generated_at: "2026-04-23T19:23:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e57d2438d0da24e1ed880bbacd244ede4af56beba4ac1baa3f2a1e393e641c9c
|
||||
source_hash: a80407deae51d7443244f6bb45b2a197aca7aec838f6526b3755fa4109ae7e81
|
||||
source_path: cli/infer.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 推理 CLI
|
||||
|
||||
`openclaw infer` 是由提供商支持的推理工作流的规范无头界面。
|
||||
`openclaw infer` 是用于由提供商支持的推理工作流的规范无头界面。
|
||||
|
||||
它刻意暴露的是能力族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。
|
||||
它有意公开的是能力家族，而不是原始 Gateway 网关 RPC 名称，也不是原始智能体工具 id。
|
||||
|
||||
## 将 infer 变成一个 skill
|
||||
## 将 infer 变成一个技能
|
||||
|
||||
把下面内容复制并粘贴给一个智能体：
|
||||
将以下内容复制并粘贴给一个智能体：
|
||||
|
||||
```text
|
||||
Read https://docs.openclaw.ai/cli/infer, then create a skill that routes my common workflows to `openclaw infer`.
|
||||
Focus on model runs, image generation, video generation, audio transcription, TTS, web search, and embeddings.
|
||||
```
|
||||
|
||||
一个良好的基于 infer 的 skill 应该：
|
||||
一个好的基于 infer 的技能应当：
|
||||
|
||||
- 将常见用户意图映射到正确的 infer 子命令
|
||||
- 为其覆盖的工作流包含一些规范的 infer 示例
|
||||
- 在示例和建议中优先使用 `openclaw infer ...`
|
||||
- 避免在 skill 正文中重新记录整个 infer 界面
|
||||
- 避免在技能正文中重新记录整个 infer 界面
|
||||
|
||||
典型的面向 infer 的 skill 覆盖范围：
|
||||
典型的面向 infer 的技能覆盖范围：
|
||||
|
||||
- `openclaw infer model run`
|
||||
- `openclaw infer image generate`
|
||||
@ -46,15 +46,15 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
|
||||
## 为什么使用 infer
|
||||
|
||||
`openclaw infer` 为 OpenClaw 中由提供商支持的推理任务提供了一套统一的 CLI。
|
||||
`openclaw infer` 为 OpenClaw 中由提供商支持的推理任务提供了一个统一的 CLI。
|
||||
|
||||
优点：
|
||||
|
||||
- 使用 OpenClaw 中已经配置好的提供商和模型，而不是为每个后端分别接入一次性封装。
|
||||
- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一到一个命令树下。
|
||||
- 为脚本、自动化和智能体驱动的工作流提供稳定的 `--json` 输出结构。
|
||||
- 使用已经在 OpenClaw 中配置好的提供商和模型，而不是为每个后端单独编写一次性封装。
|
||||
- 将模型、图像、音频转录、TTS、视频、网页和嵌入工作流统一在一个命令树下。
|
||||
- 为脚本、自动化和智能体驱动的工作流使用稳定的 `--json` 输出结构。
|
||||
- 当任务本质上是“运行推理”时，优先使用 OpenClaw 的第一方界面。
|
||||
- 大多数 infer 命令都可以使用常规本地路径，而不要求 Gateway 网关参与。
|
||||
- 对于大多数 infer 命令，使用常规本地路径而无需依赖 Gateway 网关。
|
||||
|
||||
## 命令树
|
||||
|
||||
@ -112,46 +112,46 @@ Focus on model runs, image generation, video generation, audio transcription, TT
|
||||
下表将常见推理任务映射到对应的 infer 命令。
|
||||
|
||||
| 任务 | 命令 | 说明 |
|
||||
| ---- | ---- | ---- |
|
||||
| 运行文本 / 模型提示 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 |
|
||||
| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 如果从现有文件开始，使用 `image edit` |
|
||||
| ----------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------- |
|
||||
| 运行文本/模型提示词 | `openclaw infer model run --prompt "..." --json` | 默认使用常规本地路径 |
|
||||
| 生成图像 | `openclaw infer image generate --prompt "..." --json` | 从现有文件开始时请使用 `image edit` |
|
||||
| 描述图像文件 | `openclaw infer image describe --file ./image.png --json` | `--model` 必须是支持图像的 `<provider/model>` |
|
||||
| 转录音频 | `openclaw infer audio transcribe --file ./memo.m4a --json` | `--model` 必须是 `<provider/model>` |
|
||||
| 合成语音 | `openclaw infer tts convert --text "..." --output ./speech.mp3 --json` | `tts status` 面向 Gateway 网关 |
|
||||
| 生成视频 | `openclaw infer video generate --prompt "..." --json` | |
|
||||
| 描述视频文件 | `openclaw infer video describe --file ./clip.mp4 --json` | `--model` 必须是 `<provider/model>` |
|
||||
| 搜索网页 | `openclaw infer web search --query "..." --json` | |
|
||||
| 获取网页内容 | `openclaw infer web fetch --url https://example.com --json` | |
|
||||
| 获取网页 | `openclaw infer web fetch --url https://example.com --json` | |
|
||||
| 创建嵌入 | `openclaw infer embedding create --text "..." --json` | |
|
||||
|
||||
## 行为
|
||||
|
||||
- `openclaw infer ...` 是这些工作流的主要 CLI 界面。
|
||||
- 当输出将被另一个命令或脚本消费时，请使用 `--json`。
|
||||
- 当需要特定后端时，使用 `--provider` 或 `--model provider/model`。
|
||||
- 当输出会被其他命令或脚本消费时，请使用 `--json`。
|
||||
- 当需要特定后端时，请使用 `--provider` 或 `--model provider/model`。
|
||||
- 对于 `image describe`、`audio transcribe` 和 `video describe`，`--model` 必须使用 `<provider/model>` 形式。
|
||||
- 对于 `image describe`，显式指定 `--model` 会直接运行该提供商 / 模型。该模型必须在模型目录或提供商配置中具备图像能力。
|
||||
- 无状态执行命令默认走本地路径。
|
||||
- 由 Gateway 网关管理状态的命令默认走 Gateway 网关路径。
|
||||
- 常规本地路径不要求 Gateway 网关正在运行。
|
||||
- 对于 `image describe`，显式指定 `--model` 会直接运行该提供商/模型。该模型必须在模型目录或提供商配置中具备图像能力。
|
||||
- 无状态执行命令默认走本地。
|
||||
- 由 Gateway 网关管理状态的命令默认走 Gateway 网关。
|
||||
- 常规本地路径不要求 Gateway 网关处于运行状态。
|
||||
|
||||
## Model
|
||||
|
||||
使用 `model` 进行由提供商支持的文本推理，以及模型 / 提供商检查。
|
||||
使用 `model` 进行由提供商支持的文本推理，以及模型/提供商检查。
|
||||
|
||||
```bash
|
||||
openclaw infer model run --prompt "Reply with exactly: smoke-ok" --json
|
||||
openclaw infer model run --prompt "Summarize this changelog entry" --provider openai --json
|
||||
openclaw infer model providers --json
|
||||
openclaw infer model inspect --name gpt-5.4 --json
|
||||
openclaw infer model inspect --name gpt-5.5 --json
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `model run` 会复用智能体运行时，因此提供商 / 模型覆盖的行为与常规智能体执行一致。
|
||||
- `model run` 会复用智能体运行时，因此提供商/模型覆盖行为与常规智能体执行一致。
|
||||
- `model auth login`、`model auth logout` 和 `model auth status` 用于管理已保存的提供商认证状态。
|
||||
|
||||
## 图像
|
||||
## Image
|
||||
|
||||
使用 `image` 进行生成、编辑和描述。
|
||||
|
||||
@ -165,11 +165,11 @@ openclaw infer image describe --file ./photo.jpg --model ollama/qwen2.5vl:7b --j
|
||||
|
||||
说明：
|
||||
|
||||
- 当从现有输入文件开始时，使用 `image edit`。
|
||||
- 从现有输入文件开始时，请使用 `image edit`。
|
||||
- 对于 `image describe`，`--model` 必须是支持图像的 `<provider/model>`。
|
||||
- 对于本地 Ollama 视觉模型，请先拉取模型，并将 `OLLAMA_API_KEY` 设置为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。
|
||||
- 对于本地 Ollama 视觉模型，请先拉取模型，并将 `OLLAMA_API_KEY` 设为任意占位值，例如 `ollama-local`。参见 [Ollama](/zh-CN/providers/ollama#vision-and-image-description)。
|
||||
|
||||
## 音频
|
||||
## Audio
|
||||
|
||||
使用 `audio` 进行文件转录。
|
||||
|
||||
@ -200,7 +200,7 @@ openclaw infer tts status --json
|
||||
- `tts status` 默认走 Gateway 网关，因为它反映的是由 Gateway 网关管理的 TTS 状态。
|
||||
- 使用 `tts providers`、`tts voices` 和 `tts set-provider` 来检查和配置 TTS 行为。
|
||||
|
||||
## 视频
|
||||
## Video
|
||||
|
||||
使用 `video` 进行生成和描述。
|
||||
|
||||
@ -215,7 +215,7 @@ openclaw infer video describe --file ./clip.mp4 --model openai/gpt-4.1-mini --js
|
||||
|
||||
- 对于 `video describe`，`--model` 必须是 `<provider/model>`。
|
||||
|
||||
## 网页
|
||||
## Web
|
||||
|
||||
使用 `web` 进行搜索和抓取工作流。
|
||||
|
||||
@ -228,9 +228,9 @@ openclaw infer web providers --json
|
||||
|
||||
说明：
|
||||
|
||||
- 使用 `web providers` 检查可用、已配置和已选定的提供商。
|
||||
- 使用 `web providers` 来检查可用、已配置和已选定的提供商。
|
||||
|
||||
## 嵌入
|
||||
## Embedding
|
||||
|
||||
使用 `embedding` 进行向量创建和嵌入提供商检查。
|
||||
|
||||
@ -242,7 +242,7 @@ openclaw infer embedding providers --json
|
||||
|
||||
## JSON 输出
|
||||
|
||||
Infer 命令会在共享封装结构下统一 JSON 输出：
|
||||
Infer 命令会在共享封装下规范化 JSON 输出：
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@ -1,96 +1,94 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要一份按提供商逐项整理的模型设置参考文档
|
||||
- 你需要一份按提供商划分的模型设置参考资料
|
||||
- 你想要模型提供商的示例配置或 CLI 新手引导命令
|
||||
summary: 模型提供商概览，包含示例配置 + CLI 流程
|
||||
title: 模型提供商
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T16:30:10Z"
|
||||
generated_at: "2026-04-23T19:23:50Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 29fcf755be64658ed7ff2489ec3fa828f6bb848a63646f341529a3d3f332c12b
|
||||
source_hash: bdbb8deae102c8e55d4535ddb14b8eadb999c123cb6d188ebe563971bed762fc
|
||||
source_path: concepts/model-providers.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 模型提供商
|
||||
|
||||
本页介绍的是 **LLM/模型提供商**（不是像 WhatsApp/Telegram 这样的聊天渠道）。
|
||||
关于模型选择规则，参见 [/concepts/models](/zh-CN/concepts/models)。
|
||||
本页介绍 **LLM / 模型提供商**（而不是像 WhatsApp / Telegram 这样的聊天渠道）。
|
||||
有关模型选择规则，请参见 [/concepts/models](/zh-CN/concepts/models)。
|
||||
|
||||
## 快速规则
|
||||
|
||||
- 模型引用使用 `provider/model`（示例：`opencode/claude-opus-4-6`）。
|
||||
- 设置后，`agents.defaults.models` 会作为允许列表使用。
|
||||
- 模型引用使用 `provider/model`（例如：`opencode/claude-opus-4-6`）。
|
||||
- 设置后，`agents.defaults.models` 会作为允许列表。
|
||||
- CLI 辅助命令：`openclaw onboard`、`openclaw models list`、`openclaw models set <provider/model>`。
|
||||
- `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时实际生效的上限。
|
||||
- 回退规则、冷却探测和会话覆盖持久化：参见 [模型故障转移](/zh-CN/concepts/model-failover)。
|
||||
- 内置的 `codex` 与 Codex 智能体 harness 配对使用 —— 对于由 Codex 管理的登录、发现、原生线程恢复和 app-server 执行，请使用 `codex/gpt-*`。普通的 `openai/gpt-*` 使用 OpenAI 提供商和常规传输。对于仅 Codex 的部署，可通过 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动的 PI 回退 —— 参见 [Codex harness](/zh-CN/plugins/codex-harness)。
|
||||
- `models.providers.*.models[].contextWindow` 是模型原生元数据；`contextTokens` 是运行时生效的上限。
|
||||
- 回退规则、冷却探测和会话覆盖持久化：参见 [模型故障切换](/zh-CN/concepts/model-failover)。
|
||||
- 内置的 `codex` 与 Codex 智能体 harness 配套使用 —— 使用 `codex/gpt-*` 可获得由 Codex 管理的登录、发现、原生线程恢复和应用服务器执行。普通的 `openai/gpt-*` 使用 OpenAI 提供商和常规传输。对于仅使用 Codex 的部署，可通过 `agents.defaults.embeddedHarness.fallback: "none"` 禁用自动 PI 回退 —— 参见 [Codex harness](/zh-CN/plugins/codex-harness)。
|
||||
|
||||
## 由插件负责的提供商行为
|
||||
## 由插件拥有的提供商行为
|
||||
|
||||
大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保持通用推理循环。插件负责新手引导、模型目录、身份验证环境变量映射、传输/配置规范化、工具模式清理、故障转移分类、OAuth 刷新、用量上报、thinking/reasoning 配置文件等内容。
|
||||
大多数提供商特定逻辑都位于提供商插件中（`registerProvider(...)`），而 OpenClaw 保留通用推理循环。插件负责新手引导、模型目录、认证环境变量映射、传输 / 配置标准化、工具模式清理、故障切换分类、OAuth 刷新、使用情况报告、thinking / reasoning 配置文件等。
|
||||
|
||||
提供商 SDK 钩子与内置插件示例的完整列表见 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，则属于另一种更深层的扩展接口。
|
||||
Provider SDK hook 的完整列表以及内置插件示例位于 [提供商插件](/zh-CN/plugins/sdk-provider-plugins)。如果某个提供商需要完全自定义的请求执行器，则属于另一个更深层的扩展接口。
|
||||
|
||||
<Note>
|
||||
提供商运行时 `capabilities` 是共享运行器元数据（提供商家族、transcript/tooling 特性、传输/缓存提示）。它不同于[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)，后者描述的是插件注册了什么能力（文本推理、语音等）。
|
||||
提供商运行时 `capabilities` 是共享的运行器元数据（提供商系列、转录 / 工具特性、传输 / 缓存提示）。它与[公开能力模型](/zh-CN/plugins/architecture#public-capability-model)不同，后者描述的是插件注册了什么（文本推理、语音等）。
|
||||
</Note>
|
||||
|
||||
## API 密钥轮换
|
||||
|
||||
- 支持为选定提供商进行通用密钥轮换。
|
||||
- 支持为选定提供商进行通用提供商轮换。
|
||||
- 通过以下方式配置多个密钥：
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，优先级最高）
|
||||
- `OPENCLAW_LIVE_<PROVIDER>_KEY`（单个实时覆盖，最高优先级）
|
||||
- `<PROVIDER>_API_KEYS`（逗号或分号分隔的列表）
|
||||
- `<PROVIDER>_API_KEY`（主密钥）
|
||||
- `<PROVIDER>_API_KEY_*`（编号列表，例如 `<PROVIDER>_API_KEY_1`）
|
||||
- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项。
|
||||
- 密钥选择顺序会保留优先级并去重。
|
||||
- 仅在收到速率限制响应时，请求才会使用下一个密钥重试（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性用量限制消息）。
|
||||
- 对于 Google 提供商，还会将 `GOOGLE_API_KEY` 作为回退项包含在内。
|
||||
- 密钥选择顺序会保留优先级，并对值去重。
|
||||
- 仅在遇到速率限制响应时，才会使用下一个密钥重试请求（例如 `429`、`rate_limit`、`quota`、`resource exhausted`、`Too many concurrent requests`、`ThrottlingException`、`concurrency limit reached`、`workers_ai ... quota limit exceeded`，或周期性使用上限消息）。
|
||||
- 非速率限制失败会立即失败；不会尝试密钥轮换。
|
||||
- 当所有候选密钥都失败时，将返回最后一次尝试的最终错误。
|
||||
|
||||
## 内置提供商（pi-ai 目录）
|
||||
|
||||
OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
|
||||
`models.providers` 配置；只需设置身份验证并选择模型即可。
|
||||
OpenClaw 自带 pi‑ai 目录。这些提供商**不需要**
|
||||
`models.providers` 配置；只需设置认证信息并选择模型。
|
||||
|
||||
### OpenAI
|
||||
|
||||
- 提供商：`openai`
|
||||
- 身份验证：`OPENAI_API_KEY`
|
||||
- 认证：`OPENAI_API_KEY`
|
||||
- 可选轮换：`OPENAI_API_KEYS`、`OPENAI_API_KEY_1`、`OPENAI_API_KEY_2`，以及 `OPENCLAW_LIVE_OPENAI_KEY`（单个覆盖）
|
||||
- 示例模型：`openai/gpt-5.4`、`openai/gpt-5.4-pro`
|
||||
- 示例模型：`openai/gpt-5.5`、`openai/gpt-5.5-pro`
|
||||
- CLI：`openclaw onboard --auth-choice openai-api-key`
|
||||
- 默认传输为 `auto`（优先 WebSocket，回退到 SSE）
|
||||
- 可按模型通过 `agents.defaults.models["openai/<model>"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
|
||||
- OpenAI Responses WebSocket 预热默认启用，通过 `params.openaiWsWarmup` 控制（`true`/`false`）
|
||||
- OpenAI Responses WebSocket 预热默认通过 `params.openaiWsWarmup` 启用（`true` / `false`）
|
||||
- 可通过 `agents.defaults.models["openai/<model>"].params.serviceTier` 启用 OpenAI 优先级处理
|
||||
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射到 `api.openai.com` 上的 `service_tier=priority`
|
||||
- 当你需要显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
|
||||
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、
|
||||
`User-Agent`）仅应用于发往 `api.openai.com` 的原生 OpenAI 流量，不应用于通用 OpenAI 兼容代理
|
||||
- 原生 OpenAI 路由还会保留 Responses 的 `store`、prompt-cache 提示以及
|
||||
OpenAI reasoning 兼容负载整形；代理路由则不会
|
||||
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意屏蔽，因为实时 OpenAI API 会拒绝它；Spark 被视为仅限 Codex
|
||||
- `/fast` 和 `params.fastMode` 会将直接的 `openai/*` Responses 请求映射为发往 `api.openai.com` 的 `service_tier=priority`
|
||||
- 当你想使用显式层级而不是共享的 `/fast` 开关时，请使用 `params.serviceTier`
|
||||
- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）仅适用于发往 `api.openai.com` 的原生 OpenAI 流量，不适用于通用的 OpenAI 兼容代理
|
||||
- 原生 OpenAI 路由还会保留 Responses `store`、prompt-cache 提示以及 OpenAI reasoning 兼容载荷整形；代理路由不会
|
||||
- `openai/gpt-5.3-codex-spark` 在 OpenClaw 中被有意隐藏，因为实时 OpenAI API 会拒绝它；Spark 被视为仅供 Codex 使用
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
|
||||
agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
|
||||
}
|
||||
```
|
||||
|
||||
### Anthropic
|
||||
|
||||
- 提供商：`anthropic`
|
||||
- 身份验证：`ANTHROPIC_API_KEY`
|
||||
- 认证：`ANTHROPIC_API_KEY`
|
||||
- 可选轮换：`ANTHROPIC_API_KEYS`、`ANTHROPIC_API_KEY_1`、`ANTHROPIC_API_KEY_2`，以及 `OPENCLAW_LIVE_ANTHROPIC_KEY`（单个覆盖）
|
||||
- 示例模型：`anthropic/claude-opus-4-6`
|
||||
- CLI：`openclaw onboard --auth-choice apiKey`
|
||||
- 直接的公共 Anthropic 请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥和 OAuth 身份验证流量；OpenClaw 会将其映射到 Anthropic 的 `service_tier`（`auto` 与 `standard_only`）
|
||||
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为此集成的受支持方式。
|
||||
- Anthropic setup-token 仍然作为受支持的 OpenClaw token 路径提供，但 OpenClaw 现在在可用时更优先选择 Claude CLI 复用和 `claude -p`。
|
||||
- 直接面向公开 Anthropic 的请求支持共享的 `/fast` 开关和 `params.fastMode`，包括发送到 `api.anthropic.com` 的 API 密钥认证和 OAuth 认证流量；OpenClaw 会将其映射为 Anthropic `service_tier`（`auto` 与 `standard_only`）
|
||||
- Anthropic 说明：Anthropic 员工告诉我们，OpenClaw 风格的 Claude CLI 使用再次被允许，因此除非 Anthropic 发布新政策，否则 OpenClaw 会将 Claude CLI 复用和 `claude -p` 用法视为该集成的获准方式。
|
||||
- Anthropic setup-token 仍然作为受支持的 OpenClaw token 路径保留可用，但现在 OpenClaw 在可用时更倾向于 Claude CLI 复用和 `claude -p`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -101,23 +99,21 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
|
||||
### OpenAI Code（Codex）
|
||||
|
||||
- 提供商：`openai-codex`
|
||||
- 身份验证：OAuth（ChatGPT）
|
||||
- 示例模型：`openai-codex/gpt-5.4`
|
||||
- 认证：OAuth（ChatGPT）
|
||||
- 示例模型：`openai-codex/gpt-5.5`
|
||||
- CLI：`openclaw onboard --auth-choice openai-codex` 或 `openclaw models auth login --provider openai-codex`
|
||||
- 默认传输为 `auto`（优先 WebSocket，回退到 SSE）
|
||||
- 可按模型通过 `agents.defaults.models["openai-codex/<model>"].params.transport` 覆盖（`"sse"`、`"websocket"` 或 `"auto"`）
|
||||
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）上转发
|
||||
- 隐藏的 OpenClaw 归因请求头（`originator`、`version`、
|
||||
`User-Agent`）仅附加到发往
|
||||
`chatgpt.com/backend-api` 的原生 Codex 流量，不附加到通用 OpenAI 兼容代理
|
||||
- 它与直接的 `openai/*` 共享相同的 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
|
||||
- `params.serviceTier` 也会在原生 Codex Responses 请求（`chatgpt.com/backend-api`）中透传
|
||||
- 隐藏的 OpenClaw 归因头（`originator`、`version`、`User-Agent`）仅附加在发往 `chatgpt.com/backend-api` 的原生 Codex 流量上，不适用于通用的 OpenAI 兼容代理
|
||||
- 与直接的 `openai/*` 共用同一个 `/fast` 开关和 `params.fastMode` 配置；OpenClaw 会将其映射为 `service_tier=priority`
|
||||
- 当 Codex OAuth 目录公开 `openai-codex/gpt-5.3-codex-spark` 时，它仍然可用；取决于 entitlement
|
||||
- `openai-codex/gpt-5.4` 保持原生 `contextWindow = 1050000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
|
||||
- 策略说明：OpenAI Codex OAuth 明确支持用于 OpenClaw 这类外部工具/工作流。
|
||||
- `openai-codex/gpt-5.5` 保留原生 `contextWindow = 1000000` 和默认运行时 `contextTokens = 272000`；可通过 `models.providers.openai-codex.models[].contextTokens` 覆盖运行时上限
|
||||
- 政策说明：OpenAI Codex OAuth 明确支持 OpenClaw 这类外部工具 / 工作流
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
|
||||
agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } },
|
||||
}
|
||||
```
|
||||
|
||||
@ -126,7 +122,7 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
|
||||
models: {
|
||||
providers: {
|
||||
"openai-codex": {
|
||||
models: [{ id: "gpt-5.4", contextTokens: 160000 }],
|
||||
models: [{ id: "gpt-5.5", contextTokens: 160000 }],
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -135,13 +131,13 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
|
||||
|
||||
### 其他订阅式托管选项
|
||||
|
||||
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及阿里云 DashScope 和 Coding Plan 端点映射
|
||||
- [Qwen Cloud](/zh-CN/providers/qwen)：Qwen Cloud 提供商接口，以及 Alibaba DashScope 和 Coding Plan 端点映射
|
||||
- [MiniMax](/zh-CN/providers/minimax)：MiniMax Coding Plan OAuth 或 API 密钥访问
|
||||
- [GLM Models](/zh-CN/providers/glm)：Z.AI Coding Plan 或通用 API 端点
|
||||
|
||||
### OpenCode
|
||||
|
||||
- 身份验证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
|
||||
- 认证：`OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`）
|
||||
- Zen 运行时提供商：`opencode`
|
||||
- Go 运行时提供商：`opencode-go`
|
||||
- 示例模型：`opencode/claude-opus-4-6`、`opencode-go/kimi-k2.5`
|
||||
@ -156,20 +152,20 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
|
||||
### Google Gemini（API 密钥）
|
||||
|
||||
- 提供商：`google`
|
||||
- 身份验证：`GEMINI_API_KEY`
|
||||
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退项，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
|
||||
- 认证：`GEMINI_API_KEY`
|
||||
- 可选轮换：`GEMINI_API_KEYS`、`GEMINI_API_KEY_1`、`GEMINI_API_KEY_2`、`GOOGLE_API_KEY` 回退，以及 `OPENCLAW_LIVE_GEMINI_KEY`（单个覆盖）
|
||||
- 示例模型：`google/gemini-3.1-pro-preview`、`google/gemini-3-flash-preview`
|
||||
- 兼容性：旧版 OpenClaw 配置中的 `google/gemini-3.1-flash-preview` 会被规范化为 `google/gemini-3-flash-preview`
|
||||
- 兼容性：使用 `google/gemini-3.1-flash-preview` 的旧版 OpenClaw 配置会被标准化为 `google/gemini-3-flash-preview`
|
||||
- CLI：`openclaw onboard --auth-choice gemini-api-key`
|
||||
- 直接的 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`
|
||||
- 直接 Gemini 运行还接受 `agents.defaults.models["google/<model>"].params.cachedContent`
|
||||
（或旧版 `cached_content`），以转发提供商原生的
|
||||
`cachedContents/...` 句柄；Gemini 缓存命中会以 OpenClaw `cacheRead` 的形式体现
|
||||
`cachedContents/...` 句柄；Gemini 缓存命中会显示为 OpenClaw `cacheRead`
|
||||
|
||||
### Google Vertex 和 Gemini CLI
|
||||
|
||||
- 提供商：`google-vertex`、`google-gemini-cli`
|
||||
- 身份验证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
|
||||
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。有用户报告称，使用第三方客户端后，Google 账号可能受到限制。若你选择继续，请先查看 Google 条款，并使用非关键账号。
|
||||
- 认证：Vertex 使用 gcloud ADC；Gemini CLI 使用其 OAuth 流程
|
||||
- 注意：OpenClaw 中的 Gemini CLI OAuth 是非官方集成。一些用户报告称，在使用第三方客户端后，他们的 Google 账号受到限制。若你选择继续，请查看 Google 条款并使用非关键账号。
|
||||
- Gemini CLI OAuth 作为内置 `google` 插件的一部分提供。
|
||||
- 先安装 Gemini CLI：
|
||||
- `brew install gemini-cli`
|
||||
@ -178,54 +174,54 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
|
||||
- 登录：`openclaw models auth login --provider google-gemini-cli --set-default`
|
||||
- 默认模型：`google-gemini-cli/gemini-3-flash-preview`
|
||||
- 注意：你**不需要**将 client id 或 secret 粘贴到 `openclaw.json` 中。CLI 登录流程会将
|
||||
token 存储在 Gateway 网关主机上的身份验证配置文件中。
|
||||
token 存储在 Gateway 网关主机上的 auth profile 中。
|
||||
- 如果登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`。
|
||||
- Gemini CLI 的 JSON 回复从 `response` 中解析；用量则回退到
|
||||
`stats`，其中 `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
|
||||
- Gemini CLI JSON 回复会从 `response` 解析；使用情况会回退到
|
||||
`stats`，其中 `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
|
||||
|
||||
### Z.AI（GLM）
|
||||
|
||||
- 提供商：`zai`
|
||||
- 身份验证：`ZAI_API_KEY`
|
||||
- 认证：`ZAI_API_KEY`
|
||||
- 示例模型：`zai/glm-5.1`
|
||||
- CLI：`openclaw onboard --auth-choice zai-api-key`
|
||||
- 别名：`z.ai/*` 和 `z-ai/*` 会规范化为 `zai/*`
|
||||
- 别名：`z.ai/*` 和 `z-ai/*` 会标准化为 `zai/*`
|
||||
- `zai-api-key` 会自动检测匹配的 Z.AI 端点；`zai-coding-global`、`zai-coding-cn`、`zai-global` 和 `zai-cn` 会强制使用特定接口
|
||||
|
||||
### Vercel AI Gateway
|
||||
|
||||
- 提供商：`vercel-ai-gateway`
|
||||
- 身份验证：`AI_GATEWAY_API_KEY`
|
||||
- 认证：`AI_GATEWAY_API_KEY`
|
||||
- 示例模型：`vercel-ai-gateway/anthropic/claude-opus-4.6`、
|
||||
`vercel-ai-gateway/moonshotai/kimi-k2.6`
|
||||
- CLI：`openclaw onboard --auth-choice ai-gateway-api-key`
|
||||
|
||||
### Kilo Gateway 网关
|
||||
### Kilo Gateway
|
||||
|
||||
- 提供商：`kilocode`
|
||||
- 身份验证：`KILOCODE_API_KEY`
|
||||
- 认证：`KILOCODE_API_KEY`
|
||||
- 示例模型：`kilocode/kilo/auto`
|
||||
- CLI：`openclaw onboard --auth-choice kilocode-api-key`
|
||||
- 基础 URL：`https://api.kilo.ai/api/gateway/`
|
||||
- 静态回退目录内置 `kilocode/kilo/auto`；实时
|
||||
`https://api.kilo.ai/api/gateway/models` 发现可进一步扩展运行时
|
||||
`https://api.kilo.ai/api/gateway/models` 发现可以进一步扩展运行时
|
||||
目录。
|
||||
- `kilocode/kilo/auto` 背后的精确上游路由由 Kilo Gateway 网关负责，
|
||||
并非 OpenClaw 中硬编码。
|
||||
- `kilocode/kilo/auto` 背后的具体上游路由由 Kilo Gateway
|
||||
负责，而不是在 OpenClaw 中硬编码。
|
||||
|
||||
设置详情参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
|
||||
有关设置详情，请参见 [/providers/kilocode](/zh-CN/providers/kilocode)。
|
||||
|
||||
### 其他内置提供商插件
|
||||
|
||||
| 提供商 | Id | 身份验证环境变量 | 示例模型 |
|
||||
| 提供商 | Id | 认证环境变量 | 示例模型 |
|
||||
| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- |
|
||||
| BytePlus（国际版） | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` |
|
||||
| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` |
|
||||
| Cloudflare AI Gateway 网关 | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
|
||||
| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — |
|
||||
| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — |
|
||||
| Groq | `groq` | `GROQ_API_KEY` | — |
|
||||
| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` 或 `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` |
|
||||
| Kilo Gateway 网关 | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
|
||||
| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` |
|
||||
| Kimi Coding | `kimi` | `KIMI_API_KEY` 或 `KIMICODE_API_KEY` | `kimi/kimi-code` |
|
||||
| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` |
|
||||
| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` |
|
||||
@ -237,39 +233,40 @@ OpenClaw 内置了 pi‑ai 目录。这些提供商**不需要**
|
||||
| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` |
|
||||
| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` |
|
||||
| Venice | `venice` | `VENICE_API_KEY` | — |
|
||||
| Vercel AI Gateway 网关 | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
|
||||
| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
|
||||
| Volcano Engine（Doubao） | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` |
|
||||
| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` |
|
||||
| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` |
|
||||
|
||||
值得注意的特性：
|
||||
值得了解的特性：
|
||||
|
||||
- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其 app-attribution 请求头和 Anthropic `cache_control` 标记。作为代理风格的 OpenAI 兼容路径，它会跳过仅限原生 OpenAI 的整形（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI reasoning 兼容性）。基于 Gemini 的引用仅保留代理 Gemini 的 thought-signature 清理。
|
||||
- **Kilo Gateway 网关** 中基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。
|
||||
- **MiniMax** 的 API 密钥新手引导会写入显式的 M2.7 模型定义，并设置 `input: ["text", "image"]`；在该配置具体化之前，内置目录会将聊天引用保持为仅文本。
|
||||
- **OpenRouter** 仅在已验证的 `openrouter.ai` 路由上应用其应用归因头和 Anthropic `cache_control` 标记。作为代理式 OpenAI 兼容路径，它会跳过仅适用于原生 OpenAI 的整形（`serviceTier`、Responses `store`、prompt-cache 提示、OpenAI reasoning 兼容处理）。基于 Gemini 的引用仅保留代理 Gemini thought-signature 清理。
|
||||
- **Kilo Gateway** 基于 Gemini 的引用遵循相同的代理 Gemini 清理路径；`kilocode/kilo/auto` 和其他不支持代理 reasoning 的引用会跳过代理 reasoning 注入。
|
||||
- **MiniMax** API 密钥新手引导会写入显式的 M2.7 模型定义，并设置 `input: ["text", "image"]`；在该配置具体化之前，内置目录会将聊天引用保持为仅文本。
|
||||
- **xAI** 使用 xAI Responses 路径。`/fast` 或 `params.fastMode: true` 会将 `grok-3`、`grok-3-mini`、`grok-4` 和 `grok-4-0709` 重写为其 `*-fast` 变体。`tool_stream` 默认开启；可通过 `agents.defaults.models["xai/<model>"].params.tool_stream=false` 禁用。
|
||||
- **Cerebras** 的 GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容的基础 URL 为 `https://api.cerebras.ai/v1`。
|
||||
- **Cerebras** GLM 模型使用 `zai-glm-4.7` / `zai-glm-4.6`；OpenAI 兼容基础 URL 为 `https://api.cerebras.ai/v1`。
|
||||
|
||||
## 通过 `models.providers` 配置的提供商（自定义/基础 URL）
|
||||
## 通过 `models.providers` 使用的提供商（自定义 / 基础 URL）
|
||||
|
||||
使用 `models.providers`（或 `models.json`）来添加**自定义**提供商或
|
||||
OpenAI/Anthropic 兼容代理。
|
||||
使用 `models.providers`（或 `models.json`）添加**自定义**提供商或
|
||||
OpenAI / Anthropic 兼容代理。
|
||||
|
||||
下方许多内置提供商插件已经发布了默认目录。
|
||||
仅当你想覆盖默认基础 URL、请求头或模型列表时，
|
||||
下面的许多内置提供商插件已经发布了默认目录。
|
||||
只有当你想覆盖默认基础 URL、headers 或模型列表时，
|
||||
才需要使用显式的 `models.providers.<id>` 条目。
|
||||
|
||||
### Moonshot AI（Kimi）
|
||||
|
||||
Moonshot 作为内置提供商插件提供。默认情况下请使用内置提供商，
|
||||
仅当你需要覆盖基础 URL 或模型元数据时，才添加显式的 `models.providers.moonshot` 条目：
|
||||
Moonshot 以内置提供商插件形式提供。默认情况下请使用内置提供商，
|
||||
只有在你需要覆盖基础 URL 或模型元数据时，
|
||||
才添加显式的 `models.providers.moonshot` 条目：
|
||||
|
||||
- 提供商：`moonshot`
|
||||
- 身份验证：`MOONSHOT_API_KEY`
|
||||
- 认证：`MOONSHOT_API_KEY`
|
||||
- 示例模型：`moonshot/kimi-k2.6`
|
||||
- CLI：`openclaw onboard --auth-choice moonshot-api-key` 或 `openclaw onboard --auth-choice moonshot-api-key-cn`
|
||||
|
||||
Kimi K2 模型 ID：
|
||||
Kimi K2 模型 Id：
|
||||
|
||||
[//]: # "moonshot-kimi-k2-model-refs:start"
|
||||
|
||||
@ -305,7 +302,7 @@ Kimi K2 模型 ID：
|
||||
Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
|
||||
- 提供商：`kimi`
|
||||
- 身份验证：`KIMI_API_KEY`
|
||||
- 认证：`KIMI_API_KEY`
|
||||
- 示例模型：`kimi/kimi-code`
|
||||
|
||||
```json5
|
||||
@ -317,14 +314,14 @@ Kimi Coding 使用 Moonshot AI 的 Anthropic 兼容端点：
|
||||
}
|
||||
```
|
||||
|
||||
旧版 `kimi/k2p5` 仍然接受为兼容模型 ID。
|
||||
旧版 `kimi/k2p5` 仍然作为兼容性模型 id 被接受。
|
||||
|
||||
### Volcano Engine（Doubao）
|
||||
|
||||
Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访问。
|
||||
|
||||
- 提供商：`volcengine`（编码方案：`volcengine-plan`）
|
||||
- 身份验证：`VOLCANO_ENGINE_API_KEY`
|
||||
- 提供商：`volcengine`（编码版：`volcengine-plan`）
|
||||
- 认证：`VOLCANO_ENGINE_API_KEY`
|
||||
- 示例模型：`volcengine-plan/ark-code-latest`
|
||||
- CLI：`openclaw onboard --auth-choice volcengine-api-key`
|
||||
|
||||
@ -337,12 +334,12 @@ Volcano Engine（火山引擎）在中国提供对 Doubao 和其他模型的访
|
||||
```
|
||||
|
||||
新手引导默认使用编码接口，但通用 `volcengine/*`
|
||||
目录也会同时注册。
|
||||
目录会同时注册。
|
||||
|
||||
在新手引导/配置的模型选择器中，Volcengine 身份验证选项会优先显示
|
||||
在新手引导 / 配置的模型选择器中，Volcengine 认证选项会优先显示
|
||||
`volcengine/*` 和 `volcengine-plan/*` 行。如果这些模型尚未加载，
|
||||
OpenClaw 会回退到未筛选的目录，而不是显示空的
|
||||
按提供商范围筛选的选择器。
|
||||
OpenClaw 会回退到未过滤的目录，而不是显示空的
|
||||
提供商范围选择器。
|
||||
|
||||
可用模型：
|
||||
|
||||
@ -364,8 +361,8 @@ OpenClaw 会回退到未筛选的目录，而不是显示空的
|
||||
|
||||
BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力。
|
||||
|
||||
- 提供商：`byteplus`（编码方案：`byteplus-plan`）
|
||||
- 身份验证：`BYTEPLUS_API_KEY`
|
||||
- 提供商：`byteplus`（编码版：`byteplus-plan`）
|
||||
- 认证：`BYTEPLUS_API_KEY`
|
||||
- 示例模型：`byteplus-plan/ark-code-latest`
|
||||
- CLI：`openclaw onboard --auth-choice byteplus-api-key`
|
||||
|
||||
@ -378,12 +375,12 @@ BytePlus ARK 为国际用户提供与 Volcano Engine 相同模型的访问能力
|
||||
```
|
||||
|
||||
新手引导默认使用编码接口，但通用 `byteplus/*`
|
||||
目录也会同时注册。
|
||||
目录会同时注册。
|
||||
|
||||
在新手引导/配置的模型选择器中，BytePlus（国际版）身份验证选项会优先显示
|
||||
在新手引导 / 配置的模型选择器中，BytePlus（国际版） 认证选项会优先显示
|
||||
`byteplus/*` 和 `byteplus-plan/*` 行。如果这些模型尚未加载，
|
||||
OpenClaw 会回退到未筛选的目录，而不是显示空的
|
||||
按提供商范围筛选的选择器。
|
||||
OpenClaw 会回退到未过滤的目录，而不是显示空的
|
||||
提供商范围选择器。
|
||||
|
||||
可用模型：
|
||||
|
||||
@ -404,7 +401,7 @@ OpenClaw 会回退到未筛选的目录，而不是显示空的
|
||||
Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型：
|
||||
|
||||
- 提供商：`synthetic`
|
||||
- 身份验证：`SYNTHETIC_API_KEY`
|
||||
- 认证：`SYNTHETIC_API_KEY`
|
||||
- 示例模型：`synthetic/hf:MiniMaxAI/MiniMax-M2.5`
|
||||
- CLI：`openclaw onboard --auth-choice synthetic-api-key`
|
||||
|
||||
@ -429,37 +426,37 @@ Synthetic 通过 `synthetic` 提供商提供 Anthropic 兼容模型：
|
||||
|
||||
### MiniMax
|
||||
|
||||
MiniMax 通过 `models.providers` 进行配置，因为它使用自定义端点：
|
||||
MiniMax 通过 `models.providers` 配置，因为它使用自定义端点：
|
||||
|
||||
- MiniMax OAuth（Global）：`--auth-choice minimax-global-oauth`
|
||||
- MiniMax OAuth（CN）：`--auth-choice minimax-cn-oauth`
|
||||
- MiniMax API 密钥（Global）：`--auth-choice minimax-global-api`
|
||||
- MiniMax API 密钥（CN）：`--auth-choice minimax-cn-api`
|
||||
- 身份验证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或
|
||||
- 认证：`minimax` 使用 `MINIMAX_API_KEY`；`minimax-portal` 使用 `MINIMAX_OAUTH_TOKEN` 或
|
||||
`MINIMAX_API_KEY`
|
||||
|
||||
设置详情、模型选项和配置片段请参见 [/providers/minimax](/zh-CN/providers/minimax)。
|
||||
有关设置详情、模型选项和配置片段，请参见 [/providers/minimax](/zh-CN/providers/minimax)。
|
||||
|
||||
在 MiniMax 的 Anthropic 兼容流式传输路径上，OpenClaw 默认禁用 thinking，
|
||||
除非你显式启用它；而 `/fast on` 会将
|
||||
除非你显式设置它，并且 `/fast on` 会将
|
||||
`MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。
|
||||
|
||||
由插件负责的能力拆分：
|
||||
由插件拥有的能力拆分：
|
||||
|
||||
- 文本/聊天默认保持在 `minimax/MiniMax-M2.7`
|
||||
- 图像生成为 `minimax/image-01` 或 `minimax-portal/image-01`
|
||||
- 图像理解在两个 MiniMax 身份验证路径上都由插件负责，使用 `MiniMax-VL-01`
|
||||
- 文本 / 聊天默认使用 `minimax/MiniMax-M2.7`
|
||||
- 图像生成使用 `minimax/image-01` 或 `minimax-portal/image-01`
|
||||
- 图像理解在两个 MiniMax 认证路径上都使用由插件拥有的 `MiniMax-VL-01`
|
||||
- Web 搜索保持使用提供商 id `minimax`
|
||||
|
||||
### LM Studio
|
||||
|
||||
LM Studio 作为内置提供商插件提供，并使用原生 API：
|
||||
LM Studio 以内置提供商插件形式提供，并使用原生 API：
|
||||
|
||||
- 提供商：`lmstudio`
|
||||
- 身份验证：`LM_API_TOKEN`
|
||||
- 认证：`LM_API_TOKEN`
|
||||
- 默认推理基础 URL：`http://localhost:1234/v1`
|
||||
|
||||
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 ID）：
|
||||
然后设置一个模型（替换为 `http://localhost:1234/api/v1/models` 返回的某个 Id）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -471,14 +468,14 @@ LM Studio 作为内置提供商插件提供，并使用原生 API：
|
||||
|
||||
OpenClaw 使用 LM Studio 原生的 `/api/v1/models` 和 `/api/v1/models/load`
|
||||
进行发现 + 自动加载，默认使用 `/v1/chat/completions` 进行推理。
|
||||
设置与故障排除请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
|
||||
有关设置和故障排除，请参见 [/providers/lmstudio](/zh-CN/providers/lmstudio)。
|
||||
|
||||
### Ollama
|
||||
|
||||
Ollama 作为内置提供商插件提供，并使用 Ollama 的原生 API：
|
||||
Ollama 以内置提供商插件形式提供，并使用 Ollama 的原生 API：
|
||||
|
||||
- 提供商：`ollama`
|
||||
- 身份验证：无需（本地服务器）
|
||||
- 认证：无需（本地服务器）
|
||||
- 示例模型：`ollama/llama3.3`
|
||||
- 安装：[https://ollama.com/download](https://ollama.com/download)
|
||||
|
||||
@ -496,26 +493,27 @@ ollama pull llama3.3
|
||||
```
|
||||
|
||||
当你通过
|
||||
`OLLAMA_API_KEY` 选择启用时，Ollama 会在本地 `http://127.0.0.1:11434` 被检测到，
|
||||
并且内置提供商插件会将 Ollama 直接添加到
|
||||
`openclaw onboard` 和模型选择器中。有关新手引导、云端/本地模式及自定义配置，参见 [/providers/ollama](/zh-CN/providers/ollama)。
|
||||
`OLLAMA_API_KEY` 选择启用时，系统会在本地 `http://127.0.0.1:11434` 检测 Ollama，
|
||||
而内置提供商插件会将 Ollama 直接添加到
|
||||
`openclaw onboard` 和模型选择器中。有关新手引导、云端 / 本地模式及自定义配置，
|
||||
请参见 [/providers/ollama](/zh-CN/providers/ollama)。
|
||||
|
||||
### vLLM
|
||||
|
||||
vLLM 作为内置提供商插件提供，用于本地/自托管的 OpenAI 兼容
|
||||
vLLM 以内置提供商插件形式提供，用于本地 / 自托管的 OpenAI 兼容
|
||||
服务器：
|
||||
|
||||
- 提供商：`vllm`
|
||||
- 身份验证：可选（取决于你的服务器）
|
||||
- 认证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:8000/v1`
|
||||
|
||||
要在本地选择启用自动发现（如果你的服务器不强制要求身份验证，任意值都可用）：
|
||||
要选择启用本地自动发现（如果你的服务器不强制要求认证，任意值都可以）：
|
||||
|
||||
```bash
|
||||
export VLLM_API_KEY="vllm-local"
|
||||
```
|
||||
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 Id）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -529,21 +527,21 @@ export VLLM_API_KEY="vllm-local"
|
||||
|
||||
### SGLang
|
||||
|
||||
SGLang 作为内置提供商插件提供，用于快速自托管的
|
||||
SGLang 以内置提供商插件形式提供，用于快速的自托管
|
||||
OpenAI 兼容服务器：
|
||||
|
||||
- 提供商：`sglang`
|
||||
- 身份验证：可选（取决于你的服务器）
|
||||
- 认证：可选（取决于你的服务器）
|
||||
- 默认基础 URL：`http://127.0.0.1:30000/v1`
|
||||
|
||||
要在本地选择启用自动发现（如果你的服务器不
|
||||
强制要求身份验证，任意值都可用）：
|
||||
要选择启用本地自动发现（如果你的服务器不
|
||||
强制要求认证，任意值都可以）：
|
||||
|
||||
```bash
|
||||
export SGLANG_API_KEY="sglang-local"
|
||||
```
|
||||
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 ID）：
|
||||
然后设置一个模型（替换为 `/v1/models` 返回的某个 Id）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -564,7 +562,7 @@ export SGLANG_API_KEY="sglang-local"
|
||||
agents: {
|
||||
defaults: {
|
||||
model: { primary: "lmstudio/my-local-model" },
|
||||
models: { "lmstudio/my-local-model": { alias: "本地" } },
|
||||
models: { "lmstudio/my-local-model": { alias: "Local" } },
|
||||
},
|
||||
},
|
||||
models: {
|
||||
@ -576,7 +574,7 @@ export SGLANG_API_KEY="sglang-local"
|
||||
models: [
|
||||
{
|
||||
id: "my-local-model",
|
||||
name: "本地模型",
|
||||
name: "Local Model",
|
||||
reasoning: false,
|
||||
input: ["text"],
|
||||
cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
|
||||
@ -590,23 +588,23 @@ export SGLANG_API_KEY="sglang-local"
|
||||
}
|
||||
```
|
||||
|
||||
说明：
|
||||
注意：
|
||||
|
||||
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选项。
|
||||
省略时，OpenClaw 默认值为：
|
||||
- 对于自定义提供商，`reasoning`、`input`、`cost`、`contextWindow` 和 `maxTokens` 都是可选的。
|
||||
省略时，OpenClaw 默认使用：
|
||||
- `reasoning: false`
|
||||
- `input: ["text"]`
|
||||
- `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }`
|
||||
- `contextWindow: 200000`
|
||||
- `maxTokens: 8192`
|
||||
- 建议：设置与你的代理/模型限制相匹配的显式值。
|
||||
- 对于非原生端点上的 `api: "openai-completions"`（任何非空 `baseUrl` 且其 host 不是 `api.openai.com`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
|
||||
- 代理风格的 OpenAI 兼容路由也会跳过仅限原生 OpenAI 的请求
|
||||
整形：没有 `service_tier`，没有 Responses `store`，没有 prompt-cache 提示，没有
|
||||
OpenAI reasoning 兼容负载整形，也没有隐藏的 OpenClaw 归因
|
||||
请求头。
|
||||
- 如果 `baseUrl` 为空/省略，OpenClaw 会保留默认 OpenAI 行为（会解析到 `api.openai.com`）。
|
||||
- 出于安全考虑，即使显式设置了 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。
|
||||
- 建议：设置与你的代理 / 模型限制匹配的显式值。
|
||||
- 对于非原生端点上的 `api: "openai-completions"`（任何主机不是 `api.openai.com` 的非空 `baseUrl`），OpenClaw 会强制设置 `compat.supportsDeveloperRole: false`，以避免提供商因不支持 `developer` 角色而返回 400 错误。
|
||||
- 代理式 OpenAI 兼容路由也会跳过仅适用于原生 OpenAI 的请求
|
||||
整形：不使用 `service_tier`，不使用 Responses `store`，不使用 prompt-cache 提示，不使用
|
||||
OpenAI reasoning 兼容载荷整形，也不附加隐藏的 OpenClaw 归因
|
||||
头。
|
||||
- 如果 `baseUrl` 为空 / 省略，OpenClaw 会保留默认的 OpenAI 行为（会解析到 `api.openai.com`）。
|
||||
- 出于安全考虑，即使显式设置 `compat.supportsDeveloperRole: true`，在非原生 `openai-completions` 端点上仍会被覆盖。
|
||||
|
||||
## CLI 示例
|
||||
|
||||
@ -616,11 +614,11 @@ openclaw models set opencode/claude-opus-4-6
|
||||
openclaw models list
|
||||
```
|
||||
|
||||
另请参见：[/gateway/configuration](/zh-CN/gateway/configuration) 获取完整配置示例。
|
||||
另请参见：[/gateway/configuration](/zh-CN/gateway/configuration)，获取完整配置示例。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [模型](/zh-CN/concepts/models) — 模型配置和别名
|
||||
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链和重试行为
|
||||
- [模型故障切换](/zh-CN/concepts/model-failover) — 回退链和重试行为
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键
|
||||
- [提供商](/zh-CN/providers) — 按提供商分类的设置指南
|
||||
- [提供商](/zh-CN/providers) — 按提供商划分的设置指南
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
read_when:
|
||||
- 添加或修改模型 CLI（`models list`/`set`/`scan`/`aliases`/`fallbacks`）
|
||||
- 添加或修改模型 CLI（`models list/set/scan/aliases/fallbacks`）
|
||||
- 更改模型回退行为或选择 UX
|
||||
- 更新模型扫描探测项（工具/图像）
|
||||
summary: 模型 CLI：列表、设置、别名、回退、扫描、状态
|
||||
title: 模型 CLI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T06:24:04Z"
|
||||
generated_at: "2026-04-23T19:23:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 46916d9600a4e4aebdb026aa42df39149d8b6d438a8a7e85a61053dfc8f76dcc
|
||||
source_hash: 45ee320df8d49171261cd0a5d42e1c0c39d7ea77d16fd7895ef15b1195d81fb4
|
||||
source_path: concepts/models.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 模型 CLI
|
||||
|
||||
有关凭证配置轮换、冷却时间，以及它们如何与回退机制交互，请参见 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
|
||||
提供商快速概览 + 示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。
|
||||
关于凭证配置轮换、冷却时间以及它们如何与回退机制交互，请参阅 [/concepts/model-failover](/zh-CN/concepts/model-failover)。
|
||||
提供商快速概览与示例：[/concepts/model-providers](/zh-CN/concepts/model-providers)。
|
||||
|
||||
## 模型选择的工作方式
|
||||
|
||||
@ -25,23 +25,23 @@ OpenClaw 按以下顺序选择模型：
|
||||
|
||||
1. **主模型**（`agents.defaults.model.primary` 或 `agents.defaults.model`）。
|
||||
2. `agents.defaults.model.fallbacks` 中的**回退模型**（按顺序）。
|
||||
3. **提供商凭证故障转移**会在单个提供商内部发生，然后才会移动到下一个模型。
|
||||
3. **提供商凭证回退**会在同一提供商内部发生，然后才会切换到下一个模型。
|
||||
|
||||
相关项：
|
||||
|
||||
- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（包含别名）。
|
||||
- `agents.defaults.imageModel` **仅在**主模型无法接收图像时使用。
|
||||
- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到解析后的会话/默认模型。
|
||||
- `agents.defaults.imageGenerationModel` 用于共享图像生成功能。如果省略，`image_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
|
||||
- `agents.defaults.musicGenerationModel` 用于共享音乐生成功能。如果省略，`music_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
|
||||
- `agents.defaults.videoGenerationModel` 用于共享视频生成功能。如果省略，`video_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
|
||||
- 每个智能体的默认值可通过 `agents.list[].model` 加绑定来覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。
|
||||
- `agents.defaults.models` 是 OpenClaw 可使用模型的允许列表/目录（以及别名）。
|
||||
- `agents.defaults.imageModel` **仅在**主模型无法接受图像时使用。
|
||||
- `agents.defaults.pdfModel` 由 `pdf` 工具使用。如果省略，该工具会回退到 `agents.defaults.imageModel`，然后回退到已解析的会话/默认模型。
|
||||
- `agents.defaults.imageGenerationModel` 用于共享的图像生成能力。如果省略，`image_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的图像生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
|
||||
- `agents.defaults.musicGenerationModel` 用于共享的音乐生成能力。如果省略，`music_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的音乐生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
|
||||
- `agents.defaults.videoGenerationModel` 用于共享的视频生成能力。如果省略，`video_generate` 仍可推断出一个由凭证支持的提供商默认值。它会先尝试当前默认提供商，然后按提供商 ID 顺序尝试其余已注册的视频生成提供商。如果你设置了特定的提供商/模型，也请配置该提供商的凭证/API 密钥。
|
||||
- 每个智能体的默认值可通过 `agents.list[].model` 加上绑定覆盖 `agents.defaults.model`（参见 [/concepts/multi-agent](/zh-CN/concepts/multi-agent)）。
|
||||
|
||||
## 快速模型策略
|
||||
|
||||
- 将你的主模型设置为你可用的、最新一代中最强的模型。
|
||||
- 对成本/延迟敏感的任务和风险较低的聊天，使用回退模型。
|
||||
- 对启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
|
||||
- 将你的主模型设置为你可用的、能力最强的最新一代模型。
|
||||
- 对于成本/延迟敏感的任务和风险较低的聊天，使用回退模型。
|
||||
- 对于启用了工具的智能体或不受信任的输入，避免使用较旧/较弱的模型层级。
|
||||
|
||||
## 新手引导（推荐）
|
||||
|
||||
@ -51,7 +51,7 @@ OpenClaw 按以下顺序选择模型：
|
||||
openclaw onboard
|
||||
```
|
||||
|
||||
它可以为常见提供商设置模型 + 凭证，包括 **OpenAI Code (Codex) subscription**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。
|
||||
它可以为常见提供商设置模型和凭证，包括 **OpenAI Code (Codex) subscription**（OAuth）和 **Anthropic**（API 密钥或 Claude CLI）。
|
||||
|
||||
## 配置键名（概览）
|
||||
|
||||
@ -63,38 +63,38 @@ openclaw onboard
|
||||
- `agents.defaults.models`（允许列表 + 别名 + 提供商参数）
|
||||
- `models.providers`（写入 `models.json` 的自定义提供商）
|
||||
|
||||
模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会规范化为 `zai/*`。
|
||||
模型引用会被规范化为小写。像 `z.ai/*` 这样的提供商别名会被规范化为 `zai/*`。
|
||||
|
||||
提供商配置示例（包括 OpenCode）位于
|
||||
[/providers/opencode](/zh-CN/providers/opencode)。
|
||||
|
||||
### 安全地编辑允许列表
|
||||
|
||||
手动更新 `agents.defaults.models` 时，请使用追加式写入：
|
||||
手动更新 `agents.defaults.models` 时，请使用增量写入：
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.models '{"openai-codex/gpt-5.4":{}}' --strict-json --merge
|
||||
openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge
|
||||
```
|
||||
|
||||
`openclaw config set` 会保护模型/提供商映射，防止意外覆盖。当对 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 执行普通对象赋值且会移除现有条目时，此操作会被拒绝。对于追加式更改，请使用 `--merge`；仅当提供的值应成为完整目标值时，才使用 `--replace`。
|
||||
`openclaw config set` 会保护模型/提供商映射，防止被意外覆盖。对 `agents.defaults.models`、`models.providers` 或 `models.providers.<id>.models` 进行普通对象赋值时，如果会移除现有条目，就会被拒绝。新增变更请使用 `--merge`；仅当提供的值应成为完整目标值时，才使用 `--replace`。
|
||||
|
||||
交互式提供商设置和 `openclaw configure --section model` 也会将提供商作用域内的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商时，不会丢弃无关的模型条目。
|
||||
交互式提供商设置和 `openclaw configure --section model` 也会将按提供商划分的选择合并到现有允许列表中，因此添加 Codex、Ollama 或其他提供商时，不会丢失无关的模型条目。
|
||||
|
||||
## “Model is not allowed”（以及为什么回复会停止）
|
||||
|
||||
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择了不在该允许列表中的模型时，OpenClaw 会返回：
|
||||
如果设置了 `agents.defaults.models`，它就会成为 `/model` 和会话覆盖的**允许列表**。当用户选择的模型不在该允许列表中时，OpenClaw 会返回：
|
||||
|
||||
```
|
||||
Model "provider/model" is not allowed. Use /model to list available models.
|
||||
```
|
||||
|
||||
这发生在生成正常回复**之前**，因此消息会让人感觉像是“没有响应”。修复方式如下：
|
||||
这会在生成正常回复**之前**发生，因此这条消息可能让人感觉它“没有响应”。解决方法是以下任一项：
|
||||
|
||||
- 将该模型添加到 `agents.defaults.models`，或
|
||||
- 清空允许列表（删除 `agents.defaults.models`），或
|
||||
- 清除允许列表（移除 `agents.defaults.models`），或
|
||||
- 从 `/model list` 中选择一个模型。
|
||||
|
||||
允许列表配置示例：
|
||||
允许列表示例配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -110,36 +110,36 @@ Model "provider/model" is not allowed. Use /model to list available models.
|
||||
|
||||
## 在聊天中切换模型（`/model`）
|
||||
|
||||
你可以在不重启的情况下为当前会话切换模型：
|
||||
你可以在不重启的情况下切换当前会话的模型：
|
||||
|
||||
```text
|
||||
```
|
||||
/model
|
||||
/model list
|
||||
/model 3
|
||||
/model openai/gpt-5.4
|
||||
/model openai/gpt-5.5
|
||||
/model status
|
||||
```
|
||||
|
||||
说明：
|
||||
|
||||
- `/model`（以及 `/model list`）是一个紧凑的编号选择器（模型家族 + 可用提供商）。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉菜单，以及一个提交步骤。
|
||||
- `/models add` 默认可用，可通过 `commands.modelsWrite=false` 禁用。
|
||||
- 启用后，`/models add <provider> <modelId>` 是最快路径；单独输入 `/models add` 会在支持时启动一个按提供商优先的引导流程。
|
||||
- 执行 `/models add` 后，新模型无需重启 Gateway 网关，就会在 `/models` 和 `/model` 中可用。
|
||||
- `/model <#>` 会从该选择器中进行选择。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉框，以及一个提交步骤。
|
||||
- 默认提供 `/models add`，可通过 `commands.modelsWrite=false` 禁用。
|
||||
- 启用后，`/models add <provider> <modelId>` 是最快路径；而不带参数的 `/models add` 会在支持的情况下启动“先选提供商”的引导流程。
|
||||
- 执行 `/models add` 后，新模型无需重启 Gateway 网关，即可在 `/models` 和 `/model` 中使用。
|
||||
- `/model <#>` 会从该选择器中选取。
|
||||
- `/model` 会立即持久化新的会话选择。
|
||||
- 如果智能体处于空闲状态，下一次运行会立即使用新模型。
|
||||
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点重启并切换到新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续的重试机会或下一次用户回合。
|
||||
- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` + `api` 模式）。
|
||||
- 模型引用通过在**第一个** `/` 处分割来解析。输入 `/model <ref>` 时请使用 `provider/model`。
|
||||
- 如果模型 ID 本身包含 `/`（OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。
|
||||
- 如果你省略了提供商，OpenClaw 会按以下顺序解析输入：
|
||||
- 如果智能体空闲，下一次运行会立即使用新模型。
|
||||
- 如果某次运行已经在进行中，OpenClaw 会将实时切换标记为待处理，并只会在一个干净的重试点重启到新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理的切换可能会一直排队到稍后的重试机会，或直到下一轮用户输入。
|
||||
- `/model status` 是详细视图（凭证候选项，以及在已配置时显示提供商端点 `baseUrl` 和 `api` 模式）。
|
||||
- 模型引用通过按**第一个** `/` 分割来解析。输入 `/model <ref>` 时，请使用 `provider/model`。
|
||||
- 如果模型 ID 本身包含 `/`（例如 OpenRouter 风格），你必须包含提供商前缀（示例：`/model openrouter/moonshotai/kimi-k2`）。
|
||||
- 如果你省略提供商，OpenClaw 会按以下顺序解析输入：
|
||||
1. 别名匹配
|
||||
2. 对该确切未加前缀模型 ID 的唯一已配置提供商匹配
|
||||
3. 已弃用的回退：使用已配置的默认提供商
|
||||
如果该提供商不再公开已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露一个陈旧、已移除提供商的默认值。
|
||||
2. 对该精确无前缀模型 ID 的唯一已配置提供商匹配
|
||||
3. 已弃用的回退：回退到已配置的默认提供商
|
||||
如果该提供商不再提供已配置的默认模型，OpenClaw 会改为回退到第一个已配置的提供商/模型，以避免暴露过时的、已移除提供商默认值。
|
||||
|
||||
完整命令行为/配置： [Slash commands](/zh-CN/tools/slash-commands)。
|
||||
|
||||
@ -186,18 +186,18 @@ openclaw models image-fallbacks clear
|
||||
- `--plain`：每行一个模型
|
||||
- `--json`：机器可读输出
|
||||
|
||||
`--all` 会在配置凭证之前包含内置的、由提供商拥有的静态目录行，因此仅发现视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。
|
||||
`--all` 会在配置凭证之前，先包含由内置提供商拥有的静态目录行，因此仅用于发现的视图也可以显示那些在你添加匹配提供商凭证之前不可用的模型。
|
||||
|
||||
### `models status`
|
||||
|
||||
显示解析后的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示在凭证存储中找到的配置文件的 OAuth 到期状态（默认在 24 小时内到期时警告）。`--plain` 仅打印解析后的主模型。
|
||||
OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果已配置的提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。
|
||||
JSON 包含 `auth.oauth`（警告窗口 + 配置文件）和 `auth.providers`（每个提供商的实际凭证，包括基于环境变量的凭证）。`auth.oauth` 仅表示凭证存储中的配置文件健康状态；仅通过环境变量提供凭证的提供商不会出现在其中。
|
||||
对自动化使用 `--check`（缺失/过期时退出码为 `1`，即将过期时为 `2`）。
|
||||
使用 `--probe` 进行实时凭证检查；探测行可能来自凭证配置文件、环境变量凭证或 `models.json`。
|
||||
如果显式的 `auth.order.<provider>` 省略了某个已存储配置文件，则探测会报告 `excluded_by_auth_order`，而不是尝试它。如果凭证存在，但无法为该提供商解析出可探测的模型，则探测会报告 `status: no_model`。
|
||||
显示已解析的主模型、回退模型、图像模型，以及已配置提供商的凭证概览。它还会显示认证存储中凭证配置的 OAuth 过期状态（默认会在 24 小时内过期时发出警告）。`--plain` 仅打印已解析的主模型。
|
||||
OAuth 状态始终会显示（并包含在 `--json` 输出中）。如果某个已配置的提供商没有凭证，`models status` 会打印一个 **Missing auth** 部分。
|
||||
JSON 包含 `auth.oauth`（警告窗口 + 配置）和 `auth.providers`（每个提供商的有效凭证，包括基于环境变量的凭证）。`auth.oauth` 仅表示认证存储中配置的健康状态；仅使用环境变量的提供商不会出现在其中。
|
||||
对自动化场景使用 `--check`（缺失/已过期时退出码为 `1`，即将过期时为 `2`）。
|
||||
对实时凭证检查使用 `--probe`；探测行可能来自凭证配置、环境变量凭证或 `models.json`。
|
||||
如果显式的 `auth.order.<provider>` 省略了某个已存储配置，探测会报告 `excluded_by_auth_order`，而不是尝试它。如果存在凭证，但无法为该提供商解析出可探测的模型，探测会报告 `status: no_model`。
|
||||
|
||||
凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的；也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置文件。
|
||||
凭证选择取决于提供商/账户。对于始终在线的 Gateway 网关主机，API 密钥通常是最可预测的；同时也支持复用 Claude CLI 以及现有的 Anthropic OAuth/token 配置。
|
||||
|
||||
示例（Claude CLI）：
|
||||
|
||||
@ -208,20 +208,20 @@ openclaw models status
|
||||
|
||||
## 扫描（OpenRouter 免费模型）
|
||||
|
||||
`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型的工具和图像支持。
|
||||
`openclaw models scan` 会检查 OpenRouter 的**免费模型目录**，并可选择探测模型是否支持工具和图像。
|
||||
|
||||
关键标志：
|
||||
|
||||
- `--no-probe`：跳过实时探测（仅元数据）
|
||||
- `--min-params <b>`：最小参数规模（十亿）
|
||||
- `--max-age-days <days>`：跳过较旧模型
|
||||
- `--max-age-days <days>`：跳过较旧的模型
|
||||
- `--provider <name>`：提供商前缀过滤
|
||||
- `--max-candidates <n>`：回退列表大小
|
||||
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选择项
|
||||
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选择项
|
||||
- `--set-default`：将 `agents.defaults.model.primary` 设置为第一个选中的项
|
||||
- `--set-image`：将 `agents.defaults.imageModel.primary` 设置为第一个图像选中的项
|
||||
|
||||
探测需要 OpenRouter API 密钥（来自凭证配置文件或
|
||||
`OPENROUTER_API_KEY`）。如果没有密钥，请使用 `--no-probe` 仅列出候选项。
|
||||
探测需要 OpenRouter API 密钥（来自凭证配置或 `OPENROUTER_API_KEY`）。
|
||||
如果没有密钥，请使用 `--no-probe` 仅列出候选项。
|
||||
|
||||
扫描结果按以下规则排序：
|
||||
|
||||
@ -233,33 +233,33 @@ openclaw models status
|
||||
输入
|
||||
|
||||
- OpenRouter `/models` 列表（过滤 `:free`）
|
||||
- 需要来自凭证配置文件或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)）
|
||||
- 需要来自凭证配置或 `OPENROUTER_API_KEY` 的 OpenRouter API 密钥（参见 [/environment](/zh-CN/help/environment)）
|
||||
- 可选过滤器：`--max-age-days`、`--min-params`、`--provider`、`--max-candidates`
|
||||
- 探测控制：`--timeout`、`--concurrency`
|
||||
|
||||
在 TTY 中运行时，你可以交互式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。
|
||||
在 TTY 中运行时，你可以以交互方式选择回退模型。在非交互模式下，传入 `--yes` 以接受默认值。
|
||||
|
||||
## 模型注册表（`models.json`）
|
||||
|
||||
`models.providers` 中的自定义提供商会写入智能体目录下的 `models.json`（默认 `~/.openclaw/agents/<agentId>/agent/models.json`）。默认情况下会合并该文件，除非将 `models.mode` 设置为 `replace`。
|
||||
`models.providers` 中的自定义提供商会被写入智能体目录下的 `models.json`（默认路径为 `~/.openclaw/agents/<agentId>/agent/models.json`）。除非将 `models.mode` 设置为 `replace`，否则默认会合并此文件。
|
||||
|
||||
匹配提供商 ID 的合并模式优先级：
|
||||
|
||||
- 智能体 `models.json` 中已存在的非空 `baseUrl` 优先。
|
||||
- 智能体 `models.json` 中非空的 `apiKey` 仅在该提供商在当前配置/凭证配置文件上下文中**不**受 SecretRef 管理时优先。
|
||||
- 受 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。
|
||||
- 受 SecretRef 管理的提供商 header 值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。
|
||||
- 智能体 `models.json` 中的非空 `apiKey` 仅在该提供商在当前配置/凭证配置上下文中**不是**由 SecretRef 管理时优先。
|
||||
- 由 SecretRef 管理的提供商 `apiKey` 值会从源标记刷新（环境变量引用使用 `ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`），而不是持久化已解析的密钥。
|
||||
- 由 SecretRef 管理的提供商请求头值会从源标记刷新（环境变量引用使用 `secretref-env:ENV_VAR_NAME`，文件/exec 引用使用 `secretref-managed`）。
|
||||
- 空的或缺失的智能体 `apiKey`/`baseUrl` 会回退到配置中的 `models.providers`。
|
||||
- 其他提供商字段会从配置和规范化后的目录数据中刷新。
|
||||
|
||||
标记持久化以源为权威：OpenClaw 会根据当前源配置快照（预解析），而不是根据运行时已解析的密钥值来写入标记。
|
||||
只要 OpenClaw 重新生成 `models.json`，这条规则就适用，包括像 `openclaw agent` 这样的命令驱动路径。
|
||||
标记持久化以源为准：OpenClaw 从当前活动源配置快照（解析前）写入标记，而不是从运行时已解析的密钥值写入。
|
||||
这适用于 OpenClaw 重新生成 `models.json` 的所有情况，包括诸如 `openclaw agent` 这样的命令驱动路径。
|
||||
|
||||
## 相关
|
||||
## 相关内容
|
||||
|
||||
- [模型提供商](/zh-CN/concepts/model-providers) — 提供商路由和凭证
|
||||
- [模型故障转移](/zh-CN/concepts/model-failover) — 回退链
|
||||
- [图像生成](/zh-CN/tools/image-generation) — 图像模型配置
|
||||
- [音乐生成](/zh-CN/tools/music-generation) — 音乐模型配置
|
||||
- [视频生成](/zh-CN/tools/video-generation) — 视频模型配置
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — 模型配置键名
|
||||
- [模型提供商](/zh-CN/concepts/model-providers) —— 提供商路由和凭证
|
||||
- [模型回退](/zh-CN/concepts/model-failover) —— 回退链
|
||||
- [图像生成](/zh-CN/tools/image-generation) —— 图像模型配置
|
||||
- [音乐生成](/zh-CN/tools/music-generation) —— 音乐模型配置
|
||||
- [视频生成](/zh-CN/tools/video-generation) —— 视频模型配置
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) —— 模型配置键名
|
||||
|
||||
@ -2,42 +2,42 @@
|
||||
read_when:
|
||||
- 扩展 qa-lab 或 qa-channel
|
||||
- 添加由仓库支持的 QA 场景
|
||||
- 围绕 Gateway 网关仪表板构建更高拟真度的 QA 自动化
|
||||
summary: qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态
|
||||
- 围绕 Gateway 网关仪表板构建更高真实性的 QA 自动化
|
||||
summary: 面向 qa-lab、qa-channel、种子场景和协议报告的私有 QA 自动化形态
|
||||
title: QA 端到端自动化
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T09:05:04Z"
|
||||
generated_at: "2026-04-23T19:23:50Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a967a74d2e70b042e9443c5ec954902b820d2e5a22cbecd9be74af13b9085553
|
||||
source_hash: baecad15e244cb927cac6489eb9f59531a8f56dd0ea7d47bd4dad463984cc9f3
|
||||
source_path: concepts/qa-e2e-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# QA 端到端自动化
|
||||
|
||||
私有 QA 栈旨在以比单个单元测试更贴近真实、具备渠道形态的方式来验证 OpenClaw。
|
||||
私有 QA 栈旨在以比单个单元测试更贴近真实、更加符合渠道形态的方式来验证 OpenClaw。
|
||||
|
||||
当前组成部分：
|
||||
当前包含的组成部分：
|
||||
|
||||
- `extensions/qa-channel`：合成消息渠道，包含私信、渠道、线程、表情回应、编辑和删除等交互面。
|
||||
- `extensions/qa-channel`：合成消息渠道，提供私信、渠道、线程、反应、编辑和删除等表面能力。
|
||||
- `extensions/qa-lab`：调试器 UI 和 QA 总线，用于观察转录内容、注入入站消息，以及导出 Markdown 报告。
|
||||
- `qa/`：由仓库支持的启动任务种子资源和基线 QA 场景。
|
||||
|
||||
当前 QA 操作流程是一个双栏 QA 站点：
|
||||
当前的 QA 操作流程是一个双窗格 QA 站点：
|
||||
|
||||
- 左侧：带有智能体的 Gateway 网关仪表板（控制 UI）。
|
||||
- 右侧：QA Lab，显示类似 Slack 的转录和场景计划。
|
||||
- 左侧：带有智能体的 Gateway 网关仪表板（Control UI）。
|
||||
- 右侧：QA Lab，显示类似 Slack 的转录内容和场景计划。
|
||||
|
||||
运行方式：
|
||||
使用以下命令运行：
|
||||
|
||||
```bash
|
||||
pnpm qa:lab:up
|
||||
```
|
||||
|
||||
这会构建 QA 站点、启动基于 Docker 的 gateway 测试通道，并暴露 QA Lab 页面，供操作员或自动化循环向智能体下达 QA 任务、观察真实渠道行为，并记录哪些内容成功了、失败了，或仍然受阻。
|
||||
这会构建 QA 站点，启动由 Docker 支持的 Gateway 网关通道，并暴露 QA Lab 页面，操作员或自动化循环可以在其中给智能体分配一个 QA 任务、观察真实渠道行为，并记录哪些内容有效、哪些失败了，或哪些仍然受阻。
|
||||
|
||||
如果你想更快迭代 QA Lab UI，而不必每次都重建 Docker 镜像，可以使用绑定挂载的 QA Lab bundle 启动该栈：
|
||||
如果你想在不每次都重建 Docker 镜像的情况下更快迭代 QA Lab UI，请使用绑定挂载的 QA Lab bundle 启动此栈：
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa docker-build-image
|
||||
@ -46,48 +46,48 @@ pnpm qa:lab:up:fast
|
||||
pnpm qa:lab:watch
|
||||
```
|
||||
|
||||
`qa:lab:up:fast` 会让 Docker 服务保持在预构建镜像上运行，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该 bundle，当 QA Lab 资源哈希发生变化时，浏览器会自动重新加载。
|
||||
`qa:lab:up:fast` 会让 Docker 服务保持在一个预构建镜像上，并将 `extensions/qa-lab/web/dist` 绑定挂载到 `qa-lab` 容器中。`qa:lab:watch` 会在变更时重建该 bundle，当 QA Lab 资源哈希变化时，浏览器会自动重新加载。
|
||||
|
||||
若要运行一个基于真实传输层的 Matrix 冒烟测试通道，请执行：
|
||||
若要运行一个传输层真实的 Matrix 冒烟通道，请执行：
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa matrix
|
||||
```
|
||||
|
||||
该通道会在 Docker 中配置一个一次性的 Tuwunel homeserver，注册临时的驱动、SUT 和观察者用户，创建一个私有房间，然后在 QA gateway 子进程中运行真实的 Matrix 插件。实时传输通道会将子进程配置限定在被测试的传输协议上，因此 Matrix 会在子进程配置中不包含 `qa-channel` 的情况下运行。它会将结构化报告产物以及合并后的 stdout/stderr 日志写入所选的 Matrix QA 输出目录。若还要捕获外层 `scripts/run-node.mjs` 的构建/启动输出，请将 `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` 设置为仓库本地日志文件。
|
||||
该通道会在 Docker 中配置一个一次性的 Tuwunel homeserver，注册临时的 driver、SUT 和 observer 用户，创建一个私有房间，然后在一个 QA Gateway 网关子进程中运行真实的 Matrix 插件。实时传输通道会将子进程配置限制在被测传输协议范围内，因此 Matrix 会在子进程配置中不包含 `qa-channel` 的情况下运行。它会将结构化报告产物以及合并后的 stdout/stderr 日志写入所选的 Matrix QA 输出目录。若还要捕获外层 `scripts/run-node.mjs` 的构建/启动器输出，请将 `OPENCLAW_RUN_NODE_OUTPUT_LOG=<path>` 设置为一个位于仓库内的日志文件。
|
||||
|
||||
若要运行一个基于真实传输层的 Telegram 冒烟测试通道，请执行：
|
||||
若要运行一个传输层真实的 Telegram 冒烟通道，请执行：
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa telegram
|
||||
```
|
||||
|
||||
该通道会使用一个真实的私有 Telegram 群组，而不是配置一次性服务器。它要求提供 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`，并要求两个不同的 bot 位于同一个私有群组中。SUT bot 必须具有 Telegram 用户名；如果两个 bot 都在 `@BotFather` 中启用了 Bot-to-Bot Communication Mode，则 bot 对 bot 的观察效果最佳。
|
||||
当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不以失败退出码结束，请使用 `--allow-failures`。
|
||||
Telegram 报告和摘要还会包含每次回复的 RTT，从驱动消息发送请求开始，到观察到 SUT 回复为止，金丝雀场景也包括在内。
|
||||
该通道会面向一个真实的私有 Telegram 群组，而不是配置一个一次性服务器。它需要 `OPENCLAW_QA_TELEGRAM_GROUP_ID`、`OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` 和 `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`，并且要求同一个私有群组中有两个不同的机器人。SUT 机器人必须具有一个 Telegram 用户名，并且当两个机器人都在 `@BotFather` 中启用了 Bot-to-Bot Communication Mode 时，机器人之间的观察效果最佳。
|
||||
当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不希望退出码失败，请使用 `--allow-failures`。
|
||||
Telegram 报告和摘要包含每次回复的 RTT，从 driver 消息发送请求到观测到的 SUT 回复进行计时，从 canary 开始。
|
||||
|
||||
实时传输通道现在共享一个更小的契约，而不是各自设计自己的场景列表结构：
|
||||
实时传输通道现在共享一个更小的统一契约，而不是各自发明自己的场景列表形态：
|
||||
|
||||
`qa-channel` 仍然是更广泛的合成产品行为套件，不属于实时传输覆盖矩阵的一部分。
|
||||
`qa-channel` 仍然是覆盖面广泛的合成产品行为套件，不属于实时传输覆盖矩阵的一部分。
|
||||
|
||||
| 通道 | 金丝雀 | 提及门控 | 白名单拦截 | 顶层回复 | 重启恢复 | 线程后续回复 | 线程隔离 | 表情回应观察 | 帮助命令 |
|
||||
| ---- | ------ | -------- | ---------- | -------- | -------- | ------------ | -------- | ------------ | -------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
| 通道 | Canary | 提及门控 | 允许列表阻止 | 顶层回复 | 重启恢复 | 线程后续跟进 | 线程隔离 | 反应观察 | 帮助命令 |
|
||||
| ---- | ------ | -------- | ------------ | -------- | -------- | ------------ | -------- | -------- | -------- |
|
||||
| Matrix | x | x | x | x | x | x | x | x | |
|
||||
| Telegram | x | | | | | | | | x |
|
||||
|
||||
这样可以让 `qa-channel` 继续作为广泛的产品行为套件，而 Matrix、Telegram 以及未来的实时传输协议共享一份显式的传输契约检查清单。
|
||||
这使 `qa-channel` 继续作为覆盖面广泛的产品行为套件，而 Matrix、Telegram 以及未来的实时传输协议则共享一份明确的传输契约检查清单。
|
||||
|
||||
若要运行一个一次性的 Linux VM 通道，而不将 Docker 纳入 QA 路径，请执行：
|
||||
若要运行一个无需将 Docker 引入 QA 路径的一次性 Linux VM 通道，请执行：
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
```
|
||||
|
||||
这会启动一个全新的 Multipass guest，在 guest 内安装依赖、构建 OpenClaw、运行 `qa suite`，然后将常规 QA 报告和摘要复制回主机上的 `.artifacts/qa-e2e/...`。
|
||||
它会复用与主机上 `qa suite` 相同的场景选择行为。
|
||||
主机和 Multipass 的 suite 运行默认都会并行执行多个选中的场景，并使用隔离的 gateway worker。`qa-channel` 默认并发度为 4，但不会超过所选场景数量。使用 `--concurrency <count>` 可调整 worker 数量，或使用 `--concurrency 1` 进行串行执行。
|
||||
当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不以失败退出码结束，请使用 `--allow-failures`。
|
||||
实时运行会转发适合 guest 使用的受支持 QA 认证输入：基于环境变量的提供商密钥、QA 实时提供商配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便 guest 可以通过挂载的工作区写回内容。
|
||||
这会启动一个全新的 Multipass guest，在 guest 中安装依赖、构建 OpenClaw、运行 `qa suite`，然后将常规 QA 报告和摘要复制回宿主机上的 `.artifacts/qa-e2e/...`。
|
||||
它会复用与宿主机上 `qa suite` 相同的场景选择行为。
|
||||
宿主机和 Multipass 套件运行默认都会以多个隔离的 Gateway 网关工作进程并行执行多个被选中的场景。`qa-channel` 默认并发数为 4，并受所选场景数量限制。使用 `--concurrency <count>` 可调整工作进程数量，或使用 `--concurrency 1` 进行串行执行。
|
||||
当任一场景失败时，该命令会以非零状态退出。如果你想保留产物但不希望退出码失败，请使用 `--allow-failures`。
|
||||
实时运行会转发适合 guest 使用的受支持 QA 凭证输入：基于 env 的提供商密钥、QA 实时 provider 配置路径，以及存在时的 `CODEX_HOME`。请将 `--output-dir` 保持在仓库根目录下，以便 guest 能通过挂载的工作区回写内容。
|
||||
|
||||
## 由仓库支持的种子资源
|
||||
|
||||
@ -96,70 +96,72 @@ pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline
|
||||
- `qa/scenarios/index.md`
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
|
||||
这些文件有意保存在 git 中，以便 QA 计划对人类和智能体都可见。
|
||||
这些内容特意保存在 git 中，以便 QA 计划对人类和智能体都可见。
|
||||
|
||||
`qa-lab` 应保持为一个通用 Markdown 运行器。每个场景 Markdown 文件都是一次测试运行的事实来源，并应定义：
|
||||
`qa-lab` 应保持为一个通用的 Markdown 运行器。每个场景 Markdown 文件都是一次测试运行的事实来源，并且应定义以下内容：
|
||||
|
||||
- 场景元数据
|
||||
- 可选的分类、能力、通道和风险元数据
|
||||
- 文档和代码引用
|
||||
- 可选的 category、capability、lane 和 risk 元数据
|
||||
- docs 和 code 引用
|
||||
- 可选的插件要求
|
||||
- 可选的 Gateway 网关配置补丁
|
||||
- 可执行的 `qa-flow`
|
||||
|
||||
支撑 `qa-flow` 的可复用运行时表面可以保持通用且跨领域。例如，Markdown 场景可以组合传输侧辅助工具与浏览器侧辅助工具，通过 Gateway 网关 `browser.request` 接缝驱动嵌入式控制 UI，而无需添加特例运行器。
|
||||
支撑 `qa-flow` 的可复用运行时表面允许保持通用和跨领域。例如，Markdown 场景可以将传输侧辅助工具与浏览器侧辅助工具结合起来，通过 Gateway 网关 `browser.request` 接缝驱动嵌入式 Control UI，而无需添加特殊情况运行器。
|
||||
|
||||
场景文件应按产品能力分组，而不是按源码树文件夹分组。即使文件移动，也要保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 来实现实现层面的可追溯性。
|
||||
场景文件应按产品能力分组，而不是按源代码树文件夹分组。文件移动时请保持场景 ID 稳定；使用 `docsRefs` 和 `codeRefs` 进行实现可追溯性标注。
|
||||
|
||||
基线列表应足够广泛，以覆盖：
|
||||
基线列表应保持足够广泛，以覆盖：
|
||||
|
||||
- 私信和渠道聊天
|
||||
- 线程行为
|
||||
- 消息动作生命周期
|
||||
- 消息操作生命周期
|
||||
- cron 回调
|
||||
- 记忆召回
|
||||
- 模型切换
|
||||
- 子智能体交接
|
||||
- 读取仓库和读取文档
|
||||
- 仓库读取和文档读取
|
||||
- 一个小型构建任务，例如 Lobster Invaders
|
||||
|
||||
## 提供商 mock 通道
|
||||
## provider 模拟通道
|
||||
|
||||
`qa suite` 具有两个本地提供商 mock 通道：
|
||||
`qa suite` 有两个本地 provider 模拟通道：
|
||||
|
||||
- `mock-openai` 是具备场景感知能力的 OpenClaw mock。它仍然是由仓库支持的 QA 和一致性验证的默认确定性 mock 通道。
|
||||
- `aimock` 会启动一个由 AIMock 支持的提供商服务器，用于实验性协议、夹具、录制/回放和混沌测试覆盖。它是增量补充，不会替代 `mock-openai` 场景分发器。
|
||||
- `mock-openai` 是具备场景感知能力的 OpenClaw 模拟器。它仍然是由仓库支持的 QA 和一致性门禁的默认确定性模拟通道。
|
||||
- `aimock` 会启动一个由 AIMock 支持的 provider 服务器，用于实验性协议、夹具、录制/回放和混沌覆盖。它是附加能力，不会替代 `mock-openai` 场景分发器。
|
||||
|
||||
提供商通道实现位于 `extensions/qa-lab/src/providers/` 下。每个提供商都负责自己的默认值、本地服务器启动、gateway 模型配置、auth-profile 暂存需求，以及 live/mock 能力标志。共享 suite 和 gateway 代码应通过提供商注册表进行路由，而不是根据提供商名称分支。
|
||||
provider 通道实现位于 `extensions/qa-lab/src/providers/` 下。
|
||||
每个 provider 负责自己的默认值、本地服务器启动、Gateway 网关模型配置、auth profile 暂存需求，以及实时/模拟能力标记。共享的 suite 和 Gateway 网关代码应通过 provider 注册表进行路由，而不是根据 provider 名称分支。
|
||||
|
||||
## 传输适配器
|
||||
|
||||
`qa-lab` 为 Markdown QA 场景提供一个通用传输接缝。
|
||||
`qa-channel` 是该接缝上的第一个适配器，但设计目标更广：未来无论是真实渠道还是合成渠道，都应接入同一个 suite 运行器，而不是新增特定于传输协议的 QA 运行器。
|
||||
`qa-lab` 拥有一个用于 Markdown QA 场景的通用传输接缝。
|
||||
`qa-channel` 是该接缝上的第一个适配器，但设计目标更广：未来的真实或合成渠道应接入同一个 suite 运行器，而不是添加一个特定于传输协议的 QA 运行器。
|
||||
|
||||
在架构层面，划分如下：
|
||||
从架构层面看，拆分如下：
|
||||
|
||||
- `qa-lab` 负责通用场景执行、worker 并发、产物写入和报告生成。
|
||||
- 传输适配器负责 gateway 配置、就绪性、入站和出站观察、传输动作以及标准化的传输状态。
|
||||
- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行它们的可复用运行时表面。
|
||||
- `qa-lab` 负责通用场景执行、工作进程并发、产物写入和报告。
|
||||
- 传输适配器负责 Gateway 网关配置、就绪状态、入站和出站观察、传输动作以及标准化的传输状态。
|
||||
- `qa/scenarios/` 下的 Markdown 场景文件定义测试运行；`qa-lab` 提供执行这些场景的可复用运行时表面。
|
||||
|
||||
面向维护者的新渠道适配器接入指南位于 [测试](/zh-CN/help/testing#adding-a-channel-to-qa)。
|
||||
面向维护者的新渠道适配器接入指南位于
|
||||
[测试](/zh-CN/help/testing#adding-a-channel-to-qa)。
|
||||
|
||||
## 报告
|
||||
|
||||
`qa-lab` 会根据观察到的总线时间线导出 Markdown 协议报告。
|
||||
`qa-lab` 会基于观测到的总线时间线导出一份 Markdown 协议报告。
|
||||
该报告应回答：
|
||||
|
||||
- 哪些内容成功了
|
||||
- 哪些内容失败了
|
||||
- 哪些内容有效
|
||||
- 哪些内容失败
|
||||
- 哪些内容仍然受阻
|
||||
- 值得补充哪些后续场景
|
||||
- 值得添加哪些后续场景
|
||||
|
||||
对于角色和风格检查，可让同一场景在多个实时模型引用上运行，并输出一份经评审的 Markdown 报告：
|
||||
对于角色和风格检查，请在多个实时模型引用上运行同一个场景，并写出一份经评审的 Markdown 报告：
|
||||
|
||||
```bash
|
||||
pnpm openclaw qa character-eval \
|
||||
--model openai/gpt-5.4,thinking=xhigh \
|
||||
--model openai/gpt-5.5,thinking=xhigh \
|
||||
--model openai/gpt-5.2,thinking=xhigh \
|
||||
--model openai/gpt-5,thinking=xhigh \
|
||||
--model anthropic/claude-opus-4-6,thinking=high \
|
||||
@ -167,20 +169,26 @@ pnpm openclaw qa character-eval \
|
||||
--model zai/glm-5.1,thinking=high \
|
||||
--model moonshot/kimi-k2.5,thinking=high \
|
||||
--model google/gemini-3.1-pro-preview,thinking=high \
|
||||
--judge-model openai/gpt-5.4,thinking=xhigh,fast \
|
||||
--judge-model openai/gpt-5.5,thinking=xhigh,fast \
|
||||
--judge-model anthropic/claude-opus-4-6,thinking=high \
|
||||
--blind-judge-models \
|
||||
--concurrency 16 \
|
||||
--judge-concurrency 16
|
||||
```
|
||||
|
||||
该命令运行的是本地 QA gateway 子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置 persona，然后运行普通用户轮次，例如聊天、工作区帮助和小型文件任务。候选模型不应被告知自己正在接受评估。该命令会保留每份完整转录、记录基础运行统计信息，然后让评审模型以 fast 模式和 `xhigh` 推理来按自然度、氛围和幽默感对这些运行进行排序。
|
||||
在比较不同提供商时，请使用 `--blind-judge-models`：评审提示仍会收到每份转录和运行状态，但候选引用会被替换为 `candidate-01` 之类的中性标签；在解析完成后，报告会将排序结果映射回真实引用。
|
||||
候选运行默认使用 `high` thinking，而支持的 OpenAI 模型默认使用 `xhigh`。你可以用 `--model provider/model,thinking=<level>` 为特定候选单独覆盖。`--thinking <level>` 仍可设置全局后备值，而旧的 `--model-thinking <provider/model=level>` 形式也会为了兼容性而保留。
|
||||
OpenAI 候选引用默认使用 fast 模式，以便在提供商支持时使用优先处理。若某个候选或评审需要覆盖，请内联添加 `,fast`、`,no-fast` 或 `,fast=false`。只有当你想为所有候选模型强制启用 fast 模式时，才传递 `--fast`。报告中会记录候选和评审的耗时，以供基准分析，但评审提示会明确说明不要根据速度进行排序。
|
||||
候选和评审模型运行的默认并发度都是 16。如果提供商限制或本地 gateway 压力导致运行噪声过大，请降低 `--concurrency` 或 `--judge-concurrency`。
|
||||
当未传递候选 `--model` 时，角色评估默认使用 `openai/gpt-5.4`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、`moonshot/kimi-k2.5` 和 `google/gemini-3.1-pro-preview`。
|
||||
当未传递 `--judge-model` 时，评审默认使用 `openai/gpt-5.4,thinking=xhigh,fast` 和 `anthropic/claude-opus-4-6,thinking=high`。
|
||||
该命令运行的是本地 QA Gateway 网关子进程，而不是 Docker。角色评估场景应通过 `SOUL.md` 设置 persona，然后运行普通用户轮次，例如聊天、工作区帮助和小型文件任务。候选模型不应被告知自己正在接受评估。该命令会保留每一份完整转录，记录基本运行统计信息，然后以快速模式和 `xhigh` 推理让评审模型按自然度、氛围和幽默感对这些运行进行排序。
|
||||
在比较不同 provider 时，请使用 `--blind-judge-models`：评审提示仍会获得每份转录和运行状态，但候选引用会被替换为诸如 `candidate-01` 之类的中性标签；报告会在解析后将排名映射回真实引用。
|
||||
候选运行默认使用 `high` thinking，对于支持它的 OpenAI 模型则使用 `xhigh`。可通过 `--model provider/model,thinking=<level>` 内联覆盖某个特定候选项。`--thinking <level>` 仍会设置全局后备值，而较旧的 `--model-thinking <provider/model=level>` 形式也会为兼容性保留。
|
||||
OpenAI 候选引用默认使用快速模式，以便在 provider 支持时使用优先处理。若单个候选项或评审项需要覆盖，请内联添加 `,fast`、`,no-fast` 或 `,fast=false`。仅当你希望对每个候选模型都强制启用快速模式时，才传入 `--fast`。候选和评审时长都会记录在报告中用于基准分析，但评审提示会明确说明不要按速度排序。
|
||||
候选模型和评审模型运行的默认并发数都是 16。当 provider 限制或本地 Gateway 网关压力使运行噪声过大时，请降低 `--concurrency` 或 `--judge-concurrency`。
|
||||
当未传入候选 `--model` 时，角色评估默认使用
|
||||
`openai/gpt-5.5`、`openai/gpt-5.2`、`openai/gpt-5`、`anthropic/claude-opus-4-6`、
|
||||
`anthropic/claude-sonnet-4-6`、`zai/glm-5.1`、
|
||||
`moonshot/kimi-k2.5` 和
|
||||
`google/gemini-3.1-pro-preview`。
|
||||
当未传入 `--judge-model` 时，评审默认使用
|
||||
`openai/gpt-5.5,thinking=xhigh,fast` 和
|
||||
`anthropic/claude-opus-4-6,thinking=high`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
|
||||
@ -1,41 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- 当 API 提供商失败时，你希望有一个可靠的回退方案
|
||||
- 当 API 提供商失效时，你希望有一个可靠的回退方案
|
||||
- 你正在运行 Codex CLI 或其他本地 AI CLI，并希望复用它们
|
||||
- 你想了解用于 CLI 后端工具访问的 MCP loopback 桥接机制
|
||||
summary: CLI 后端：本地 AI CLI 回退机制，可选 MCP 工具桥接
|
||||
- 你想了解用于 CLI 后端工具访问的 MCP loopback 桥接器
|
||||
summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退方案
|
||||
title: CLI 后端
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T14:54:03Z"
|
||||
generated_at: "2026-04-23T19:23:51Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ff7458d18b8a5b716930579241177917fd3edffcf7f6e211c7d570cf76519316
|
||||
source_hash: 3709769c7fd88be1c455001d77472848f1b65a8aac499c6c35b063c4faa1cbfb
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# CLI 后端（回退运行时）
|
||||
|
||||
当 API 提供商不可用、触发速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI**作为**纯文本回退**。这项设计刻意保持保守：
|
||||
当 API 提供商不可用、遭遇速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退方案**。这一设计刻意保持保守：
|
||||
|
||||
- **OpenClaw 工具不会被直接注入**，但带有 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。
|
||||
- 对支持该能力的 CLI 提供 **JSONL 流式传输**。
|
||||
- **支持会话**（因此后续轮次可以保持连贯）。
|
||||
- **不会直接注入 OpenClaw 工具**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。
|
||||
- 为支持的 CLI 提供 **JSONL 流式传输**。
|
||||
- **支持会话**（因此后续轮次能够保持连贯）。
|
||||
- 如果 CLI 接受图片路径，**图片也可以透传**。
|
||||
|
||||
这被设计为一种**安全兜底机制**，而不是主路径。当你想要“不依赖外部 API 也始终可用”的文本响应时，可以使用它。
|
||||
它的定位是一个**安全兜底机制**，而不是主要路径。当你希望获得“不管怎样都能工作”的文本回复，而不依赖外部 API 时，可以使用它。
|
||||
|
||||
如果你需要具备 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
|
||||
如果你需要带有 ACP 会话控制、后台任务、线程/对话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
|
||||
|
||||
## 面向初学者的快速开始
|
||||
|
||||
你可以**无需任何配置**使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）：
|
||||
你可以**无需任何配置**使用 Codex CLI（内置 OpenAI 插件会注册一个默认后端）：
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.4
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
```
|
||||
|
||||
如果你的 Gateway 网关运行在 launchd/systemd 下且 `PATH` 很精简，只需添加命令路径：
|
||||
如果你的 Gateway 网关运行在 launchd/systemd 下且 PATH 很精简，只需添加命令路径：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -51,13 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
|
||||
}
|
||||
```
|
||||
|
||||
就是这样。除了 CLI 自身之外，不需要密钥，也不需要额外的认证配置。
|
||||
就是这样。除了 CLI 本身所需的配置外，不需要密钥，也不需要额外的认证配置。
|
||||
|
||||
如果你在 Gateway 网关主机上把某个内置 CLI 后端用作**主要消息提供商**，当你的配置在模型引用中或在 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。
|
||||
如果你将某个内置 CLI 后端作为 Gateway 网关主机上的**主要消息提供商**使用，当你的配置在模型引用或 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。
|
||||
|
||||
## 将它用作回退
|
||||
## 将其用作回退方案
|
||||
|
||||
将 CLI 后端加入你的回退列表，这样它只会在主模型失败时运行：
|
||||
将 CLI 后端添加到你的回退列表中，这样它只会在主模型失败时运行：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -65,11 +65,11 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "anthropic/claude-opus-4-6",
|
||||
fallbacks: ["codex-cli/gpt-5.4"],
|
||||
fallbacks: ["codex-cli/gpt-5.5"],
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": { alias: "Opus" },
|
||||
"codex-cli/gpt-5.4": {},
|
||||
"codex-cli/gpt-5.5": {},
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -78,8 +78,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
|
||||
|
||||
说明：
|
||||
|
||||
- 如果你使用 `agents.defaults.models`（允许列表），也必须把你的 CLI 后端模型包含进去。
|
||||
- 如果主提供商失败（认证、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。
|
||||
- 如果你使用 `agents.defaults.models`（允许列表），你也必须在其中包含 CLI 后端模型。
|
||||
- 如果主提供商失败（认证、速率限制、超时），OpenClaw 接下来会尝试 CLI 后端。
|
||||
|
||||
## 配置概览
|
||||
|
||||
@ -89,8 +89,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.4
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
每个条目都以一个**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。
|
||||
这个提供商 id 会成为你的模型引用左侧部分：
|
||||
每个条目都以**提供商 id** 作为键（例如 `codex-cli`、`my-cli`）。
|
||||
该提供商 id 会成为你的模型引用左侧部分：
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -120,7 +120,7 @@ agents.defaults.cliBackends
|
||||
sessionMode: "existing",
|
||||
sessionIdFields: ["session_id", "conversation_id"],
|
||||
systemPromptArg: "--system",
|
||||
// 对于 Codex 风格的 CLI，也可以改为指向一个提示文件：
|
||||
// 对于 Codex 风格的 CLI，也可以改为指向提示词文件：
|
||||
// systemPromptFileConfigArg: "-c",
|
||||
// systemPromptFileConfigKey: "model_instructions_file",
|
||||
systemPromptWhen: "first",
|
||||
@ -138,21 +138,22 @@ agents.defaults.cliBackends
|
||||
|
||||
1. 根据提供商前缀（`codex-cli/...`）**选择后端**。
|
||||
2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。
|
||||
3. 使用会话 id（如果支持）**执行 CLI**，以保持历史一致。
|
||||
3. 使用会话 id（如果支持）**执行 CLI**，从而保持历史一致。
|
||||
内置的 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活，并通过 stream-json stdin 发送后续轮次。
|
||||
4. **解析输出**（JSON 或纯文本）并返回最终文本。
|
||||
5. 按后端**持久化会话 id**，以便后续轮次复用同一个 CLI 会话。
|
||||
5. 按后端**持久化会话 id**，这样后续轮次可以复用同一个 CLI 会话。
|
||||
|
||||
<Note>
|
||||
内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，再次允许 OpenClaw 风格的 Claude CLI 用法，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将这种用于该集成的 `claude -p` 用法视为已获认可。
|
||||
内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 工作人员告诉我们，再次允许 OpenClaw 风格的 Claude CLI 用法，因此除非 Anthropic 发布新的政策，否则 OpenClaw 将 `claude -p` 用法视为该集成的已认可方式。
|
||||
</Note>
|
||||
|
||||
内置的 OpenAI `codex-cli` 后端会通过 Codex 的 `model_instructions_file` 配置覆盖项（`-c
|
||||
model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 并未提供 Claude 风格的 `--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装后的提示词写入临时文件。
|
||||
model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 的
|
||||
`--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装后的提示词写入临时文件。
|
||||
|
||||
内置的 Anthropic `claude-cli` 后端以两种方式接收 OpenClaw Skills 快照：一种是追加系统提示词中的精简 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件只包含对当前智能体/会话有资格使用的 Skills，因此 Claude Code 的原生 skill 解析器看到的过滤后集合，与 OpenClaw 原本会在提示词中公布的集合相同。Skills 的 env/API 密钥覆盖仍然由 OpenClaw 应用于本次运行的子进程环境。
|
||||
内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw 的 Skills 快照：其一是附加系统提示词中的精简 OpenClaw Skills 目录，其二是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件只包含对该智能体/会话符合条件的 Skills，因此 Claude Code 的原生 Skills 解析器看到的就是与 OpenClaw 原本会在提示词中公布的同一组过滤结果。对于运行过程中的 Skill 环境变量/API 密钥覆盖，仍由 OpenClaw 应用到子进程环境中。
|
||||
|
||||
在 OpenClaw 能使用内置 `claude-cli` 后端之前，Claude Code 本身必须已经在同一主机上完成登录：
|
||||
在 OpenClaw 能使用内置 `claude-cli` 后端之前，Claude Code 本身必须已经在同一台主机上登录：
|
||||
|
||||
```bash
|
||||
claude auth login
|
||||
@ -160,27 +161,28 @@ claude auth status --text
|
||||
openclaw models auth login --provider anthropic --method cli --set-default
|
||||
```
|
||||
|
||||
只有当 `claude` 二进制文件不在 `PATH` 上时，才使用 `agents.defaults.cliBackends.claude-cli.command`。
|
||||
只有当 `claude` 二进制文件不在 `PATH` 中时，才需要使用 `agents.defaults.cliBackends.claude-cli.command`。
|
||||
|
||||
## 会话
|
||||
|
||||
- 如果 CLI 支持会话，设置 `sessionArg`（例如 `--session-id`）或
|
||||
`sessionArgs`（占位符 `{sessionId}`），用于需要将该 id 插入多个标志的情况。
|
||||
- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或
|
||||
`sessionArgs`（占位符为 `{sessionId}`），适用于需要将 ID 插入多个标志的情况。
|
||||
- 如果 CLI 使用带有不同标志的**恢复子命令**，请设置
|
||||
`resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`
|
||||
（用于非 JSON 恢复）。
|
||||
`resumeArgs`（恢复时替换 `args`），并可选择设置 `resumeOutput`
|
||||
（用于非 JSON 的恢复输出）。
|
||||
- `sessionMode`：
|
||||
- `always`：始终发送会话 id（如果未存储则生成新的 UUID）。
|
||||
- `existing`：只有先前已存储时才发送会话 id。
|
||||
- `existing`：只有之前已存储会话 id 时才发送。
|
||||
- `none`：永不发送会话 id。
|
||||
- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"` 和 `input: "stdin"`，因此只要进程仍然活跃，后续轮次就会复用这个活动中的 Claude 进程。现在默认就是 warm stdio，包括那些省略传输字段的自定义配置。如果 Gateway 网关重启，或空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。在恢复前，已存储的会话 id 会先与现有且可读的项目转录记录进行校验，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下悄悄启动一个新的 Claude CLI 会话。
|
||||
- 已存储的 CLI 会话属于提供商拥有的连续性。隐式的每日会话重置不会切断它们；`/reset` 和显式的 `session.reset` 策略仍然会切断。
|
||||
- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"`，
|
||||
以及 `input: "stdin"`，这样在 Claude 进程仍处于活动状态时，后续轮次就能复用该实时 Claude 进程。现在默认就是预热的 stdio，包括那些省略传输字段的自定义配置。如果 Gateway 网关重启或空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。已存储的会话 id 会先针对现有且可读取的项目转录记录进行验证，之后才会恢复，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下悄悄启动一个全新的 Claude CLI 会话。
|
||||
- 已存储的 CLI 会话属于提供商连续性的一部分。隐式的每日会话重置不会切断它们；但 `/reset` 和显式的 `session.reset` 策略仍然会切断。
|
||||
|
||||
序列化说明：
|
||||
|
||||
- `serialize: true` 会保持同一 lane 中的运行顺序。
|
||||
- 大多数 CLI 会在一个提供商 lane 上串行化。
|
||||
- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，包括认证配置文件 id 变化、静态 API 密钥变化、静态令牌变化，或当 CLI 暴露该信息时 OAuth 账户身份变化。OAuth 访问令牌和刷新令牌轮换不会切断已存储的 CLI 会话。如果某个 CLI 没有暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行决定恢复权限。
|
||||
- `serialize: true` 会保持同一执行通道中的运行按顺序进行。
|
||||
- 大多数 CLI 都会在一个提供商通道上串行执行。
|
||||
- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，这包括认证配置文件 id、静态 API 密钥、静态令牌，或 CLI 暴露出的 OAuth 账户身份发生变化。OAuth 访问令牌和刷新令牌轮换不会切断已存储的 CLI 会话。如果某个 CLI 没有暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。
|
||||
|
||||
## 图片（透传）
|
||||
|
||||
@ -191,24 +193,24 @@ imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会把文件路径追加到提示词中（路径注入）；对于那些能从普通路径自动加载本地文件的 CLI，这已经足够。
|
||||
OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会将文件路径附加到提示词中（路径注入），这对于那些能够从普通路径自动加载本地文件的 CLI 已经足够。
|
||||
|
||||
## 输入 / 输出
|
||||
|
||||
- `output: "json"`（默认）会尝试解析 JSON 并提取文本与会话 id。
|
||||
- `output: "json"`（默认）会尝试解析 JSON 并提取文本和会话 id。
|
||||
- 对于 Gemini CLI 的 JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。
|
||||
- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及存在时的会话标识符。
|
||||
- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及其中存在的会话标识符。
|
||||
- `output: "text"` 会将 stdout 视为最终响应。
|
||||
|
||||
输入模式：
|
||||
|
||||
- `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传递。
|
||||
- `input: "arg"`（默认）会将提示词作为最后一个 CLI 参数传入。
|
||||
- `input: "stdin"` 会通过 stdin 发送提示词。
|
||||
- 如果提示词很长且设置了 `maxPromptArgChars`，则会改用 stdin。
|
||||
|
||||
## 默认值（插件拥有）
|
||||
## 默认值（插件所属）
|
||||
|
||||
内置的 OpenAI 插件也为 `codex-cli` 注册了一个默认值：
|
||||
内置的 OpenAI 插件也为 `codex-cli` 注册了一个默认配置：
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
|
||||
@ -219,7 +221,7 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，
|
||||
- `imageArg: "--image"`
|
||||
- `sessionMode: "existing"`
|
||||
|
||||
内置的 Google 插件也为 `google-gemini-cli` 注册了一个默认值：
|
||||
内置的 Google 插件也为 `google-gemini-cli` 注册了一个默认配置：
|
||||
|
||||
- `command: "gemini"`
|
||||
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
|
||||
@ -230,30 +232,30 @@ OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，
|
||||
- `sessionMode: "existing"`
|
||||
- `sessionIdFields: ["session_id", "sessionId"]`
|
||||
|
||||
前提条件：本地 Gemini CLI 必须已安装，并且可通过 `PATH` 中的
|
||||
前提条件：本地 Gemini CLI 必须已经安装，并且可在 `PATH` 中作为
|
||||
`gemini` 使用（`brew install gemini-cli` 或
|
||||
`npm install -g @google/gemini-cli`）。
|
||||
|
||||
Gemini CLI JSON 说明：
|
||||
|
||||
- 回复文本从 JSON 的 `response` 字段读取。
|
||||
- 当 `usage` 缺失或为空时，用量会回退到 `stats`。
|
||||
- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
|
||||
- 如果 `stats.input` 缺失，OpenClaw 会通过
|
||||
- 当 `usage` 不存在或为空时，用量会回退到 `stats`。
|
||||
- `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。
|
||||
- 如果缺少 `stats.input`，OpenClaw 会根据
|
||||
`stats.input_tokens - stats.cached` 推导输入 token 数。
|
||||
|
||||
只有在需要时才覆盖这些默认值（常见情况：使用绝对 `command` 路径）。
|
||||
仅在必要时覆盖（常见情况：使用绝对 `command` 路径）。
|
||||
|
||||
## 插件拥有的默认值
|
||||
## 插件所属默认值
|
||||
|
||||
CLI 后端默认值现在属于插件表面的一部分：
|
||||
CLI 后端默认值现在已成为插件表面的一部分：
|
||||
|
||||
- 插件使用 `api.registerCliBackend(...)` 注册它们。
|
||||
- 插件通过 `api.registerCliBackend(...)` 注册它们。
|
||||
- 后端 `id` 会成为模型引用中的提供商前缀。
|
||||
- 用户在 `agents.defaults.cliBackends.<id>` 中的配置仍然会覆盖插件默认值。
|
||||
- 后端特定的配置清理仍由插件通过可选的 `normalizeConfig` hook 负责。
|
||||
- 位于 `agents.defaults.cliBackends.<id>` 下的用户配置仍会覆盖插件默认值。
|
||||
- 通过可选的 `normalizeConfig` 钩子，后端特定的配置清理逻辑仍归插件所有。
|
||||
|
||||
需要微小提示词/消息兼容性 shim 的插件，可以声明双向文本转换，而无需替换某个提供商或 CLI 后端：
|
||||
需要细小提示词/消息兼容性垫片的插件，可以声明双向文本转换，而无需替换提供商或 CLI 后端：
|
||||
|
||||
```typescript
|
||||
api.registerTextTransforms({
|
||||
@ -270,43 +272,45 @@ api.registerTextTransforms({
|
||||
});
|
||||
```
|
||||
|
||||
`input` 会重写传给 CLI 的系统提示词和用户提示词。`output` 会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式传输的 assistant 增量以及解析后的最终文本。
|
||||
`input` 会重写传递给 CLI 的系统提示词和用户提示词。`output`
|
||||
会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式传输的助手增量内容以及解析后的最终文本。
|
||||
|
||||
对于输出 Claude Code stream-json 兼容 JSONL 的 CLI，请在该后端配置上设置
|
||||
对于输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置上设置
|
||||
`jsonlDialect: "claude-stream-json"`。
|
||||
|
||||
## Bundle MCP 覆盖层
|
||||
|
||||
CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择加入一个生成的 MCP 配置覆盖层。
|
||||
CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置 `bundleMcp: true` 选择启用生成的 MCP 配置覆盖层。
|
||||
|
||||
当前内置行为：
|
||||
|
||||
- `claude-cli`：生成严格的 MCP 配置文件
|
||||
- `claude-cli`：生成严格 MCP 配置文件
|
||||
- `codex-cli`：为 `mcp_servers` 提供内联配置覆盖
|
||||
- `google-gemini-cli`：生成 Gemini 系统设置文件
|
||||
|
||||
启用 bundle MCP 后，OpenClaw 会：
|
||||
|
||||
- 启动一个 loopback HTTP MCP 服务器，向 CLI 进程暴露 Gateway 网关工具
|
||||
- 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程
|
||||
- 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证
|
||||
- 将工具访问范围限定在当前会话、账户和渠道上下文中
|
||||
- 将工具访问范围限定在当前会话、账户和渠道上下文内
|
||||
- 为当前工作区加载已启用的 bundle-MCP 服务器
|
||||
- 将它们与现有的后端 MCP 配置/设置结构合并
|
||||
- 使用所属扩展中由后端拥有的集成模式重写启动配置
|
||||
- 将它们与任何现有的后端 MCP 配置/设置结构合并
|
||||
- 使用所属扩展定义的集成模式重写启动配置
|
||||
|
||||
如果没有启用任何 MCP 服务器，当某个后端选择加入 bundle MCP 时，OpenClaw 仍会注入严格配置，以确保后台运行保持隔离。
|
||||
如果没有启用任何 MCP 服务器，当某个后端选择启用 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。
|
||||
|
||||
## 限制
|
||||
|
||||
- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到 CLI 后端协议中。后端只有在选择加入 `bundleMcp: true` 时，才会看到 Gateway 网关工具。
|
||||
- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；另一些则会缓冲到退出时才输出。
|
||||
- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到
|
||||
CLI 后端协议中。只有当后端选择启用 `bundleMcp: true` 时，它们才会看到 Gateway 网关工具。
|
||||
- **流式传输是后端特定的。** 有些后端会流式输出 JSONL；另一些则会缓冲直到退出。
|
||||
- **结构化输出** 取决于 CLI 的 JSON 格式。
|
||||
- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），其结构化程度低于初始的 `--json` 运行。不过 OpenClaw 会话本身仍可正常工作。
|
||||
- **Codex CLI 会话** 通过文本输出恢复（不是 JSONL），因此其结构化程度低于初始的 `--json` 运行。不过 OpenClaw 会话仍会正常工作。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- **找不到 CLI**：将 `command` 设置为完整路径。
|
||||
- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
|
||||
- **没有会话连续性**：确保已设置 `sessionArg`，并且 `sessionMode` 不是
|
||||
`none`（Codex CLI 当前无法使用 JSON 输出进行恢复）。
|
||||
- **没有会话连续性**：确保已设置 `sessionArg`，且 `sessionMode` 不是
|
||||
`none`（Codex CLI 目前无法使用 JSON 输出进行恢复）。
|
||||
- **图片被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。
|
||||
|
||||
@ -3,24 +3,24 @@ read_when:
|
||||
- 学习如何配置 OpenClaw
|
||||
- 查找配置示例
|
||||
- 首次设置 OpenClaw
|
||||
summary: 适用于常见 OpenClaw 设置、与 schema 精确对齐的配置示例
|
||||
summary: 适用于常见 OpenClaw 设置的符合 schema 的准确配置示例
|
||||
title: 配置示例
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:23:29Z"
|
||||
generated_at: "2026-04-23T19:24:17Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 1c85643b02285cefa2aaa9dd7c1e3abebb505bc8b415b5153b5899efc3ade0f7
|
||||
source_hash: 9b5f280003776000a24ab6f9174fcd85f3b159e58c9f22923c6c6ab9143682fb
|
||||
source_path: gateway/configuration-examples.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 配置示例
|
||||
|
||||
以下示例与当前配置 schema 保持一致。完整参考和各字段说明，请参见[Configuration](/gateway/configuration)。
|
||||
以下示例与当前配置 schema 保持一致。若需完整参考和逐字段说明，请参见 [Configuration](/zh-CN/gateway/configuration)。
|
||||
|
||||
## 快速开始
|
||||
|
||||
### 绝对最小配置
|
||||
### 最小配置
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -29,9 +29,9 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
保存到 `~/.openclaw/openclaw.json`，然后你就可以用这个号码给机器人发送私信。
|
||||
保存到 `~/.openclaw/openclaw.json`，然后你就可以从该号码向机器人发送私信。
|
||||
|
||||
### 推荐入门配置
|
||||
### 推荐起步配置
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -55,7 +55,7 @@ x-i18n:
|
||||
|
||||
## 扩展示例（主要选项）
|
||||
|
||||
> JSON5 允许你使用注释和尾随逗号。普通 JSON 也可以。
|
||||
> JSON5 允许使用注释和尾随逗号。普通 JSON 也可以。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -71,7 +71,7 @@ x-i18n:
|
||||
},
|
||||
},
|
||||
|
||||
// Auth 配置文件元数据（秘密存储在 auth-profiles.json 中）
|
||||
// 认证配置档元数据（密钥存放在 auth-profiles.json 中）
|
||||
auth: {
|
||||
profiles: {
|
||||
"anthropic:default": { provider: "anthropic", mode: "api_key" },
|
||||
@ -141,7 +141,7 @@ x-i18n:
|
||||
maxBytes: 20971520,
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-4o-mini-transcribe" },
|
||||
// 可选 CLI 回退（Whisper 二进制）：
|
||||
// 可选的 CLI 回退（Whisper 二进制）：
|
||||
// { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
|
||||
],
|
||||
timeoutSeconds: 120,
|
||||
@ -243,7 +243,7 @@ x-i18n:
|
||||
userTimezone: "America/Chicago",
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-6",
|
||||
fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.4"],
|
||||
fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.5"],
|
||||
},
|
||||
imageModel: {
|
||||
primary: "openrouter/anthropic/claude-sonnet-4-6",
|
||||
@ -251,9 +251,9 @@ x-i18n:
|
||||
models: {
|
||||
"anthropic/claude-opus-4-6": { alias: "opus" },
|
||||
"anthropic/claude-sonnet-4-6": { alias: "sonnet" },
|
||||
"openai/gpt-5.4": { alias: "gpt" },
|
||||
"openai/gpt-5.5": { alias: "gpt" },
|
||||
},
|
||||
skills: ["github", "weather"], // 会被未设置 list[].skills 的智能体继承
|
||||
skills: ["github", "weather"], // 被未设置 list[].skills 的智能体继承
|
||||
thinkingDefault: "low",
|
||||
verboseDefault: "off",
|
||||
elevatedDefault: "on",
|
||||
@ -293,7 +293,7 @@ x-i18n:
|
||||
},
|
||||
sandbox: {
|
||||
mode: "non-main",
|
||||
scope: "session", // 相较于旧版 perSession: true，更推荐
|
||||
scope: "session", // 优先于旧版 perSession: true
|
||||
workspaceRoot: "~/.openclaw/sandboxes",
|
||||
docker: {
|
||||
image: "openclaw-sandbox:bookworm-slim",
|
||||
@ -313,14 +313,14 @@ x-i18n:
|
||||
id: "main",
|
||||
default: true,
|
||||
// 继承 defaults.skills -> github, weather
|
||||
thinkingDefault: "high", // 按智能体覆盖 thinking
|
||||
reasoningDefault: "on", // 按智能体设置 reasoning 可见性
|
||||
fastModeDefault: false, // 按智能体设置快速模式
|
||||
thinkingDefault: "high", // 每个智能体的 thinking 覆盖
|
||||
reasoningDefault: "on", // 每个智能体的推理可见性
|
||||
fastModeDefault: false, // 每个智能体的快速模式
|
||||
},
|
||||
{
|
||||
id: "quick",
|
||||
skills: [], // 这个智能体不使用任何 Skills
|
||||
fastModeDefault: true, // 这个智能体始终快速运行
|
||||
fastModeDefault: true, // 这个智能体始终以快速模式运行
|
||||
thinkingDefault: "off",
|
||||
},
|
||||
],
|
||||
@ -374,7 +374,7 @@ x-i18n:
|
||||
},
|
||||
},
|
||||
|
||||
// Cron 任务
|
||||
// Cron 作业
|
||||
cron: {
|
||||
enabled: true,
|
||||
store: "~/.openclaw/cron/cron.json",
|
||||
@ -468,7 +468,7 @@ x-i18n:
|
||||
|
||||
## 常见模式
|
||||
|
||||
### 共享 Skill 基线与单项覆盖
|
||||
### 共享 Skills 基线并覆盖一个智能体
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -486,8 +486,8 @@ x-i18n:
|
||||
```
|
||||
|
||||
- `agents.defaults.skills` 是共享基线。
|
||||
- `agents.list[].skills` 会为单个智能体替换这套基线。
|
||||
- 如果某个智能体不应看到任何 Skills，请使用 `skills: []`。
|
||||
- `agents.list[].skills` 会替换某个智能体的这份基线。
|
||||
- 当某个智能体不应看到任何 Skills 时，请使用 `skills: []`。
|
||||
|
||||
### 多平台设置
|
||||
|
||||
@ -512,7 +512,7 @@ x-i18n:
|
||||
|
||||
### 安全私信模式（共享收件箱 / 多用户私信）
|
||||
|
||||
如果有多个人可以给你的机器人发私信（`allowFrom` 中有多个条目、为多个人批准了 pairing，或 `dmPolicy: "open"`），请启用**安全私信模式**，这样不同发送者的私信默认不会共享同一个上下文：
|
||||
如果有多个人可以向你的机器人发送私信（`allowFrom` 中有多个条目、为多个人批准了配对，或使用 `dmPolicy: "open"`），请启用 **安全私信模式**，这样不同发送者发来的私信默认不会共享同一个上下文：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -536,10 +536,10 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
对于 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，默认优先按发送者 ID 进行授权。
|
||||
只有在你明确接受这种风险的情况下，才启用各渠道中的 `dangerouslyAllowNameMatching: true`，以允许直接使用可变的名称/邮箱/昵称进行匹配。
|
||||
对于 Discord/Slack/Google Chat/Microsoft Teams/Mattermost/IRC，发送者授权默认优先基于 ID。
|
||||
只有在你明确接受该风险时，才通过各渠道的 `dangerouslyAllowNameMatching: true` 启用基于可变名称/邮箱/昵称的直接匹配。
|
||||
|
||||
### Anthropic API key + MiniMax 回退
|
||||
### Anthropic API 密钥 + MiniMax 回退
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -598,7 +598,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### 仅本地模型
|
||||
### 仅使用本地模型
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -633,6 +633,6 @@ x-i18n:
|
||||
## 提示
|
||||
|
||||
- 如果你设置了 `dmPolicy: "open"`，对应的 `allowFrom` 列表必须包含 `"*"`。
|
||||
- provider ID 的格式各不相同（电话号码、用户 ID、渠道 ID）。请参阅 provider 文档确认格式。
|
||||
- 之后可以再添加的可选部分：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
|
||||
- 更深入的设置说明请参见 [Providers](/providers) 和 [故障排除](/gateway/troubleshooting)。
|
||||
- 提供商 ID 各不相同（电话号码、用户 ID、渠道 ID）。请查阅提供商文档以确认格式。
|
||||
- 之后可以添加的可选部分包括：`web`、`browser`、`ui`、`discovery`、`canvasHost`、`talk`、`signal`、`imessage`。
|
||||
- 更深入的设置说明请参见 [Providers](/zh-CN/providers) 和 [故障排除](/zh-CN/gateway/troubleshooting)。
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -3,35 +3,32 @@ read_when:
|
||||
- 首次设置 OpenClaw
|
||||
- 查找常见配置模式
|
||||
- 导航到特定配置部分
|
||||
summary: 配置概览：常见任务、快速设置，以及指向完整参考的链接
|
||||
summary: 配置概览：常见任务、快速设置与完整参考链接
|
||||
title: 配置
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T08:25:19Z"
|
||||
generated_at: "2026-04-23T19:24:37Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: d76b40c25f98de791e0d8012b2bc5b80e3e38dde99bb9105539e800ddac3f362
|
||||
source_hash: e21161b8b05cf2963d935646bc9b8fe3e3de514cefee71c837566a4090538df2
|
||||
source_path: gateway/configuration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 配置
|
||||
|
||||
OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
|
||||
当前使用的配置路径必须是一个常规文件。对于 OpenClaw 自身发起的写入操作，
|
||||
不支持使用符号链接形式的 `openclaw.json` 布局；原子写入可能会替换该路径，
|
||||
而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将
|
||||
`OPENCLAW_CONFIG_PATH` 直接指向真实文件。
|
||||
OpenClaw 会从 `~/.openclaw/openclaw.json` 读取可选的 <Tooltip tip="JSON5 支持注释和尾随逗号">**JSON5**</Tooltip> 配置。
|
||||
当前使用的配置路径必须是一个常规文件。对于由 OpenClaw 执行写入的场景，不支持使用符号链接的 `openclaw.json` 布局；原子写入可能会替换该路径，而不是保留符号链接。如果你将配置保存在默认状态目录之外，请将 `OPENCLAW_CONFIG_PATH` 直接指向真实文件。
|
||||
|
||||
如果文件缺失，OpenClaw 会使用安全的默认值。添加配置的常见原因包括：
|
||||
如果该文件不存在，OpenClaw 会使用安全的默认值。常见的添加配置原因包括：
|
||||
|
||||
- 连接渠道并控制谁可以向机器人发送消息
|
||||
- 设置模型、工具、沙箱隔离或自动化功能（cron、hooks）
|
||||
- 连接渠道并控制谁可以给机器人发消息
|
||||
- 设置模型、工具、沙箱隔离或自动化（cron、hooks）
|
||||
- 调整会话、媒体、网络或 UI
|
||||
|
||||
有关所有可用字段，请参阅[完整参考](/zh-CN/gateway/configuration-reference)。
|
||||
所有可用字段请参阅[完整参考](/zh-CN/gateway/configuration-reference)。
|
||||
|
||||
<Tip>
|
||||
**刚接触配置？** 可以从 `openclaw onboard` 开始进行交互式设置，或者查看 [Configuration Examples](/zh-CN/gateway/configuration-examples) 指南，获取可直接复制粘贴的完整配置。
|
||||
**刚开始接触配置？** 请先使用 `openclaw onboard` 进行交互式设置，或查看[配置示例](/zh-CN/gateway/configuration-examples)指南，获取可直接复制粘贴的完整配置。
|
||||
</Tip>
|
||||
|
||||
## 最小配置
|
||||
@ -49,7 +46,7 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
|
||||
<Tabs>
|
||||
<Tab title="交互式向导">
|
||||
```bash
|
||||
openclaw onboard # 完整的新手引导流程
|
||||
openclaw onboard # 完整新手引导流程
|
||||
openclaw configure # 配置向导
|
||||
```
|
||||
</Tab>
|
||||
@ -61,50 +58,42 @@ OpenClaw 会从 `~/.openclaw/openclaw.json` 读取一个可选的 <Tooltip tip="
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="控制 UI">
|
||||
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789)，然后使用 **配置** 选项卡。
|
||||
控制 UI 会根据当前配置 schema 渲染表单，其中包括字段
|
||||
`title` / `description` 文档元数据，以及在可用情况下的插件和渠道 schema，
|
||||
同时还提供一个 **Raw JSON** 编辑器作为兜底入口。对于下钻式
|
||||
UI 和其他工具，Gateway 网关 还提供了 `config.schema.lookup`，用于
|
||||
获取单个路径范围内的 schema 节点及其直接子节点摘要。
|
||||
打开 [http://127.0.0.1:18789](http://127.0.0.1:18789) 并使用 **配置** 标签页。
|
||||
Control UI 会根据实时配置 schema 渲染表单，包括字段 `title` / `description` 文档元数据，以及在可用时的插件和渠道 schema，并提供一个 **Raw JSON** 编辑器作为兜底方式。对于下钻式 UI 和其他工具，Gateway 网关还暴露了 `config.schema.lookup`，用于获取单个路径范围的 schema 节点及其直接子节点摘要。
|
||||
</Tab>
|
||||
<Tab title="直接编辑">
|
||||
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关 会监视该文件并自动应用更改（参见[热重载](#config-hot-reload)）。
|
||||
直接编辑 `~/.openclaw/openclaw.json`。Gateway 网关会监视该文件并自动应用更改（见[热重载](#config-hot-reload)）。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 严格校验
|
||||
|
||||
<Warning>
|
||||
OpenClaw 只接受与 schema 完全匹配的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关 **拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。
|
||||
OpenClaw 只接受完全符合 schema 的配置。未知键名、格式错误的类型或无效值都会导致 Gateway 网关**拒绝启动**。唯一的根级例外是 `$schema`（字符串），这样编辑器就可以附加 JSON Schema 元数据。
|
||||
</Warning>
|
||||
|
||||
`openclaw config schema` 会打印供控制 UI
|
||||
和校验使用的规范 JSON Schema。`config.schema.lookup` 会获取单个路径范围内的节点及其
|
||||
子节点摘要，用于下钻式工具。字段 `title`/`description` 文档元数据
|
||||
会传递到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/
|
||||
`oneOf`/`allOf` 分支中。当清单注册表加载后，运行时插件和渠道 schema 也会合并进来。
|
||||
`openclaw config schema` 会打印 Control UI 和校验所使用的规范 JSON Schema。
|
||||
`config.schema.lookup` 会获取单个路径范围节点及其子节点摘要，用于下钻式工具。
|
||||
字段 `title`/`description` 文档元数据会延续到嵌套对象、通配符（`*`）、数组项（`[]`）以及 `anyOf`/`oneOf`/`allOf` 分支中。
|
||||
加载清单注册表后，运行时插件和渠道 schema 也会合并进来。
|
||||
|
||||
当校验失败时：
|
||||
|
||||
- Gateway 网关 不会启动
|
||||
- Gateway 网关不会启动
|
||||
- 只有诊断命令可用（`openclaw doctor`、`openclaw logs`、`openclaw health`、`openclaw status`）
|
||||
- 运行 `openclaw doctor` 查看具体问题
|
||||
- 运行 `openclaw doctor --fix`（或 `--yes`）以应用修复
|
||||
- 运行 `openclaw doctor --fix`（或 `--yes`）应用修复
|
||||
|
||||
Gateway 网关 在每次成功启动后都会保留一份受信任的“上次已知正常”副本。
|
||||
如果之后 `openclaw.json` 未通过校验（或缺少 `gateway.mode`、体积明显缩小，
|
||||
或前面意外插入了一行日志），OpenClaw 会将损坏的文件保留为
|
||||
`.clobbered.*`，恢复“上次已知正常”副本，并记录恢复原因。
|
||||
下一次智能体回合也会收到一条系统事件警告，这样主智能体就不会盲目重写已恢复的配置。
|
||||
当候选配置中包含诸如 `***` 之类已脱敏的密钥占位符时，
|
||||
将其提升为“上次已知正常”副本的操作会被跳过。
|
||||
每次成功启动后，Gateway 网关都会保留一份可信的“最后一次已知正常”副本。
|
||||
如果之后 `openclaw.json` 校验失败（或丢失 `gateway.mode`、体积显著缩小，或前面意外插入了一行日志），OpenClaw 会将损坏的文件保留为 `.clobbered.*`，恢复“最后一次已知正常”副本，并记录恢复原因。
|
||||
下一次智能体轮次也会收到一条系统事件警告，这样主智能体就不会盲目重写已恢复的配置。
|
||||
如果候选配置中包含诸如 `***` 之类已脱敏的密钥占位符，则不会将其提升为“最后一次已知正常”。
|
||||
|
||||
## 常见任务
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="设置一个渠道（WhatsApp、Telegram、Discord 等）">
|
||||
每个渠道在 `channels.<provider>` 下都有自己的配置部分。设置步骤请参见对应的专用渠道页面：
|
||||
每个渠道在 `channels.<provider>` 下都有自己的配置部分。设置步骤请参阅相应的专属渠道页面：
|
||||
|
||||
- [WhatsApp](/zh-CN/channels/whatsapp) — `channels.whatsapp`
|
||||
- [Telegram](/zh-CN/channels/telegram) — `channels.telegram`
|
||||
@ -117,7 +106,7 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
- [iMessage](/zh-CN/channels/imessage) — `channels.imessage`
|
||||
- [Mattermost](/zh-CN/channels/mattermost) — `channels.mattermost`
|
||||
|
||||
所有渠道都共享相同的私信策略模式：
|
||||
所有渠道共享相同的私信策略模式：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -126,7 +115,7 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
enabled: true,
|
||||
botToken: "123:abc",
|
||||
dmPolicy: "pairing", // pairing | allowlist | open | disabled
|
||||
allowFrom: ["tg:123"], // only for allowlist/open
|
||||
allowFrom: ["tg:123"], // 仅用于 allowlist/open
|
||||
},
|
||||
},
|
||||
}
|
||||
@ -135,7 +124,7 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="选择并配置模型">
|
||||
设置主模型和可选的后备模型：
|
||||
设置主模型和可选回退模型：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -143,42 +132,42 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "anthropic/claude-sonnet-4-6",
|
||||
fallbacks: ["openai/gpt-5.4"],
|
||||
fallbacks: ["openai/gpt-5.5"],
|
||||
},
|
||||
models: {
|
||||
"anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
|
||||
"openai/gpt-5.4": { alias: "GPT" },
|
||||
"openai/gpt-5.5": { alias: "GPT" },
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- `agents.defaults.models` 定义模型目录，并充当 `/model` 的允许列表。
|
||||
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 添加允许列表条目，而不会移除现有模型。会删除条目的普通替换操作将被拒绝，除非你传入 `--replace`。
|
||||
- `agents.defaults.models` 定义模型目录，并作为 `/model` 的允许列表。
|
||||
- 使用 `openclaw config set agents.defaults.models '<json>' --strict-json --merge` 可在不移除现有模型的情况下添加允许列表条目。会移除条目的普通替换操作会被拒绝，除非你传入 `--replace`。
|
||||
- 模型引用使用 `provider/model` 格式（例如 `anthropic/claude-opus-4-6`）。
|
||||
- `agents.defaults.imageMaxDimensionPx` 控制对话记录/工具图像的缩放上限（默认 `1200`）；在截图较多的运行中，较低的值通常能减少视觉 token 的使用量。
|
||||
- 在聊天中切换模型，请参见 [Models CLI](/zh-CN/concepts/models)；关于凭证轮换和后备行为，请参见 [Model Failover](/zh-CN/concepts/model-failover)。
|
||||
- 对于自定义/自托管提供商，请参见参考文档中的 [Custom providers](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。
|
||||
- `agents.defaults.imageMaxDimensionPx` 控制转录/工具图像的缩放下限（默认 `1200`）；较低的值通常会在截图较多的运行中减少视觉 token 使用量。
|
||||
- 在聊天中切换模型请参阅[模型 CLI](/zh-CN/concepts/models)，关于凭证轮换和回退行为请参阅[模型回退](/zh-CN/concepts/model-failover)。
|
||||
- 对于自定义/自托管提供商，请参阅参考中的[自定义提供商](/zh-CN/gateway/configuration-reference#custom-providers-and-base-urls)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="控制谁可以向机器人发送消息">
|
||||
私信访问通过每个渠道的 `dmPolicy` 进行控制：
|
||||
<Accordion title="控制谁可以给机器人发消息">
|
||||
私信访问通过每个渠道的 `dmPolicy` 控制：
|
||||
|
||||
- `"pairing"`（默认）：未知发送者会收到一次性配对码以供批准
|
||||
- `"allowlist"`：仅允许 `allowFrom` 中的发送者（或已配对的允许存储）
|
||||
- `"open"`：允许所有入站私信（需要 `allowFrom: ["*"]`）
|
||||
- `"open"`：允许所有传入私信（要求 `allowFrom: ["*"]`）
|
||||
- `"disabled"`：忽略所有私信
|
||||
|
||||
对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道专用的允许列表。
|
||||
对于群组，请使用 `groupPolicy` + `groupAllowFrom` 或渠道特定允许列表。
|
||||
|
||||
有关每个渠道的详细信息，请参见[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)。
|
||||
每个渠道的详细信息请参阅[完整参考](/zh-CN/gateway/configuration-reference#dm-and-group-access)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="设置群聊提及门控">
|
||||
群组消息默认 **需要提及**。可按智能体配置模式：
|
||||
群组消息默认**要求提及**。可按智能体配置模式：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -201,14 +190,13 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
```
|
||||
|
||||
- **元数据提及**：原生 @ 提及（WhatsApp 点按提及、Telegram @bot 等）
|
||||
- **文本模式**：`mentionPatterns` 中的安全正则表达式模式
|
||||
- 有关每个渠道的覆盖规则和自聊模式，请参见[完整参考](/zh-CN/gateway/configuration-reference#group-chat-mention-gating)。
|
||||
- **文本模式**：`mentionPatterns` 中的安全正则模式
|
||||
- 每个渠道的覆盖和自聊模式请参阅[完整参考](/zh-CN/gateway/configuration-reference#group-chat-mention-gating)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="按智能体限制 Skills">
|
||||
使用 `agents.defaults.skills` 作为共享基线，然后通过
|
||||
`agents.list[].skills` 覆盖特定智能体：
|
||||
使用 `agents.defaults.skills` 作为共享基线，然后通过 `agents.list[].skills` 覆盖特定智能体：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -219,22 +207,21 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
list: [
|
||||
{ id: "writer" }, // 继承 github、weather
|
||||
{ id: "docs", skills: ["docs-search"] }, // 替换默认值
|
||||
{ id: "locked-down", skills: [] }, // 无 Skills
|
||||
{ id: "locked-down", skills: [] }, // 不启用 Skills
|
||||
],
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
- 省略 `agents.defaults.skills` 可使默认 Skills 不受限制。
|
||||
- 省略 `agents.list[].skills` 将继承默认值。
|
||||
- 设置 `agents.list[].skills: []` 表示不启用 Skills。
|
||||
- 请参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和
|
||||
[配置参考](/zh-CN/gateway/configuration-reference#agents-defaults-skills)。
|
||||
- 省略 `agents.defaults.skills` 表示默认不限制 Skills。
|
||||
- 省略 `agents.list[].skills` 表示继承默认值。
|
||||
- 将 `agents.list[].skills` 设为 `[]` 表示不启用 Skills。
|
||||
- 参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 以及[配置参考](/zh-CN/gateway/configuration-reference#agents-defaults-skills)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="调整 Gateway 网关 渠道健康监控">
|
||||
控制 Gateway 网关 对看起来已停滞的渠道执行重启的激进程度：
|
||||
<Accordion title="调整 Gateway 网关渠道健康监控">
|
||||
控制 Gateway 网关对看似卡住的渠道执行重启的激进程度：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -256,20 +243,20 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
}
|
||||
```
|
||||
|
||||
- 设置 `gateway.channelHealthCheckMinutes: 0` 可全局禁用健康监控重启。
|
||||
- 将 `gateway.channelHealthCheckMinutes: 0` 设为 0 可全局禁用健康监控重启。
|
||||
- `channelStaleEventThresholdMinutes` 应大于或等于检查间隔。
|
||||
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled`，可对单个渠道或账户禁用自动重启，而无需禁用全局监控。
|
||||
- 关于运维调试，请参见[健康检查](/zh-CN/gateway/health)；有关所有字段，请参见[完整参考](/zh-CN/gateway/configuration-reference#gateway)。
|
||||
- 使用 `channels.<provider>.healthMonitor.enabled` 或 `channels.<provider>.accounts.<id>.healthMonitor.enabled`，可为单个渠道或账号禁用自动重启，而不必关闭全局监控。
|
||||
- 运行调试请参阅[健康检查](/zh-CN/gateway/health)，所有字段请参阅[完整参考](/zh-CN/gateway/configuration-reference#gateway)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="配置会话和重置">
|
||||
会话控制对话的连续性和隔离性：
|
||||
会话控制对话连续性和隔离性：
|
||||
|
||||
```json5
|
||||
{
|
||||
session: {
|
||||
dmScope: "per-channel-peer", // recommended for multi-user
|
||||
dmScope: "per-channel-peer", // 推荐用于多用户
|
||||
threadBindings: {
|
||||
enabled: true,
|
||||
idleHours: 24,
|
||||
@ -286,8 +273,8 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
|
||||
- `dmScope`：`main`（共享）| `per-peer` | `per-channel-peer` | `per-account-channel-peer`
|
||||
- `threadBindings`：线程绑定会话路由的全局默认值（Discord 支持 `/focus`、`/unfocus`、`/agents`、`/session idle` 和 `/session max-age`）。
|
||||
- 关于作用域、身份关联和发送策略，请参见[会话管理](/zh-CN/concepts/session)。
|
||||
- 有关所有字段，请参见[完整参考](/zh-CN/gateway/configuration-reference#session)。
|
||||
- 作用域、身份关联和发送策略请参阅[会话管理](/zh-CN/concepts/session)。
|
||||
- 所有字段请参阅[完整参考](/zh-CN/gateway/configuration-reference#session)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -309,14 +296,14 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
|
||||
先构建镜像：`scripts/sandbox-setup.sh`
|
||||
|
||||
完整指南请参见[沙箱隔离](/zh-CN/gateway/sandboxing)，所有选项请参见[完整参考](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)。
|
||||
完整指南请参阅[沙箱隔离](/zh-CN/gateway/sandboxing)，所有选项请参阅[完整参考](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="为官方 iOS 构建启用基于 relay 的推送">
|
||||
基于 relay 的推送在 `openclaw.json` 中配置。
|
||||
|
||||
在 Gateway 网关 配置中设置：
|
||||
在 Gateway 网关配置中设置：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -340,37 +327,37 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com
|
||||
```
|
||||
|
||||
这会执行以下操作：
|
||||
作用如下：
|
||||
|
||||
- 允许 Gateway 网关 通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。
|
||||
- 使用由已配对 iOS 应用转发的、限定注册范围的发送授权。Gateway 网关 不需要部署范围的 relay token。
|
||||
- 将每个基于 relay 的注册绑定到 iOS 应用配对时所连接的 Gateway 网关 身份，因此其他 Gateway 网关 无法复用已存储的注册信息。
|
||||
- 本地/手动构建的 iOS 版本仍使用直接 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发构建版本。
|
||||
- 必须与官方/TestFlight iOS 构建中内置的 relay base URL 匹配，这样注册和发送流量才会到达同一个 relay 部署。
|
||||
- 让 Gateway 网关能够通过外部 relay 发送 `push.test`、唤醒提示和重连唤醒。
|
||||
- 使用由已配对 iOS 应用转发的、基于注册范围的发送授权。Gateway 网关不需要部署范围的 relay token。
|
||||
- 将每个基于 relay 的注册绑定到 iOS 应用所配对的 Gateway 网关身份，因此其他 Gateway 网关无法复用已存储的注册信息。
|
||||
- 对本地/手动构建的 iOS 版本继续使用直接 APNs。基于 relay 的发送仅适用于通过 relay 注册的官方分发版本。
|
||||
- 必须与官方/TestFlight iOS 构建中内置的 relay 基础 URL 匹配，这样注册和发送流量才会到达同一个 relay 部署。
|
||||
|
||||
端到端流程：
|
||||
|
||||
1. 安装一个使用相同 relay base URL 编译的官方/TestFlight iOS 构建版本。
|
||||
2. 在 Gateway 网关 上配置 `gateway.push.apns.relay.baseUrl`。
|
||||
3. 将 iOS 应用与 Gateway 网关 配对，并让节点会话和操作员会话都建立连接。
|
||||
4. iOS 应用获取 Gateway 网关 身份，使用 App Attest 和应用收据向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的 Gateway 网关。
|
||||
5. Gateway 网关 存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
|
||||
1. 安装一个使用相同 relay 基础 URL 编译的官方/TestFlight iOS 构建。
|
||||
2. 在 Gateway 网关上配置 `gateway.push.apns.relay.baseUrl`。
|
||||
3. 将 iOS 应用与 Gateway 网关配对，并让节点会话与操作员会话都建立连接。
|
||||
4. iOS 应用获取 Gateway 网关身份，使用 App Attest 和应用收据向 relay 注册，然后将基于 relay 的 `push.apns.register` 负载发布到已配对的 Gateway 网关。
|
||||
5. Gateway 网关存储 relay 句柄和发送授权，然后将它们用于 `push.test`、唤醒提示和重连唤醒。
|
||||
|
||||
运行说明：
|
||||
运维说明：
|
||||
|
||||
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接应用，以便它发布绑定到该 Gateway 网关 的新 relay 注册信息。
|
||||
- 如果你发布了一个指向不同 relay 部署的新 iOS 构建版本，应用会刷新其缓存的 relay 注册信息，而不是复用旧的 relay 来源。
|
||||
- 如果你将 iOS 应用切换到另一个 Gateway 网关，请重新连接该应用，以便它发布一个绑定到新 Gateway 网关的 relay 注册。
|
||||
- 如果你发布了一个指向不同 relay 部署的新 iOS 构建，应用会刷新其缓存的 relay 注册，而不是复用旧的 relay 来源。
|
||||
|
||||
兼容性说明：
|
||||
|
||||
- `OPENCLAW_APNS_RELAY_BASE_URL` 和 `OPENCLAW_APNS_RELAY_TIMEOUT_MS` 仍可作为临时环境变量覆盖项使用。
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 local loopback 的开发逃生口；不要在配置中持久保存 HTTP relay URL。
|
||||
- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true` 仍然只是一个仅限 loopback 的开发逃生口；不要在配置中持久化 HTTP relay URL。
|
||||
|
||||
有关端到端流程，请参见 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)；有关 relay 安全模型，请参见 [Authentication and trust flow](/zh-CN/platforms/ios#authentication-and-trust-flow)。
|
||||
端到端流程请参阅 [iOS App](/zh-CN/platforms/ios#relay-backed-push-for-official-builds)，relay 安全模型请参阅[认证与信任流程](/zh-CN/platforms/ios#authentication-and-trust-flow)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="设置心跳（定期检查）">
|
||||
<Accordion title="设置 heartbeat（定期检查）">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
@ -384,10 +371,10 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
}
|
||||
```
|
||||
|
||||
- `every`：时长字符串（`30m`、`2h`）。设置为 `0m` 可禁用。
|
||||
- `every`：时长字符串（`30m`、`2h`）。设为 `0m` 可禁用。
|
||||
- `target`：`last` | `none` | `<channel-id>`（例如 `discord`、`matrix`、`telegram` 或 `whatsapp`）
|
||||
- `directPolicy`：对于私信式心跳目标，可设为 `allow`（默认）或 `block`
|
||||
- 完整指南请参见 [Heartbeat](/zh-CN/gateway/heartbeat)。
|
||||
- `directPolicy`：用于私信类 heartbeat 目标时，可设为 `allow`（默认）或 `block`
|
||||
- 完整指南请参阅 [Heartbeat](/zh-CN/gateway/heartbeat)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -406,14 +393,14 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
}
|
||||
```
|
||||
|
||||
- `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设置为 `false` 可禁用）。
|
||||
- `sessionRetention`：从 `sessions.json` 中清理已完成的隔离运行会话（默认 `24h`；设为 `false` 可禁用）。
|
||||
- `runLog`：按大小和保留行数清理 `cron/runs/<jobId>.jsonl`。
|
||||
- 功能概览和 CLI 示例请参见 [Cron jobs](/zh-CN/automation/cron-jobs)。
|
||||
- 功能概览和 CLI 示例请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="设置 webhooks（hooks）">
|
||||
在 Gateway 网关 上启用 HTTP webhook 端点：
|
||||
<Accordion title="设置 webhook（hooks）">
|
||||
在 Gateway 网关上启用 HTTP webhook 端点：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -437,20 +424,20 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
```
|
||||
|
||||
安全说明：
|
||||
- 将所有 hook/webhook 负载内容都视为不可信输入。
|
||||
- 将所有 hook/webhook 负载内容都视为不受信任的输入。
|
||||
- 使用专用的 `hooks.token`；不要复用共享的 Gateway 网关 token。
|
||||
- Hook 身份验证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串 token 会被拒绝。
|
||||
- `hooks.path` 不能为 `/`；请将 webhook 入口保留在专用子路径下，例如 `/hooks`。
|
||||
- 保持不安全内容绕过标志为禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`），除非你是在进行严格限定范围的调试。
|
||||
- 如果你启用了 `hooks.allowRequestSessionKey`，也要同时设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选的会话键。
|
||||
- 对于由 hook 驱动的智能体，优先使用强大的现代模型层级和严格的工具策略（例如仅消息传递，并在可能时启用沙箱隔离）。
|
||||
- Hook 认证仅支持请求头（`Authorization: Bearer ...` 或 `x-openclaw-token`）；查询字符串中的 token 会被拒绝。
|
||||
- `hooks.path` 不能是 `/`；请将 webhook 入口放在专用子路径下，例如 `/hooks`。
|
||||
- 除非进行严格限定范围的调试，否则请保持不安全内容绕过标志为禁用状态（`hooks.gmail.allowUnsafeExternalContent`、`hooks.mappings[].allowUnsafeExternalContent`）。
|
||||
- 如果你启用了 `hooks.allowRequestSessionKey`，也请设置 `hooks.allowedSessionKeyPrefixes`，以限制调用方可选的会话键名范围。
|
||||
- 对于由 hook 驱动的智能体，请优先使用强大的现代模型层级和严格的工具策略（例如仅限消息传递，并尽可能启用沙箱隔离）。
|
||||
|
||||
有关所有映射选项和 Gmail 集成，请参见[完整参考](/zh-CN/gateway/configuration-reference#hooks)。
|
||||
所有映射选项和 Gmail 集成请参阅[完整参考](/zh-CN/gateway/configuration-reference#hooks)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="配置多智能体路由">
|
||||
运行多个相互隔离的智能体，并为其分配独立的工作区和会话：
|
||||
运行多个相互隔离的智能体，并为其使用单独的工作区和会话：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -467,12 +454,12 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
}
|
||||
```
|
||||
|
||||
绑定规则和每个智能体的访问配置文件，请参见 [Multi-Agent](/zh-CN/concepts/multi-agent) 和[完整参考](/zh-CN/gateway/configuration-reference#multi-agent-routing)。
|
||||
绑定规则和每个智能体的访问配置请参阅[多智能体](/zh-CN/concepts/multi-agent)和[完整参考](/zh-CN/gateway/configuration-reference#multi-agent-routing)。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="将配置拆分为多个文件（$include）">
|
||||
使用 `$include` 来组织大型配置：
|
||||
使用 `$include` 组织大型配置：
|
||||
|
||||
```json5
|
||||
// ~/.openclaw/openclaw.json
|
||||
@ -485,17 +472,13 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
}
|
||||
```
|
||||
|
||||
- **单个文件**：替换所在对象
|
||||
- **单个文件**：替换包含它的对象
|
||||
- **文件数组**：按顺序深度合并（后者优先）
|
||||
- **同级键**：在 include 之后再合并（覆盖引入的值）
|
||||
- **同级键名**：在 include 之后合并（覆盖被包含的值）
|
||||
- **嵌套 include**：支持，最多 10 层
|
||||
- **相对路径**：相对于包含它的文件解析
|
||||
- **由 OpenClaw 发起的写入**：当一次写入只更改一个由单文件 include
|
||||
支撑的顶层部分时，例如 `plugins: { $include: "./plugins.json5" }`，
|
||||
OpenClaw 会更新该被引入文件，并保持 `openclaw.json` 不变
|
||||
- **不支持透传写入**：对于根级 include、include 数组以及带有
|
||||
同级覆盖的 include，OpenClaw 发起的写入会以封闭失败方式终止，而不是
|
||||
将配置拍平
|
||||
- **OpenClaw 自有写入**：当一次写入只更改一个由单文件 include 支持的顶层部分时，例如 `plugins: { $include: "./plugins.json5" }`，OpenClaw 会更新该被包含文件，并保持 `openclaw.json` 不变
|
||||
- **不支持的透传写入**：根级 include、include 数组，以及带有同级覆盖的 include，对于 OpenClaw 自有写入会以“失败即关闭”的方式处理，而不是将配置展平
|
||||
- **错误处理**：对缺失文件、解析错误和循环 include 提供清晰错误信息
|
||||
|
||||
</Accordion>
|
||||
@ -503,27 +486,20 @@ Gateway 网关 在每次成功启动后都会保留一份受信任的“上次
|
||||
|
||||
## 配置热重载
|
||||
|
||||
Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改 —— 对于大多数设置，无需手动重启。
|
||||
Gateway 网关会监视 `~/.openclaw/openclaw.json` 并自动应用更改——对于大多数设置，无需手动重启。
|
||||
|
||||
直接编辑文件会在通过校验前被视为不可信。监视器会等待
|
||||
编辑器的临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复
|
||||
“上次已知正常”配置来拒绝无效的外部编辑。由 OpenClaw 发起的
|
||||
配置写入在落盘前也会经过相同的 schema 校验；具有破坏性的覆盖行为，例如
|
||||
删除 `gateway.mode` 或将文件缩小到原来的一半以下，会被拒绝，
|
||||
并保存为 `.rejected.*` 以供检查。
|
||||
直接编辑文件会在通过校验前被视为不受信任。监视器会等待编辑器临时写入/重命名抖动稳定下来，读取最终文件，并通过恢复“最后一次已知正常”配置来拒绝无效的外部编辑。OpenClaw 自有的配置写入也会在写入前经过相同的 schema 关卡；诸如删除 `gateway.mode` 或将文件缩小到原来一半以下之类的破坏性覆盖会被拒绝，并保存为 `.rejected.*` 以供检查。
|
||||
|
||||
如果你在日志中看到 `Config auto-restored from last-known-good` 或
|
||||
`config reload restored last-known-good config`，请检查 `openclaw.json` 旁边对应的
|
||||
`.clobbered.*` 文件，修复被拒绝的负载，然后运行
|
||||
`openclaw config validate`。恢复检查清单请参见[Gateway 网关 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
|
||||
`config reload restored last-known-good config`，请检查 `openclaw.json` 旁边对应的 `.clobbered.*` 文件，修复被拒绝的负载，然后运行 `openclaw config validate`。恢复检查清单请参阅 [Gateway 故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)。
|
||||
|
||||
### 重载模式
|
||||
|
||||
| 模式 | 行为 |
|
||||
| ---------------------- | --------------------------------------------------------------------------------------- |
|
||||
| **`hybrid`**（默认） | 立即热应用安全更改。对关键更改自动重启。 |
|
||||
| **`hot`** | 仅热应用安全更改。当需要重启时记录警告 —— 由你手动处理。 |
|
||||
| **`restart`** | 对任何配置更改都重启 Gateway 网关，无论是否安全。 |
|
||||
| **`hot`** | 仅热应用安全更改。当需要重启时记录警告——由你自行处理。 |
|
||||
| **`restart`** | 任何配置更改都会重启 Gateway 网关，无论是否安全。 |
|
||||
| **`off`** | 禁用文件监视。更改会在下一次手动重启时生效。 |
|
||||
|
||||
```json5
|
||||
@ -534,64 +510,54 @@ Gateway 网关 会监视 `~/.openclaw/openclaw.json` 并自动应用更改 —
|
||||
}
|
||||
```
|
||||
|
||||
### 哪些可以热应用，哪些需要重启
|
||||
### 哪些可热应用，哪些需要重启
|
||||
|
||||
大多数字段都可以无停机热应用。在 `hybrid` 模式下，需要重启的更改会自动处理。
|
||||
|
||||
| 类别 | 字段 | 需要重启？ |
|
||||
| ------------------- | ----------------------------------------------------------------- | --------------- |
|
||||
| 渠道 | `channels.*`、`web`（WhatsApp）—— 所有内置和插件渠道 | 否 |
|
||||
| 智能体和模型 | `agent`、`agents`、`models`、`routing` | 否 |
|
||||
| 渠道 | `channels.*`、`web`（WhatsApp）——所有内置和插件渠道 | 否 |
|
||||
| 智能体与模型 | `agent`、`agents`、`models`、`routing` | 否 |
|
||||
| 自动化 | `hooks`、`cron`、`agent.heartbeat` | 否 |
|
||||
| 会话和消息 | `session`、`messages` | 否 |
|
||||
| 工具和媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 |
|
||||
| UI 和其他 | `ui`、`logging`、`identity`、`bindings` | 否 |
|
||||
| Gateway 网关 服务器 | `gateway.*`（port、bind、auth、tailscale、TLS、HTTP） | **是** |
|
||||
| 会话与消息 | `session`、`messages` | 否 |
|
||||
| 工具与媒体 | `tools`、`browser`、`skills`、`audio`、`talk` | 否 |
|
||||
| UI 与其他 | `ui`、`logging`、`identity`、`bindings` | 否 |
|
||||
| Gateway 网关服务器 | `gateway.*`（port、bind、auth、Tailscale、TLS、HTTP） | **是** |
|
||||
| 基础设施 | `discovery`、`canvasHost`、`plugins` | **是** |
|
||||
|
||||
<Note>
|
||||
`gateway.reload` 和 `gateway.remote` 是例外 —— 更改它们**不会**触发重启。
|
||||
`gateway.reload` 和 `gateway.remote` 是例外——更改它们**不会**触发重启。
|
||||
</Note>
|
||||
|
||||
### 重载规划
|
||||
|
||||
当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会基于
|
||||
源文件编写时的布局来规划重载，而不是基于拍平后的内存视图。
|
||||
这样即使某个单独的顶层部分位于其自己的被引入文件中，例如
|
||||
`plugins: { $include: "./plugins.json5" }`，热重载决策（热应用还是重启）也能保持可预测。
|
||||
如果源布局存在歧义，重载规划会以封闭失败方式终止。
|
||||
当你编辑一个通过 `$include` 引用的源文件时，OpenClaw 会根据源作者编写的布局来规划重载，而不是根据展平后的内存视图。即使某个顶层部分单独存在于一个被包含文件中，例如 `plugins: { $include: "./plugins.json5" }`，这也能让热重载决策（热应用还是重启）保持可预测。如果源布局存在歧义，重载规划会以“失败即关闭”的方式处理。
|
||||
|
||||
## 配置 RPC（程序化更新）
|
||||
## 配置 RPC（编程式更新）
|
||||
|
||||
对于通过 Gateway 网关 API 写入配置的工具，推荐使用以下流程：
|
||||
|
||||
- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子节点
|
||||
摘要）
|
||||
- 使用 `config.get` 获取当前快照及其 `hash`
|
||||
- 使用 `config.patch` 进行部分更新（JSON merge patch：对象合并，`null`
|
||||
表示删除，数组整体替换）
|
||||
- 仅当你确实打算替换整个配置时，才使用 `config.apply`
|
||||
- 使用 `update.run` 显式执行自更新并重启
|
||||
- 使用 `config.schema.lookup` 检查一个子树（浅层 schema 节点 + 子节点摘要）
|
||||
- 使用 `config.get` 获取当前快照和 `hash`
|
||||
- 使用 `config.patch` 执行部分更新（JSON merge patch：对象合并，`null` 删除，数组替换）
|
||||
- 仅在你打算替换整个配置时使用 `config.apply`
|
||||
- 使用 `update.run` 执行显式自更新并重启
|
||||
|
||||
<Note>
|
||||
控制平面写入（`config.apply`、`config.patch`、`update.run`）
|
||||
按每个 `deviceId+clientIp` 限流为每 60 秒 3 次请求。
|
||||
重启请求会被合并，然后在两次重启周期之间强制执行 30 秒冷却时间。
|
||||
控制平面写入（`config.apply`、`config.patch`、`update.run`）按每个 `deviceId+clientIp` 限制为每 60 秒 3 次请求。重启请求会被合并处理，并在两次重启周期之间强制执行 30 秒冷却时间。
|
||||
</Note>
|
||||
|
||||
部分 patch 示例：
|
||||
|
||||
```bash
|
||||
openclaw gateway call config.get --params '{}' # capture payload.hash
|
||||
openclaw gateway call config.get --params '{}' # 捕获 payload.hash
|
||||
openclaw gateway call config.patch --params '{
|
||||
"raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
|
||||
"baseHash": "<hash>"
|
||||
}'
|
||||
```
|
||||
|
||||
`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、
|
||||
`note` 和 `restartDelayMs`。当配置已存在时，这两种方法都要求提供
|
||||
`baseHash`。
|
||||
`config.apply` 和 `config.patch` 都接受 `raw`、`baseHash`、`sessionKey`、`note` 和 `restartDelayMs`。如果配置已存在，这两种方法都要求提供 `baseHash`。
|
||||
|
||||
## 环境变量
|
||||
|
||||
@ -611,8 +577,8 @@ OpenClaw 会从父进程读取环境变量，此外还包括：
|
||||
}
|
||||
```
|
||||
|
||||
<Accordion title="导入 Shell 环境变量（可选）">
|
||||
如果启用，并且预期键名尚未设置，OpenClaw 会运行你的登录 shell，并且只导入缺失的键名：
|
||||
<Accordion title="导入 shell 环境变量（可选）">
|
||||
如果启用，且预期键名未设置，OpenClaw 会运行你的登录 shell，并只导入缺失的键名：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -622,11 +588,11 @@ OpenClaw 会从父进程读取环境变量，此外还包括：
|
||||
}
|
||||
```
|
||||
|
||||
对应的环境变量：`OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
环境变量等价写法：`OPENCLAW_LOAD_SHELL_ENV=1`
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="在配置值中替换环境变量">
|
||||
可在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
|
||||
在任意配置字符串值中使用 `${VAR_NAME}` 引用环境变量：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -638,9 +604,9 @@ OpenClaw 会从父进程读取环境变量，此外还包括：
|
||||
规则：
|
||||
|
||||
- 仅匹配大写名称：`[A-Z_][A-Z0-9_]*`
|
||||
- 缺失或为空的变量会在加载时报错
|
||||
- 缺失或为空的变量会在加载时抛出错误
|
||||
- 使用 `$${VAR}` 转义以输出字面量
|
||||
- 在 `$include` 文件中同样有效
|
||||
- 在 `$include` 文件中同样适用
|
||||
- 内联替换：`"${BASE}/v1"` → `"https://api.example.com/v1"`
|
||||
|
||||
</Accordion>
|
||||
@ -678,16 +644,16 @@ OpenClaw 会从父进程读取环境变量，此外还包括：
|
||||
}
|
||||
```
|
||||
|
||||
有关 SecretRef 的详细信息（包括用于 `env`/`file`/`exec` 的 `secrets.providers`），请参见[Secrets Management](/zh-CN/gateway/secrets)。
|
||||
支持的凭证路径列在 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface) 中。
|
||||
有关 SecretRef 的详细信息（包括用于 `env`/`file`/`exec` 的 `secrets.providers`），请参阅[密钥管理](/zh-CN/gateway/secrets)。
|
||||
支持的凭证路径列于 [SecretRef Credential Surface](/zh-CN/reference/secretref-credential-surface)。
|
||||
</Accordion>
|
||||
|
||||
有关完整的优先级和来源，请参见[环境](/zh-CN/help/environment)。
|
||||
完整优先级和来源请参阅[环境变量](/zh-CN/help/environment)。
|
||||
|
||||
## 完整参考
|
||||
|
||||
有关完整的逐字段参考，请参见 **[配置参考](/zh-CN/gateway/configuration-reference)**。
|
||||
完整的逐字段参考请参阅 **[配置参考](/zh-CN/gateway/configuration-reference)**。
|
||||
|
||||
---
|
||||
|
||||
_相关内容：[Configuration Examples](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_
|
||||
_相关内容：[配置示例](/zh-CN/gateway/configuration-examples) · [配置参考](/zh-CN/gateway/configuration-reference) · [Doctor](/zh-CN/gateway/doctor)_
|
||||
|
||||
@ -1,110 +1,108 @@
|
||||
---
|
||||
read_when:
|
||||
- 集成那些期望使用 OpenAI Chat Completions 的工具
|
||||
summary: 从 Gateway 网关暴露 OpenAI 兼容的 `/v1/chat/completions` HTTP 端点
|
||||
- 集成那些需要 OpenAI Chat Completions 的工具
|
||||
summary: 从 Gateway 网关公开一个兼容 OpenAI 的 `/v1/chat/completions` HTTP 端点
|
||||
title: OpenAI Chat Completions
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:24:20Z"
|
||||
generated_at: "2026-04-23T19:24:38Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: c374b2f32ce693a8c752e2b0a2532c5f0299ed280f9a0e97b1a9d73bcec37b95
|
||||
source_hash: 36f09a82d96bbbc78ba325572dda1524857a534629398582a0bfc007f427b61c
|
||||
source_path: gateway/openai-http-api.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenAI Chat Completions（HTTP）
|
||||
|
||||
OpenClaw 的 Gateway 网关可以提供一个小型的 OpenAI 兼容 Chat Completions 端点。
|
||||
OpenClaw 的 Gateway 网关可以提供一个小型的、兼容 OpenAI 的 Chat Completions 端点。
|
||||
|
||||
该端点**默认禁用**。请先在配置中启用它。
|
||||
|
||||
- `POST /v1/chat/completions`
|
||||
- 与 Gateway 网关相同的端口（WS + HTTP 复用）：`http://<gateway-host>:<port>/v1/chat/completions`
|
||||
|
||||
当启用 Gateway 网关的 OpenAI 兼容 HTTP 表面时，它还会提供：
|
||||
当启用 Gateway 网关兼容 OpenAI 的 HTTP 接口后，它还会提供：
|
||||
|
||||
- `GET /v1/models`
|
||||
- `GET /v1/models/{id}`
|
||||
- `POST /v1/embeddings`
|
||||
- `POST /v1/responses`
|
||||
|
||||
在底层，请求会作为普通的 Gateway 网关智能体运行来执行（与 `openclaw agent` 使用同一条代码路径），因此路由/权限/配置与你的 Gateway 网关保持一致。
|
||||
在底层，请求会作为一次普通的 Gateway 智能体运行来执行（与 `openclaw agent` 使用相同代码路径），因此路由/权限/配置都与你的 Gateway 网关保持一致。
|
||||
|
||||
## 认证
|
||||
## 身份验证
|
||||
|
||||
使用 Gateway 网关认证配置。
|
||||
使用 Gateway 网关的身份验证配置。
|
||||
|
||||
常见的 HTTP 认证路径：
|
||||
常见的 HTTP 身份验证路径：
|
||||
|
||||
- 共享密钥认证（`gateway.auth.mode="token"` 或 `"password"`）：
|
||||
- 共享密钥身份验证（`gateway.auth.mode="token"` 或 `"password"`）：
|
||||
`Authorization: Bearer <token-or-password>`
|
||||
- 受信任的带身份 HTTP 认证（`gateway.auth.mode="trusted-proxy"`）：
|
||||
通过已配置的身份感知代理进行路由，并让它注入所需的身份头
|
||||
- 私有入口开放认证（`gateway.auth.mode="none"`）：
|
||||
不需要认证头
|
||||
- 受信任的携带身份信息的 HTTP 身份验证（`gateway.auth.mode="trusted-proxy"`）：
|
||||
通过已配置的身份感知代理进行路由，并让它注入所需的身份标头
|
||||
- 私有入口开放身份验证（`gateway.auth.mode="none"`）：
|
||||
不需要身份验证标头
|
||||
|
||||
注意事项：
|
||||
说明：
|
||||
|
||||
- 当 `gateway.auth.mode="token"` 时，使用 `gateway.auth.token`（或 `OPENCLAW_GATEWAY_TOKEN`）。
|
||||
- 当 `gateway.auth.mode="password"` 时，使用 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。
|
||||
- 当 `gateway.auth.mode="trusted-proxy"` 时，HTTP 请求必须来自
|
||||
已配置的非 loopback 受信任代理源；同主机上的 loopback 代理
|
||||
不满足此模式。
|
||||
- 如果配置了 `gateway.auth.rateLimit` 且认证失败次数过多，端点会返回 `429`，并带有 `Retry-After`。
|
||||
- 当 `gateway.auth.mode="trusted-proxy"` 时，HTTP 请求必须来自已配置的非 loopback 受信任代理来源；同主机 loopback 代理不满足该模式要求。
|
||||
- 如果已配置 `gateway.auth.rateLimit` 且身份验证失败次数过多，端点会返回 `429` 并附带 `Retry-After`。
|
||||
|
||||
## 安全边界（重要）
|
||||
|
||||
请将该端点视为此 Gateway 网关实例的**完整操作员访问**表面。
|
||||
请将此端点视为该 Gateway 网关实例的**完整操作员访问**接口。
|
||||
|
||||
- 这里的 HTTP bearer 认证不是狭义的按用户划分作用域模型。
|
||||
- 对此端点有效的 Gateway 网关 token/password 应被视为所有者/操作员凭证。
|
||||
- 请求会经过与受信任操作员操作相同的控制平面智能体路径。
|
||||
- 此端点上不存在单独的非所有者/按用户划分的工具边界；一旦调用方通过了这里的 Gateway 网关认证，OpenClaw 就会将该调用方视为此 Gateway 网关的受信任操作员。
|
||||
- 对于共享密钥认证模式（`token` 和 `password`），即使调用方发送了更窄的 `x-openclaw-scopes` 头，端点也会恢复正常的完整操作员默认值。
|
||||
- 受信任的带身份 HTTP 模式（例如 trusted proxy 认证或私有入口上的 `gateway.auth.mode="none"`）在提供 `x-openclaw-scopes` 时会遵从它，否则会回退到正常的操作员默认作用域集。
|
||||
- 如果目标智能体策略允许敏感工具，此端点就可以使用它们。
|
||||
- 请仅在 loopback/tailnet/私有入口上保留此端点；不要将其直接暴露到公共互联网。
|
||||
- 这里的 HTTP bearer 身份验证不是一个狭义的按用户划分的作用域模型。
|
||||
- 该端点的有效 Gateway 网关 token/password 应被视为所有者/操作员凭证。
|
||||
- 请求会通过与受信任操作员操作相同的控制平面智能体路径运行。
|
||||
- 此端点上没有单独的非所有者/按用户划分的工具边界；一旦调用方通过了这里的 Gateway 网关身份验证，OpenClaw 就会将该调用方视为此 Gateway 网关的受信任操作员。
|
||||
- 对于共享密钥身份验证模式（`token` 和 `password`），即使调用方发送了更窄的 `x-openclaw-scopes` 标头，该端点也会恢复正常的完整操作员默认设置。
|
||||
- 对于受信任的携带身份信息的 HTTP 模式（例如 trusted proxy 身份验证或 `gateway.auth.mode="none"`），存在 `x-openclaw-scopes` 时会遵循它，否则会回退到正常的操作员默认作用域集合。
|
||||
- 如果目标智能体策略允许敏感工具，此端点也可以使用它们。
|
||||
- 请仅在 loopback/tailnet/私有入口上使用此端点；不要将其直接暴露到公共互联网。
|
||||
|
||||
认证矩阵：
|
||||
身份验证矩阵：
|
||||
|
||||
- `gateway.auth.mode="token"` 或 `"password"` + `Authorization: Bearer ...`
|
||||
- 证明持有共享的 Gateway 网关操作员密钥
|
||||
- 证明持有共享 Gateway 网关操作员密钥
|
||||
- 忽略更窄的 `x-openclaw-scopes`
|
||||
- 恢复完整的默认操作员作用域集：
|
||||
`operator.admin`、`operator.approvals`、`operator.pairing`、
|
||||
`operator.read`、`operator.talk.secrets`、`operator.write`
|
||||
- 将此端点上的聊天回合视为所有者发送者回合
|
||||
- 受信任的带身份 HTTP 模式（例如 trusted proxy 认证，或私有入口上的 `gateway.auth.mode="none"`）
|
||||
- 认证某个外层受信任身份或部署边界
|
||||
- 在头存在时遵从 `x-openclaw-scopes`
|
||||
- 在头缺失时回退到正常的操作员默认作用域集
|
||||
- 只有当调用方显式缩窄作用域且省略 `operator.admin` 时，才会失去所有者语义
|
||||
- 恢复完整的默认操作员作用域集合：
|
||||
`operator.admin`, `operator.approvals`, `operator.pairing`,
|
||||
`operator.read`, `operator.talk.secrets`, `operator.write`
|
||||
- 将该端点上的聊天轮次视为所有者发送者轮次
|
||||
- 受信任的携带身份信息的 HTTP 模式（例如 trusted proxy 身份验证，或私有入口上的 `gateway.auth.mode="none"`）
|
||||
- 对某种外层受信任身份或部署边界进行身份验证
|
||||
- 当标头存在时遵循 `x-openclaw-scopes`
|
||||
- 当标头缺失时回退到正常的操作员默认作用域集合
|
||||
- 仅当调用方显式收窄作用域并省略 `operator.admin` 时，才会失去所有者语义
|
||||
|
||||
请参阅 [Security](/gateway/security) 和 [Remote access](/gateway/remote)。
|
||||
参见 [安全性](/zh-CN/gateway/security) 和 [远程访问](/zh-CN/gateway/remote)。
|
||||
|
||||
## 以智能体为先的模型契约
|
||||
## 智能体优先的模型契约
|
||||
|
||||
OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提供商模型 ID。
|
||||
OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提供商模型 id。
|
||||
|
||||
- `model: "openclaw"` 会路由到已配置的默认智能体。
|
||||
- `model: "openclaw/default"` 也会路由到已配置的默认智能体。
|
||||
- `model: "openclaw/<agentId>"` 会路由到某个特定智能体。
|
||||
- `model: "openclaw/<agentId>"` 会路由到特定智能体。
|
||||
|
||||
可选请求头：
|
||||
可选请求标头：
|
||||
|
||||
- `x-openclaw-model: <provider/model-or-bare-id>` 会为所选智能体覆盖后端模型。
|
||||
- `x-openclaw-agent-id: <agentId>` 仍作为兼容性覆盖受支持。
|
||||
- `x-openclaw-model: <provider/model-or-bare-id>` 会覆盖所选智能体的后端模型。
|
||||
- `x-openclaw-agent-id: <agentId>` 仍作为兼容性覆盖项受支持。
|
||||
- `x-openclaw-session-key: <sessionKey>` 可完全控制会话路由。
|
||||
- `x-openclaw-message-channel: <channel>` 可为具备渠道感知的提示词和策略设置合成入站渠道上下文。
|
||||
- `x-openclaw-message-channel: <channel>` 会为感知渠道的提示词和策略设置合成入口渠道上下文。
|
||||
|
||||
仍然接受的兼容性别名：
|
||||
仍然接受的兼容别名：
|
||||
|
||||
- `model: "openclaw:<agentId>"`
|
||||
- `model: "agent:<agentId>"`
|
||||
|
||||
## 启用该端点
|
||||
## 启用端点
|
||||
|
||||
将 `gateway.http.endpoints.chatCompletions.enabled` 设为 `true`：
|
||||
将 `gateway.http.endpoints.chatCompletions.enabled` 设置为 `true`：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -118,9 +116,9 @@ OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提
|
||||
}
|
||||
```
|
||||
|
||||
## 禁用该端点
|
||||
## 禁用端点
|
||||
|
||||
将 `gateway.http.endpoints.chatCompletions.enabled` 设为 `false`：
|
||||
将 `gateway.http.endpoints.chatCompletions.enabled` 设置为 `false`：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -136,57 +134,57 @@ OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提
|
||||
|
||||
## 会话行为
|
||||
|
||||
默认情况下，该端点对每个请求都是**无状态**的（每次调用都会生成一个新的会话键）。
|
||||
默认情况下，此端点对每个请求都是**无状态的**（每次调用都会生成一个新的会话键）。
|
||||
|
||||
如果请求中包含 OpenAI `user` 字符串，Gateway 网关会从中派生一个稳定的会话键，因此重复调用可以共享同一个智能体会话。
|
||||
如果请求包含 OpenAI `user` 字符串，Gateway 网关会基于它派生出一个稳定的会话键，因此重复调用可以共享同一个智能体会话。
|
||||
|
||||
## 为什么这个表面很重要
|
||||
## 为什么这个接口很重要
|
||||
|
||||
这是对自托管前端和工具最有杠杆作用的一组兼容接口：
|
||||
这是对自托管前端和工具最有价值的一组兼容接口：
|
||||
|
||||
- 大多数 Open WebUI、LobeChat 和 LibreChat 部署都期望 `/v1/models`。
|
||||
- 许多 RAG 系统都期望 `/v1/embeddings`。
|
||||
- 现有的 OpenAI 聊天客户端通常可以从 `/v1/chat/completions` 开始。
|
||||
- 更偏向智能体原生的客户端则越来越倾向于 `/v1/responses`。
|
||||
- 大多数 Open WebUI、LobeChat 和 LibreChat 配置都需要 `/v1/models`。
|
||||
- 许多 RAG 系统需要 `/v1/embeddings`。
|
||||
- 现有的 OpenAI 聊天客户端通常可以从 `/v1/chat/completions` 开始接入。
|
||||
- 更偏向智能体原生的客户端则越来越倾向于使用 `/v1/responses`。
|
||||
|
||||
## 模型列表和智能体路由
|
||||
## 模型列表与智能体路由
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="`/v1/models` 返回什么？">
|
||||
一个 OpenClaw 智能体目标列表。
|
||||
|
||||
返回的 ID 为 `openclaw`、`openclaw/default` 以及 `openclaw/<agentId>` 条目。
|
||||
返回的 id 包括 `openclaw`、`openclaw/default` 和 `openclaw/<agentId>` 条目。
|
||||
直接将它们用作 OpenAI `model` 值即可。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="`/v1/models` 列出的是智能体还是子智能体？">
|
||||
它列出的是顶层智能体目标，不是后端提供商模型，也不是子智能体。
|
||||
|
||||
子智能体仍然是内部执行拓扑的一部分。它们不会显示为伪模型。
|
||||
子智能体仍然属于内部执行拓扑。它们不会作为伪模型出现。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="为什么包含 `openclaw/default`？">
|
||||
`openclaw/default` 是已配置默认智能体的稳定别名。
|
||||
|
||||
这意味着即使不同环境中的真实默认智能体 ID 发生变化，客户端也可以继续使用同一个可预测的 ID。
|
||||
这意味着即使不同环境中的真实默认智能体 id 发生变化，客户端仍可持续使用同一个可预测 id。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="如何覆盖后端模型？">
|
||||
使用 `x-openclaw-model`。
|
||||
|
||||
示例：
|
||||
`x-openclaw-model: openai/gpt-5.4`
|
||||
`x-openclaw-model: gpt-5.4`
|
||||
`x-openclaw-model: openai/gpt-5.5`
|
||||
`x-openclaw-model: gpt-5.5`
|
||||
|
||||
如果省略它，所选智能体会使用其正常配置的模型选择运行。
|
||||
如果省略它，所选智能体会按其正常配置的模型选择运行。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="embeddings 如何适配这个契约？">
|
||||
`/v1/embeddings` 使用相同的智能体目标 `model` ID。
|
||||
`/v1/embeddings` 使用相同的智能体目标 `model` id。
|
||||
|
||||
使用 `model: "openclaw/default"` 或 `model: "openclaw/<agentId>"`。
|
||||
当你需要特定 embedding 模型时，请通过 `x-openclaw-model` 发送。
|
||||
如果没有该头，请求会传递到所选智能体的正常 embedding 设置。
|
||||
当你需要特定的嵌入模型时，请在 `x-openclaw-model` 中发送它。
|
||||
如果没有该标头，请求会透传到所选智能体的常规嵌入配置。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -201,18 +199,18 @@ OpenClaw 将 OpenAI `model` 字段视为**智能体目标**，而不是原始提
|
||||
|
||||
## Open WebUI 快速设置
|
||||
|
||||
对于基本的 Open WebUI 连接：
|
||||
进行基本的 Open WebUI 连接时：
|
||||
|
||||
- 基础 URL：`http://127.0.0.1:18789/v1`
|
||||
- macOS 上 Docker 的基础 URL：`http://host.docker.internal:18789/v1`
|
||||
- API key：你的 Gateway 网关 bearer token
|
||||
- API 密钥：你的 Gateway 网关 bearer token
|
||||
- 模型：`openclaw/default`
|
||||
|
||||
预期行为：
|
||||
|
||||
- `GET /v1/models` 应列出 `openclaw/default`
|
||||
- Open WebUI 应使用 `openclaw/default` 作为聊天模型 ID
|
||||
- 如果你希望该智能体使用特定的后端提供商/模型，请设置该智能体正常的默认模型，或发送 `x-openclaw-model`
|
||||
- Open WebUI 应使用 `openclaw/default` 作为聊天模型 id
|
||||
- 如果你想为该智能体指定特定后端提供商/模型，请设置该智能体的常规默认模型，或发送 `x-openclaw-model`
|
||||
|
||||
快速冒烟测试：
|
||||
|
||||
@ -221,7 +219,7 @@ curl -sS http://127.0.0.1:18789/v1/models \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN'
|
||||
```
|
||||
|
||||
如果该请求返回 `openclaw/default`，大多数 Open WebUI 部署就可以使用相同的基础 URL 和 token 连接。
|
||||
如果返回了 `openclaw/default`，大多数 Open WebUI 配置都可以使用相同的基础 URL 和 token 进行连接。
|
||||
|
||||
## 示例
|
||||
|
||||
@ -243,7 +241,7 @@ curl -sS http://127.0.0.1:18789/v1/chat/completions \
|
||||
curl -N http://127.0.0.1:18789/v1/chat/completions \
|
||||
-H 'Authorization: Bearer YOUR_TOKEN' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'x-openclaw-model: openai/gpt-5.4' \
|
||||
-H 'x-openclaw-model: openai/gpt-5.5' \
|
||||
-d '{
|
||||
"model": "openclaw/research",
|
||||
"stream": true,
|
||||
@ -278,9 +276,9 @@ curl -sS http://127.0.0.1:18789/v1/embeddings \
|
||||
}'
|
||||
```
|
||||
|
||||
注意事项：
|
||||
说明：
|
||||
|
||||
- `/v1/models` 返回的是 OpenClaw 智能体目标，而不是原始提供商目录。
|
||||
- `openclaw/default` 始终存在，因此一个稳定 ID 就可跨环境使用。
|
||||
- 后端提供商/模型覆盖应放在 `x-openclaw-model` 中，而不是 OpenAI `model` 字段中。
|
||||
- `openclaw/default` 始终存在，因此同一个稳定 id 可在不同环境中使用。
|
||||
- 后端提供商/模型覆盖项应放在 `x-openclaw-model` 中，而不是 OpenAI `model` 字段中。
|
||||
- `/v1/embeddings` 支持将 `input` 作为字符串或字符串数组。
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when: You hit 'sandbox jail' or see a tool/elevated refusal and want the exact config key to change.
|
||||
status: active
|
||||
summary: 为什么工具会被阻止：沙箱运行时、工具允许/拒绝策略，以及提权执行门禁
|
||||
title: 沙箱与工具策略与提权执行的区别
|
||||
summary: 工具为何会被阻止：沙箱运行时、工具允许/拒绝策略，以及提权执行门禁
|
||||
title: 沙箱 vs 工具策略 vs 提权执行
|
||||
x-i18n:
|
||||
generated_at: "2026-04-20T18:29:33Z"
|
||||
generated_at: "2026-04-23T19:24:40Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a85378343df0594be451212cb4c95b349a0cc7cd1f242b9306be89903a450db1
|
||||
source_hash: cfc54cdb1adbe37a2cfa837560d3d3862c1aa2732dcb8a73377114d4b873e569
|
||||
source_path: gateway/sandbox-vs-tool-policy-vs-elevated.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 沙箱与工具策略与提权执行的区别
|
||||
# 沙箱 vs 工具策略 vs 提权执行
|
||||
|
||||
OpenClaw 有三种相关但不同的控制方式：
|
||||
OpenClaw 有三个相关但不同的控制项：
|
||||
|
||||
1. **沙箱**（`agents.defaults.sandbox.*` / `agents.list[].sandbox.*`）决定**工具在哪里运行**（沙箱后端还是主机）。
|
||||
2. **工具策略**（`tools.*`、`tools.sandbox.tools.*`、`agents.list[].tools.*`）决定**哪些工具可用 / 被允许**。
|
||||
3. **提权执行**（`tools.elevated.*`、`agents.list[].tools.elevated.*`）是一个**仅限 exec 的逃生通道**：当你处于沙箱中时，可用于在沙箱外运行（默认是 `gateway`，或者当 exec 目标被配置为 `node` 时使用 `node`）。
|
||||
2. **工具策略**（`tools.*`、`tools.sandbox.tools.*`、`agents.list[].tools.*`）决定**哪些工具可用/允许使用**。
|
||||
3. **提权执行**（`tools.elevated.*`、`agents.list[].tools.elevated.*`）是一个**仅针对 exec 的逃逸通道**：当你处于沙箱中时，可让其在沙箱外运行（默认是 `gateway`，或者当 exec 目标配置为 `node` 时使用 `node`）。
|
||||
|
||||
## 快速调试
|
||||
|
||||
使用检查器查看 OpenClaw **实际**在做什么：
|
||||
使用检查器查看 OpenClaw _实际_ 在做什么：
|
||||
|
||||
```bash
|
||||
openclaw sandbox explain
|
||||
@ -33,9 +33,9 @@ openclaw sandbox explain --json
|
||||
|
||||
它会输出：
|
||||
|
||||
- 生效的沙箱模式 / 作用域 / 工作区访问权限
|
||||
- 当前会话是否处于沙箱中（主会话与非主会话）
|
||||
- 生效的沙箱工具允许 / 拒绝设置（以及它来自智能体 / 全局 / 默认配置中的哪一层）
|
||||
- 生效中的沙箱模式 / 作用域 / 工作区访问权限
|
||||
- 当前会话是否处于沙箱中（主会话 vs 非主会话）
|
||||
- 生效中的沙箱工具允许 / 拒绝规则（以及其来源是智能体 / 全局 / 默认值）
|
||||
- 提权执行门禁和修复建议键路径
|
||||
|
||||
## 沙箱：工具在哪里运行
|
||||
@ -43,20 +43,20 @@ openclaw sandbox explain --json
|
||||
沙箱隔离由 `agents.defaults.sandbox.mode` 控制：
|
||||
|
||||
- `"off"`：所有内容都在主机上运行。
|
||||
- `"non-main"`：只有非主会话会进入沙箱（这是群组 / 渠道场景中常见的“意外”来源）。
|
||||
- `"non-main"`：只有非主会话会被沙箱隔离（这是群组 / 渠道中常见的“意外”来源）。
|
||||
- `"all"`：所有内容都在沙箱中运行。
|
||||
|
||||
完整矩阵（作用域、工作区挂载、镜像）请参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
|
||||
|
||||
### 绑定挂载（安全快速检查）
|
||||
|
||||
- `docker.binds` 会**穿透**沙箱文件系统：你挂载的任何内容都会以你设置的模式（`:ro` 或 `:rw`）在容器内可见。
|
||||
- 如果你省略模式，默认是可读写；对于源码 / 密钥，优先使用 `:ro`。
|
||||
- `scope: "shared"` 会忽略每个智能体的独立绑定挂载（只应用全局绑定挂载）。
|
||||
- OpenClaw 会对绑定源进行两次校验：先检查规范化后的源路径，然后在通过最深的现有祖先路径解析后再次检查。通过符号链接父目录逃逸，无法绕过被阻止路径或允许根目录检查。
|
||||
- 不存在的叶子路径也会被安全检查。如果 `/workspace/alias-out/new-file` 通过一个符号链接父目录解析到被阻止路径，或超出已配置的允许根目录范围，该绑定挂载会被拒绝。
|
||||
- 挂载 `/var/run/docker.sock` 实际上等于把主机控制权交给沙箱；只有在你明确知道自己在做什么时才应这样做。
|
||||
- 工作区访问权限（`workspaceAccess: "ro"` / `"rw"`）与绑定挂载模式相互独立。
|
||||
- `docker.binds` 会_穿透_沙箱文件系统：你挂载的任何内容都会以你设置的模式（`:ro` 或 `:rw`）出现在容器内。
|
||||
- 如果省略模式，默认是读写；对于源码 / 密钥，优先使用 `:ro`。
|
||||
- `scope: "shared"` 会忽略按智能体设置的挂载（仅应用全局挂载）。
|
||||
- OpenClaw 会对绑定源路径进行两次验证：首先验证规范化后的源路径，然后在通过最深的现有祖先路径解析后再次验证。基于父级符号链接的逃逸无法绕过阻止路径或允许根路径检查。
|
||||
- 不存在的叶子路径仍会被安全检查。如果 `/workspace/alias-out/new-file` 通过符号链接父路径解析到某个被阻止的路径，或位于已配置允许根路径之外，则该绑定会被拒绝。
|
||||
- 绑定 `/var/run/docker.sock` 实际上等于把主机控制权交给沙箱；只有在你明确有此意图时才应这样做。
|
||||
- 工作区访问（`workspaceAccess: "ro"` / `"rw"`）与绑定模式无关。
|
||||
|
||||
## 工具策略：哪些工具存在 / 可调用
|
||||
|
||||
@ -64,21 +64,21 @@ openclaw sandbox explain --json
|
||||
|
||||
- **工具配置文件**：`tools.profile` 和 `agents.list[].tools.profile`（基础允许列表）
|
||||
- **提供商工具配置文件**：`tools.byProvider[provider].profile` 和 `agents.list[].tools.byProvider[provider].profile`
|
||||
- **全局 / 每智能体工具策略**：`tools.allow` / `tools.deny` 和 `agents.list[].tools.allow` / `agents.list[].tools.deny`
|
||||
- **全局 / 按智能体工具策略**：`tools.allow` / `tools.deny` 和 `agents.list[].tools.allow` / `agents.list[].tools.deny`
|
||||
- **提供商工具策略**：`tools.byProvider[provider].allow/deny` 和 `agents.list[].tools.byProvider[provider].allow/deny`
|
||||
- **沙箱工具策略**（仅在处于沙箱中时生效）：`tools.sandbox.tools.allow` / `tools.sandbox.tools.deny` 和 `agents.list[].tools.sandbox.tools.*`
|
||||
- **沙箱工具策略**（仅在处于沙箱时生效）：`tools.sandbox.tools.allow` / `tools.sandbox.tools.deny` 和 `agents.list[].tools.sandbox.tools.*`
|
||||
|
||||
经验规则：
|
||||
|
||||
- `deny` 永远优先。
|
||||
- 如果 `allow` 非空，其他所有内容都会被视为已阻止。
|
||||
- `deny` 总是优先生效。
|
||||
- 如果 `allow` 非空，则其他所有内容都视为被阻止。
|
||||
- 工具策略是硬性终止条件：`/exec` 不能覆盖被拒绝的 `exec` 工具。
|
||||
- `/exec` 只会为已授权发送者修改会话默认值；它不会授予工具访问权限。
|
||||
提供商工具键既可以使用 `provider`（例如 `google-antigravity`），也可以使用 `provider/model`（例如 `openai/gpt-5.4`）。
|
||||
- `/exec` 只会为已授权发送者更改会话默认值；它不会授予工具访问权限。
|
||||
提供商工具键可接受 `provider`（例如 `google-antigravity`）或 `provider/model`（例如 `openai/gpt-5.5`）。
|
||||
|
||||
### 工具组（简写）
|
||||
|
||||
工具策略（全局、智能体、沙箱）支持 `group:*` 条目，它会展开为多个工具：
|
||||
工具策略（全局、智能体、沙箱）支持 `group:*` 条目，可展开为多个工具：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -92,9 +92,10 @@ openclaw sandbox explain --json
|
||||
}
|
||||
```
|
||||
|
||||
可用的工具组：
|
||||
可用组：
|
||||
|
||||
- `group:runtime`：`exec`、`process`、`code_execution`（`bash` 可作为 `exec` 的别名）
|
||||
- `group:runtime`：`exec`、`process`、`code_execution`（`bash` 可作为
|
||||
`exec` 的别名使用）
|
||||
- `group:fs`：`read`、`write`、`edit`、`apply_patch`
|
||||
- `group:sessions`：`sessions_list`、`sessions_history`、`sessions_send`、`sessions_spawn`、`sessions_yield`、`subagents`、`session_status`
|
||||
- `group:memory`：`memory_search`、`memory_get`
|
||||
@ -105,25 +106,25 @@ openclaw sandbox explain --json
|
||||
- `group:nodes`：`nodes`
|
||||
- `group:agents`：`agents_list`
|
||||
- `group:media`：`image`、`image_generate`、`video_generate`、`tts`
|
||||
- `group:openclaw`：所有内置 OpenClaw 工具（不包括提供商插件）
|
||||
- `group:openclaw`：所有 OpenClaw 内置工具（不包括提供商插件）
|
||||
|
||||
## 提权执行：仅限 exec 的“在主机上运行”
|
||||
## 提权执行：仅针对 exec 的“在主机上运行”
|
||||
|
||||
提权执行**不会**授予额外工具；它只影响 `exec`。
|
||||
|
||||
- 如果你处于沙箱中，`/elevated on`（或带 `elevated: true` 的 `exec`）会在沙箱外运行（仍可能需要审批）。
|
||||
- 使用 `/elevated full` 可跳过该会话中的 exec 审批。
|
||||
- 如果你本来就是直接运行，提权执行实际上没有效果（但仍受门禁控制）。
|
||||
- 提权执行**不**受 Skills 作用域限制，也**不**会覆盖工具允许 / 拒绝策略。
|
||||
- 提权执行不会从 `host=auto` 授予任意跨主机覆盖；它遵循正常的 exec 目标规则，并且只有在配置的 / 会话中的目标本来就是 `node` 时，才会保留 `node`。
|
||||
- `/exec` 与提权执行是分开的。它只会为已授权发送者调整每个会话的 exec 默认值。
|
||||
- 使用 `/elevated full` 可为当前会话跳过 exec 审批。
|
||||
- 如果你已经在直接运行环境中，提权执行实际上不会产生效果（但仍受门禁控制）。
|
||||
- 提权执行**不是** Skills 作用域的，也**不会**覆盖工具允许 / 拒绝规则。
|
||||
- 提权执行不会从 `host=auto` 授予任意跨主机覆盖；它遵循正常的 exec 目标规则，且仅在配置的 / 会话的目标本来就是 `node` 时才保留 `node`。
|
||||
- `/exec` 与提权执行是分开的。它只会为已授权发送者调整按会话生效的 exec 默认值。
|
||||
|
||||
门禁：
|
||||
|
||||
- 启用开关：`tools.elevated.enabled`（以及可选的 `agents.list[].tools.elevated.enabled`）
|
||||
- 启用项：`tools.elevated.enabled`（以及可选的 `agents.list[].tools.elevated.enabled`）
|
||||
- 发送者允许列表：`tools.elevated.allowFrom.<provider>`（以及可选的 `agents.list[].tools.elevated.allowFrom.<provider>`）
|
||||
|
||||
参见 [提权执行模式](/zh-CN/tools/elevated)。
|
||||
请参见 [提权模式](/zh-CN/tools/elevated)。
|
||||
|
||||
## 常见“沙箱牢笼”修复方法
|
||||
|
||||
@ -132,16 +133,16 @@ openclaw sandbox explain --json
|
||||
修复建议键（任选其一）：
|
||||
|
||||
- 禁用沙箱：`agents.defaults.sandbox.mode=off`（或按智能体设置 `agents.list[].sandbox.mode=off`）
|
||||
- 允许该工具在沙箱中使用：
|
||||
- 从 `tools.sandbox.tools.deny` 中移除它（或按智能体从 `agents.list[].tools.sandbox.tools.deny` 中移除）
|
||||
- 或者把它添加到 `tools.sandbox.tools.allow`（或按智能体添加到 allow）
|
||||
- 允许该工具在沙箱内使用：
|
||||
- 将其从 `tools.sandbox.tools.deny` 中移除（或按智能体从 `agents.list[].tools.sandbox.tools.deny` 中移除）
|
||||
- 或将其添加到 `tools.sandbox.tools.allow`（或按智能体添加到 allow）
|
||||
|
||||
### “我以为这是主会话，为什么它在沙箱里？”
|
||||
### “我以为这是主会话，为什么它被沙箱隔离了？”
|
||||
|
||||
在 `"non-main"` 模式下，群组 / 渠道键**不是**主会话。请使用主会话键（由 `sandbox explain` 显示），或将模式切换为 `"off"`。
|
||||
在 `"non-main"` 模式下，群组 / 渠道键_不是_主会话。请使用主会话键（由 `sandbox explain` 显示），或将模式切换为 `"off"`。
|
||||
|
||||
## 另请参见
|
||||
|
||||
- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整的沙箱参考（模式、作用域、后端、镜像）
|
||||
- [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 每个智能体的覆盖项和优先级
|
||||
- [提权执行模式](/zh-CN/tools/elevated)
|
||||
- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整沙箱参考（模式、作用域、后端、镜像）
|
||||
- [多智能体沙箱与工具](/zh-CN/tools/multi-agent-sandbox-tools) -- 按智能体覆盖和优先级
|
||||
- [提权模式](/zh-CN/tools/elevated)
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
@ -1,35 +1,35 @@
|
||||
---
|
||||
read_when:
|
||||
- 在 Fly.io 上部署 OpenClaw
|
||||
- 设置 Fly volume、密钥和首次运行配置
|
||||
summary: 在 Fly.io 上逐步部署 OpenClaw，包含持久化存储和 HTTPS
|
||||
- 设置 Fly 卷、密钥和首次运行配置
|
||||
summary: 面向 OpenClaw 的 Fly.io 逐步部署指南，包含持久化存储和 HTTPS
|
||||
title: Fly.io
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T08:27:10Z"
|
||||
generated_at: "2026-04-23T19:25:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a5f8c2c03295d786c0d8df98f8a5ae9335fa0346a188b81aae3e07d566a2c0ef
|
||||
source_hash: 565bae44242217f7a2fa118fbdb1c2f4b989fed1d1fa011129a0983f1f5997f6
|
||||
source_path: install/fly.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Fly.io 部署
|
||||
|
||||
**目标：** 在 [Fly.io](https://fly.io) 机器上运行 OpenClaw Gateway 网关，具备持久化存储、自动 HTTPS 和 Discord/渠道访问能力。
|
||||
**目标：** 让 OpenClaw Gateway 网关运行在 [Fly.io](https://fly.io) 机器上，并具备持久化存储、自动 HTTPS，以及 Discord/渠道访问能力。
|
||||
|
||||
## 你需要准备的内容
|
||||
|
||||
- 已安装 [flyctl CLI](https://fly.io/docs/hands-on/install-flyctl/)
|
||||
- Fly.io 账户（免费层可用）
|
||||
- 模型鉴权：你所选模型提供商的 API 密钥
|
||||
- 渠道凭证：Discord 机器人 token、Telegram token 等
|
||||
- 一个 Fly.io 账号（免费层即可）
|
||||
- 模型认证：你所选模型提供商的 API 密钥
|
||||
- 渠道凭证：Discord 机器人令牌、Telegram 令牌等
|
||||
|
||||
## 面向初学者的快速路径
|
||||
## 面向新手的快速路径
|
||||
|
||||
1. 克隆仓库 → 自定义 `fly.toml`
|
||||
2. 创建应用 + volume → 设置密钥
|
||||
2. 创建应用和卷 → 设置密钥
|
||||
3. 使用 `fly deploy` 部署
|
||||
4. SSH 登录创建配置，或使用 Control UI
|
||||
4. 通过 SSH 登录以创建配置，或使用控制 UI
|
||||
|
||||
<Steps>
|
||||
<Step title="创建 Fly 应用">
|
||||
@ -38,21 +38,21 @@ x-i18n:
|
||||
git clone https://github.com/openclaw/openclaw.git
|
||||
cd openclaw
|
||||
|
||||
# 创建新的 Fly 应用（请自行选择名称）
|
||||
# 创建一个新的 Fly 应用（请自行选择名称）
|
||||
fly apps create my-openclaw
|
||||
|
||||
# 创建持久化 volume（通常 1GB 就足够）
|
||||
# 创建一个持久卷（通常 1GB 就够用）
|
||||
fly volumes create openclaw_data --size 1 --region iad
|
||||
```
|
||||
|
||||
**提示：** 选择离你最近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。
|
||||
**提示：** 选择一个离你较近的区域。常见选项：`lhr`（伦敦）、`iad`（弗吉尼亚）、`sjc`（圣何塞）。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="配置 fly.toml">
|
||||
编辑 `fly.toml` 以匹配你的应用名称和需求。
|
||||
编辑 `fly.toml`，使其符合你的应用名称和需求。
|
||||
|
||||
**安全说明：** 默认配置会暴露一个公共 URL。如果你想要无公网 IP 的加固部署，请参见[私有部署](#private-deployment-hardened)或使用 `fly.private.toml`。
|
||||
**安全说明：** 默认配置会公开一个公共 URL。若需不带公共 IP 的强化部署，请参见 [Private Deployment](#private-deployment-hardened) 或使用 `fly.private.toml`。
|
||||
|
||||
```toml
|
||||
app = "my-openclaw" # 你的应用名称
|
||||
@ -89,19 +89,19 @@ x-i18n:
|
||||
|
||||
**关键设置：**
|
||||
|
||||
| Setting | Why |
|
||||
| 设置 | 原因 |
|
||||
| ------------------------------ | --------------------------------------------------------------------------- |
|
||||
| `--bind lan` | 绑定到 `0.0.0.0`，这样 Fly 的代理才能访问 Gateway 网关 |
|
||||
| `--allow-unconfigured` | 在没有配置文件的情况下启动（你稍后会创建） |
|
||||
| `internal_port = 3000` | 必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）匹配，以通过 Fly 健康检查 |
|
||||
| `memory = "2048mb"` | 512MB 太小；建议使用 2GB |
|
||||
| `OPENCLAW_STATE_DIR = "/data"` | 将状态持久化到 volume |
|
||||
| `--bind lan` | 绑定到 `0.0.0.0`，这样 Fly 的代理才能访问 Gateway 网关 |
|
||||
| `--allow-unconfigured` | 可在没有配置文件的情况下启动（你会在之后创建它） |
|
||||
| `internal_port = 3000` | 必须与 `--port 3000`（或 `OPENCLAW_GATEWAY_PORT`）一致，以通过 Fly 健康检查 |
|
||||
| `memory = "2048mb"` | 512MB 太小；推荐 2GB |
|
||||
| `OPENCLAW_STATE_DIR = "/data"` | 将状态持久保存到卷中 |
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="设置密钥">
|
||||
```bash
|
||||
# 必需：Gateway 网关 token（用于非 loopback 绑定）
|
||||
# 必需：Gateway 网关令牌（用于非 loopback 绑定）
|
||||
fly secrets set OPENCLAW_GATEWAY_TOKEN=$(openssl rand -hex 32)
|
||||
|
||||
# 模型提供商 API 密钥
|
||||
@ -111,15 +111,15 @@ x-i18n:
|
||||
fly secrets set OPENAI_API_KEY=sk-...
|
||||
fly secrets set GOOGLE_API_KEY=...
|
||||
|
||||
# 渠道 token
|
||||
# 渠道令牌
|
||||
fly secrets set DISCORD_BOT_TOKEN=MTQ...
|
||||
```
|
||||
|
||||
**说明：**
|
||||
|
||||
- 非 loopback 绑定（`--bind lan`）要求存在有效的 Gateway 网关鉴权路径。这个 Fly.io 示例使用 `OPENCLAW_GATEWAY_TOKEN`，但 `gateway.auth.password` 或正确配置的非 loopback `trusted-proxy` 部署也满足要求。
|
||||
- 请将这些 token 视为密码。
|
||||
- **所有 API 密钥和 token 都优先使用环境变量，而不是配置文件。** 这样可以避免将密钥写入 `openclaw.json`，从而降低被意外暴露或记录的风险。
|
||||
- 非 loopback 绑定（`--bind lan`）要求存在有效的 Gateway 网关认证路径。本 Fly.io 示例使用 `OPENCLAW_GATEWAY_TOKEN`，但 `gateway.auth.password` 或配置正确的非 loopback `trusted-proxy` 部署也能满足该要求。
|
||||
- 像对待密码一样对待这些令牌。
|
||||
- 对所有 API 密钥和令牌，**优先使用环境变量而不是配置文件**。这样可以避免密钥出现在 `openclaw.json` 中，降低意外暴露或被记录到日志中的风险。
|
||||
|
||||
</Step>
|
||||
|
||||
@ -128,16 +128,16 @@ x-i18n:
|
||||
fly deploy
|
||||
```
|
||||
|
||||
首次部署会构建 Docker 镜像（约 2-3 分钟）。后续部署会更快。
|
||||
首次部署会构建 Docker 镜像（约 2–3 分钟）。后续部署会更快。
|
||||
|
||||
部署后，验证：
|
||||
部署后，请验证：
|
||||
|
||||
```bash
|
||||
fly status
|
||||
fly logs
|
||||
```
|
||||
|
||||
你应该看到：
|
||||
你应该会看到：
|
||||
|
||||
```
|
||||
[gateway] listening on ws://0.0.0.0:3000 (PID xxx)
|
||||
@ -147,7 +147,7 @@ x-i18n:
|
||||
</Step>
|
||||
|
||||
<Step title="创建配置文件">
|
||||
通过 SSH 登录机器以创建正式配置：
|
||||
通过 SSH 登录到机器以创建正式配置：
|
||||
|
||||
```bash
|
||||
fly ssh console
|
||||
@ -163,7 +163,7 @@ x-i18n:
|
||||
"defaults": {
|
||||
"model": {
|
||||
"primary": "anthropic/claude-opus-4-6",
|
||||
"fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.4"]
|
||||
"fallbacks": ["anthropic/claude-sonnet-4-6", "openai/gpt-5.5"]
|
||||
},
|
||||
"maxConcurrent": 4
|
||||
},
|
||||
@ -207,14 +207,14 @@ x-i18n:
|
||||
EOF
|
||||
```
|
||||
|
||||
**说明：** 由于 `OPENCLAW_STATE_DIR=/data`，配置路径是 `/data/openclaw.json`。
|
||||
**注意：** 由于设置了 `OPENCLAW_STATE_DIR=/data`，配置路径为 `/data/openclaw.json`。
|
||||
|
||||
**说明：** Discord token 可以来自以下任一方式：
|
||||
**注意：** Discord 令牌可以来自以下任一位置：
|
||||
|
||||
- 环境变量：`DISCORD_BOT_TOKEN`（推荐用于密钥）
|
||||
- 环境变量：`DISCORD_BOT_TOKEN`（推荐用于存放密钥）
|
||||
- 配置文件：`channels.discord.token`
|
||||
|
||||
如果使用环境变量，就无需把 token 添加到配置中。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。
|
||||
如果使用环境变量，则无需将令牌加入配置中。Gateway 网关会自动读取 `DISCORD_BOT_TOKEN`。
|
||||
|
||||
重启以应用配置：
|
||||
|
||||
@ -226,7 +226,7 @@ x-i18n:
|
||||
</Step>
|
||||
|
||||
<Step title="访问 Gateway 网关">
|
||||
### Control UI
|
||||
### 控制 UI
|
||||
|
||||
在浏览器中打开：
|
||||
|
||||
@ -236,9 +236,7 @@ x-i18n:
|
||||
|
||||
或访问 `https://my-openclaw.fly.dev/`
|
||||
|
||||
使用已配置的共享密钥进行鉴权。本指南使用来自 `OPENCLAW_GATEWAY_TOKEN` 的 Gateway 网关
|
||||
token；如果你改用了密码鉴权，请改用
|
||||
该密码。
|
||||
使用已配置的共享密钥进行认证。本指南使用 `OPENCLAW_GATEWAY_TOKEN` 中的 Gateway 网关令牌；如果你改用了密码认证，请改用该密码。
|
||||
|
||||
### 日志
|
||||
|
||||
@ -262,19 +260,19 @@ x-i18n:
|
||||
|
||||
Gateway 网关绑定到了 `127.0.0.1`，而不是 `0.0.0.0`。
|
||||
|
||||
**修复：** 在 `fly.toml` 的进程命令中添加 `--bind lan`。
|
||||
**修复方法：** 在 `fly.toml` 的进程命令中添加 `--bind lan`。
|
||||
|
||||
### 健康检查失败 / 连接被拒绝
|
||||
### 健康检查失败 / connection refused
|
||||
|
||||
Fly 无法通过配置端口访问 Gateway 网关。
|
||||
Fly 无法通过配置的端口访问 Gateway 网关。
|
||||
|
||||
**修复：** 确保 `internal_port` 与 Gateway 网关端口匹配（设置 `--port 3000` 或 `OPENCLAW_GATEWAY_PORT=3000`）。
|
||||
**修复方法：** 确保 `internal_port` 与 Gateway 网关端口一致（设置 `--port 3000` 或 `OPENCLAW_GATEWAY_PORT=3000`）。
|
||||
|
||||
### OOM / 内存问题
|
||||
|
||||
容器不断重启或被杀死。迹象包括：`SIGABRT`、`v8::internal::Runtime_AllocateInYoungGeneration` 或静默重启。
|
||||
容器持续重启或被杀死。迹象包括：`SIGABRT`、`v8::internal::Runtime_AllocateInYoungGeneration`，或无提示重启。
|
||||
|
||||
**修复：** 增加 `fly.toml` 中的内存：
|
||||
**修复方法：** 增加 `fly.toml` 中的内存：
|
||||
|
||||
```toml
|
||||
[[vm]]
|
||||
@ -287,15 +285,15 @@ Fly 无法通过配置端口访问 Gateway 网关。
|
||||
fly machine update <machine-id> --vm-memory 2048 -y
|
||||
```
|
||||
|
||||
**说明：** 512MB 太小。1GB 可能可以运行，但在负载较高或启用详细日志时可能 OOM。**建议使用 2GB。**
|
||||
**注意：** 512MB 太小。1GB 也许能运行，但在有负载或启用详细日志时可能会 OOM。**推荐使用 2GB。**
|
||||
|
||||
### Gateway 网关锁问题
|
||||
### Gateway 网关锁文件问题
|
||||
|
||||
Gateway 网关因“already running”错误而拒绝启动。
|
||||
Gateway 网关拒绝启动，并报出 “already running” 错误。
|
||||
|
||||
当容器重启但 PID 锁文件仍保留在 volume 上时，就会出现这种情况。
|
||||
这通常发生在容器重启后，但 PID 锁文件仍保留在卷中。
|
||||
|
||||
**修复：** 删除锁文件：
|
||||
**修复方法：** 删除锁文件：
|
||||
|
||||
```bash
|
||||
fly ssh console --command "rm -f /data/gateway.*.lock"
|
||||
@ -306,7 +304,7 @@ fly machine restart <machine-id>
|
||||
|
||||
### 未读取配置
|
||||
|
||||
`--allow-unconfigured` 只会绕过启动保护。它不会创建或修复 `/data/openclaw.json`，所以请确保你的实际配置存在，并且在你希望正常以本地 Gateway 网关方式启动时包含 `gateway.mode="local"`。
|
||||
`--allow-unconfigured` 只会绕过启动保护。它不会创建或修复 `/data/openclaw.json`，因此请确保你的实际配置存在，并且在你希望正常以本地模式启动 Gateway 网关时包含 `gateway.mode="local"`。
|
||||
|
||||
验证配置是否存在：
|
||||
|
||||
@ -319,7 +317,7 @@ fly ssh console --command "cat /data/openclaw.json"
|
||||
`fly ssh console -C` 命令不支持 shell 重定向。要写入配置文件：
|
||||
|
||||
```bash
|
||||
# 使用 echo + tee（从本地通过管道传到远程）
|
||||
# 使用 echo + tee（从本地管道到远程）
|
||||
echo '{"your":"config"}' | fly ssh console -C "tee /data/openclaw.json"
|
||||
|
||||
# 或使用 sftp
|
||||
@ -327,18 +325,18 @@ fly sftp shell
|
||||
> put /local/path/config.json /data/openclaw.json
|
||||
```
|
||||
|
||||
**说明：** 如果文件已存在，`fly sftp` 可能失败。请先删除：
|
||||
**注意：** 如果文件已存在，`fly sftp` 可能会失败。请先删除：
|
||||
|
||||
```bash
|
||||
fly ssh console --command "rm /data/openclaw.json"
|
||||
```
|
||||
|
||||
### 状态未持久化
|
||||
### 状态未持久保存
|
||||
|
||||
如果你在重启后丢失 auth profile、渠道/提供商状态或会话，
|
||||
说明状态目录写到了容器文件系统中。
|
||||
如果重启后你丢失了认证配置档、渠道/提供商状态或会话数据，
|
||||
说明状态目录被写入到了容器文件系统中。
|
||||
|
||||
**修复：** 确保在 `fly.toml` 中设置了 `OPENCLAW_STATE_DIR=/data`，然后重新部署。
|
||||
**修复方法：** 确保在 `fly.toml` 中设置了 `OPENCLAW_STATE_DIR=/data`，然后重新部署。
|
||||
|
||||
## 更新
|
||||
|
||||
@ -356,7 +354,7 @@ fly logs
|
||||
|
||||
### 更新机器命令
|
||||
|
||||
如果你需要在不完整重新部署的情况下更改启动命令：
|
||||
如果你需要在不完整重新部署的情况下修改启动命令：
|
||||
|
||||
```bash
|
||||
# 获取机器 ID
|
||||
@ -369,49 +367,49 @@ fly machine update <machine-id> --command "node dist/index.js gateway --port 300
|
||||
fly machine update <machine-id> --vm-memory 2048 --command "node dist/index.js gateway --port 3000 --bind lan" -y
|
||||
```
|
||||
|
||||
**说明：** 在执行 `fly deploy` 后，机器命令可能会重置为 `fly.toml` 中的内容。如果你做过手动更改，请在部署后重新应用这些更改。
|
||||
**注意：** 执行 `fly deploy` 后，机器命令可能会重置为 `fly.toml` 中的内容。如果你做过手动修改，请在部署后重新应用这些修改。
|
||||
|
||||
## 私有部署（加固版）
|
||||
## 私有部署（强化版）
|
||||
|
||||
默认情况下，Fly 会分配公网 IP，这意味着你的 Gateway 网关可以通过 `https://your-app.fly.dev` 访问。这很方便，但也意味着你的部署可被互联网扫描器（Shodan、Censys 等）发现。
|
||||
默认情况下，Fly 会分配公共 IP，这会让你的 Gateway 网关可通过 `https://your-app.fly.dev` 访问。这样做很方便，但也意味着你的部署可被互联网扫描器（Shodan、Censys 等）发现。
|
||||
|
||||
如果你希望获得**完全不暴露公网**的加固部署，请使用私有模板。
|
||||
如果你希望进行**完全不对公网暴露**的强化部署，请使用私有模板。
|
||||
|
||||
### 何时使用私有部署
|
||||
|
||||
- 你只进行**出站**调用/消息（没有入站 webhook）
|
||||
- 你为任何 webhook 回调使用 **ngrok 或 Tailscale** 隧道
|
||||
- 你只进行**出站**调用/发消息（没有入站 webhook）
|
||||
- 你使用 **ngrok 或 Tailscale** 隧道处理所有 webhook 回调
|
||||
- 你通过 **SSH、代理或 WireGuard** 访问 Gateway 网关，而不是浏览器
|
||||
- 你希望部署**对互联网扫描器隐藏**
|
||||
|
||||
### 设置
|
||||
|
||||
使用 `fly.private.toml`，而不是标准配置：
|
||||
使用 `fly.private.toml` 而不是标准配置：
|
||||
|
||||
```bash
|
||||
# 使用私有配置部署
|
||||
fly deploy -c fly.private.toml
|
||||
```
|
||||
|
||||
或者将现有部署转换为私有：
|
||||
或者将现有部署转换为私有部署：
|
||||
|
||||
```bash
|
||||
# 列出当前 IP
|
||||
fly ips list -a my-openclaw
|
||||
|
||||
# 释放公网 IP
|
||||
# 释放公共 IP
|
||||
fly ips release <public-ipv4> -a my-openclaw
|
||||
fly ips release <public-ipv6> -a my-openclaw
|
||||
|
||||
# 切换到私有配置，以便后续部署不会重新分配公网 IP
|
||||
# （移除 [http_service]，或使用私有模板部署）
|
||||
# 切换到私有配置，这样未来部署就不会重新分配公共 IP
|
||||
# （移除 [http_service] 或使用私有模板部署）
|
||||
fly deploy -c fly.private.toml
|
||||
|
||||
# 分配仅私有 IPv6
|
||||
# 分配仅私有的 IPv6
|
||||
fly ips allocate-v6 --private -a my-openclaw
|
||||
```
|
||||
|
||||
此后，`fly ips list` 应只显示一个 `private` 类型 IP：
|
||||
完成后，`fly ips list` 应只显示一个 `private` 类型 IP：
|
||||
|
||||
```
|
||||
VERSION IP TYPE REGION
|
||||
@ -420,12 +418,12 @@ v6 fdaa:x:x:x:x::x private global
|
||||
|
||||
### 访问私有部署
|
||||
|
||||
由于没有公共 URL，请使用以下方式之一：
|
||||
由于没有公共 URL，请使用以下任一方式：
|
||||
|
||||
**选项 1：本地代理（最简单）**
|
||||
|
||||
```bash
|
||||
# 将本地端口 3000 转发到应用
|
||||
# 将本地 3000 端口转发到应用
|
||||
fly proxy 3000:3000 -a my-openclaw
|
||||
|
||||
# 然后在浏览器中打开 http://localhost:3000
|
||||
@ -447,15 +445,15 @@ fly wireguard create
|
||||
fly ssh console -a my-openclaw
|
||||
```
|
||||
|
||||
### 私有部署中的 webhook
|
||||
### 私有部署中的 Webhooks
|
||||
|
||||
如果你在不暴露公网的情况下仍然需要 webhook 回调（Twilio、Telnyx 等）：
|
||||
如果你在不公开暴露的前提下仍需要 webhook 回调（Twilio、Telnyx 等）：
|
||||
|
||||
1. **ngrok 隧道** —— 在容器内或作为 sidecar 运行 ngrok
|
||||
2. **Tailscale Funnel** —— 通过 Tailscale 暴露特定路径
|
||||
3. **仅出站** —— 某些提供商（Twilio）在没有 webhook 的情况下也能正常进行出站呼叫
|
||||
1. **ngrok 隧道** - 在容器内或作为 sidecar 运行 ngrok
|
||||
2. **Tailscale Funnel** - 通过 Tailscale 暴露特定路径
|
||||
3. **仅出站** - 某些提供商（如 Twilio）在无 webhook 的情况下也能良好支持出站呼叫
|
||||
|
||||
使用 ngrok 的语音通话配置示例：
|
||||
语音通话使用 ngrok 的配置示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -476,36 +474,36 @@ fly ssh console -a my-openclaw
|
||||
}
|
||||
```
|
||||
|
||||
ngrok 隧道运行在容器内，并提供公共 webhook URL，而不会暴露 Fly 应用本身。请将 `webhookSecurity.allowedHosts` 设置为该公共隧道主机名，以便接受转发后的 host header。
|
||||
ngrok 隧道在容器内部运行，并提供一个公共 webhook URL，而不会暴露 Fly 应用本身。请将 `webhookSecurity.allowedHosts` 设置为该公共隧道主机名，这样才会接受被转发的 Host 请求头。
|
||||
|
||||
### 安全收益
|
||||
|
||||
| Aspect | Public | Private |
|
||||
| 方面 | 公共部署 | 私有部署 |
|
||||
| ----------------- | ------------ | ---------- |
|
||||
| Internet scanners | 可发现 | 隐藏 |
|
||||
| Direct attacks | 可能 | 被阻止 |
|
||||
| Control UI access | 浏览器 | 代理/VPN |
|
||||
| Webhook delivery | 直接 | 通过隧道 |
|
||||
| 互联网扫描器 | 可发现 | 已隐藏 |
|
||||
| 直接攻击 | 可能 | 已阻止 |
|
||||
| 控制 UI 访问 | 浏览器 | 代理/VPN |
|
||||
| webhook 投递 | 直接 | 通过隧道 |
|
||||
|
||||
## 说明
|
||||
|
||||
- Fly.io 使用 **x86 架构**（不是 ARM）
|
||||
- Dockerfile 兼容两种架构
|
||||
- Fly.io 使用的是 **x86 架构**（不是 ARM）
|
||||
- Dockerfile 同时兼容这两种架构
|
||||
- 对于 WhatsApp/Telegram 新手引导，请使用 `fly ssh console`
|
||||
- 持久化数据位于 `/data` volume 上
|
||||
- 持久化数据存储在卷的 `/data` 路径下
|
||||
- Signal 需要 Java + signal-cli；请使用自定义镜像，并将内存保持在 2GB 以上。
|
||||
|
||||
## 成本
|
||||
|
||||
使用推荐配置（`shared-cpu-2x`，2GB RAM）时：
|
||||
使用推荐配置（`shared-cpu-2x`、2GB RAM）时：
|
||||
|
||||
- 约 $10-15/月，取决于使用情况
|
||||
- 取决于使用情况，约为每月 10–15 美元
|
||||
- 免费层包含一定额度
|
||||
|
||||
详情请参见 [Fly.io pricing](https://fly.io/docs/about/pricing/)。
|
||||
|
||||
## 后续步骤
|
||||
|
||||
- 设置消息渠道：[Channels](/channels)
|
||||
- 配置 Gateway 网关：[Gateway configuration](/gateway/configuration)
|
||||
- 让 OpenClaw 保持最新：[Updating](/install/updating)
|
||||
- 设置消息渠道：[Channels](/zh-CN/channels)
|
||||
- 配置 Gateway 网关：[Gateway configuration](/zh-CN/gateway/configuration)
|
||||
- 保持 OpenClaw 为最新版本：[Updating](/zh-CN/install/updating)
|
||||
|
||||
@ -1,58 +1,58 @@
|
||||
---
|
||||
read_when:
|
||||
- 设计或重构媒体理解
|
||||
- 调整入站音频/视频/图像预处理
|
||||
summary: 入站图像/音频/视频理解（可选），并提供提供商 + CLI 回退方案
|
||||
- 调优入站音频/视频/图像预处理
|
||||
summary: 入站图像/音频/视频理解（可选），支持提供商 + CLI 回退方案
|
||||
title: 媒体理解
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T00:08:05Z"
|
||||
generated_at: "2026-04-23T19:25:16Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 5bb2d0eab59d857c2849f329435f8fad3eeff427f7984d011bd5b7d9fd7bf51c
|
||||
source_hash: 89e89b0db8cc4a53270492ce5dfa1bb0a0d0f2dec7f4900ea9984bf98bbbc189
|
||||
source_path: nodes/media-understanding.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 媒体理解 - 入站（2026-01-17）
|
||||
|
||||
OpenClaw 可以在回复流水线运行前，**总结入站媒体**（图像/音频/视频）。它会在检测到本地工具或提供商密钥可用时自动启用，也可以被禁用或自定义。如果理解功能关闭，模型仍会像往常一样接收原始文件/URL。
|
||||
OpenClaw 可以在回复流水线运行前**总结入站媒体**（图像/音频/视频）。它会在本地工具或提供商密钥可用时自动检测，也可以被禁用或自定义。如果理解功能关闭，模型仍会像往常一样接收原始文件/URL。
|
||||
|
||||
特定厂商的媒体行为由厂商插件注册，而 OpenClaw
|
||||
核心负责共享的 `tools.media` 配置、回退顺序以及回复流水线集成。
|
||||
核心负责共享的 `tools.media` 配置、回退顺序，以及与回复流水线的集成。
|
||||
|
||||
## 目标
|
||||
|
||||
- 可选：将入站媒体预先整理为简短文本，以实现更快的路由和更好的命令解析。
|
||||
- 始终保留向模型传递原始媒体。
|
||||
- 支持 **provider API** 和 **CLI 回退方案**。
|
||||
- 允许多个模型按顺序回退（错误/大小/超时）。
|
||||
- 支持**提供商 API** 和 **CLI 回退方案**。
|
||||
- 允许多个模型并按顺序回退（错误/大小/超时）。
|
||||
|
||||
## 高层行为
|
||||
|
||||
1. 收集入站附件（`MediaPaths`、`MediaUrls`、`MediaTypes`）。
|
||||
2. 对每个已启用的能力，按策略选择附件（默认：**第一个**）。
|
||||
3. 选择第一个符合条件的模型条目（大小 + 能力 + 认证）。
|
||||
4. 如果模型失败或媒体过大，**回退到下一个条目**。
|
||||
2. 对每种已启用能力（图像/音频/视频），按策略选择附件（默认：**第一个**）。
|
||||
3. 选择第一个符合条件的模型条目（大小 + 能力 + 身份验证）。
|
||||
4. 如果某个模型失败或媒体过大，则**回退到下一个条目**。
|
||||
5. 成功时：
|
||||
- `Body` 变为 `[Image]`、`[Audio]` 或 `[Video]` 块。
|
||||
- 音频会设置 `{{Transcript}}`；如果存在说明文字，命令解析使用说明文字，否则使用转录文本。
|
||||
- 说明文字会作为 `User text:` 保留在块中。
|
||||
- `Body` 会变成 `[Image]`、`[Audio]` 或 `[Video]` 区块。
|
||||
- 音频会设置 `{{Transcript}}`；存在说明文字时，命令解析使用说明文字，否则使用转录文本。
|
||||
- 说明文字会作为 `User text:` 保留在区块内。
|
||||
|
||||
如果理解失败或被禁用，**回复流程会继续**，并使用原始正文 + 附件。
|
||||
|
||||
## 配置概览
|
||||
|
||||
`tools.media` 支持**共享模型**以及按能力分别覆盖：
|
||||
`tools.media` 支持**共享模型**以及按能力划分的覆盖项：
|
||||
|
||||
- `tools.media.models`：共享模型列表（使用 `capabilities` 进行限制）。
|
||||
- `tools.media.image` / `tools.media.audio` / `tools.media.video`：
|
||||
- 默认值（`prompt`、`maxChars`、`maxBytes`、`timeoutSeconds`、`language`）
|
||||
- 提供商覆盖（`baseUrl`、`headers`、`providerOptions`）
|
||||
- 提供商覆盖项（`baseUrl`、`headers`、`providerOptions`）
|
||||
- 通过 `tools.media.audio.providerOptions.deepgram` 设置 Deepgram 音频选项
|
||||
- 音频转录回显控制（`echoTranscript`，默认 `false`；`echoFormat`）
|
||||
- 可选的**按能力划分的 `models` 列表**（优先于共享模型）
|
||||
- `attachments` 策略（`mode`、`maxAttachments`、`prefer`）
|
||||
- `scope`（可选，按渠道/聊天类型/会话键进行限制）
|
||||
- `scope`（可选，按渠道/chatType/会话键进行限制）
|
||||
- `tools.media.concurrency`：最大并发能力运行数（默认 **2**）。
|
||||
|
||||
```json5
|
||||
@ -63,15 +63,15 @@ OpenClaw 可以在回复流水线运行前，**总结入站媒体**（图像/音
|
||||
/* 共享列表 */
|
||||
],
|
||||
image: {
|
||||
/* 可选覆盖 */
|
||||
/* 可选覆盖项 */
|
||||
},
|
||||
audio: {
|
||||
/* 可选覆盖 */
|
||||
/* 可选覆盖项 */
|
||||
echoTranscript: true,
|
||||
echoFormat: '📝 "{transcript}"',
|
||||
},
|
||||
video: {
|
||||
/* 可选覆盖 */
|
||||
/* 可选覆盖项 */
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -80,13 +80,13 @@ OpenClaw 可以在回复流水线运行前，**总结入站媒体**（图像/音
|
||||
|
||||
### 模型条目
|
||||
|
||||
每个 `models[]` 条目都可以是 **provider** 或 **CLI**：
|
||||
每个 `models[]` 条目都可以是**提供商**或 **CLI**：
|
||||
|
||||
```json5
|
||||
{
|
||||
type: "provider", // 如果省略则为默认值
|
||||
type: "provider", // 如果省略，则默认为该值
|
||||
provider: "openai",
|
||||
model: "gpt-5.4-mini",
|
||||
model: "gpt-5.5",
|
||||
prompt: "Describe the image in <= 500 chars.",
|
||||
maxChars: 500,
|
||||
maxBytes: 10485760,
|
||||
@ -119,9 +119,9 @@ CLI 模板还可以使用：
|
||||
|
||||
- `{{MediaDir}}`（包含媒体文件的目录）
|
||||
- `{{OutputDir}}`（为本次运行创建的临时目录）
|
||||
- `{{OutputBase}}`（临时文件基础路径，不带扩展名）
|
||||
- `{{OutputBase}}`（临时输出文件基础路径，不含扩展名）
|
||||
|
||||
## 默认值和限制
|
||||
## 默认值与限制
|
||||
|
||||
推荐默认值：
|
||||
|
||||
@ -134,32 +134,30 @@ CLI 模板还可以使用：
|
||||
|
||||
规则：
|
||||
|
||||
- 如果媒体超过 `maxBytes`，该模型将被跳过，并**尝试下一个模型**。
|
||||
- 小于 **1024 字节**的音频文件会被视为空/损坏，并在 provider/CLI 转录前跳过。
|
||||
- 如果媒体超过 `maxBytes`，则跳过该模型并**尝试下一个模型**。
|
||||
- 小于 **1024 字节**的音频文件会被视为空或损坏，并在提供商/CLI 转录之前跳过。
|
||||
- 如果模型返回的内容超过 `maxChars`，输出会被截断。
|
||||
- `prompt` 默认为简单的 “Describe the {media}.”，并附带 `maxChars` 指引（仅图像/视频）。
|
||||
- 如果当前主图像模型已经原生支持视觉能力，OpenClaw
|
||||
会跳过 `[Image]` 摘要块，而是直接将原始图像传递给模型。
|
||||
- 显式的 `openclaw infer image describe --model <provider/model>` 请求不同：它们会直接运行该支持图像能力的 provider/model，包括
|
||||
`ollama/qwen2.5vl:7b` 这类 Ollama 引用。
|
||||
- 如果 `<capability>.enabled: true` 但未配置任何模型，当其 provider 支持该能力时，OpenClaw 会尝试使用**当前活动回复模型**。
|
||||
- 如果当前激活的主图像模型本身已原生支持视觉能力，OpenClaw
|
||||
会跳过 `[Image]` 摘要区块，而是将原始图像直接传给模型。
|
||||
- 显式的 `openclaw infer image describe --model <provider/model>` 请求则不同：它们会直接运行该具备图像能力的 provider/model，包括诸如 `ollama/qwen2.5vl:7b` 这样的 Ollama 引用。
|
||||
- 如果 `<capability>.enabled: true` 但未配置任何模型，当其提供商支持该能力时，OpenClaw 会尝试使用**当前激活的回复模型**。
|
||||
|
||||
### 自动检测媒体理解（默认）
|
||||
|
||||
如果 `tools.media.<capability>.enabled` **未**设置为 `false`，并且你没有配置模型，OpenClaw 会按以下顺序自动检测，并在**第一个可用选项**处停止：
|
||||
如果 `tools.media.<capability>.enabled` **未**被设置为 `false`，并且你尚未配置模型，OpenClaw 会按以下顺序自动检测，并在**找到第一个可用选项后停止**：
|
||||
|
||||
1. **当前活动回复模型**，前提是其 provider 支持该能力。
|
||||
1. **当前激活的回复模型**，前提是其提供商支持该能力。
|
||||
2. **`agents.defaults.imageModel`** 主/回退引用（仅图像）。
|
||||
3. **本地 CLI**（仅音频；如果已安装）
|
||||
- `sherpa-onnx-offline`（需要 `SHERPA_ONNX_MODEL_DIR`，其中包含 encoder/decoder/joiner/tokens）
|
||||
- `whisper-cli`（`whisper-cpp`；使用 `WHISPER_CPP_MODEL` 或内置的 tiny 模型）
|
||||
- `whisper`（Python CLI；自动下载模型）
|
||||
4. **Gemini CLI**（`gemini`），使用 `read_many_files`
|
||||
5. **提供商认证**
|
||||
- 已配置的、支持该能力的 `models.providers.*` 条目会优先于内置回退顺序进行尝试。
|
||||
- 仅图像的配置提供商，只要包含支持图像能力的模型，即使它们不是内置厂商插件，也会自动注册用于媒体理解。
|
||||
- 当显式选择时，Ollama 图像理解可用，例如通过 `agents.defaults.imageModel` 或
|
||||
`openclaw infer image describe --model ollama/<vision-model>`。
|
||||
5. **提供商身份验证**
|
||||
- 已配置的 `models.providers.*` 条目中，支持该能力的会在内置回退顺序之前尝试。
|
||||
- 使用具备图像能力模型的仅图像配置提供商，即使不是内置厂商插件，也会自动为媒体理解注册。
|
||||
- 当显式选择时，Ollama 图像理解可用，例如通过 `agents.defaults.imageModel` 或 `openclaw infer image describe --model ollama/<vision-model>`。
|
||||
- 内置回退顺序：
|
||||
- 音频：OpenAI → Groq → xAI → Deepgram → Google → Mistral
|
||||
- 图像：OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI
|
||||
@ -179,24 +177,24 @@ CLI 模板还可以使用：
|
||||
}
|
||||
```
|
||||
|
||||
注意：二进制检测在 macOS/Linux/Windows 上均为尽力而为；请确保 CLI 在 `PATH` 中（我们会展开 `~`），或者设置带完整命令路径的显式 CLI 模型。
|
||||
注意：在 macOS/Linux/Windows 上，二进制检测都只是尽力而为；请确保 CLI 位于 `PATH` 中（我们会展开 `~`），或者设置带有完整命令路径的显式 CLI 模型。
|
||||
|
||||
### 代理环境支持（provider 模型）
|
||||
### 代理环境支持（提供商模型）
|
||||
|
||||
启用基于 provider 的**音频**和**视频**媒体理解时，OpenClaw
|
||||
会在 provider HTTP 调用中遵循标准的出站代理环境变量：
|
||||
启用基于提供商的**音频**和**视频**媒体理解时，OpenClaw
|
||||
会在调用提供商 HTTP 时遵循标准的出站代理环境变量：
|
||||
|
||||
- `HTTPS_PROXY`
|
||||
- `HTTP_PROXY`
|
||||
- `https_proxy`
|
||||
- `http_proxy`
|
||||
|
||||
如果未设置任何代理环境变量，媒体理解将使用直连出口。
|
||||
如果未设置代理环境变量，媒体理解将直接出网。
|
||||
如果代理值格式错误，OpenClaw 会记录警告并回退为直接抓取。
|
||||
|
||||
## 能力（可选）
|
||||
|
||||
如果你设置了 `capabilities`，该条目只会用于这些媒体类型。对于共享列表，OpenClaw 可以推断默认值：
|
||||
如果你设置了 `capabilities`，该条目只会对这些媒体类型运行。对于共享列表，OpenClaw 可以推断默认值：
|
||||
|
||||
- `openai`、`anthropic`、`minimax`：**图像**
|
||||
- `minimax-portal`：**图像**
|
||||
@ -209,33 +207,31 @@ CLI 模板还可以使用：
|
||||
- `groq`：**音频**
|
||||
- `xai`：**音频**
|
||||
- `deepgram`：**音频**
|
||||
- 任何带有支持图像能力模型的 `models.providers.<id>.models[]` 目录：**图像**
|
||||
- 任意 `models.providers.<id>.models[]` 目录中带有具备图像能力模型的条目：**图像**
|
||||
|
||||
对于 CLI 条目，**请显式设置 `capabilities`**，以避免意外匹配。
|
||||
如果你省略 `capabilities`，该条目将适用于其所在列表。
|
||||
如果省略 `capabilities`，则该条目会对其所在列表适用。
|
||||
|
||||
## Provider 支持矩阵（OpenClaw 集成）
|
||||
## 提供商支持矩阵（OpenClaw 集成）
|
||||
|
||||
| Capability | Provider integration | Notes |
|
||||
| ---------- | -------------------- | ----- |
|
||||
| 图像 | OpenAI、OpenRouter、Anthropic、Google、MiniMax、Moonshot、Qwen、Z.AI、配置提供商 | 厂商插件注册图像支持；MiniMax 和 MiniMax OAuth 都使用 `MiniMax-VL-01`；支持图像的配置提供商会自动注册。 |
|
||||
| 音频 | OpenAI、Groq、Deepgram、Google、Mistral | 提供商转录（Whisper/Deepgram/Gemini/Voxtral）。 |
|
||||
| 视频 | Google、Qwen、Moonshot | 通过厂商插件提供视频理解；Qwen 视频理解使用标准的 DashScope 端点。 |
|
||||
| Capability | 提供商集成 | 说明 |
|
||||
| ---------- | ---------- | ---- |
|
||||
| Image | OpenAI、OpenRouter、Anthropic、Google、MiniMax、Moonshot、Qwen、Z.AI、配置提供商 | 厂商插件会注册图像支持；MiniMax 和 MiniMax OAuth 都使用 `MiniMax-VL-01`；具备图像能力的配置提供商会自动注册。 |
|
||||
| Audio | OpenAI、Groq、Deepgram、Google、Mistral | 提供商转录（Whisper/Deepgram/Gemini/Voxtral）。 |
|
||||
| Video | Google、Qwen、Moonshot | 通过厂商插件提供视频理解；Qwen 视频理解使用标准 DashScope 端点。 |
|
||||
|
||||
MiniMax 说明：
|
||||
|
||||
- `minimax` 和 `minimax-portal` 图像理解来自插件拥有的
|
||||
`MiniMax-VL-01` 媒体提供商。
|
||||
- 内置的 MiniMax 文本目录仍然以纯文本为起点；显式的
|
||||
`models.providers.minimax` 条目会实例化支持图像能力的 M2.7 chat 引用。
|
||||
- `minimax` 和 `minimax-portal` 图像理解来自插件拥有的 `MiniMax-VL-01` 媒体提供商。
|
||||
- 内置的 MiniMax 文本目录仍从仅文本开始；显式的 `models.providers.minimax` 条目会具体化支持图像的 M2.7 聊天引用。
|
||||
|
||||
## 模型选择指导
|
||||
## 模型选择指引
|
||||
|
||||
- 当质量和安全性很重要时，优先为每种媒体能力选择可用的、能力最强的最新一代模型。
|
||||
- 对于处理不可信输入的启用工具的智能体，避免使用较旧/较弱的媒体模型。
|
||||
- 每种能力至少保留一个回退方案以确保可用性（高质量模型 + 更快/更便宜的模型）。
|
||||
- 当 provider API 不可用时，CLI 回退方案（`whisper-cli`、`whisper`、`gemini`）很有用。
|
||||
- `parakeet-mlx` 说明：使用 `--output-dir` 时，如果输出格式为 `txt`（或未指定），OpenClaw 会读取 `<output-dir>/<media-basename>.txt`；非 `txt` 格式会回退到 stdout。
|
||||
- 当质量和安全性很重要时，应优先为每种媒体能力选择可用的最新一代最强模型。
|
||||
- 对于处理不受信任输入的启用工具智能体，避免使用较旧/较弱的媒体模型。
|
||||
- 每种能力至少保留一个回退项以确保可用性（高质量模型 + 更快/更便宜的模型）。
|
||||
- CLI 回退方案（`whisper-cli`、`whisper`、`gemini`）在提供商 API 不可用时很有帮助。
|
||||
- `parakeet-mlx` 说明：使用 `--output-dir` 时，当输出格式为 `txt`（或未指定）时，OpenClaw 会读取 `<output-dir>/<media-basename>.txt`；非 `txt` 格式则回退到 stdout。
|
||||
|
||||
## 附件策略
|
||||
|
||||
@ -249,26 +245,26 @@ MiniMax 说明：
|
||||
|
||||
文件附件提取行为：
|
||||
|
||||
- 提取的文件文本会先包装为**不可信外部内容**，然后再附加到媒体提示中。
|
||||
- 注入块使用显式边界标记，例如
|
||||
- 提取出的文件文本会先包装为**不受信任的外部内容**，然后再附加到媒体提示词中。
|
||||
- 注入的区块会使用明确的边界标记，例如
|
||||
`<<<EXTERNAL_UNTRUSTED_CONTENT id="...">>>` /
|
||||
`<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>`，并包含
|
||||
`Source: External` 元数据行。
|
||||
- 该附件提取路径有意省略较长的
|
||||
`SECURITY NOTICE:` 横幅，以避免媒体提示过于臃肿；边界标记和元数据仍会保留。
|
||||
`<<<END_EXTERNAL_UNTRUSTED_CONTENT id="...">>>`，并包含一行
|
||||
`Source: External` 元数据。
|
||||
- 此附件提取路径有意省略了较长的
|
||||
`SECURITY NOTICE:` 横幅，以避免媒体提示词膨胀；但边界标记和元数据仍会保留。
|
||||
- 如果文件没有可提取文本，OpenClaw 会注入 `[No extractable text]`。
|
||||
- 如果 PDF 在该路径中回退为渲染后的页面图像，媒体提示会保留占位符 `[PDF content rendered to images; images not forwarded to model]`，因为这个附件提取步骤转发的是文本块，而不是渲染后的 PDF 图像。
|
||||
- 如果 PDF 在此路径中回退为渲染后的页面图像，媒体提示词会保留占位符 `[PDF content rendered to images; images not forwarded to model]`，因为该附件提取步骤传递的是文本区块，而不是渲染后的 PDF 图像。
|
||||
|
||||
## 配置示例
|
||||
|
||||
### 1) 共享模型列表 + 覆盖
|
||||
### 1）共享模型列表 + 覆盖项
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
media: {
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-5.4-mini", capabilities: ["image"] },
|
||||
{ provider: "openai", model: "gpt-5.5", capabilities: ["image"] },
|
||||
{
|
||||
provider: "google",
|
||||
model: "gemini-3-flash-preview",
|
||||
@ -298,7 +294,7 @@ MiniMax 说明：
|
||||
}
|
||||
```
|
||||
|
||||
### 2) 仅音频 + 视频（关闭图像）
|
||||
### 2）仅音频 + 视频（关闭图像）
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -338,7 +334,7 @@ MiniMax 说明：
|
||||
}
|
||||
```
|
||||
|
||||
### 3) 可选图像理解
|
||||
### 3）可选的图像理解
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -349,7 +345,7 @@ MiniMax 说明：
|
||||
maxBytes: 10485760,
|
||||
maxChars: 500,
|
||||
models: [
|
||||
{ provider: "openai", model: "gpt-5.4-mini" },
|
||||
{ provider: "openai", model: "gpt-5.5" },
|
||||
{ provider: "anthropic", model: "claude-opus-4-6" },
|
||||
{
|
||||
type: "cli",
|
||||
@ -369,7 +365,7 @@ MiniMax 说明：
|
||||
}
|
||||
```
|
||||
|
||||
### 4) 多模态单条目（显式能力）
|
||||
### 4）多模态单条目（显式 capabilities）
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -409,21 +405,21 @@ MiniMax 说明：
|
||||
|
||||
## 状态输出
|
||||
|
||||
当媒体理解运行时，`/status` 会包含一条简短的摘要行：
|
||||
当媒体理解运行时，`/status` 会包含一行简短摘要：
|
||||
|
||||
```
|
||||
📎 Media: image ok (openai/gpt-5.4-mini) · audio skipped (maxBytes)
|
||||
📎 Media: image ok (openai/gpt-5.5) · audio skipped (maxBytes)
|
||||
```
|
||||
|
||||
这会显示各项能力的结果，以及适用时所选的 provider/model。
|
||||
这会显示按能力划分的结果，以及适用时所选的 provider/model。
|
||||
|
||||
## 说明
|
||||
|
||||
- 理解是**尽力而为**的。错误不会阻止回复。
|
||||
- 即使理解被禁用，附件仍会传递给模型。
|
||||
- 使用 `scope` 来限制理解运行的位置（例如仅在私信中）。
|
||||
- 理解功能是**尽力而为**的。错误不会阻止回复。
|
||||
- 即使理解功能被禁用，附件仍会传递给模型。
|
||||
- 使用 `scope` 可限制理解功能的运行范围（例如仅在私信中）。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- [配置](/zh-CN/gateway/configuration)
|
||||
- [图像和媒体支持](/zh-CN/nodes/images)
|
||||
- [图像与媒体支持](/zh-CN/nodes/images)
|
||||
|
||||
@ -1,73 +1,77 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想使用内置的 Codex 应用服务器测试工具
|
||||
- 你想使用内置的 Codex app-server harness
|
||||
- 你需要 Codex 模型引用和配置示例
|
||||
- 你想为仅使用 Codex 的部署禁用 Pi 回退机制
|
||||
summary: 通过内置的 Codex 应用服务器测试工具运行 OpenClaw 嵌入式智能体轮次
|
||||
title: Codex 测试工具
|
||||
- 你想为仅使用 Codex 的部署禁用 PI 回退
|
||||
summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次
|
||||
title: Codex Harness
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T16:04:44Z"
|
||||
generated_at: "2026-04-23T19:25:20Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 07e7fb033cd4025e53d65a719bab7bd704335933bf19bfb10648cede42cdee46
|
||||
source_hash: 99ca00550be4e41aa154a99298e3e1b027f8199d541249149cb0ec722e035876
|
||||
source_path: plugins/codex-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Codex 测试工具
|
||||
# Codex Harness
|
||||
|
||||
内置的 `codex` 插件让 OpenClaw 通过 Codex 应用服务器运行嵌入式智能体轮次，而不是使用内置的 Pi 测试工具。
|
||||
内置的 `codex` 插件让 OpenClaw 可以通过 Codex app-server，而不是内置的 PI harness，来运行嵌入式智能体轮次。
|
||||
|
||||
当你希望由 Codex 接管底层智能体会话时，请使用此方式：模型发现、原生线程恢复、原生压缩以及应用服务器执行。
|
||||
OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传递，以及可见的转录镜像。
|
||||
当你希望由 Codex 接管底层智能体会话时，请使用它：模型发现、原生线程恢复、原生压缩，以及 app-server 执行。
|
||||
OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体投递，以及可见的转录镜像。
|
||||
|
||||
原生 Codex 轮次也会遵循共享的插件钩子，因此提示词 shim、感知压缩的自动化、工具中间件和生命周期观察器都会与 Pi 测试工具保持一致：
|
||||
原生 Codex 轮次同样遵循共享插件钩子，因此 prompt shim、具备 compaction 感知的自动化、工具中间件和生命周期观察器都能与 PI harness 保持一致：
|
||||
|
||||
- `before_prompt_build`
|
||||
- `before_compaction`, `after_compaction`
|
||||
- `llm_input`, `llm_output`
|
||||
- `tool_result`, `after_tool_call`
|
||||
- `before_compaction`、`after_compaction`
|
||||
- `llm_input`、`llm_output`
|
||||
- `tool_result`、`after_tool_call`
|
||||
- `before_message_write`
|
||||
- `agent_end`
|
||||
|
||||
内置插件还可以注册一个 Codex 应用服务器扩展工厂，以添加异步 `tool_result` 中间件。
|
||||
内置插件还可以注册一个 Codex app-server extension factory，以添加异步 `tool_result` 中间件。
|
||||
|
||||
该测试工具默认关闭。只有在启用 `codex` 插件且解析后的模型是 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选中它。
|
||||
如果你从未配置 `codex/*`，现有的 Pi、OpenAI、Anthropic、Gemini、本地和自定义提供商运行都会保持当前行为。
|
||||
该 harness 默认关闭。只有在启用了 `codex` 插件且解析后的模型是 `codex/*` 模型时，或者你显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex` 时，才会选择它。
|
||||
如果你从未配置 `codex/*`，现有的 PI、OpenAI、Anthropic、Gemini、local 和自定义 provider 运行都会保持当前行为。
|
||||
|
||||
## 选择正确的模型前缀
|
||||
|
||||
OpenClaw 为 OpenAI 访问方式和 Codex 风格的访问方式提供了不同路径：
|
||||
OpenClaw 为 OpenAI 访问和 Codex 形态的访问提供了不同路由：
|
||||
|
||||
| 模型引用 | 运行时路径 | 使用场景 |
|
||||
| 模型引用 | 运行时路径 | 适用场景 |
|
||||
| ---------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.4` | 通过 OpenClaw/Pi 流程的 OpenAI 提供商 | 你想通过 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 |
|
||||
| `openai-codex/gpt-5.4` | 通过 Pi 的 OpenAI Codex OAuth 提供商 | 你想使用 ChatGPT/Codex OAuth，但不使用 Codex 应用服务器测试工具。 |
|
||||
| `codex/gpt-5.4` | 内置 Codex 提供商加 Codex 测试工具 | 你希望嵌入式智能体轮次使用原生 Codex 应用服务器执行。 |
|
||||
| `openai/gpt-5.5` | 通过 OpenClaw/PI 管线的 OpenAI provider | 你希望通过 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 |
|
||||
| `openai-codex/gpt-5.5` | 通过 PI 的 OpenAI Codex OAuth provider | 你希望使用 ChatGPT/Codex OAuth，但不使用 Codex app-server harness。 |
|
||||
| `codex/gpt-5.5` | 内置 Codex provider 加 Codex harness | 你希望嵌入式智能体轮次使用原生 Codex app-server 执行。 |
|
||||
|
||||
Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、本地和自定义提供商引用都会保持其正常路径。
|
||||
Codex harness 只接管 `codex/*` 模型引用。现有的 `openai/*`、`openai-codex/*`、Anthropic、Gemini、xAI、local 和自定义 provider 引用都会继续走各自的正常路径。
|
||||
|
||||
测试工具选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选测试工具的 id，并在同一会话 id 的后续轮次中继续使用它。若你希望未来的会话使用另一种测试工具，请更改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在现有对话于 Pi 和 Codex 之间切换前，请使用 `/new` 或 `/reset` 启动一个新会话。
|
||||
这样可以避免同一份转录被重放到两个不兼容的原生会话系统中。
|
||||
Harness 选择不是实时会话控制。当嵌入式轮次运行时，OpenClaw 会在该会话上记录所选 harness ID，并在同一会话 ID 的后续轮次中持续使用它。
|
||||
当你希望未来的新会话使用其他 harness 时，请修改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；在将现有对话从 PI 切换到 Codex 之前，请使用 `/new` 或 `/reset` 启动一个全新会话。
|
||||
这样可以避免将同一份转录通过两套不兼容的原生会话系统重放。
|
||||
|
||||
在测试工具固定机制引入之前创建的旧会话，一旦已有转录历史，就会被视为固定到 Pi。更改配置后，使用 `/new` 或 `/reset` 可让该对话改为使用 Codex。
|
||||
在 harness 固定机制引入之前创建的旧会话，只要已有转录历史，就会被视为固定到 PI。
|
||||
更改配置后，使用 `/new` 或 `/reset` 可让该对话切换到 Codex。
|
||||
|
||||
`/status` 会在 `Fast` 旁边显示生效的非 Pi 测试工具，例如 `Fast · codex`。默认的 Pi 测试工具不会显示。
|
||||
`/status` 会在 `Fast` 旁边显示生效中的非 PI harness，例如 `Fast · codex`。
|
||||
默认的 PI harness 不会显示。
|
||||
|
||||
## 要求
|
||||
|
||||
- OpenClaw，且可使用内置的 `codex` 插件。
|
||||
- Codex 应用服务器 `0.118.0` 或更高版本。
|
||||
- 应用服务器进程可用的 Codex 身份验证。
|
||||
- OpenClaw，并且可使用内置的 `codex` 插件。
|
||||
- Codex app-server `0.118.0` 或更高版本。
|
||||
- app-server 进程可用的 Codex 认证信息。
|
||||
|
||||
该插件会阻止过旧或未标明版本的应用服务器握手。
|
||||
这样可以让 OpenClaw 保持在已验证过的协议范围内运行。
|
||||
该插件会阻止版本过旧或未提供版本信息的 app-server 握手。
|
||||
这样可以确保 OpenClaw 只运行在它已测试过的协议表面上。
|
||||
|
||||
对于实时测试和 Docker 冒烟测试，身份验证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex 应用服务器相同的认证材料。
|
||||
对于 live 和 Docker smoke 测试，认证通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。
|
||||
请使用与你本地 Codex app-server 相同的认证材料。
|
||||
|
||||
## 最小配置
|
||||
|
||||
使用 `codex/gpt-5.4`，启用内置插件，并强制使用 `codex` 测试工具：
|
||||
使用 `codex/gpt-5.5`，启用内置插件，并强制使用 `codex` harness：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -80,7 +84,7 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、`
|
||||
},
|
||||
agents: {
|
||||
defaults: {
|
||||
model: "codex/gpt-5.4",
|
||||
model: "codex/gpt-5.5",
|
||||
embeddedHarness: {
|
||||
runtime: "codex",
|
||||
fallback: "none",
|
||||
@ -90,7 +94,7 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、`
|
||||
}
|
||||
```
|
||||
|
||||
如果你的配置使用 `plugins.allow`，也要在其中加入 `codex`：
|
||||
如果你的配置使用了 `plugins.allow`，也请把 `codex` 加进去：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -105,11 +109,12 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、`
|
||||
}
|
||||
```
|
||||
|
||||
将 `agents.defaults.model` 或某个智能体模型设置为 `codex/<model>` 时，也会自动启用内置的 `codex` 插件。在共享配置中，显式写出插件条目仍然很有用，因为这能清楚表明部署意图。
|
||||
将 `agents.defaults.model` 或某个智能体模型设置为 `codex/<model>`，也会自动启用内置的 `codex` 插件。
|
||||
在共享配置中，显式写出插件条目仍然很有用，因为它能更清楚地表明部署意图。
|
||||
|
||||
## 添加 Codex，但不替换其他模型
|
||||
## 在不替换其他模型的情况下添加 Codex
|
||||
|
||||
如果你希望 `codex/*` 模型使用 Codex，而其他模型仍使用 Pi，请保留 `runtime: "auto"`：
|
||||
如果你希望 `codex/*` 模型使用 Codex，而其他所有模型继续使用 PI，请保持 `runtime: "auto"`：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -123,13 +128,13 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、`
|
||||
agents: {
|
||||
defaults: {
|
||||
model: {
|
||||
primary: "codex/gpt-5.4",
|
||||
fallbacks: ["openai/gpt-5.4", "anthropic/claude-opus-4-6"],
|
||||
primary: "codex/gpt-5.5",
|
||||
fallbacks: ["openai/gpt-5.5", "anthropic/claude-opus-4-6"],
|
||||
},
|
||||
models: {
|
||||
"codex/gpt-5.4": { alias: "codex" },
|
||||
"codex/gpt-5.5": { alias: "codex" },
|
||||
"codex/gpt-5.4-mini": { alias: "codex-mini" },
|
||||
"openai/gpt-5.4": { alias: "gpt" },
|
||||
"openai/gpt-5.5": { alias: "gpt" },
|
||||
"anthropic/claude-opus-4-6": { alias: "opus" },
|
||||
},
|
||||
embeddedHarness: {
|
||||
@ -141,22 +146,22 @@ Codex 测试工具只会接管 `codex/*` 模型引用。现有的 `openai/*`、`
|
||||
}
|
||||
```
|
||||
|
||||
采用这种配置时：
|
||||
在这种配置下：
|
||||
|
||||
- `/model codex` 或 `/model codex/gpt-5.4` 会使用 Codex 应用服务器测试工具。
|
||||
- `/model gpt` 或 `/model openai/gpt-5.4` 会使用 OpenAI 提供商路径。
|
||||
- `/model opus` 会使用 Anthropic 提供商路径。
|
||||
- 如果选择的是非 Codex 模型，Pi 仍然会作为兼容性测试工具。
|
||||
- `/model codex` 或 `/model codex/gpt-5.5` 使用 Codex app-server harness。
|
||||
- `/model gpt` 或 `/model openai/gpt-5.5` 使用 OpenAI provider 路径。
|
||||
- `/model opus` 使用 Anthropic provider 路径。
|
||||
- 如果选择的是非 Codex 模型，PI 仍然是兼容性 harness。
|
||||
|
||||
## 仅使用 Codex 的部署
|
||||
## 仅 Codex 部署
|
||||
|
||||
当你需要证明每一次嵌入式智能体轮次都使用 Codex 测试工具时，请禁用 Pi 回退：
|
||||
当你需要证明每一个嵌入式智能体轮次都使用 Codex harness 时，请禁用 PI 回退：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
model: "codex/gpt-5.4",
|
||||
model: "codex/gpt-5.5",
|
||||
embeddedHarness: {
|
||||
runtime: "codex",
|
||||
fallback: "none",
|
||||
@ -174,11 +179,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、应用服务器版本过旧，或应用服务器无法启动，OpenClaw 都会尽早失败。
|
||||
禁用回退后，如果 Codex 插件被禁用、请求的模型不是 `codex/*` 引用、app-server 版本过旧，或者 app-server 无法启动，OpenClaw 都会尽早失败。
|
||||
|
||||
## 按智能体使用 Codex
|
||||
## 每智能体 Codex
|
||||
|
||||
你可以只让某一个智能体专用 Codex，而默认智能体仍保持正常的自动选择：
|
||||
你可以让某一个智能体仅使用 Codex，而默认智能体仍保留正常的自动选择：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -198,7 +203,7 @@ openclaw gateway run
|
||||
{
|
||||
id: "codex",
|
||||
name: "Codex",
|
||||
model: "codex/gpt-5.4",
|
||||
model: "codex/gpt-5.5",
|
||||
embeddedHarness: {
|
||||
runtime: "codex",
|
||||
fallback: "none",
|
||||
@ -209,14 +214,16 @@ openclaw gateway run
|
||||
}
|
||||
```
|
||||
|
||||
使用常规会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex 测试工具会按需为其创建或恢复配套的应用服务器线程。`/reset` 会清除该线程对应的 OpenClaw 会话绑定，并让下一轮再次根据当前配置解析测试工具。
|
||||
使用普通会话命令即可切换智能体和模型。
|
||||
`/new` 会创建一个新的 OpenClaw 会话，而 Codex harness 会按需创建或恢复其 sidecar app-server 线程。
|
||||
`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一轮根据当前配置重新解析 harness。
|
||||
|
||||
## 模型发现
|
||||
|
||||
默认情况下，Codex 插件会向应用服务器请求可用模型。
|
||||
如果发现失败或超时，它会使用内置的回退目录：
|
||||
默认情况下，Codex 插件会向 app-server 请求可用模型。
|
||||
如果发现失败或超时，它会使用内置回退目录：
|
||||
|
||||
- `codex/gpt-5.4`
|
||||
- `codex/gpt-5.5`
|
||||
- `codex/gpt-5.4-mini`
|
||||
- `codex/gpt-5.2`
|
||||
|
||||
@ -259,19 +266,20 @@ openclaw gateway run
|
||||
}
|
||||
```
|
||||
|
||||
## 应用服务器连接与策略
|
||||
## App-server 连接与策略
|
||||
|
||||
默认情况下，插件会用以下命令在本地启动 Codex：
|
||||
默认情况下，插件会使用以下命令在本地启动 Codex：
|
||||
|
||||
```bash
|
||||
codex app-server --listen stdio://
|
||||
```
|
||||
|
||||
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex 测试工具会话：
|
||||
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：
|
||||
`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及
|
||||
`sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会因为无人响应的原生审批提示而中断。
|
||||
`sandbox: "danger-full-access"`。
|
||||
这是用于自治心跳的可信本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会因为没有人可响应的原生审批提示而停下来。
|
||||
|
||||
如果要启用由 Codex Guardian 审核的审批，请设置 `appServer.mode:
|
||||
如果你想启用由 Codex guardian 审核的审批，请设置 `appServer.mode:
|
||||
"guardian"`：
|
||||
|
||||
```json5
|
||||
@ -292,11 +300,15 @@ codex app-server --listen stdio://
|
||||
}
|
||||
```
|
||||
|
||||
Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个审核子智能体，而不是向人工发出提示。审核器会应用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多防护措施，但仍需要无人值守的智能体持续推进，请使用 Guardian。
|
||||
Guardian 是原生 Codex 审批审核者。
|
||||
当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个 reviewer 子智能体，而不是发给人工提示。
|
||||
该 reviewer 会应用 Codex 的风险框架，并批准或拒绝具体请求。
|
||||
如果你希望比 YOLO 模式有更多防护措施，但仍需要无人值守的智能体持续推进，请使用 Guardian。
|
||||
|
||||
`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。各个策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选项混合使用。
|
||||
`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。
|
||||
各个单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。
|
||||
|
||||
对于已经在运行的应用服务器，请使用 WebSocket 传输：
|
||||
对于已经在运行的 app-server，可使用 WebSocket 传输：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -323,19 +335,19 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 |
|
||||
| `command` | `"codex"` | 用于 stdio 传输的可执行文件。 |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 |
|
||||
| `url` | 未设置 | WebSocket 应用服务器 URL。 |
|
||||
| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 |
|
||||
| `headers` | `{}` | 额外的 WebSocket 标头。 |
|
||||
| `requestTimeoutMs` | `60000` | 应用服务器控制平面调用的超时时间。 |
|
||||
| `mode` | `"yolo"` | 用于 YOLO 或 Guardian 审核执行的预设。 |
|
||||
| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 |
|
||||
| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 |
|
||||
| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 让 Codex Guardian 审核提示。 |
|
||||
| `serviceTier` | 未设置 | 可选的 Codex 应用服务器服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 |
|
||||
| `command` | `"codex"` | `stdio` 传输使用的可执行文件。 |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | `stdio` 传输使用的参数。 |
|
||||
| `url` | 未设置 | WebSocket app-server URL。 |
|
||||
| `authToken` | 未设置 | WebSocket 传输使用的 Bearer token。 |
|
||||
| `headers` | `{}` | 额外的 WebSocket headers。 |
|
||||
| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 |
|
||||
| `mode` | `"yolo"` | YOLO 或 guardian 审核执行的预设。 |
|
||||
| `approvalPolicy` | `"never"` | 发送到线程 start/resume/turn 的原生 Codex 审批策略。 |
|
||||
| `sandbox` | `"danger-full-access"` | 发送到线程 start/resume 的原生 Codex 沙箱模式。 |
|
||||
| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 可让 Codex Guardian 审核提示。 |
|
||||
| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。 |
|
||||
|
||||
当对应配置字段未设置时，较旧的环境变量仍可作为本地测试的回退方式：
|
||||
当匹配的配置字段未设置时，较旧的环境变量仍可作为本地测试的回退方式：
|
||||
|
||||
- `OPENCLAW_CODEX_APP_SERVER_BIN`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
|
||||
@ -344,13 +356,13 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在
|
||||
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
|
||||
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试时使用
|
||||
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，推荐使用配置，
|
||||
因为这样可以将插件行为与 Codex 测试工具设置的其余部分放在同一个经过审查的文件中。
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"`，或在一次性本地测试中使用
|
||||
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，优先使用配置，
|
||||
因为这样能将插件行为与 Codex harness 其余设置放在同一个经过审查的文件中。
|
||||
|
||||
## 常见用法
|
||||
## 常见配方
|
||||
|
||||
使用默认 stdio 传输的本地 Codex：
|
||||
使用默认 `stdio` 传输的本地 Codex：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -364,7 +376,7 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在
|
||||
}
|
||||
```
|
||||
|
||||
仅使用 Codex 的测试工具验证，禁用 Pi 回退：
|
||||
仅 Codex harness 验证，并禁用 PI 回退：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -403,7 +415,7 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在
|
||||
}
|
||||
```
|
||||
|
||||
带显式标头的远程应用服务器：
|
||||
带显式 headers 的远程 app-server：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -426,73 +438,72 @@ Guardian 是原生的 Codex 审批审核器。当 Codex 请求离开沙箱、在
|
||||
}
|
||||
```
|
||||
|
||||
模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有的 Codex 线程时，
|
||||
下一轮会再次将当前选定的 `codex/*` 模型、提供商、审批策略、沙箱和服务层级发送给
|
||||
应用服务器。从 `codex/gpt-5.4` 切换到 `codex/gpt-5.2` 时，会保留线程绑定，但会要求
|
||||
Codex 使用新选定的模型继续执行。
|
||||
模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到现有 Codex 线程时，
|
||||
下一轮会再次把当前选中的 `codex/*` 模型、provider、审批策略、沙箱和服务层级发送给
|
||||
app-server。将 `codex/gpt-5.5` 切换到 `codex/gpt-5.2` 时，会保留线程绑定，
|
||||
但会要求 Codex 使用新选择的模型继续执行。
|
||||
|
||||
## Codex 命令
|
||||
|
||||
内置插件将 `/codex` 注册为授权斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道中使用。
|
||||
内置插件会将 `/codex` 注册为一个已授权的斜杠命令。它是通用的，可在任何支持 OpenClaw 文本命令的渠道中使用。
|
||||
|
||||
常见形式：
|
||||
|
||||
- `/codex status` 显示实时应用服务器连接状态、模型、账户、速率限制、MCP 服务器和 skills。
|
||||
- `/codex models` 列出实时 Codex 应用服务器模型。
|
||||
- `/codex status` 显示实时 app-server 连接状态、模型、账户、速率限制、MCP 服务器和 Skills。
|
||||
- `/codex models` 列出实时 Codex app-server 模型。
|
||||
- `/codex threads [filter]` 列出最近的 Codex 线程。
|
||||
- `/codex resume <thread-id>` 将当前 OpenClaw 会话附加到现有 Codex 线程。
|
||||
- `/codex compact` 请求 Codex 应用服务器压缩已附加的线程。
|
||||
- `/codex review` 为已附加的线程启动 Codex 原生审查。
|
||||
- `/codex compact` 请求 Codex app-server 压缩已附加线程。
|
||||
- `/codex review` 为已附加线程启动 Codex 原生审查。
|
||||
- `/codex account` 显示账户和速率限制状态。
|
||||
- `/codex mcp` 列出 Codex 应用服务器 MCP 服务器状态。
|
||||
- `/codex skills` 列出 Codex 应用服务器 Skills。
|
||||
- `/codex mcp` 列出 Codex app-server MCP 服务器状态。
|
||||
- `/codex skills` 列出 Codex app-server Skills。
|
||||
|
||||
`/codex resume` 会写入与测试工具正常轮次所使用的同一个配套绑定文件。
|
||||
在下一条消息中，OpenClaw 会恢复该 Codex 线程，将当前选定的 OpenClaw `codex/*`
|
||||
模型传入应用服务器，并保持启用扩展历史记录。
|
||||
`/codex resume` 会写入与 harness 正常轮次相同的 sidecar 绑定文件。
|
||||
在下一条消息时，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw `codex/*` 模型传入 app-server，并保持扩展历史记录启用。
|
||||
|
||||
该命令功能要求 Codex 应用服务器版本为 `0.118.0` 或更高。如果未来版本或自定义的应用服务器
|
||||
未暴露某个 JSON-RPC 方法，各个控制方法会显示为 `unsupported by this Codex app-server`。
|
||||
该命令面要求 Codex app-server `0.118.0` 或更高版本。如果未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，则各个控制方法会显示为 `unsupported by this Codex app-server`。
|
||||
|
||||
## 工具、媒体与压缩
|
||||
|
||||
Codex 测试工具仅改变底层嵌入式智能体执行器。
|
||||
Codex harness 只会改变底层嵌入式智能体执行器。
|
||||
|
||||
OpenClaw 仍然构建工具列表，并从测试工具接收动态工具结果。文本、图像、视频、音乐、TTS、
|
||||
审批和消息工具输出会继续通过正常的 OpenClaw 传递路径处理。
|
||||
OpenClaw 仍然会构建工具列表，并从 harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，都会继续通过 OpenClaw 的常规投递路径传输。
|
||||
|
||||
当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具审批请求会通过 OpenClaw 的插件审批流程路由；其他请求输入和自由格式输入请求仍会以失败关闭的方式处理。
|
||||
当 Codex 将 `_meta.codex_approval_kind` 标记为
|
||||
`"mcp_tool_call"` 时，Codex MCP 工具审批请求会通过 OpenClaw 的插件审批流程进行路由；
|
||||
其他请求输入和自由格式输入请求仍然会以失败关闭方式处理。
|
||||
|
||||
当所选模型使用 Codex 测试工具时，原生线程压缩会委托给 Codex 应用服务器。OpenClaw 会保留一份转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的模型或测试工具切换。该镜像包括用户提示、最终助手文本，以及在应用服务器发出时包含轻量级的 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩开始和完成信号。它尚未提供人类可读的压缩摘要，也未提供 Codex 在压缩后保留了哪些条目的可审计列表。
|
||||
当所选模型使用 Codex harness 时，原生线程压缩会委托给 Codex app-server。
|
||||
OpenClaw 会继续保留一个转录镜像，用于渠道历史记录、搜索、`/new`、`/reset`，以及未来的模型或 harness 切换。该镜像包含用户提示、最终助手文本，以及 app-server 发出时的轻量级 Codex 推理或计划记录。当前，OpenClaw 只记录原生压缩开始和完成信号。它尚未提供人类可读的压缩摘要，也未提供一份可审计清单来说明压缩后 Codex 保留了哪些条目。
|
||||
|
||||
媒体生成不需要 Pi。图像、视频、音乐、PDF、TTS 和媒体理解会继续使用相应的提供商/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。
|
||||
媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 和媒体理解仍会使用相应的 provider/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。
|
||||
|
||||
## 故障排除
|
||||
|
||||
**`/model` 中未显示 Codex：** 启用 `plugins.entries.codex.enabled`，
|
||||
**`/model` 中没有出现 Codex：** 启用 `plugins.entries.codex.enabled`，
|
||||
设置一个 `codex/*` 模型引用，或检查 `plugins.allow` 是否排除了 `codex`。
|
||||
|
||||
**OpenClaw 使用的是 Pi 而不是 Codex：** 如果没有 Codex 测试工具接管该运行，
|
||||
OpenClaw 可能会使用 Pi 作为兼容性后端。测试时设置
|
||||
**OpenClaw 使用的是 PI 而不是 Codex：** 如果没有 Codex harness 接管该运行，
|
||||
OpenClaw 可能会将 PI 用作兼容性后端。测试时请设置
|
||||
`embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置
|
||||
`embeddedHarness.fallback: "none"` 以在没有匹配的插件测试工具时直接失败。
|
||||
一旦选中了 Codex 应用服务器，它的失败会直接暴露出来，无需额外的回退配置。
|
||||
`embeddedHarness.fallback: "none"` 以在没有插件 harness 匹配时直接失败。一旦选中 Codex app-server，其失败会直接暴露出来，而不会再经过额外的回退配置。
|
||||
|
||||
**应用服务器被拒绝：** 升级 Codex，使应用服务器握手报告版本
|
||||
**app-server 被拒绝：** 升级 Codex，使 app-server 握手报告版本为
|
||||
`0.118.0` 或更高。
|
||||
|
||||
**模型发现很慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`
|
||||
**模型发现太慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs`
|
||||
或禁用发现。
|
||||
|
||||
**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，
|
||||
并确认远程应用服务器使用相同的 Codex 应用服务器协议版本。
|
||||
以及远程 app-server 是否使用相同版本的 Codex app-server 协议。
|
||||
|
||||
**非 Codex 模型使用了 Pi：** 这是预期行为。Codex 测试工具只会接管
|
||||
**非 Codex 模型使用了 PI：** 这是预期行为。Codex harness 只接管
|
||||
`codex/*` 模型引用。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [智能体测试工具插件](/zh-CN/plugins/sdk-agent-harness)
|
||||
- [智能体 Harness 插件](/zh-CN/plugins/sdk-agent-harness)
|
||||
- [模型提供商](/zh-CN/concepts/model-providers)
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference)
|
||||
- [测试](/zh-CN/help/testing#live-codex-app-server-harness-smoke)
|
||||
|
||||
@ -1,55 +1,65 @@
|
||||
---
|
||||
read_when:
|
||||
- 你正在构建一个 OpenClaw 插件
|
||||
- 你需要发布一个插件配置 schema，或调试插件校验错误
|
||||
summary: 插件清单 + JSON schema 要求（严格配置校验）
|
||||
- 你需要提供插件配置 schema，或调试插件验证错误
|
||||
summary: 插件清单 + JSON schema 要求（严格配置验证）
|
||||
title: 插件清单
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T16:56:50Z"
|
||||
generated_at: "2026-04-23T19:25:24Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e9e7bca47b076cc49080bd6921ef9d295c840e9a19c5271dbfea83d9882ea404
|
||||
source_hash: 4dd7c7e91637ff93ea60ee5d8069a9263382749435ca22a804fece05fc5f94ac
|
||||
source_path: plugins/manifest.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 插件清单（`openclaw.plugin.json`）
|
||||
|
||||
本页仅适用于 **OpenClaw 原生插件清单**。
|
||||
本页仅适用于**原生 OpenClaw 插件清单**。
|
||||
|
||||
有关兼容的 bundle 布局，请参阅 [插件 bundle](/zh-CN/plugins/bundles)。
|
||||
有关兼容的 bundle 布局，请参见 [插件 bundles](/zh-CN/plugins/bundles)。
|
||||
|
||||
兼容的 bundle 格式使用不同的清单文件：
|
||||
|
||||
- Codex bundle：`.codex-plugin/plugin.json`
|
||||
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件布局
|
||||
- Claude bundle：`.claude-plugin/plugin.json`，或不带清单的默认 Claude 组件
|
||||
布局
|
||||
- Cursor bundle：`.cursor-plugin/plugin.json`
|
||||
|
||||
OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的 `openclaw.plugin.json` schema 对它们进行校验。
|
||||
OpenClaw 也会自动检测这些 bundle 布局，但不会按照此处描述的 `openclaw.plugin.json` schema
|
||||
对它们进行验证。
|
||||
|
||||
对于兼容 bundle，OpenClaw 当前会在布局符合 OpenClaw 运行时预期时，读取 bundle 元数据，以及已声明的 skill 根目录、Claude 命令根目录、Claude bundle `settings.json` 默认值、Claude bundle LSP 默认值和受支持的 hook 包。
|
||||
对于兼容 bundle，当前在布局符合 OpenClaw 运行时预期时，
|
||||
OpenClaw 会读取 bundle 元数据、已声明的 skill 根目录、Claude 命令根目录、Claude bundle 的 `settings.json` 默认值、
|
||||
Claude bundle 的 LSP 默认值，以及受支持的 hook pack。
|
||||
|
||||
每个原生 OpenClaw 插件都 **必须** 在**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码的情况下**验证配置。缺失或无效的清单会被视为插件错误，并阻止配置校验。
|
||||
每个原生 OpenClaw 插件**都必须**在
|
||||
**插件根目录**中提供一个 `openclaw.plugin.json` 文件。OpenClaw 使用此清单在**不执行插件代码**
|
||||
的情况下验证配置。缺失或无效的清单会被视为
|
||||
插件错误，并阻止配置验证。
|
||||
|
||||
查看完整的插件系统指南：[插件](/zh-CN/tools/plugin)。
|
||||
有关原生能力模型以及当前外部兼容性指导，请参阅：
|
||||
请参见完整的插件系统指南：[插件](/zh-CN/tools/plugin)。
|
||||
有关原生能力模型和当前的外部兼容性指引：
|
||||
[能力模型](/zh-CN/plugins/architecture#public-capability-model)。
|
||||
|
||||
## 此文件的作用
|
||||
|
||||
`openclaw.plugin.json` 是 OpenClaw 在**加载你的插件代码之前**读取的元数据。以下所有内容都必须足够轻量，以便在不启动插件运行时的情况下进行检查。
|
||||
`openclaw.plugin.json` 是 OpenClaw 在**加载你的
|
||||
插件代码之前**读取的元数据。下面的所有内容都必须足够轻量，以便在不启动
|
||||
插件运行时的情况下进行检查。
|
||||
|
||||
**用于：**
|
||||
**可用于：**
|
||||
|
||||
- 插件标识、配置校验和配置 UI 提示
|
||||
- 插件标识、配置验证和配置 UI 提示
|
||||
- 认证、新手引导和设置元数据（别名、自动启用、提供商环境变量、认证选项）
|
||||
- 控制平面界面的激活提示
|
||||
- 简写模型家族归属
|
||||
- 简写模型系列归属
|
||||
- 静态能力归属快照（`contracts`）
|
||||
- 共享 `openclaw qa` 主机可检查的 QA 运行器元数据
|
||||
- 合并到目录和校验界面中的渠道专用配置元数据
|
||||
- 供共享 `openclaw qa` 主机检查的 QA 运行器元数据
|
||||
- 合并到目录和验证界面中的渠道专用配置元数据
|
||||
|
||||
**不要用于：** 注册运行时行为、声明代码入口点，或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。
|
||||
**不要用于：**注册运行时行为、声明代码入口点，
|
||||
或 npm 安装元数据。这些应放在你的插件代码和 `package.json` 中。
|
||||
|
||||
## 最小示例
|
||||
|
||||
@ -132,62 +142,64 @@ OpenClaw 也会自动检测这些 bundle 布局，但不会根据此处描述的
|
||||
| 字段 | 必填 | 类型 | 含义 |
|
||||
| ------------------------------------ | -------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `id` | 是 | `string` | 规范插件 id。这是在 `plugins.entries.<id>` 中使用的 id。 |
|
||||
| `configSchema` | 是 | `object` | 此插件配置的内联 JSON Schema。 |
|
||||
| `enabledByDefault` | 否 | `true` | 将内置插件标记为默认启用。省略此字段，或将其设为任何非 `true` 的值，则该插件默认保持禁用。 |
|
||||
| `legacyPluginIds` | 否 | `string[]` | 会规范化为此规范插件 id 的旧版 id。 |
|
||||
| `configSchema` | 是 | `object` | 该插件配置的内联 JSON Schema。 |
|
||||
| `enabledByDefault` | 否 | `true` | 将某个内置插件标记为默认启用。省略它，或设置为任何非 `true` 的值，以使插件默认保持禁用。 |
|
||||
| `legacyPluginIds` | 否 | `string[]` | 会被标准化为此规范插件 id 的旧版 id。 |
|
||||
| `autoEnableWhenConfiguredProviders` | 否 | `string[]` | 当认证、配置或模型引用提到这些提供商 id 时，应自动启用此插件。 |
|
||||
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明一个由 `plugins.slots.*` 使用的互斥插件类型。 |
|
||||
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于设备发现和配置校验。 |
|
||||
| `kind` | 否 | `"memory"` \| `"context-engine"` | 声明由 `plugins.slots.*` 使用的互斥插件类型。 |
|
||||
| `channels` | 否 | `string[]` | 由此插件拥有的渠道 id。用于发现和配置验证。 |
|
||||
| `providers` | 否 | `string[]` | 由此插件拥有的提供商 id。 |
|
||||
| `modelSupport` | 否 | `object` | 由清单拥有的简写模型家族元数据，用于在运行时之前自动加载插件。 |
|
||||
| `providerEndpoints` | 否 | `object[]` | 由清单拥有的 endpoint 主机 / `baseUrl` 元数据，用于核心在提供商运行时加载前对提供商路由进行分类。 |
|
||||
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于在显式配置引用时于启动阶段自动激活。 |
|
||||
| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前的冷启动模型发现期间，应探测其插件自有 synthetic auth hook 的提供商或 CLI 后端引用。 |
|
||||
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API key 值，表示非秘密的本地、OAuth 或环境凭证状态。 |
|
||||
| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，应在运行时加载前产生具备插件感知的配置和 CLI 诊断信息。 |
|
||||
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量提供商认证环境变量元数据。 |
|
||||
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个提供商 id 进行认证查找的提供商 id，例如共享基础提供商 API key 和认证配置文件的编码提供商。 |
|
||||
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量渠道环境变量元数据。将其用于由环境变量驱动的渠道设置或认证界面，以便通用启动 / 配置辅助逻辑能够识别。 |
|
||||
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI 标志接线的轻量认证选项元数据。 |
|
||||
| `activation` | 否 | `object` | 用于提供商、命令、渠道、路由和能力触发加载的轻量激活提示。仅为元数据；插件运行时仍拥有实际行为。 |
|
||||
| `setup` | 否 | `object` | 供设备发现和设置界面在不加载插件运行时的情况下检查的轻量设置 / 新手引导描述符。 |
|
||||
| `qaRunners` | 否 | `object[]` | 由共享 `openclaw qa` 主机在插件运行时加载前使用的轻量 QA 运行器描述符。 |
|
||||
| `contracts` | 否 | `object` | 外部认证 hook、speech、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、网页搜索和工具归属的静态内置能力快照。 |
|
||||
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量媒体理解默认元数据。 |
|
||||
| `channelConfigs` | 否 | `Record<string, object>` | 由清单拥有的渠道配置元数据，在运行时加载前合并到设备发现和校验界面中。 |
|
||||
| `modelSupport` | 否 | `object` | 由清单拥有的简写模型系列元数据，用于在运行时之前自动加载插件。 |
|
||||
| `providerEndpoints` | 否 | `object[]` | 由清单拥有的端点 host / baseUrl 元数据，用于那些在提供商运行时加载前，核心必须先分类的提供商路由。 |
|
||||
| `cliBackends` | 否 | `string[]` | 由此插件拥有的 CLI 推理后端 id。用于根据显式配置引用在启动时自动激活。 |
|
||||
| `syntheticAuthRefs` | 否 | `string[]` | 在运行时加载前进行冷启动模型发现时，需探测其由插件拥有的 synthetic auth hook 的提供商或 CLI 后端引用。 |
|
||||
| `nonSecretAuthMarkers` | 否 | `string[]` | 由内置插件拥有的占位 API 密钥值，表示非机密的本地、OAuth 或环境凭证状态。 |
|
||||
| `commandAliases` | 否 | `object[]` | 由此插件拥有的命令名称，在运行时加载前，这些命令应产生带有插件感知的配置和 CLI 诊断信息。 |
|
||||
| `providerAuthEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量级提供商认证环境变量元数据。 |
|
||||
| `providerAuthAliases` | 否 | `Record<string, string>` | 应复用另一个提供商 id 进行认证查找的提供商 id，例如与基础提供商共享 API 密钥和 auth profile 的编码提供商。 |
|
||||
| `channelEnvVars` | 否 | `Record<string, string[]>` | OpenClaw 可在不加载插件代码的情况下检查的轻量级渠道环境变量元数据。将其用于通用启动 / 配置辅助工具需要识别的、由环境变量驱动的渠道设置或认证界面。 |
|
||||
| `providerAuthChoices` | 否 | `object[]` | 用于新手引导选择器、首选提供商解析和简单 CLI flag 绑定的轻量级认证选项元数据。 |
|
||||
| `activation` | 否 | `object` | 用于提供商、命令、渠道、路由和能力触发加载的轻量级激活提示。仅为元数据；实际行为仍由插件运行时负责。 |
|
||||
| `setup` | 否 | `object` | 供发现和设置界面在不加载插件运行时的情况下检查的轻量级设置 / 新手引导描述符。 |
|
||||
| `qaRunners` | 否 | `object[]` | 共享 `openclaw qa` 主机在插件运行时加载前使用的轻量级 QA 运行器描述符。 |
|
||||
| `contracts` | 否 | `object` | 面向外部认证 hook、语音、实时转录、实时语音、媒体理解、图像生成、音乐生成、视频生成、网页抓取、Web 搜索和工具归属的静态内置能力快照。 |
|
||||
| `mediaUnderstandingProviderMetadata` | 否 | `Record<string, object>` | 为 `contracts.mediaUnderstandingProviders` 中声明的提供商 id 提供的轻量级媒体理解默认元数据。 |
|
||||
| `channelConfigs` | 否 | `Record<string, object>` | 在运行时加载前，合并到发现和验证界面中的、由清单拥有的渠道配置元数据。 |
|
||||
| `skills` | 否 | `string[]` | 要加载的 Skills 目录，相对于插件根目录。 |
|
||||
| `name` | 否 | `string` | 人类可读的插件名称。 |
|
||||
| `description` | 否 | `string` | 显示在插件界面中的简短摘要。 |
|
||||
| `description` | 否 | `string` | 在插件界面中显示的简短摘要。 |
|
||||
| `version` | 否 | `string` | 信息性插件版本。 |
|
||||
| `uiHints` | 否 | `Record<string, object>` | 配置字段的 UI 标签、占位符和敏感性提示。 |
|
||||
|
||||
## `providerAuthChoices` 参考
|
||||
|
||||
每个 `providerAuthChoices` 条目描述一个新手引导或认证选项。
|
||||
OpenClaw 会在提供商运行时加载前读取它。
|
||||
OpenClaw 会在提供商运行时加载之前读取它。
|
||||
|
||||
| 字段 | 必填 | 类型 | 含义 |
|
||||
| --------------------- | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | 是 | `string` | 此选项所属的提供商 id。 |
|
||||
| `method` | 是 | `string` | 要分派到的认证方法 id。 |
|
||||
| `method` | 是 | `string` | 要分发到的认证方法 id。 |
|
||||
| `choiceId` | 是 | `string` | 供新手引导和 CLI 流程使用的稳定认证选项 id。 |
|
||||
| `choiceLabel` | 否 | `string` | 面向用户的标签。如果省略，OpenClaw 会回退到 `choiceId`。 |
|
||||
| `choiceHint` | 否 | `string` | 选择器的简短辅助文本。 |
|
||||
| `choiceLabel` | 否 | `string` | 面向用户的标签。若省略，OpenClaw 会回退为 `choiceId`。 |
|
||||
| `choiceHint` | 否 | `string` | 选择器中的简短辅助文本。 |
|
||||
| `assistantPriority` | 否 | `number` | 在由助手驱动的交互式选择器中，值越小排序越靠前。 |
|
||||
| `assistantVisibility` | 否 | `"visible"` \| `"manual-only"` | 在助手选择器中隐藏该选项，但仍允许手动通过 CLI 选择。 |
|
||||
| `deprecatedChoiceIds` | 否 | `string[]` | 应将用户重定向到此替代选项的旧版选项 id。 |
|
||||
| `groupId` | 否 | `string` | 用于对相关选项分组的可选组 id。 |
|
||||
| `groupLabel` | 否 | `string` | 该组的面向用户标签。 |
|
||||
| `groupHint` | 否 | `string` | 该组的简短辅助文本。 |
|
||||
| `optionKey` | 否 | `string` | 用于简单单标志认证流程的内部选项键。 |
|
||||
| `cliFlag` | 否 | `string` | CLI 标志名称，例如 `--openrouter-api-key`。 |
|
||||
| `groupId` | 否 | `string` | 用于分组相关选项的可选分组 id。 |
|
||||
| `groupLabel` | 否 | `string` | 该分组面向用户的标签。 |
|
||||
| `groupHint` | 否 | `string` | 该分组的简短辅助文本。 |
|
||||
| `optionKey` | 否 | `string` | 用于简单单 flag 认证流程的内部选项键。 |
|
||||
| `cliFlag` | 否 | `string` | CLI flag 名称，例如 `--openrouter-api-key`。 |
|
||||
| `cliOption` | 否 | `string` | 完整 CLI 选项形式，例如 `--openrouter-api-key <key>`。 |
|
||||
| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的说明。 |
|
||||
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应出现在哪些新手引导界面中。如果省略，默认值为 `["text-inference"]`。 |
|
||||
| `cliDescription` | 否 | `string` | 用于 CLI 帮助中的描述。 |
|
||||
| `onboardingScopes` | 否 | `Array<"text-inference" \| "image-generation">` | 此选项应显示在哪些新手引导界面中。若省略，默认值为 `["text-inference"]`。 |
|
||||
|
||||
## `commandAliases` 参考
|
||||
|
||||
当插件拥有一个运行时命令名称，而用户可能会误将其放入 `plugins.allow`，或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw 使用此元数据在不导入插件运行时代码的情况下提供诊断信息。
|
||||
当插件拥有一个运行时命令名，而用户可能
|
||||
错误地将其放入 `plugins.allow` 或尝试将其作为根 CLI 命令运行时，请使用 `commandAliases`。OpenClaw
|
||||
使用此元数据在不导入插件运行时代码的情况下提供诊断信息。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -205,15 +217,18 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
| ------------ | -------- | ----------------- | ----------------------------------------------------------------------- |
|
||||
| `name` | 是 | `string` | 属于此插件的命令名称。 |
|
||||
| `kind` | 否 | `"runtime-slash"` | 将该别名标记为聊天斜杠命令，而不是根 CLI 命令。 |
|
||||
| `cliCommand` | 否 | `string` | 若存在相关根 CLI 命令，则建议用于 CLI 操作的该命令。 |
|
||||
| `cliCommand` | 否 | `string` | 若存在，用于建议给 CLI 操作的相关根 CLI 命令。 |
|
||||
|
||||
## `activation` 参考
|
||||
|
||||
当插件可以以低成本声明哪些控制平面事件应在之后激活它时，请使用 `activation`。
|
||||
当插件能够以低成本声明后续哪些控制平面事件
|
||||
应激活它时，请使用 `activation`。
|
||||
|
||||
## `qaRunners` 参考
|
||||
|
||||
当插件在共享的 `openclaw qa` 根命令下提供一个或多个传输运行器时，请使用 `qaRunners`。保持此元数据轻量且静态；插件运行时仍通过导出 `qaRunnerCliRegistrations` 的轻量 `runtime-api.ts` 界面拥有实际 CLI 注册逻辑。
|
||||
当插件在共享 `openclaw qa` 根命令下贡献一个或多个传输运行器时，请使用 `qaRunners`。保持此元数据轻量且静态；实际的 CLI 注册仍由插件
|
||||
运行时通过导出 `qaRunnerCliRegistrations` 的轻量级
|
||||
`runtime-api.ts` 接口负责。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -229,11 +244,13 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
| 字段 | 必填 | 类型 | 含义 |
|
||||
| ------------- | -------- | -------- | ------------------------------------------------------------------ |
|
||||
| `commandName` | 是 | `string` | 挂载在 `openclaw qa` 下的子命令，例如 `matrix`。 |
|
||||
| `description` | 否 | `string` | 当共享主机需要一个存根命令时使用的回退帮助文本。 |
|
||||
| `description` | 否 | `string` | 当共享主机需要一个占位命令时使用的回退帮助文本。 |
|
||||
|
||||
此块仅为元数据。它不会注册运行时行为，也不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。
|
||||
|
||||
当前消费者会将其用作在更广泛插件加载前的缩小范围提示，因此缺少激活元数据通常只会带来性能成本；只要旧版清单归属回退仍然存在，它就不应影响正确性。
|
||||
这个区块仅是元数据。它不会注册运行时行为，也
|
||||
不会替代 `register(...)`、`setupEntry` 或其他运行时 / 插件入口点。
|
||||
当前使用方将其作为在更广泛插件加载前缩小范围的提示，因此
|
||||
缺失激活元数据通常只会带来性能损耗；在旧版清单归属回退仍存在时，
|
||||
它不应改变正确性。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -249,21 +266,25 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
|
||||
| 字段 | 必填 | 类型 | 含义 |
|
||||
| ---------------- | -------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
|
||||
| `onProviders` | 否 | `string[]` | 请求这些提供商 id 时应激活此插件。 |
|
||||
| `onProviders` | 否 | `string[]` | 当请求这些提供商 id 时，应激活此插件。 |
|
||||
| `onCommands` | 否 | `string[]` | 应激活此插件的命令 id。 |
|
||||
| `onChannels` | 否 | `string[]` | 应激活此插件的渠道 id。 |
|
||||
| `onRoutes` | 否 | `string[]` | 应激活此插件的路由类型。 |
|
||||
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的广义能力提示。 |
|
||||
| `onCapabilities` | 否 | `Array<"provider" \| "channel" \| "tool" \| "hook">` | 控制平面激活规划使用的宽泛能力提示。 |
|
||||
|
||||
当前在线使用方：
|
||||
当前实时使用方：
|
||||
|
||||
- 由命令触发的 CLI 规划会回退到旧版 `commandAliases[].cliCommand` 或 `commandAliases[].name`
|
||||
- 当缺少显式渠道激活元数据时，由渠道触发的设置 / 渠道规划会回退到旧版 `channels[]` 归属
|
||||
- 当缺少显式提供商激活元数据时，由提供商触发的设置 / 运行时规划会回退到旧版 `providers[]` 和顶层 `cliBackends[]` 归属
|
||||
- 由命令触发的 CLI 规划会回退到旧版
|
||||
`commandAliases[].cliCommand` 或 `commandAliases[].name`
|
||||
- 当缺少显式渠道激活元数据时，渠道触发的设置 / 渠道规划会回退到旧版 `channels[]`
|
||||
归属
|
||||
- 当缺少显式提供商激活元数据时，提供商触发的设置 / 运行时规划会回退到旧版
|
||||
`providers[]` 和顶层 `cliBackends[]` 归属
|
||||
|
||||
## `setup` 参考
|
||||
|
||||
当设置和新手引导界面需要在运行时加载前读取轻量、由插件拥有的元数据时，请使用 `setup`。
|
||||
当设置和新手引导界面在运行时加载前需要轻量级、由插件拥有的元数据时，
|
||||
请使用 `setup`。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -282,18 +303,25 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
}
|
||||
```
|
||||
|
||||
顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理后端。`setup.cliBackends` 是控制平面 / 设置流程的设置专用描述符界面，应保持为纯元数据。
|
||||
顶层 `cliBackends` 仍然有效，并继续描述 CLI 推理
|
||||
后端。`setup.cliBackends` 是面向控制平面 / 设置流程的
|
||||
设置专用描述符接口，应保持仅元数据。
|
||||
|
||||
如果存在，`setup.providers` 和 `setup.cliBackends` 是设置发现时首选的描述符优先查找界面。如果该描述符只用于缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook，请将 `requiresRuntime` 设为 `true`，并保留 `setup-api` 作为回退执行路径。
|
||||
存在时，`setup.providers` 和 `setup.cliBackends` 是设置发现时首选的
|
||||
“描述符优先”查找接口。如果描述符只能缩小候选插件范围，而设置仍需要更丰富的设置期运行时 hook，
|
||||
请设置 `requiresRuntime: true`，并保留 `setup-api` 作为
|
||||
回退执行路径。
|
||||
|
||||
由于设置查找可能会执行插件拥有的 `setup-api` 代码，规范化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在已发现插件之间保持唯一。归属不明确时会默认失败关闭，而不是按发现顺序选出一个赢家。
|
||||
由于设置查找可能执行由插件拥有的 `setup-api` 代码，
|
||||
标准化后的 `setup.providers[].id` 和 `setup.cliBackends[]` 值必须在所有已发现插件中保持唯一。
|
||||
归属不明确时会以保守方式失败关闭，而不是按发现顺序挑选赢家。
|
||||
|
||||
### `setup.providers` 参考
|
||||
|
||||
| 字段 | 必填 | 类型 | 含义 |
|
||||
| ------------- | -------- | ---------- | ------------------------------------------------------------------------------------ |
|
||||
| `id` | 是 | `string` | 在设置或新手引导期间暴露的提供商 id。保持规范化 id 在全局唯一。 |
|
||||
| `authMethods` | 否 | `string[]` | 此提供商在不加载完整运行时的情况下支持的设置 / 认证方法 id。 |
|
||||
| `id` | 是 | `string` | 在设置或新手引导期间暴露的提供商 id。保持标准化 id 在全局范围内唯一。 |
|
||||
| `authMethods` | 否 | `string[]` | 该提供商在不加载完整运行时的情况下支持的设置 / 认证方法 id。 |
|
||||
| `envVars` | 否 | `string[]` | 通用设置 / 状态界面可在插件运行时加载前检查的环境变量。 |
|
||||
|
||||
### `setup` 字段
|
||||
@ -301,13 +329,13 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
| 字段 | 必填 | 类型 | 含义 |
|
||||
| ------------------ | -------- | ---------- | --------------------------------------------------------------------------------------------------- |
|
||||
| `providers` | 否 | `object[]` | 在设置和新手引导期间暴露的提供商设置描述符。 |
|
||||
| `cliBackends` | 否 | `string[]` | 用于描述符优先设置查找的设置期后端 id。保持规范化 id 在全局唯一。 |
|
||||
| `configMigrations` | 否 | `string[]` | 由此插件设置界面拥有的配置迁移 id。 |
|
||||
| `cliBackends` | 否 | `string[]` | 用于“描述符优先”设置查找的设置期后端 id。保持标准化 id 在全局范围内唯一。 |
|
||||
| `configMigrations` | 否 | `string[]` | 由此插件的设置界面拥有的配置迁移 id。 |
|
||||
| `requiresRuntime` | 否 | `boolean` | 在描述符查找之后，设置是否仍需要执行 `setup-api`。 |
|
||||
|
||||
## `uiHints` 参考
|
||||
|
||||
`uiHints` 是从配置字段名称到小型渲染提示的映射。
|
||||
`uiHints` 是从配置字段名到小型渲染提示的映射。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -328,14 +356,15 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
| ------------- | ---------- | --------------------------------------- |
|
||||
| `label` | `string` | 面向用户的字段标签。 |
|
||||
| `help` | `string` | 简短辅助文本。 |
|
||||
| `tags` | `string[]` | 可选 UI 标签。 |
|
||||
| `advanced` | `boolean` | 将该字段标记为高级。 |
|
||||
| `sensitive` | `boolean` | 将该字段标记为密钥或敏感信息。 |
|
||||
| `tags` | `string[]` | 可选的 UI 标签。 |
|
||||
| `advanced` | `boolean` | 将该字段标记为高级项。 |
|
||||
| `sensitive` | `boolean` | 将该字段标记为机密或敏感。 |
|
||||
| `placeholder` | `string` | 表单输入的占位文本。 |
|
||||
|
||||
## `contracts` 参考
|
||||
|
||||
仅将 `contracts` 用于 OpenClaw 可在不导入插件运行时的情况下读取的静态能力归属元数据。
|
||||
仅在 OpenClaw 可以在不导入插件运行时的情况下
|
||||
读取静态能力归属元数据时，才使用 `contracts`。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -360,22 +389,28 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
| 字段 | 类型 | 含义 |
|
||||
| -------------------------------- | ---------- | ----------------------------------------------------------------- |
|
||||
| `embeddedExtensionFactories` | `string[]` | 内置插件可为其注册工厂的嵌入式运行时 id。 |
|
||||
| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证配置文件 hook 的提供商 id。 |
|
||||
| `speechProviders` | `string[]` | 此插件拥有的 speech 提供商 id。 |
|
||||
| `externalAuthProviders` | `string[]` | 此插件拥有其外部认证 profile hook 的提供商 id。 |
|
||||
| `speechProviders` | `string[]` | 此插件拥有的语音提供商 id。 |
|
||||
| `realtimeTranscriptionProviders` | `string[]` | 此插件拥有的实时转录提供商 id。 |
|
||||
| `realtimeVoiceProviders` | `string[]` | 此插件拥有的实时语音提供商 id。 |
|
||||
| `mediaUnderstandingProviders` | `string[]` | 此插件拥有的媒体理解提供商 id。 |
|
||||
| `imageGenerationProviders` | `string[]` | 此插件拥有的图像生成提供商 id。 |
|
||||
| `videoGenerationProviders` | `string[]` | 此插件拥有的视频生成提供商 id。 |
|
||||
| `webFetchProviders` | `string[]` | 此插件拥有的网页抓取提供商 id。 |
|
||||
| `webSearchProviders` | `string[]` | 此插件拥有的网页搜索提供商 id。 |
|
||||
| `tools` | `string[]` | 此插件为内置合约检查所拥有的智能体工具名称。 |
|
||||
| `webSearchProviders` | `string[]` | 此插件拥有的 Web 搜索提供商 id。 |
|
||||
| `tools` | `string[]` | 此插件为内置契约检查所拥有的智能体工具名称。 |
|
||||
|
||||
实现 `resolveExternalAuthProfiles` 的提供商插件应声明 `contracts.externalAuthProviders`。未声明的插件仍会通过已弃用的兼容性回退路径运行，但该回退更慢，并将在迁移窗口结束后移除。
|
||||
实现 `resolveExternalAuthProfiles` 的提供商插件应声明
|
||||
`contracts.externalAuthProviders`。未声明该项的插件仍会通过
|
||||
已弃用的兼容性回退路径运行，但该回退更慢，
|
||||
并将在迁移窗口结束后移除。
|
||||
|
||||
## `mediaUnderstandingProviderMetadata` 参考
|
||||
|
||||
当媒体理解提供商具有默认模型、自动认证回退优先级，或通用核心辅助逻辑在运行时加载前所需的原生文档支持时，请使用 `mediaUnderstandingProviderMetadata`。键名也必须在 `contracts.mediaUnderstandingProviders` 中声明。
|
||||
当媒体理解提供商具有默认模型、自动认证回退优先级，
|
||||
或需要通用核心辅助工具在运行时加载前知晓的原生文档支持时，
|
||||
请使用 `mediaUnderstandingProviderMetadata`。其键也必须在
|
||||
`contracts.mediaUnderstandingProviders` 中声明。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -403,13 +438,14 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
| 字段 | 类型 | 含义 |
|
||||
| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- |
|
||||
| `capabilities` | `("image" \| "audio" \| "video")[]` | 此提供商公开的媒体能力。 |
|
||||
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的“能力到模型”默认映射。 |
|
||||
| `autoPriority` | `Record<string, number>` | 用于基于凭证的自动提供商回退时，数值越小排序越靠前。 |
|
||||
| `defaultModels` | `Record<string, string>` | 当配置未指定模型时使用的能力到模型默认映射。 |
|
||||
| `autoPriority` | `Record<string, number>` | 对于基于凭证的自动提供商回退，数字越小排序越靠前。 |
|
||||
| `nativeDocumentInputs` | `"pdf"[]` | 该提供商支持的原生文档输入。 |
|
||||
|
||||
## `channelConfigs` 参考
|
||||
|
||||
当渠道插件在运行时加载前需要轻量配置元数据时，请使用 `channelConfigs`。
|
||||
当渠道插件在运行时加载前需要轻量级配置元数据时，
|
||||
请使用 `channelConfigs`。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -441,14 +477,16 @@ OpenClaw 会在提供商运行时加载前读取它。
|
||||
| 字段 | 类型 | 含义 |
|
||||
| ------------- | ------------------------ | ----------------------------------------------------------------------------------------- |
|
||||
| `schema` | `object` | `channels.<id>` 的 JSON Schema。每个已声明的渠道配置条目都必须提供。 |
|
||||
| `uiHints` | `Record<string, object>` | 该渠道配置部分的可选 UI 标签 / 占位符 / 敏感性提示。 |
|
||||
| `uiHints` | `Record<string, object>` | 该渠道配置区块的可选 UI 标签 / 占位符 / 敏感性提示。 |
|
||||
| `label` | `string` | 当运行时元数据尚未就绪时，合并到选择器和检查界面中的渠道标签。 |
|
||||
| `description` | `string` | 用于检查和目录界面的简短渠道说明。 |
|
||||
| `preferOver` | `string[]` | 在选择界面中，此渠道应优先于的旧版或较低优先级插件 id。 |
|
||||
| `description` | `string` | 用于检查和目录界面的简短渠道描述。 |
|
||||
| `preferOver` | `string[]` | 此渠道在选择界面中应优先于的旧版或较低优先级插件 id。 |
|
||||
|
||||
## `modelSupport` 参考
|
||||
|
||||
当 OpenClaw 应在插件运行时加载前，根据 `gpt-5.4` 或 `claude-sonnet-4.6` 之类的简写模型 id 推断你的提供商插件时，请使用 `modelSupport`。
|
||||
当 OpenClaw 应该在插件运行时加载前，
|
||||
根据 `gpt-5.5` 或 `claude-sonnet-4.6` 这样的简写模型 id 推断你的提供商插件时，
|
||||
请使用 `modelSupport`。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -463,35 +501,43 @@ OpenClaw 按以下优先级处理：
|
||||
|
||||
- 显式 `provider/model` 引用使用所属 `providers` 清单元数据
|
||||
- `modelPatterns` 优先于 `modelPrefixes`
|
||||
- 如果一个非内置插件和一个内置插件都匹配，则非内置插件胜出
|
||||
- 其余歧义会被忽略，直到用户或配置明确指定提供商
|
||||
- 如果一个非内置插件和一个内置插件同时匹配，则非内置
|
||||
插件胜出
|
||||
- 对于剩余的歧义，在用户或配置指定提供商之前会被忽略
|
||||
|
||||
字段：
|
||||
|
||||
| 字段 | 类型 | 含义 |
|
||||
| --------------- | ---------- | ------------------------------------------------------------------------------- |
|
||||
| `modelPrefixes` | `string[]` | 对简写模型 id 使用 `startsWith` 进行匹配的前缀。 |
|
||||
| `modelPatterns` | `string[]` | 在移除配置文件后缀后，对简写模型 id 进行匹配的正则表达式源码。 |
|
||||
| `modelPatterns` | `string[]` | 在移除 profile 后缀后，对简写模型 id 进行匹配的正则来源字符串。 |
|
||||
|
||||
旧版顶层能力键已弃用。使用 `openclaw doctor --fix` 将 `speechProviders`、`realtimeTranscriptionProviders`、`realtimeVoiceProviders`、`mediaUnderstandingProviders`、`imageGenerationProviders`、`videoGenerationProviders`、`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规清单加载不再将这些顶层字段视为能力归属。
|
||||
旧版顶层 capability 键已弃用。请使用 `openclaw doctor --fix` 将
|
||||
`speechProviders`、`realtimeTranscriptionProviders`、
|
||||
`realtimeVoiceProviders`、`mediaUnderstandingProviders`、
|
||||
`imageGenerationProviders`、`videoGenerationProviders`、
|
||||
`webFetchProviders` 和 `webSearchProviders` 移动到 `contracts` 下；常规
|
||||
清单加载已不再将这些顶层字段视为 capability
|
||||
归属信息。
|
||||
|
||||
## 清单与 `package.json`
|
||||
|
||||
这两个文件承担不同职责：
|
||||
这两个文件的职责不同：
|
||||
|
||||
| 文件 | 用途 |
|
||||
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `openclaw.plugin.json` | 设备发现、配置校验、认证选项元数据，以及必须在插件代码运行前存在的 UI 提示 |
|
||||
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 代码块 |
|
||||
| `openclaw.plugin.json` | 发现、配置验证、认证选项元数据，以及必须在插件代码运行前存在的 UI 提示 |
|
||||
| `package.json` | npm 元数据、依赖安装，以及用于入口点、安装门控、设置或目录元数据的 `openclaw` 区块 |
|
||||
|
||||
如果你不确定某项元数据应该放在哪里，请使用以下规则：
|
||||
如果你不确定某项元数据应放在哪里，请使用以下规则：
|
||||
|
||||
- 如果 OpenClaw 必须在加载插件代码前知道它，就放入 `openclaw.plugin.json`
|
||||
- 如果它与打包、入口文件或 npm 安装行为有关，就放入 `package.json`
|
||||
- 如果 OpenClaw 必须在加载插件代码之前知道它，就放进 `openclaw.plugin.json`
|
||||
- 如果它与打包、入口文件或 npm 安装行为有关，就放进 `package.json`
|
||||
|
||||
### 影响设备发现的 `package.json` 字段
|
||||
### 影响发现的 `package.json` 字段
|
||||
|
||||
某些运行时前的插件元数据会有意放在 `package.json` 的 `openclaw` 代码块下，而不是 `openclaw.plugin.json` 中。
|
||||
有些运行时前的插件元数据有意放在 `package.json` 的
|
||||
`openclaw` 区块中，而不是 `openclaw.plugin.json` 中。
|
||||
|
||||
重要示例：
|
||||
|
||||
@ -499,31 +545,52 @@ OpenClaw 按以下优先级处理：
|
||||
| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `openclaw.extensions` | 声明原生插件入口点。必须保持在插件包目录内。 |
|
||||
| `openclaw.runtimeExtensions` | 为已安装包声明构建后的 JavaScript 运行时入口点。必须保持在插件包目录内。 |
|
||||
| `openclaw.setupEntry` | 在新手引导、延迟渠道启动和只读渠道状态 / SecretRef 发现期间使用的轻量仅设置入口点。必须保持在插件包目录内。 |
|
||||
| `openclaw.setupEntry` | 在新手引导、延后渠道启动以及只读渠道状态 / SecretRef 发现期间使用的轻量级仅设置入口点。必须保持在插件包目录内。 |
|
||||
| `openclaw.runtimeSetupEntry` | 为已安装包声明构建后的 JavaScript 设置入口点。必须保持在插件包目录内。 |
|
||||
| `openclaw.channel` | 轻量渠道目录元数据，例如标签、文档路径、别名和选择文案。 |
|
||||
| `openclaw.channel.configuredState` | 轻量已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅环境变量的设置？”。 |
|
||||
| `openclaw.channel.persistedAuthState` | 轻量持久化认证状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已有任何内容登录？”。 |
|
||||
| `openclaw.channel` | 轻量级渠道目录元数据，例如标签、文档路径、别名和选择说明文案。 |
|
||||
| `openclaw.channel.configuredState` | 轻量级已配置状态检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已存在仅靠环境变量的设置？” |
|
||||
| `openclaw.channel.persistedAuthState` | 轻量级持久化认证检查器元数据，可在不加载完整渠道运行时的情况下回答“是否已经有任何账号登录？” |
|
||||
| `openclaw.install.npmSpec` / `openclaw.install.localPath` | 内置和外部发布插件的安装 / 更新提示。 |
|
||||
| `openclaw.install.defaultChoice` | 当有多个安装来源可用时的首选安装路径。 |
|
||||
| `openclaw.install.minHostVersion` | 最低支持的 OpenClaw 主机版本，使用如 `>=2026.3.22` 这样的 semver 下限。 |
|
||||
| `openclaw.install.expectedIntegrity` | 预期的 npm 分发完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取的制品。 |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个受限的内置插件重新安装恢复路径。 |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许在启动期间，完整渠道插件之前先加载仅设置的渠道界面。 |
|
||||
| `openclaw.install.defaultChoice` | 当存在多个安装来源时，首选的安装路径。 |
|
||||
| `openclaw.install.minHostVersion` | 最低受支持的 OpenClaw 主机版本，使用类似 `>=2026.3.22` 的 semver 下限。 |
|
||||
| `openclaw.install.expectedIntegrity` | 预期的 npm dist 完整性字符串，例如 `sha512-...`；安装和更新流程会据此校验获取到的制品。 |
|
||||
| `openclaw.install.allowInvalidConfigRecovery` | 当配置无效时，允许一个范围很窄的内置插件重装恢复路径。 |
|
||||
| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | 允许仅设置的渠道界面在启动期间先于完整渠道插件加载。 |
|
||||
|
||||
清单元数据决定在运行时加载前，新手引导中会出现哪些提供商 / 渠道 / 设置选项。`package.json#openclaw.install` 告诉新手引导在用户选择其中某项时，如何获取或启用该插件。不要将安装提示移动到 `openclaw.plugin.json` 中。
|
||||
清单元数据决定了在运行时加载前，
|
||||
新手引导中会出现哪些提供商 / 渠道 / 设置选项。`package.json#openclaw.install` 告诉
|
||||
新手引导，当用户选择这些选项之一时，应如何获取或启用该插件。不要将安装提示移入 `openclaw.plugin.json`。
|
||||
|
||||
`openclaw.install.minHostVersion` 会在安装和清单注册表加载期间强制执行。无效值会被拒绝；较新但有效的值会使旧主机跳过该插件。
|
||||
`openclaw.install.minHostVersion` 会在安装和清单
|
||||
注册表加载期间强制执行。无效值会被拒绝；较新的但有效的值会使插件在较旧主机上被跳过。
|
||||
|
||||
精确的 npm 版本固定已存在于 `npmSpec` 中，例如 `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。如果你希望在获取的 npm 制品不再匹配固定发布版本时，让更新流程默认失败关闭，请将其与 `expectedIntegrity` 搭配使用。交互式新手引导会提供受信任注册表 npm 规格，包括裸包名和 dist-tag。存在 `expectedIntegrity` 时，安装 / 更新流程会强制执行它；省略时，注册表解析结果会被记录，但不会附带完整性固定。
|
||||
精确的 npm 版本固定已经放在 `npmSpec` 中，例如
|
||||
`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`。当你希望更新流程在获取到的
|
||||
npm 制品不再匹配固定版本时以保守方式失败，请将其与
|
||||
`expectedIntegrity` 搭配使用。交互式新手引导
|
||||
会提供可信注册表 npm 规范，包括裸包名和 dist-tag。
|
||||
当存在 `expectedIntegrity` 时，安装 / 更新流程会强制校验它；当省略时，
|
||||
会记录注册表解析结果，但不附带完整性固定。
|
||||
|
||||
当状态、渠道列表或 SecretRef 扫描需要在不加载完整运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。设置入口点应公开渠道元数据，以及对设置安全的配置、状态和 secrets 适配器；将网络客户端、Gateway 网关监听器和传输运行时保留在主扩展入口点中。
|
||||
当状态、渠道列表或 SecretRef 扫描需要在不加载完整
|
||||
运行时的情况下识别已配置账号时，渠道插件应提供 `openclaw.setupEntry`。
|
||||
该设置入口点应公开渠道元数据以及适用于设置场景的配置、
|
||||
状态和密钥适配器；网络客户端、Gateway 网关监听器和
|
||||
传输运行时应保留在主扩展入口点中。
|
||||
|
||||
运行时入口点字段不会绕过针对源码入口点字段的包边界检查。例如，`openclaw.runtimeExtensions` 不能让一个越界的 `openclaw.extensions` 路径变得可加载。
|
||||
运行时入口点字段不会覆盖针对源码
|
||||
入口点字段的包边界检查。例如，
|
||||
`openclaw.runtimeExtensions` 不能让越界的 `openclaw.extensions` 路径变为可加载。
|
||||
|
||||
`openclaw.install.allowInvalidConfigRecovery` 的设计范围是刻意收窄的。它不会让任意损坏的配置变得可安装。当前它只允许安装流程从特定的陈旧内置插件升级失败中恢复，例如缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.<id>` 条目。无关的配置错误仍会阻止安装，并引导运维人员执行 `openclaw doctor --fix`。
|
||||
`openclaw.install.allowInvalidConfigRecovery` 的设计范围刻意很窄。它并
|
||||
不会让任意损坏的配置都变得可安装。
|
||||
目前它仅允许安装流程从某些特定的陈旧内置插件升级失败中恢复，例如
|
||||
缺失的内置插件路径，或同一内置插件对应的陈旧 `channels.<id>` 条目。
|
||||
无关的配置错误仍会阻止安装，并将操作人员引导到
|
||||
`openclaw doctor --fix`。
|
||||
|
||||
`openclaw.channel.persistedAuthState` 是一个微型检查器模块的包元数据：
|
||||
`openclaw.channel.persistedAuthState` 是一个微型检查器
|
||||
模块的包元数据：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -539,9 +606,12 @@ OpenClaw 按以下优先级处理：
|
||||
}
|
||||
```
|
||||
|
||||
当设置、Doctor 或已配置状态流程需要在完整渠道插件加载前执行一个低成本的“是 / 否”认证探测时，请使用它。目标导出应是一个只读取持久化状态的小函数；不要通过完整渠道运行时 barrel 转发它。
|
||||
当设置、Doctor 或已配置状态流程在完整渠道插件加载前，
|
||||
需要一个低成本的“是 / 否”认证探测时，请使用它。目标导出应是一个仅仅读取持久化状态的小函数；
|
||||
不要通过完整渠道运行时 barrel 转发它。
|
||||
|
||||
`openclaw.channel.configuredState` 对低成本的仅环境变量已配置检查采用相同结构：
|
||||
`openclaw.channel.configuredState` 对低成本、仅基于环境变量的
|
||||
已配置检查采用相同形式：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -557,50 +627,57 @@ OpenClaw 按以下优先级处理：
|
||||
}
|
||||
```
|
||||
|
||||
当一个渠道可以根据环境变量或其他微型非运行时输入回答已配置状态时，请使用它。如果检查需要完整配置解析或真实渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState` hook 中。
|
||||
当某个渠道可以仅根据环境变量或其他轻量级
|
||||
非运行时输入来判断已配置状态时，请使用它。如果检查需要完整配置解析或真实的
|
||||
渠道运行时，请将该逻辑保留在插件 `config.hasConfiguredState`
|
||||
hook 中。
|
||||
|
||||
## 设备发现优先级（重复插件 id）
|
||||
## 发现优先级（重复插件 id）
|
||||
|
||||
OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区、配置中显式选择的路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；低优先级的重复项会被丢弃，而不会与其并列加载。
|
||||
OpenClaw 会从多个根位置发现插件（内置、全局安装、工作区、显式配置选定路径）。如果两个发现结果共享相同的 `id`，则只保留**优先级最高**的清单；较低优先级的重复项会被丢弃，而不是与之并行加载。
|
||||
|
||||
优先级从高到低如下：
|
||||
|
||||
1. **配置中选定** —— 在 `plugins.entries.<id>` 中显式固定的路径
|
||||
2. **内置** —— 随 OpenClaw 一起发布的插件
|
||||
1. **配置选定** —— 在 `plugins.entries.<id>` 中显式固定的路径
|
||||
2. **内置** —— 随 OpenClaw 一起分发的插件
|
||||
3. **全局安装** —— 安装到全局 OpenClaw 插件根目录中的插件
|
||||
4. **工作区** —— 相对于当前工作区发现的插件
|
||||
|
||||
影响：
|
||||
|
||||
- 工作区中放置的某个内置插件分叉版本或陈旧副本，不会覆盖内置构建版本。
|
||||
- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它，使其依靠优先级获胜，而不是依赖工作区发现。
|
||||
- 被丢弃的重复项会被记录日志，以便 Doctor 和启动诊断能指向被舍弃的副本。
|
||||
- 工作区中某个内置插件的 fork 或陈旧副本不会遮蔽内置构建版本。
|
||||
- 若要真正用本地插件覆盖内置插件，请通过 `plugins.entries.<id>` 固定它，使其通过优先级获胜，而不是依赖工作区发现。
|
||||
- 被丢弃的重复项会记录日志，以便 Doctor 和启动诊断指出被丢弃的副本。
|
||||
|
||||
## JSON Schema 要求
|
||||
|
||||
- **每个插件都必须提供一个 JSON Schema**，即使它不接受任何配置。
|
||||
- 可以使用空 schema（例如 `{ "type": "object", "additionalProperties": false }`）。
|
||||
- Schema 会在配置读写时校验，而不是在运行时校验。
|
||||
- Schema 会在配置读取 / 写入时验证，而不是在运行时验证。
|
||||
|
||||
## 校验行为
|
||||
## 验证行为
|
||||
|
||||
- 未知的 `channels.*` 键是**错误**，除非该渠道 id 由某个插件清单声明。
|
||||
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*` 必须引用**可发现的**插件 id。未知 id 是**错误**。
|
||||
- 如果某个插件已安装，但其清单或 schema 损坏或缺失，校验会失败，Doctor 会报告该插件错误。
|
||||
- 如果插件配置存在，但插件处于**禁用**状态，该配置会被保留，并且 Doctor + 日志中会显示**警告**。
|
||||
- 未知的 `channels.*` 键会被视为**错误**，除非该渠道 id 已由
|
||||
某个插件清单声明。
|
||||
- `plugins.entries.<id>`、`plugins.allow`、`plugins.deny` 和 `plugins.slots.*`
|
||||
必须引用**可发现的**插件 id。未知 id 会被视为**错误**。
|
||||
- 如果某个插件已安装，但其清单或 schema 损坏或缺失，
|
||||
验证将失败，Doctor 会报告该插件错误。
|
||||
- 如果插件配置存在，但插件**已禁用**，则配置会被保留，
|
||||
并且 Doctor + 日志中会显示**警告**。
|
||||
|
||||
完整的 `plugins.*` schema，请参阅[配置参考](/zh-CN/gateway/configuration)。
|
||||
有关完整的 `plugins.*` schema，请参见 [配置参考](/zh-CN/gateway/configuration)。
|
||||
|
||||
## 说明
|
||||
|
||||
- 对于原生 OpenClaw 插件，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于设备发现 + 校验。
|
||||
- 原生清单使用 JSON5 解析，因此允许注释、尾随逗号和未加引号的键，只要最终值仍然是一个对象即可。
|
||||
- 清单加载器只读取文档中说明的清单字段。避免使用自定义顶层键。
|
||||
- 当插件不需要时，可以省略 `channels`、`providers`、`cliBackends` 和 `skills`。
|
||||
- 互斥插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 对应 `plugins.slots.memory`，`kind: "context-engine"` 对应 `plugins.slots.contextEngine`（默认 `legacy`）。
|
||||
- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅是声明式的。状态、审计、cron 投递校验及其他只读界面在将某个环境变量视为已配置之前，仍会应用插件信任和有效激活策略。
|
||||
- 有关需要提供商代码的运行时向导元数据，请参阅[提供商运行时 hooks](/zh-CN/plugins/architecture#provider-runtime-hooks)。
|
||||
- 如果你的插件依赖原生模块，请记录构建步骤以及所有包管理器 allowlist 要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild <package>`）。
|
||||
- 对于**原生 OpenClaw 插件**，包括本地文件系统加载，清单都是**必需的**。运行时仍会单独加载插件模块；清单仅用于发现 + 验证。
|
||||
- 原生清单使用 JSON5 解析，因此支持注释、尾随逗号和未加引号的键，只要最终值仍然是对象即可。
|
||||
- 清单加载器只会读取文档中说明的清单字段。避免使用自定义顶层键。
|
||||
- 当插件不需要这些项时，`channels`、`providers`、`cliBackends` 和 `skills` 都可以省略。
|
||||
- 互斥插件类型通过 `plugins.slots.*` 选择：`kind: "memory"` 使用 `plugins.slots.memory`，`kind: "context-engine"` 使用 `plugins.slots.contextEngine`（默认 `legacy`）。
|
||||
- 环境变量元数据（`providerAuthEnvVars`、`channelEnvVars`）仅为声明式元数据。状态、审计、cron 投递验证以及其他只读界面在将环境变量视为已配置之前，仍会应用插件信任和生效中的激活策略。
|
||||
- 对于需要提供商代码的运行时向导元数据，请参见 [提供商运行时 hook](/zh-CN/plugins/architecture#provider-runtime-hooks)。
|
||||
- 如果你的插件依赖原生模块，请记录构建步骤以及任何包管理器允许列表要求（例如 pnpm `allow-build-scripts` + `pnpm rebuild <package>`）。
|
||||
|
||||
## 相关内容
|
||||
|
||||
@ -611,7 +688,7 @@ OpenClaw 会从多个根目录发现插件（内置、全局安装、工作区
|
||||
<Card title="插件架构" href="/zh-CN/plugins/architecture" icon="diagram-project">
|
||||
内部架构和能力模型。
|
||||
</Card>
|
||||
<Card title="SDK 概览" href="/zh-CN/plugins/sdk-overview" icon="book">
|
||||
<Card title="插件 SDK 概览" href="/zh-CN/plugins/sdk-overview" icon="book">
|
||||
插件 SDK 参考和子路径导入。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,53 +1,54 @@
|
||||
---
|
||||
read_when:
|
||||
- 你正在更改嵌入式智能体运行时或 Harness 注册表
|
||||
- 你正在从内置或受信任的插件注册一个智能体 Harness
|
||||
- 你正在从内置或受信任插件注册一个智能体 Harness
|
||||
- 你需要了解 Codex 插件与模型提供商之间的关系
|
||||
sidebarTitle: Agent Harness
|
||||
summary: 用于替换底层嵌入式智能体执行器的插件实验性 SDK 接口面
|
||||
summary: 面向替换底层嵌入式智能体执行器的插件的实验性 SDK 界面
|
||||
title: 智能体 Harness 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T16:04:43Z"
|
||||
generated_at: "2026-04-23T19:26:03Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: ec858acedaae8670c730022f8cc700499ac3b95d3d4144584e01051b224fee64
|
||||
source_hash: c0822248298c61f9dda7ec342558e8cda7c936876060b471ed01dc6c90779010
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 智能体 Harness 插件
|
||||
|
||||
**智能体 harness** 是一个已准备好的 OpenClaw 智能体单次轮次的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。
|
||||
**智能体 Harness** 是为一次已准备好的 OpenClaw 智能体轮次提供底层执行的执行器。
|
||||
它不是模型提供商，不是渠道，也不是工具注册表。
|
||||
|
||||
仅对内置或受信任的原生插件使用此接口面。该契约仍然是实验性的，因为参数类型有意映射当前的嵌入式运行器。
|
||||
仅将此界面用于内置或受信任的原生插件。该契约仍然是实验性的，因为其参数类型有意镜像当前的嵌入式运行器。
|
||||
|
||||
## 何时使用 harness
|
||||
## 何时使用 Harness
|
||||
|
||||
当某个模型家族拥有自己的原生会话运行时，而常规 OpenClaw 提供商传输抽象并不适合时，注册一个智能体 harness。
|
||||
当某个模型家族拥有自己的原生会话运行时，而普通的 OpenClaw 提供商传输层并不是正确抽象时，请注册一个智能体 Harness。
|
||||
|
||||
例如：
|
||||
示例：
|
||||
|
||||
- 拥有线程与压缩能力的原生 coding-agent 服务器
|
||||
- 必须流式传输原生计划 / 推理 / 工具事件的本地 CLI 或守护进程
|
||||
- 除 OpenClaw 会话转录之外，还需要自身 resume id 的模型运行时
|
||||
- 拥有线程和压缩能力的原生编码智能体服务器
|
||||
- 必须流式传输原生计划/推理/工具事件的本地 CLI 或守护进程
|
||||
- 除 OpenClaw 会话转录外，还需要维护自己 resume id 的模型运行时
|
||||
|
||||
不要仅仅为了添加一个新的 LLM API 而注册 harness。对于常规 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
|
||||
不要仅仅为了添加新的 LLM API 而注册 Harness。对于普通的 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
|
||||
|
||||
## 核心仍然负责的内容
|
||||
## 核心仍负责的内容
|
||||
|
||||
在选择 harness 之前，OpenClaw 已经解析了：
|
||||
在选择 Harness 之前，OpenClaw 已经完成了以下解析：
|
||||
|
||||
- 提供商和模型
|
||||
- 运行时凭证状态
|
||||
- 思考级别和上下文预算
|
||||
- OpenClaw 转录 / 会话文件
|
||||
- 运行时认证状态
|
||||
- thinking 级别和上下文预算
|
||||
- OpenClaw 转录/会话文件
|
||||
- 工作区、沙箱和工具策略
|
||||
- 渠道回复回调和流式传输回调
|
||||
- 模型回退和实时模型切换策略
|
||||
|
||||
这种划分是有意设计的。harness 运行的是一个已准备好的尝试；它不会选择提供商、替代渠道投递，或静默切换模型。
|
||||
这种划分是有意为之。Harness 运行的是一次已准备好的尝试；它不会选择提供商、替代渠道投递，也不会静默切换模型。
|
||||
|
||||
## 注册 harness
|
||||
## 注册一个 Harness
|
||||
|
||||
**导入：** `openclaw/plugin-sdk/agent-harness`
|
||||
|
||||
@ -85,64 +86,68 @@ export default definePluginEntry({
|
||||
|
||||
## 选择策略
|
||||
|
||||
OpenClaw 会在提供商 / 模型解析之后选择一个 harness：
|
||||
OpenClaw 会在提供商/模型解析之后选择 Harness：
|
||||
|
||||
1. 现有会话中记录的 harness id 优先生效，因此配置 / 环境变量的变化不会将该转录热切换到另一个运行时。
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` 会为尚未固定的会话强制使用具有该 id 的已注册 harness。
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI harness。
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 harness 是否支持已解析的提供商 / 模型。
|
||||
5. 如果没有匹配的已注册 harness，除非禁用了 PI 回退，否则 OpenClaw 会使用 PI。
|
||||
1. 现有会话中已记录的 Harness id 优先，这样配置/环境变更就不会将该转录热切换到另一个运行时。
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` 会为尚未固定的会话强制使用具有该 id 的已注册 Harness。
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI Harness。
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` 会询问已注册的 Harness 是否支持已解析的提供商/模型。
|
||||
5. 如果没有已注册的 Harness 匹配，OpenClaw 会使用 PI，除非已禁用 PI 回退。
|
||||
|
||||
插件 harness 失败会表现为运行失败。在 `auto` 模式下，仅当没有已注册的插件 harness 支持已解析的提供商 / 模型时，才会使用 PI 回退。一旦某个插件 harness 已接管一次运行，OpenClaw 就不会通过 PI 重放同一轮次，因为这可能改变凭证 / 运行时语义或造成副作用重复。
|
||||
插件 Harness 失败会表现为运行失败。在 `auto` 模式下，只有当没有已注册插件 Harness 支持已解析的提供商/模型时，才会使用 PI 回退。一旦某个插件 Harness 已认领一次运行，OpenClaw 就不会再通过 PI 重放同一轮次，因为这可能会改变认证/运行时语义，或导致副作用重复发生。
|
||||
|
||||
嵌入式运行后，所选 harness id 会与会话 id 一起持久化。在 harness 固定机制之前创建的旧会话，一旦拥有转录历史，就会被视为固定到 PI。要在 PI 与原生插件 harness 之间切换，请使用新的 / 重置后的会话。`/status` 会在 `Fast` 旁显示诸如 `codex` 之类的非默认 harness id；PI 作为默认兼容路径则会被隐藏。
|
||||
选定的 Harness id 会在一次嵌入式运行后，与会话 id 一起持久化保存。对于在 Harness 固定机制出现之前创建的旧会话，只要它们已有转录历史，就会被视为固定到 PI。在 PI 与原生插件 Harness 之间切换时，请使用新的/重置的会话。`/status` 会在 `Fast` 旁边显示诸如 `codex` 之类的非默认 Harness id；PI 不会显示，因为它是默认的兼容路径。
|
||||
|
||||
内置 Codex 插件将 `codex` 注册为它的 harness id。核心将其视为普通的插件 harness id；Codex 专用别名应属于插件或操作员配置，而不应放在共享运行时选择器中。
|
||||
内置 Codex 插件将 `codex` 注册为其 Harness id。核心将其视为普通插件 Harness id；Codex 专用别名应属于插件或操作员配置，而不是共享运行时选择器。
|
||||
|
||||
## 提供商与 harness 配对
|
||||
## 提供商与 Harness 配对
|
||||
|
||||
大多数 harness 也应同时注册一个提供商。提供商让模型引用、凭证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后，harness 在 `supports(...)` 中声明对该提供商的支持。
|
||||
大多数 Harness 也应注册一个提供商。提供商会让模型引用、认证状态、模型元数据和 `/model` 选择对 OpenClaw 的其余部分可见。然后 Harness 在 `supports(...)` 中认领该提供商。
|
||||
|
||||
内置 Codex 插件遵循这种模式：
|
||||
内置 Codex 插件采用这种模式：
|
||||
|
||||
- provider id：`codex`
|
||||
- 用户模型引用：`codex/gpt-5.4`、`codex/gpt-5.2`，或 Codex app server 返回的其他模型
|
||||
- 用户模型引用：`codex/gpt-5.5`、`codex/gpt-5.2`，或 Codex 应用服务器返回的其他模型
|
||||
- harness id：`codex`
|
||||
- 凭证：合成的提供商可用性，因为 Codex harness 拥有原生 Codex 登录 / 会话
|
||||
- app-server 请求：OpenClaw 向 Codex 发送裸模型 id，并让 harness 与原生 app-server 协议通信
|
||||
- 认证：合成的提供商可用性，因为 Codex Harness 拥有原生 Codex 登录/会话
|
||||
- 应用服务器请求：OpenClaw 将裸模型 id 发送给 Codex，并由 Harness 与原生 app-server 协议通信
|
||||
|
||||
Codex 插件是增量式的。普通的 `openai/gpt-*` 引用仍然是 OpenAI 提供商引用，并继续使用常规 OpenClaw 提供商路径。当你需要 Codex 管理的凭证、Codex 模型发现、原生线程和 Codex app-server 执行时，请选择 `codex/gpt-*`。`/model` 可以在 Codex app server 返回的 Codex 模型之间切换，而无需 OpenAI 提供商凭证。
|
||||
Codex 插件是增量式的。普通 `openai/gpt-*` 引用仍然是 OpenAI 提供商引用，并继续使用常规 OpenClaw 提供商路径。当你希望使用由 Codex 管理的认证、Codex 模型发现、原生线程和 Codex app-server 执行时，请选择 `codex/gpt-*`。`/model` 可以在 Codex app-server 返回的 Codex 模型之间切换，而无需 OpenAI 提供商凭证。
|
||||
|
||||
有关操作员设置、模型前缀示例和仅限 Codex 的配置，请参阅 [Codex Harness](/zh-CN/plugins/codex-harness)。
|
||||
有关操作员设置、模型前缀示例和仅适用于 Codex 的配置，请参见
|
||||
[Codex Harness](/zh-CN/plugins/codex-harness)。
|
||||
|
||||
OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会检查 app-server 初始化握手，并阻止较旧或未带版本信息的服务器，以确保 OpenClaw 只运行在其已测试过的协议接口面之上。
|
||||
OpenClaw 要求 Codex app-server 为 `0.118.0` 或更新版本。Codex 插件会检查 app-server 初始化握手，并阻止较旧或无版本服务器，以确保 OpenClaw 只在它已测试过的协议界面上运行。
|
||||
|
||||
### Codex app-server 工具结果中间件
|
||||
|
||||
当清单声明 `contracts.embeddedExtensionFactories: ["codex-app-server"]` 时，内置插件还可以通过 `api.registerCodexAppServerExtensionFactory(...)` 附加 Codex app-server 专用的 `tool_result` 中间件。这是受信任插件的接口，用于那些需要在原生 Codex harness 内部运行、并在工具输出被投影回 OpenClaw 转录之前执行的异步工具结果转换。
|
||||
当内置插件的清单声明 `contracts.embeddedExtensionFactories: ["codex-app-server"]` 时，它们还可以通过 `api.registerCodexAppServerExtensionFactory(...)` 附加 Codex app-server 专用的 `tool_result` 中间件。
|
||||
这是面向受信任插件的扩展点，用于那些需要在原生 Codex Harness 内运行、并在工具输出回投到 OpenClaw 转录之前进行异步工具结果转换的场景。
|
||||
|
||||
### 原生 Codex harness 模式
|
||||
### 原生 Codex Harness 模式
|
||||
|
||||
内置的 `codex` harness 是嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置 `codex` 插件；如果你的配置使用了限制性 allowlist，还要将 `codex` 加入 `plugins.allow`。它与 `openai-codex/*` 不同：
|
||||
内置 `codex` Harness 是嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置 `codex` 插件；如果你的配置使用受限 allowlist，还需要将 `codex` 包含在 `plugins.allow` 中。它不同于 `openai-codex/*`：
|
||||
|
||||
- `openai-codex/*` 通过常规 OpenClaw 提供商路径使用 ChatGPT / Codex OAuth。
|
||||
- `codex/*` 使用内置 Codex 提供商，并通过 Codex app-server 路由该轮次。
|
||||
- `openai-codex/*` 通过常规 OpenClaw 提供商路径使用 ChatGPT/Codex OAuth
|
||||
- `codex/*` 使用内置 Codex 提供商，并通过 Codex app-server 路由该轮次
|
||||
|
||||
当此模式运行时，Codex 负责原生线程 id、resume 行为、压缩和 app-server 执行。OpenClaw 仍然负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径可以接管运行时，请使用 `embeddedHarness.runtime: "codex"` 配合 `embeddedHarness.fallback: "none"`。该配置仅是一个选择保护：Codex app-server 失败本来就会直接失败，而不会通过 PI 重试。
|
||||
当该模式运行时，Codex 负责原生线程 id、resume 行为、压缩以及 app-server 执行。OpenClaw 仍然负责聊天渠道、可见转录镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径能够认领该运行时，请使用 `embeddedHarness.runtime: "codex"` 并设置
|
||||
`embeddedHarness.fallback: "none"`。该配置只是选择保护：Codex app-server 失败本来就会直接失败，而不会再通过 PI 重试。
|
||||
|
||||
## 禁用 PI 回退
|
||||
|
||||
默认情况下，OpenClaw 以 `agents.defaults.embeddedHarness` 设置为 `{ runtime: "auto", fallback: "pi" }` 来运行嵌入式智能体。在 `auto` 模式下，已注册的插件 harness 可以接管某个提供商 / 模型组合。如果没有任何匹配，OpenClaw 会回退到 PI。
|
||||
默认情况下，OpenClaw 使用 `agents.defaults.embeddedHarness`
|
||||
设为 `{ runtime: "auto", fallback: "pi" }` 来运行嵌入式智能体。在 `auto` 模式下，已注册插件 Harness 可以认领某个提供商/模型对。如果没有匹配项，OpenClaw 会回退到 PI。
|
||||
|
||||
当你需要在缺少插件 harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 harness 失败本来就会硬失败。这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。
|
||||
当你需要在缺少插件 Harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 Harness 失败本来就会硬失败。这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。
|
||||
|
||||
对于仅限 Codex 的嵌入式运行：
|
||||
对于仅 Codex 的嵌入式运行：
|
||||
|
||||
```json
|
||||
{
|
||||
"agents": {
|
||||
"defaults": {
|
||||
"model": "codex/gpt-5.4",
|
||||
"model": "codex/gpt-5.5",
|
||||
"embeddedHarness": {
|
||||
"runtime": "codex",
|
||||
"fallback": "none"
|
||||
@ -152,7 +157,7 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会
|
||||
}
|
||||
```
|
||||
|
||||
如果你希望任何已注册的插件 harness 都能接管匹配的模型，但又绝不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退：
|
||||
如果你希望任何已注册的插件 Harness 都能认领匹配模型，但又不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -167,7 +172,7 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会
|
||||
}
|
||||
```
|
||||
|
||||
按智能体覆盖使用相同的结构：
|
||||
每个智能体的覆盖使用相同结构：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -181,7 +186,7 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会
|
||||
"list": [
|
||||
{
|
||||
"id": "codex-only",
|
||||
"model": "codex/gpt-5.4",
|
||||
"model": "codex/gpt-5.5",
|
||||
"embeddedHarness": {
|
||||
"runtime": "codex",
|
||||
"fallback": "none"
|
||||
@ -192,7 +197,8 @@ OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会
|
||||
}
|
||||
```
|
||||
|
||||
`OPENCLAW_AGENT_RUNTIME` 仍然会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。
|
||||
`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。使用
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可通过环境变量禁用 PI 回退。
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -200,34 +206,36 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
在禁用回退后，如果请求的 harness 未注册、不支持已解析的提供商 / 模型，或者在产生轮次副作用之前失败，则会话会尽早失败。这对仅限 Codex 的部署以及必须证明 Codex app-server 路径确实在使用中的实时测试而言，是有意设计的行为。
|
||||
禁用回退后，如果请求的 Harness 未注册、不支持已解析的提供商/模型，或在产生轮次副作用之前就已失败，则会话会提前失败。对于仅 Codex 的部署，以及必须证明实际使用了 Codex app-server 路径的实时测试，这正是预期行为。
|
||||
|
||||
此设置只控制嵌入式智能体 harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。
|
||||
此设置仅控制嵌入式智能体 Harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商专用模型路由。
|
||||
|
||||
## 原生会话与转录镜像
|
||||
|
||||
harness 可以保留原生会话 id、线程 id 或守护进程侧的 resume token。请将这种绑定明确关联到 OpenClaw 会话，并继续将用户可见的助手 / 工具输出镜像到 OpenClaw 转录中。
|
||||
Harness 可以维护原生 session id、thread id 或守护进程侧的 resume token。
|
||||
请将这种绑定明确关联到 OpenClaw 会话，并持续将用户可见的助手/工具输出镜像到 OpenClaw 转录中。
|
||||
|
||||
OpenClaw 转录仍然是以下场景的兼容层：
|
||||
OpenClaw 转录仍是以下能力的兼容层：
|
||||
|
||||
- 渠道可见的会话历史
|
||||
- 转录搜索与索引
|
||||
- 在后续轮次切换回内置 PI harness
|
||||
- 转录搜索和索引
|
||||
- 在后续轮次切换回内置 PI Harness
|
||||
- 通用的 `/new`、`/reset` 和会话删除行为
|
||||
|
||||
如果你的 harness 存储了 sidecar 绑定，请实现 `reset(...)`，这样 OpenClaw 才能在所属 OpenClaw 会话被重置时清除它。
|
||||
如果你的 Harness 存储了 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 能在所属 OpenClaw 会话被重置时清除它。
|
||||
|
||||
## 工具与媒体结果
|
||||
## 工具和媒体结果
|
||||
|
||||
核心会构建 OpenClaw 工具列表，并将其传入已准备好的尝试中。当 harness 执行动态工具调用时，请通过 harness 结果结构返回工具结果，而不是自行发送渠道媒体。
|
||||
核心会构建 OpenClaw 工具列表，并将其传入已准备好的尝试中。
|
||||
当 Harness 执行动态工具调用时，请通过 Harness 结果结构返回工具结果，而不是自行发送渠道媒体。
|
||||
|
||||
这样可以让文本、图像、视频、音乐、TTS、审批以及消息工具输出，与由 PI 支持的运行走同一条投递路径。
|
||||
这样可以让文本、图像、视频、音乐、TTS、审批和消息工具输出，与由 PI 支持的运行使用同一条投递路径。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 公共导入路径是通用的，但某些 attempt / result 类型别名仍然保留 `Pi` 名称以保持兼容性。
|
||||
- 第三方 harness 安装仍处于实验阶段。在你确实需要原生会话运行时之前，优先使用提供商插件。
|
||||
- 支持跨轮次切换 harness。不要在一轮进行过程中、在原生工具、审批、助手文本或消息发送已经开始之后切换 harness。
|
||||
- 公共导入路径是通用的，但部分 attempt/result 类型别名仍然保留 `Pi` 命名以保持兼容性。
|
||||
- 第三方 Harness 安装仍属实验性功能。在你确实需要原生会话运行时时，才应优先考虑它；否则请优先使用提供商插件。
|
||||
- 支持跨轮次切换 Harness。不要在某一轮次中途、在原生工具、审批、助手文本或消息发送已经开始之后切换 Harness。
|
||||
|
||||
## 相关内容
|
||||
|
||||
|
||||
@ -1,26 +1,27 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想用一个 API 密钥访问多个 LLM
|
||||
- 你想在 OpenClaw 中通过 Kilo Gateway 运行模型
|
||||
summary: 使用 Kilo Gateway 的统一 API 在 OpenClaw 中访问多种模型
|
||||
- 你希望用一个 API 密钥访问多种 LLM
|
||||
- 你想在 OpenClaw 中通过 Kilo Gateway 网关运行模型
|
||||
summary: 使用 Kilo Gateway 网关的统一 API 在 OpenClaw 中访问多种模型
|
||||
title: Kilocode
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T10:43:06Z"
|
||||
generated_at: "2026-04-23T19:26:11Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 32946f2187f3933115341cbe81006718b10583abc4deea7440b5e56366025f4a
|
||||
source_hash: 4c0fa1c4949a76a353f76c47010510b75a6da6dc6d5b993f8e1f5e9b6fef53ce
|
||||
source_path: providers/kilocode.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Kilo Gateway
|
||||
|
||||
Kilo Gateway 提供一个**统一 API**，可将请求路由到单个端点和 API 密钥背后的多种模型。它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。
|
||||
Kilo Gateway 提供一个**统一 API**，可通过单一端点和 API 密钥将请求路由到多个模型。
|
||||
它兼容 OpenAI，因此大多数 OpenAI SDK 只需切换 base URL 即可使用。
|
||||
|
||||
| Property | Value |
|
||||
| -------- | ----- |
|
||||
| 属性 | 值 |
|
||||
| -------- | ---------------------------------- |
|
||||
| 提供商 | `kilocode` |
|
||||
| 认证 | `KILOCODE_API_KEY` |
|
||||
| 凭证 | `KILOCODE_API_KEY` |
|
||||
| API | 兼容 OpenAI |
|
||||
| Base URL | `https://api.kilo.ai/api/gateway/` |
|
||||
|
||||
@ -28,7 +29,7 @@ Kilo Gateway 提供一个**统一 API**，可将请求路由到单个端点和 A
|
||||
|
||||
<Steps>
|
||||
<Step title="创建账户">
|
||||
前往 [app.kilo.ai](https://app.kilo.ai)，登录或创建账户，然后导航到 API Keys 并生成一个新密钥。
|
||||
前往 [app.kilo.ai](https://app.kilo.ai)，登录或创建账户，然后进入 API Keys 页面生成一个新密钥。
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
@ -42,7 +43,7 @@ Kilo Gateway 提供一个**统一 API**，可将请求路由到单个端点和 A
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="验证模型是否可用">
|
||||
<Step title="验证模型可用">
|
||||
```bash
|
||||
openclaw models list --provider kilocode
|
||||
```
|
||||
@ -51,10 +52,10 @@ Kilo Gateway 提供一个**统一 API**，可将请求路由到单个端点和 A
|
||||
|
||||
## 默认模型
|
||||
|
||||
默认模型是 `kilocode/kilo/auto`，这是一个由 Kilo Gateway 管理、由提供商拥有的智能路由模型。
|
||||
默认模型是 `kilocode/kilo/auto`，这是一个由提供商维护的智能路由模型，由 Kilo Gateway 管理。
|
||||
|
||||
<Note>
|
||||
OpenClaw 将 `kilocode/kilo/auto` 视为稳定的默认引用，但不会发布该路由从任务到上游模型映射的源码依据。`kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 决定，而不是在 OpenClaw 中硬编码。
|
||||
OpenClaw 将 `kilocode/kilo/auto` 视为稳定的默认引用，但不会发布该路由从任务到上游模型的源支持映射。`kilocode/kilo/auto` 背后的确切上游路由由 Kilo Gateway 负责，而不是在 OpenClaw 中硬编码。
|
||||
</Note>
|
||||
|
||||
## 可用模型
|
||||
@ -62,18 +63,18 @@ OpenClaw 将 `kilocode/kilo/auto` 视为稳定的默认引用，但不会发布
|
||||
OpenClaw 会在启动时从 Kilo Gateway 动态发现可用模型。使用
|
||||
`/models kilocode` 可查看你的账户可用的完整模型列表。
|
||||
|
||||
Gateway 网关上任何可用模型都可以配合 `kilocode/` 前缀使用：
|
||||
Gateway 网关上任何可用模型都可以使用 `kilocode/` 前缀：
|
||||
|
||||
| 模型引用 | 说明 |
|
||||
| -------- | ---- |
|
||||
| `kilocode/kilo/auto` | 默认 —— 智能路由 |
|
||||
| -------------------------------------- | ---------------------------------- |
|
||||
| `kilocode/kilo/auto` | 默认 — 智能路由 |
|
||||
| `kilocode/anthropic/claude-sonnet-4` | 通过 Kilo 使用 Anthropic |
|
||||
| `kilocode/openai/gpt-5.4` | 通过 Kilo 使用 OpenAI |
|
||||
| `kilocode/openai/gpt-5.5` | 通过 Kilo 使用 OpenAI |
|
||||
| `kilocode/google/gemini-3-pro-preview` | 通过 Kilo 使用 Google |
|
||||
| ...以及更多 | 使用 `/models kilocode` 列出全部 |
|
||||
| ……以及更多 | 使用 `/models kilocode` 列出全部 |
|
||||
|
||||
<Tip>
|
||||
启动时，OpenClaw 会查询 `GET https://api.kilo.ai/api/gateway/models`，并将发现的模型合并到静态后备目录之前。内置后备目录始终包含 `kilocode/kilo/auto`（`Kilo Auto`），其参数为 `input: ["text", "image"]`、`reasoning: true`、`contextWindow: 1000000` 和 `maxTokens: 128000`。
|
||||
启动时，OpenClaw 会查询 `GET https://api.kilo.ai/api/gateway/models`，并将发现的模型合并到静态回退目录之前。内置回退目录始终包含 `kilocode/kilo/auto`（`Kilo Auto`），其配置为 `input: ["text", "image"]`、`reasoning: true`、`contextWindow: 1000000` 和 `maxTokens: 128000`。
|
||||
</Tip>
|
||||
|
||||
## 配置示例
|
||||
@ -91,26 +92,26 @@ Gateway 网关上任何可用模型都可以配合 `kilocode/` 前缀使用：
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="传输与兼容性">
|
||||
源码中将 Kilo Gateway 记录为兼容 OpenRouter，因此它会保留在代理风格的 OpenAI 兼容路径上，而不是使用原生 OpenAI 请求整形。
|
||||
源代码中将 Kilo Gateway 记录为兼容 OpenRouter，因此它会保留在代理式的 OpenAI 兼容路径上，而不是使用原生 OpenAI 请求整形。
|
||||
|
||||
- 由 Gemini 支持的 Kilo 引用会保留在 proxy-Gemini 路径上，因此 OpenClaw 会继续在该路径执行 Gemini thought-signature 清理，而不会启用原生 Gemini 重放校验或 bootstrap 重写。
|
||||
- 由 Gemini 支持的 Kilo 引用会保留在 proxy-Gemini 路径上，因此 OpenClaw 会在那里继续执行 Gemini thought-signature 清理，而不会启用原生 Gemini 重放校验或 bootstrap 重写。
|
||||
- Kilo Gateway 在底层使用带有你的 API 密钥的 Bearer token。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="流包装器与推理">
|
||||
Kilo 的共享流包装器会添加 provider app header，并为受支持的具体模型引用规范化代理推理负载。
|
||||
<Accordion title="流包装器与 reasoning">
|
||||
Kilo 的共享流包装器会添加提供商应用头，并为受支持的具体模型引用规范化代理 reasoning 负载。
|
||||
|
||||
<Warning>
|
||||
`kilocode/kilo/auto` 和其他不支持代理推理的提示会跳过推理注入。如果你需要推理支持，请使用具体的模型引用，例如 `kilocode/anthropic/claude-sonnet-4`。
|
||||
`kilocode/kilo/auto` 以及其他不支持代理 reasoning 的提示会跳过 reasoning 注入。如果你需要 reasoning 支持，请使用具体模型引用，例如 `kilocode/anthropic/claude-sonnet-4`。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="故障排除">
|
||||
- 如果模型发现过程在启动时失败，OpenClaw 会回退到包含 `kilocode/kilo/auto` 的内置静态目录。
|
||||
- 确认你的 API 密钥有效，并且你的 Kilo 账户已启用所需模型。
|
||||
- 当 Gateway 网关以守护进程方式运行时，确保 `KILOCODE_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。
|
||||
- 如果启动时模型发现失败，OpenClaw 会回退到包含 `kilocode/kilo/auto` 的内置静态目录。
|
||||
- 请确认你的 API 密钥有效，并且你的 Kilo 账户已启用所需模型。
|
||||
- 当 Gateway 网关以守护进程方式运行时，请确保 `KILOCODE_API_KEY` 对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供）。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -118,12 +119,12 @@ Gateway 网关上任何可用模型都可以配合 `kilocode/` 前缀使用：
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
选择提供商、模型引用和故障转移行为。
|
||||
选择提供商、模型引用和回退行为。
|
||||
</Card>
|
||||
<Card title="配置参考" href="/zh-CN/gateway/configuration" icon="gear">
|
||||
完整的 OpenClaw 配置参考。
|
||||
OpenClaw 完整配置参考。
|
||||
</Card>
|
||||
<Card title="Kilo Gateway" href="https://app.kilo.ai" icon="arrow-up-right-from-square">
|
||||
Kilo Gateway 仪表板、API 密钥和账户管理。
|
||||
Kilo Gateway 控制台、API 密钥和账户管理。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,46 +1,46 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 OpenClaw 中使用 OpenAI 模型
|
||||
- 你想使用 Codex 订阅认证，而不是 API 密钥
|
||||
- 你想使用 Codex 订阅身份验证，而不是 API 密钥
|
||||
- 你需要更严格的 GPT-5 智能体执行行为
|
||||
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T18:44:56Z"
|
||||
generated_at: "2026-04-23T19:26:09Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 69aa2a3badd2d3667e2164c4c492cb8e9caa8b911c750f9210b211b1a6c3ba66
|
||||
source_hash: 75c0492abf21cc2f0dfb83f32111b2b7e41cb85dd09ede6c1c45b18a135e46e1
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# OpenAI
|
||||
|
||||
OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式：
|
||||
OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持两种身份验证方式：
|
||||
|
||||
- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型）
|
||||
- **Codex 订阅** — 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型）
|
||||
- **API 密钥** —— 通过 OpenAI Platform 直接访问，按使用量计费（`openai/*` 模型）
|
||||
- **Codex 订阅** —— 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型）
|
||||
|
||||
OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。
|
||||
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。
|
||||
|
||||
## OpenClaw 功能覆盖范围
|
||||
|
||||
| OpenAI 能力 | OpenClaw 对应功能 | 状态 |
|
||||
| OpenAI 能力 | OpenClaw 接口 | 状态 |
|
||||
| ------------------------- | ----------------------------------------- | ------------------------------------------------------ |
|
||||
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
|
||||
| Codex 订阅模型 | `openai-codex/<model>` 模型提供商 | 是 |
|
||||
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时可用 |
|
||||
| 图像 | `image_generate` | 是 |
|
||||
| 视频 | `video_generate` | 是 |
|
||||
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
|
||||
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
|
||||
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
|
||||
| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 |
|
||||
| Embeddings | memory embedding provider | 是 |
|
||||
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
|
||||
| Codex 订阅模型 | `openai-codex/<model>` 模型提供商 | 是 |
|
||||
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，当启用 Web 搜索且未固定提供商时 |
|
||||
| 图像 | `image_generate` | 是 |
|
||||
| 视频 | `video_generate` | 是 |
|
||||
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
|
||||
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
|
||||
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
|
||||
| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 |
|
||||
| Embeddings | memory embedding provider | 是 |
|
||||
|
||||
## 入门指南
|
||||
|
||||
选择你偏好的认证方式，并按照设置步骤进行操作。
|
||||
选择你偏好的身份验证方式，并按步骤完成设置。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API 密钥（OpenAI Platform）">
|
||||
@ -48,32 +48,32 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="获取你的 API 密钥">
|
||||
在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
|
||||
在 [OpenAI Platform 仪表板](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
```
|
||||
|
||||
或者直接传入密钥：
|
||||
或直接传入密钥：
|
||||
|
||||
```bash
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
```
|
||||
</Step>
|
||||
<Step title="验证模型是否可用">
|
||||
<Step title="验证模型可用">
|
||||
```bash
|
||||
openclaw models list --provider openai
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 路由概览
|
||||
### 路由摘要
|
||||
|
||||
| Model ref | Route | Auth |
|
||||
| Model ref | 路由 | 身份验证 |
|
||||
|-----------|-------|------|
|
||||
| `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
ChatGPT/Codex 登录通过 `openai-codex/*` 路由，而不是 `openai/*`。
|
||||
@ -84,18 +84,18 @@ x-i18n:
|
||||
```json5
|
||||
{
|
||||
env: { OPENAI_API_KEY: "sk-..." },
|
||||
agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
|
||||
agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
|
||||
}
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **不会** 在直接 API 路径上公开 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
|
||||
OpenClaw **不会**在直接 API 路径中暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型。Spark 仅限 Codex。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Codex 订阅">
|
||||
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex 云端需要使用 ChatGPT 登录。
|
||||
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。
|
||||
|
||||
<Steps>
|
||||
<Step title="运行 Codex OAuth">
|
||||
@ -109,7 +109,7 @@ x-i18n:
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：
|
||||
对于无头环境或不适合回调的设置，可添加 `--device-code`，使用 ChatGPT 设备码流程登录，而不是 localhost 浏览器回调：
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
@ -117,56 +117,56 @@ x-i18n:
|
||||
</Step>
|
||||
<Step title="设置默认模型">
|
||||
```bash
|
||||
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.4
|
||||
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
|
||||
```
|
||||
</Step>
|
||||
<Step title="验证模型是否可用">
|
||||
<Step title="验证模型可用">
|
||||
```bash
|
||||
openclaw models list --provider openai-codex
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 路由概览
|
||||
### 路由摘要
|
||||
|
||||
| Model ref | Route | Auth |
|
||||
| Model ref | 路由 | 身份验证 |
|
||||
|-----------|-------|------|
|
||||
| `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于 entitlement） |
|
||||
| `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于授权资格） |
|
||||
|
||||
<Note>
|
||||
这一路由与 `openai/gpt-5.4` 是有意分开的。直接 Platform 访问请配合 API 密钥使用 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。
|
||||
该路由与 `openai/gpt-5.5` 是刻意分开的。直接 Platform 访问请使用带 API 密钥的 `openai/*`，Codex 订阅访问请使用 `openai-codex/*`。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
|
||||
agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } },
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在其自己的智能体认证存储中管理生成的凭证。
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录 —— OpenClaw 会在自己的智能体身份验证存储中管理生成的凭证。
|
||||
</Note>
|
||||
|
||||
### 上下文窗口上限
|
||||
|
||||
OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
|
||||
|
||||
对于 `openai-codex/gpt-5.4`：
|
||||
对于 `openai-codex/gpt-5.5`：
|
||||
|
||||
- 原生 `contextWindow`：`1050000`
|
||||
- 原生 `contextWindow`：`1000000`
|
||||
- 默认运行时 `contextTokens` 上限：`272000`
|
||||
|
||||
在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它：
|
||||
在实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它：
|
||||
|
||||
```json5
|
||||
{
|
||||
models: {
|
||||
providers: {
|
||||
"openai-codex": {
|
||||
models: [{ id: "gpt-5.4", contextTokens: 160000 }],
|
||||
models: [{ id: "gpt-5.5", contextTokens: 160000 }],
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -182,15 +182,15 @@ x-i18n:
|
||||
|
||||
## 图像生成
|
||||
|
||||
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。
|
||||
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成能力。
|
||||
|
||||
| 能力 | 值 |
|
||||
| Capability | Value |
|
||||
| ------------------------- | ---------------------------------- |
|
||||
| 默认模型 | `openai/gpt-image-2` |
|
||||
| 每次请求的最大图像数 | 4 |
|
||||
| 默认模型 | `openai/gpt-image-2` |
|
||||
| 每次请求的最大图像数 | 4 |
|
||||
| 编辑模式 | 已启用（最多 5 张参考图像） |
|
||||
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
|
||||
| 宽高比 / 分辨率 | 不会传递给 OpenAI Images API |
|
||||
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
|
||||
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -206,7 +206,7 @@ x-i18n:
|
||||
有关共享工具参数、提供商选择和故障切换行为，请参见 [图像生成](/zh-CN/tools/image-generation)。
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` 是 OpenAI 文生图生成和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
|
||||
`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖项使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
|
||||
|
||||
生成：
|
||||
|
||||
@ -222,11 +222,11 @@ x-i18n:
|
||||
|
||||
## 视频生成
|
||||
|
||||
内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。
|
||||
内置的 `openai` 插件通过 `video_generate` 工具注册视频生成能力。
|
||||
|
||||
| 能力 | 值 |
|
||||
| Capability | Value |
|
||||
| ---------------- | --------------------------------------------------------------------------------- |
|
||||
| 默认模型 | `openai/sora-2` |
|
||||
| 默认模型 | `openai/sora-2` |
|
||||
| 模式 | 文生视频、图生视频、单视频编辑 |
|
||||
| 参考输入 | 1 张图像或 1 个视频 |
|
||||
| 尺寸覆盖 | 支持 |
|
||||
@ -246,19 +246,19 @@ x-i18n:
|
||||
有关共享工具参数、提供商选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
|
||||
</Note>
|
||||
|
||||
## GPT-5 提示词扩展
|
||||
## GPT-5 提示词贡献
|
||||
|
||||
OpenClaw 为跨提供商的 GPT-5 系列运行添加了共享的 GPT-5 提示词扩展。它按模型 id 应用，因此 `openai/gpt-5.4`、`openai-codex/gpt-5.4`、`openrouter/openai/gpt-5.4`、`opencode/gpt-5.4` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。
|
||||
OpenClaw 会为跨提供商的 GPT-5 系列运行添加一个共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai/gpt-5.5`、`openai-codex/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的叠加层。较旧的 GPT-4.x 模型不会应用。
|
||||
|
||||
内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖层，因此 `codex/gpt-5.x` 会话即使其余 harness 提示词由 Codex 控制，也会保持相同的后续执行和主动心跳指导。
|
||||
内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 heartbeat 叠加层，因此即使 Codex 负责其余 harness 提示词，`codex/gpt-5.x` 会话仍会保持相同的后续跟进和主动 heartbeat 指引。
|
||||
|
||||
GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性、执行安全性、工具纪律、输出形态、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指导始终对匹配的模型启用。友好交互风格层是单独的，并且可配置。
|
||||
GPT-5 贡献会添加一个带标签的行为契约，用于规范人格持续性、执行安全、工具纪律、输出形状、完成检查和验证。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指引对匹配模型始终启用。友好交互风格层是独立的，并且可配置。
|
||||
|
||||
| 值 | 效果 |
|
||||
| Value | Effect |
|
||||
| ---------------------- | ------------------------------------------- |
|
||||
| `"friendly"`（默认） | 启用友好交互风格层 |
|
||||
| `"on"` | `"friendly"` 的别名 |
|
||||
| `"off"` | 仅禁用友好风格层 |
|
||||
| `"on"` | `"friendly"` 的别名 |
|
||||
| `"off"` | 仅禁用友好风格层 |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="配置">
|
||||
@ -282,30 +282,30 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
|
||||
运行时对值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退项读取，但仅在未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时生效。
|
||||
旧版 `plugins.entries.openai.config.personality` 在未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，仍会作为兼容性回退项读取。
|
||||
</Note>
|
||||
|
||||
## 语音和语音识别
|
||||
## 语音与语音处理
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="语音合成（TTS）">
|
||||
内置的 `openai` 插件为 `messages.tts` 功能面注册了语音合成功能。
|
||||
内置的 `openai` 插件会为 `messages.tts` 接口注册语音合成功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
| Setting | Config path | Default |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
|
||||
| 音色 | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| 语速 | `messages.tts.providers.openai.speed` | （未设置） |
|
||||
| 语音 | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
|
||||
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
|
||||
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` |
|
||||
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音笔记为 `opus`，文件为 `mp3` |
|
||||
| API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
| 基础 URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
|
||||
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
|
||||
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -320,22 +320,23 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性
|
||||
```
|
||||
|
||||
<Note>
|
||||
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 Base URL，而不会影响聊天 API 端点。
|
||||
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 基础 URL，而不会影响聊天 API 端点。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="语音转文本">
|
||||
内置的 `openai` 插件通过 OpenClaw 的媒体理解转录功能面注册批量语音转文本功能。
|
||||
内置的 `openai` 插件通过
|
||||
OpenClaw 的媒体理解转录接口注册批量语音转文本功能。
|
||||
|
||||
- 默认模型：`gpt-4o-transcribe`
|
||||
- 端点：OpenAI REST `/v1/audio/transcriptions`
|
||||
- 输入路径：multipart 音频文件上传
|
||||
- 在 OpenClaw 中，凡是入站音频转录使用
|
||||
`tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道
|
||||
- 在 OpenClaw 中，只要入站音频转录使用
|
||||
`tools.media.audio`，就会受支持，包括 Discord 语音频道片段和渠道
|
||||
音频附件
|
||||
|
||||
如需强制将 OpenAI 用于入站音频转录：
|
||||
如需强制对入站音频转录使用 OpenAI：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -355,14 +356,14 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性
|
||||
}
|
||||
```
|
||||
|
||||
当共享音频媒体配置或每次调用的转录请求提供语言和提示词线索时，这些信息会转发给 OpenAI。
|
||||
当共享音频媒体配置或按次调用的转录请求提供了语言和提示词提示时，这些内容会转发给 OpenAI。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时转录">
|
||||
内置的 `openai` 插件为 Voice Call 插件注册实时转录功能。
|
||||
内置的 `openai` 插件会为 Voice Call 插件注册实时转录功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
| Setting | Config path | Default |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||||
| 语言 | `...openai.language` | （未设置） |
|
||||
@ -372,19 +373,19 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性
|
||||
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。此流式提供商用于 Voice Call 的实时转录路径；Discord 语音目前仍记录短片段，并改用批量 `tools.media.audio` 转录路径。
|
||||
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。该流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时语音">
|
||||
内置的 `openai` 插件为 Voice Call 插件注册实时语音功能。
|
||||
内置的 `openai` 插件会为 Voice Call 插件注册实时语音功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
| Setting | Config path | Default |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
|
||||
| 音色 | `...openai.voice` | `alloy` |
|
||||
| 温度 | `...openai.temperature` | `0.8` |
|
||||
| 语音 | `...openai.voice` | `alloy` |
|
||||
| Temperature | `...openai.temperature` | `0.8` |
|
||||
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
|
||||
| 静音时长 | `...openai.silenceDurationMs` | `500` |
|
||||
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
@ -398,21 +399,24 @@ GPT-5 扩展添加了带标签的行为契约，用于规范 persona 持续性
|
||||
|
||||
## Azure OpenAI 端点
|
||||
|
||||
内置的 `openai` 提供商可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 中的 Azure 主机名，并自动切换到 Azure 的请求格式。
|
||||
内置的 `openai` 提供商可以通过覆盖基础 URL，将图像
|
||||
生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw
|
||||
会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到
|
||||
Azure 的请求格式。
|
||||
|
||||
<Note>
|
||||
实时语音使用独立的配置路径
|
||||
实时语音使用单独的配置路径
|
||||
（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），
|
||||
不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参见
|
||||
[语音和语音识别](#voice-and-speech) 下的 **实时语音**
|
||||
不会受 `models.providers.openai.baseUrl` 影响。其 Azure
|
||||
设置请参见 [语音与语音处理](#voice-and-speech) 下的**实时语音**
|
||||
折叠面板。
|
||||
</Note>
|
||||
|
||||
在以下情况下使用 Azure OpenAI：
|
||||
以下情况下可使用 Azure OpenAI：
|
||||
|
||||
- 你已经有 Azure OpenAI 订阅、配额或企业协议
|
||||
- 你已经拥有 Azure OpenAI 订阅、配额或企业协议
|
||||
- 你需要 Azure 提供的区域数据驻留或合规控制
|
||||
- 你希望将流量保留在现有 Azure 租户内
|
||||
- 你希望将流量保留在现有 Azure 租户内部
|
||||
|
||||
### 配置
|
||||
|
||||
@ -433,26 +437,27 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路由：
|
||||
OpenClaw 会识别以下 Azure 主机后缀，并将其用于 Azure 图像生成
|
||||
路由：
|
||||
|
||||
- `*.openai.azure.com`
|
||||
- `*.services.ai.azure.com`
|
||||
- `*.cognitiveservices.azure.com`
|
||||
|
||||
对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会：
|
||||
对于识别出的 Azure 主机上的图像生成请求，OpenClaw 会：
|
||||
|
||||
- 发送 `api-key` 请求头，而不是 `Authorization: Bearer`
|
||||
- 使用以 deployment 为范围的路径（`/openai/deployments/{deployment}/...`）
|
||||
- 为每个请求追加 `?api-version=...`
|
||||
- 发送 `api-key` 标头，而不是 `Authorization: Bearer`
|
||||
- 使用以部署为作用域的路径（`/openai/deployments/{deployment}/...`）
|
||||
- 在每个请求后追加 `?api-version=...`
|
||||
|
||||
其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准的
|
||||
其他基础 URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准
|
||||
OpenAI 图像请求格式。
|
||||
|
||||
<Note>
|
||||
`openai` 提供商图像生成路径的 Azure 路由要求
|
||||
OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义
|
||||
`openai.baseUrl` 都当作公共 OpenAI 端点处理，因此在 Azure
|
||||
图像 deployment 上会失败。
|
||||
`openai.baseUrl` 视为公共 OpenAI 端点，因此会在 Azure
|
||||
图像部署上失败。
|
||||
</Note>
|
||||
|
||||
### API 版本
|
||||
@ -465,70 +470,72 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
|
||||
当该变量未设置时，默认值为 `2024-12-01-preview`。
|
||||
|
||||
### 模型名称就是 deployment 名称
|
||||
### 模型名称就是部署名称
|
||||
|
||||
Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是公共 OpenAI 模型 id。
|
||||
Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，
|
||||
OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，
|
||||
而不是公开的 OpenAI 模型 id。
|
||||
|
||||
如果你创建了一个名为 `gpt-image-2-prod` 的 deployment，用于提供 `gpt-image-2`：
|
||||
如果你创建了一个名为 `gpt-image-2-prod` 且提供 `gpt-image-2` 的部署：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
|
||||
同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
|
||||
|
||||
### 区域可用性
|
||||
|
||||
Azure 图像生成目前仅在部分区域可用
|
||||
Azure 图像生成当前仅在部分区域可用
|
||||
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
|
||||
`uaenorth`）。创建 deployment 之前，请先查看 Microsoft 当前的区域列表，并确认你的区域提供该特定模型。
|
||||
`uaenorth`）。创建
|
||||
部署前，请先检查 Microsoft 当前的区域列表，并确认特定模型在你的区域中可用。
|
||||
|
||||
### 参数差异
|
||||
|
||||
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。
|
||||
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如
|
||||
Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。
|
||||
Azure 可能会拒绝公共 OpenAI 允许的选项（例如
|
||||
`gpt-image-2` 上某些 `background` 值），或者仅在特定模型
|
||||
版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是
|
||||
OpenClaw。如果 Azure 请求因验证错误失败，请在
|
||||
Azure 门户中检查你的特定 deployment 和 API 版本所支持的参数集。
|
||||
版本中提供这些选项。这些差异来自 Azure 和底层模型，而不是
|
||||
OpenClaw。如果 Azure 请求因验证错误而失败，请检查
|
||||
Azure 门户中你的具体部署和 API 版本所支持的参数集。
|
||||
|
||||
<Note>
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会收到
|
||||
OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configuration) 下
|
||||
**原生与兼容 OpenAI 路由**
|
||||
折叠面板。
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收
|
||||
OpenClaw 的隐藏归因标头——参见 [高级配置](#advanced-configuration) 下
|
||||
**原生 vs OpenAI 兼容路由** 折叠面板。
|
||||
|
||||
若要在 Azure 上处理聊天或 Responses 流量（除图像生成之外），请使用
|
||||
对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用
|
||||
新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl`
|
||||
并不会启用 Azure 的 API / 认证格式。另有一个单独的
|
||||
`azure-openai-responses/*` 提供商；请参见
|
||||
下方的“服务端压缩”折叠面板。
|
||||
不会自动采用 Azure 的 API/身份验证格式。另有一个独立的
|
||||
`azure-openai-responses/*` 提供商；请参见下面的
|
||||
服务端压缩折叠面板。
|
||||
</Note>
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="传输（WebSocket 与 SSE）">
|
||||
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都采用 WebSocket 优先，并在失败时回退到 SSE（`"auto"`）。
|
||||
<Accordion title="传输协议（WebSocket vs SSE）">
|
||||
OpenClaw 对 `openai/*` 和 `openai-codex/*` 均默认使用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。
|
||||
|
||||
在 `"auto"` 模式下，OpenClaw 会：
|
||||
- 在回退到 SSE 之前，对一次早期 WebSocket 失败进行一次重试
|
||||
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
|
||||
- 为重试和重连附加稳定的会话和轮次身份请求头
|
||||
- 发生失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE
|
||||
- 为重试和重连附加稳定的会话和轮次身份标头
|
||||
- 在不同传输变体之间标准化用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
|
||||
| 值 | 行为 |
|
||||
| Value | Behavior |
|
||||
|-------|----------|
|
||||
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
|
||||
| `"sse"` | 仅强制使用 SSE |
|
||||
| `"websocket"` | 仅强制使用 WebSocket |
|
||||
| `"auto"`（默认） | WebSocket 优先，失败时回退到 SSE |
|
||||
| `"sse"` | 强制仅使用 SSE |
|
||||
| `"websocket"` | 强制仅使用 WebSocket |
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"openai-codex/gpt-5.4": {
|
||||
"openai-codex/gpt-5.5": {
|
||||
params: { transport: "auto" },
|
||||
},
|
||||
},
|
||||
@ -544,7 +551,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="WebSocket 预热">
|
||||
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。
|
||||
OpenClaw 默认会为 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。
|
||||
|
||||
```json5
|
||||
// 禁用预热
|
||||
@ -552,7 +559,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"openai/gpt-5.4": {
|
||||
"openai/gpt-5.5": {
|
||||
params: { openaiWsWarmup: false },
|
||||
},
|
||||
},
|
||||
@ -564,20 +571,20 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="快速模式">
|
||||
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供共享的快速模式开关：
|
||||
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供统一的快速模式开关：
|
||||
|
||||
- **聊天 / UI：** `/fast status|on|off`
|
||||
- **聊天/UI：** `/fast status|on|off`
|
||||
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。
|
||||
启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"openai/gpt-5.4": { params: { fastMode: true } },
|
||||
"openai-codex/gpt-5.4": { params: { fastMode: true } },
|
||||
"openai/gpt-5.5": { params: { fastMode: true } },
|
||||
"openai-codex/gpt-5.5": { params: { fastMode: true } },
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -585,21 +592,21 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
```
|
||||
|
||||
<Note>
|
||||
会话覆盖优先于配置。清除 Sessions UI 中的会话覆盖后，会话将返回配置的默认值。
|
||||
会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖项后，会话将返回到配置的默认值。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="优先处理（service_tier）">
|
||||
OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型设置：
|
||||
OpenAI 的 API 通过 `service_tier` 暴露优先处理能力。你可以在 OpenClaw 中按模型设置它：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"openai/gpt-5.4": { params: { serviceTier: "priority" } },
|
||||
"openai-codex/gpt-5.4": { params: { serviceTier: "priority" } },
|
||||
"openai/gpt-5.5": { params: { serviceTier: "priority" } },
|
||||
"openai-codex/gpt-5.5": { params: { serviceTier: "priority" } },
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -609,7 +616,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
支持的值：`auto`、`default`、`flex`、`priority`。
|
||||
|
||||
<Warning>
|
||||
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
|
||||
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由其中任一提供商，OpenClaw 会保持 `service_tier` 不变。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
@ -617,20 +624,20 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
<Accordion title="服务端压缩（Responses API）">
|
||||
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩：
|
||||
|
||||
- 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
|
||||
- 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
|
||||
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- 默认 `compact_threshold`：`contextWindow` 的 70%（如果不可用则为 `80000`）
|
||||
|
||||
<Tabs>
|
||||
<Tab title="显式启用">
|
||||
对于兼容端点（如 Azure OpenAI Responses）很有用：
|
||||
对 Azure OpenAI Responses 这类兼容端点很有用：
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"azure-openai-responses/gpt-5.4": {
|
||||
"azure-openai-responses/gpt-5.5": {
|
||||
params: { responsesServerCompaction: true },
|
||||
},
|
||||
},
|
||||
@ -645,7 +652,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"openai/gpt-5.4": {
|
||||
"openai/gpt-5.5": {
|
||||
params: {
|
||||
responsesServerCompaction: true,
|
||||
responsesCompactThreshold: 120000,
|
||||
@ -663,7 +670,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
agents: {
|
||||
defaults: {
|
||||
models: {
|
||||
"openai/gpt-5.4": {
|
||||
"openai/gpt-5.5": {
|
||||
params: { responsesServerCompaction: false },
|
||||
},
|
||||
},
|
||||
@ -675,13 +682,13 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。
|
||||
`responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="严格智能体 GPT 模式">
|
||||
对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
|
||||
<Accordion title="严格智能体式 GPT 模式">
|
||||
对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的内嵌执行契约：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -693,33 +700,33 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
}
|
||||
```
|
||||
|
||||
启用 `strict-agentic` 后，OpenClaw 会：
|
||||
- 当工具操作可用时，不再将仅有计划的轮次视为成功进展
|
||||
- 使用“立即行动”的引导重试该轮
|
||||
- 在处理较大任务时自动启用 `update_plan`
|
||||
- 如果模型持续只做规划而不执行操作，则显示明确的阻塞状态
|
||||
使用 `strict-agentic` 时，OpenClaw 会：
|
||||
- 当有工具操作可用时，不再将仅规划的轮次视为成功进展
|
||||
- 使用“立即行动”的引导重试该轮次
|
||||
- 对于重要工作，自动启用 `update_plan`
|
||||
- 如果模型持续规划而不执行，则显式显示阻塞状态
|
||||
|
||||
<Note>
|
||||
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列仍保持默认行为。
|
||||
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列会保持默认行为。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="原生与兼容 OpenAI 路由">
|
||||
OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用兼容 OpenAI 的 `/v1` 代理不同：
|
||||
<Accordion title="原生 vs OpenAI 兼容路由">
|
||||
OpenClaw 会以不同方式处理直接 OpenAI、Codex 和 Azure OpenAI 端点，与通用兼容 OpenAI 的 `/v1` 代理不同：
|
||||
|
||||
**原生路由**（`openai/*`、`openai-codex/*`、Azure OpenAI）：
|
||||
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
|
||||
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的 reasoning
|
||||
- 对于会拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用推理设置
|
||||
- 默认将工具 schema 设为严格模式
|
||||
- 仅在经过验证的原生主机上附加隐藏归因请求头
|
||||
- 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
|
||||
- 仅在已验证的原生主机上附加隐藏归因标头
|
||||
- 保留仅适用于 OpenAI 的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
|
||||
|
||||
**代理 / 兼容路由：**
|
||||
- 使用更宽松的兼容行为
|
||||
- 不强制严格工具 schema，也不附加原生专用请求头
|
||||
**代理/兼容路由：**
|
||||
- 使用更宽松的兼容性行为
|
||||
- 不强制严格工具 schema，也不附加仅原生支持的标头
|
||||
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。
|
||||
Azure OpenAI 使用原生传输和兼容性行为，但不会接收隐藏归因标头。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -736,7 +743,7 @@ OpenClaw 的隐藏归因请求头——详见 [高级配置](#advanced-configura
|
||||
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
|
||||
共享视频工具参数和提供商选择。
|
||||
</Card>
|
||||
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
|
||||
认证细节和凭证复用规则。
|
||||
<Card title="OAuth 和身份验证" href="/zh-CN/gateway/authentication" icon="key">
|
||||
身份验证细节和凭证复用规则。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想要通过 OpenCode 托管的模型访问
|
||||
- 你想在 Zen 目录和 Go 目录之间进行选择
|
||||
summary: 使用 OpenCode Zen 和 Go 目录配合 OpenClaw
|
||||
- 你想使用 OpenCode 托管的模型访问方式
|
||||
- 你想在 Zen 和 Go 目录之间进行选择
|
||||
summary: 将 OpenCode Zen 和 Go 目录与 OpenClaw 一起使用
|
||||
title: OpenCode
|
||||
x-i18n:
|
||||
generated_at: "2026-04-12T10:36:44Z"
|
||||
generated_at: "2026-04-23T19:26:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: a68444d8c403c3caba4a18ea47f078c7a4c163f874560e1fad0e818afb6e0e60
|
||||
source_hash: d958a8b32277cf4e40f086e6f8281826c70a7583823216403bca09108778f3b3
|
||||
source_path: providers/opencode.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,13 +17,13 @@ x-i18n:
|
||||
|
||||
OpenCode 在 OpenClaw 中提供两个托管目录：
|
||||
|
||||
| 目录 | 前缀 | 运行时提供商 |
|
||||
| 目录 | 前缀 | 运行时提供商 |
|
||||
| ------- | ----------------- | ---------------- |
|
||||
| **Zen** | `opencode/...` | `opencode` |
|
||||
| **Go** | `opencode-go/...` | `opencode-go` |
|
||||
| **Zen** | `opencode/...` | `opencode` |
|
||||
| **Go** | `opencode-go/...` | `opencode-go` |
|
||||
|
||||
两个目录都使用同一个 OpenCode API 密钥。OpenClaw 会将运行时提供商 id 分开，
|
||||
以确保上游按模型路由保持正确，但新手引导和文档会将它们视为同一个 OpenCode 设置。
|
||||
这两个目录使用同一个 OpenCode API key。OpenClaw 会将运行时 provider ID 拆分开，
|
||||
以确保上游的按模型路由保持正确，但新手引导和文档会将它们视为同一个 OpenCode 设置。
|
||||
|
||||
## 入门指南
|
||||
|
||||
@ -37,7 +37,7 @@ OpenCode 在 OpenClaw 中提供两个托管目录：
|
||||
openclaw onboard --auth-choice opencode-zen
|
||||
```
|
||||
|
||||
或者直接传入密钥：
|
||||
或直接传入 key：
|
||||
|
||||
```bash
|
||||
openclaw onboard --opencode-zen-api-key "$OPENCODE_API_KEY"
|
||||
@ -58,7 +58,7 @@ OpenCode 在 OpenClaw 中提供两个托管目录：
|
||||
</Tab>
|
||||
|
||||
<Tab title="Go 目录">
|
||||
**最适合：** 由 OpenCode 托管的 Kimi、GLM 和 MiniMax 阵容。
|
||||
**最适合：** OpenCode 托管的 Kimi、GLM 和 MiniMax 产品线。
|
||||
|
||||
<Steps>
|
||||
<Step title="运行新手引导">
|
||||
@ -66,7 +66,7 @@ OpenCode 在 OpenClaw 中提供两个托管目录：
|
||||
openclaw onboard --auth-choice opencode-go
|
||||
```
|
||||
|
||||
或者直接传入密钥：
|
||||
或直接传入 key：
|
||||
|
||||
```bash
|
||||
openclaw onboard --opencode-go-api-key "$OPENCODE_API_KEY"
|
||||
@ -100,39 +100,39 @@ OpenCode 在 OpenClaw 中提供两个托管目录：
|
||||
|
||||
### Zen
|
||||
|
||||
| 属性 | 值 |
|
||||
| 属性 | 值 |
|
||||
| ---------------- | ----------------------------------------------------------------------- |
|
||||
| 运行时提供商 | `opencode` |
|
||||
| 示例模型 | `opencode/claude-opus-4-6`, `opencode/gpt-5.4`, `opencode/gemini-3-pro` |
|
||||
| 运行时提供商 | `opencode` |
|
||||
| 示例模型 | `opencode/claude-opus-4-6`、`opencode/gpt-5.5`、`opencode/gemini-3-pro` |
|
||||
|
||||
### Go
|
||||
|
||||
| 属性 | 值 |
|
||||
| 属性 | 值 |
|
||||
| ---------------- | ------------------------------------------------------------------------ |
|
||||
| 运行时提供商 | `opencode-go` |
|
||||
| 示例模型 | `opencode-go/kimi-k2.5`, `opencode-go/glm-5`, `opencode-go/minimax-m2.5` |
|
||||
| 运行时提供商 | `opencode-go` |
|
||||
| 示例模型 | `opencode-go/kimi-k2.5`、`opencode-go/glm-5`、`opencode-go/minimax-m2.5` |
|
||||
|
||||
## 高级说明
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="API 密钥别名">
|
||||
<Accordion title="API key 别名">
|
||||
也支持将 `OPENCODE_ZEN_API_KEY` 作为 `OPENCODE_API_KEY` 的别名。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="共享凭证">
|
||||
在设置期间输入一个 OpenCode 密钥后，会为两个运行时提供商都存储凭证。
|
||||
你不需要分别为每个目录单独进行新手引导。
|
||||
在设置期间输入一个 OpenCode key，会为两个运行时 provider 都存储凭证。
|
||||
你不需要分别为每个目录执行新手引导。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="计费和控制台">
|
||||
你需要登录 OpenCode，添加计费信息，并复制你的 API 密钥。计费
|
||||
和目录可用性由 OpenCode 控制台统一管理。
|
||||
<Accordion title="计费与控制台">
|
||||
你需要登录 OpenCode、添加计费信息并复制你的 API key。计费
|
||||
和目录可用性都在 OpenCode 控制台中管理。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gemini 重放行为">
|
||||
由 Gemini 支持的 OpenCode 引用会保留在 proxy-Gemini 路径上，因此 OpenClaw 会
|
||||
在该路径上保留 Gemini thought-signature 清理，而不会启用原生 Gemini
|
||||
重放验证或 bootstrap 重写。
|
||||
在该路径上继续保留 Gemini thought-signature 清理，而不会启用原生 Gemini
|
||||
重放校验或 bootstrap 重写。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="非 Gemini 重放行为">
|
||||
@ -141,17 +141,17 @@ OpenCode 在 OpenClaw 中提供两个托管目录：
|
||||
</AccordionGroup>
|
||||
|
||||
<Tip>
|
||||
在设置期间输入一个 OpenCode 密钥后，会为 Zen 和 Go
|
||||
运行时提供商都存储凭证，因此你只需要进行一次新手引导。
|
||||
在设置期间输入一个 OpenCode key，会为 Zen 和
|
||||
Go 两个运行时 provider 都存储凭证，因此你只需要执行一次新手引导。
|
||||
</Tip>
|
||||
|
||||
## 相关内容
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
选择提供商、模型引用和故障切换行为。
|
||||
选择 provider、模型引用和故障切换行为。
|
||||
</Card>
|
||||
<Card title="配置参考" href="/zh-CN/gateway/configuration-reference" icon="gear">
|
||||
agents、models 和 providers 的完整配置参考。
|
||||
智能体、模型和 provider 的完整配置参考。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,38 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想将 Vercel AI Gateway 与 OpenClaw 一起使用
|
||||
- 你需要 API 密钥环境变量或 CLI 认证选项
|
||||
summary: Vercel AI Gateway 设置（认证 + 模型选择）
|
||||
title: Vercel AI Gateway 网关
|
||||
- 你需要 API 密钥环境变量或 CLI 凭证选择项
|
||||
summary: Vercel AI Gateway 设置（凭证 + 模型选择）
|
||||
title: Vercel AI Gateway
|
||||
x-i18n:
|
||||
generated_at: "2026-04-22T03:53:30Z"
|
||||
generated_at: "2026-04-23T19:26:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 11c0f764d4c35633d0fbfc189bae0fc451dc799002fc1a6d0c84fc73842bbe31
|
||||
source_hash: 410dfb7c0f44337653906b661612d946ccf48716ae700a718a4f004b03bc1261
|
||||
source_path: providers/vercel-ai-gateway.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Vercel AI Gateway 网关
|
||||
# Vercel AI Gateway
|
||||
|
||||
[Vercel AI Gateway](https://vercel.com/ai-gateway) 提供统一的 API，让你通过单个端点访问数百种模型。
|
||||
[Vercel AI Gateway](https://vercel.com/ai-gateway) 提供统一 API，可通过单一端点访问数百种模型。
|
||||
|
||||
| Property | Value |
|
||||
| 属性 | 值 |
|
||||
| ------------- | -------------------------------- |
|
||||
| 提供商 | `vercel-ai-gateway` |
|
||||
| 认证 | `AI_GATEWAY_API_KEY` |
|
||||
| API | 与 Anthropic Messages 兼容 |
|
||||
| 凭证 | `AI_GATEWAY_API_KEY` |
|
||||
| API | 兼容 Anthropic Messages |
|
||||
| 模型目录 | 通过 `/v1/models` 自动发现 |
|
||||
|
||||
<Tip>
|
||||
OpenClaw 会自动发现 Gateway 网关 的 `/v1/models` 目录，因此 `/models vercel-ai-gateway` 会包含当前的模型引用，例如 `vercel-ai-gateway/openai/gpt-5.4` 和 `vercel-ai-gateway/moonshotai/kimi-k2.6`。
|
||||
OpenClaw 会自动发现 Gateway 网关的 `/v1/models` 目录，因此
|
||||
`/models vercel-ai-gateway` 会包含当前模型引用，例如
|
||||
`vercel-ai-gateway/openai/gpt-5.5` 和
|
||||
`vercel-ai-gateway/moonshotai/kimi-k2.6`。
|
||||
</Tip>
|
||||
|
||||
## 入门指南
|
||||
|
||||
<Steps>
|
||||
<Step title="设置 API 密钥">
|
||||
运行新手引导并选择 AI Gateway 网关 认证选项：
|
||||
运行新手引导并选择 AI Gateway 凭证选项：
|
||||
|
||||
```bash
|
||||
openclaw onboard --auth-choice ai-gateway-api-key
|
||||
@ -40,7 +43,7 @@ OpenClaw 会自动发现 Gateway 网关 的 `/v1/models` 目录，因此 `/model
|
||||
|
||||
</Step>
|
||||
<Step title="设置默认模型">
|
||||
将该模型添加到你的 OpenClaw 配置中：
|
||||
将模型添加到你的 OpenClaw 配置中：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -62,7 +65,7 @@ OpenClaw 会自动发现 Gateway 网关 的 `/v1/models` 目录，因此 `/model
|
||||
|
||||
## 非交互式示例
|
||||
|
||||
对于脚本化或 CI 设置，请在命令行中传递所有值：
|
||||
对于脚本化或 CI 设置，请在命令行中传入所有值：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -73,31 +76,32 @@ openclaw onboard --non-interactive \
|
||||
|
||||
## 模型 ID 简写
|
||||
|
||||
OpenClaw 接受 Vercel Claude 的简写模型引用，并会在运行时将其标准化：
|
||||
OpenClaw 接受 Vercel Claude 简写模型引用，并会在运行时将其规范化：
|
||||
|
||||
| 简写输入 | 标准化后的模型引用 |
|
||||
| 简写输入 | 规范化后的模型引用 |
|
||||
| ----------------------------------- | --------------------------------------------- |
|
||||
| `vercel-ai-gateway/claude-opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4.6` |
|
||||
| `vercel-ai-gateway/opus-4.6` | `vercel-ai-gateway/anthropic/claude-opus-4-6` |
|
||||
|
||||
<Tip>
|
||||
你可以在配置中使用简写或完整限定的模型引用。OpenClaw 会自动解析为规范形式。
|
||||
你可以在配置中使用简写，也可以使用完整模型引用。OpenClaw 会自动解析为规范形式。
|
||||
</Tip>
|
||||
|
||||
## 高级说明
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="用于守护进程的环境变量">
|
||||
如果 OpenClaw Gateway 网关 以守护进程（launchd/systemd）方式运行，请确保 `AI_GATEWAY_API_KEY` 可供该进程使用。
|
||||
<Accordion title="守护进程的环境变量">
|
||||
如果 OpenClaw Gateway 网关以守护进程方式运行（launchd/systemd），请确保
|
||||
`AI_GATEWAY_API_KEY` 对该进程可用。
|
||||
|
||||
<Warning>
|
||||
如果密钥只设置在 `~/.profile` 中，除非显式导入该环境，否则 launchd/systemd 守护进程将无法看到它。请在 `~/.openclaw/.env` 中设置该密钥，或通过 `env.shellEnv` 设置，以确保 Gateway 网关 进程可以读取它。
|
||||
如果密钥仅设置在 `~/.profile` 中，那么 launchd/systemd 守护进程将无法看到它，除非显式导入该环境。请将密钥设置在 `~/.openclaw/.env` 中，或通过 `env.shellEnv` 提供，以确保 Gateway 网关进程可以读取它。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="提供商路由">
|
||||
Vercel AI Gateway 网关 会根据模型引用前缀将请求路由到上游提供商。例如，`vercel-ai-gateway/anthropic/claude-opus-4.6` 会通过 Anthropic 路由，`vercel-ai-gateway/openai/gpt-5.4` 会通过 OpenAI 路由，而 `vercel-ai-gateway/moonshotai/kimi-k2.6` 会通过 Moonshot AI 路由。单个 `AI_GATEWAY_API_KEY` 即可处理所有上游提供商的认证。
|
||||
Vercel AI Gateway 会根据模型引用前缀将请求路由到上游提供商。例如，`vercel-ai-gateway/anthropic/claude-opus-4.6` 会通过 Anthropic 路由，而 `vercel-ai-gateway/openai/gpt-5.5` 会通过 OpenAI 路由，`vercel-ai-gateway/moonshotai/kimi-k2.6` 会通过 MoonshotAI 路由。你的单个 `AI_GATEWAY_API_KEY` 会处理所有上游提供商的认证。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -105,9 +109,9 @@ OpenClaw 接受 Vercel Claude 的简写模型引用，并会在运行时将其
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
选择提供商、模型引用和故障切换行为。
|
||||
选择提供商、模型引用和回退行为。
|
||||
</Card>
|
||||
<Card title="故障排除" href="/zh-CN/help/troubleshooting" icon="wrench">
|
||||
常规故障排除和常见问题。
|
||||
通用故障排除和常见问题。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,14 +1,14 @@
|
||||
---
|
||||
read_when:
|
||||
- 重构 QA 场景定义或 qa-lab 测试框架代码
|
||||
- 在 Markdown 场景与 TypeScript 测试框架逻辑之间迁移 QA 行为
|
||||
summary: QA 重构：场景目录与测试框架整合计划
|
||||
- 重构 QA 场景定义或 qa-lab Harness 代码
|
||||
- 在 Markdown 场景与 TypeScript Harness 逻辑之间迁移 QA 行为
|
||||
summary: 用于场景目录和 Harness 整合的 QA 重构计划
|
||||
title: QA 重构
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T06:43:04Z"
|
||||
generated_at: "2026-04-23T19:26:47Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 16867d5be372ab414aa516144193144414c326ea53a52627f3ff91f85b8fdf9d
|
||||
source_hash: ffb9c79628fa6208dfaf731c6fb4c767e85a126c8f2066ca859721c5f62b9ab9
|
||||
source_path: refactor/qa.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -19,21 +19,21 @@ x-i18n:
|
||||
|
||||
## 目标
|
||||
|
||||
将 OpenClaw QA 从分裂定义模型迁移为单一事实来源：
|
||||
将 OpenClaw QA 从分裂式定义模型迁移为单一事实来源：
|
||||
|
||||
- 场景元数据
|
||||
- 发送给模型的提示词
|
||||
- 设置与清理
|
||||
- 测试框架逻辑
|
||||
- setup 和 teardown
|
||||
- Harness 逻辑
|
||||
- 断言与成功标准
|
||||
- 产物与报告提示
|
||||
|
||||
期望的最终状态是：一个通用 QA 测试框架加载功能强大的场景定义文件，而不是在 TypeScript 中硬编码大部分行为。
|
||||
期望的最终状态是：一个通用 QA Harness 加载强大的场景定义文件，而不是将大部分行为硬编码在 TypeScript 中。
|
||||
|
||||
## 当前状态
|
||||
|
||||
当前的主要事实来源已位于 `qa/scenarios/index.md`，以及
|
||||
`qa/scenarios/<theme>/*.md` 下每个场景对应的单独文件中。
|
||||
主要事实来源现在位于 `qa/scenarios/index.md`，以及每个场景对应的
|
||||
`qa/scenarios/<theme>/*.md` 文件。
|
||||
|
||||
已实现：
|
||||
|
||||
@ -44,29 +44,29 @@ x-i18n:
|
||||
- `qa/scenarios/<theme>/*.md`
|
||||
- 每个场景一个 Markdown 文件
|
||||
- 场景元数据
|
||||
- handler 绑定
|
||||
- 场景特定执行配置
|
||||
- 处理器绑定
|
||||
- 场景专用执行配置
|
||||
- `extensions/qa-lab/src/scenario-catalog.ts`
|
||||
- Markdown 包解析器 + zod 校验
|
||||
- `extensions/qa-lab/src/qa-agent-bootstrap.ts`
|
||||
- 从 Markdown 包渲染计划
|
||||
- 基于 Markdown 包渲染计划
|
||||
- `extensions/qa-lab/src/qa-agent-workspace.ts`
|
||||
- 生成兼容性种子文件以及 `QA_SCENARIOS.md`
|
||||
- 生成兼容性文件以及 `QA_SCENARIOS.md`
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- 通过 Markdown 定义的 handler 绑定选择可执行场景
|
||||
- 通过 Markdown 定义的处理器绑定选择可执行场景
|
||||
- QA bus 协议 + UI
|
||||
- 用于图像/视频/音频/文件渲染的通用内联附件
|
||||
|
||||
仍然分裂的表面：
|
||||
仍然存在的分裂界面：
|
||||
|
||||
- `extensions/qa-lab/src/suite.ts`
|
||||
- 仍然承载大部分可执行的自定义 handler 逻辑
|
||||
- 仍然承载大部分可执行的自定义处理器逻辑
|
||||
- `extensions/qa-lab/src/report.ts`
|
||||
- 仍然从运行时输出中推导报告结构
|
||||
- 仍然从运行时输出推导报告结构
|
||||
|
||||
因此，事实来源分裂的问题已修复，但执行层面目前仍主要依赖 handler，而非完全声明式。
|
||||
因此，事实来源分裂的问题已经修复，但执行层仍主要由处理器支持，而不是完全声明式。
|
||||
|
||||
## 实际的场景表面是什么样的
|
||||
## 实际的场景界面是什么样的
|
||||
|
||||
阅读当前 suite 可以看到几类不同的场景。
|
||||
|
||||
@ -74,16 +74,16 @@ x-i18n:
|
||||
|
||||
- 渠道基线
|
||||
- 私信基线
|
||||
- 线程跟进
|
||||
- 线程后续跟进
|
||||
- 模型切换
|
||||
- 审批继续执行
|
||||
- 反应/编辑/删除
|
||||
- 审批后续执行
|
||||
- reaction/edit/delete
|
||||
|
||||
### 配置与运行时变更
|
||||
|
||||
- 配置补丁禁用 Skills
|
||||
- 配置应用后重启唤醒
|
||||
- 配置重启能力切换
|
||||
- config patch 技能禁用
|
||||
- config apply 重启唤醒
|
||||
- config restart 能力切换
|
||||
- 运行时清单漂移检查
|
||||
|
||||
### 文件系统与仓库断言
|
||||
@ -92,47 +92,47 @@ x-i18n:
|
||||
- 构建 Lobster Invaders
|
||||
- 生成图像产物查找
|
||||
|
||||
### Memory 编排
|
||||
### 内存编排
|
||||
|
||||
- 记忆召回
|
||||
- 渠道上下文中的记忆工具
|
||||
- 记忆失败回退
|
||||
- 会话记忆排序
|
||||
- 线程记忆隔离
|
||||
- 记忆 Dreaming 扫描
|
||||
- 内存回忆
|
||||
- 渠道上下文中的内存工具
|
||||
- 内存失败回退
|
||||
- 会话内存排序
|
||||
- 线程内存隔离
|
||||
- memory dreaming sweep
|
||||
|
||||
### 工具与插件集成
|
||||
|
||||
- MCP plugin-tools 调用
|
||||
- skill 可见性
|
||||
- skill 热安装
|
||||
- 技能可见性
|
||||
- 技能热安装
|
||||
- 原生图像生成
|
||||
- 图像往返
|
||||
- 从附件理解图像
|
||||
- 基于附件的图像理解
|
||||
|
||||
### 多轮与多参与者
|
||||
### 多轮次与多参与者
|
||||
|
||||
- 子智能体移交
|
||||
- 子智能体扇出综合
|
||||
- subagent 切换交接
|
||||
- subagent 扇出综合
|
||||
- 重启恢复类流程
|
||||
|
||||
这些分类之所以重要，是因为它们决定了 DSL 的需求。仅有“提示词 + 期望文本”的扁平列表是不够的。
|
||||
这些类别很重要，因为它们决定 DSL 需求。仅有“提示词 + 预期文本”的扁平列表是不够的。
|
||||
|
||||
## 方向
|
||||
|
||||
### 单一事实来源
|
||||
|
||||
使用 `qa/scenarios/index.md` 和 `qa/scenarios/<theme>/*.md` 作为编写时的单一事实来源。
|
||||
使用 `qa/scenarios/index.md` 和 `qa/scenarios/<theme>/*.md` 作为编写层面的事实来源。
|
||||
|
||||
这个包应保持：
|
||||
该场景包应保持：
|
||||
|
||||
- 在评审中人类可读
|
||||
- 机器可解析
|
||||
- 足够丰富，能够驱动：
|
||||
- 便于人工评审阅读
|
||||
- 可供机器解析
|
||||
- 足够丰富，以驱动：
|
||||
- suite 执行
|
||||
- QA 工作区引导
|
||||
- QA 工作区 bootstrap
|
||||
- QA Lab UI 元数据
|
||||
- 文档/发现提示词
|
||||
- docs/discovery 提示词
|
||||
- 报告生成
|
||||
|
||||
### 首选编写格式
|
||||
@ -160,15 +160,15 @@ x-i18n:
|
||||
- assertions
|
||||
- cleanup
|
||||
|
||||
这样可以获得：
|
||||
这样可以带来：
|
||||
|
||||
- 比大型 JSON 更好的 PR 可读性
|
||||
- 比纯 YAML 更丰富的上下文
|
||||
- 比庞大的 JSON 更适合在 PR 中阅读
|
||||
- 比纯 YAML 具有更丰富的上下文
|
||||
- 严格解析和 zod 校验
|
||||
|
||||
原始 JSON 只应作为中间生成形式被接受。
|
||||
仅在作为中间生成形式时，才接受原始 JSON。
|
||||
|
||||
## 建议的场景文件结构
|
||||
## 提议的场景文件结构
|
||||
|
||||
示例：
|
||||
|
||||
@ -179,7 +179,7 @@ title: Image generation roundtrip
|
||||
surface: image
|
||||
tags: [media, image, roundtrip]
|
||||
models:
|
||||
primary: openai/gpt-5.4
|
||||
primary: openai/gpt-5.5
|
||||
requires:
|
||||
tools: [image_generate]
|
||||
plugins: [openai, qa-channel]
|
||||
@ -193,7 +193,7 @@ codeRefs:
|
||||
|
||||
# Objective
|
||||
|
||||
验证生成的媒体会在后续轮次中重新附加。
|
||||
Verify generated media is reattached on the follow-up turn.
|
||||
|
||||
# Setup
|
||||
|
||||
@ -214,7 +214,7 @@ codeRefs:
|
||||
- action: agent.send
|
||||
session: agent:qa:image-roundtrip
|
||||
message: |
|
||||
图像生成检查：生成一张 QA 灯塔图像，并用一句简短的话总结它。
|
||||
Image generation check: generate a QA lighthouse image and summarize it in one short sentence.
|
||||
- action: artifact.capture
|
||||
kind: generated-image
|
||||
promptSnippet: Image generation check
|
||||
@ -222,7 +222,7 @@ codeRefs:
|
||||
- action: agent.send
|
||||
session: agent:qa:image-roundtrip
|
||||
message: |
|
||||
图像往返检查：用一句简短的话描述生成的灯塔附件。
|
||||
Roundtrip image inspection check: describe the generated lighthouse attachment in one short sentence.
|
||||
attachments:
|
||||
- fromArtifact: lighthouseImage
|
||||
```
|
||||
@ -241,11 +241,11 @@ codeRefs:
|
||||
```
|
||||
````
|
||||
|
||||
## DSL 必须覆盖的 Runner 能力
|
||||
## DSL 必须覆盖的运行器能力
|
||||
|
||||
根据当前 suite，通用 runner 需要的不仅仅是执行提示词。
|
||||
根据当前 suite，通用运行器需要的不只是提示词执行。
|
||||
|
||||
### 环境与设置操作
|
||||
### 环境与 setup 动作
|
||||
|
||||
- `bus.reset`
|
||||
- `gateway.waitHealthy`
|
||||
@ -254,14 +254,14 @@ codeRefs:
|
||||
- `thread.create`
|
||||
- `workspace.writeSkill`
|
||||
|
||||
### 智能体轮次操作
|
||||
### 智能体轮次动作
|
||||
|
||||
- `agent.send`
|
||||
- `agent.wait`
|
||||
- `bus.injectInbound`
|
||||
- `bus.injectOutbound`
|
||||
|
||||
### 配置与运行时操作
|
||||
### 配置与运行时动作
|
||||
|
||||
- `config.get`
|
||||
- `config.patch`
|
||||
@ -270,7 +270,7 @@ codeRefs:
|
||||
- `tools.effective`
|
||||
- `skills.status`
|
||||
|
||||
### 文件与产物操作
|
||||
### 文件与产物动作
|
||||
|
||||
- `file.write`
|
||||
- `file.read`
|
||||
@ -279,7 +279,7 @@ codeRefs:
|
||||
- `artifact.captureGeneratedImage`
|
||||
- `artifact.capturePath`
|
||||
|
||||
### Memory 与 cron 操作
|
||||
### 内存与 cron 动作
|
||||
|
||||
- `memory.indexForce`
|
||||
- `memory.searchCli`
|
||||
@ -289,7 +289,7 @@ codeRefs:
|
||||
- `cron.waitCompletion`
|
||||
- `sessionTranscript.write`
|
||||
|
||||
### MCP 操作
|
||||
### MCP 动作
|
||||
|
||||
- `mcp.callTool`
|
||||
|
||||
@ -311,43 +311,43 @@ codeRefs:
|
||||
|
||||
## 变量与产物引用
|
||||
|
||||
DSL 必须支持保存输出并在后续引用。
|
||||
DSL 必须支持保存输出以及后续引用。
|
||||
|
||||
来自当前 suite 的示例：
|
||||
|
||||
- 创建线程，然后复用 `threadId`
|
||||
- 创建会话，然后复用 `sessionKey`
|
||||
- 生成图像，然后在下一轮附加该文件
|
||||
- 生成一个唤醒标记字符串，然后断言它稍后出现
|
||||
- 生成图像，然后在下一轮中附加该文件
|
||||
- 生成一个唤醒标记字符串，然后断言它稍后会出现
|
||||
|
||||
所需能力：
|
||||
|
||||
- `saveAs`
|
||||
- `${vars.name}`
|
||||
- `${artifacts.name}`
|
||||
- 路径、会话键、线程 ID、标记、工具输出的类型化引用
|
||||
- 针对路径、会话键、线程 id、标记、工具输出的类型化引用
|
||||
|
||||
如果没有变量支持，测试框架逻辑仍会不断从 DSL 泄漏回 TypeScript。
|
||||
如果没有变量支持，Harness 将继续把场景逻辑泄漏回 TypeScript 中。
|
||||
|
||||
## 哪些内容应保留为逃生口
|
||||
|
||||
在第一阶段，实现一个完全纯声明式的 runner 并不现实。
|
||||
在第 1 阶段，实现一个完全纯粹的声明式运行器并不现实。
|
||||
|
||||
有些场景天生就更偏编排：
|
||||
有些场景天然就需要大量编排：
|
||||
|
||||
- 记忆 Dreaming 扫描
|
||||
- 配置应用后重启唤醒
|
||||
- 配置重启能力切换
|
||||
- 基于时间戳/路径解析生成图像产物
|
||||
- memory dreaming sweep
|
||||
- config apply 重启唤醒
|
||||
- config restart 能力切换
|
||||
- 按时间戳/路径解析生成图像产物
|
||||
- discovery-report 评估
|
||||
|
||||
目前这些应继续使用显式自定义 handler。
|
||||
这些场景目前应继续使用显式自定义处理器。
|
||||
|
||||
推荐规则：
|
||||
|
||||
- 85–90% 声明式
|
||||
- 对于剩余复杂部分，使用显式 `customHandler` 步骤
|
||||
- 仅允许已命名并有文档的自定义 handler
|
||||
- 对于剩余的困难部分，使用显式 `customHandler` 步骤
|
||||
- 只允许具名且有文档的自定义处理器
|
||||
- 场景文件中不允许匿名内联代码
|
||||
|
||||
这样既能保持通用引擎整洁，又能继续推进。
|
||||
@ -356,19 +356,19 @@ DSL 必须支持保存输出并在后续引用。
|
||||
|
||||
### 当前
|
||||
|
||||
场景 Markdown 现在已是以下内容的事实来源：
|
||||
场景 Markdown 已经是以下内容的事实来源：
|
||||
|
||||
- suite 执行
|
||||
- 工作区引导文件
|
||||
- 工作区 bootstrap 文件
|
||||
- QA Lab UI 场景目录
|
||||
- 报告元数据
|
||||
- 发现提示词
|
||||
- discovery 提示词
|
||||
|
||||
已生成的兼容性内容：
|
||||
生成的兼容层：
|
||||
|
||||
- 种子工作区仍包含 `QA_KICKOFF_TASK.md`
|
||||
- 种子工作区仍包含 `QA_SCENARIO_PLAN.md`
|
||||
- 种子工作区现在还包含 `QA_SCENARIOS.md`
|
||||
- 已植入的工作区仍然包含 `QA_KICKOFF_TASK.md`
|
||||
- 已植入的工作区仍然包含 `QA_SCENARIO_PLAN.md`
|
||||
- 已植入的工作区现在还包含 `QA_SCENARIOS.md`
|
||||
|
||||
## 重构计划
|
||||
|
||||
@ -378,10 +378,10 @@ DSL 必须支持保存输出并在后续引用。
|
||||
|
||||
- 添加了 `qa/scenarios/index.md`
|
||||
- 将场景拆分到 `qa/scenarios/<theme>/*.md`
|
||||
- 添加了命名 Markdown YAML 包内容解析器
|
||||
- 为具名 Markdown YAML 包内容添加了解析器
|
||||
- 使用 zod 进行校验
|
||||
- 将消费者切换到解析后的包
|
||||
- 移除了仓库级的 `qa/seed-scenarios.json` 和 `qa/QA_KICKOFF_TASK.md`
|
||||
- 将消费者切换到解析后的场景包
|
||||
- 删除了仓库级 `qa/seed-scenarios.json` 和 `qa/QA_KICKOFF_TASK.md`
|
||||
|
||||
### 第 2 阶段：通用引擎
|
||||
|
||||
@ -395,13 +395,13 @@ DSL 必须支持保存输出并在后续引用。
|
||||
|
||||
交付物：
|
||||
|
||||
- 引擎可执行简单的声明式场景
|
||||
- 引擎能够执行简单的声明式场景
|
||||
|
||||
从主要是“提示词 + 等待 + 断言”的场景开始：
|
||||
从那些大多由“提示词 + 等待 + 断言”构成的场景开始：
|
||||
|
||||
- 线程跟进
|
||||
- 从附件理解图像
|
||||
- skill 可见性与调用
|
||||
- 线程后续跟进
|
||||
- 基于附件的图像理解
|
||||
- 技能可见性与调用
|
||||
- 渠道基线
|
||||
|
||||
交付物：
|
||||
@ -411,35 +411,35 @@ DSL 必须支持保存输出并在后续引用。
|
||||
### 第 4 阶段：迁移中等复杂度场景
|
||||
|
||||
- 图像生成往返
|
||||
- 渠道上下文中的记忆工具
|
||||
- 会话记忆排序
|
||||
- 子智能体移交
|
||||
- 子智能体扇出综合
|
||||
- 渠道上下文中的内存工具
|
||||
- 会话内存排序
|
||||
- subagent 切换交接
|
||||
- subagent 扇出综合
|
||||
|
||||
交付物：
|
||||
|
||||
- 变量、产物、工具断言、request-log 断言得到验证
|
||||
- 变量、产物、工具断言、请求日志断言都得到验证
|
||||
|
||||
### 第 5 阶段：将复杂场景保留在自定义 handler 中
|
||||
### 第 5 阶段：将困难场景保留在自定义处理器中
|
||||
|
||||
- 记忆 Dreaming 扫描
|
||||
- 配置应用后重启唤醒
|
||||
- 配置重启能力切换
|
||||
- memory dreaming sweep
|
||||
- config apply 重启唤醒
|
||||
- config restart 能力切换
|
||||
- 运行时清单漂移
|
||||
|
||||
交付物：
|
||||
|
||||
- 保持相同的编写格式，但在需要时使用显式自定义步骤块
|
||||
- 仍使用同一种编写格式，但在需要时使用显式自定义步骤块
|
||||
|
||||
### 第 6 阶段：删除硬编码场景映射
|
||||
|
||||
当包覆盖率足够高后：
|
||||
当场景包覆盖率足够高后：
|
||||
|
||||
- 删除 `extensions/qa-lab/src/suite.ts` 中大部分特定场景的 TypeScript 分支逻辑
|
||||
- 删除 `extensions/qa-lab/src/suite.ts` 中大部分场景专用 TypeScript 分支
|
||||
|
||||
## Fake Slack / 富媒体支持
|
||||
## 假 Slack / 富媒体支持
|
||||
|
||||
当前的 QA bus 以文本为主。
|
||||
当前 QA bus 以文本为主。
|
||||
|
||||
相关文件：
|
||||
|
||||
@ -449,17 +449,17 @@ DSL 必须支持保存输出并在后续引用。
|
||||
- `extensions/qa-lab/src/bus-server.ts`
|
||||
- `extensions/qa-lab/web/src/ui-render.ts`
|
||||
|
||||
当前 QA bus 支持：
|
||||
目前 QA bus 支持：
|
||||
|
||||
- 文本
|
||||
- 反应
|
||||
- reactions
|
||||
- 线程
|
||||
|
||||
它尚未对内联媒体附件建模。
|
||||
|
||||
### 所需传输契约
|
||||
### 所需的传输契约
|
||||
|
||||
添加一个通用 QA bus 附件模型：
|
||||
添加一个通用的 QA bus 附件模型：
|
||||
|
||||
```ts
|
||||
type QaBusAttachment = {
|
||||
@ -478,67 +478,67 @@ type QaBusAttachment = {
|
||||
};
|
||||
```
|
||||
|
||||
然后将 `attachments?: QaBusAttachment[]` 添加到：
|
||||
然后为以下类型添加 `attachments?: QaBusAttachment[]`：
|
||||
|
||||
- `QaBusMessage`
|
||||
- `QaBusInboundMessageInput`
|
||||
- `QaBusOutboundMessageInput`
|
||||
|
||||
### 为什么先做通用模型
|
||||
### 为什么要先做通用层
|
||||
|
||||
不要构建仅限 Slack 的媒体模型。
|
||||
不要构建 Slack 专用的媒体模型。
|
||||
|
||||
而应采用：
|
||||
应当改为：
|
||||
|
||||
- 一个通用 QA 传输模型
|
||||
- 其上支持多个渲染器
|
||||
- 当前的 QA Lab 聊天
|
||||
- 未来的 fake Slack web
|
||||
- 其他任何 fake transport 视图
|
||||
- 一个通用的 QA 传输模型
|
||||
- 其上构建多个渲染器
|
||||
- 当前 QA Lab 聊天界面
|
||||
- 未来的假 Slack 网页界面
|
||||
- 其他任何假传输视图
|
||||
|
||||
这样可以避免重复逻辑，并让媒体场景保持与传输方式无关。
|
||||
这样可以避免重复逻辑，并让媒体场景保持与传输层无关。
|
||||
|
||||
### 所需 UI 工作
|
||||
### 需要的 UI 工作
|
||||
|
||||
更新 QA UI，以渲染：
|
||||
|
||||
- 内联图片预览
|
||||
- 内联图像预览
|
||||
- 内联音频播放器
|
||||
- 内联视频播放器
|
||||
- 文件附件 chip
|
||||
|
||||
当前 UI 已能渲染线程和反应，因此附件渲染应能叠加到相同的消息卡片模型上。
|
||||
当前 UI 已经可以渲染线程和 reactions，因此附件渲染应能叠加到同一套消息卡片模型上。
|
||||
|
||||
### 媒体传输将启用的场景工作
|
||||
### 媒体传输启用后的场景工作
|
||||
|
||||
一旦附件可以通过 QA bus 流动，我们就能添加更丰富的 fake-chat 场景：
|
||||
一旦附件能够通过 QA bus 流转，我们就可以添加更丰富的假聊天场景：
|
||||
|
||||
- fake Slack 中的内联图片回复
|
||||
- 假 Slack 中的内联图像回复
|
||||
- 音频附件理解
|
||||
- 视频附件理解
|
||||
- 混合附件顺序
|
||||
- 保留媒体的线程回复
|
||||
- 在线程回复中保留媒体
|
||||
|
||||
## 建议
|
||||
|
||||
下一块实现应当是：
|
||||
下一块实现工作应当是：
|
||||
|
||||
1. 添加 Markdown 场景加载器 + zod schema
|
||||
2. 从 Markdown 生成当前目录
|
||||
3. 先迁移几个简单场景
|
||||
4. 添加通用 QA bus 附件支持
|
||||
5. 在 QA UI 中渲染内联图片
|
||||
5. 在 QA UI 中渲染内联图像
|
||||
6. 然后扩展到音频和视频
|
||||
|
||||
这是能同时验证两个目标的最小路径：
|
||||
这是能够同时证明以下两个目标的最小路径：
|
||||
|
||||
- 通用、由 Markdown 定义的 QA
|
||||
- 更丰富的 fake messaging 表面
|
||||
- 通用的、由 Markdown 定义的 QA
|
||||
- 更丰富的假消息界面
|
||||
|
||||
## 未决问题
|
||||
## 未解决问题
|
||||
|
||||
- 场景文件是否应允许嵌入带变量插值的 Markdown 提示词模板
|
||||
- 设置/清理应作为命名区段存在，还是仅作为有序操作列表
|
||||
- 产物引用在 schema 中应为强类型，还是基于字符串
|
||||
- 自定义 handler 应放在一个统一注册表中，还是按 surface 分注册表
|
||||
- 在迁移期间，生成的 JSON 兼容文件是否应继续保留为已检入状态
|
||||
- setup/cleanup 是否应为具名分节，还是仅作为有序动作列表
|
||||
- 产物引用在 schema 中是否应采用强类型，还是基于字符串
|
||||
- 自定义处理器应放在单一注册表中，还是按 surface 分注册表
|
||||
- 迁移期间生成的 JSON 兼容文件是否应继续保留在版本控制中
|
||||
|
||||
@ -1,16 +1,16 @@
|
||||
---
|
||||
read_when:
|
||||
- 查找特定的新手引导步骤或标志
|
||||
- 使用非交互模式自动化新手引导
|
||||
- 使用非交互模式自动执行新手引导
|
||||
- 调试新手引导行为
|
||||
sidebarTitle: Onboarding Reference
|
||||
summary: CLI 新手引导的完整参考：每个步骤、标志和配置字段
|
||||
summary: CLI 新手引导完整参考：每个步骤、标志和配置字段
|
||||
title: 新手引导参考
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T02:36:29Z"
|
||||
generated_at: "2026-04-23T19:26:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 51405f5d9ba3d9553662fd0a03254a709d5eb4b27339c5edfe1da1111629d0dd
|
||||
source_hash: 136fd90adfaaa9f0481168642e5efadb4f9ee67def0ac1bb40433d178f791474
|
||||
source_path: reference/wizard.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -18,63 +18,63 @@ x-i18n:
|
||||
# 新手引导参考
|
||||
|
||||
这是 `openclaw onboard` 的完整参考。
|
||||
如需高层概览，请参阅 [设置向导（CLI）](/zh-CN/start/wizard)。
|
||||
如需高层概览，请参见 [设置向导（CLI）](/zh-CN/start/wizard)。
|
||||
|
||||
## 流程详情（本地模式）
|
||||
## 流程细节（本地模式）
|
||||
|
||||
<Steps>
|
||||
<Step title="现有配置检测">
|
||||
- 如果 `~/.openclaw/openclaw.json` 存在，选择 **保留 / 修改 / 重置**。
|
||||
- 重新运行新手引导**不会**清除任何内容，除非你明确选择 **重置**
|
||||
<Step title="检测现有配置">
|
||||
- 如果 `~/.openclaw/openclaw.json` 已存在，可选择 **保留 / 修改 / 重置**。
|
||||
- 重新运行新手引导**不会**清除任何内容，除非你显式选择 **重置**
|
||||
（或传入 `--reset`）。
|
||||
- CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full`
|
||||
可额外删除工作区。
|
||||
- 如果配置无效或包含旧版键名，向导会停止，并要求
|
||||
你在继续之前运行 `openclaw doctor`。
|
||||
可额外移除工作区。
|
||||
- 如果配置无效或包含旧版键，向导会停止，并要求
|
||||
你先运行 `openclaw doctor` 再继续。
|
||||
- 重置使用 `trash`（绝不使用 `rm`），并提供以下范围：
|
||||
- 仅配置
|
||||
- 配置 + 凭证 + 会话
|
||||
- 完全重置（也会删除工作区）
|
||||
- 完整重置（同时移除工作区）
|
||||
</Step>
|
||||
<Step title="模型/凭证">
|
||||
- **Anthropic API 密钥**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示你输入密钥，然后保存以供守护进程使用。
|
||||
- **Anthropic API 密钥**：在新手引导/配置中是 Anthropic 助手的首选项。
|
||||
- **Anthropic setup-token**：在新手引导/配置中仍然可用，不过 OpenClaw 现在在可用时更倾向于复用 Claude CLI。
|
||||
- **OpenAI Code（Codex）订阅（OAuth）**：浏览器流程；粘贴 `code#state`。
|
||||
- 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
|
||||
- **OpenAI Code（Codex）订阅（设备配对）**：使用短时效设备代码的浏览器配对流程。
|
||||
- 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
|
||||
- **OpenAI API 密钥**：如果存在则使用 `OPENAI_API_KEY`，否则提示你输入密钥，然后将其存储到凭证配置文件中。
|
||||
- 当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。
|
||||
- **xAI（Grok）API 密钥**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。
|
||||
- **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可在 https://opencode.ai/auth 获取），并允许你选择 Zen 或 Go 目录。
|
||||
- **Ollama**：首先提供 **Cloud + Local**、**仅 Cloud** 或 **仅 Local**。`仅 Cloud` 会提示输入 `OLLAMA_API_KEY` 并使用 `https://ollama.com`；依赖主机的模式会提示输入 Ollama 基础 URL、发现可用模型，并在需要时自动拉取所选本地模型；`Cloud + Local` 还会检查该 Ollama 主机是否已登录以使用云访问。
|
||||
- 更多详情：[Ollama](/zh-CN/providers/ollama)
|
||||
- **API 密钥**：会为你存储该密钥。
|
||||
- **Vercel AI Gateway（多模型代理）**：提示输入 `AI_GATEWAY_API_KEY`。
|
||||
- 更多详情：[Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)
|
||||
<Step title="模型/认证">
|
||||
- **Anthropic API key**：如果存在则使用 `ANTHROPIC_API_KEY`，否则提示输入 key，然后保存以供守护进程使用。
|
||||
- **Anthropic API key**：在新手引导/配置中是首选的 Anthropic assistant 选择。
|
||||
- **Anthropic setup-token**：在新手引导/配置中仍可用，不过 OpenClaw 现在在可用时更倾向于复用 Claude CLI。
|
||||
- **OpenAI Code (Codex) subscription (OAuth)**：浏览器流程；粘贴 `code#state`。
|
||||
- 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设为 `openai-codex/gpt-5.5`。
|
||||
- **OpenAI Code (Codex) subscription (device pairing)**：使用短时有效设备码的浏览器配对流程。
|
||||
- 当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设为 `openai-codex/gpt-5.5`。
|
||||
- **OpenAI API key**：如果存在则使用 `OPENAI_API_KEY`，否则提示输入 key，然后将其存入 auth profiles。
|
||||
- 当模型未设置、为 `openai/*`，或为 `openai-codex/*` 时，将 `agents.defaults.model` 设为 `openai/gpt-5.5`。
|
||||
- **xAI (Grok) API key**：提示输入 `XAI_API_KEY`，并将 xAI 配置为模型 provider。
|
||||
- **OpenCode**：提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`，可在 https://opencode.ai/auth 获取），并让你选择 Zen 或 Go 目录。
|
||||
- **Ollama**：首先提供 **Cloud + Local**、**仅 Cloud** 或 **仅 Local**。`仅 Cloud` 会提示输入 `OLLAMA_API_KEY` 并使用 `https://ollama.com`；基于主机的模式会提示输入 Ollama 基础 URL、发现可用模型，并在需要时自动拉取所选本地模型；`Cloud + Local` 还会检查该 Ollama 主机是否已登录并可访问云服务。
|
||||
- 更多细节： [Ollama](/zh-CN/providers/ollama)
|
||||
- **API key**：会为你存储该 key。
|
||||
- **Vercel AI Gateway (multi-model proxy)**：提示输入 `AI_GATEWAY_API_KEY`。
|
||||
- 更多细节： [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)
|
||||
- **Cloudflare AI Gateway**：提示输入 Account ID、Gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
|
||||
- 更多详情：[Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)
|
||||
- 更多细节： [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)
|
||||
- **MiniMax**：会自动写入配置；托管默认值是 `MiniMax-M2.7`。
|
||||
API 密钥设置使用 `minimax/...`，OAuth 设置使用
|
||||
API key 设置使用 `minimax/...`，而 OAuth 设置使用
|
||||
`minimax-portal/...`。
|
||||
- 更多详情：[MiniMax](/zh-CN/providers/minimax)
|
||||
- **StepFun**：会为中国或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。
|
||||
- Standard 当前包含 `step-3.5-flash`，Step Plan 还包含 `step-3.5-flash-2603`。
|
||||
- 更多详情：[StepFun](/zh-CN/providers/stepfun)
|
||||
- **Synthetic（兼容 Anthropic）**：提示输入 `SYNTHETIC_API_KEY`。
|
||||
- 更多详情：[Synthetic](/zh-CN/providers/synthetic)
|
||||
- **Moonshot（Kimi K2）**：会自动写入配置。
|
||||
- 更多细节： [MiniMax](/zh-CN/providers/minimax)
|
||||
- **StepFun**：会自动为中国区或全球端点上的 StepFun standard 或 Step Plan 写入配置。
|
||||
- Standard 当前包含 `step-3.5-flash`，Step Plan 也包含 `step-3.5-flash-2603`。
|
||||
- 更多细节： [StepFun](/zh-CN/providers/stepfun)
|
||||
- **Synthetic (Anthropic-compatible)**：提示输入 `SYNTHETIC_API_KEY`。
|
||||
- 更多细节： [Synthetic](/zh-CN/providers/synthetic)
|
||||
- **Moonshot (Kimi K2)**：会自动写入配置。
|
||||
- **Kimi Coding**：会自动写入配置。
|
||||
- 更多详情：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)
|
||||
- **跳过**：暂不配置凭证。
|
||||
- 从检测到的选项中选择一个默认模型（或手动输入 provider/model）。为获得最佳质量并降低提示注入风险，请选择你的提供商栈中可用的最新一代最强模型。
|
||||
- 新手引导会执行模型检查；如果配置的模型未知或缺少凭证，会发出警告。
|
||||
- API 密钥存储模式默认使用明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。
|
||||
- 凭证配置文件位于 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（API 密钥 + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。
|
||||
- 更多详情：[/concepts/oauth](/zh-CN/concepts/oauth)
|
||||
- 更多细节： [Moonshot AI (Kimi + Kimi Coding)](/zh-CN/providers/moonshot)
|
||||
- **跳过**：暂不配置认证。
|
||||
- 从检测到的选项中选择默认模型（或手动输入 provider/model）。为了获得最佳质量并降低 prompt injection 风险，请选择你的 provider 栈中可用的最新一代最强模型。
|
||||
- 新手引导会运行模型检查，并在配置的模型未知或缺少认证时发出警告。
|
||||
- API key 存储模式默认使用明文 auth-profile 值。使用 `--secret-input-mode ref` 可改为存储基于环境变量的引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）。
|
||||
- Auth profiles 位于 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`（API key + OAuth）。`~/.openclaw/credentials/oauth.json` 仅用于导入旧版数据。
|
||||
- 更多细节： [/concepts/oauth](/zh-CN/concepts/oauth)
|
||||
<Note>
|
||||
无头/服务器提示：先在有浏览器的机器上完成 OAuth，然后复制
|
||||
无头/服务器提示：可先在有浏览器的机器上完成 OAuth，然后复制
|
||||
该智能体的 `auth-profiles.json`（例如
|
||||
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`，或对应的
|
||||
`$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机。`credentials/oauth.json`
|
||||
@ -82,64 +82,64 @@ x-i18n:
|
||||
</Note>
|
||||
</Step>
|
||||
<Step title="工作区">
|
||||
- 默认为 `~/.openclaw/workspace`（可配置）。
|
||||
- 会初始化智能体引导仪式所需的工作区文件。
|
||||
- 完整工作区布局和备份指南：[智能体工作区](/zh-CN/concepts/agent-workspace)
|
||||
- 默认是 `~/.openclaw/workspace`（可配置）。
|
||||
- 会预填智能体 bootstrap 仪式所需的工作区文件。
|
||||
- 完整工作区布局 + 备份指南： [智能体工作区](/zh-CN/concepts/agent-workspace)
|
||||
</Step>
|
||||
<Step title="Gateway 网关">
|
||||
- 端口、绑定、认证模式、Tailscale 暴露。
|
||||
- 认证建议：即使是 loopback，也保留 **Token**，这样本地 WS 客户端也必须进行认证。
|
||||
- 认证建议：即使是 loopback，也请保持 **Token**，这样本地 WS 客户端仍必须进行认证。
|
||||
- 在 token 模式下，交互式设置提供：
|
||||
- **生成/存储明文 token**（默认）
|
||||
- **使用 SecretRef**（可选启用）
|
||||
- 快速开始会在新手引导探测/仪表板引导中，复用 `env`、`file` 和 `exec` 提供商上现有的 `gateway.auth.token` SecretRef。
|
||||
- 如果该 SecretRef 已配置但无法解析，新手引导会尽早失败，并给出清晰的修复信息，而不是静默降级运行时认证。
|
||||
- 在 password 模式下，交互式设置同样支持明文或 SecretRef 存储。
|
||||
- 非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
|
||||
- 要求在新手引导进程环境中存在非空环境变量。
|
||||
- 快速开始会跨 `env`、`file` 和 `exec` provider 复用现有的 `gateway.auth.token` SecretRef，用于新手引导探测/控制面板 bootstrap。
|
||||
- 如果该 SecretRef 已配置但无法解析，新手引导会尽早失败，并给出明确修复信息，而不是静默降级运行时认证。
|
||||
- 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。
|
||||
- 非交互 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
|
||||
- 要求新手引导进程环境中存在且非空的环境变量。
|
||||
- 不能与 `--gateway-token` 同时使用。
|
||||
- 只有在你完全信任每个本地进程时才禁用认证。
|
||||
- 仅当你完全信任每一个本地进程时，才禁用认证。
|
||||
- 非 loopback 绑定仍然要求认证。
|
||||
</Step>
|
||||
<Step title="渠道">
|
||||
- [WhatsApp](/zh-CN/channels/whatsapp)：可选二维码登录。
|
||||
- [Telegram](/zh-CN/channels/telegram)：机器人 token。
|
||||
- [Discord](/zh-CN/channels/discord)：机器人 token。
|
||||
- [Google Chat](/zh-CN/channels/googlechat)：服务账号 JSON + webhook audience。
|
||||
- [Mattermost](/zh-CN/channels/mattermost)（插件）：机器人 token + 基础 URL。
|
||||
- [Signal](/zh-CN/channels/signal)：可选安装 `signal-cli` + 账号配置。
|
||||
- [BlueBubbles](/zh-CN/channels/bluebubbles)：**推荐用于 iMessage**；服务器 URL + 密码 + webhook。
|
||||
- [WhatsApp](/zh-CN/channels/whatsapp)：可选 QR 登录。
|
||||
- [Telegram](/zh-CN/channels/telegram)：bot token。
|
||||
- [Discord](/zh-CN/channels/discord)：bot token。
|
||||
- [Google Chat](/zh-CN/channels/googlechat)：服务账户 JSON + webhook audience。
|
||||
- [Mattermost](/zh-CN/channels/mattermost)（plugin）：bot token + 基础 URL。
|
||||
- [Signal](/zh-CN/channels/signal)：可选安装 `signal-cli` + 账户配置。
|
||||
- [BlueBubbles](/zh-CN/channels/bluebubbles)：**iMessage 的推荐方案**；服务器 URL + password + webhook。
|
||||
- [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问。
|
||||
- 私信安全：默认启用配对。首次私信会发送验证码；通过 `openclaw pairing approve <channel> <code>` 批准，或使用允许列表。
|
||||
- 私信安全：默认是配对。第一条私信会发送一个代码；通过 `openclaw pairing approve <channel> <code>` 批准，或使用 allowlist。
|
||||
</Step>
|
||||
<Step title="Web 搜索">
|
||||
- 选择一个受支持的提供商，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（或跳过）。
|
||||
- 基于 API 的提供商可使用环境变量或现有配置进行快速设置；无密钥提供商则使用其特定前置条件。
|
||||
- 选择一个受支持的 provider，例如 Brave、DuckDuckGo、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Ollama Web 搜索、Perplexity、SearXNG 或 Tavily（或跳过）。
|
||||
- 基于 API 的 provider 可使用环境变量或现有配置进行快速设置；无 key 的 provider 则使用其各自的前置条件。
|
||||
- 使用 `--skip-search` 跳过。
|
||||
- 稍后配置：`openclaw configure --section web`。
|
||||
</Step>
|
||||
<Step title="守护进程安装">
|
||||
<Step title="安装守护进程">
|
||||
- macOS：LaunchAgent
|
||||
- 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随附）。
|
||||
- 需要已登录的用户会话；对于无头场景，请使用自定义 LaunchDaemon（未内置提供）。
|
||||
- Linux（以及通过 WSL2 的 Windows）：systemd 用户单元
|
||||
- 新手引导会尝试通过 `loginctl enable-linger <user>` 启用 lingering，这样 Gateway 网关会在注销后继续运行。
|
||||
- 可能会提示输入 sudo（会写入 `/var/lib/systemd/linger`）；它会先尝试不使用 sudo。
|
||||
- **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。Bun **不推荐**。
|
||||
- 如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析后的明文 token 值持久化到监督服务环境元数据中。
|
||||
- 如果 token 认证需要 token，而已配置的 token SecretRef 未解析，守护进程安装会被阻止，并提供可执行的指导。
|
||||
- 如果同时配置了 `gateway.auth.token` 和 `gateway.auth.password`，但未设置 `gateway.auth.mode`，守护进程安装会被阻止，直到显式设置模式。
|
||||
- 新手引导会尝试启用 lingering：`loginctl enable-linger <user>`，以便 Gateway 网关在登出后继续运行。
|
||||
- 可能会提示使用 sudo（写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。
|
||||
- **运行时选择：** Node（推荐；WhatsApp/Telegram 必需）。**不推荐** Bun。
|
||||
- 如果 token 认证需要 token，且 `gateway.auth.token` 由 SecretRef 管理，守护进程安装会验证它，但不会将解析出的明文 token 值持久化到 supervisor 服务环境元数据中。
|
||||
- 如果 token 认证需要 token，且配置的 token SecretRef 无法解析，守护进程安装会被阻止，并给出可执行的指导。
|
||||
- 如果 `gateway.auth.token` 和 `gateway.auth.password` 都已配置，而 `gateway.auth.mode` 未设置，守护进程安装会被阻止，直到显式设置 mode。
|
||||
</Step>
|
||||
<Step title="健康检查">
|
||||
- 启动 Gateway 网关（如有需要）并运行 `openclaw health`。
|
||||
- 提示：`openclaw status --deep` 会将实时 Gateway 网关健康探测添加到状态输出中，包括在支持时的渠道探测（需要 Gateway 网关可访问）。
|
||||
- 启动 Gateway 网关（如有需要），并运行 `openclaw health`。
|
||||
- 提示：`openclaw status --deep` 会在状态输出中加入实时 Gateway 网关健康探测，包括支持时的渠道探测（要求 Gateway 网关可达）。
|
||||
</Step>
|
||||
<Step title="Skills（推荐）">
|
||||
- 读取可用的 Skills 并检查要求。
|
||||
- 让你选择一个节点管理器：**npm / pnpm**（bun 不推荐）。
|
||||
- 安装可选依赖项（其中一些在 macOS 上使用 Homebrew）。
|
||||
- 读取可用 Skills 并检查要求。
|
||||
- 让你选择一个节点管理器：**npm / pnpm**（不推荐 bun）。
|
||||
- 安装可选依赖（有些在 macOS 上使用 Homebrew）。
|
||||
</Step>
|
||||
<Step title="完成">
|
||||
- 摘要 + 后续步骤，包括提供更多功能的 iOS/Android/macOS 应用。
|
||||
- 摘要 + 后续步骤，包括 iOS/Android/macOS 应用以获得更多功能。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
@ -150,7 +150,7 @@ x-i18n:
|
||||
|
||||
## 非交互模式
|
||||
|
||||
使用 `--non-interactive` 来自动化或编写新手引导脚本：
|
||||
使用 `--non-interactive` 可自动化或脚本化新手引导：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -166,7 +166,7 @@ openclaw onboard --non-interactive \
|
||||
|
||||
添加 `--json` 可获得机器可读摘要。
|
||||
|
||||
在非交互模式下使用 Gateway 网关 token SecretRef：
|
||||
非交互模式中的 Gateway 网关 token SecretRef：
|
||||
|
||||
```bash
|
||||
export OPENCLAW_GATEWAY_TOKEN="your-token"
|
||||
@ -177,13 +177,13 @@ openclaw onboard --non-interactive \
|
||||
--gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN
|
||||
```
|
||||
|
||||
`--gateway-token` 与 `--gateway-token-ref-env` 互斥。
|
||||
`--gateway-token` 和 `--gateway-token-ref-env` 互斥。
|
||||
|
||||
<Note>
|
||||
`--json` **不**意味着非交互模式。脚本中请使用 `--non-interactive`（以及 `--workspace`）。
|
||||
`--json` **不**意味着非交互模式。对于脚本，请使用 `--non-interactive`（以及 `--workspace`）。
|
||||
</Note>
|
||||
|
||||
各提供商的命令示例见 [CLI 自动化](/zh-CN/start/wizard-cli-automation#provider-specific-examples)。
|
||||
provider 专用命令示例位于 [CLI 自动化](/zh-CN/start/wizard-cli-automation#provider-specific-examples)。
|
||||
本参考页用于说明标志语义和步骤顺序。
|
||||
|
||||
### 添加智能体（非交互）
|
||||
@ -191,22 +191,22 @@ openclaw onboard --non-interactive \
|
||||
```bash
|
||||
openclaw agents add work \
|
||||
--workspace ~/.openclaw/workspace-work \
|
||||
--model openai/gpt-5.4 \
|
||||
--model openai/gpt-5.5 \
|
||||
--bind whatsapp:biz \
|
||||
--non-interactive \
|
||||
--json
|
||||
```
|
||||
|
||||
## Gateway 网关向导 RPC
|
||||
## Gateway 向导 RPC
|
||||
|
||||
Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.next`、`wizard.cancel`、`wizard.status`）。
|
||||
客户端（macOS 应用、Control UI）可以渲染各步骤，而无需重新实现新手引导逻辑。
|
||||
客户端（macOS 应用、Control UI）可以渲染这些步骤，而无需重新实现新手引导逻辑。
|
||||
|
||||
## Signal 设置（signal-cli）
|
||||
|
||||
新手引导可以从 GitHub Releases 安装 `signal-cli`：
|
||||
|
||||
- 下载相应的发布资源。
|
||||
- 下载适当的发布资源。
|
||||
- 将其存储到 `~/.openclaw/tools/signal-cli/<version>/` 下。
|
||||
- 将 `channels.signal.cliPath` 写入你的配置。
|
||||
|
||||
@ -214,19 +214,19 @@ Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.nex
|
||||
|
||||
- JVM 构建需要 **Java 21**。
|
||||
- 在可用时会使用原生构建。
|
||||
- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内按 Linux 流程执行。
|
||||
- Windows 使用 WSL2；`signal-cli` 安装会在 WSL 内遵循 Linux 流程。
|
||||
|
||||
## 向导会写入什么
|
||||
## 向导会写入什么内容
|
||||
|
||||
`~/.openclaw/openclaw.json` 中的典型字段：
|
||||
|
||||
- `agents.defaults.workspace`
|
||||
- `agents.defaults.model` / `models.providers`（如果选择了 MiniMax）
|
||||
- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有的显式值会被保留）
|
||||
- `gateway.*`（模式、绑定、认证、Tailscale）
|
||||
- `session.dmScope`（行为详情：[CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)）
|
||||
- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有显式值会被保留）
|
||||
- `gateway.*`（mode、bind、auth、tailscale）
|
||||
- `session.dmScope`（行为细节： [CLI 设置参考](/zh-CN/start/wizard-cli-reference#outputs-and-internals)）
|
||||
- `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*`
|
||||
- 如果你在提示中选择启用，还会写入渠道允许列表（Slack/Discord/Matrix/Microsoft Teams）；在可能的情况下，名称会解析为 ID。
|
||||
- 当你在提示中选择启用时，写入渠道 allowlist（Slack/Discord/Matrix/Microsoft Teams）（如果可能，名称会解析为 ID）。
|
||||
- `skills.install.nodeManager`
|
||||
- `setup --node-manager` 接受 `npm`、`pnpm` 或 `bun`。
|
||||
- 手动配置仍可通过直接设置 `skills.install.nodeManager` 来使用 `yarn`。
|
||||
@ -238,16 +238,16 @@ Gateway 网关通过 RPC 暴露新手引导流程（`wizard.start`、`wizard.nex
|
||||
|
||||
`openclaw agents add` 会写入 `agents.list[]` 和可选的 `bindings`。
|
||||
|
||||
WhatsApp 凭证存储在 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
|
||||
WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
|
||||
会话存储在 `~/.openclaw/agents/<agentId>/sessions/` 下。
|
||||
|
||||
某些渠道以插件形式提供。当你在设置期间选择其中之一时，新手引导
|
||||
会先提示安装它（npm 或本地路径），然后才能进行配置。
|
||||
有些渠道以 plugin 形式提供。当你在设置期间选择其中一个时，新手引导
|
||||
会先提示安装它（npm 或本地路径），然后才能继续配置。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 新手引导概览：[设置向导（CLI）](/zh-CN/start/wizard)
|
||||
- macOS 应用新手引导：[新手引导](/zh-CN/start/onboarding)
|
||||
- 配置参考：[Gateway 网关配置](/zh-CN/gateway/configuration)
|
||||
- 提供商：[WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord)、[Google Chat](/zh-CN/channels/googlechat)、[Signal](/zh-CN/channels/signal)、[BlueBubbles](/zh-CN/channels/bluebubbles)（iMessage）、[iMessage](/zh-CN/channels/imessage)（旧版）
|
||||
- Skills：[Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)
|
||||
- 新手引导概览： [设置向导（CLI）](/zh-CN/start/wizard)
|
||||
- macOS 应用新手引导： [新手引导](/zh-CN/start/onboarding)
|
||||
- 配置参考： [Gateway 网关配置](/zh-CN/gateway/configuration)
|
||||
- Providers： [WhatsApp](/zh-CN/channels/whatsapp)、[Telegram](/zh-CN/channels/telegram)、[Discord](/zh-CN/channels/discord)、[Google Chat](/zh-CN/channels/googlechat)、[Signal](/zh-CN/channels/signal)、[BlueBubbles](/zh-CN/channels/bluebubbles)（iMessage）、[iMessage](/zh-CN/channels/imessage)（旧版）
|
||||
- Skills： [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config)
|
||||
|
||||
@ -1,25 +1,25 @@
|
||||
---
|
||||
read_when:
|
||||
- 你正在脚本或 CI 中自动化新手引导
|
||||
- 你需要针对特定提供商的非交互式示例
|
||||
- 你正在脚本或 CI 中自动执行新手引导
|
||||
- 你需要特定提供商的非交互式示例
|
||||
sidebarTitle: CLI automation
|
||||
summary: 用于 OpenClaw CLI 的脚本化新手引导和智能体设置
|
||||
summary: OpenClaw CLI 的脚本化新手引导与智能体设置
|
||||
title: CLI 自动化
|
||||
x-i18n:
|
||||
generated_at: "2026-04-06T15:31:32Z"
|
||||
generated_at: "2026-04-23T19:26:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: bca2dd6e482a16b27284fc76319e936e8df0ff5558134827c19f6875436cc652
|
||||
source_hash: 755be6e44f88154fbd647278bc9122886a0b08bfcf72213c194f58ee57575551
|
||||
source_path: start/wizard-cli-automation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# CLI 自动化
|
||||
|
||||
使用 `--non-interactive` 来自动化 `openclaw onboard`。
|
||||
使用 `--non-interactive` 可自动执行 `openclaw onboard`。
|
||||
|
||||
<Note>
|
||||
`--json` 并不意味着非交互模式。对于脚本，请使用 `--non-interactive`（以及 `--workspace`）。
|
||||
`--json` 不意味着非交互模式。对于脚本，请使用 `--non-interactive`（以及 `--workspace`）。
|
||||
</Note>
|
||||
|
||||
## 基础非交互式示例
|
||||
@ -37,13 +37,13 @@ openclaw onboard --non-interactive \
|
||||
--skip-skills
|
||||
```
|
||||
|
||||
添加 `--json` 以获得机器可读的摘要。
|
||||
添加 `--json` 可获得机器可读的摘要。
|
||||
|
||||
使用 `--secret-input-mode ref` 可将基于环境变量的引用存储到认证 profile 中，而不是存储明文值。
|
||||
使用 `--secret-input-mode ref` 可将基于环境变量的引用存储到凭证配置中，而不是存储明文值。
|
||||
在新手引导流程中，支持在环境变量引用和已配置的提供商引用（`file` 或 `exec`）之间进行交互式选择。
|
||||
|
||||
在非交互式 `ref` 模式下，提供商环境变量必须在进程环境中设置。
|
||||
传入内联密钥标志但未设置对应环境变量时，现在会快速失败。
|
||||
在非交互式 `ref` 模式下，必须在进程环境中设置提供商环境变量。
|
||||
如果传入内联密钥标志，但未设置对应环境变量，现在会快速失败。
|
||||
|
||||
示例：
|
||||
|
||||
@ -55,7 +55,7 @@ openclaw onboard --non-interactive \
|
||||
--accept-risk
|
||||
```
|
||||
|
||||
## 提供商特定示例
|
||||
## 提供商专用示例
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anthropic API 密钥示例">
|
||||
@ -110,7 +110,7 @@ openclaw onboard --non-interactive \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
</Accordion>
|
||||
<Accordion title="Moonshot AI 示例">
|
||||
<Accordion title="Moonshot 示例">
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
--mode local \
|
||||
@ -149,7 +149,7 @@ openclaw onboard --non-interactive \
|
||||
--gateway-port 18789 \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
如果要使用 Go catalog，请改为 `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"`。
|
||||
如需使用 Go 目录，请改为 `--auth-choice opencode-go --opencode-go-api-key "$OPENCODE_API_KEY"`。
|
||||
</Accordion>
|
||||
<Accordion title="Ollama 示例">
|
||||
```bash
|
||||
@ -176,9 +176,9 @@ openclaw onboard --non-interactive \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
`--custom-api-key` 是可选项。如果省略，新手引导会检查 `CUSTOM_API_KEY`。
|
||||
`--custom-api-key` 为可选项。如果省略，新手引导会检查 `CUSTOM_API_KEY`。
|
||||
|
||||
ref 模式变体：
|
||||
`ref` 模式变体：
|
||||
|
||||
```bash
|
||||
export CUSTOM_API_KEY="your-key"
|
||||
@ -194,23 +194,22 @@ openclaw onboard --non-interactive \
|
||||
--gateway-bind loopback
|
||||
```
|
||||
|
||||
在该模式下，新手引导会将 `apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。
|
||||
在此模式下，新手引导会将 `apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Anthropic setup-token 仍然可作为受支持的新手引导令牌路径使用，但 OpenClaw 现在在可用时更优先使用 Claude CLI 复用。
|
||||
在生产环境中，优先使用 Anthropic API 密钥。
|
||||
Anthropic setup-token 仍然作为受支持的新手引导 token 路径保留，但 OpenClaw 现在在可用时更倾向于复用 Claude CLI。
|
||||
在生产环境中，建议优先使用 Anthropic API 密钥。
|
||||
|
||||
## 添加另一个智能体
|
||||
|
||||
使用 `openclaw agents add <name>` 创建一个单独的智能体，它拥有自己的工作区、
|
||||
会话和认证 profile。不带 `--workspace` 运行会启动向导。
|
||||
使用 `openclaw agents add <name>` 创建一个单独的智能体，它拥有自己的工作区、会话和凭证配置。不带 `--workspace` 运行会启动向导。
|
||||
|
||||
```bash
|
||||
openclaw agents add work \
|
||||
--workspace ~/.openclaw/workspace-work \
|
||||
--model openai/gpt-5.4 \
|
||||
--model openai/gpt-5.5 \
|
||||
--bind whatsapp:biz \
|
||||
--non-interactive \
|
||||
--json
|
||||
@ -225,11 +224,11 @@ openclaw agents add work \
|
||||
说明：
|
||||
|
||||
- 默认工作区遵循 `~/.openclaw/workspace-<agentId>`。
|
||||
- 添加 `bindings` 以路由入站消息（向导可以完成此操作）。
|
||||
- 添加 `bindings` 以路由传入消息（向导可以完成此操作）。
|
||||
- 非交互式标志：`--model`、`--agent-dir`、`--bind`、`--non-interactive`。
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 新手引导中心：[设置向导（CLI）](/zh-CN/start/wizard)
|
||||
- 完整参考：[CLI 设置参考](/zh-CN/start/wizard-cli-reference)
|
||||
- 命令参考：[`openclaw onboard`](/cli/onboard)
|
||||
- 命令参考：[`openclaw onboard`](/zh-CN/cli/onboard)
|
||||
|
||||
@ -1,15 +1,15 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要了解 `openclaw onboard` 的详细行为
|
||||
- 你正在调试新手引导结果，或集成新手引导客户端
|
||||
- 你需要 `openclaw onboard` 的详细行为说明
|
||||
- 你正在调试新手引导结果或集成新手引导客户端
|
||||
sidebarTitle: CLI reference
|
||||
summary: CLI 设置流程、凭证 / 模型设置、输出和内部机制的完整参考
|
||||
summary: CLI 设置流程、凭证/模型设置、输出和内部机制的完整参考
|
||||
title: CLI 设置参考
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T02:36:28Z"
|
||||
generated_at: "2026-04-23T19:27:12Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 60b47a3cd7eaa6e10b5e7108ba4eb331afddffa55a321eac98243611fd7e721b
|
||||
source_hash: 485f7d074b5f9cde9cb9342bd213a93a8221c3561a92184edeceb98c40267d1d
|
||||
source_path: start/wizard-cli-reference.md
|
||||
workflow: 15
|
||||
---
|
||||
@ -17,88 +17,88 @@ x-i18n:
|
||||
# CLI 设置参考
|
||||
|
||||
本页是 `openclaw onboard` 的完整参考。
|
||||
简短指南见 [设置向导（CLI）](/zh-CN/start/wizard)。
|
||||
简要指南请参阅[设置向导（CLI）](/zh-CN/start/wizard)。
|
||||
|
||||
## 向导的作用
|
||||
## 向导会执行什么
|
||||
|
||||
本地模式（默认）会引导你完成：
|
||||
本地模式（默认）会引导你完成以下内容：
|
||||
|
||||
- 模型和凭证设置（OpenAI Code 订阅 OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot、StepFun 和 AI Gateway 选项）
|
||||
- 工作区位置和引导文件
|
||||
- Gateway 网关设置（端口、绑定、凭证、Tailscale）
|
||||
- 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、BlueBubbles，以及其他内置渠道插件）
|
||||
- 模型和凭证设置（OpenAI Code subscription OAuth、Anthropic Claude CLI 或 API 密钥，以及 MiniMax、GLM、Ollama、Moonshot、StepFun 和 AI Gateway 选项）
|
||||
- 工作区位置和 bootstrap 文件
|
||||
- Gateway 网关设置（port、bind、auth、Tailscale）
|
||||
- 渠道和提供商（Telegram、WhatsApp、Discord、Google Chat、Mattermost、Signal、BlueBubbles 及其他内置渠道插件）
|
||||
- 守护进程安装（LaunchAgent、systemd 用户单元，或原生 Windows Scheduled Task，并在失败时回退到 Startup 文件夹）
|
||||
- 健康检查
|
||||
- Skills 设置
|
||||
|
||||
远程模式会将这台机器配置为连接到其他位置的 Gateway 网关。
|
||||
远程模式会将本机配置为连接到其他地方的 Gateway 网关。
|
||||
它不会在远程主机上安装或修改任何内容。
|
||||
|
||||
## 本地流程详情
|
||||
|
||||
<Steps>
|
||||
<Step title="现有配置检测">
|
||||
- 如果存在 `~/.openclaw/openclaw.json`，可选择保留、修改或重置。
|
||||
- 重新运行向导不会清除任何内容，除非你明确选择重置（或传入 `--reset`）。
|
||||
- CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` 还会移除工作区。
|
||||
- 如果配置无效或包含旧版键名，向导会停止，并要求你先运行 `openclaw doctor` 后再继续。
|
||||
<Step title="检测现有配置">
|
||||
- 如果 `~/.openclaw/openclaw.json` 已存在，可选择保留、修改或重置。
|
||||
- 重新运行向导不会清除任何内容，除非你明确选择“重置”（或传入 `--reset`）。
|
||||
- CLI `--reset` 默认作用于 `config+creds+sessions`；使用 `--reset-scope full` 可连同工作区一起移除。
|
||||
- 如果配置无效或包含旧版键名，向导会停止，并要求你先运行 `openclaw doctor` 再继续。
|
||||
- 重置使用 `trash`，并提供以下范围：
|
||||
- 仅配置
|
||||
- 配置 + 凭证 + 会话
|
||||
- 完整重置（同时移除工作区）
|
||||
- 完全重置（还会移除工作区）
|
||||
</Step>
|
||||
<Step title="模型和凭证">
|
||||
- 完整选项矩阵见 [凭证和模型选项](#auth-and-model-options)。
|
||||
<Step title="模型与凭证">
|
||||
- 完整选项矩阵见[凭证与模型选项](#auth-and-model-options)。
|
||||
</Step>
|
||||
<Step title="工作区">
|
||||
- 默认值为 `~/.openclaw/workspace`（可配置）。
|
||||
- 会写入首次运行引导仪式所需的工作区文件。
|
||||
- 工作区布局见：[智能体工作区](/zh-CN/concepts/agent-workspace)。
|
||||
- 默认 `~/.openclaw/workspace`（可配置）。
|
||||
- 会为首次运行 bootstrap ritual 预置所需工作区文件。
|
||||
- 工作区布局： [智能体工作区](/zh-CN/concepts/agent-workspace)。
|
||||
</Step>
|
||||
<Step title="Gateway 网关">
|
||||
- 会提示你设置端口、绑定、凭证模式和 Tailscale 暴露方式。
|
||||
- 推荐：即使仅用于 loopback，也保持启用令牌凭证，这样本地 WS 客户端也必须进行认证。
|
||||
- 在令牌模式下，交互式设置提供：
|
||||
- **生成 / 存储明文令牌**（默认）
|
||||
- 会提示输入 port、bind、auth 模式和 Tailscale 暴露设置。
|
||||
- 建议：即使使用 loopback，也保留 token 认证开启，这样本地 WS 客户端也必须进行认证。
|
||||
- 在 token 模式下，交互式设置提供：
|
||||
- **生成/存储明文 token**（默认）
|
||||
- **使用 SecretRef**（可选启用）
|
||||
- 在密码模式下，交互式设置也支持明文或 SecretRef 存储。
|
||||
- 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
|
||||
- 要求新手引导进程环境中存在非空环境变量。
|
||||
- 在 password 模式下，交互式设置也支持明文或 SecretRef 存储。
|
||||
- 非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
|
||||
- 要求在新手引导进程环境中提供非空环境变量。
|
||||
- 不能与 `--gateway-token` 同时使用。
|
||||
- 仅当你完全信任每个本地进程时，才禁用凭证。
|
||||
- 非 loopback 绑定仍然需要凭证。
|
||||
- 只有在你完全信任每个本地进程时，才建议禁用认证。
|
||||
- 非 loopback 绑定仍然需要认证。
|
||||
</Step>
|
||||
<Step title="渠道">
|
||||
- [WhatsApp](/zh-CN/channels/whatsapp)：可选 QR 登录
|
||||
- [Telegram](/zh-CN/channels/telegram)：机器人令牌
|
||||
- [Discord](/zh-CN/channels/discord)：机器人令牌
|
||||
- [Telegram](/zh-CN/channels/telegram)：bot token
|
||||
- [Discord](/zh-CN/channels/discord)：bot token
|
||||
- [Google Chat](/zh-CN/channels/googlechat)：服务账号 JSON + webhook audience
|
||||
- [Mattermost](/zh-CN/channels/mattermost)：机器人令牌 + 基础 URL
|
||||
- [Mattermost](/zh-CN/channels/mattermost)：bot token + base URL
|
||||
- [Signal](/zh-CN/channels/signal)：可选 `signal-cli` 安装 + 账号配置
|
||||
- [BlueBubbles](/zh-CN/channels/bluebubbles)：推荐用于 iMessage；服务器 URL + 密码 + webhook
|
||||
- [iMessage](/zh-CN/channels/imessage)：旧版 `imsg` CLI 路径 + DB 访问
|
||||
- 私信安全：默认为配对。首次私信会发送一个代码；可通过
|
||||
`openclaw pairing approve <channel> <code>` 批准，或使用 allowlist。
|
||||
- 私信安全：默认是 pairing。首次私信会发送一个代码；可通过
|
||||
`openclaw pairing approve <channel> <code>` 批准，或使用允许列表。
|
||||
</Step>
|
||||
<Step title="守护进程安装">
|
||||
<Step title="安装守护进程">
|
||||
- macOS：LaunchAgent
|
||||
- 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未随产品提供）。
|
||||
- 需要已登录的用户会话；对于无头环境，请使用自定义 LaunchDaemon（未内置提供）。
|
||||
- Linux 和通过 WSL2 的 Windows：systemd 用户单元
|
||||
- 向导会尝试执行 `loginctl enable-linger <user>`，以便 Gateway 网关在注销后继续运行。
|
||||
- 可能会提示 sudo（写入 `/var/lib/systemd/linger`）；它会先尝试无 sudo 方式。
|
||||
- 向导会尝试执行 `loginctl enable-linger <user>`，以便登出后 Gateway 网关仍保持运行。
|
||||
- 可能会请求 sudo（写入 `/var/lib/systemd/linger`）；会先尝试不使用 sudo。
|
||||
- 原生 Windows：优先使用 Scheduled Task
|
||||
- 如果任务创建被拒绝，OpenClaw 会回退到每用户 Startup 文件夹登录项，并立即启动 Gateway 网关。
|
||||
- 仍优先推荐 Scheduled Task，因为它们提供更好的主管理器状态信息。
|
||||
- 运行时选择：Node（推荐；WhatsApp 和 Telegram 需要）。不推荐使用 Bun。
|
||||
- 仍然优先推荐 Scheduled Tasks，因为它们提供更好的 supervisor 状态。
|
||||
- 运行时选择：Node（推荐；WhatsApp 和 Telegram 必需）。不建议使用 Bun。
|
||||
</Step>
|
||||
<Step title="健康检查">
|
||||
- 启动 Gateway 网关（如有需要）并运行 `openclaw health`。
|
||||
- `openclaw status --deep` 会在状态输出中加入实时 Gateway 网关健康探测，包括支持时的渠道探测。
|
||||
- 启动 Gateway 网关（如果需要）并运行 `openclaw health`。
|
||||
- `openclaw status --deep` 会将实时 Gateway 网关健康探测加入状态输出，在支持时还包括渠道探测。
|
||||
</Step>
|
||||
<Step title="Skills">
|
||||
- 读取可用 Skills 并检查要求。
|
||||
- 让你选择 Node 管理器：npm、pnpm 或 bun。
|
||||
- 安装可选依赖（其中一些在 macOS 上使用 Homebrew）。
|
||||
- 读取可用 Skills 并检查依赖要求。
|
||||
- 让你选择 node 管理器：npm、pnpm 或 bun。
|
||||
- 安装可选依赖（部分在 macOS 上使用 Homebrew）。
|
||||
</Step>
|
||||
<Step title="完成">
|
||||
- 显示摘要和后续步骤，包括 iOS、Android 和 macOS 应用选项。
|
||||
@ -107,12 +107,12 @@ x-i18n:
|
||||
|
||||
<Note>
|
||||
如果未检测到 GUI，向导会打印用于 Control UI 的 SSH 端口转发说明，而不是打开浏览器。
|
||||
如果缺少 Control UI 资源，向导会尝试构建它们；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。
|
||||
如果缺少 Control UI 资源，向导会尝试构建；回退命令为 `pnpm ui:build`（会自动安装 UI 依赖）。
|
||||
</Note>
|
||||
|
||||
## 远程模式详情
|
||||
|
||||
远程模式会将这台机器配置为连接到其他位置的 Gateway 网关。
|
||||
远程模式会将本机配置为连接到其他地方的 Gateway 网关。
|
||||
|
||||
<Info>
|
||||
远程模式不会在远程主机上安装或修改任何内容。
|
||||
@ -121,44 +121,44 @@ x-i18n:
|
||||
你需要设置：
|
||||
|
||||
- 远程 Gateway 网关 URL（`ws://...`）
|
||||
- 如果远程 Gateway 网关需要凭证，则设置令牌（推荐）
|
||||
- 如果远程 Gateway 网关需要认证，则设置 token（推荐）
|
||||
|
||||
<Note>
|
||||
- 如果 Gateway 网关仅绑定到 loopback，请使用 SSH 隧道或 tailnet。
|
||||
- 发现提示：
|
||||
- 如果 Gateway 网关仅绑定 loopback，请使用 SSH 隧道或 tailnet。
|
||||
- 设备发现提示：
|
||||
- macOS：Bonjour（`dns-sd`）
|
||||
- Linux：Avahi（`avahi-browse`）
|
||||
</Note>
|
||||
|
||||
## 凭证和模型选项
|
||||
## 凭证与模型选项
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Anthropic API 密钥">
|
||||
如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示输入密钥，然后保存供守护进程使用。
|
||||
如果存在 `ANTHROPIC_API_KEY` 则使用它，否则提示输入密钥，然后将其保存以供守护进程使用。
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI Code 订阅（OAuth）">
|
||||
<Accordion title="OpenAI Code subscription（OAuth）">
|
||||
浏览器流程；粘贴 `code#state`。
|
||||
|
||||
当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
|
||||
当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.5`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI Code 订阅（设备配对）">
|
||||
浏览器配对流程，使用短时有效的设备代码。
|
||||
<Accordion title="OpenAI Code subscription（设备配对）">
|
||||
浏览器配对流程，使用短期有效的设备码。
|
||||
|
||||
当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.4`。
|
||||
当模型未设置或为 `openai/*` 时，将 `agents.defaults.model` 设置为 `openai-codex/gpt-5.5`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI API 密钥">
|
||||
如果存在 `OPENAI_API_KEY` 则使用它，否则提示输入密钥，然后将该凭证存储到凭证配置文件中。
|
||||
如果存在 `OPENAI_API_KEY` 则使用它，否则提示输入密钥，然后将凭证存储到凭证配置中。
|
||||
|
||||
当模型未设置、为 `openai/*` 或 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.4`。
|
||||
当模型未设置、为 `openai/*` 或为 `openai-codex/*` 时，将 `agents.defaults.model` 设置为 `openai/gpt-5.5`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="xAI（Grok）API 密钥">
|
||||
提示输入 `XAI_API_KEY`，并将 xAI 配置为模型提供商。
|
||||
</Accordion>
|
||||
<Accordion title="OpenCode">
|
||||
提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），并让你选择 Zen 或 Go 目录。
|
||||
提示输入 `OPENCODE_API_KEY`（或 `OPENCODE_ZEN_API_KEY`），并允许你选择 Zen 或 Go 目录。
|
||||
设置 URL：[opencode.ai/auth](https://opencode.ai/auth)。
|
||||
</Accordion>
|
||||
<Accordion title="API 密钥（通用）">
|
||||
@ -166,43 +166,43 @@ x-i18n:
|
||||
</Accordion>
|
||||
<Accordion title="Vercel AI Gateway">
|
||||
提示输入 `AI_GATEWAY_API_KEY`。
|
||||
更多详情见：[Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)。
|
||||
更多细节： [Vercel AI Gateway](/zh-CN/providers/vercel-ai-gateway)。
|
||||
</Accordion>
|
||||
<Accordion title="Cloudflare AI Gateway">
|
||||
提示输入账号 ID、Gateway 网关 ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
|
||||
更多详情见：[Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)。
|
||||
提示输入 account ID、gateway ID 和 `CLOUDFLARE_AI_GATEWAY_API_KEY`。
|
||||
更多细节： [Cloudflare AI Gateway](/zh-CN/providers/cloudflare-ai-gateway)。
|
||||
</Accordion>
|
||||
<Accordion title="MiniMax">
|
||||
配置会自动写入。托管默认值为 `MiniMax-M2.7`；API 密钥设置使用
|
||||
`minimax/...`，OAuth 设置使用 `minimax-portal/...`。
|
||||
更多详情见：[MiniMax](/zh-CN/providers/minimax)。
|
||||
更多细节： [MiniMax](/zh-CN/providers/minimax)。
|
||||
</Accordion>
|
||||
<Accordion title="StepFun">
|
||||
配置会针对中国或全球端点的 StepFun standard 或 Step Plan 自动写入。
|
||||
Standard 当前包括 `step-3.5-flash`，Step Plan 还包括 `step-3.5-flash-2603`。
|
||||
更多详情见：[StepFun](/zh-CN/providers/stepfun)。
|
||||
会为中国或全球端点上的 StepFun standard 或 Step Plan 自动写入配置。
|
||||
StepFun standard 当前包括 `step-3.5-flash`，Step Plan 还包括 `step-3.5-flash-2603`。
|
||||
更多细节： [StepFun](/zh-CN/providers/stepfun)。
|
||||
</Accordion>
|
||||
<Accordion title="Synthetic（兼容 Anthropic）">
|
||||
提示输入 `SYNTHETIC_API_KEY`。
|
||||
更多详情见：[Synthetic](/zh-CN/providers/synthetic)。
|
||||
更多细节： [Synthetic](/zh-CN/providers/synthetic)。
|
||||
</Accordion>
|
||||
<Accordion title="Ollama（云端和本地开放模型）">
|
||||
<Accordion title="Ollama（Cloud 和本地开放模型）">
|
||||
会先提示选择 `Cloud + Local`、`Cloud only` 或 `Local only`。
|
||||
`Cloud only` 使用 `OLLAMA_API_KEY` 和 `https://ollama.com`。
|
||||
基于主机的模式会提示输入基础 URL（默认 `http://127.0.0.1:11434`），发现可用模型，并建议默认值。
|
||||
`Cloud + Local` 还会检查该 Ollama 主机是否已登录以访问云端。
|
||||
更多详情见：[Ollama](/zh-CN/providers/ollama)。
|
||||
基于主机的模式会提示输入 base URL（默认 `http://127.0.0.1:11434`），发现可用模型，并给出默认建议。
|
||||
`Cloud + Local` 还会检查该 Ollama 主机是否已登录以获得 cloud 访问权限。
|
||||
更多细节： [Ollama](/zh-CN/providers/ollama)。
|
||||
</Accordion>
|
||||
<Accordion title="Moonshot 和 Kimi Coding">
|
||||
Moonshot（Kimi K2）和 Kimi Coding 配置会自动写入。
|
||||
更多详情见：[Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)。
|
||||
更多细节： [Moonshot AI（Kimi + Kimi Coding）](/zh-CN/providers/moonshot)。
|
||||
</Accordion>
|
||||
<Accordion title="自定义提供商">
|
||||
适用于兼容 OpenAI 和兼容 Anthropic 的端点。
|
||||
可用于兼容 OpenAI 和兼容 Anthropic 的端点。
|
||||
|
||||
交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储选项：
|
||||
- **立即粘贴 API 密钥**（明文）
|
||||
- **使用 secret reference**（环境变量引用或已配置的提供商引用，带预检校验）
|
||||
交互式新手引导支持与其他提供商 API 密钥流程相同的 API 密钥存储方式：
|
||||
- **现在粘贴 API 密钥**（明文）
|
||||
- **使用密钥引用**（环境变量引用或已配置提供商引用，带预检校验）
|
||||
|
||||
非交互式标志：
|
||||
- `--auth-choice custom-api-key`
|
||||
@ -221,47 +221,42 @@ x-i18n:
|
||||
模型行为：
|
||||
|
||||
- 从检测到的选项中选择默认模型，或手动输入提供商和模型。
|
||||
- 当新手引导从某个提供商凭证选项开始时，模型选择器会自动优先
|
||||
该提供商。对于 Volcengine 和 BytePlus，此优先级
|
||||
也会匹配它们的 coding-plan 变体（`volcengine-plan/*`、
|
||||
`byteplus-plan/*`）。
|
||||
- 如果该优先提供商过滤后为空，选择器会回退到
|
||||
完整目录，而不是显示没有模型。
|
||||
- 向导会运行模型检查，并在配置的模型未知或缺少凭证时发出警告。
|
||||
- 当新手引导从某个提供商凭证选项开始时，模型选择器会自动优先该提供商。对于 Volcengine 和 BytePlus，同样的偏好也会匹配它们的 coding-plan 变体（`volcengine-plan/*`、`byteplus-plan/*`）。
|
||||
- 如果这种按优先提供商过滤后会得到空结果，选择器会回退到完整目录，而不是显示无模型可选。
|
||||
- 向导会运行模型检查，并在已配置模型未知或缺少凭证时发出警告。
|
||||
|
||||
凭证和配置文件路径：
|
||||
凭证和配置路径：
|
||||
|
||||
- 凭证配置文件（API 密钥 + OAuth）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- 凭证配置（API 密钥 + OAuth）：`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`
|
||||
- 旧版 OAuth 导入：`~/.openclaw/credentials/oauth.json`
|
||||
|
||||
凭证存储模式：
|
||||
|
||||
- 默认新手引导行为会将 API 密钥作为明文值持久化到凭证配置文件中。
|
||||
- 默认新手引导行为会将 API 密钥以明文值形式持久化到凭证配置中。
|
||||
- `--secret-input-mode ref` 会启用引用模式，而不是明文密钥存储。
|
||||
在交互式设置中，你可以选择以下任一方式：
|
||||
在交互式设置中，你可以选择以下任一项：
|
||||
- 环境变量引用（例如 `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`）
|
||||
- 已配置的提供商引用（`file` 或 `exec`），包含提供商别名 + id
|
||||
- 交互式引用模式在保存前会执行快速预检校验。
|
||||
- 已配置提供商引用（`file` 或 `exec`），带提供商别名和 id
|
||||
- 交互式引用模式会在保存前执行快速预检校验。
|
||||
- 环境变量引用：校验变量名，以及当前新手引导环境中的非空值。
|
||||
- 提供商引用：校验提供商配置并解析请求的 id。
|
||||
- 如果预检失败，新手引导会显示错误并允许你重试。
|
||||
- 在非交互式模式下，`--secret-input-mode ref` 仅支持基于环境变量。
|
||||
- 在非交互式模式下，`--secret-input-mode ref` 仅支持基于环境变量的方式。
|
||||
- 在新手引导进程环境中设置提供商环境变量。
|
||||
- 内联密钥标志（例如 `--openai-api-key`）要求该环境变量已设置；否则新手引导会快速失败。
|
||||
- 内联密钥标志（例如 `--openai-api-key`）要求对应环境变量已设置；否则新手引导会快速失败。
|
||||
- 对于自定义提供商，非交互式 `ref` 模式会将 `models.providers.<id>.apiKey` 存储为 `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`。
|
||||
- 在该自定义提供商场景中，`--custom-api-key` 要求必须设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。
|
||||
- Gateway 网关凭证凭据在交互式设置中支持明文和 SecretRef 选项：
|
||||
- 令牌模式：**生成 / 存储明文令牌**（默认）或 **使用 SecretRef**。
|
||||
- 密码模式：明文或 SecretRef。
|
||||
- 非交互式令牌 SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
|
||||
- 现有的明文设置会继续保持不变并正常工作。
|
||||
- 在该自定义提供商场景中，`--custom-api-key` 要求已设置 `CUSTOM_API_KEY`；否则新手引导会快速失败。
|
||||
- Gateway 网关认证凭证在交互式设置中支持明文和 SecretRef 两种选择：
|
||||
- Token 模式：**生成/存储明文 token**（默认）或 **使用 SecretRef**。
|
||||
- Password 模式：明文或 SecretRef。
|
||||
- 非交互式 token SecretRef 路径：`--gateway-token-ref-env <ENV_VAR>`。
|
||||
- 现有的明文设置仍可继续正常使用。
|
||||
|
||||
<Note>
|
||||
无头环境和服务器提示：先在有浏览器的机器上完成 OAuth，然后复制
|
||||
该智能体的 `auth-profiles.json`（例如
|
||||
无头环境和服务器提示：请先在有浏览器的机器上完成 OAuth，然后将该智能体的 `auth-profiles.json`（例如
|
||||
`~/.openclaw/agents/<agentId>/agent/auth-profiles.json`，或对应的
|
||||
`$OPENCLAW_STATE_DIR/...` 路径）到 Gateway 网关主机。`credentials/oauth.json`
|
||||
仅是旧版导入来源。
|
||||
`$OPENCLAW_STATE_DIR/...` 路径）复制到 Gateway 网关主机。`credentials/oauth.json`
|
||||
仅作为旧版导入来源。
|
||||
</Note>
|
||||
|
||||
## 输出和内部机制
|
||||
@ -269,15 +264,15 @@ x-i18n:
|
||||
`~/.openclaw/openclaw.json` 中的典型字段：
|
||||
|
||||
- `agents.defaults.workspace`
|
||||
- `agents.defaults.model` / `models.providers`（如果选择了 MiniMax）
|
||||
- `agents.defaults.model` / `models.providers`（如果选择了 Minimax）
|
||||
- `tools.profile`（本地新手引导在未设置时默认使用 `"coding"`；现有显式值会被保留）
|
||||
- `gateway.*`（模式、绑定、凭证、Tailscale）
|
||||
- `session.dmScope`（本地新手引导在未设置时默认将其设为 `per-channel-peer`；现有显式值会被保留）
|
||||
- `gateway.*`（mode、bind、auth、Tailscale）
|
||||
- `session.dmScope`（本地新手引导在未设置时默认设为 `per-channel-peer`；现有显式值会被保留）
|
||||
- `channels.telegram.botToken`、`channels.discord.token`、`channels.matrix.*`、`channels.signal.*`、`channels.imessage.*`
|
||||
- 当你在提示中选择启用时的渠道 allowlist（Slack、Discord、Matrix、Microsoft Teams）（如果可能，名称会解析为 ID）
|
||||
- 在提示中选择启用时的渠道允许列表（Slack、Discord、Matrix、Microsoft Teams）（在可能时会将名称解析为 ID）
|
||||
- `skills.install.nodeManager`
|
||||
- `setup --node-manager` 标志接受 `npm`、`pnpm` 或 `bun`。
|
||||
- 稍后手动配置仍可将 `skills.install.nodeManager: "yarn"`` 设置为该值。
|
||||
- 后续手动配置仍可将 `skills.install.nodeManager: "yarn"` 设为 `"yarn"`。
|
||||
- `wizard.lastRunAt`
|
||||
- `wizard.lastRunVersion`
|
||||
- `wizard.lastRunCommit`
|
||||
@ -290,7 +285,7 @@ WhatsApp 凭证位于 `~/.openclaw/credentials/whatsapp/<accountId>/` 下。
|
||||
会话存储在 `~/.openclaw/agents/<agentId>/sessions/` 下。
|
||||
|
||||
<Note>
|
||||
某些渠道以插件形式提供。在设置期间选择它们时，向导会先提示你安装插件（npm 或本地路径），然后再进行渠道配置。
|
||||
某些渠道以插件形式提供。在设置过程中选择这些渠道时，向导会先提示安装插件（npm 或本地路径），然后再进行渠道配置。
|
||||
</Note>
|
||||
|
||||
Gateway 网关向导 RPC：
|
||||
@ -305,14 +300,14 @@ Gateway 网关向导 RPC：
|
||||
Signal 设置行为：
|
||||
|
||||
- 下载合适的发布资源
|
||||
- 将其存储在 `~/.openclaw/tools/signal-cli/<version>/` 下
|
||||
- 将其存储到 `~/.openclaw/tools/signal-cli/<version>/`
|
||||
- 在配置中写入 `channels.signal.cliPath`
|
||||
- JVM 构建需要 Java 21
|
||||
- 可用时会使用原生构建
|
||||
- Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 `signal-cli` 流程
|
||||
- 可用时优先使用原生构建
|
||||
- Windows 使用 WSL2，并在 WSL 内遵循 Linux 的 signal-cli 流程
|
||||
|
||||
## 相关文档
|
||||
|
||||
- 新手引导中心：[设置向导（CLI）](/start/wizard)
|
||||
- 自动化和脚本：[CLI 自动化](/start/wizard-cli-automation)
|
||||
- 命令参考：[`openclaw onboard`](/cli/onboard)
|
||||
- 新手引导中心：[设置向导（CLI）](/zh-CN/start/wizard)
|
||||
- 自动化与脚本：[CLI 自动化](/zh-CN/start/wizard-cli-automation)
|
||||
- 命令参考：[`openclaw onboard`](/zh-CN/cli/onboard)
|
||||
|
||||
@ -1,86 +1,88 @@
|
||||
---
|
||||
read_when:
|
||||
- 通过 ACP 运行编码 harness
|
||||
- 在消息渠道上设置绑定到对话的 ACP 会话
|
||||
- 将消息渠道中的对话绑定到持久化 ACP 会话
|
||||
- 在消息渠道上设置与会话绑定的 ACP 会话
|
||||
- 将消息渠道会话绑定到持久化 ACP 会话
|
||||
- 排查 ACP 后端和插件接线问题
|
||||
- 调试 ACP 完成结果投递或智能体到智能体循环问题
|
||||
- 调试 ACP 完成结果传递或智能体到智能体循环问题
|
||||
- 从聊天中操作 `/acp` 命令
|
||||
summary: 对 Codex、Claude Code、Cursor、Gemini CLI、OpenClaw ACP 和其他 harness 智能体使用 ACP 运行时会话
|
||||
title: ACP 智能体
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T16:17:19Z"
|
||||
generated_at: "2026-04-23T19:27:21Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 4a3205cf8d52564c4bf9b289e329de1c56743697d14fa22e2190946be54e4db4
|
||||
source_hash: 329e64aa98d722e649cd4f079a66d14f4f331de9994646539995d1b371bbacb3
|
||||
source_path: tools/acp-agents.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# ACP 智能体
|
||||
|
||||
[Agent Client Protocol (ACP)](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI 以及其他受支持的 ACPX harness）。
|
||||
[Agent Client Protocol（ACP）](https://agentclientprotocol.com/) 会话让 OpenClaw 能够通过 ACP 后端插件运行外部编码 harness（例如 Pi、Claude Code、Codex、Cursor、Copilot、OpenClaw ACP、OpenCode、Gemini CLI，以及其他受支持的 ACPX harness）。
|
||||
|
||||
如果你用自然语言要求 OpenClaw “在 Codex 中运行这个”或“在线程中启动 Claude Code”，OpenClaw 应该将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每次 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
|
||||
如果你用自然语言要求 OpenClaw “在 Codex 中运行这个” 或 “在线程里启动 Claude Code”，OpenClaw 应将该请求路由到 ACP 运行时（而不是原生子智能体运行时）。每次 ACP 会话启动都会被跟踪为一个[后台任务](/zh-CN/automation/tasks)。
|
||||
|
||||
如果你希望 Codex 或 Claude Code 作为外部 MCP 客户端直接连接到现有的 OpenClaw 渠道对话，请使用 [`openclaw mcp serve`](/zh-CN/cli/mcp)，而不是 ACP。
|
||||
如果你想让 Codex 或 Claude Code 作为外部 MCP 客户端直接连接
|
||||
到现有的 OpenClaw 渠道会话，请改用 [`openclaw mcp serve`](/zh-CN/cli/mcp)，
|
||||
而不是 ACP。
|
||||
|
||||
## 我该看哪个页面？
|
||||
## 我需要哪个页面？
|
||||
|
||||
这里有三个相近但很容易混淆的功能入口：
|
||||
这里附近有三个很容易混淆的界面：
|
||||
|
||||
| 你想要... | 使用这个 | 说明 |
|
||||
| 你想要…… | 使用这个 | 说明 |
|
||||
| ---------------------------------------------------------------------------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| 通过 OpenClaw 运行 Codex、Claude Code、Gemini CLI 或其他外部 harness | 本页：ACP 智能体 | 绑定聊天的会话、`/acp spawn`、`sessions_spawn({ runtime: "acp" })`、后台任务、运行时控制 |
|
||||
| 将一个 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE/客户端 通过 stdio/WebSocket 使用 ACP 与 OpenClaw 通信 |
|
||||
| 复用本地 AI CLI 作为纯文本回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、也没有 harness 运行时 |
|
||||
| 将一个 OpenClaw Gateway 网关会话作为 ACP 服务器暴露给编辑器或客户端 | [`openclaw acp`](/zh-CN/cli/acp) | 桥接模式。IDE / 客户端通过 stdio / WebSocket 向 OpenClaw 发送 ACP |
|
||||
| 将本地 AI CLI 复用为仅文本的回退模型 | [CLI 后端](/zh-CN/gateway/cli-backends) | 不是 ACP。没有 OpenClaw 工具、没有 ACP 控制、也没有 harness 运行时 |
|
||||
|
||||
## 这开箱即用吗？
|
||||
## 开箱即用吗？
|
||||
|
||||
通常可以。全新安装默认启用内置的 `acpx` 运行时插件，并附带一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时探测并自我修复。运行 `/acp doctor` 可执行就绪性检查。
|
||||
通常可以。全新安装默认启用内置的 `acpx` 运行时插件，并带有一个插件本地固定版本的 `acpx` 二进制文件，OpenClaw 会在启动时对其进行探测和自修复。运行 `/acp doctor` 可进行就绪检查。
|
||||
|
||||
首次运行的注意事项：
|
||||
|
||||
- 目标 harness 适配器（Codex、Claude 等）可能会在你首次使用时通过 `npx` 按需获取。
|
||||
- 该 harness 所需的厂商认证仍然必须已存在于主机上。
|
||||
- 如果主机没有 npm 或没有网络访问能力，则首次运行时的适配器获取会失败，直到缓存被预热或适配器通过其他方式安装。
|
||||
- 目标 harness 适配器（Codex、Claude 等）在你首次使用时，可能会通过 `npx` 按需获取。
|
||||
- 该 harness 对应的厂商认证信息仍然必须存在于主机上。
|
||||
- 如果主机没有 npm 或网络访问能力，那么首次运行的适配器获取会失败，直到缓存预热完成或通过其他方式安装适配器。
|
||||
|
||||
## 操作手册
|
||||
## 运维操作手册
|
||||
|
||||
在聊天中使用 `/acp` 的快速流程：
|
||||
|
||||
1. **启动** — `/acp spawn codex --bind here` 或 `/acp spawn codex --mode persistent --thread auto`
|
||||
2. 在绑定的对话或线程中**工作**（或者显式指定会话键）。
|
||||
3. **检查状态** — `/acp status`
|
||||
4. **调整** — `/acp model <provider/model>`、`/acp permissions <profile>`、`/acp timeout <seconds>`
|
||||
5. **引导**而不替换上下文 — `/acp steer tighten logging and continue`
|
||||
6. **停止** — `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定）
|
||||
1. **启动** —— `/acp spawn codex --bind here` 或 `/acp spawn codex --mode persistent --thread auto`
|
||||
2. 在绑定的会话或线程中**工作**（或者显式指定会话键）。
|
||||
3. **检查状态** —— `/acp status`
|
||||
4. **调优** —— `/acp model <provider/model>`、`/acp permissions <profile>`、`/acp timeout <seconds>`
|
||||
5. 在不替换上下文的情况下**引导** —— `/acp steer tighten logging and continue`
|
||||
6. **停止** —— `/acp cancel`（当前轮次）或 `/acp close`（会话 + 绑定）
|
||||
|
||||
应当路由到 ACP 运行时的自然语言触发示例：
|
||||
应路由到 ACP 运行时的自然语言触发方式：
|
||||
|
||||
- “把这个 Discord 渠道绑定到 Codex。”
|
||||
- “在这里的一个线程中启动持久化的 Codex 会话。”
|
||||
- “把这个作为一次性的 Claude Code ACP 会话运行，并总结结果。”
|
||||
- “对此任务使用 Gemini CLI 并放在线程里，然后后续继续在同一个线程中进行。”
|
||||
- “把这个 Discord 频道绑定到 Codex。”
|
||||
- “在这里的线程里启动一个持久的 Codex 会话。”
|
||||
- “把这个作为一次性 Claude Code ACP 会话运行，并总结结果。”
|
||||
- “在线程里用 Gemini CLI 处理这个任务，然后把后续跟进继续保留在同一个线程里。”
|
||||
|
||||
OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持时绑定到当前对话或线程，并将后续消息路由到该会话，直到关闭或过期。
|
||||
OpenClaw 会选择 `runtime: "acp"`，解析 harness `agentId`，在支持时绑定到当前会话或线程，并在关闭 / 过期之前将后续消息路由到该会话。
|
||||
|
||||
## ACP 与子智能体的区别
|
||||
## ACP 与子智能体
|
||||
|
||||
当你想使用外部 harness 运行时时，请使用 ACP。想使用 OpenClaw 原生委派运行时，则使用子智能体。
|
||||
当你想使用外部 harness 运行时时，请使用 ACP。当你想使用 OpenClaw 原生委派运行时，请使用子智能体。
|
||||
|
||||
| 区域 | ACP 会话 | 子智能体运行 |
|
||||
| ------------- | ------------------------------------- | ---------------------------------- |
|
||||
| 运行时 | ACP 后端插件（例如 acpx） | OpenClaw 原生子智能体运行时 |
|
||||
| 会话键 | `agent:<agentId>:acp:<uuid>` | `agent:<agentId>:subagent:<uuid>` |
|
||||
| 主要命令 | `/acp ...` | `/subagents ...` |
|
||||
| 启动工具 | `sessions_spawn` 且 `runtime:"acp"` | `sessions_spawn`（默认运行时） |
|
||||
| 启动工具 | `sessions_spawn` 且使用 `runtime:"acp"` | `sessions_spawn`（默认运行时） |
|
||||
|
||||
另请参见[子智能体](/zh-CN/tools/subagents)。
|
||||
另请参见 [子智能体](/zh-CN/tools/subagents)。
|
||||
|
||||
## ACP 如何运行 Claude Code
|
||||
|
||||
通过 ACP 运行 Claude Code 时，调用栈如下：
|
||||
对于通过 ACP 运行的 Claude Code，其栈如下：
|
||||
|
||||
1. OpenClaw ACP 会话控制平面
|
||||
2. 内置的 `acpx` 运行时插件
|
||||
@ -89,56 +91,56 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持
|
||||
|
||||
重要区别：
|
||||
|
||||
- ACP Claude 是一个 harness 会话，带有 ACP 控制、会话恢复、后台任务跟踪，以及可选的对话 / 线程绑定。
|
||||
- CLI 后端是独立的纯文本本地回退运行时。参见 [CLI 后端](/zh-CN/gateway/cli-backends)。
|
||||
- ACP Claude 是一个 harness 会话，具备 ACP 控制、会话恢复、后台任务跟踪以及可选的会话 / 线程绑定。
|
||||
- CLI 后端是单独的、仅文本的本地回退运行时。参见 [CLI 后端](/zh-CN/gateway/cli-backends)。
|
||||
|
||||
对操作人员来说，实用规则是：
|
||||
对运维人员来说，实用规则是：
|
||||
|
||||
- 想要 `/acp spawn`、可绑定会话、运行时控制或持久化 harness 工作：使用 ACP
|
||||
- 想通过原始 CLI 获得简单的本地文本回退：使用 CLI 后端
|
||||
- 想要通过原始 CLI 获得简单的本地文本回退：使用 CLI 后端
|
||||
|
||||
## 绑定会话
|
||||
|
||||
### 绑定当前对话
|
||||
### 当前会话绑定
|
||||
|
||||
`/acp spawn <harness> --bind here` 会将当前对话固定绑定到已启动的 ACP 会话——不会创建子线程，仍在同一聊天界面。OpenClaw 继续负责传输、认证、安全与投递；该对话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原位置重置该会话；`/acp close` 会移除该绑定。
|
||||
`/acp spawn <harness> --bind here` 会将当前会话固定到启动的 ACP 会话 —— 不创建子线程，保持在同一聊天界面。OpenClaw 仍然负责传输、认证、安全和投递；该会话中的后续消息会路由到同一个会话；`/new` 和 `/reset` 会在原地重置该会话；`/acp close` 会移除该绑定。
|
||||
|
||||
理解模型：
|
||||
心智模型：
|
||||
|
||||
- **聊天界面** —— 人们持续对话的地方（Discord 渠道、Telegram 话题、iMessage 聊天）。
|
||||
- **聊天界面** —— 人们持续对话的地方（Discord 频道、Telegram 话题、iMessage 聊天）。
|
||||
- **ACP 会话** —— OpenClaw 路由到的持久化 Codex / Claude / Gemini 运行时状态。
|
||||
- **子线程 / 话题** —— 仅在使用 `--thread ...` 时创建的可选额外消息界面。
|
||||
- **运行时工作区** —— harness 运行所在的文件系统位置（`cwd`、repo 检出目录、后端工作区）。它独立于聊天界面。
|
||||
- **子线程 / 话题** —— 仅由 `--thread ...` 创建的可选额外消息界面。
|
||||
- **运行时工作区** —— harness 运行所在的文件系统位置（`cwd`、仓库 checkout、后端工作区）。它独立于聊天界面。
|
||||
|
||||
示例：
|
||||
|
||||
- `/acp spawn codex --bind here` — 保持当前聊天，启动或连接 Codex，并将后续消息路由到这里。
|
||||
- `/acp spawn codex --thread auto` — OpenClaw 可以创建一个子线程 / 话题并绑定到那里。
|
||||
- `/acp spawn codex --bind here --cwd /workspace/repo` — 仍然绑定当前聊天，但 Codex 在 `/workspace/repo` 中运行。
|
||||
- `/acp spawn codex --bind here` —— 保持当前聊天，启动或附加 Codex，并将未来消息路由到这里。
|
||||
- `/acp spawn codex --thread auto` —— OpenClaw 可能会创建一个子线程 / 话题并在那里绑定。
|
||||
- `/acp spawn codex --bind here --cwd /workspace/repo` —— 同样绑定当前聊天，Codex 在 `/workspace/repo` 中运行。
|
||||
|
||||
说明：
|
||||
|
||||
- `--bind here` 和 `--thread ...` 互斥。
|
||||
- `--bind here` 仅适用于声明支持当前对话绑定的渠道；否则 OpenClaw 会返回明确的不支持提示。绑定会在 Gateway 网关重启后继续保留。
|
||||
- 在 Discord 上，仅当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions`；`--bind here` 不需要。
|
||||
- 如果你启动到另一个 ACP 智能体且未指定 `--cwd`，OpenClaw 默认继承**目标智能体的**工作区。若继承路径不存在（`ENOENT`/`ENOTDIR`），则回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接显示。
|
||||
- `--bind here` 仅适用于声明支持当前会话绑定的渠道；否则 OpenClaw 会返回清晰的不支持提示。绑定会跨 Gateway 网关重启持久化。
|
||||
- 在 Discord 上，仅当 OpenClaw 需要为 `--thread auto|here` 创建子线程时，才需要 `spawnAcpSessions` —— `--bind here` 不需要。
|
||||
- 如果你在未指定 `--cwd` 的情况下启动到不同的 ACP 智能体，OpenClaw 默认会继承**目标智能体的**工作区。缺失的继承路径（`ENOENT` / `ENOTDIR`）会回退到后端默认值；其他访问错误（例如 `EACCES`）会作为启动错误直接显示。
|
||||
|
||||
### 绑定到线程的会话
|
||||
### 线程绑定会话
|
||||
|
||||
当某个渠道适配器启用了线程绑定时，ACP 会话可以绑定到线程：
|
||||
|
||||
- OpenClaw 将线程绑定到目标 ACP 会话。
|
||||
- 该线程中的后续消息会路由到已绑定的 ACP 会话。
|
||||
- ACP 输出会投递回同一个线程。
|
||||
- 失焦 / 关闭 / 归档 / 空闲超时或最大存活时间到期时，该绑定会被移除。
|
||||
- 该线程中的后续消息会路由到绑定的 ACP 会话。
|
||||
- ACP 输出会回传到同一个线程。
|
||||
- 失焦 / 关闭 / 归档 / 空闲超时或最大存活时间到期时，会移除绑定。
|
||||
|
||||
线程绑定支持取决于适配器。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回明确的不支持 / 不可用提示。
|
||||
线程绑定支持取决于适配器。如果当前渠道适配器不支持线程绑定，OpenClaw 会返回清晰的不支持 / 不可用消息。
|
||||
|
||||
线程绑定 ACP 所需的功能标志：
|
||||
线程绑定 ACP 所需的功能开关：
|
||||
|
||||
- `acp.enabled=true`
|
||||
- `acp.dispatch.enabled` 默认开启（设为 `false` 可暂停 ACP 分发）
|
||||
- 渠道适配器的 ACP 线程启动标志已启用（适配器特定）
|
||||
- 已启用渠道适配器 ACP 线程启动开关（适配器特定）
|
||||
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
@ -146,23 +148,23 @@ OpenClaw 会选择 `runtime: "acp"`，解析 harness 的 `agentId`，在支持
|
||||
|
||||
- 任何暴露会话 / 线程绑定能力的渠道适配器。
|
||||
- 当前内置支持：
|
||||
- Discord 线程 / 渠道
|
||||
- Telegram 话题（群组 / 超级群组中的 forum topics，以及私信话题）
|
||||
- 渠道插件也可以通过相同的绑定接口添加支持。
|
||||
- Discord 线程 / 频道
|
||||
- Telegram 话题（群组 / 超级群组中的论坛话题，以及私信话题）
|
||||
- 插件渠道也可以通过相同的绑定接口添加支持。
|
||||
|
||||
## 渠道特定设置
|
||||
|
||||
对于非临时工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。
|
||||
对于非临时性工作流，请在顶层 `bindings[]` 条目中配置持久化 ACP 绑定。
|
||||
|
||||
### 绑定模型
|
||||
|
||||
- `bindings[].type="acp"` 表示持久化 ACP 对话绑定。
|
||||
- `bindings[].match` 用于标识目标对话：
|
||||
- Discord 渠道或线程：`match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- Telegram forum topic：`match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- BlueBubbles 私信 / 群聊：`match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
- `bindings[].type="acp"` 表示一个持久化 ACP 会话绑定。
|
||||
- `bindings[].match` 标识目标会话：
|
||||
- Discord 频道或线程：`match.channel="discord"` + `match.peer.id="<channelOrThreadId>"`
|
||||
- Telegram 论坛话题：`match.channel="telegram"` + `match.peer.id="<chatId>:topic:<topicId>"`
|
||||
- BlueBubbles 私信 / 群聊：`match.channel="bluebubbles"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
对于稳定的群组绑定，优先使用 `chat_id:*` 或 `chat_identifier:*`。
|
||||
- iMessage 私信 / 群聊：`match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
- iMessage 私信 / 群聊：`match.channel="imessage"` + `match.peer.id="<handle|chat_id:*|chat_guid:*|chat_identifier:*>"`
|
||||
对于稳定的群组绑定，优先使用 `chat_id:*`。
|
||||
- `bindings[].agentId` 是所属的 OpenClaw 智能体 id。
|
||||
- 可选的 ACP 覆盖项位于 `bindings[].acp` 下：
|
||||
@ -267,24 +269,24 @@ ACP 绑定会话的覆盖优先级：
|
||||
}
|
||||
```
|
||||
|
||||
行为如下：
|
||||
行为：
|
||||
|
||||
- OpenClaw 会在使用前确保配置的 ACP 会话已存在。
|
||||
- 该渠道或话题中的消息会路由到配置好的 ACP 会话。
|
||||
- 在已绑定的对话中，`/new` 和 `/reset` 会在原位置重置同一个 ACP 会话键。
|
||||
- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍然适用。
|
||||
- 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置中继承目标智能体的工作区。
|
||||
- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败会作为启动错误直接显示。
|
||||
- OpenClaw 会在使用前确保已配置的 ACP 会话存在。
|
||||
- 该频道或话题中的消息会路由到已配置的 ACP 会话。
|
||||
- 在已绑定的会话中，`/new` 和 `/reset` 会在原地重置同一个 ACP 会话键。
|
||||
- 临时运行时绑定（例如由线程聚焦流程创建的绑定）在存在时仍会生效。
|
||||
- 对于未显式指定 `cwd` 的跨智能体 ACP 启动，OpenClaw 会从智能体配置继承目标智能体工作区。
|
||||
- 缺失的继承工作区路径会回退到后端默认 `cwd`；非缺失类访问失败会作为启动错误显示。
|
||||
|
||||
## 启动 ACP 会话（接口）
|
||||
|
||||
### 从 `sessions_spawn`
|
||||
### 从 `sessions_spawn` 启动
|
||||
|
||||
使用 `runtime: "acp"` 从智能体轮次或工具调用中启动 ACP 会话。
|
||||
使用 `runtime: "acp"` 可从智能体轮次或工具调用中启动 ACP 会话。
|
||||
|
||||
```json
|
||||
{
|
||||
"task": "打开这个仓库并总结失败的测试",
|
||||
"task": "打开仓库并总结失败的测试",
|
||||
"runtime": "acp",
|
||||
"agentId": "codex",
|
||||
"thread": true,
|
||||
@ -294,9 +296,9 @@ ACP 绑定会话的覆盖优先级：
|
||||
|
||||
说明：
|
||||
|
||||
- `runtime` 默认是 `subagent`，因此对于 ACP 会话，要显式设置 `runtime: "acp"`。
|
||||
- 如果省略 `agentId`，则在已配置时，OpenClaw 会使用 `acp.defaultAgent`。
|
||||
- `mode: "session"` 需要 `thread: true`，以保持持久化的绑定对话。
|
||||
- `runtime` 默认为 `subagent`，因此对于 ACP 会话，请显式设置 `runtime: "acp"`。
|
||||
- 如果省略 `agentId`，OpenClaw 会在已配置时使用 `acp.defaultAgent`。
|
||||
- `mode: "session"` 需要 `thread: true`，以保持一个持久绑定的会话。
|
||||
|
||||
接口详情：
|
||||
|
||||
@ -304,62 +306,62 @@ ACP 绑定会话的覆盖优先级：
|
||||
- `runtime`（ACP 必填）：必须为 `"acp"`。
|
||||
- `agentId`（可选）：ACP 目标 harness id。如果已设置，则回退到 `acp.defaultAgent`。
|
||||
- `thread`（可选，默认 `false`）：在支持时请求线程绑定流程。
|
||||
- `mode`（可选）：`run`（一次性）或 `session`（持久化）。
|
||||
- 默认是 `run`
|
||||
- 如果 `thread: true` 且省略 `mode`，OpenClaw 可能会根据运行时路径默认使用持久化行为
|
||||
- `mode`（可选）：`run`（一次性）或 `session`（持久）。
|
||||
- 默认为 `run`
|
||||
- 如果 `thread: true` 且省略 mode，OpenClaw 可能会根据运行时路径默认采用持久行为
|
||||
- `mode: "session"` 需要 `thread: true`
|
||||
- `cwd`（可选）：请求的运行时工作目录（由后端 / 运行时策略验证）。如果省略，则在已配置时，ACP 启动会继承目标智能体的工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会被返回。
|
||||
- `label`（可选）：面向操作人员的标签，用于会话 / 横幅文本。
|
||||
- `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其对话历史。需要 `runtime: "acp"`。
|
||||
- `streamTo`（可选）：`"parent"` 将初始 ACP 运行的进度摘要以系统事件形式流式回传到请求方会话。
|
||||
- 在可用时，接受的响应中会包含 `streamLogPath`，指向一个按会话划分的 JSONL 日志（`<sessionId>.acp-stream.jsonl`），你可以对其执行 tail 以查看完整的转发历史。
|
||||
- `model`（可选）：为 ACP 子会话显式覆盖模型。对于 `runtime: "acp"`，该值会生效，因此子会话会使用请求的模型，而不是静默回退到目标智能体的默认模型。
|
||||
- `cwd`（可选）：请求的运行时工作目录（由后端 / 运行时策略验证）。若省略，在已配置时，ACP 启动会继承目标智能体的工作区；缺失的继承路径会回退到后端默认值，而真实的访问错误会直接返回。
|
||||
- `label`（可选）：用于会话 / 横幅文本中的面向运维者标签。
|
||||
- `resumeSessionId`（可选）：恢复现有 ACP 会话，而不是创建新会话。智能体会通过 `session/load` 重放其会话历史。需要 `runtime: "acp"`。
|
||||
- `streamTo`（可选）：`"parent"` 会将初始 ACP 运行进度摘要作为系统事件流回请求方会话。
|
||||
- 当可用时，接受的响应会包含指向会话范围 JSONL 日志（`<sessionId>.acp-stream.jsonl`）的 `streamLogPath`，你可以对其执行 tail 以查看完整转发历史。
|
||||
- `model`（可选）：ACP 子会话的显式模型覆盖。对于 `runtime: "acp"` 会生效，因此子会话会使用所请求的模型，而不是静默回退到目标智能体默认值。
|
||||
|
||||
## 投递模型
|
||||
## 传递模型
|
||||
|
||||
ACP 会话既可以是交互式工作区，也可以是由父级持有的后台工作。投递路径取决于其形态。
|
||||
ACP 会话既可以是交互式工作区，也可以是父级拥有的后台工作。传递路径取决于其形态。
|
||||
|
||||
### 交互式 ACP 会话
|
||||
|
||||
交互式会话用于在可见的聊天界面中持续对话：
|
||||
|
||||
- `/acp spawn ... --bind here` 将当前对话绑定到 ACP 会话。
|
||||
- `/acp spawn ... --thread ...` 将一个渠道线程 / 话题绑定到 ACP 会话。
|
||||
- 持久化配置的 `bindings[].type="acp"` 会将匹配的对话路由到同一个 ACP 会话。
|
||||
- `/acp spawn ... --bind here` 将当前会话绑定到 ACP 会话。
|
||||
- `/acp spawn ... --thread ...` 将渠道线程 / 话题绑定到 ACP 会话。
|
||||
- 持久化配置的 `bindings[].type="acp"` 会将匹配的会话路由到同一个 ACP 会话。
|
||||
|
||||
已绑定对话中的后续消息会直接路由到 ACP 会话，ACP 输出也会回传到同一个渠道 / 线程 / 话题。
|
||||
绑定会话中的后续消息会直接路由到 ACP 会话，ACP 输出也会回传到同一个渠道 / 线程 / 话题。
|
||||
|
||||
### 父级持有的一次性 ACP 会话
|
||||
### 父级拥有的一次性 ACP 会话
|
||||
|
||||
由另一个智能体运行启动的一次性 ACP 会话是后台子级，类似于子智能体：
|
||||
由另一个智能体运行启动的一次性 ACP 会话属于后台子任务，类似子智能体：
|
||||
|
||||
- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求执行工作。
|
||||
- 子级在自己的 ACP harness 会话中运行。
|
||||
- 完成结果通过内部任务完成通知路径回传。
|
||||
- 在需要面向用户的回复时，父级会以正常助手口吻改写子级结果。
|
||||
- 父级通过 `sessions_spawn({ runtime: "acp", mode: "run" })` 请求工作。
|
||||
- 子级在其自己的 ACP harness 会话中运行。
|
||||
- 完成后通过内部任务完成通知路径回报。
|
||||
- 当需要面向用户的回复时，父级会用正常的助手口吻改写子级结果。
|
||||
|
||||
不要将这一路径视为父级和子级之间的点对点聊天。子级已经有一个回传给父级的完成通道。
|
||||
不要将这条路径视为父级与子级之间的点对点聊天。子级已经有一个回传给父级的完成通道。
|
||||
|
||||
### `sessions_send` 与 A2A 投递
|
||||
### `sessions_send` 与 A2A 传递
|
||||
|
||||
`sessions_send` 可以在启动后以另一个会话为目标。对于普通对等会话，在注入消息后，OpenClaw 会使用智能体到智能体（A2A）后续路径：
|
||||
`session_spawn` 之后，`sessions_send` 可以将目标指向另一个会话。对于普通对等会话，在注入消息后，OpenClaw 会使用智能体到智能体（A2A）的后续路径：
|
||||
|
||||
- 等待目标会话的回复
|
||||
- 可选地让请求方和目标交换有限轮次的后续消息
|
||||
- 要求目标生成一条 announce 消息
|
||||
- 将该 announce 投递到可见的渠道或线程
|
||||
- 可选地让请求方与目标交换有限轮数的后续消息
|
||||
- 要求目标生成一条通知消息
|
||||
- 将该通知投递到可见渠道或线程
|
||||
|
||||
这条 A2A 路径是对等发送场景下的一种回退机制，用于发送方需要可见后续响应的情况。当某个无关会话在广泛的 `tools.sessions.visibility` 设置下能够查看并向 ACP 目标发送消息时，该机制仍会保持启用。
|
||||
对于发送方需要一个可见后续回复的对等发送，这条 A2A 路径是一种回退机制。当一个无关会话能够看到并向 ACP 目标发消息时，它仍然保持启用，例如在较宽泛的 `tools.sessions.visibility` 设置下。
|
||||
|
||||
只有当请求方是其自身所拥有的、由父级持有的一次性 ACP 子级的父级时，OpenClaw 才会跳过 A2A 后续处理。在这种情况下，如果在任务完成机制之上再运行 A2A，可能会用子级结果唤醒父级，再把父级的回复转发回子级，从而形成父 / 子回声循环。对于这种自有子级情况，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为结果已由完成路径负责处理。
|
||||
仅当请求方是其自身“父级拥有的一次性 ACP 子级”的父级时，OpenClaw 才会跳过 A2A 后续流程。在这种情况下，如果在任务完成之上再运行 A2A，可能会在子级结果到达时唤醒父级，再把父级的回复转发回子级，从而形成父 / 子回声循环。对于这种“自有子级”场景，`sessions_send` 结果会报告 `delivery.status="skipped"`，因为完成路径已经负责处理结果。
|
||||
|
||||
### 恢复现有会话
|
||||
|
||||
使用 `resumeSessionId` 可继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其对话历史，因此能带着之前的完整上下文继续进行。
|
||||
使用 `resumeSessionId` 可继续之前的 ACP 会话，而不是重新开始。智能体会通过 `session/load` 重放其会话历史，因此能够在完整保留先前上下文的基础上继续。
|
||||
|
||||
```json
|
||||
{
|
||||
"task": "从我们上次停下的地方继续——修复剩余的测试失败",
|
||||
"task": "从我们上次停下的地方继续 —— 修复剩余的测试失败",
|
||||
"runtime": "acp",
|
||||
"agentId": "codex",
|
||||
"resumeSessionId": "<previous-session-id>"
|
||||
@ -368,47 +370,47 @@ ACP 会话既可以是交互式工作区，也可以是由父级持有的后台
|
||||
|
||||
常见用例：
|
||||
|
||||
- 将一个 Codex 会话从你的笔记本交接到手机——告诉你的智能体从你上次停下的地方继续
|
||||
- 继续你之前在 CLI 中以交互方式启动、现在要通过智能体无头继续的编码会话
|
||||
- 接续因 Gateway 网关重启或空闲超时而中断的工作
|
||||
- 将 Codex 会话从你的笔记本电脑移交到手机 —— 告诉你的智能体从你上次停下的地方继续
|
||||
- 继续一个你最初在 CLI 中交互式启动、现在想通过智能体无头继续的编码会话
|
||||
- 继续因 Gateway 网关重启或空闲超时而中断的工作
|
||||
|
||||
说明：
|
||||
|
||||
- `resumeSessionId` 需要 `runtime: "acp"`——如果与子智能体运行时一起使用，会返回错误。
|
||||
- `resumeSessionId` 会恢复上游 ACP 对话历史；`thread` 和 `mode` 仍然会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然要求 `thread: true`。
|
||||
- `resumeSessionId` 需要 `runtime: "acp"` —— 如果与子智能体运行时一起使用，会返回错误。
|
||||
- `resumeSessionId` 会恢复上游 ACP 会话历史；`thread` 和 `mode` 仍会正常应用于你正在创建的新 OpenClaw 会话，因此 `mode: "session"` 仍然需要 `thread: true`。
|
||||
- 目标智能体必须支持 `session/load`（Codex 和 Claude Code 支持）。
|
||||
- 如果找不到该会话 ID，启动将以明确错误失败——不会静默回退到新会话。
|
||||
- 如果找不到该会话 id，则启动会以清晰错误失败 —— 不会静默回退到新会话。
|
||||
|
||||
<Accordion title="部署后的冒烟测试">
|
||||
<Accordion title="部署后冒烟测试">
|
||||
|
||||
Gateway 网关部署后，应运行一次实时端到端检查，而不是只依赖单元测试：
|
||||
在 Gateway 网关部署后，请运行一次真实的端到端检查，而不是只依赖单元测试：
|
||||
|
||||
1. 验证目标主机上的已部署 Gateway 网关版本和提交。
|
||||
2. 打开一个指向实时智能体的临时 ACPX 桥接会话。
|
||||
3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，任务为 `Reply with exactly LIVE-ACP-SPAWN-OK`。
|
||||
4. 验证 `accepted=yes`、真实的 `childSessionKey`，且没有验证器错误。
|
||||
1. 在目标主机上验证已部署的 Gateway 网关版本和提交。
|
||||
2. 打开一个到实时智能体的临时 ACPX 桥接会话。
|
||||
3. 要求该智能体调用 `sessions_spawn`，并设置 `runtime: "acp"`、`agentId: "codex"`、`mode: "run"`，以及任务 `Reply with exactly LIVE-ACP-SPAWN-OK`。
|
||||
4. 验证 `accepted=yes`、存在真实的 `childSessionKey`，且没有验证器错误。
|
||||
5. 清理该临时桥接会话。
|
||||
|
||||
请将检查门槛保持在 `mode: "run"`，并跳过 `streamTo: "parent"`——绑定线程的 `mode: "session"` 和流式转发路径属于另外的、更丰富的集成验证。
|
||||
保持 gate 使用 `mode: "run"`，并跳过 `streamTo: "parent"` —— 线程绑定的 `mode: "session"` 和流转发路径属于另外更丰富的集成验证流程。
|
||||
|
||||
</Accordion>
|
||||
|
||||
## 沙箱兼容性
|
||||
|
||||
ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运行。
|
||||
ACP 会话当前运行在主机运行时上，而不是 OpenClaw 沙箱中。
|
||||
|
||||
当前限制：
|
||||
|
||||
- 如果请求方会话处于沙箱中，则 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn` 的 ACP 启动都会被阻止。
|
||||
- 如果请求方会话处于沙箱中，则对于 `sessions_spawn({ runtime: "acp" })` 和 `/acp spawn`，ACP 启动都会被阻止。
|
||||
- 错误：`Sandboxed sessions cannot spawn ACP sessions because runtime="acp" runs on the host. Use runtime="subagent" from sandboxed sessions.`
|
||||
- 带有 `runtime: "acp"` 的 `sessions_spawn` 不支持 `sandbox: "require"`。
|
||||
- 错误：`sessions_spawn sandbox="require" is unsupported for runtime="acp" because ACP sessions run outside the sandbox. Use runtime="subagent" or sandbox="inherit".`
|
||||
|
||||
当你需要由沙箱强制执行的运行时，请使用 `runtime: "subagent"`。
|
||||
当你需要由沙箱强制执行的运行环境时，请使用 `runtime: "subagent"`。
|
||||
|
||||
### 从 `/acp` 命令
|
||||
### 从 `/acp` 命令启动
|
||||
|
||||
在需要时，使用 `/acp spawn` 从聊天中进行显式的操作控制。
|
||||
在需要时，使用 `/acp spawn` 可从聊天中进行显式运维控制。
|
||||
|
||||
```text
|
||||
/acp spawn codex --mode persistent --thread auto
|
||||
@ -417,7 +419,7 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运
|
||||
/acp spawn codex --thread here
|
||||
```
|
||||
|
||||
关键标志：
|
||||
关键 flag：
|
||||
|
||||
- `--mode persistent|oneshot`
|
||||
- `--bind here|off`
|
||||
@ -425,24 +427,24 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运
|
||||
- `--cwd <absolute-path>`
|
||||
- `--label <name>`
|
||||
|
||||
参见[斜杠命令](/zh-CN/tools/slash-commands)。
|
||||
参见 [斜杠命令](/zh-CN/tools/slash-commands)。
|
||||
|
||||
## 会话目标解析
|
||||
|
||||
大多数 `/acp` 操作都接受可选的会话目标（`session-key`、`session-id` 或 `session-label`）。
|
||||
大多数 `/acp` 操作都接受一个可选的会话目标（`session-key`、`session-id` 或 `session-label`）。
|
||||
|
||||
解析顺序：
|
||||
|
||||
1. 显式目标参数（或 `/acp steer` 的 `--session`）
|
||||
- 先尝试键
|
||||
- 然后尝试 UUID 形式的会话 id
|
||||
- 最后尝试标签
|
||||
2. 当前线程绑定（如果此对话 / 线程绑定到了 ACP 会话）
|
||||
- 先尝试 key
|
||||
- 然后尝试 UUID 形式的 session id
|
||||
- 最后尝试 label
|
||||
2. 当前线程绑定（如果此会话 / 线程已绑定到某个 ACP 会话）
|
||||
3. 当前请求方会话回退
|
||||
|
||||
当前对话绑定和线程绑定都会参与第 2 步。
|
||||
当前会话绑定和线程绑定都会参与第 2 步。
|
||||
|
||||
如果无法解析出目标，OpenClaw 会返回明确错误（`Unable to resolve session target: ...`）。
|
||||
如果无法解析出目标，OpenClaw 会返回清晰错误（`Unable to resolve session target: ...`）。
|
||||
|
||||
## 启动绑定模式
|
||||
|
||||
@ -450,15 +452,15 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运
|
||||
|
||||
| 模式 | 行为 |
|
||||
| ------ | ---------------------------------------------------------------------- |
|
||||
| `here` | 在原位置绑定当前活动对话；如果没有活动对话则失败。 |
|
||||
| `off` | 不创建当前对话绑定。 |
|
||||
| `here` | 在原地绑定当前活动会话；如果当前没有活动会话则失败。 |
|
||||
| `off` | 不创建当前会话绑定。 |
|
||||
|
||||
说明：
|
||||
|
||||
- `--bind here` 是“让这个渠道或聊天由 Codex 驱动”的最简单操作路径。
|
||||
- `--bind here` 是“让这个频道或聊天由 Codex 支持”的最简单运维路径。
|
||||
- `--bind here` 不会创建子线程。
|
||||
- `--bind here` 仅适用于暴露当前对话绑定支持的渠道。
|
||||
- `--bind` 和 `--thread` 不能在同一个 `/acp spawn` 调用中组合使用。
|
||||
- `--bind here` 仅在暴露当前会话绑定支持的渠道上可用。
|
||||
- `--bind` 和 `--thread` 不能在同一次 `/acp spawn` 调用中同时使用。
|
||||
|
||||
## 启动线程模式
|
||||
|
||||
@ -466,57 +468,57 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运
|
||||
|
||||
| 模式 | 行为 |
|
||||
| ------ | --------------------------------------------------------------------------------------------------- |
|
||||
| `auto` | 如果当前在活动线程中：绑定该线程。如果当前不在线程中：在支持时创建 / 绑定一个子线程。 |
|
||||
| `auto` | 若当前在活动线程中：绑定该线程。若不在线程中：在支持时创建 / 绑定一个子线程。 |
|
||||
| `here` | 要求当前必须处于活动线程中；否则失败。 |
|
||||
| `off` | 不绑定。会话以未绑定状态启动。 |
|
||||
|
||||
说明：
|
||||
|
||||
- 在不支持线程绑定的界面上，默认行为实际上等同于 `off`。
|
||||
- 绑定线程的启动需要渠道策略支持：
|
||||
- 线程绑定启动需要渠道策略支持：
|
||||
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
- Telegram：`channels.telegram.threadBindings.spawnAcpSessions=true`
|
||||
- 当你想固定当前对话而不创建子线程时，请使用 `--bind here`。
|
||||
- 如果你想固定当前会话而不创建子线程，请使用 `--bind here`。
|
||||
|
||||
## ACP 控制
|
||||
|
||||
| 命令 | 作用 | 示例 |
|
||||
| -------------------- | --------------------------------------------------------- | ------------------------------------------------------------- |
|
||||
| `/acp spawn` | 创建 ACP 会话；可选当前绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | 取消目标会话的进行中轮次。 | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp spawn` | 创建 ACP 会话；可选当前会话绑定或线程绑定。 | `/acp spawn codex --bind here --cwd /repo` |
|
||||
| `/acp cancel` | 取消目标会话中正在进行的轮次。 | `/acp cancel agent:codex:acp:<uuid>` |
|
||||
| `/acp steer` | 向运行中的会话发送引导指令。 | `/acp steer --session support inbox prioritize failing tests` |
|
||||
| `/acp close` | 关闭会话并解绑线程目标。 | `/acp close` |
|
||||
| `/acp status` | 显示后端、模式、状态、运行时选项和能力。 | `/acp status` |
|
||||
| `/acp set-mode` | 为目标会话设置运行时模式。 | `/acp set-mode plan` |
|
||||
| `/acp set` | 通用运行时配置选项写入。 | `/acp set model openai/gpt-5.4` |
|
||||
| `/acp cwd` | 设置运行时工作目录覆盖值。 | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp status` | 显示后端、模式、状态、运行时选项和 capabilities。 | `/acp status` |
|
||||
| `/acp set-mode` | 设置目标会话的运行时模式。 | `/acp set-mode plan` |
|
||||
| `/acp set` | 通用运行时配置选项写入。 | `/acp set model openai/gpt-5.5` |
|
||||
| `/acp cwd` | 设置运行时工作目录覆盖。 | `/acp cwd /Users/user/Projects/repo` |
|
||||
| `/acp permissions` | 设置审批策略配置文件。 | `/acp permissions strict` |
|
||||
| `/acp timeout` | 设置运行时超时（秒）。 | `/acp timeout 120` |
|
||||
| `/acp model` | 设置运行时模型覆盖值。 | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | 移除会话运行时选项覆盖值。 | `/acp reset-options` |
|
||||
| `/acp model` | 设置运行时模型覆盖。 | `/acp model anthropic/claude-opus-4-6` |
|
||||
| `/acp reset-options` | 移除会话运行时选项覆盖。 | `/acp reset-options` |
|
||||
| `/acp sessions` | 从存储中列出最近的 ACP 会话。 | `/acp sessions` |
|
||||
| `/acp doctor` | 后端健康状态、能力、可执行修复。 | `/acp doctor` |
|
||||
| `/acp install` | 输出确定性的安装与启用步骤。 | `/acp install` |
|
||||
| `/acp doctor` | 后端健康状态、capabilities 和可执行修复。 | `/acp doctor` |
|
||||
| `/acp install` | 打印确定性的安装和启用步骤。 | `/acp install` |
|
||||
|
||||
`/acp status` 会显示生效中的运行时选项，以及运行时级别和后端级别的会话标识符。当后端缺少某项能力时，不支持的控制错误会被清晰显示。`/acp sessions` 会读取当前已绑定会话或请求方会话的存储；目标令牌（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根路径。
|
||||
`/acp status` 会显示生效中的运行时选项，以及运行时级别和后端级别的会话标识符。当某个后端缺少某项 capability 时，不支持控制的错误会清晰显示。`/acp sessions` 会读取当前绑定会话或请求方会话的存储；目标 token（`session-key`、`session-id` 或 `session-label`）会通过 Gateway 网关会话发现进行解析，包括每个智能体自定义的 `session.store` 根目录。
|
||||
|
||||
## 运行时选项映射
|
||||
|
||||
`/acp` 提供便捷命令和一个通用设置器。
|
||||
`/acp` 既有便捷命令，也有通用 setter。
|
||||
|
||||
等价操作：
|
||||
|
||||
- `/acp model <id>` 映射到运行时配置键 `model`。
|
||||
- `/acp permissions <profile>` 映射到运行时配置键 `approval_policy`。
|
||||
- `/acp timeout <seconds>` 映射到运行时配置键 `timeout`。
|
||||
- `/acp cwd <path>` 直接更新运行时 `cwd` 覆盖值。
|
||||
- `/acp cwd <path>` 直接更新运行时 `cwd` 覆盖。
|
||||
- `/acp set <key> <value>` 是通用路径。
|
||||
- 特例：`key=cwd` 使用 `cwd` 覆盖路径。
|
||||
- `/acp reset-options` 会清除目标会话的所有运行时覆盖值。
|
||||
- 特殊情况：`key=cwd` 使用 `cwd` 覆盖路径。
|
||||
- `/acp reset-options` 会清除目标会话的所有运行时覆盖。
|
||||
|
||||
## acpx harness 支持（当前）
|
||||
## `acpx` harness 支持（当前）
|
||||
|
||||
当前 acpx 内置 harness 别名：
|
||||
当前 `acpx` 内置 harness 别名：
|
||||
|
||||
- `claude`
|
||||
- `codex`
|
||||
@ -533,10 +535,10 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运
|
||||
- `pi`
|
||||
- `qwen`
|
||||
|
||||
当 OpenClaw 使用 acpx 后端时，除非你的 acpx 配置定义了自定义智能体别名，否则应优先将这些值用于 `agentId`。
|
||||
如果你本地安装的 Cursor 仍然将 ACP 暴露为 `agent acp`，请在你的 acpx 配置中覆盖 `cursor` 智能体命令，而不是修改内置默认值。
|
||||
当 OpenClaw 使用 `acpx` 后端时，除非你的 `acpx` 配置定义了自定义智能体别名，否则应优先将这些值用作 `agentId`。
|
||||
如果你的本地 Cursor 安装仍然通过 `agent acp` 暴露 ACP，请在你的 `acpx` 配置中覆盖 `cursor` 智能体命令，而不是更改内置默认值。
|
||||
|
||||
直接使用 acpx CLI 也可以通过 `--agent <command>` 指向任意适配器，但这个原始逃生口是 acpx CLI 的功能（不是常规的 OpenClaw `agentId` 路径）。
|
||||
直接使用 `acpx` CLI 也可以通过 `--agent <command>` 定向任意适配器，但这个原始逃生舱是 `acpx` CLI 功能（不是常规的 OpenClaw `agentId` 路径）。
|
||||
|
||||
## 必需配置
|
||||
|
||||
@ -546,7 +548,7 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运
|
||||
{
|
||||
acp: {
|
||||
enabled: true,
|
||||
// 可选。默认值为 true；设为 false 可暂停 ACP 分发，同时保留 /acp 控制。
|
||||
// 可选。默认值为 true；设为 false 可在保留 /acp 控制的同时暂停 ACP 分发。
|
||||
dispatch: { enabled: true },
|
||||
backend: "acpx",
|
||||
defaultAgent: "codex",
|
||||
@ -578,7 +580,7 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运
|
||||
}
|
||||
```
|
||||
|
||||
线程绑定配置取决于渠道适配器。以 Discord 为例：
|
||||
线程绑定配置是渠道适配器特定的。以 Discord 为例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -600,27 +602,27 @@ ACP 会话当前在主机运行时上运行，而不是在 OpenClaw 沙箱内运
|
||||
}
|
||||
```
|
||||
|
||||
如果绑定线程的 ACP 启动无法工作，请先验证适配器功能标志：
|
||||
如果线程绑定的 ACP 启动无法工作，请先验证适配器功能开关：
|
||||
|
||||
- Discord：`channels.discord.threadBindings.spawnAcpSessions=true`
|
||||
|
||||
当前对话绑定不需要创建子线程。它们需要活动的对话上下文，以及一个暴露 ACP 对话绑定能力的渠道适配器。
|
||||
当前会话绑定不需要创建子线程。它们需要一个活动会话上下文，以及一个暴露 ACP 会话绑定能力的渠道适配器。
|
||||
|
||||
参见[配置参考](/zh-CN/gateway/configuration-reference)。
|
||||
参见 [配置参考](/zh-CN/gateway/configuration-reference)。
|
||||
|
||||
## acpx 后端的插件设置
|
||||
## `acpx` 后端的插件设置
|
||||
|
||||
全新安装默认启用内置的 `acpx` 运行时插件，因此 ACP
|
||||
通常无需手动安装插件即可工作。
|
||||
|
||||
先从以下命令开始：
|
||||
先运行：
|
||||
|
||||
```text
|
||||
/acp doctor
|
||||
```
|
||||
|
||||
如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或想
|
||||
切换到本地开发检出版本，请使用显式插件路径：
|
||||
如果你禁用了 `acpx`、通过 `plugins.allow` / `plugins.deny` 拒绝了它，或者想
|
||||
切换到本地开发 checkout，请使用显式插件路径：
|
||||
|
||||
```bash
|
||||
openclaw plugins install acpx
|
||||
@ -639,11 +641,11 @@ openclaw plugins install ./path/to/local/acpx-plugin
|
||||
/acp doctor
|
||||
```
|
||||
|
||||
### acpx 命令和版本配置
|
||||
### `acpx` 命令和版本配置
|
||||
|
||||
默认情况下，内置的 `acpx` 插件使用其插件本地固定的二进制文件（插件包内部的 `node_modules/.bin/acpx`）。启动时会先将该后端注册为未就绪状态，并由一个后台作业验证 `acpx --version`；如果二进制文件缺失或版本不匹配，它会运行 `npm install --omit=dev --no-save acpx@<pinned>` 并再次验证。整个过程中，Gateway 网关始终保持非阻塞。
|
||||
默认情况下，内置的 `acpx` 插件使用其插件本地固定二进制文件（插件包内的 `node_modules/.bin/acpx`）。启动时会先将该后端注册为未就绪，随后后台任务会验证 `acpx --version`；如果二进制文件缺失或版本不匹配，它会运行 `npm install --omit=dev --no-save acpx@<pinned>` 并重新验证。整个过程中 Gateway 网关保持非阻塞。
|
||||
|
||||
可在插件配置中覆盖命令或版本：
|
||||
在插件配置中覆盖命令或版本：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -665,13 +667,12 @@ openclaw plugins install ./path/to/local/acpx-plugin
|
||||
- `expectedVersion: "any"` 会禁用严格版本匹配。
|
||||
- 自定义 `command` 路径会禁用插件本地自动安装。
|
||||
|
||||
参见[插件](/zh-CN/tools/plugin)。
|
||||
参见 [插件](/zh-CN/tools/plugin)。
|
||||
|
||||
### 自动依赖安装
|
||||
|
||||
当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，acpx
|
||||
运行时依赖（平台特定的二进制文件）会通过 postinstall 钩子自动安装。
|
||||
如果自动安装失败，Gateway 网关仍会正常启动，
|
||||
当你通过 `npm install -g openclaw` 全局安装 OpenClaw 时，`acpx`
|
||||
运行时依赖（平台特定二进制文件）会通过 postinstall hook 自动安装。如果自动安装失败，Gateway 网关仍会正常启动，
|
||||
并通过 `openclaw acp doctor` 报告缺失的依赖。
|
||||
|
||||
### 插件工具 MCP 桥接
|
||||
@ -679,129 +680,129 @@ openclaw plugins install ./path/to/local/acpx-plugin
|
||||
默认情况下，ACPX 会话**不会**向
|
||||
ACP harness 暴露 OpenClaw 插件注册的工具。
|
||||
|
||||
如果你希望 Codex 或 Claude Code 等 ACP 智能体调用已安装的
|
||||
OpenClaw 插件工具，例如 memory recall/store，请启用专用桥接：
|
||||
如果你希望 Codex 或 Claude Code 之类的 ACP 智能体能够调用已安装的
|
||||
OpenClaw 插件工具，例如记忆 recall / store，请启用专用桥接：
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.pluginToolsMcpBridge true
|
||||
```
|
||||
|
||||
其作用：
|
||||
这会执行以下操作：
|
||||
|
||||
- 在 ACPX 会话启动引导中注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。
|
||||
- 暴露已安装并启用的 OpenClaw
|
||||
插件中已经注册的插件工具。
|
||||
- 在 ACPX 会话引导期间注入一个名为 `openclaw-plugin-tools` 的内置 MCP 服务器。
|
||||
- 暴露已安装且已启用的 OpenClaw
|
||||
插件已注册的插件工具。
|
||||
- 保持该功能为显式启用，且默认关闭。
|
||||
|
||||
安全与信任说明：
|
||||
|
||||
- 这会扩大 ACP harness 的工具暴露面。
|
||||
- ACP 智能体只能访问 Gateway 网关中已经激活的插件工具。
|
||||
- 请将其视为与允许这些插件在
|
||||
OpenClaw 自身内部执行相同的信任边界。
|
||||
- 启用前请检查已安装的插件。
|
||||
- 这会扩展 ACP harness 的工具面。
|
||||
- ACP 智能体只能访问 Gateway 网关中已激活的插件工具。
|
||||
- 应将其视为与允许这些插件在
|
||||
OpenClaw 自身中执行相同的信任边界。
|
||||
- 启用前请审查已安装插件。
|
||||
|
||||
自定义 `mcpServers` 仍会像之前一样工作。内置的插件工具桥接是一个
|
||||
额外的按需启用便捷功能，而不是通用 MCP 服务器配置的替代品。
|
||||
自定义 `mcpServers` 仍按原样工作。内置的插件工具桥接只是一个
|
||||
额外的可选便捷功能，而不是通用 MCP 服务器配置的替代品。
|
||||
|
||||
### OpenClaw 工具 MCP 桥接
|
||||
|
||||
默认情况下，ACPX 会话也**不会**通过
|
||||
MCP 暴露内置 OpenClaw 工具。当 ACP 智能体需要使用选定的
|
||||
内置工具（例如 `cron`）时，请启用单独的核心工具桥接：
|
||||
MCP 暴露 OpenClaw 内置工具。当某个 ACP 智能体需要选定的
|
||||
内置工具（如 `cron`）时，请启用单独的核心工具桥接：
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.openClawToolsMcpBridge true
|
||||
```
|
||||
|
||||
其作用：
|
||||
这会执行以下操作：
|
||||
|
||||
- 在 ACPX 会话启动引导中注入一个名为 `openclaw-tools` 的内置 MCP 服务器。
|
||||
- 暴露选定的内置 OpenClaw 工具。初始服务器暴露 `cron`。
|
||||
- 在 ACPX 会话引导期间注入一个名为 `openclaw-tools` 的内置 MCP 服务器。
|
||||
- 暴露选定的 OpenClaw 内置工具。初始服务器会暴露 `cron`。
|
||||
- 保持核心工具暴露为显式启用，且默认关闭。
|
||||
|
||||
### 运行时超时配置
|
||||
|
||||
内置的 `acpx` 插件默认将嵌入式运行时轮次设置为 120 秒
|
||||
超时。这为 Gemini CLI 等较慢的 harness 提供了足够时间来完成
|
||||
内置的 `acpx` 插件默认将嵌入式运行时轮次的超时时间设置为 120 秒。
|
||||
这为 Gemini CLI 等较慢的 harness 提供了足够时间来完成
|
||||
ACP 启动和初始化。如果你的主机需要不同的
|
||||
运行时限制，可以覆盖该值：
|
||||
运行时限制，可以覆盖它：
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.timeoutSeconds 180
|
||||
```
|
||||
|
||||
更改此值后，重启 Gateway 网关。
|
||||
更改此值后请重启 Gateway 网关。
|
||||
|
||||
### 健康探测智能体配置
|
||||
|
||||
内置的 `acpx` 插件在判断嵌入式运行时后端是否就绪时，
|
||||
会探测一个 harness 智能体。默认值是 `codex`。如果你的部署
|
||||
内置的 `acpx` 插件在判断嵌入式
|
||||
运行时后端是否就绪时，会探测一个 harness 智能体。默认使用 `codex`。如果你的部署
|
||||
使用不同的默认 ACP 智能体，请将探测智能体设置为相同的 id：
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.probeAgent claude
|
||||
```
|
||||
|
||||
更改此值后，重启 Gateway 网关。
|
||||
更改此值后请重启 Gateway 网关。
|
||||
|
||||
## 权限配置
|
||||
|
||||
ACP 会话以非交互方式运行——没有 TTY 可用于批准或拒绝文件写入与 shell 执行权限提示。acpx 插件提供了两个配置键来控制权限处理方式：
|
||||
ACP 会话以非交互方式运行 —— 没有 TTY 可用于批准或拒绝文件写入和 shell 执行权限提示。`acpx` 插件提供了两个配置键来控制权限处理方式：
|
||||
|
||||
这些 ACPX harness 权限与 OpenClaw 执行审批是分开的，也与 CLI 后端厂商绕过标志（例如 Claude CLI `--permission-mode bypassPermissions`）分开。ACPX 的 `approve-all` 是 ACP 会话在 harness 级别的紧急放行开关。
|
||||
这些 ACPX harness 权限独立于 OpenClaw exec 审批，也独立于 CLI 后端厂商绕过 flag，例如 Claude CLI `--permission-mode bypassPermissions`。ACPX `approve-all` 是 ACP 会话的 harness 级别紧急放行开关。
|
||||
|
||||
### `permissionMode`
|
||||
|
||||
控制 harness 智能体可在不提示的情况下执行哪些操作。
|
||||
控制 harness 智能体无需提示即可执行哪些操作。
|
||||
|
||||
| 值 | 行为 |
|
||||
| --------------- | --------------------------------------------------------- |
|
||||
| `approve-all` | 自动批准所有文件写入和 shell 命令。 |
|
||||
| `approve-reads` | 仅自动批准读取；写入和执行需要提示。 |
|
||||
| `approve-reads` | 仅自动批准读取；写入和执行仍需要提示。 |
|
||||
| `deny-all` | 拒绝所有权限提示。 |
|
||||
|
||||
### `nonInteractivePermissions`
|
||||
|
||||
控制当本应显示权限提示、但没有可用的交互式 TTY 时会发生什么（对于 ACP 会话，这种情况始终成立）。
|
||||
控制当本应显示权限提示、但没有可交互 TTY 可用时会发生什么（ACP 会话始终如此）。
|
||||
|
||||
| 值 | 行为 |
|
||||
| ------ | ----------------------------------------------------------------- |
|
||||
| `fail` | 以 `AcpRuntimeError` 中止会话。**（默认）** |
|
||||
| `deny` | 静默拒绝该权限并继续（平滑降级）。 |
|
||||
| `fail` | 使用 `AcpRuntimeError` 中止会话。**（默认）** |
|
||||
| `deny` | 静默拒绝该权限并继续执行（优雅降级）。 |
|
||||
|
||||
### 配置
|
||||
|
||||
通过插件配置进行设置：
|
||||
通过插件配置设置：
|
||||
|
||||
```bash
|
||||
openclaw config set plugins.entries.acpx.config.permissionMode approve-all
|
||||
openclaw config set plugins.entries.acpx.config.nonInteractivePermissions fail
|
||||
```
|
||||
|
||||
更改这些值后，重启 Gateway 网关。
|
||||
更改这些值后请重启 Gateway 网关。
|
||||
|
||||
> **重要：** OpenClaw 当前默认使用 `permissionMode=approve-reads` 和 `nonInteractivePermissions=fail`。在非交互式 ACP 会话中，任何触发权限提示的写入或执行操作都可能因 `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` 而失败。
|
||||
>
|
||||
> 如果你需要限制权限，请将 `nonInteractivePermissions` 设置为 `deny`，这样会话会平滑降级，而不是直接崩溃。
|
||||
> 如果你需要限制权限，请将 `nonInteractivePermissions` 设置为 `deny`，这样会话会优雅降级，而不是直接崩溃。
|
||||
|
||||
## 故障排除
|
||||
|
||||
| 症状 | 可能原因 | 修复方法 |
|
||||
| --------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `ACP runtime backend is not configured` | 后端插件缺失或被禁用。 | 安装并启用后端插件，然后运行 `/acp doctor`。 |
|
||||
| `ACP is disabled by policy (acp.enabled=false)` | ACP 被全局禁用。 | 设置 `acp.enabled=true`。 |
|
||||
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发已禁用。 | 设置 `acp.dispatch.enabled=true`。 |
|
||||
| `ACP runtime backend is not configured` | 后端插件缺失或已禁用。 | 安装并启用后端插件，然后运行 `/acp doctor`。 |
|
||||
| `ACP is disabled by policy (acp.enabled=false)` | ACP 在全局范围内被禁用。 | 设置 `acp.enabled=true`。 |
|
||||
| `ACP dispatch is disabled by policy (acp.dispatch.enabled=false)` | 来自普通线程消息的分发被禁用。 | 设置 `acp.dispatch.enabled=true`。 |
|
||||
| `ACP agent "<id>" is not allowed by policy` | 智能体不在允许列表中。 | 使用允许的 `agentId`，或更新 `acp.allowedAgents`。 |
|
||||
| `Unable to resolve session target: ...` | 键 / id / 标签令牌错误。 | 运行 `/acp sessions`，复制精确的键 / 标签后重试。 |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定对话的情况下使用了 `--bind here`。 | 移动到目标聊天 / 渠道后重试，或使用不绑定的启动。 |
|
||||
| `Conversation bindings are unavailable for <channel>.` | 适配器缺少当前对话 ACP 绑定能力。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 |
|
||||
| `Unable to resolve session target: ...` | key / id / label token 错误。 | 运行 `/acp sessions`，复制准确的 key / label，然后重试。 |
|
||||
| `--bind here requires running /acp spawn inside an active ... conversation` | 在没有活动可绑定会话的情况下使用了 `--bind here`。 | 移动到目标聊天 / 频道后重试，或使用未绑定启动。 |
|
||||
| `Conversation bindings are unavailable for <channel>.` | 适配器缺少当前会话 ACP 绑定 capability。 | 在支持时使用 `/acp spawn ... --thread ...`，配置顶层 `bindings[]`，或切换到受支持的渠道。 |
|
||||
| `--thread here requires running /acp spawn inside an active ... thread` | 在线程上下文之外使用了 `--thread here`。 | 移动到目标线程，或使用 `--thread auto` / `off`。 |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有当前活动绑定目标。 | 由所有者重新绑定，或使用其他对话或线程。 |
|
||||
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定能力。 | 使用 `--thread off`，或切换到受支持的适配器 / 渠道。 |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机侧；请求方会话处于沙箱中。 | 从沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话中运行 ACP 启动。 |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对强制沙箱隔离使用 `runtime="subagent"`，或从非沙箱会话中使用带 `sandbox="inherit"` 的 ACP。 |
|
||||
| 绑定会话缺少 ACP 元数据 | ACP 会话元数据已过时 / 已删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定 / 聚焦线程。 |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 阻止了非交互式 ACP 会话中的写入 / 执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](#permission-configuration)。 |
|
||||
| ACP 会话很早失败且几乎没有输出 | 权限提示被 `permissionMode` / `nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，设置 `permissionMode=approve-all`；如需平滑降级，设置 `nonInteractivePermissions=deny`。 |
|
||||
| ACP 会话在工作完成后无限期卡住 | harness 进程已完成，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 |
|
||||
| `Only <user-id> can rebind this channel/conversation/thread.` | 另一个用户拥有当前活动绑定目标。 | 由所有者重新绑定，或使用其他会话或线程。 |
|
||||
| `Thread bindings are unavailable for <channel>.` | 适配器缺少线程绑定 capability。 | 使用 `--thread off`，或切换到受支持的适配器 / 渠道。 |
|
||||
| `Sandboxed sessions cannot spawn ACP sessions ...` | ACP 运行时位于主机侧；请求方会话处于沙箱中。 | 在沙箱会话中使用 `runtime="subagent"`，或从非沙箱会话运行 ACP 启动。 |
|
||||
| `sessions_spawn sandbox="require" is unsupported for runtime="acp" ...` | 为 ACP 运行时请求了 `sandbox="require"`。 | 对必须使用沙箱的场景使用 `runtime="subagent"`，或从非沙箱会话中使用带 `sandbox="inherit"` 的 ACP。 |
|
||||
| 绑定会话缺少 ACP 元数据 | ACP 会话元数据已陈旧 / 被删除。 | 使用 `/acp spawn` 重新创建，然后重新绑定 / 聚焦线程。 |
|
||||
| `AcpRuntimeError: Permission prompt unavailable in non-interactive mode` | `permissionMode` 在非交互式 ACP 会话中阻止了写入 / 执行。 | 将 `plugins.entries.acpx.config.permissionMode` 设置为 `approve-all` 并重启 Gateway 网关。参见[权限配置](#permission-configuration)。 |
|
||||
| ACP 会话很早失败且几乎没有输出 | 权限提示被 `permissionMode` / `nonInteractivePermissions` 阻止。 | 检查 Gateway 网关日志中的 `AcpRuntimeError`。如需完整权限，请设置 `permissionMode=approve-all`；如需优雅降级，请设置 `nonInteractivePermissions=deny`。 |
|
||||
| ACP 会话在完成工作后无限期停滞 | harness 进程已结束，但 ACP 会话未报告完成。 | 使用 `ps aux \| grep acpx` 监控；手动杀掉陈旧进程。 |
|
||||
|
||||
@ -3,73 +3,74 @@ read_when:
|
||||
- 使用或修改 exec 工具
|
||||
- 调试 stdin 或 TTY 行为
|
||||
summary: Exec 工具用法、stdin 模式和 TTY 支持
|
||||
title: Exec Tool
|
||||
title: Exec 工具
|
||||
x-i18n:
|
||||
generated_at: "2026-04-21T06:26:43Z"
|
||||
generated_at: "2026-04-23T19:27:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 5018468f31bb76fc142ddef7002c7bbc617406de7ce912670d1b9edef6a9a042
|
||||
source_hash: f191380330a86f8f0c291cde65062fe4146f20e6a6bd2169e1439f2518cd5194
|
||||
source_path: tools/exec.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# Exec 工具
|
||||
|
||||
在工作区中运行 shell 命令。通过 `process` 支持前台和后台执行。
|
||||
如果 `process` 不被允许，`exec` 会同步运行，并忽略 `yieldMs`/`background`。
|
||||
后台会话按智能体隔离；`process` 只能看到来自同一智能体的会话。
|
||||
在工作区中运行 shell 命令。通过 `process` 支持前台 + 后台执行。
|
||||
如果 `process` 被禁止，`exec` 会同步运行，并忽略 `yieldMs`/`background`。
|
||||
后台会话按智能体隔离；`process` 只能看到同一智能体的会话。
|
||||
|
||||
## 参数
|
||||
|
||||
- `command`（必需）
|
||||
- `workdir`（默认为当前工作目录）
|
||||
- `command`（必填）
|
||||
- `workdir`（默认为 cwd）
|
||||
- `env`（键/值覆盖）
|
||||
- `yieldMs`（默认 10000）：延迟后自动转入后台
|
||||
- `background`（布尔值）：立即转入后台
|
||||
- `background`（bool）：立即转入后台
|
||||
- `timeout`（秒，默认 1800）：到期后终止
|
||||
- `pty`（布尔值）：在可用时于伪终端中运行（仅限 TTY 的 CLI、编码智能体、终端 UI）
|
||||
- `pty`（bool）：可用时在伪终端中运行（仅支持 TTY 的 CLI、编码智能体、终端 UI）
|
||||
- `host`（`auto | sandbox | gateway | node`）：执行位置
|
||||
- `security`（`deny | allowlist | full`）：`gateway`/`node` 的执行模式
|
||||
- `security`（`deny | allowlist | full`）：`gateway`/`node` 的强制执行模式
|
||||
- `ask`（`off | on-miss | always`）：`gateway`/`node` 的审批提示
|
||||
- `node`（字符串）：用于 `host=node` 的节点 id/名称
|
||||
- `elevated`（布尔值）：请求提升模式（从沙箱逃逸到已配置的主机路径）；仅当 `elevated` 最终解析为 `full` 时，才会强制 `security=full`
|
||||
- `node`（string）：`host=node` 时的节点 id/名称
|
||||
- `elevated`（bool）：请求提升模式（从沙箱逃逸到已配置的主机路径）；仅当 elevated 最终解析为 `full` 时，才会强制 `security=full`
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- `host` 默认为 `auto`：当会话启用了沙箱运行时时使用 `sandbox`，否则使用 `gateway`。
|
||||
- `auto` 是默认路由策略，不是通配符。可以在单次调用中使用 `host=node`；只有在当前没有启用沙箱运行时时，才允许单次调用使用 `host=gateway`。
|
||||
- 在没有额外配置时，`host=auto` 依然可以“开箱即用”：没有沙箱时会解析为 `gateway`；有正在运行的沙箱时则保持在沙箱内。
|
||||
- `elevated` 会从沙箱逃逸到已配置的主机路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认是 `host=node`）时为 `node`。只有在当前会话/提供商启用了提升访问时，这个选项才可用。
|
||||
- `gateway`/`node` 的审批由 `~/.openclaw/exec-approvals.json` 控制。
|
||||
- `node` 需要一个已配对的节点（配套应用或无头节点主机）。
|
||||
- 如果有多个可用节点，请设置 `exec.node` 或 `tools.exec.node` 进行选择。
|
||||
- `host` 默认是 `auto`：当会话启用了沙箱运行时时使用沙箱，否则使用 Gateway 网关。
|
||||
- `auto` 是默认路由策略，不是通配符。每次调用都允许从 `auto` 指定 `host=node`；只有在没有活动沙箱运行时时，才允许每次调用指定 `host=gateway`。
|
||||
- 在没有额外配置的情况下，`host=auto` 仍然可以“直接使用”：没有沙箱时会解析为 `gateway`；有活动沙箱时则会保留在沙箱中。
|
||||
- `elevated` 会从沙箱逃逸到已配置的主机路径：默认是 `gateway`，或者当 `tools.exec.host=node`（或会话默认是 `host=node`）时为 `node`。只有当前会话/提供商启用了提升访问时才可用。
|
||||
- `gateway`/`node` 审批由 `~/.openclaw/exec-approvals.json` 控制。
|
||||
- `node` 需要已配对的节点（配套应用或无头节点主机）。
|
||||
- 如果有多个节点可用，请设置 `exec.node` 或 `tools.exec.node` 进行选择。
|
||||
- `exec host=node` 是节点上唯一的 shell 执行路径；旧版 `nodes.run` 包装器已移除。
|
||||
- 在非 Windows 主机上，exec 会优先使用已设置的 `SHELL`；如果 `SHELL` 是 `fish`，它会优先从 `PATH` 中选择 `bash`（或 `sh`），以避免不兼容 `fish` 的脚本，然后才会在两者都不存在时回退到 `SHELL`。
|
||||
- 在 Windows 主机上，exec 会优先发现 PowerShell 7（依次检查 Program Files、ProgramW6432，然后是 `PATH`），然后回退到 Windows PowerShell 5.1。
|
||||
- 在非 Windows 主机上，exec 会在设置了 `SHELL` 时使用它；如果 `SHELL` 是 `fish`，则会优先从 `PATH` 中选择 `bash`（或 `sh`）以避免与 fish 不兼容的脚本，然后在两者都不存在时回退到 `SHELL`。
|
||||
- 在 Windows 主机上，exec 会优先发现 PowerShell 7（依次检查 Program Files、ProgramW6432，然后是 PATH），然后回退到 Windows PowerShell 5.1。
|
||||
- 主机执行（`gateway`/`node`）会拒绝 `env.PATH` 和加载器覆盖（`LD_*`/`DYLD_*`），以防止二进制劫持或注入代码。
|
||||
- OpenClaw 会在启动的命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），这样 shell/配置文件规则就可以检测到 exec 工具上下文。
|
||||
- 重要：沙箱隔离默认**关闭**。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会以安全关闭方式失败，而不是静默地在 gateway 主机上运行。请启用沙箱隔离，或结合审批使用 `host=gateway`。
|
||||
- 脚本预检（用于发现常见的 Python/Node shell 语法错误）只会检查位于有效 `workdir` 边界内的文件。如果某个脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。
|
||||
- 对于现在开始的长时间运行任务，只需启动一次，并在启用了自动完成唤醒且命令有输出或失败时依赖自动唤醒即可。
|
||||
对日志、状态、输入或人工干预，请使用 `process`；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。
|
||||
- 对于应稍后执行或按计划执行的任务，请使用 cron，而不是用 `exec` 的 sleep/延迟模式。
|
||||
- OpenClaw 会在派生命令环境中设置 `OPENCLAW_SHELL=exec`（包括 PTY 和沙箱执行），以便 shell/profile 规则检测 exec 工具上下文。
|
||||
- 重要：沙箱隔离**默认关闭**。如果沙箱隔离关闭，隐式 `host=auto` 会解析为 `gateway`。显式 `host=sandbox` 仍会以安全关闭方式失败，而不会悄悄在 Gateway 网关主机上运行。请启用沙箱隔离，或搭配审批使用 `host=gateway`。
|
||||
- 脚本预检（用于发现常见 Python/Node shell 语法错误）只会检查有效 `workdir` 边界内的文件。如果某个脚本路径解析到 `workdir` 之外，则会跳过该文件的预检。
|
||||
- 对于现在开始的长时间运行任务，请只启动一次，并在启用了自动完成唤醒且命令产生输出或失败时依赖自动完成唤醒。
|
||||
使用 `process` 查看日志、状态、输入或进行干预；不要用 sleep 循环、timeout 循环或重复轮询来模拟调度。
|
||||
- 对于应稍后发生或按计划运行的任务，请使用 cron，而不是
|
||||
`exec` 的 sleep/delay 模式。
|
||||
|
||||
## 配置
|
||||
|
||||
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，转入后台的 exec 会话在退出时会将系统事件加入队列并请求一次心跳。
|
||||
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行时间超过该值时，发出一次“正在运行”通知（设为 0 则禁用）。
|
||||
- `tools.exec.host`（默认：`auto`；当沙箱运行时启用时解析为 `sandbox`，否则解析为 `gateway`）
|
||||
- `tools.exec.security`（默认：沙箱为 `deny`，`gateway` 和 `node` 在未设置时为 `full`）
|
||||
- `tools.exec.notifyOnExit`（默认：true）：为 true 时，转入后台的 exec 会话在退出时会将系统事件加入队列，并请求一次 heartbeat。
|
||||
- `tools.exec.approvalRunningNoticeMs`（默认：10000）：当需要审批的 exec 运行时间超过该值时，发出一条“running”通知（设为 0 可禁用）。
|
||||
- `tools.exec.host`（默认：`auto`；当沙箱运行时处于活动状态时解析为 `sandbox`，否则为 `gateway`）
|
||||
- `tools.exec.security`（默认：对沙箱为 `deny`，对 gateway + node 在未设置时为 `full`）
|
||||
- `tools.exec.ask`（默认：`off`）
|
||||
- 对 `gateway` 和 `node`，默认是无需审批的主机 exec。如果你想启用审批/allowlist 行为，请同时收紧 `tools.exec.*` 和主机上的 `~/.openclaw/exec-approvals.json`；参见 [Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。
|
||||
- YOLO 来自主机策略默认值（`security=full`、`ask=off`），而不是来自 `host=auto`。如果你想强制走 `gateway` 或 `node` 路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。
|
||||
- 在 `security=full` 且 `ask=off` 模式下，主机 exec 会直接遵循已配置策略；不存在额外的启发式命令混淆预过滤器，也不存在额外的脚本预检拒绝层。
|
||||
- 无审批的主机 exec 是 gateway + node 的默认行为。如果你希望使用审批/allowlist 行为，请同时收紧 `tools.exec.*` 和主机上的 `~/.openclaw/exec-approvals.json`；参见 [Exec 审批](/zh-CN/tools/exec-approvals#no-approval-yolo-mode)。
|
||||
- YOLO 来源于主机策略默认值（`security=full`、`ask=off`），而不是 `host=auto`。如果你想强制使用 gateway 或 node 路由，请设置 `tools.exec.host` 或使用 `/exec host=...`。
|
||||
- 在 `security=full` 且 `ask=off` 模式下，主机 exec 会直接遵循已配置策略；不存在额外的启发式命令混淆预过滤器或脚本预检拒绝层。
|
||||
- `tools.exec.node`（默认：未设置）
|
||||
- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器求值形式，如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`，始终需要显式审批。`allow-always` 仍可持久化允许无害的解释器/脚本调用，但内联求值形式每次仍会提示。
|
||||
- `tools.exec.pathPrepend`：在 exec 运行时添加到 `PATH` 前面的目录列表（仅 `gateway` 和 `sandbox`）。
|
||||
- `tools.exec.safeBins`：仅处理 stdin 的安全二进制文件，可在没有显式 allowlist 条目的情况下运行。行为详情见 [Safe bins](/zh-CN/tools/exec-approvals#safe-bins-stdin-only)。
|
||||
- `tools.exec.safeBinTrustedDirs`：用于 `safeBins` 路径检查的其他显式可信目录。`PATH` 条目永远不会自动视为可信。内置默认值是 `/bin` 和 `/usr/bin`。
|
||||
- `tools.exec.safeBinProfiles`：为自定义 safe bin 提供的可选自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。
|
||||
- `tools.exec.strictInlineEval`（默认：false）：为 true 时，内联解释器求值形式，如 `python -c`、`node -e`、`ruby -e`、`perl -e`、`php -r`、`lua -e` 和 `osascript -e`，始终需要显式审批。`allow-always` 仍可持久信任良性的解释器/脚本调用，但内联求值形式每次仍会提示。
|
||||
- `tools.exec.pathPrepend`：在 exec 运行时添加到 `PATH` 前面的目录列表（仅 gateway + sandbox）。
|
||||
- `tools.exec.safeBins`：仅 stdin 的安全二进制，可在没有显式 allowlist 条目的情况下运行。行为细节参见 [Safe bins](/zh-CN/tools/exec-approvals#safe-bins-stdin-only)。
|
||||
- `tools.exec.safeBinTrustedDirs`：用于 `safeBins` 路径检查的额外显式受信任目录。`PATH` 条目永远不会自动受信任。内置默认值为 `/bin` 和 `/usr/bin`。
|
||||
- `tools.exec.safeBinProfiles`：按 safe bin 配置的可选自定义 argv 策略（`minPositional`、`maxPositional`、`allowedValueFlags`、`deniedFlags`）。
|
||||
|
||||
示例：
|
||||
|
||||
@ -85,12 +86,13 @@ x-i18n:
|
||||
|
||||
### PATH 处理
|
||||
|
||||
- `host=gateway`：会将你的登录 shell `PATH` 合并到 exec 环境中。主机执行会拒绝 `env.PATH` 覆盖。守护进程本身仍使用最小化的 `PATH`：
|
||||
- `host=gateway`：将你的 login-shell `PATH` 合并到 exec 环境中。主机执行会拒绝 `env.PATH` 覆盖。守护进程本身仍以最小 `PATH` 运行：
|
||||
- macOS：`/opt/homebrew/bin`、`/usr/local/bin`、`/usr/bin`、`/bin`
|
||||
- Linux：`/usr/local/bin`、`/usr/bin`、`/bin`
|
||||
- `host=sandbox`：在容器内运行 `sh -lc`（登录 shell），因此 `/etc/profile` 可能会重置 `PATH`。
|
||||
OpenClaw 会在配置文件加载完成后通过内部环境变量把 `env.PATH` 追加到前面（不进行 shell 插值）；`tools.exec.pathPrepend` 也会在这里生效。
|
||||
- `host=node`：只会将你传入且未被阻止的环境变量覆盖发送到节点。主机执行会拒绝 `env.PATH` 覆盖，节点主机也会忽略它。如果你需要在节点上增加额外的 PATH 条目，请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。
|
||||
- `host=sandbox`：在容器内运行 `sh -lc`（login shell），因此 `/etc/profile` 可能会重置 `PATH`。
|
||||
OpenClaw 会在 profile 加载后通过内部环境变量将 `env.PATH` 前置进去（不进行 shell 插值）；
|
||||
`tools.exec.pathPrepend` 在这里也会生效。
|
||||
- `host=node`：只会将你传入的、未被阻止的环境变量覆盖发送到节点。主机执行会拒绝 `env.PATH` 覆盖，并且节点主机会忽略它。如果你需要在节点上增加 PATH 条目，请配置节点主机服务环境（systemd/launchd），或将工具安装到标准位置。
|
||||
|
||||
按智能体绑定节点（在配置中使用智能体列表索引）：
|
||||
|
||||
@ -99,12 +101,12 @@ openclaw config get agents.list
|
||||
openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
|
||||
```
|
||||
|
||||
控制 UI：Nodes 选项卡包含一个小型的“Exec 节点绑定”面板，用于配置同样的设置。
|
||||
Control UI：Nodes 标签页中包含一个小型“Exec 节点绑定”面板，用于相同设置。
|
||||
|
||||
## 会话级覆盖（`/exec`）
|
||||
## 会话覆盖（`/exec`）
|
||||
|
||||
使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**每个会话**的默认值。
|
||||
发送不带参数的 `/exec` 可显示当前值。
|
||||
使用 `/exec` 为 `host`、`security`、`ask` 和 `node` 设置**按会话生效**的默认值。
|
||||
不带参数发送 `/exec` 可显示当前值。
|
||||
|
||||
示例：
|
||||
|
||||
@ -114,68 +116,69 @@ openclaw config set agents.list[0].tools.exec.node "node-id-or-name"
|
||||
|
||||
## 授权模型
|
||||
|
||||
`/exec` 只对**已授权的发送者**生效（渠道 allowlist/配对 加上 `commands.useAccessGroups`）。
|
||||
它只会更新**会话状态**，不会写入配置。若要彻底禁用 exec，请通过工具策略拒绝它
|
||||
（`tools.deny: ["exec"]` 或按智能体设置）。除非你显式设置 `security=full` 和 `ask=off`，否则主机审批仍然适用。
|
||||
`/exec` 仅对**已授权发送者**生效（渠道 allowlist/配对加上 `commands.useAccessGroups`）。
|
||||
它只会更新**会话状态**，不会写入配置。若要彻底禁用 exec，请通过工具
|
||||
策略禁止它（`tools.deny: ["exec"]` 或按智能体配置）。
|
||||
除非你显式设置 `security=full` 和 `ask=off`，否则主机审批仍然适用。
|
||||
|
||||
## Exec 审批（配套应用 / 节点主机）
|
||||
|
||||
沙箱隔离的智能体可以要求每次请求都先获得审批，之后才允许 `exec` 在 gateway 或节点主机上运行。
|
||||
关于策略、allowlist 和 UI 流程，请参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
|
||||
沙箱隔离的智能体可以要求每次请求都先审批，然后才允许 `exec` 在 Gateway 网关或节点主机上运行。
|
||||
有关策略、allowlist 和 UI 流程，请参见 [Exec 审批](/zh-CN/tools/exec-approvals)。
|
||||
|
||||
当需要审批时，exec 工具会立即返回，
|
||||
并带有 `status: "approval-pending"` 和一个审批 id。一旦获批（或被拒绝 / 超时），
|
||||
并带有 `status: "approval-pending"` 和一个审批 id。一旦审批通过（或被拒绝 / 超时），
|
||||
Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如果命令在
|
||||
`tools.exec.approvalRunningNoticeMs` 之后仍在运行，则会发出一次 `Exec running` 通知。
|
||||
在原生支持审批卡片/按钮的渠道中，智能体应优先依赖该原生 UI，
|
||||
只有当工具结果明确说明聊天审批不可用，或手动审批是唯一方式时，
|
||||
才应附带手动 `/approve` 命令。
|
||||
`tools.exec.approvalRunningNoticeMs` 之后仍在运行，则会发出一条 `Exec running` 通知。
|
||||
在支持原生审批卡片/按钮的渠道上，智能体应优先依赖该
|
||||
原生 UI，只有在工具
|
||||
结果明确说明聊天审批不可用或手动审批是唯一途径时，才应包含手动 `/approve` 命令。
|
||||
|
||||
## allowlist + safe bins
|
||||
## Allowlist + safe bins
|
||||
|
||||
手动 allowlist 强制仅匹配**已解析的二进制路径**（不匹配 basename）。当
|
||||
`security=allowlist` 时，仅当管道中的每个片段都在 allowlist 中
|
||||
或属于 safe bin 时，shell 命令才会被自动允许。在 allowlist 模式下，
|
||||
链式命令（`;`、`&&`、`||`）和重定向会被拒绝，除非每个顶层片段都满足 allowlist 要求
|
||||
（包括 safe bins）。重定向仍然不受支持。
|
||||
持久化的 `allow-always` 信任不会绕过这条规则：链式命令仍然要求每个
|
||||
手动 allowlist 强制执行仅匹配**解析后的二进制路径**（不匹配 basename）。当
|
||||
`security=allowlist` 时，只有当管道中的每一段都在
|
||||
allowlist 中或属于 safe bin，shell 命令才会被自动允许。链式命令（`;`、`&&`、`||`）和重定向在
|
||||
allowlist 模式下会被拒绝，除非每个顶层片段都满足 allowlist（包括 safe bins）。
|
||||
重定向仍然不受支持。
|
||||
持久化的 `allow-always` 信任也不能绕过该规则：链式命令仍要求每个
|
||||
顶层片段都匹配。
|
||||
|
||||
`autoAllowSkills` 是 exec 审批中的一条独立便捷路径。它不同于
|
||||
手动路径 allowlist 条目。若要实现严格的显式信任，请保持
|
||||
`autoAllowSkills` 为禁用状态。
|
||||
`autoAllowSkills` 是 exec 审批中的一个单独便捷路径。它与
|
||||
手动路径 allowlist 条目不同。若要进行严格的显式信任，请保持 `autoAllowSkills` 关闭。
|
||||
|
||||
请将这两类控制分别用于不同目的：
|
||||
这两组控制各有用途：
|
||||
|
||||
- `tools.exec.safeBins`：小型、仅处理 stdin 的流过滤器。
|
||||
- `tools.exec.safeBinTrustedDirs`：safe bin 可执行路径的显式额外可信目录。
|
||||
- `tools.exec.safeBins`：小型、仅 stdin 的流过滤器。
|
||||
- `tools.exec.safeBinTrustedDirs`：用于 safe-bin 可执行路径的显式额外受信任目录。
|
||||
- `tools.exec.safeBinProfiles`：自定义 safe bin 的显式 argv 策略。
|
||||
- allowlist：对可执行路径的显式信任。
|
||||
|
||||
不要把 `safeBins` 当作通用 allowlist，也不要添加解释器/运行时二进制文件（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式 allowlist 条目，并保持审批提示开启。
|
||||
如果解释器/运行时 `safeBins` 条目缺少显式 profile，`openclaw security audit` 会发出警告，而 `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles` 条目生成脚手架。
|
||||
如果你又把 `jq` 这类行为宽泛的二进制文件显式加回 `safeBins`，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。
|
||||
不要将 `safeBins` 视为通用 allowlist，也不要添加解释器/运行时二进制（例如 `python3`、`node`、`ruby`、`bash`）。如果你需要这些，请使用显式 allowlist 条目，并保持启用审批提示。
|
||||
当解释器/运行时 `safeBins` 条目缺少显式 profile 时，`openclaw security audit` 会发出警告，而 `openclaw doctor --fix` 可以为缺失的自定义 `safeBinProfiles` 条目生成脚手架。
|
||||
当你显式将 `jq` 这类行为范围较广的二进制重新加入 `safeBins` 时，`openclaw security audit` 和 `openclaw doctor` 也会发出警告。
|
||||
如果你显式将解释器加入 allowlist，请启用 `tools.exec.strictInlineEval`，这样内联代码求值形式仍然需要新的审批。
|
||||
|
||||
完整策略细节和示例，请参见 [Exec 审批](/zh-CN/tools/exec-approvals#safe-bins-stdin-only) 和 [Safe bins 与 allowlist 的区别](/zh-CN/tools/exec-approvals#safe-bins-versus-allowlist)。
|
||||
有关完整策略细节和示例，请参见 [Exec 审批](/zh-CN/tools/exec-approvals#safe-bins-stdin-only) 和 [Safe bins 与 allowlist 的区别](/zh-CN/tools/exec-approvals#safe-bins-versus-allowlist)。
|
||||
|
||||
## 示例
|
||||
|
||||
前台运行：
|
||||
前台：
|
||||
|
||||
```json
|
||||
{ "tool": "exec", "command": "ls -la" }
|
||||
```
|
||||
|
||||
后台运行 + 轮询：
|
||||
后台 + 轮询：
|
||||
|
||||
```json
|
||||
{"tool":"exec","command":"npm run build","yieldMs":1000}
|
||||
{"tool":"process","action":"poll","sessionId":"<id>"}
|
||||
```
|
||||
|
||||
轮询用于按需查看状态，不应用于等待循环。如果启用了自动完成唤醒，
|
||||
当命令输出内容或失败时，它可以唤醒会话。
|
||||
轮询用于按需查看状态，而不是等待循环。
|
||||
如果启用了自动完成唤醒，
|
||||
命令在产生输出或失败时可以唤醒会话。
|
||||
|
||||
发送按键（tmux 风格）：
|
||||
|
||||
@ -191,7 +194,7 @@ Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如
|
||||
{ "tool": "process", "action": "submit", "sessionId": "<id>" }
|
||||
```
|
||||
|
||||
粘贴（默认带 bracketed paste）：
|
||||
粘贴（默认带括号包装）：
|
||||
|
||||
```json
|
||||
{ "tool": "process", "action": "paste", "sessionId": "<id>", "text": "line1\nline2\n" }
|
||||
@ -200,30 +203,29 @@ Gateway 网关会发出系统事件（`Exec finished` / `Exec denied`）。如
|
||||
## apply_patch
|
||||
|
||||
`apply_patch` 是 `exec` 的一个子工具，用于结构化的多文件编辑。
|
||||
它默认对 OpenAI 和 OpenAI Codex 模型启用。只有在你想禁用它
|
||||
或将其限制为特定模型时，才需要使用配置：
|
||||
它默认对 OpenAI 和 OpenAI Codex 模型启用。仅当你想禁用它或将其限制到特定模型时，才需要使用配置：
|
||||
|
||||
```json5
|
||||
{
|
||||
tools: {
|
||||
exec: {
|
||||
applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.4"] },
|
||||
applyPatch: { workspaceOnly: true, allowModels: ["gpt-5.5"] },
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- 仅适用于 OpenAI/OpenAI Codex 模型。
|
||||
- 仅对 OpenAI/OpenAI Codex 模型可用。
|
||||
- 工具策略仍然适用；`allow: ["write"]` 会隐式允许 `apply_patch`。
|
||||
- 配置位于 `tools.exec.applyPatch`。
|
||||
- `tools.exec.applyPatch.enabled` 默认值为 `true`；如需对 OpenAI 模型禁用该工具，请将其设为 `false`。
|
||||
- `tools.exec.applyPatch.workspaceOnly` 默认值为 `true`（限制在工作区内）。只有在你明确希望 `apply_patch` 在工作区目录之外写入/删除内容时，才应将其设为 `false`。
|
||||
- 配置位于 `tools.exec.applyPatch` 下。
|
||||
- `tools.exec.applyPatch.enabled` 默认值为 `true`；将其设为 `false` 可为 OpenAI 模型禁用该工具。
|
||||
- `tools.exec.applyPatch.workspaceOnly` 默认值为 `true`（限制在工作区内）。仅当你确实希望 `apply_patch` 在工作区目录之外写入/删除时，才应将其设为 `false`。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [Exec 审批](/zh-CN/tools/exec-approvals) — shell 命令的审批门控
|
||||
- [沙箱隔离](/zh-CN/gateway/sandboxing) — 在沙箱隔离环境中运行命令
|
||||
- [后台进程](/zh-CN/gateway/background-process) — 长时间运行的 exec 和 process 工具
|
||||
- [安全](/zh-CN/gateway/security) — 工具策略和提升访问权限
|
||||
- [Exec 审批](/zh-CN/tools/exec-approvals) —— shell 命令的审批门控
|
||||
- [沙箱隔离](/zh-CN/gateway/sandboxing) —— 在沙箱隔离环境中运行命令
|
||||
- [后台进程](/zh-CN/gateway/background-process) —— 长时间运行的 exec 和 process 工具
|
||||
- [安全性](/zh-CN/gateway/security) —— 工具策略和提升访问
|
||||
|
||||
@ -1,23 +1,23 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在工作流中加入一个纯 JSON 的 LLM 步骤
|
||||
- 你需要用于自动化的、经过 schema 校验的 LLM 输出
|
||||
summary: 用于工作流的纯 JSON LLM 任务（可选插件工具）
|
||||
title: LLM Task
|
||||
- 你想在工作流中加入一个仅 JSON 的 LLM 步骤
|
||||
- 你需要用于自动化的经 schema 验证的 LLM 输出
|
||||
summary: 面向工作流的仅 JSON LLM 任务（可选插件工具）
|
||||
title: LLM 任务
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T10:11:37Z"
|
||||
generated_at: "2026-04-23T19:27:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: cbe9b286a8e958494de06a59b6e7b750a82d492158df344c7afe30fce24f0584
|
||||
source_hash: 4234b2fd9247c06fcc481be6e3339726ebdb84891f4b8324f17e2d387dac4d8a
|
||||
source_path: tools/llm-task.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# LLM Task
|
||||
# LLM 任务
|
||||
|
||||
`llm-task` 是一个**可选插件工具**，用于运行纯 JSON 的 LLM 任务，并返回结构化输出（可选地依据 JSON Schema 进行校验）。
|
||||
`llm-task` 是一个**可选插件工具**，用于运行仅 JSON 的 LLM 任务，并返回结构化输出（可选地根据 JSON Schema 进行验证）。
|
||||
|
||||
这非常适合 Lobster 这样的工作流引擎：你可以添加一个单独的 LLM 步骤，而无需为每个工作流编写自定义 OpenClaw 代码。
|
||||
这非常适合 Lobster 之类的工作流引擎：你可以添加一个单独的 LLM 步骤，而无需为每个工作流编写自定义 OpenClaw 代码。
|
||||
|
||||
## 启用插件
|
||||
|
||||
@ -58,9 +58,9 @@ x-i18n:
|
||||
"enabled": true,
|
||||
"config": {
|
||||
"defaultProvider": "openai-codex",
|
||||
"defaultModel": "gpt-5.4",
|
||||
"defaultModel": "gpt-5.5",
|
||||
"defaultAuthProfileId": "main",
|
||||
"allowedModels": ["openai-codex/gpt-5.4"],
|
||||
"allowedModels": ["openai-codex/gpt-5.5"],
|
||||
"maxTokens": 800,
|
||||
"timeoutMs": 30000
|
||||
}
|
||||
@ -70,7 +70,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
`allowedModels` 是 `provider/model` 字符串的 allowlist。如果设置了它，任何不在列表中的请求都会被拒绝。
|
||||
`allowedModels` 是由 `provider/model` 字符串组成的 allowlist。如果设置了它，则任何不在该列表中的请求都会被拒绝。
|
||||
|
||||
## 工具参数
|
||||
|
||||
@ -85,11 +85,11 @@ x-i18n:
|
||||
- `maxTokens`（数字，可选）
|
||||
- `timeoutMs`（数字，可选）
|
||||
|
||||
`thinking` 接受标准的 OpenClaw 推理预设，例如 `low` 或 `medium`。
|
||||
`thinking` 接受标准 OpenClaw 推理预设，例如 `low` 或 `medium`。
|
||||
|
||||
## 输出
|
||||
|
||||
返回包含已解析 JSON 的 `details.json`（如果提供了 `schema`，还会依据它进行校验）。
|
||||
返回 `details.json`，其中包含已解析的 JSON（若提供了 `schema`，还会对其进行验证）。
|
||||
|
||||
## 示例：Lobster 工作流步骤
|
||||
|
||||
@ -115,8 +115,7 @@ openclaw.invoke --tool llm-task --action json --args-json '{
|
||||
|
||||
## 安全说明
|
||||
|
||||
- 该工具是**纯 JSON** 的，并会指示模型只输出 JSON（不使用
|
||||
代码围栏，不带说明文字）。
|
||||
- 在这次运行中，不会向模型暴露任何工具。
|
||||
- 除非你使用 `schema` 进行校验，否则应将输出视为不可信。
|
||||
- 在任何会产生副作用的步骤（发送、发布、exec）之前先设置审批。
|
||||
- 该工具是**仅 JSON** 的，并会指示模型只输出 JSON（不包含代码围栏，也不包含说明性文字）。
|
||||
- 本次运行不会向模型暴露任何工具。
|
||||
- 除非你使用 `schema` 进行验证，否则应将输出视为不受信任。
|
||||
- 在任何有副作用的步骤（send、post、exec）之前放置审批。
|
||||
|
||||
@ -1,37 +1,36 @@
|
||||
---
|
||||
read_when: “You want per-agent sandboxing or per-agent tool allow/deny policies in a multi-agent gateway.”
|
||||
status: active
|
||||
summary: “按智能体的沙箱隔离 + 工具限制、优先级和示例”
|
||||
summary: “每智能体沙箱隔离 + 工具限制、优先级和示例”
|
||||
title: 多智能体沙箱隔离与工具
|
||||
x-i18n:
|
||||
generated_at: "2026-04-05T10:12:15Z"
|
||||
generated_at: "2026-04-23T19:27:35Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 07985f7c8fae860a7b9bf685904903a4a8f90249e95e4179cf0775a1208c0597
|
||||
source_hash: dff5be3e06ca4701adb078cd8ab2eb36a66b0c705e1ab34a4ae470399cde93e5
|
||||
source_path: tools/multi-agent-sandbox-tools.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 多智能体沙箱隔离与工具配置
|
||||
|
||||
在多智能体设置中，每个智能体都可以覆盖全局沙箱隔离和工具
|
||||
策略。本页介绍按智能体的配置、优先级规则以及
|
||||
示例。
|
||||
在多智能体设置中，每个智能体都可以覆盖全局沙箱隔离和工具策略。
|
||||
本页介绍每智能体配置、优先级规则和示例。
|
||||
|
||||
- **沙箱后端和模式**：参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
|
||||
- **沙箱后端与模式**：参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。
|
||||
- **调试被阻止的工具**：参见 [沙箱 vs 工具策略 vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) 和 `openclaw sandbox explain`。
|
||||
- **Elevated exec**：参见 [Elevated Mode](/zh-CN/tools/elevated)。
|
||||
- **Elevated exec**：参见 [Elevated 模式](/zh-CN/tools/elevated)。
|
||||
|
||||
认证是按智能体划分的：每个智能体都从自己的 `agentDir` 认证存储读取，
|
||||
认证按智能体隔离：每个智能体都会从其自身 `agentDir` 下的认证存储读取，
|
||||
路径为 `~/.openclaw/agents/<agentId>/agent/auth-profiles.json`。
|
||||
凭据**不会**在智能体之间共享。绝不要在多个智能体之间复用 `agentDir`。
|
||||
如果你想共享凭据，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir` 中。
|
||||
凭证**不会**在智能体之间共享。绝不要在多个智能体之间复用 `agentDir`。
|
||||
如果你想共享凭证，请将 `auth-profiles.json` 复制到另一个智能体的 `agentDir` 中。
|
||||
|
||||
---
|
||||
|
||||
## 配置示例
|
||||
|
||||
### 示例 1：个人智能体 + 受限家庭智能体
|
||||
### 示例 1：个人 + 受限家庭智能体
|
||||
|
||||
```json
|
||||
{
|
||||
@ -77,8 +76,8 @@ x-i18n:
|
||||
|
||||
**结果：**
|
||||
|
||||
- `main` 智能体：在主机上运行，具有完整工具访问权限
|
||||
- `family` 智能体：在 Docker 中运行（每个智能体一个容器），仅有 `read` 工具
|
||||
- `main` 智能体：在主机上运行，拥有完整工具访问权限
|
||||
- `family` 智能体：在 Docker 中运行（每个智能体一个容器），仅可使用 `read` 工具
|
||||
|
||||
---
|
||||
|
||||
@ -113,7 +112,7 @@ x-i18n:
|
||||
|
||||
---
|
||||
|
||||
### 示例 2b：全局 coding 配置 + 仅限消息的智能体
|
||||
### 示例 2b：全局 coding 配置 + 仅消息智能体
|
||||
|
||||
```json
|
||||
{
|
||||
@ -131,8 +130,8 @@ x-i18n:
|
||||
|
||||
**结果：**
|
||||
|
||||
- 默认智能体会获得 coding 工具
|
||||
- `support` 智能体仅限消息功能（+ Slack 工具）
|
||||
- 默认智能体获得 coding 工具
|
||||
- `support` 智能体仅可使用消息工具（+ Slack 工具）
|
||||
|
||||
---
|
||||
|
||||
@ -152,14 +151,14 @@ x-i18n:
|
||||
"id": "main",
|
||||
"workspace": "~/.openclaw/workspace",
|
||||
"sandbox": {
|
||||
"mode": "off" // 覆盖：main 永不使用沙箱
|
||||
"mode": "off" // 覆盖：main 永不进入沙箱
|
||||
}
|
||||
},
|
||||
{
|
||||
"id": "public",
|
||||
"workspace": "~/.openclaw/workspace-public",
|
||||
"sandbox": {
|
||||
"mode": "all", // 覆盖：public 始终使用沙箱
|
||||
"mode": "all", // 覆盖：public 始终进入沙箱
|
||||
"scope": "agent"
|
||||
},
|
||||
"tools": {
|
||||
@ -176,11 +175,11 @@ x-i18n:
|
||||
|
||||
## 配置优先级
|
||||
|
||||
当同时存在全局（`agents.defaults.*`）和按智能体（`agents.list[].*`）配置时：
|
||||
当全局（`agents.defaults.*`）和智能体专属（`agents.list[].*`）配置同时存在时：
|
||||
|
||||
### 沙箱配置
|
||||
|
||||
按智能体设置会覆盖全局设置：
|
||||
智能体专属设置会覆盖全局设置：
|
||||
|
||||
```
|
||||
agents.list[].sandbox.mode > agents.defaults.sandbox.mode
|
||||
@ -194,29 +193,29 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
|
||||
**说明：**
|
||||
|
||||
- 对于该智能体，`agents.list[].sandbox.{docker,browser,prune}.*` 会覆盖 `agents.defaults.sandbox.{docker,browser,prune}.*`（当沙箱范围解析为 `"shared"` 时会被忽略）。
|
||||
- 对于该智能体，`agents.list[].sandbox.{docker,browser,prune}.*` 会覆盖 `agents.defaults.sandbox.{docker,browser,prune}.*`（当沙箱 scope 解析为 `"shared"` 时会被忽略）。
|
||||
|
||||
### 工具限制
|
||||
|
||||
过滤顺序为：
|
||||
过滤顺序如下：
|
||||
|
||||
1. **工具 profile**（`tools.profile` 或 `agents.list[].tools.profile`）
|
||||
2. **提供商工具 profile**（`tools.byProvider[provider].profile` 或 `agents.list[].tools.byProvider[provider].profile`）
|
||||
1. **工具配置**（`tools.profile` 或 `agents.list[].tools.profile`）
|
||||
2. **provider 工具配置**（`tools.byProvider[provider].profile` 或 `agents.list[].tools.byProvider[provider].profile`）
|
||||
3. **全局工具策略**（`tools.allow` / `tools.deny`）
|
||||
4. **提供商工具策略**（`tools.byProvider[provider].allow/deny`）
|
||||
5. **按智能体的工具策略**（`agents.list[].tools.allow/deny`）
|
||||
6. **智能体提供商策略**（`agents.list[].tools.byProvider[provider].allow/deny`）
|
||||
4. **provider 工具策略**（`tools.byProvider[provider].allow/deny`）
|
||||
5. **智能体专属工具策略**（`agents.list[].tools.allow/deny`）
|
||||
6. **智能体 provider 策略**（`agents.list[].tools.byProvider[provider].allow/deny`）
|
||||
7. **沙箱工具策略**（`tools.sandbox.tools` 或 `agents.list[].tools.sandbox.tools`）
|
||||
8. **Subagent 工具策略**（`tools.subagents.tools`，如果适用）
|
||||
8. **子智能体工具策略**（`tools.subagents.tools`，如果适用）
|
||||
|
||||
每一层都可以进一步限制工具，但不能重新授予之前层级已拒绝的工具。
|
||||
如果设置了 `agents.list[].tools.sandbox.tools`，它会替换该智能体的 `tools.sandbox.tools`。
|
||||
如果设置了 `agents.list[].tools.profile`，它会覆盖该智能体的 `tools.profile`。
|
||||
提供商工具键可以接受 `provider`（例如 `google-antigravity`）或 `provider/model`（例如 `openai/gpt-5.4`）。
|
||||
每一层都可以进一步限制工具，但不能重新授予前面层级已经拒绝的工具。
|
||||
如果设置了 `agents.list[].tools.sandbox.tools`，则它会替换该智能体的 `tools.sandbox.tools`。
|
||||
如果设置了 `agents.list[].tools.profile`，则它会覆盖该智能体的 `tools.profile`。
|
||||
provider 工具键既接受 `provider`（例如 `google-antigravity`），也接受 `provider/model`（例如 `openai/gpt-5.5`）。
|
||||
|
||||
工具策略支持 `group:*` 简写，可展开为多个工具。完整列表参见 [工具组](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)。
|
||||
工具策略支持 `group:*` 简写，可展开为多个工具。完整列表请参见 [工具分组](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#tool-groups-shorthands)。
|
||||
|
||||
按智能体的 Elevated 覆盖（`agents.list[].tools.elevated`）还可以进一步限制特定智能体的 elevated exec。详情参见 [Elevated Mode](/zh-CN/tools/elevated)。
|
||||
每智能体 elevated 覆盖（`agents.list[].tools.elevated`）还可以进一步限制特定智能体的 elevated exec。详情请参见 [Elevated 模式](/zh-CN/tools/elevated)。
|
||||
|
||||
---
|
||||
|
||||
@ -245,7 +244,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
}
|
||||
```
|
||||
|
||||
**之后（具有不同配置的多智能体）：**
|
||||
**之后（使用不同配置的多智能体）：**
|
||||
|
||||
```json
|
||||
{
|
||||
@ -262,7 +261,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
}
|
||||
```
|
||||
|
||||
旧版 `agent.*` 配置会由 `openclaw doctor` 迁移；今后请优先使用 `agents.defaults` + `agents.list`。
|
||||
旧版 `agent.*` 配置可由 `openclaw doctor` 迁移；今后请优先使用 `agents.defaults` + `agents.list`。
|
||||
|
||||
---
|
||||
|
||||
@ -279,7 +278,7 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
}
|
||||
```
|
||||
|
||||
### 安全执行智能体（不允许文件修改）
|
||||
### 安全执行智能体（不允许修改文件）
|
||||
|
||||
```json
|
||||
{
|
||||
@ -302,22 +301,22 @@ agents.list[].sandbox.prune.* > agents.defaults.sandbox.prune.*
|
||||
}
|
||||
```
|
||||
|
||||
此配置中的 `sessions_history` 仍然返回有界、已净化的 recall
|
||||
视图，而不是原始 transcript 倾倒。助手 recall 会剥离 thinking 标签、
|
||||
`<relevant-memories>` 脚手架、纯文本工具调用 XML 载荷
|
||||
此配置中的 `sessions_history` 仍然返回有界、已净化的回忆视图，
|
||||
而不是原始转录转储。助手回忆会去除 thinking 标签、
|
||||
`<relevant-memories>` 脚手架、纯文本工具调用 XML 负载
|
||||
（包括 `<tool_call>...</tool_call>`、
|
||||
`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、
|
||||
`<function_calls>...</function_calls>` 以及被截断的工具调用块）、
|
||||
降级后的工具调用脚手架、泄露的 ASCII/全角模型控制
|
||||
token，以及格式错误的 MiniMax 工具调用 XML，然后才进行脱敏/截断。
|
||||
降级后的工具调用脚手架、泄露的 ASCII/全角模型控制 token，
|
||||
以及格式错误的 MiniMax 工具调用 XML，然后再执行脱敏/截断。
|
||||
|
||||
---
|
||||
|
||||
## 常见陷阱：“non-main”
|
||||
|
||||
`agents.defaults.sandbox.mode: "non-main"` 基于 `session.mainKey`（默认值为 `"main"`），
|
||||
而不是智能体 id。群组/渠道会话始终拥有自己的 key，因此它们
|
||||
会被视为 non-main，并进入沙箱。如果你希望某个智能体永不进入
|
||||
`agents.defaults.sandbox.mode: "non-main"` 基于 `session.mainKey`（默认 `"main"`），
|
||||
而不是智能体 ID。群组/渠道会话始终拥有自己的键，因此它们
|
||||
会被视为非 main，并会进入沙箱。如果你希望某个智能体永不进入
|
||||
沙箱，请设置 `agents.list[].sandbox.mode: "off"`。
|
||||
|
||||
---
|
||||
@ -352,29 +351,29 @@ token，以及格式错误的 MiniMax 工具调用 XML，然后才进行脱敏/
|
||||
|
||||
## 故障排除
|
||||
|
||||
### 尽管设置了 `mode: "all"`，智能体仍未进入沙箱
|
||||
### 尽管设置了 `mode: "all"`，智能体却没有进入沙箱
|
||||
|
||||
- 检查是否存在覆盖它的全局 `agents.defaults.sandbox.mode`
|
||||
- 按智能体配置优先级更高，因此请设置 `agents.list[].sandbox.mode: "all"`
|
||||
- 检查是否存在会覆盖它的全局 `agents.defaults.sandbox.mode`
|
||||
- 智能体专属配置优先级更高，因此请设置 `agents.list[].sandbox.mode: "all"`
|
||||
|
||||
### 尽管在拒绝列表中，工具仍然可用
|
||||
### 尽管在 deny 列表中，工具仍然可用
|
||||
|
||||
- 检查工具过滤顺序：全局 → 智能体 → 沙箱 → subagent
|
||||
- 每一层只能进一步限制，不能重新授予
|
||||
- 检查工具过滤顺序：全局 → 智能体 → 沙箱 → 子智能体
|
||||
- 每一层都只能进一步限制，不能重新授予
|
||||
- 通过日志验证：`[tools] filtering tools for agent:${agentId}`
|
||||
|
||||
### 容器没有按智能体隔离
|
||||
|
||||
- 在按智能体的沙箱配置中设置 `scope: "agent"`
|
||||
- 默认值是 `"session"`，这会为每个会话创建一个容器
|
||||
- 在智能体专属沙箱配置中设置 `scope: "agent"`
|
||||
- 默认值是 `"session"`，即每个会话创建一个容器
|
||||
|
||||
---
|
||||
|
||||
## 另见
|
||||
## 另请参见
|
||||
|
||||
- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整的沙箱参考（模式、范围、后端、镜像）
|
||||
- [沙箱隔离](/zh-CN/gateway/sandboxing) -- 完整沙箱参考（模式、scope、后端、镜像）
|
||||
- [沙箱 vs 工具策略 vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated) -- 调试“为什么这个被阻止了？”
|
||||
- [Elevated Mode](/zh-CN/tools/elevated)
|
||||
- [Elevated 模式](/zh-CN/tools/elevated)
|
||||
- [多智能体路由](/zh-CN/concepts/multi-agent)
|
||||
- [沙箱配置](/zh-CN/gateway/configuration-reference#agentsdefaultssandbox)
|
||||
- [会话管理](/zh-CN/concepts/session)
|
||||
|
||||
@ -5,31 +5,31 @@ read_when:
|
||||
summary: 斜杠命令：文本与原生、配置以及支持的命令
|
||||
title: 斜杠命令
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T12:50:41Z"
|
||||
generated_at: "2026-04-23T19:28:04Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 13290dcdf649ae66603a92a0aca68460bb63ff476179cc2dded796aaa841d66c
|
||||
source_hash: 62af79d351db2ef6a62df570300bb191c7d5078ef5da2308b4a9d99a56ca7863
|
||||
source_path: tools/slash-commands.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 斜杠命令
|
||||
|
||||
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。
|
||||
仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是别名）。
|
||||
命令由 Gateway 网关处理。大多数命令必须作为**独立**消息发送，并且以 `/` 开头。
|
||||
仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是其别名）。
|
||||
|
||||
这里有两个相关系统：
|
||||
|
||||
- **命令**：独立的 `/...` 消息。
|
||||
- **指令**：`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
|
||||
- 指令会在模型看到消息之前从消息中剥离。
|
||||
- 在普通聊天消息中（不是仅含指令的消息），它们会被视为“内联提示”，且**不会**持久化会话设置。
|
||||
- 在仅含指令的消息中（消息只包含指令），它们会持久化到会话，并回复一条确认信息。
|
||||
- 指令只会对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。
|
||||
未授权发送者看到的指令会被当作普通文本处理。
|
||||
- 指令会在模型看到消息前被剥离。
|
||||
- 在普通聊天消息中（不是仅包含指令的消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
|
||||
- 在仅包含指令的消息中（消息只包含指令），它们会持久化到会话中，并回复一个确认消息。
|
||||
- 指令仅对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的 allowlist；否则，授权来自渠道 allowlist/配对以及 `commands.useAccessGroups`。
|
||||
未授权发送者发送的指令会被当作普通文本处理。
|
||||
|
||||
还有一些**内联快捷方式**（仅限允许列表内/已授权发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
它们会立即运行，在模型看到消息之前被剥离，剩余文本则继续走正常流程。
|
||||
还有少量**内联快捷命令**（仅限 allowlist/已授权发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
它们会立即运行，并在模型看到消息前被剥离，剩余文本继续走正常流程。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -59,86 +59,86 @@ x-i18n:
|
||||
```
|
||||
|
||||
- `commands.text`（默认 `true`）启用在聊天消息中解析 `/...`。
|
||||
- 在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。
|
||||
- 在不支持原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。
|
||||
- `commands.native`（默认 `"auto"`）注册原生命令。
|
||||
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生能力的提供商忽略。
|
||||
- 自动：在 Discord/Telegram 上开启；在 Slack 上关闭（直到你添加 slash commands）；对于不支持原生命令的提供商则忽略。
|
||||
- 设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。
|
||||
- `false` 会在启动时清除 Discord/Telegram 上此前已注册的命令。Slack 命令在 Slack 应用中管理，不会被自动移除。
|
||||
- `commands.nativeSkills`（默认 `"auto"`）会在支持时以原生方式注册 **skill** 命令。
|
||||
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。
|
||||
- `false` 会在启动时清除之前在 Discord/Telegram 上注册的命令。Slack 命令由 Slack 应用管理，不会自动移除。
|
||||
- `commands.nativeSkills`（默认 `"auto"`）在支持时以原生方式注册**技能**命令。
|
||||
- 自动：在 Discord/Telegram 上开启；在 Slack 上关闭（Slack 需要为每个技能单独创建一个 slash 命令）。
|
||||
- 设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
|
||||
- `commands.bash`（默认 `false`）启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
|
||||
- `commands.bash`（默认 `false`）启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` allowlist）。
|
||||
- `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多久（`0` 表示立即转入后台）。
|
||||
- `commands.config`（默认 `false`）启用 `/config`（读取/写入 `openclaw.json`）。
|
||||
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入由 OpenClaw 管理的 `mcp.servers` 下的 MCP 配置）。
|
||||
- `commands.plugins`（默认 `false`）启用 `/plugins`（plugin 发现/状态，以及安装 + 启用/禁用控制）。
|
||||
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 配置）。
|
||||
- `commands.plugins`（默认 `false`）启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。
|
||||
- `commands.debug`（默认 `false`）启用 `/debug`（仅运行时覆盖）。
|
||||
- `commands.restart`（默认 `true`）启用 `/restart` 以及 Gateway 网关重启工具操作。
|
||||
- `commands.ownerAllowFrom`（可选）设置仅限 owner 的命令/工具界面的显式 owner 允许列表。这与 `commands.allowFrom` 分开。
|
||||
- 每个渠道的 `channels.<channel>.commands.enforceOwnerForCommands`（可选，默认 `false`）会让仅限 owner 的命令在该界面上要求**owner 身份**才能运行。设为 `true` 时，发送者必须匹配已解析的 owner 候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生 owner 元数据），或者在内部消息渠道上拥有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的 owner 候选列表，**都不足够**——该渠道上的仅限 owner 命令会以默认拒绝方式失败。如果你希望仅限 owner 的命令只由 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。
|
||||
- `commands.ownerDisplay` 控制 owner id 在系统提示中的显示方式：`raw` 或 `hash`。
|
||||
- `commands.ownerDisplaySecret` 可选地设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
|
||||
- `commands.allowFrom`（可选）设置用于命令授权的按提供商区分的允许列表。配置后，它会成为命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。
|
||||
- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令执行允许列表/策略。
|
||||
- `commands.ownerAllowFrom`（可选）为仅限 owner 的命令/工具界面设置显式 owner allowlist。这与 `commands.allowFrom` 分开。
|
||||
- 每个渠道的 `channels.<channel>.commands.enforceOwnerForCommands`（可选，默认 `false`）会使该界面上的仅限 owner 命令必须由**owner 身份**执行。当其为 `true` 时，发送者必须匹配某个已解析的 owner 候选者（例如 `commands.ownerAllowFrom` 中的某个条目，或提供商原生 owner 元数据），或者在内部消息渠道上持有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的 owner 候选列表，**都不足以**满足要求——该渠道上的仅限 owner 命令会以封闭方式失败。如果你希望仅限 owner 的命令只由 `ownerAllowFrom` 和标准命令 allowlist 控制，请保持关闭。
|
||||
- `commands.ownerDisplay` 控制 owner id 在系统提示词中的显示方式：`raw` 或 `hash`。
|
||||
- `commands.ownerDisplaySecret` 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
|
||||
- `commands.allowFrom`（可选）为命令授权设置按提供商划分的 allowlist。配置后，它将成为命令和指令的唯一授权来源（渠道 allowlist/配对及 `commands.useAccessGroups` 将被忽略）。全局默认值使用 `"*"`；提供商专用键会覆盖它。
|
||||
- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令强制执行 allowlist/策略。
|
||||
|
||||
## 命令列表
|
||||
|
||||
当前的事实来源：
|
||||
当前事实来源：
|
||||
|
||||
- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts`
|
||||
- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
|
||||
- plugin 命令来自 plugin 的 `registerCommand()` 调用
|
||||
- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的 plugin
|
||||
- 插件命令来自插件中的 `registerCommand()` 调用
|
||||
- 你的 Gateway 网关上实际可用的命令仍取决于配置标志、渠道界面，以及已安装/启用的插件
|
||||
|
||||
### 核心内置命令
|
||||
|
||||
当前可用的内置命令：
|
||||
|
||||
- `/new [model]` 启动一个新会话；`/reset` 是重置别名。
|
||||
- `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并原地重新运行启动/系统提示加载。
|
||||
- `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 id，并原地重新运行 startup/system-prompt 加载。
|
||||
- `/compact [instructions]` 压缩会话上下文。参见 [/concepts/compaction](/zh-CN/concepts/compaction)。
|
||||
- `/stop` 中止当前运行。
|
||||
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
|
||||
- `/think <level>` 设置思考级别。可选项来自当前模型的活跃提供商配置文件；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也可能包含 `xhigh`、`adaptive`、`max` 或仅在支持时提供的二元 `on` 等自定义级别。别名：`/thinking`、`/t`。
|
||||
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期。
|
||||
- `/think <level>` 设置 thinking 级别。可选项来自活动模型的提供商配置档；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，而 `xhigh`、`adaptive`、`max` 或二元 `on` 等自定义级别仅在支持时可用。别名：`/thinking`、`/t`。
|
||||
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
|
||||
- `/trace on|off` 切换当前会话的 plugin 跟踪输出。
|
||||
- `/trace on|off` 切换当前会话的插件追踪输出。
|
||||
- `/fast [status|on|off]` 显示或设置快速模式。
|
||||
- `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
|
||||
- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。
|
||||
- `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。
|
||||
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
|
||||
- `/model [name|#|status]` 显示或设置模型。
|
||||
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商，或列出某个提供商的模型。
|
||||
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及诸如 `debounce:2s cap:25 drop:summarize` 之类的选项。
|
||||
- `/help` 显示简短帮助摘要。
|
||||
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及如 `debounce:2s cap:25 drop:summarize` 之类的选项。
|
||||
- `/help` 显示简要帮助摘要。
|
||||
- `/commands` 显示生成的命令目录。
|
||||
- `/tools [compact|verbose]` 显示当前智能体此刻可用的能力。
|
||||
- `/status` 显示运行时状态，包括 `Runtime`/`Runner` 标签，以及可用时的提供商使用情况/配额。
|
||||
- `/tasks` 列出当前会话中活跃/最近的后台任务。
|
||||
- `/context [list|detail|json]` 说明上下文是如何组装的。
|
||||
- `/tools [compact|verbose]` 显示当前智能体此刻可以使用的内容。
|
||||
- `/status` 显示运行时状态，包括 `Runtime`/`Runner` 标签，以及可用时的提供商用量/配额。
|
||||
- `/tasks` 列出当前会话的活动/最近后台任务。
|
||||
- `/context [list|detail|json]` 解释上下文是如何组装的。
|
||||
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
|
||||
- `/export-trajectory [path]` 为当前会话导出 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。别名：`/trajectory`。
|
||||
- `/export-trajectory [path]` 为当前会话导出一个 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。别名：`/trajectory`。
|
||||
- `/whoami` 显示你的发送者 id。别名：`/id`。
|
||||
- `/skill <name> [input]` 按名称运行一个 skill。
|
||||
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
|
||||
- `/skill <name> [input]` 按名称运行一个 Skills。
|
||||
- `/allowlist [list|add|remove] ...` 管理 allowlist 条目。仅文本。
|
||||
- `/approve <id> <decision>` 处理 exec 审批提示。
|
||||
- `/btw <question>` 提出一个旁支问题，而不改变后续会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。
|
||||
- `/btw <question>` 在不改变未来会话上下文的情况下提出一个旁支问题。参见 [/tools/btw](/zh-CN/tools/btw)。
|
||||
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
|
||||
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
|
||||
- `/focus <target>` 将当前 Discord 线程或 Telegram 主题/会话绑定到一个会话目标。
|
||||
- `/focus <target>` 将当前 Discord 线程或 Telegram topic/conversation 绑定到一个会话目标。
|
||||
- `/unfocus` 移除当前绑定。
|
||||
- `/agents` 列出当前会话中线程绑定的智能体。
|
||||
- `/agents` 列出当前会话中绑定到线程的智能体。
|
||||
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
|
||||
- `/steer <id|#> <message>` 向正在运行的子智能体发送引导。别名：`/tell`。
|
||||
- `/steer <id|#> <message>` 向一个正在运行的子智能体发送引导。别名：`/tell`。
|
||||
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限 owner。需要 `commands.config: true`。
|
||||
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限 owner。需要 `commands.mcp: true`。
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改 plugin 状态。`/plugin` 是别名。写入操作仅限 owner。需要 `commands.plugins: true`。
|
||||
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写入操作仅限 owner。需要 `commands.plugins: true`。
|
||||
- `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限 owner。需要 `commands.debug: true`。
|
||||
- `/usage off|tokens|full|cost` 控制每次响应的 usage 页脚，或打印本地成本摘要。
|
||||
- `/usage off|tokens|full|cost` 控制每次响应的用量页脚，或输出本地成本摘要。
|
||||
- `/tts on|off|status|provider|limit|summary|audio|help` 控制 TTS。参见 [/tools/tts](/zh-CN/tools/tts)。
|
||||
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可将其禁用。
|
||||
- `/restart` 在启用时重启 OpenClaw。默认启用；设置 `commands.restart: false` 可禁用。
|
||||
- `/activation mention|always` 设置群组激活模式。
|
||||
- `/send on|off|inherit` 设置发送策略。仅限 owner。
|
||||
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
|
||||
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true`，以及 `tools.elevated` allowlist。
|
||||
- `!poll [sessionId]` 检查后台 bash 作业。
|
||||
- `!stop [sessionId]` 停止后台 bash 作业。
|
||||
|
||||
@ -151,87 +151,87 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
- `/dock-slack`（别名：`/dock_slack`）
|
||||
- `/dock-telegram`（别名：`/dock_telegram`）
|
||||
|
||||
### 内置 plugin 命令
|
||||
### 内置插件命令
|
||||
|
||||
内置 plugin 可以添加更多斜杠命令。此仓库中当前的内置命令：
|
||||
内置插件可以添加更多 slash commands。此仓库中当前的内置命令：
|
||||
|
||||
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
- `/dreaming [on|off|status|help]` 切换 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [Pairing](/zh-CN/channels/pairing)。
|
||||
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
|
||||
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
|
||||
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称为 `/talkvoice`。
|
||||
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
|
||||
- 仅 QQ Bot 的命令：
|
||||
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex app-server Harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
|
||||
- 仅 QQ Bot 命令：
|
||||
- `/bot-ping`
|
||||
- `/bot-version`
|
||||
- `/bot-help`
|
||||
- `/bot-upgrade`
|
||||
- `/bot-logs`
|
||||
|
||||
### 动态 skill 命令
|
||||
### 动态 Skills 命令
|
||||
|
||||
用户可调用的 Skills 也会作为斜杠命令公开：
|
||||
可由用户调用的 Skills 也会作为 slash commands 暴露：
|
||||
|
||||
- `/skill <name> [input]` 始终可作为通用入口点使用。
|
||||
- 当 skill/plugin 注册它们时，Skills 也可能作为直接命令出现，例如 `/prose`。
|
||||
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
|
||||
- 当 Skills/插件注册它们时，Skills 也可能直接显示为 `/prose` 这样的命令。
|
||||
- 原生 Skills 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- 命令接受一个可选的 `:`，放在命令和参数之间（例如 `/think: high`、`/send: on`、`/help:`）。
|
||||
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。
|
||||
- 如需查看完整的提供商 usage 明细，请使用 `openclaw status --usage`。
|
||||
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
|
||||
- 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
|
||||
- `/usage` 控制每次响应的 usage 页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。
|
||||
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
|
||||
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的 plugin 规格：本地路径/归档、npm 包，或 `clawhub:<pkg>`。
|
||||
- `/plugins enable|disable` 会更新 plugin 配置，并且可能提示你重启。
|
||||
- 仅限 Discord 的原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。
|
||||
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求实际线程绑定已启用（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
|
||||
- 命令接受命令与参数之间可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
|
||||
- `/new <model>` 接受模型别名、`provider/model`，或提供商名称（模糊匹配）；如果没有匹配项，则该文本会被视为消息正文。
|
||||
- 如需完整的提供商用量明细，请使用 `openclaw status --usage`。
|
||||
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道的 `configWrites`。
|
||||
- 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也遵循目标账号的 `configWrites`。
|
||||
- `/usage` 控制每次响应的用量页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。
|
||||
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。
|
||||
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件规格：本地路径/压缩包、npm 包，或 `clawhub:<pkg>`。
|
||||
- `/plugins enable|disable` 会更新插件配置，并且可能提示你重启。
|
||||
- 仅 Discord 原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。
|
||||
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求有效启用线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
|
||||
- ACP 命令参考和运行时行为： [ACP Agents](/zh-CN/tools/acp-agents)。
|
||||
- `/verbose` 旨在用于调试和额外可见性；正常使用时请保持**关闭**。
|
||||
- `/trace` 比 `/verbose` 更窄：它只显示由 plugin 拥有的 trace/debug 行，并保持普通详细工具输出关闭。
|
||||
- `/fast on|off` 会持久化一个会话级覆盖。使用 Sessions UI 中的 `inherit` 选项可清除它，并回退到配置默认值。
|
||||
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括使用 OAuth 身份验证的流量）会映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
|
||||
- 相关时仍会显示工具失败摘要，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时才包含。
|
||||
- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中具有风险：它们可能会暴露你原本无意公开的内部推理、工具输出或 plugin 诊断信息。建议保持关闭，尤其是在群聊中。
|
||||
- `/verbose` 用于调试和额外可见性；在正常使用中请保持**关闭**。
|
||||
- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具输出关闭。
|
||||
- `/fast on|off` 会持久化一个会话覆盖。使用 Sessions UI 的 `inherit` 选项可清除该覆盖并回退到配置默认值。
|
||||
- `/fast` 是提供商相关的：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接的公共 Anthropic 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，则会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
|
||||
- 工具失败摘要在相关时仍会显示，但详细失败文本仅会在 `/verbose` 为 `on` 或 `full` 时包含。
|
||||
- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中有风险：它们可能暴露你本无意公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
|
||||
- `/model` 会立即持久化新的会话模型。
|
||||
- 如果智能体处于空闲状态，下一次运行会立刻使用它。
|
||||
- 如果智能体处于空闲状态，下一次运行会立即使用它。
|
||||
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点重启到新模型。
|
||||
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续的重试机会或下一个用户轮次。
|
||||
- **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
|
||||
- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。
|
||||
- **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入在普通消息中时也可工作，并会在模型看到剩余文本前被剥离。
|
||||
- 例如：`hey /status` 会触发状态回复，而剩余文本会继续走正常流程。
|
||||
- 如果工具活动或回复输出已经开始，则待处理切换可能会一直排队，直到之后出现重试机会或下一个用户轮次。
|
||||
- **快速路径：** 来自 allowlist 发送者的纯命令消息会被立即处理（绕过队列 + 模型）。
|
||||
- **群组提及门控：** 来自 allowlist 发送者的纯命令消息会绕过提及要求。
|
||||
- **内联快捷命令（仅限 allowlist 发送者）：** 某些命令在嵌入普通消息时也能工作，并会在模型看到剩余文本前被剥离。
|
||||
- 示例：`hey /status` 会触发状态回复，而剩余文本继续经过正常流程。
|
||||
- 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
|
||||
- 未授权的纯命令消息会被静默忽略，而内联 `/...` 标记会被当作普通文本。
|
||||
- **Skill 命令：** `user-invocable` Skills 也会公开为斜杠命令。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突时会附加数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 单独创建命令时，这会很有用）。
|
||||
- 默认情况下，skill 命令会作为普通请求转发给模型。
|
||||
- Skills 可以选择声明 `command-dispatch: tool`，以将命令直接路由到工具（确定性，不经过模型）。
|
||||
- 示例：`/prose`（OpenProse plugin）——参见 [OpenProse](/zh-CN/prose)。
|
||||
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时也会使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。
|
||||
- 未授权的纯命令消息会被静默忽略，而内联 `/...` 令牌会被当作普通文本处理。
|
||||
- **Skills 命令：** `user-invocable` Skills 也会作为 slash commands 暴露。名称会被规范化为 `a-z0-9_`（最大 32 个字符）；发生冲突时会加数字后缀（例如 `_2`）。
|
||||
- `/skill <name> [input]` 按名称运行一个 Skills（当原生命令限制阻止为每个技能创建命令时，这很有用）。
|
||||
- 默认情况下，Skills 命令会作为普通请求转发给模型。
|
||||
- Skills 可选择声明 `command-dispatch: tool`，将该命令直接路由到工具（确定性，无需模型）。
|
||||
- 示例：`/prose`（OpenProse 插件）——参见 [OpenProse](/zh-CN/prose)。
|
||||
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必填参数时，也会显示按钮菜单）。Telegram 和 Slack 会在某个命令支持选项且你省略参数时显示按钮菜单。
|
||||
|
||||
## `/tools`
|
||||
|
||||
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体现在在这次对话中能使用什么**。
|
||||
`/tools` 回答的是运行时问题，而不是配置问题：**这个智能体现在在此对话中可以使用什么**。
|
||||
|
||||
- 默认的 `/tools` 是紧凑模式，便于快速浏览。
|
||||
- 默认的 `/tools` 是紧凑模式，针对快速浏览进行了优化。
|
||||
- `/tools verbose` 会添加简短说明。
|
||||
- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。
|
||||
- 结果是会话作用域的，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
|
||||
- `/tools` 包含那些在运行时实际可达的工具，包括核心工具、已连接的 plugin 工具以及由渠道拥有的工具。
|
||||
- 支持参数的原生命令界面会暴露同样的模式切换，即 `compact|verbose`。
|
||||
- 结果是按会话作用域计算的，因此更改智能体、渠道、线程、发送者授权或模型，都可能改变输出。
|
||||
- `/tools` 包含运行时实际可访问的工具，包括核心工具、已连接的插件工具以及渠道自有工具。
|
||||
|
||||
如需编辑 profile 和覆盖项，请使用 Control UI 的工具面板或配置/目录界面，而不要把 `/tools` 当作静态目录。
|
||||
对于配置档和覆盖编辑，请使用控制 UI 的 Tools 面板或配置/目录界面，而不要把 `/tools` 当作静态目录。
|
||||
|
||||
## Usage 界面（各处显示什么）
|
||||
## 用量界面（哪些内容显示在哪里）
|
||||
|
||||
- **提供商 usage/配额**（例如：“Claude 剩余 80%”）会在启用 usage 跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一为“剩余百分比”；对于 MiniMax，仅剩余值的百分比字段会在显示前反转，而 `model_remains` 响应会优先使用聊天模型条目以及带模型标签的计划标签。
|
||||
- `/status` 中的**Token/cache 行**在实时会话快照信息稀少时，可以回退到最近的转录 usage 条目。现有的非零实时值仍然优先，而转录回退也可以在存储总量缺失或更小时恢复当前活动运行时模型标签以及一个更偏向 prompt 的较大总量。
|
||||
- **Runtime 与 runner：** `/status` 用 `Runtime` 报告生效的执行路径和沙箱状态，用 `Runner` 报告实际运行会话的是谁：内嵌 Pi、基于 CLI 的提供商，还是 ACP harness/backend。
|
||||
- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到正常回复后）。
|
||||
- `/model status` 关注的是**模型/凭证/端点**，不是 usage。
|
||||
- **提供商用量/配额**（例如：“Claude 剩余 80%”）会在启用用量跟踪时出现在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一标准化为“剩余百分比”；对于 MiniMax，会在显示前反转仅剩余百分比字段，而 `model_remains` 响应会优先使用聊天模型条目和带模型标签的计划标签。
|
||||
- 当实时会话快照信息稀疏时，`/status` 中的 **token/cache 行** 可以回退到最近的转录用量条目。已有的非零实时值仍然优先，而转录回退也可以在已存储总量缺失或更小时恢复活动运行时模型标签以及更大的、面向提示词的总量。
|
||||
- **Runtime 与 runner：** `/status` 使用 `Runtime` 表示有效执行路径和沙箱状态，使用 `Runner` 表示实际运行该会话的是谁：嵌入式 Pi、由 CLI 支持的提供商，还是 ACP Harness/后端。
|
||||
- **每次响应的 token/cost** 由 `/usage off|tokens|full` 控制（追加在普通回复后面）。
|
||||
- `/model status` 关注的是**模型/认证/端点**，而不是用量。
|
||||
|
||||
## 模型选择（`/model`）
|
||||
|
||||
@ -239,29 +239,29 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
```
|
||||
/model
|
||||
/model list
|
||||
/model 3
|
||||
/model openai/gpt-5.4
|
||||
/model openai/gpt-5.5
|
||||
/model opus@anthropic:default
|
||||
/model status
|
||||
```
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。
|
||||
- `/model` 和 `/model list` 会显示一个紧凑的、带编号的选择器（模型家族 + 可用提供商）。
|
||||
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉框以及一个提交步骤。
|
||||
- `/model <#>` 会从该选择器中选择（并在可能时优先使用当前提供商）。
|
||||
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用。
|
||||
- `/model <#>` 会从该选择器中选择（并在可能时优先当前提供商）。
|
||||
- `/model status` 会显示详细视图，包括配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用的话。
|
||||
|
||||
## 调试覆盖项
|
||||
## 调试覆盖
|
||||
|
||||
`/debug` 允许你设置**仅运行时**的配置覆盖项（内存中，不写磁盘）。仅限 owner。默认禁用；通过 `commands.debug: true` 启用。
|
||||
`/debug` 允许你设置**仅运行时**配置覆盖（存于内存，不写磁盘）。仅限 owner。默认禁用；使用 `commands.debug: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
```
|
||||
/debug show
|
||||
/debug set messages.responsePrefix="[openclaw]"
|
||||
/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
|
||||
@ -269,14 +269,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
/debug reset
|
||||
```
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- 覆盖项会立即应用到新的配置读取中，但**不会**写入 `openclaw.json`。
|
||||
- 使用 `/debug reset` 清除所有覆盖项，并恢复到磁盘上的配置。
|
||||
- 覆盖会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。
|
||||
- 使用 `/debug reset` 可清除所有覆盖，并返回磁盘上的配置。
|
||||
|
||||
## Plugin 跟踪输出
|
||||
## 插件追踪输出
|
||||
|
||||
`/trace` 允许你切换**会话作用域的 plugin trace/debug 行**，而无需开启完整详细模式。
|
||||
`/trace` 允许你切换**按会话作用域**的插件 trace/debug 行，而无需开启完整详细模式。
|
||||
|
||||
示例：
|
||||
|
||||
@ -286,22 +286,22 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
/trace off
|
||||
```
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- 不带参数的 `/trace` 会显示当前会话的 trace 状态。
|
||||
- `/trace on` 会为当前会话启用 plugin trace 行。
|
||||
- `/trace off` 会再次将其关闭。
|
||||
- Plugin trace 行可能会出现在 `/status` 中，也可能作为普通助手回复之后的后续诊断消息出现。
|
||||
- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时的配置覆盖项。
|
||||
- `/trace` 不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。
|
||||
- 不带参数的 `/trace` 会显示当前会话的追踪状态。
|
||||
- `/trace on` 会为当前会话启用插件追踪行。
|
||||
- `/trace off` 会再次将其禁用。
|
||||
- 插件追踪行可能出现在 `/status` 中，也可能作为普通助手回复之后的附加诊断消息出现。
|
||||
- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时的配置覆盖。
|
||||
- `/trace` 也不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。
|
||||
|
||||
## 配置更新
|
||||
|
||||
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限 owner。默认禁用；通过 `commands.config: true` 启用。
|
||||
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限 owner。默认禁用；使用 `commands.config: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
```text
|
||||
```
|
||||
/config show
|
||||
/config show messages.responsePrefix
|
||||
/config get messages.responsePrefix
|
||||
@ -309,14 +309,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
/config unset messages.responsePrefix
|
||||
```
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- 写入前会校验配置；无效更改会被拒绝。
|
||||
- `/config` 更新会在重启后继续保留。
|
||||
- 写入前会对配置进行验证；无效更改会被拒绝。
|
||||
- `/config` 更新会在重启后保持生效。
|
||||
|
||||
## MCP 更新
|
||||
|
||||
`/mcp` 会将 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers` 下。仅限 owner。默认禁用；通过 `commands.mcp: true` 启用。
|
||||
`/mcp` 会在 `mcp.servers` 下写入由 OpenClaw 管理的 MCP 服务器定义。仅限 owner。默认禁用；使用 `commands.mcp: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -327,14 +327,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
/mcp unset context7
|
||||
```
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。
|
||||
- 运行时适配器决定哪些传输方式实际上可执行。
|
||||
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是存储在由 Pi 拥有的项目设置中。
|
||||
- 运行时适配器决定哪些传输实际上可执行。
|
||||
|
||||
## Plugin 更新
|
||||
## 插件更新
|
||||
|
||||
`/plugins` 允许操作员检查已发现的 plugin，并在配置中切换启用状态。只读流程可使用 `/plugin` 作为别名。默认禁用；通过 `commands.plugins: true` 启用。
|
||||
`/plugins` 允许操作员检查已发现的插件，并在配置中切换启用状态。只读流程可使用 `/plugin` 作为别名。默认禁用；使用 `commands.plugins: true` 启用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -346,36 +346,36 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
/plugins disable context7
|
||||
```
|
||||
|
||||
注意：
|
||||
说明：
|
||||
|
||||
- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的 plugin 发现。
|
||||
- `/plugins enable|disable` 只更新 plugin 配置；不会安装或卸载 plugin。
|
||||
- 在启用/禁用变更后，重启 Gateway 网关以使其生效。
|
||||
- `/plugins list` 和 `/plugins show` 会根据当前工作区和磁盘配置执行真实的插件发现。
|
||||
- `/plugins enable|disable` 只更新插件配置；它不会安装或卸载插件。
|
||||
- 在启用/禁用变更后，请重启 Gateway 网关以应用它们。
|
||||
|
||||
## 界面说明
|
||||
|
||||
- **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有各自的会话）。
|
||||
- **文本命令** 在正常聊天会话中运行（私信共享 `main`，群组拥有各自独立会话）。
|
||||
- **原生命令** 使用隔离会话：
|
||||
- Discord：`agent:<agentId>:discord:slash:<userId>`
|
||||
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
|
||||
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位到聊天会话）
|
||||
- **`/stop`** 面向当前活动聊天会话，因此它可以中止当前运行。
|
||||
- **Slack：** `channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时的 Block Kit 按钮形式提供。
|
||||
- Slack 原生命令例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本形式的 `/status` 在 Slack 消息中仍然可用。
|
||||
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 指向聊天会话）
|
||||
- **`/stop`** 会指向活动聊天会话，以便中止当前运行。
|
||||
- **Slack：** `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果启用 `commands.native`，则必须为每个内置命令创建一个 Slack slash 命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时 Block Kit 按钮形式投递。
|
||||
- Slack 原生例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍然可用。
|
||||
|
||||
## BTW 旁支问题
|
||||
|
||||
`/btw` 是一个关于当前会话的快速**旁支问题**。
|
||||
`/btw` 是一个关于当前会话的快捷**旁支问题**。
|
||||
|
||||
与普通聊天不同：
|
||||
|
||||
- 它会使用当前会话作为背景上下文，
|
||||
- 它会作为一个独立的**无工具**一次性调用运行，
|
||||
- 它不会改变后续会话上下文，
|
||||
- 它以一个独立的**无工具**一次性调用运行，
|
||||
- 它不会改变未来的会话上下文，
|
||||
- 它不会写入转录历史，
|
||||
- 它会作为实时旁路结果传递，而不是普通助手消息。
|
||||
- 它会以实时旁支结果的形式投递，而不是普通助手消息。
|
||||
|
||||
这使得 `/btw` 在你希望主任务继续进行的同时，临时获得一个澄清时非常有用。
|
||||
这使得 `/btw` 在你希望获得临时澄清、同时主任务继续进行时非常有用。
|
||||
|
||||
示例：
|
||||
|
||||
@ -383,4 +383,4 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
|
||||
/btw what are we doing right now?
|
||||
```
|
||||
|
||||
有关完整行为和客户端 UX 细节，请参见 [BTW Side Questions](/zh-CN/tools/btw)。
|
||||
完整行为和客户端 UX 细节请参见 [BTW Side Questions](/zh-CN/tools/btw)。
|
||||
|
||||
Loading…
Reference in New Issue
Block a user