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

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-29 21:39:00 +00:00
parent 7cdc0e2fe0
commit 6982cf3775
7 changed files with 823 additions and 399 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

113
docs/zh-CN/automation/index.md
View File

@ -1,20 +1,20 @@
---
read_when:
- 决定如何使用 OpenClaw 自动化工作
- 在心跳、cron、钩子和长期指令之间选择
- 在 Heartbeat、cron、跟进承诺、钩子和常驻指令之间选择
- 寻找合适的自动化入口点
summary: 自动化机制概览：任务、定时任务、钩子、常驻指令和任务流
summary: 自动化机制概览：任务、cron、钩子、常设指令和任务流
title: 自动化与任务
x-i18n:
generated_at: "2026-04-29T09:12:56Z"
generated_at: "2026-04-29T21:36:54Z"
model: gpt-5.5
provider: openai
source_hash: da79bdd32a231f90850697b94bf061a778e9d0ad81420119ccd3fa0d3bc16fc1
source_hash: a2465c39f21db8bcb98f980a2c4b2c03018dddd5f43de59d8bf6ce0d6e97d9ef
source_path: automation/index.md
workflow: 16
---
OpenClaw 通过任务、计划作业、事件钩子和常设指令在后台运行工作。本页帮助你选择合适的机制，并了解它们如何配合。
OpenClaw 通过任务、定时任务、推断式跟进承诺、事件钩子和长期指令在后台运行工作。本页帮助你选择合适的机制，并理解它们如何协同工作。
## 快速决策指南
@ -25,6 +25,7 @@ flowchart TD
START --> Q3{Orchestrate multi-step flows?}
START --> Q4{React to lifecycle events?}
START --> Q5{Give the agent persistent instructions?}
START --> Q6{Remember a natural follow-up?}
Q1 -->|Yes| Q1a{Exact timing or flexible?}
Q1a -->|Exact| CRON["Scheduled Tasks (Cron)"]
@ -34,59 +35,68 @@ flowchart TD
Q3 -->|Yes| FLOW[Task Flow]
Q4 -->|Yes| HOOKS[Hooks]
Q5 -->|Yes| SO[Standing Orders]
Q6 -->|Yes| COMMITMENTS[Inferred Commitments]
```
| 用例 | 推荐 | 原因 |
| 使用场景 | 推荐方式 | 原因 |
| --------------------------------------- | ---------------------- | ------------------------------------------------ |
| 在上午 9 点准时发送每日报告 | 计划任务（Cron） | 精确计时，隔离执行 |
| 20 分钟后提醒我 | 计划任务（Cron） | 使用精确计时的一次性任务（`--at`） |
| 运行每周深度分析 | 计划任务（Cron） | 独立任务，可使用不同模型 |
| 每 30 分钟检查收件箱 | 心跳 | 与其他检查批处理，感知上下文 |
| 监控日历中的即将到来的事件 | 心跳 | 自然适合周期性感知 |
| 检查子智能体或 ACP 运行的状态 | 后台任务 | 任务账本会跟踪所有分离的工作 |
| 审计运行了什么以及何时运行 | 后台任务 | `openclaw tasks list` 和 `openclaw tasks audit` |
| 多步骤研究后总结 | 任务流 | 带修订跟踪的持久编排 |
| 在会话重置时运行脚本 | 钩子 | 事件驱动，在生命周期事件上触发 |
| 每次工具调用时执行代码 | 插件钩子 | 进程内钩子可以拦截工具调用 |
| 回复前始终检查合规性 | 常设指令 | 自动注入到每个会话 |
| 在上午 9 点准时发送日报 | 定时任务（Cron） | 精确时间，隔离执行 |
| 20 分钟后提醒我 | 定时任务（Cron） | 使用精确时间的一次性任务（`--at`） |
| 每周运行深度分析 | 定时任务（Cron） | 独立任务，可使用不同模型 |
| 每 30 分钟检查收件箱 | Heartbeat | 与其他检查批量执行，具备上下文感知 |
| 监控日历中的即将到来的事件 | Heartbeat | 非常适合周期性感知 |
| 在提到的面试后跟进 | 推断式跟进承诺 | 类似记忆的跟进，不是明确的提醒请求 |
| 基于用户上下文进行温和关怀式问候 | 推断式跟进承诺 | 限定在同一智能体和渠道内 |
| 检查子智能体或 ACP 运行的状态 | 后台任务 | 任务台账会跟踪所有脱离主流程的工作 |
| 审计运行过的内容和时间 | 后台任务 | `openclaw tasks list` 和 `openclaw tasks audit` |
| 多步研究后再总结 | Task Flow | 带修订跟踪的持久编排 |
| 在会话重置时运行脚本 | 钩子 | 事件驱动，在生命周期事件触发 |
| 每次工具调用时执行代码 | 插件钩子 | 进程内钩子可以拦截工具调用 |
| 回复前始终检查合规性 | 长期指令 | 自动注入到每个会话中 |
### 计划任务（Cron）与心跳
### 定时任务（Cron）与 Heartbeat
| 维度 | 计划任务（Cron） | 心跳 |
| --------------- | ----------------------------------- | ------------------------------------- |
| 计时 | 精确（cron 表达式、一次性任务） | 近似（默认每 30 分钟） |
| 会话上下文 | 全新（隔离）或共享 | 完整主会话上下文 |
| 任务记录 | 始终创建 | 从不创建 |
| 交付 | 渠道、webhook 或静默 | 内联在主会话中 |
| 最适合 | 报告、提醒、后台作业 | 收件箱检查、日历、通知 |
| 维度 | 定时任务（Cron） | Heartbeat |
| ---------- | ----------------------------------- | ------------------------------------- |
| 时间 | 精确（cron 表达式、一次性任务） | 近似（默认每 30 分钟） |
| 会话上下文 | 全新（隔离）或共享 | 完整主会话上下文 |
| 任务记录 | 始终创建 | 从不创建 |
| 投递 | 渠道、webhook 或静默 | 在主会话中内联 |
| 最适合 | 报告、提醒、后台作业 | 收件箱检查、日历、通知 |
当你需要精确计时或隔离执行时，使用计划任务（Cron）。当工作受益于完整会话上下文且近似计时可以接受时，使用心跳。
当你需要精确时间或隔离执行时，使用定时任务（Cron）。当工作受益于完整会话上下文且近似时间即可时，使用 Heartbeat。
## 核心概念
### 计划任务（cron）
### 定时任务（cron）
Cron 是 Gateway 网关内置的精确计时调度器。它会持久化作业，在正确时间唤醒智能体，并可将输出交付到聊天渠道或 webhook 端点。支持一次性提醒、重复表达式和入站 webhook 触发器。
Cron 是 Gateway 网关内置的精确定时调度器。它会持久化作业，在正确时间唤醒智能体，并可将输出投递到聊天渠道或 webhook 端点。支持一次性提醒、重复表达式和入站 webhook 触发器。
参见[计划任务](/zh-CN/automation/cron-jobs)。
参见[定时任务](/zh-CN/automation/cron-jobs)。
### 任务
后台任务账本跟踪所有分离的工作：ACP 运行、子智能体生成、隔离 cron 执行和 CLI 操作。任务是记录，不是调度器。使用 `openclaw tasks list` 和 `openclaw tasks audit` 检查它们。
后台任务台账会跟踪所有脱离主流程的工作：ACP 运行、子智能体启动、隔离 cron 执行和 CLI 操作。任务是记录，不是调度器。使用 `openclaw tasks list` 和 `openclaw tasks audit` 检查它们。
参见[后台任务](/zh-CN/automation/tasks)。
### 任务流
### 推断式跟进承诺
任务流是后台任务之上的流程编排基底。它通过托管和镜像同步模式、修订跟踪，以及用于检查的 `openclaw tasks flow list|show|cancel`，来管理持久的多步骤流程。
跟进承诺是可选择启用的短期跟进记忆。OpenClaw 会从普通对话中推断它们，将其限定到同一智能体和渠道，并通过 Heartbeat 投递到期的问候。用户明确请求的精确提醒仍应由 cron 处理。
参见[任务流](/zh-CN/automation/taskflow)。
参见[推断式跟进承诺](/zh-CN/concepts/commitments)。
### 常设指令
### Task Flow
常设指令授予智能体对已定义程序的永久操作权限。它们位于工作区文件中（通常为 `AGENTS.md`），并会注入到每个会话中。可与 cron 结合，用于基于时间的执行。
Task Flow 是后台任务之上的流程编排基底。它通过托管和镜像同步模式、修订跟踪，以及用于检查的 `openclaw tasks flow list|show|cancel`，管理持久的多步流程。
参见[常设指令](/zh-CN/automation/standing-orders)。
参见 [Task Flow](/zh-CN/automation/taskflow)。
### 长期指令
长期指令为智能体授予针对已定义程序的永久操作权限。它们存放在工作区文件中（通常是 `AGENTS.md`），并会注入到每个会话中。可与 cron 结合使用，以实现基于时间的强制执行。
参见[长期指令](/zh-CN/automation/standing-orders)。
### 钩子
@ -94,28 +104,29 @@ Cron 是 Gateway 网关内置的精确计时调度器。它会持久化作业，
参见[钩子](/zh-CN/automation/hooks)。
### 心跳
### Heartbeat
心跳是周期性的主会话轮次（默认每 30 分钟一次）。它在一个带完整会话上下文的智能体轮次中批处理多个检查（收件箱、日历、通知）。心跳轮次不会创建任务记录，也不会延长每日/空闲会话重置的新鲜度。使用 `HEARTBEAT.md` 放置一个小型清单；如果你希望在心跳自身内部进行仅到期的周期性检查，也可以使用 `tasks:` 块。空心跳文件会以 `empty-heartbeat-file` 跳过；仅到期任务模式会以 `no-tasks-due` 跳过。当 cron 工作处于活动或排队状态时，心跳会延后；`heartbeat.skipWhenBusy` 也可以在子智能体或嵌套通道繁忙时延后心跳。
Heartbeat 是周期性的主会话轮次（默认每 30 分钟）。它会在一次智能体轮次中批量执行多项检查（收件箱、日历、通知），并带有完整会话上下文。Heartbeat 轮次不会创建任务记录，也不会延长每日/空闲会话重置的新鲜度。使用 `HEARTBEAT.md` 编写一个小型检查清单；如果你希望在 Heartbeat 本身内部只运行到期的周期性检查，则使用 `tasks:` 块。空的 Heartbeat 文件会以 `empty-heartbeat-file` 跳过；仅到期任务模式会以 `no-tasks-due` 跳过。当 cron 工作处于活跃或排队状态时，Heartbeat 会延后；`heartbeat.skipWhenBusy` 还可以在子智能体或嵌套通道繁忙时延后它们。
参见[心跳](/zh-CN/gateway/heartbeat)。
参见 [Heartbeat](/zh-CN/gateway/heartbeat)。
## 它们如何配合
## 它们如何协同工作
- **Cron** 处理精确计划（每日报告、每周回顾）和一次性提醒。所有 cron 执行都会创建任务记录。
- **心跳** 在每 30 分钟一次的批处理轮次中处理例行监控（收件箱、日历、通知）。
- **钩子** 通过自定义脚本响应特定事件（会话重置、压缩、消息流）。插件钩子覆盖工具调用。
- **常设指令** 为智能体提供持久上下文和权限边界。
- **任务流** 在单个任务之上协调多步骤流程。
- **任务** 自动跟踪所有分离的工作，以便你检查和审计。
- **Cron** 处理精确日程（日报、周回顾）和一次性提醒。所有 cron 执行都会创建任务记录。
- **Heartbeat** 每 30 分钟在一个批量轮次中处理常规监控（收件箱、日历、通知）。
- **钩子** 使用自定义脚本响应特定事件（会话重置、压缩、消息流）。插件钩子覆盖工具调用。
- **长期指令** 为智能体提供持久上下文和权限边界。
- **Task Flow** 在单个任务之上协调多步流程。
- **任务** 自动跟踪所有脱离主流程的工作，便于你检查和审计。
## 相关内容
- [计划任务](/zh-CN/automation/cron-jobs) — 精确调度和一次性提醒
- [后台任务](/zh-CN/automation/tasks) — 所有分离工作的任务账本
- [任务流](/zh-CN/automation/taskflow) — 持久的多步骤流程编排
- [定时任务](/zh-CN/automation/cron-jobs) — 精确调度和一次性提醒
- [推断式跟进承诺](/zh-CN/concepts/commitments) — 类似记忆的跟进问候
- [后台任务](/zh-CN/automation/tasks) — 所有脱离主流程工作的任务台账
- [Task Flow](/zh-CN/automation/taskflow) — 持久的多步流程编排
- [钩子](/zh-CN/automation/hooks) — 事件驱动的生命周期脚本
- [插件钩子](/zh-CN/plugins/hooks) — 进程内工具、提示、消息和生命周期钩子
- [常设指令](/zh-CN/automation/standing-orders) — 持久智能体指令
- [心跳](/zh-CN/gateway/heartbeat) — 周期性主会话轮次
- [长期指令](/zh-CN/automation/standing-orders) — 持久的智能体指令
- [Heartbeat](/zh-CN/gateway/heartbeat) — 周期性主会话轮次
- [配置参考](/zh-CN/gateway/configuration-reference) — 所有配置键

301
docs/zh-CN/ci.md
View File

File diff suppressed because one or more lines are too long

94
docs/zh-CN/cli/commitments.md Normal file
View File

@ -0,0 +1,94 @@
---
read_when:
- 你想查看推断式跟进承诺
- 你想要忽略待处理的签到
- 你正在审计 Heartbeat 可能会传递的内容
summary: '`openclaw commitments` 的 CLI 参考（查看并忽略推断出的跟进事项）'
title: '`openclaw commitments`'
x-i18n:
generated_at: "2026-04-29T21:37:00Z"
model: gpt-5.5
provider: openai
source_hash: 37d5e5dca25cf649a5069360aa4e41fcc33d042dea99f643b98c07189c58f21c
source_path: cli/commitments.md
workflow: 16
---
列出并管理推断式跟进承诺。
跟进承诺是选择启用的短期跟进记忆，由会话上下文创建。请参阅[推断式跟进承诺](/zh-CN/concepts/commitments)了解概念指南。
没有子命令时，`openclaw commitments` 会列出待处理的跟进承诺。
## 用法
```bash
openclaw commitments [--all] [--agent <id>] [--status <status>] [--json]
openclaw commitments list [--all] [--agent <id>] [--status <status>] [--json]
openclaw commitments dismiss <id...> [--json]
```
## 选项
- `--all`：显示所有状态，而不是只显示待处理的跟进承诺。
- `--agent <id>`：筛选到一个智能体 ID。
- `--status <status>`：按状态筛选。取值：`pending`、`sent`、`dismissed`、`snoozed` 或 `expired`。
- `--json`：输出机器可读的 JSON。
## 示例
列出待处理的跟进承诺：
```bash
openclaw commitments
```
列出所有已存储的跟进承诺：
```bash
openclaw commitments --all
```
筛选到一个智能体：
```bash
openclaw commitments --agent main
```
查找已推迟的跟进承诺：
```bash
openclaw commitments --status snoozed
```
解除一个或多个跟进承诺：
```bash
openclaw commitments dismiss cm_abc123 cm_def456
```
导出为 JSON：
```bash
openclaw commitments --all --json
```
## 输出
文本输出包括：
- 跟进承诺 ID
- 状态
- 类型
- 最早到期时间
- 作用域
- 建议的跟进消息文本
JSON 输出还包括跟进承诺存储路径和完整的已存储记录。
## 相关内容
- [推断式跟进承诺](/zh-CN/concepts/commitments)
- [记忆概览](/zh-CN/concepts/memory)
- [Heartbeat](/zh-CN/gateway/heartbeat)
- [定时任务](/zh-CN/automation/cron-jobs)

81
docs/zh-CN/cli/index.md
View File

@ -3,60 +3,60 @@ read_when:
- 找到合适的 `openclaw` 子命令
- 查找全局标志或输出样式规则
summary: OpenClaw CLI 索引：命令列表、全局标志，以及指向各命令页面的链接
title: CLI 参考资料
title: CLI 参考
x-i18n:
generated_at: "2026-04-25T08:03:59Z"
model: gpt-5.4
generated_at: "2026-04-29T21:36:46Z"
model: gpt-5.5
provider: openai
source_hash: b8a61396b8ec7f57d15988d40b09f90458745bbb29e90bd387134aa032214853
source_hash: 522e0f156b919946756de6b933bb0a08374507401bf8639312daf52781927f33
source_path: cli/index.md
workflow: 15
workflow: 16
---
`openclaw` 是主要的 CLI 入口点。每个核心命令要么有专门的参考页面，要么与其别名命令一起记录；本索引列出了命令、全局标志，以及适用于整个 CLI 的输出样式规则。
`openclaw` 是主要的 CLI 入口点。每个核心命令都有专门的参考页面，或与其别名对应的命令一起记录；此索引列出命令、全局标志，以及适用于整个 CLI 的输出样式规则。
## 命令页面
| 区域 | 命令 |
| 区域 | 命令 |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 设置和新手引导 | [`crestodian`](/zh-CN/cli/crestodian) · [`setup`](/zh-CN/cli/setup) · [`onboard`](/zh-CN/cli/onboard) · [`configure`](/zh-CN/cli/configure) · [`config`](/zh-CN/cli/config) · [`completion`](/zh-CN/cli/completion) · [`doctor`](/zh-CN/cli/doctor) · [`dashboard`](/zh-CN/cli/dashboard) |
| 重置和卸载 | [`backup`](/zh-CN/cli/backup) · [`reset`](/zh-CN/cli/reset) · [`uninstall`](/zh-CN/cli/uninstall) · [`update`](/zh-CN/cli/update) |
| 消息和智能体 | [`message`](/zh-CN/cli/message) · [`agent`](/zh-CN/cli/agent) · [`agents`](/zh-CN/cli/agents) · [`acp`](/zh-CN/cli/acp) · [`mcp`](/zh-CN/cli/mcp) |
| 健康状态和会话 | [`status`](/zh-CN/cli/status) · [`health`](/zh-CN/cli/health) · [`sessions`](/zh-CN/cli/sessions) |
| Gateway 网关和日志 | [`gateway`](/zh-CN/cli/gateway) · [`logs`](/zh-CN/cli/logs) · [`system`](/zh-CN/cli/system) |
| 模型和推理 | [`models`](/zh-CN/cli/models) · [`infer`](/zh-CN/cli/infer) · `capability`（[`infer`](/zh-CN/cli/infer) 的别名） · [`memory`](/zh-CN/cli/memory) · [`wiki`](/zh-CN/cli/wiki) |
| 网络和节点 | [`directory`](/zh-CN/cli/directory) · [`nodes`](/zh-CN/cli/nodes) · [`devices`](/zh-CN/cli/devices) · [`node`](/zh-CN/cli/node) |
| 运行时和沙箱 | [`approvals`](/zh-CN/cli/approvals) · `exec-policy`（见 [`approvals`](/zh-CN/cli/approvals)） · [`sandbox`](/zh-CN/cli/sandbox) · [`tui`](/zh-CN/cli/tui) · `chat`/`terminal`（[`tui --local`](/zh-CN/cli/tui) 的别名） · [`browser`](/zh-CN/cli/browser) |
| 自动化 | [`cron`](/zh-CN/cli/cron) · [`tasks`](/zh-CN/cli/tasks) · [`hooks`](/zh-CN/cli/hooks) · [`webhooks`](/zh-CN/cli/webhooks) |
| 设备发现和文档 | [`dns`](/zh-CN/cli/dns) · [`docs`](/zh-CN/cli/docs) |
| 配对和渠道 | [`pairing`](/zh-CN/cli/pairing) · [`qr`](/zh-CN/cli/qr) · [`channels`](/zh-CN/cli/channels) |
| 安全和插件 | [`security`](/zh-CN/cli/security) · [`secrets`](/zh-CN/cli/secrets) · [`skills`](/zh-CN/cli/skills) · [`plugins`](/zh-CN/cli/plugins) · [`proxy`](/zh-CN/cli/proxy) |
| 旧版别名 | [`daemon`](/zh-CN/cli/daemon)（Gateway 网关服务） · [`clawbot`](/zh-CN/cli/clawbot)（命名空间） |
| 插件（可选） | [`voicecall`](/zh-CN/cli/voicecall)（如果已安装） |
| 重置和卸载 | [`backup`](/zh-CN/cli/backup) · [`reset`](/zh-CN/cli/reset) · [`uninstall`](/zh-CN/cli/uninstall) · [`update`](/zh-CN/cli/update) |
| 消息和智能体 | [`message`](/zh-CN/cli/message) · [`agent`](/zh-CN/cli/agent) · [`agents`](/zh-CN/cli/agents) · [`acp`](/zh-CN/cli/acp) · [`mcp`](/zh-CN/cli/mcp) |
| 健康状态和会话 | [`status`](/zh-CN/cli/status) · [`health`](/zh-CN/cli/health) · [`sessions`](/zh-CN/cli/sessions) |
| Gateway 网关和日志 | [`gateway`](/zh-CN/cli/gateway) · [`logs`](/zh-CN/cli/logs) · [`system`](/zh-CN/cli/system) |
| 模型和推理 | [`models`](/zh-CN/cli/models) · [`infer`](/zh-CN/cli/infer) · `capability`（[`infer`](/zh-CN/cli/infer) 的别名） · [`memory`](/zh-CN/cli/memory) · [`commitments`](/zh-CN/cli/commitments) · [`wiki`](/zh-CN/cli/wiki) |
| 网络和节点 | [`directory`](/zh-CN/cli/directory) · [`nodes`](/zh-CN/cli/nodes) · [`devices`](/zh-CN/cli/devices) · [`node`](/zh-CN/cli/node) |
| 运行时和沙箱 | [`approvals`](/zh-CN/cli/approvals) · `exec-policy`（见 [`approvals`](/zh-CN/cli/approvals)） · [`sandbox`](/zh-CN/cli/sandbox) · [`tui`](/zh-CN/cli/tui) · `chat`/`terminal`（[`tui --local`](/zh-CN/cli/tui) 的别名） · [`browser`](/zh-CN/cli/browser) |
| 自动化 | [`cron`](/zh-CN/cli/cron) · [`tasks`](/zh-CN/cli/tasks) · [`hooks`](/zh-CN/cli/hooks) · [`webhooks`](/zh-CN/cli/webhooks) |
| 设备发现和文档 | [`dns`](/zh-CN/cli/dns) · [`docs`](/zh-CN/cli/docs) |
| 配对和渠道 | [`pairing`](/zh-CN/cli/pairing) · [`qr`](/zh-CN/cli/qr) · [`channels`](/zh-CN/cli/channels) |
| 安全和插件 | [`security`](/zh-CN/cli/security) · [`secrets`](/zh-CN/cli/secrets) · [`skills`](/zh-CN/cli/skills) · [`plugins`](/zh-CN/cli/plugins) · [`proxy`](/zh-CN/cli/proxy) |
| 旧版别名 | [`daemon`](/zh-CN/cli/daemon)（Gateway 网关服务） · [`clawbot`](/zh-CN/cli/clawbot)（命名空间） |
| 插件（可选） | [`voicecall`](/zh-CN/cli/voicecall)（如果已安装） |
## 全局标志
| 标志 | 用途 |
| 标志 | 用途 |
| ----------------------- | --------------------------------------------------------------------- |
| `--dev` | 将状态隔离在 `~/.openclaw-dev` 下，并切换默认端口 |
| `--profile <name>` | 将状态隔离在 `~/.openclaw-<name>` 下 |
| `--container <name>` | 将执行目标指定为某个已命名容器 |
| `--no-color` | 禁用 ANSI 颜色（也支持 `NO_COLOR=1`） |
| `--update` | [`openclaw update`](/zh-CN/cli/update) 的简写形式（仅适用于源码安装） |
| `-V`, `--version`, `-v` | 打印版本并退出 |
| `--dev` | 将状态隔离在 `~/.openclaw-dev` 下并偏移默认端口 |
| `--profile <name>` | 将状态隔离在 `~/.openclaw-<name>` 下 |
| `--container <name>` | 指定用于执行的命名容器 |
| `--no-color` | 禁用 ANSI 颜色（也会遵循 `NO_COLOR=1`） |
| `--update` | [`openclaw update`](/zh-CN/cli/update) 的简写（仅适用于源码安装） |
| `-V`, `--version`, `-v` | 打印版本并退出 |
## 输出模式
- ANSI 颜色和进度指示器仅在 TTY 会话中渲染。
- OSC-8 超链接会在支持时渲染为可点击链接；否则 CLI 会回退为普通 URL。
- `--json`（以及在支持时的 `--plain`）会禁用样式，以获得干净的输出。
- 长时间运行的命令会显示进度指示器（在支持时使用 OSC 9;4）。
- 在受支持的位置，OSC-8 超链接会渲染为可点击链接；否则 CLI 会回退为纯 URL。
- `--json`（以及受支持位置的 `--plain`）会禁用样式，以便输出干净内容。
- 长时间运行的命令会显示进度指示器（受支持时使用 OSC 9;4）。
调色板的唯一可信来源：`src/terminal/palette.ts`。
调色板事实来源：`src/terminal/palette.ts`。
## 命令树
<Accordion title="完整命令树">
<Accordion title="Full command tree">
```
openclaw [--dev] [--profile <name>] <command>
@ -124,6 +124,9 @@ openclaw [--dev] [--profile <name>] <command>
status
index
search
commitments
list
dismiss
wiki
status
doctor
@ -350,26 +353,26 @@ openclaw [--dev] [--profile <name>] <command>
terminal (alias: tui --local)
```
插件可以添加额外的顶级命令（例如 `openclaw voicecall`）。
插件可以添加额外的顶层命令（例如 `openclaw voicecall`）。
</Accordion>
## 聊天斜杠命令
聊天消息支持 `/...` 命令。请参阅 [斜杠命令](/zh-CN/tools/slash-commands)。
聊天消息支持 `/...` 命令。参见[斜杠命令](/zh-CN/tools/slash-commands)。
重点包括：
要点：
- `/status` — 快速诊断。
- `/trace` — 会话范围内的插件追踪/调试行。
- `/trace` — 会话范围的插件跟踪/调试行。
- `/config` — 持久化的配置更改。
- `/debug` — 仅运行时的配置覆盖（保存在内存中，不写入磁盘；需要 `commands.debug: true`）。
- `/debug` — 仅运行时的配置覆盖（内存中，不写入磁盘；需要 `commands.debug: true`）。
## 用量跟踪
当 OAuth/API 凭证可用时，`openclaw status --usage` 和 Control UI 会显示提供商的用量/配额。数据直接来自提供商的用量端点，并被标准化为 `X% left`。当前支持用量窗口的提供商有：Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi 和 z.ai。
当 OAuth/API 凭证可用时，`openclaw status --usage` 和 Control UI 会显示提供商用量/配额。数据直接来自提供商用量端点，并归一化为 `X% left`。当前具有用量窗口的提供商：Anthropic、GitHub Copilot、Gemini CLI、OpenAI Codex、MiniMax、Xiaomi 和 z.ai。
详见 [用量跟踪](/zh-CN/concepts/usage-tracking)。
详情参见[用量跟踪](/zh-CN/concepts/usage-tracking)。
## 相关内容

147
docs/zh-CN/concepts/commitments.md Normal file
View File

@ -0,0 +1,147 @@
---
read_when:
- 你希望 OpenClaw 记住自然的后续跟进
- 你想了解推断式跟进与提醒有何不同
- 你想查看或忽略跟进承诺
sidebarTitle: Commitments
summary: 用于并非精确提醒的回访的推断式跟进记忆
title: 推断式跟进承诺
x-i18n:
generated_at: "2026-04-29T21:36:56Z"
model: gpt-5.5
provider: openai
source_hash: 3f51af0ac2c9841258fbeeb8f2f98dba6f438b8e0c9433f601a0504d6ef27111
source_path: concepts/commitments.md
workflow: 16
---
跟进承诺是短期存在的后续跟进记忆。启用后，OpenClaw 可以
注意到某段对话创造了未来回访的机会，并记住稍后再提起。
示例：
- 你提到明天有面试。OpenClaw 可能会在之后回访。
- 你说自己很疲惫。OpenClaw 可能会稍后询问你是否睡过了。
- 智能体说它会在某件事变化后跟进。OpenClaw 可能会跟踪这个
未闭合的循环。
跟进承诺不是像 `MEMORY.md` 那样的持久事实，也不是精确的
提醒。它位于记忆和自动化之间：OpenClaw 记住一个绑定到
对话的义务，然后由 Heartbeat 在到期时投递。
## 启用跟进承诺
跟进承诺默认关闭。请在配置中启用：
```bash
openclaw config set commitments.enabled true
openclaw config set commitments.maxPerDay 3
```
等效的 `openclaw.json`：
```json
{
"commitments": {
"enabled": true,
"maxPerDay": 3
}
}
```
`commitments.maxPerDay` 限制在一个滚动日内，每个智能体会话可以投递
多少个推断式后续跟进。默认值为 `3`。
## 工作原理
智能体回复后，OpenClaw 可能会在单独的上下文中运行一次隐藏的后台
提取过程。该过程只查找推断式后续跟进承诺。它不会写入可见对话，
也不会要求主智能体对提取进行推理。
当它找到高置信度候选项时，OpenClaw 会存储一条跟进承诺，其中包含：
- 智能体 ID
- 会话键
- 原始渠道和投递目标
- 到期时间窗口
- 简短的建议回访
- 足够的来源上下文，供 Heartbeat 判断是否发送
投递通过 Heartbeat 进行。当跟进承诺到期时，Heartbeat 会把该跟进承诺
加入同一智能体和渠道范围内的 Heartbeat 回合。模型可以发送一条自然的
回访，也可以回复 `HEARTBEAT_OK` 将其忽略。
OpenClaw 绝不会在写入推断式跟进承诺后立即投递。到期时间会被限制为
至少晚于创建时间一个 Heartbeat 间隔，因此后续跟进不会在刚被推断出的
同一刻回显回来。
## 范围
跟进承诺限定在创建它们时的确切智能体和渠道上下文内。在 Discord 中与
一个智能体交谈时推断出的后续跟进，不会由另一个智能体、另一个渠道或
无关会话投递。
这种范围限定是该功能的一部分。自然回访应该像是同一段对话的延续，
而不是一个全局提醒系统。
## 跟进承诺与提醒
| 需求 | 使用 |
| ----------------------------------------------- | ---------------------------------------- |
| “下午 3 点提醒我” | [定时任务](/zh-CN/automation/cron-jobs) |
| “20 分钟后提醒我” | [定时任务](/zh-CN/automation/cron-jobs) |
| “每个工作日运行这份报告” | [定时任务](/zh-CN/automation/cron-jobs) |
| “我明天有面试” | 跟进承诺 |
| “我整晚没睡” | 跟进承诺 |
| “如果我没有回复这个未处理的话题，请跟进” | 跟进承诺 |
精确的用户请求已经属于调度器路径。跟进承诺只用于推断式后续跟进：
也就是用户没有要求提醒，但对话明确创造了一个有用的未来回访时机。
## 管理跟进承诺
使用 CLI 检查和清除已存储的跟进承诺：
```bash
openclaw commitments
openclaw commitments --all
openclaw commitments --agent main
openclaw commitments --status snoozed
openclaw commitments dismiss cm_abc123
```
请参阅 [`openclaw commitments`](/zh-CN/cli/commitments) 获取命令参考。
## 隐私和成本
跟进承诺提取会使用一次 LLM 过程，因此启用它会在符合条件的回合之后
增加后台模型用量。该过程对用户可见的对话是隐藏的，但它可以读取最近
的交流内容，以判断是否存在后续跟进。
已存储的跟进承诺是 OpenClaw 本地状态。它们是操作性记忆，而不是长期
记忆。使用以下命令停用该功能：
```bash
openclaw config set commitments.enabled false
```
## 故障排除
如果预期的后续跟进没有出现：
- 确认 `commitments.enabled` 为 `true`。
- 检查 `openclaw commitments --all` 中是否有待处理、已忽略、已稍后提醒或已过期的
记录。
- 确保该智能体的 Heartbeat 正在运行。
- 检查该智能体会话是否已经达到 `commitments.maxPerDay`。
- 记住，精确提醒会被跟进承诺提取跳过，并且应改为出现在
[定时任务](/zh-CN/automation/cron-jobs) 下。
## 相关内容
- [记忆概览](/zh-CN/concepts/memory)
- [主动记忆](/zh-CN/concepts/active-memory)
- [Heartbeat](/zh-CN/gateway/heartbeat)
- [定时任务](/zh-CN/automation/cron-jobs)
- [`openclaw commitments`](/zh-CN/cli/commitments)
- [配置参考](/zh-CN/gateway/configuration-reference#commitments)

87
docs/zh-CN/concepts/memory.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你想了解记忆的工作原理
- 你想了解记忆是如何工作的
- 你想知道要写入哪些记忆文件
summary: OpenClaw 如何跨会话记住信息
summary: OpenClaw 如何跨会话记住内容
title: 记忆概览
x-i18n:
generated_at: "2026-04-28T11:49:17Z"
generated_at: "2026-04-29T21:36:43Z"
model: gpt-5.5
provider: openai
source_hash: 5495270d96c72de525ff3d285b122eb2b86137c741e3042f067b7adc55eb51f0
source_hash: ecf6cf2c95ce3ee78d62923e795f16957088f0eb6620ed50647cff05b99bd572
source_path: concepts/memory.md
workflow: 16
---
@ -19,66 +19,72 @@ OpenClaw 通过在你的智能体工作区中写入**纯 Markdown 文件**来记
你的智能体有三个与记忆相关的文件：
- **`MEMORY.md`** — 长期记忆。持久化事实、偏好和决策。会在每个私信会话开始时加载。
- **`MEMORY.md`** — 长期记忆。持久的事实、偏好和决策。会在每个私信会话开始时加载。
- **`memory/YYYY-MM-DD.md`** — 每日笔记。持续记录的上下文和观察。今天和昨天的笔记会自动加载。
- **`DREAMS.md`**（可选）— Dream Diary 和 Dreaming 扫描摘要，供人工审阅，包括有依据的历史回填条目。
这些文件位于智能体工作区中（默认 `~/.openclaw/workspace`）。
<Tip>
如果你希望智能体记住某件事，直接告诉它：“记住我偏好 TypeScript。”它会把内容写入合适的文件。
如果你希望智能体记住某件事，直接告诉它即可：“记住我偏好 TypeScript。” 它会把内容写入适当的文件。
</Tip>
## 推断式跟进承诺
有些未来跟进并不是持久事实。如果你提到明天有一次面试，有用的记忆可能是“面试后跟进”，而不是“永久存入 `MEMORY.md`”。
[跟进承诺](/zh-CN/concepts/commitments) 是针对此类场景的可选、短期跟进记忆。OpenClaw 会在隐藏的后台步骤中推断它们，将其限定在同一个智能体和渠道内，并通过 Heartbeat 发送到期的跟进。明确的提醒仍然使用[定时任务](/zh-CN/automation/cron-jobs)。
## 记忆工具
智能体有两个用于处理记忆的工具：
- **`memory_search`** — 使用语义搜索查找相关笔记，即使用词与原文不同也可以找到。
- **`memory_get`** — 读取指定的记忆文件或行范围。
- **`memory_search`** — 使用语义搜索查找相关笔记，即使措辞与原文不同也可以找到。
- **`memory_get`** — 读取特定的记忆文件或行范围。
这两个工具都由当前启用的记忆插件提供（默认：`memory-core`）。
这两个工具由主动记忆插件提供（默认：`memory-core`）。
## Memory Wiki 配套插件
如果你希望持久记忆更像一个维护良好的知识库，而不只是原始笔记，请使用内置的 `memory-wiki` 插件。
如果你希望持久记忆表现得更像一个维护良好的知识库，而不只是原始笔记，可以使用内置的 `memory-wiki` 插件。
`memory-wiki` 会把持久知识编译成一个 wiki 知识库，具备：
`memory-wiki` 会将持久知识编译成一个 wiki 库，包含：
- 确定性的页面结构
- 结构化声明和证据
- 矛盾和新鲜度跟踪
- 生成的仪表板
- 矛盾与新鲜度跟踪
- 生成的仪表盘
- 面向智能体/运行时消费者的编译摘要
- wiki 原生工具，例如 `wiki_search`、`wiki_get`、`wiki_apply` 和 `wiki_lint`
它不会替代当前启用的记忆插件。当前启用的记忆插件仍然负责回忆、提升和 Dreaming。`memory-wiki` 会在旁边添加一个富含出处信息的知识层。
它不会替代主动记忆插件。主动记忆插件仍然负责回忆、提升和 Dreaming。`memory-wiki` 会在旁边添加一个富含来源信息的知识层。
参见 [Memory Wiki](/zh-CN/plugins/memory-wiki)。
## 记忆搜索
配置嵌入提供商后，`memory_search` 会使用**混合搜索**：将向量相似度（语义含义）与关键词匹配（ID 和代码符号等精确术语）结合起来。只要你拥有任一受支持提供商的 API 密钥，它就可以开箱即用。
配置嵌入提供商后，`memory_search` 会使用**混合搜索**，将向量相似度（语义含义）与关键字匹配（ID 和代码符号等精确术语）结合起来。只要你拥有任意受支持提供商的 API key，它就可以开箱即用。
<Info>
OpenClaw 会根据可用的 API 密钥自动检测你的嵌入提供商。如果你已经配置 OpenAI、Gemini、Voyage 或 Mistral 密钥，记忆搜索会自动启用。
OpenClaw 会根据可用的 API key 自动检测你的嵌入提供商。如果你配置了 OpenAI、Gemini、Voyage 或 Mistral key，记忆搜索会自动启用。
</Info>
有关搜索的工作方式、调优选项和提供商设置的详细信息，请参见 [Memory Search](/zh-CN/concepts/memory-search)。
有关搜索工作方式、调优选项和提供商设置的详细信息，请参见[记忆搜索](/zh-CN/concepts/memory-search)。
## 记忆后端
<CardGroup cols={3}>
<Card title="内置（默认）" icon="database" href="/zh-CN/concepts/memory-builtin">
基于 SQLite。支持关键词搜索、向量相似度和混合搜索，开箱即用。无需额外依赖。
<Card title="Builtin (default)" icon="database" href="/zh-CN/concepts/memory-builtin">
基于 SQLite。通过关键字搜索、向量相似度和混合搜索开箱即用。无需额外依赖。
</Card>
<Card title="QMD" icon="search" href="/zh-CN/concepts/memory-qmd">
本地优先的 sidecar，支持重排序、查询扩展，以及索引工作区之外的目录。
本地优先的 sidecar，支持重排序、查询扩展，以及索引工作区之外目录的能力。
</Card>
<Card title="Honcho" icon="brain" href="/zh-CN/concepts/memory-honcho">
AI 原生的跨会话记忆，具备用户建模、语义搜索和多智能体感知能力。通过插件安装。
AI 原生的跨会话记忆，支持用户建模、语义搜索和多智能体感知。插件安装。
</Card>
<Card title="LanceDB" icon="layers" href="/zh-CN/plugins/memory-lancedb">
内置的 LanceDB 后端记忆，支持 OpenAI 兼容嵌入、自动回忆、自动捕获和本地 Ollama 嵌入。
内置的 LanceDB 支持记忆，包含 OpenAI 兼容嵌入、自动回忆、自动捕获和本地 Ollama 嵌入支持。
</Card>
</CardGroup>
@ -86,15 +92,15 @@ AI 原生的跨会话记忆，具备用户建模、语义搜索和多智能体
<CardGroup cols={1}>
<Card title="Memory Wiki" icon="book" href="/zh-CN/plugins/memory-wiki">
将持久记忆编译成富含出处信息的 wiki 知识库，包含声明、仪表板、桥接模式，以及对 Obsidian 友好的工作流。
将持久记忆编译成富含来源信息的 wiki 库，包含声明、仪表盘、桥接模式和适合 Obsidian 的工作流。
</Card>
</CardGroup>
## 自动记忆刷新
在 [compaction](/zh-CN/concepts/compaction) 汇总你的对话之前，OpenClaw 会运行一个静默回合，提醒智能体把重要上下文保存到记忆文件中。该功能默认开启，你无需配置任何内容。
在[压缩](/zh-CN/concepts/compaction)总结你的对话之前，OpenClaw 会运行一个静默回合，提醒智能体把重要上下文保存到记忆文件中。此功能默认开启，你无需配置任何内容。
要让这个维护回合使用本地模型，请设置一个精确的记忆刷新模型覆盖：
若要让这个整理回合使用本地模型，请设置一个精确的记忆刷新模型覆盖：
```json
{
@ -110,33 +116,33 @@ AI 原生的跨会话记忆，具备用户建模、语义搜索和多智能体
}
```
该覆盖仅适用于记忆刷新回合，不会继承当前会话的 fallback 链。
该覆盖仅应用于记忆刷新回合，并且不会继承当前会话的回退链。
<Tip>
记忆刷新可防止 compaction 期间上下文丢失。如果你的智能体在对话中有尚未写入文件的重要事实，它们会在生成摘要前自动保存。
记忆刷新可防止压缩期间的上下文丢失。如果你的智能体在对话中有尚未写入文件的重要事实，它们会在生成摘要之前自动保存。
</Tip>
## Dreaming
Dreaming 是可选的后台记忆整合过程。它会收集短期信号、为候选项评分，并且只将符合条件的条目提升到长期记忆（`MEMORY.md`）。
Dreaming 是一个可选的后台记忆整合步骤。它会收集短期信号、为候选项评分，并且只将符合条件的项目提升到长期记忆（`MEMORY.md`）。
它旨在让长期记忆保持高信号密度：
它的设计目标是让长期记忆保持高信噪比：
- **选择启用**：默认禁用。
- **定时执行**：启用后，`memory-core` 会自动管理一个周期性 cron 任务，用于完整的 Dreaming 扫描。
- **阈值控制**：提升必须通过评分、回忆频率和查询多样性门槛。
- **可选启用**：默认禁用。
- **定时执行**：启用后，`memory-core` 会自动管理一个用于完整 Dreaming 扫描的周期性 cron job。
- **设有阈值**：提升必须通过分数、回忆频率和查询多样性门槛。
- **可审阅**：阶段摘要和日记条目会写入 `DREAMS.md`，供人工审阅。
有关阶段行为、评分信号和 Dream Diary 详细信息，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
有关阶段行为、评分信号和 Dream Diary 详情，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
## 有依据的回填和实时提升
Dreaming 系统现在有两个密切相关的审阅通道：
- **实时 Dreaming** 使用 `memory/.dreams/` 下的短期 Dreaming 存储；普通深度阶段在判断哪些内容可以进入 `MEMORY.md` 时使用的就是它。
- **实时 Dreaming** 使用 `memory/.dreams/` 下的短期 Dreaming 存储，这是普通深度阶段在决定哪些内容可以进入 `MEMORY.md` 时使用的内容。
- **有依据的回填** 将历史 `memory/YYYY-MM-DD.md` 笔记作为独立的每日文件读取，并将结构化审阅输出写入 `DREAMS.md`。
当你想重放较早的笔记，并检查系统认为哪些内容具有持久价值，而无需手动编辑 `MEMORY.md` 时，有依据的回填很有用。
当你想重放较旧的笔记，并在不手动编辑 `MEMORY.md` 的情况下检查系统认为哪些内容是持久的，有依据的回填会很有用。
当你使用：
@ -150,7 +156,7 @@ openclaw memory rem-backfill --path ./memory --stage-short-term
- 短期存储仍然是面向机器的排序界面。
- `MEMORY.md` 仍然只由深度提升写入。
如果你认为这次重放没有用，可以移除暂存的产物，而不影响普通日记条目或正常回忆状态：
如果你认为这次重放没有帮助，可以移除暂存的产物，而不影响普通日记条目或正常回忆状态：
```bash
openclaw memory rem-backfill --rollback
@ -165,17 +171,17 @@ openclaw memory search "query" # Search from the command line
openclaw memory index --force # Rebuild the index
```
## 相关阅读
## 延伸阅读
- [内置记忆引擎](/zh-CN/concepts/memory-builtin)：默认 SQLite 后端。
- [QMD 记忆引擎](/zh-CN/concepts/memory-qmd)：高级本地优先 sidecar。
- [Honcho 记忆](/zh-CN/concepts/memory-honcho)：AI 原生跨会话记忆。
- [QMD 记忆引擎](/zh-CN/concepts/memory-qmd)：高级的本地优先 sidecar。
- [Honcho 记忆](/zh-CN/concepts/memory-honcho)：AI 原生的跨会话记忆。
- [Memory LanceDB](/zh-CN/plugins/memory-lancedb)：基于 LanceDB 的插件，支持 OpenAI 兼容嵌入。
- [Memory Wiki](/zh-CN/plugins/memory-wiki)：编译后的知识库和 wiki 原生工具。
- [记忆搜索](/zh-CN/concepts/memory-search)：搜索流水线、提供商和调优。
- [Dreaming](/zh-CN/concepts/dreaming)：从短期回忆到长期记忆的后台提升。
- [记忆配置参考](/zh-CN/reference/memory-config)：所有配置开关。
- [Compaction](/zh-CN/concepts/compaction)：compaction 如何与记忆交互。
- [压缩](/zh-CN/concepts/compaction)：压缩如何与记忆交互。
## 相关内容
@ -184,3 +190,4 @@ openclaw memory index --force # Rebuild the index
- [内置记忆引擎](/zh-CN/concepts/memory-builtin)
- [Honcho 记忆](/zh-CN/concepts/memory-honcho)
- [Memory LanceDB](/zh-CN/plugins/memory-lancedb)
- [跟进承诺](/zh-CN/concepts/commitments)

399
docs/zh-CN/reference/RELEASING.md
View File

@ -1,146 +1,142 @@
---
read_when:
- 正在查找公开发布渠道定义
- 运行发布验证或包验收
- 运行发布验证或软件包验收
- 查找版本命名和发布节奏
summary: 发布通道、操作员检查清单、验证环境、版本命名和节奏
summary: 发布通道、操作员检查清单、验证环境、版本命名和发布节奏
title: 发布策略
x-i18n:
generated_at: "2026-04-29T11:37:54Z"
generated_at: "2026-04-29T21:36:59Z"
model: gpt-5.5
provider: openai
source_hash: bc944cc72f61226363cd6684c1b4830c518874da21bcf8127d365772275f17f7
source_hash: 54dc9ad7918ac95ec535a0404bbcbc04461a2b977151db0c2039b91e7e69c15c
source_path: reference/RELEASING.md
workflow: 16
---
OpenClaw 有三个公开发布通道：
- stable：带标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest`
- stable：已打标签的发布版本，默认发布到 npm `beta`，或在明确请求时发布到 npm `latest`
- beta：发布到 npm `beta` 的预发布标签
- dev：`main` 的移动头部
## 版本命名
- 稳定发布版本：`YYYY.M.D`
- stable 发布版本：`YYYY.M.D`
- Git 标签：`vYYYY.M.D`
- 稳定修正发布版本：`YYYY.M.D-N`
- stable 修正发布版本：`YYYY.M.D-N`
- Git 标签：`vYYYY.M.D-N`
- Beta 预发布版本：`YYYY.M.D-beta.N`
- beta 预发布版本：`YYYY.M.D-beta.N`
- Git 标签：`vYYYY.M.D-beta.N`
- 月份或日期不要补零
- `latest` 表示当前已提升的稳定 npm 发布版本
- `latest` 表示当前已提升的 stable npm 发布版本
- `beta` 表示当前 beta 安装目标
- 稳定版和稳定修正发布版本默认发布到 npm `beta`；发布操作者可以明确指定 `latest`，也可以稍后提升经过验证的 beta 构建
- 每个稳定的 OpenClaw 发布版本都会同时交付 npm 软件包和 macOS 应用；
beta 发布通常会先验证并发布 npm/软件包路径，除非明确请求，
否则 mac 应用的构建、签名和公证保留给稳定版
- stable 和 stable 修正发布版本默认发布到 npm `beta`；发布操作员可以明确指定 `latest`，或稍后提升一个已验证的 beta 构建
- 每个 stable OpenClaw 发布版本都会同时交付 npm 包和 macOS 应用；
beta 发布版本通常先验证并发布 npm/包路径，除非明确请求，否则
mac 应用构建/签名/公证仅保留给 stable
## 发布节奏
- 发布按 beta 优先推进
- 只有最新 beta 验证通过后才会发布稳定版
- 维护者通常会从当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本，
- 只有最新 beta 通过验证后才会发布 stable
- 维护者通常从基于当前 `main` 创建的 `release/YYYY.M.D` 分支切出发布版本，
这样发布验证和修复不会阻塞 `main` 上的新开发
- 如果 beta 标签已经推送或发布并且需要修复，维护者会切出下一个
`-beta.N` 标签，而不是删除或重新创建旧 beta 标签
- 详细发布流程、审批、凭证和恢复说明仅限维护者
- 如果 beta 标签已经推送或发布且需要修复，维护者会切出下一个 `-beta.N` 标签，
而不是删除或重新创建旧的 beta 标签
- 详细的发布流程、审批、凭证和恢复说明仅限维护者查看
## 发布操作者清单
## 发布操作员清单
此清单是发布流程的公开形态。私有凭证、签名、公证、dist-tag 恢复和紧急回滚详情保留在仅限维护者的发布运行手册中。
此清单是发布流程的公开形态。私有凭证、
签名、公证、dist-tag 恢复和紧急回滚细节保留在
仅限维护者的发布运行手册中。
1. 从当前 `main` 开始：拉取最新内容，确认目标提交已推送，
并确认当前 `main` 的 CI 足够健康，可以从它创建分支。
并确认当前 `main` CI 足够绿，可以从它创建分支。
2. 使用 `/changelog` 根据真实提交历史重写顶部 `CHANGELOG.md` 章节，
保持条目面向用户，提交它，推送它，并在创建分支前再 rebase/pull 一次。
3. 审查
保持条目面向用户，提交它，推送它，并在创建分支前再次 rebase/pull。
3. 检查
`src/plugins/compat/registry.ts` 和
`src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。仅当升级路径仍然被覆盖时才移除过期兼容性，或者记录为什么要有意保留它。
`src/commands/doctor/shared/deprecation-compat.ts` 中的发布兼容性记录。只有在升级路径仍被覆盖时才移除过期兼容性，
否则记录为什么有意继续保留。
4. 从当前 `main` 创建 `release/YYYY.M.D`；不要直接在 `main` 上执行常规发布工作。
5. 为预期标签提升每个必需位置的版本，然后运行本地确定性预检：
5. 为预期标签更新每个必需的版本位置，然后运行本地确定性预检：
`pnpm check:test-types`、`pnpm check:architecture`、
`pnpm build && pnpm ui:build` 和 `pnpm release:check`。
6. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前，
允许使用完整的 40 字符发布分支 SHA 进行仅验证预检。
6. 以 `preflight_only=true` 运行 `OpenClaw NPM Release`。在标签存在之前，
允许使用完整 40 字符的发布分支 SHA 进行仅验证预检。
保存成功的 `preflight_run_id`。
7. 对发布分支、标签或完整提交 SHA 使用 `Full Release Validation` 启动所有预发布测试。
这是四个大型发布测试箱的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。
8. 如果验证失败，在发布分支上修复，并重新运行能够证明修复的最小失败文件、通道、工作流作业、软件包配置、提供商或模型 allowlist。只有当变更表面让之前证据失效时，才重新运行完整的总控流程。
9. 对于 beta，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布，
然后针对已发布的 `openclaw@YYYY.M.D-beta.N`
或 `openclaw@beta` 软件包运行发布后软件包验收。如果已推送或已发布的 beta 需要修复，
7. 使用 `Full Release Validation` 为发布分支、标签或完整提交 SHA 启动所有预发布测试。
这是四个大型发布测试盒的唯一手动入口点：Vitest、Docker、QA Lab 和 Package。
8. 如果验证失败，在发布分支上修复，并重新运行能证明修复的最小失败
文件、通道、workflow job、package profile、provider 或 model allowlist。
只有当变更范围让先前证据过期时，才重新运行完整 umbrella。
9. 对于 beta，标记 `vYYYY.M.D-beta.N`，使用 npm dist-tag `beta` 发布，然后针对已发布的 `openclaw@YYYY.M.D-beta.N`
或 `openclaw@beta` 包运行发布后包验收。如果已推送或已发布的 beta 需要修复，
切出下一个 `-beta.N`；不要删除或重写旧 beta。
10. 对于稳定版，只有经过验证的 beta 或候选发布版本具备所需验证证据后才能继续。稳定版 npm 发布会通过 `preflight_run_id` 复用成功的预检工件；稳定版 macOS 发布就绪还要求 `main` 上存在打包好的 `.zip`、`.dmg`、`.dSYM.zip` 和已更新的
10. 对于 stable，只有在已验证的 beta 或发布候选具备所需验证证据后才继续。
stable npm 发布会通过 `preflight_run_id` 复用成功的
预检工件；stable macOS 发布就绪还要求 `main` 上存在已打包的 `.zip`、`.dmg`、`.dSYM.zip` 和更新后的
`appcast.xml`。
11. 发布后，运行 npm 发布后验证器，在你需要发布后渠道证明时可选择运行独立的已发布 npm Telegram E2E，按需提升 dist-tag，根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub release/prerelease 说明，并执行发布公告步骤。
11. 发布后，运行 npm 发布后验证器，需要发布后渠道证明时可选运行独立的
published-npm Telegram E2E，按需进行 dist-tag 提升，根据完整匹配的 `CHANGELOG.md` 章节生成 GitHub release/prerelease notes，
并执行发布公告步骤。
## 发布预检
- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外仍被覆盖
- 在发布预检前运行 `pnpm check:architecture`，确保更广泛的导入循环和架构边界检查在更快的本地门禁之外保持绿色
- 在 `pnpm release:check` 前运行 `pnpm build && pnpm ui:build`，确保打包验证步骤所需的 `dist/*` 发布产物和 Control UI bundle 已存在
- 在发布批准前运行手动 `Full Release Validation` workflow，从一个入口启动所有预发布 test boxes。它接受分支、标签或完整 commit SHA，分发手动 `CI`，并分发 `OpenClaw Release Checks`，用于安装 smoke、package acceptance、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 线。仅在 package 已发布且也应运行发布后 Telegram E2E 时提供 `npm_telegram_package_spec`。当私有证据报告应证明验证匹配已发布的 npm package、但不强制运行 Telegram E2E 时，提供 `evidence_package_spec`。
示例：
`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- 当你希望在发布工作继续进行时，为 package 候选项获取旁路证明，请运行手动 `Package Acceptance` workflow。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 以当前 `workflow_ref` harness 打包可信的 `package_ref` 分支/标签/SHA；对需要 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions run 上传的 tarball 使用 `source=artifact`。该 workflow 会将候选项解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并且可以用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一个 tarball 运行 Telegram QA。
示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai`
常用 profile：
- `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载线
- `package`：不含 OpenWebUI 或 live ClawHub 的 artifact-native package/update/plugin 线
- `product`：package profile 外加 MCP 渠道、cron/subagent 清理、OpenAI web search 和 OpenWebUI
- `full`：带 OpenWebUI 的 Docker 发布路径分片
- 在发布预检前运行 `pnpm check:test-types`，确保测试 TypeScript 在更快的本地 `pnpm check` 门禁之外也保持覆盖
- 在发布预检前运行 `pnpm check:architecture`，确保更广泛的导入循环和架构边界检查在更快的本地门禁之外为绿色
- 在 `pnpm release:check` 之前运行 `pnpm build && pnpm ui:build`，确保预期的 `dist/*` 发布产物和控制 UI 包存在，供打包验证步骤使用
- 在发布批准前运行手动 `Full Release Validation` 工作流，以便从一个入口点启动所有预发布测试盒。它接受分支、标签或完整提交 SHA，分发手动 `CI`，并分发 `OpenClaw Release Checks`，用于安装冒烟、包验收、Docker 发布路径套件、live/E2E、OpenWebUI、QA Lab 一致性、Matrix 和 Telegram 线路。仅在包已发布且发布后的 Telegram E2E 也应运行时，才提供 `npm_telegram_package_spec`。当私有证据报告应证明验证匹配已发布的 npm 包、但不强制运行 Telegram E2E 时，提供 `evidence_package_spec`。示例：`gh workflow run full-release-validation.yml --ref main -f ref=release/YYYY.M.D`
- 当你希望在发布工作继续进行的同时，为包候选项获取侧信道证明时，运行手动 `Package Acceptance` 工作流。对 `openclaw@beta`、`openclaw@latest` 或精确发布版本使用 `source=npm`；使用 `source=ref` 通过当前 `workflow_ref` harness 打包可信的 `package_ref` 分支/标签/SHA；对带必需 SHA-256 的 HTTPS tarball 使用 `source=url`；或对另一个 GitHub Actions 运行上传的 tarball 使用 `source=artifact`。该工作流会将候选项解析为 `package-under-test`，针对该 tarball 复用 Docker E2E 发布调度器，并可用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier` 针对同一 tarball 运行 Telegram QA。示例：`gh workflow run package-acceptance.yml --ref main -f workflow_ref=main -f source=npm -f package_spec=openclaw@beta -f suite_profile=product -f telegram_mode=mock-openai`
常用配置：
- `smoke`：安装/渠道/智能体、Gateway 网关网络和配置重载线路
- `package`：不含 OpenWebUI 或 live ClawHub 的产物原生包/更新/插件线路
- `product`：包配置加 MCP 渠道、cron/subagent 清理、OpenAI web 搜索和 OpenWebUI
- `full`：带 OpenWebUI 的 Docker 发布路径分块
- `custom`：用于聚焦重跑的精确 `docker_lanes` 选择
- 当你只需要发布候选项的完整普通 CI 覆盖时，直接运行手动 `CI` workflow。手动 CI 分发会绕过 changed scoping，并强制运行 Linux Node 分片、内置插件分片、渠道 contract、Node 22 兼容性、`check`、`check-additional`、build smoke、docs checks、Python skills、Windows、macOS、Android 和 Control UI i18n 线。
示例：`gh workflow run ci.yml --ref release/YYYY.M.D`
- 验证发布 telemetry 时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP receiver 运行 QA-lab，并验证导出的 trace span 名称、有界 attributes，以及内容/标识符脱敏；不需要 Opik、Langfuse 或其他外部 collector。
- 每次带标签发布前运行 `pnpm release:check`
- 发布检查现在在单独的手动 workflow 中运行：
`OpenClaw Release Checks`
- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab mock 一致性门禁，以及快速 live Matrix profile 和 Telegram QA 线。live 线使用 `qa-live-shared` environment；Telegram 还使用 Convex CI credential leases。当你希望并行获取完整 Matrix 传输、媒体和 E2EE inventory 时，运行手动 `QA-Lab - All Lanes` workflow，并设置 `matrix_profile=all` 和 `matrix_shards=true`。
- 跨 OS 安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用 reusable workflow `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意的：让真实 npm 发布路径保持简短、确定且专注于 artifact，同时让较慢的 live 检查留在自己的线中，避免它们拖慢或阻塞发布
- 带 secret 的发布检查应通过 `Full Release Validation` 分发，或从 `main`/release workflow ref 分发，以便 workflow 逻辑和 secrets 保持受控
- `OpenClaw Release Checks` 接受分支、标签或完整 commit SHA，只要解析出的 commit 可从 OpenClaw 分支或 release tag 到达
- `OpenClaw NPM Release` validation-only 预检也接受当前完整 40 字符 workflow 分支 commit SHA，无需推送 tag
- 该 SHA 路径仅用于验证，不能升级为真实发布
- 在 SHA 模式下，workflow 只为 package metadata check 合成 `v<package.json version>`；真实发布仍需要真实 release tag
- 两个 workflow 都将真实 publish 和 promotion 路径保留在 GitHub-hosted runners 上，而非变更性 validation 路径可以使用更大的 Blacksmith Linux runners
- 该 workflow 使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` workflow secrets 运行
`OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
- npm 发布预检不再等待单独的发布检查线
- 批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`
（或匹配的 beta/correction tag）
- npm publish 后，运行
`node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`
（或匹配的 beta/correction version），在全新的临时 prefix 中验证已发布 registry 安装路径
- beta publish 后，运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`
以使用共享租赁 Telegram credential pool，针对已发布 npm package 验证 installed-package 新手引导、Telegram 设置和真实 Telegram E2E。本地 maintainer 一次性操作可以省略 Convex vars，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境变量凭证。
- Maintainers 可以通过手动 `NPM Telegram Beta E2E` workflow 从 GitHub Actions 运行相同的发布后检查。它有意仅允许手动运行，不会在每次 merge 时运行。
- Maintainer 发布自动化现在使用 preflight-then-promote：
- 真实 npm publish 必须通过成功的 npm `preflight_run_id`
- 真实 npm publish 必须从与成功 preflight run 相同的 `main` 或 `release/YYYY.M.D` 分支分发
- stable npm releases 默认指向 `beta`
- stable npm publish 可以通过 workflow input 明确指定 `latest`
- 基于 token 的 npm dist-tag 变更现在位于
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
以保障安全，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而 public repo 保持 OIDC-only publish
- 当你只需要发布候选项的完整常规 CI 覆盖时，直接运行手动 `CI` 工作流。手动 CI 分发会绕过变更范围限定，并强制运行 Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和控制 UI i18n 线路。示例：`gh workflow run ci.yml --ref release/YYYY.M.D`
- 验证发布遥测时运行 `pnpm qa:otel:smoke`。它通过本地 OTLP/HTTP 接收器运行 QA-lab，并验证导出的跟踪 span 名称、有界属性以及内容/标识符脱敏，无需 Opik、Langfuse 或其他外部采集器。
- 每次打标签发布前运行 `pnpm release:check`
- 发布检查现在在一个单独的手动工作流中运行：`OpenClaw Release Checks`
- `OpenClaw Release Checks` 还会在发布批准前运行 QA Lab 模拟一致性门禁、快速 live Matrix 配置和 Telegram QA 线路。live 线路使用 `qa-live-shared` 环境；Telegram 还使用 Convex CI 凭证租约。当你希望并行获取完整 Matrix 传输、媒体和 E2EE 清单时，使用 `matrix_profile=all` 和 `matrix_shards=true` 运行手动 `QA-Lab - All Lanes` 工作流。
- 跨操作系统安装和升级运行时验证是公开 `OpenClaw Release Checks` 和 `Full Release Validation` 的一部分，它们会直接调用可复用工作流 `.github/workflows/openclaw-cross-os-release-checks-reusable.yml`
- 这种拆分是有意的：保持真实 npm 发布路径短、确定且聚焦产物，同时让较慢的 live 检查留在自己的线路中，避免拖慢或阻塞发布
- 带有密钥的发布检查应通过 `Full Release Validation` 分发，或从 `main`/release 工作流引用分发，以保持工作流逻辑和密钥受控
- `OpenClaw Release Checks` 接受分支、标签或完整提交 SHA，只要解析出的提交可从 OpenClaw 分支或发布标签到达
- `OpenClaw NPM Release` 仅验证预检也接受当前完整 40 字符工作流分支提交 SHA，无需已推送的标签
- 该 SHA 路径仅用于验证，不能提升为真实发布
- 在 SHA 模式下，工作流仅为包元数据检查合成 `v<package.json version>`；真实发布仍需要真实发布标签
- 两个工作流都将真实发布和提升路径保留在 GitHub 托管 runner 上，而非变更性验证路径可以使用更大的 Blacksmith Linux runner
- 该工作流会使用 `OPENAI_API_KEY` 和 `ANTHROPIC_API_KEY` 工作流密钥运行 `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_CACHE_TEST=1 pnpm test:live:cache`
- npm 发布预检不再等待单独的发布检查线路
- 在批准前运行 `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/openclaw-npm-release-check.ts`（或匹配的 beta/修正版标签）
- npm 发布后，运行 `node --import tsx scripts/openclaw-npm-postpublish-verify.ts YYYY.M.D`（或匹配的 beta/修正版版本），在全新的临时前缀中验证已发布注册表安装路径
- beta 发布后，运行 `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@YYYY.M.D-beta.N OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci pnpm test:docker:npm-telegram-live`，使用共享租约 Telegram 凭证池，针对已发布的 npm 包验证已安装包新手引导、Telegram 设置和真实 Telegram E2E。本地维护者的一次性运行可以省略 Convex 变量，并直接传入三个 `OPENCLAW_QA_TELEGRAM_*` 环境凭证。
- 维护者可以通过手动 `NPM Telegram Beta E2E` 工作流从 GitHub Actions 运行同一个发布后检查。它有意仅支持手动运行，不会在每次合并时运行。
- 维护者发布自动化现在使用先预检再提升：
- 真实 npm 发布必须通过成功的 npm `preflight_run_id`
- 真实 npm 发布必须从与成功预检运行相同的 `main` 或 `release/YYYY.M.D` 分支分发
- 稳定 npm 发布默认使用 `beta`
- 稳定 npm 发布可以通过工作流输入显式目标为 `latest`
- 基于令牌的 npm dist-tag 变更现在位于 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`，出于安全考虑，因为 `npm dist-tag add` 仍需要 `NPM_TOKEN`，而公开仓库保持仅 OIDC 发布
- 公开 `macOS Release` 仅用于验证
- 真实私有 mac publish 必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id`
- 真实 publish 路径会提升已准备好的 artifacts，而不是再次 rebuild 它们
- 对于 `YYYY.M.D-N` 这样的 stable correction releases，发布后 verifier 还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的相同 temp-prefix 升级路径，确保 release corrections 不会静默地让旧的 global installs 停留在 base stable payload 上
- npm 发布预检会 fail closed，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` payload，以免我们再次发布空的浏览器 dashboard
- 发布后验证还会检查已发布 registry install 是否在根 `dist/*` 布局下包含非空的内置插件 runtime deps。若某个发布缺失或包含空的内置插件依赖 payload，则 postpublish verifier 会失败，且不能 promoted 到 `latest`。
- `pnpm test:install:smoke` 还会对候选 update tarball 强制执行 npm pack `unpackedSize` 预算，因此 installer e2e 会在 release publish 路径前捕获意外的 pack bloat
- 如果发布工作触及 CI planning、extension timing manifests 或 extension test matrices，请在批准前重新生成并审查由 planner 拥有的 `plugin-prerelease-extension-shard` matrix outputs，来源为 `.github/workflows/plugin-prerelease.yml`，确保 release notes 不会描述过时的 CI 布局
- Stable macOS 发布就绪性还包括 updater surfaces：
- 真实私有 mac 发布必须通过成功的私有 mac `preflight_run_id` 和 `validate_run_id`
- 真实发布路径会提升已准备好的产物，而不是再次重建它们
- 对于类似 `YYYY.M.D-N` 的稳定修正版本，发布后验证器还会检查从 `YYYY.M.D` 到 `YYYY.M.D-N` 的同一临时前缀升级路径，确保发布修正不会静默地让较旧的全局安装停留在基础稳定载荷上
- npm 发布预检会默认失败，除非 tarball 同时包含 `dist/control-ui/index.html` 和非空的 `dist/control-ui/assets/` 载荷，避免再次发布空的浏览器仪表板
- 发布后验证还会检查已发布注册表安装是否在根 `dist/*` 布局下包含非空的内置插件运行时依赖。若发布版本缺少或带有空的内置插件依赖载荷，发布后验证器会失败，且无法提升为 `latest`。
- `pnpm test:install:smoke` 也会对候选更新 tarball 强制执行 npm pack `unpackedSize` 预算，因此安装器 e2e 会在发布发布路径前捕获意外的打包膨胀
- 如果发布工作触及 CI 规划、插件计时清单或插件测试矩阵，请在批准前重新生成并审查由规划器拥有的 `plugin-prerelease-extension-shard` 矩阵输出，来源于 `.github/workflows/plugin-prerelease.yml`，确保发布说明不会描述过时的 CI 布局
- 稳定 macOS 发布就绪还包括更新器表面：
- GitHub release 最终必须包含打包的 `.zip`、`.dmg` 和 `.dSYM.zip`
- publish 后，`main` 上的 `appcast.xml` 必须指向新的 stable zip
- 打包后的 app 必须保留非 debug bundle id、非空 Sparkle feed URL，以及对该 release version 而言不低于 canonical Sparkle build floor 的 `CFBundleVersion`
- 发布后，`main` 上的 `appcast.xml` 必须指向新的稳定 zip
- 打包后的应用必须保持非调试 bundle id、非空 Sparkle feed URL，以及等于或高于该发布版本规范 Sparkle 构建下限的 `CFBundleVersion`
## 发布 test boxes
## 发布测试盒
`Full Release Validation` 是 operators 从一个入口启动所有预发布测试的方式。请从可信的 `main` workflow ref 运行它，并将 release branch、tag 或完整 commit SHA 作为 `ref` 传入：
`Full Release Validation` 是操作员从一个入口点启动所有预发布测试的方式。从可信的 `main` 工作流引用运行它，并将发布分支、标签或完整提交 SHA 作为 `ref` 传入：
```bash
gh workflow run full-release-validation.yml \
@ -152,19 +148,17 @@ gh workflow run full-release-validation.yml \
-f evidence_package_spec=openclaw@YYYY.M.D-beta.N
```
该 workflow 会解析目标 ref，使用 `target_ref=<release-ref>` 分发手动 `CI`，分发 `OpenClaw Release Checks`，并在设置 `npm_telegram_package_spec` 时可选地分发独立的发布后 Telegram E2E。`OpenClaw Release Checks` 随后会扇出安装 smoke、跨 OS 发布检查、live/E2E Docker 发布路径覆盖、带 Telegram package QA 的 Package Acceptance、QA Lab 一致性、live Matrix 和 live Telegram。仅当 `Full Release Validation` summary 显示 `normal_ci` 和 `release_checks` 成功，并且任何可选的 `npm_telegram` child 成功或有意跳过时，完整 run 才可接受。最终 verifier summary 包含每个 child run 的最慢 job 表格，因此 release manager 可以在不下载日志的情况下看到当前关键路径。
Child workflows 从运行 `Full Release Validation` 的可信 ref 分发，通常为 `--ref main`，即使目标 `ref` 指向较旧的 release branch 或 tag。没有单独的 Full Release Validation workflow-ref input；请通过选择 workflow run ref 来选择可信 harness。
该工作流会解析目标引用，使用 `target_ref=<release-ref>` 分发手动 `CI`，分发 `OpenClaw Release Checks`，并在设置了 `npm_telegram_package_spec` 时可选地分发独立的发布后 Telegram E2E。随后，`OpenClaw Release Checks` 会扇出安装冒烟、跨操作系统发布检查、live/E2E Docker 发布路径覆盖、带 Telegram 包 QA 的 Package Acceptance、QA Lab 一致性、live Matrix 和 live Telegram。完整运行只有在 `Full Release Validation` 摘要显示 `normal_ci` 和 `release_checks` 成功，且任何可选的 `npm_telegram` 子项成功或被有意跳过时才可接受。最终验证器摘要会包含每个子运行的最慢作业表，因此发布经理无需下载日志即可看到当前关键路径。子工作流从运行 `Full Release Validation` 的可信引用分发，通常是 `--ref main`，即使目标 `ref` 指向较旧的发布分支或标签。不存在单独的 Full Release Validation 工作流引用输入；通过选择工作流运行引用来选择可信 harness。
使用 `release_profile` 选择 live/provider 覆盖广度：
使用 `release_profile` 选择 live/提供商覆盖范围：
- `minimum`：最快的 release-critical OpenAI/core live 和 Docker 路径
- `stable`：minimum 加上用于 release approval 的 stable provider/backend 覆盖
- `full`：stable 加上广泛的 advisory provider/media 覆盖
- `minimum`：最快的发布关键 OpenAI/core live 和 Docker 路径
- `stable`：minimum 加上用于发布批准的稳定提供商/后端覆盖
- `full`：stable 加上广泛的建议提供商/媒体覆盖
`OpenClaw Release Checks` 使用可信 workflow ref 将目标 ref 解析一次为 `release-package-under-test`，并在 release-path Docker checks 和 Package Acceptance 中复用该 artifact。这让所有面向 package 的 boxes 使用相同字节，并避免重复 package builds。
当 repo/org variable 已设置时，跨 OS OpenAI install smoke 使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4-mini`，因为这条线证明的是 package install、新手引导、gateway startup 和一次 live 智能体 turn，而不是对最慢默认模型进行 benchmark。更广泛的 live provider matrix 仍然是进行 model-specific 覆盖的地方。
`OpenClaw Release Checks` 使用可信工作流引用将目标引用一次性解析为 `release-package-under-test`，并在发布路径 Docker 检查和 Package Acceptance 中复用该产物。这会让所有面向包的测试盒使用相同字节，并避免重复构建包。当设置了仓库/组织变量时，跨操作系统 OpenAI 安装冒烟使用 `OPENCLAW_CROSS_OS_OPENAI_MODEL`，否则使用 `openai/gpt-5.4-mini`，因为此线路证明的是包安装、新手引导、Gateway 网关启动和一次 live 智能体轮次，而不是基准测试最慢的默认模型。更广泛的 live 提供商矩阵仍然是模型特定覆盖的位置。
请根据 release stage 使用这些 variants：
根据发布阶段使用这些变体：
```bash
# Validate an unpublished release candidate branch.
@ -193,22 +187,37 @@ gh workflow run full-release-validation.yml \
-f npm_telegram_provider_mode=mock-openai
```
不要把完整总控工作流作为聚焦修复后的首次重跑。如果某个检查盒失败，请使用失败的子工作流、作业、Docker 通道、包配置文件、模型提供商或 QA 通道作为下一次验证。只有当修复更改了共享发布编排，或让之前的全检查盒证据变得过期时，才再次运行完整总控工作流。总控工作流的最终验证器会重新检查记录的子工作流运行 ID，因此当某个子工作流成功重跑后，只需重跑失败的 `Verify full validation` 父作业。
不要把完整总控流程用作聚焦修复后的第一次重跑。如果某个盒子失败，
下一次证明请使用失败的子 workflow、job、Docker 通道、包配置文件、模型
提供商或 QA 通道。只有当修复更改了共享发布编排，或使此前所有盒子的
证据过期时，才再次运行完整总控流程。总控流程的最终验证器会重新检查
已记录的子 workflow 运行 ID，因此在子 workflow 成功重跑后，只需重跑
失败的父级 `Verify full validation` job。
对于有边界的恢复，请将 `rerun_group` 传给总控工作流。`all` 是真正的候选发布运行，`ci` 只运行常规 CI 子工作流，`plugin-prerelease` 只运行仅发布用的插件子工作流，`release-checks` 运行所有发布检查盒，而更窄的发布分组包括 `install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、`qa-live`，以及在提供独立包 Telegram 通道时的 `npm-telegram`。
对于有界恢复，请向总控流程传入 `rerun_group`。`all` 是真正的
候选发布运行，`ci` 只运行普通 CI 子项，`plugin-prerelease` 只运行
仅发布插件子项，`release-checks` 会运行每个发布盒子，更窄的发布组包括
`install-smoke`、`cross-os`、`live-e2e`、`package`、`qa`、`qa-parity`、
`qa-live`，以及在提供独立包 Telegram 通道时的 `npm-telegram`。
### Vitest
Vitest 检查盒是手动 `CI` 子工作流。手动 CI 会有意绕过变更范围限定，并为候选发布强制运行常规测试图：Linux Node 分片、内置插件分片、渠道契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、Python Skills、Windows、macOS、Android 和 Control UI i18n。
Vitest 盒子是手动 `CI` 子 workflow。手动 CI 会有意绕过变更范围限定，
并为候选发布强制运行普通测试图：Linux Node 分片、内置插件分片、渠道
契约、Node 22 兼容性、`check`、`check-additional`、构建冒烟、文档检查、
Python skills、Windows、macOS、Android，以及 Control UI i18n。
使用此检查盒回答“源代码树是否通过了完整的常规测试套件？”它不同于发布路径的产品验证。需要保留的证据：
使用这个盒子回答“源代码树是否通过了完整的普通测试套件？”它与发布路径
产品验证不同。需要保留的证据：
- `Full Release Validation` 摘要，显示已调度的 `CI` 运行 URL
- `CI` 在精确目标 SHA 上通过
- 调查回归时来自 CI 作业的失败或缓慢分片名称
- 当运行需要性能分析时，保留 Vitest 计时产物，例如 `.artifacts/vitest-shard-timings.json`
- `CI` 在精确目标 SHA 上为绿色
- 调查回归时来自 CI job 的失败或缓慢分片名称
- 当一次运行需要性能分析时，保留 `.artifacts/vitest-shard-timings.json`
等 Vitest 计时产物
仅当发布需要确定性的常规 CI，但不需要 Docker、QA Lab、实时、跨 OS 或包检查盒时，才直接运行手动 CI：
仅当发布需要确定性的普通 CI，而不需要 Docker、QA Lab、live、cross-OS
或 package 盒子时，才直接运行手动 CI：
```bash
gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
@ -216,49 +225,95 @@ gh workflow run ci.yml --ref main -f target_ref=release/YYYY.M.D
### Docker
Docker 检查盒位于 `OpenClaw Release Checks` 中，通过 `openclaw-live-and-e2e-checks-reusable.yml` 运行，并包含发布模式的 `install-smoke` 工作流。它通过打包后的 Docker 环境验证候选发布，而不只是源代码级测试。
Docker 盒子位于 `OpenClaw Release Checks` 中，通过
`openclaw-live-and-e2e-checks-reusable.yml` 提供，另有发布模式的
`install-smoke` workflow。它通过打包后的 Docker 环境验证候选发布，而不
只是源码级测试。
发布 Docker 覆盖范围包括：
- 启用较慢 Bun 全局安装冒烟的完整安装冒烟
- 启用慢速 Bun 全局安装冒烟的完整安装冒烟
- 按目标 SHA 准备/复用根 Dockerfile 冒烟镜像，QR、root/gateway 和
installer/Bun 冒烟 job 作为独立的 install-smoke 分片运行
- 仓库 E2E 通道
- 发布路径 Docker 分块：`core`、`package-update-openai`、`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、`plugins-runtime-services`、`plugins-runtime-install-a`、`plugins-runtime-install-b`、`plugins-runtime-install-c`、`plugins-runtime-install-d`、`plugins-runtime-install-e`、`plugins-runtime-install-f`、`plugins-runtime-install-g`、`plugins-runtime-install-h`、`bundled-channels-core`、`bundled-channels-update-a`、`bundled-channels-update-discord`、`bundled-channels-update-b` 和 `bundled-channels-contracts`
- 按需在 `plugins-runtime-services` 分块中覆盖 OpenWebUI
- 将内置渠道依赖通道拆分到 channel-smoke、update-target 和 setup/runtime 契约分块中，而不是放在一个大型内置渠道作业里
- 拆分内置插件安装/卸载通道 `bundled-plugin-install-uninstall-0` 到 `bundled-plugin-install-uninstall-23`
- 当发布检查包含实时套件时，覆盖 live/E2E 提供商套件和 Docker 实时模型
- 发布路径 Docker 分块：`core`、`package-update-openai`、
`package-update-anthropic`、`package-update-core`、`plugins-runtime-plugins`、
`plugins-runtime-services`、
`plugins-runtime-install-a`、`plugins-runtime-install-b`、
`plugins-runtime-install-c`、`plugins-runtime-install-d`、
`plugins-runtime-install-e`、`plugins-runtime-install-f`、
`plugins-runtime-install-g`、`plugins-runtime-install-h`、
`bundled-channels-core`、`bundled-channels-update-a`、
`bundled-channels-update-discord`、`bundled-channels-update-b`，以及
`bundled-channels-contracts`
- 按需在 `plugins-runtime-services` 分块内覆盖 OpenWebUI
- 将内置渠道依赖通道拆分到 channel-smoke、update-target 以及
setup/runtime 契约分块，而不是一个大型 bundled-channel job
- 拆分内置插件安装/卸载通道，从 `bundled-plugin-install-uninstall-0`
到 `bundled-plugin-install-uninstall-23`
- 当发布检查包含 live 套件时，覆盖 live/E2E 提供商套件和 Docker live
模型覆盖
重跑前先使用 Docker 产物。发布路径调度器会上传 `.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，请在可复用 live/E2E 工作流上使用 `docker_lanes=<lane[,lane]>`，而不是重跑所有发布分块。生成的重跑命令会在可用时包含之前的 `package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败通道可以复用同一个 tarball 和 GHCR 镜像。
重跑前先使用 Docker 产物。发布路径调度器会上传
`.artifacts/docker-tests/`，其中包含通道日志、`summary.json`、
`failures.json`、阶段计时、调度器计划 JSON 和重跑命令。对于聚焦恢复，
请在可复用 live/E2E workflow 上使用 `docker_lanes=<lane[,lane]>`，
而不是重跑所有发布分块。生成的重跑命令会在可用时包含此前的
`package_artifact_run_id` 和已准备的 Docker 镜像输入，因此失败通道可以
复用同一个 tarball 和 GHCR 镜像。
### QA Lab
QA Lab 检查盒也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和渠道级发布门禁，独立于 Vitest 和 Docker 包机制。
QA Lab 盒子也是 `OpenClaw Release Checks` 的一部分。它是智能体行为和
渠道级发布门禁，独立于 Vitest 和 Docker 包机制。
发布 QA Lab 覆盖范围包括：
- 使用 agentic parity pack，将 OpenAI 候选通道与 Opus 4.6 基线进行比较的模拟一致性门禁
- 使用 `qa-live-shared` 环境的快速实时 Matrix QA 配置文件
- 使用 Convex CI 凭据租约的实时 Telegram QA 通道
- mock parity gate，使用 agentic parity pack 将 OpenAI 候选通道与
Opus 4.6 基线进行比较
- 使用 `qa-live-shared` 环境的快速 live Matrix QA 配置
- 使用 Convex CI 凭据租约的 live Telegram QA 通道
- 当发布遥测需要明确的本地证明时运行 `pnpm qa:otel:smoke`
使用此检查盒回答“发布在 QA 场景和实时渠道流程中是否行为正确？”批准发布时保留 parity、Matrix 和 Telegram 通道的产物 URL。完整 Matrix 覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认的发布关键通道。
使用这个盒子回答“该发布在 QA 场景和 live 渠道流程中是否行为正确？”
批准发布时保留 parity、Matrix 和 Telegram 通道的产物 URL。完整 Matrix
覆盖仍可作为手动分片 QA-Lab 运行使用，而不是默认发布关键通道。
### Package
Package 检查盒是可安装产品门禁。它由 `Package Acceptance` 和解析器 `scripts/resolve-openclaw-package-candidate.mjs` 支撑。解析器会将候选项规范化为 Docker E2E 使用的 `package-under-test` tarball，验证包清单，记录包版本和 SHA-256，并将工作流 harness ref 与包源 ref 分开。
Package 盒子是可安装产品门禁。它由 `Package Acceptance` 和解析器
`scripts/resolve-openclaw-package-candidate.mjs` 支持。该解析器会将候选项
规范化为 Docker E2E 使用的 `package-under-test` tarball，验证包清单，
记录包版本和 SHA-256，并让 workflow harness ref 与包源码 ref 保持分离。
支持的候选来源：
- `source=npm`：`openclaw@beta`、`openclaw@latest` 或精确的 OpenClaw 发布版本
- `source=ref`：使用选定的 `workflow_ref` harness 打包受信任的 `package_ref` 分支、标签或完整提交 SHA
- `source=npm`：`openclaw@beta`、`openclaw@latest`，或精确的 OpenClaw
发布版本
- `source=ref`：使用选定的 `workflow_ref` harness 打包受信任的
`package_ref` 分支、标签或完整 commit SHA
- `source=url`：下载 HTTPS `.tgz`，并要求提供 `package_sha256`
- `source=artifact`：复用另一个 GitHub Actions 运行上传的 `.tgz`
`OpenClaw Release Checks` 使用 `source=ref`、`package_ref=<release-ref>`、`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline` 和 `telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker 分块覆盖重叠的安装、更新和插件更新通道；Package Acceptance 保留面向同一已解析 tarball 的产物原生内置渠道兼容性、离线插件 fixture 和 Telegram 包 QA。它是此前大部分需要 Parallels 的包/更新覆盖的 GitHub 原生替代方案。跨 OS 发布检查对 OS 特定的新手引导、安装器和平台行为仍然重要，但包/更新产品验证应优先使用 Package Acceptance。
`OpenClaw Release Checks` 会以 `source=ref`、`package_ref=<release-ref>`、
`suite_profile=custom`、`docker_lanes=bundled-channel-deps-compat plugins-offline`
和 `telegram_mode=mock-openai` 运行 Package Acceptance。发布路径 Docker
分块覆盖重叠的安装、更新和插件更新通道；Package Acceptance 则针对同一
已解析 tarball 保留产物原生的内置渠道兼容性、离线插件夹具和 Telegram
包 QA。它是过去大部分需要 Parallels 的包/更新覆盖的 GitHub 原生替代。
Cross-OS 发布检查对特定 OS 的新手引导、安装器和平台行为仍然重要，但
包/更新产品验证应优先使用 Package Acceptance。
旧版 package-acceptance 宽松规则是有意限时的。直到 `2026.4.25` 的包，可以对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺失私有 QA 清单条目、缺失 `gateway install --wrapper`、tarball 派生 git fixture 中缺失补丁文件、缺失持久化的 `update.channel`、旧版插件安装记录位置、缺失 marketplace 安装记录持久化，以及 `plugins update` 期间的配置元数据迁移。已发布的 `2026.4.26` 包可以对已发布的本地构建元数据戳文件发出警告。之后的包必须满足现代包契约；这些相同缺口会导致发布验证失败。
旧版 package-acceptance 宽容策略有意设置了时间边界。直到 `2026.4.25`
的包都可以对已经发布到 npm 的元数据缺口使用兼容路径：tarball 中缺少
私有 QA 清单条目、缺少 `gateway install --wrapper`、tarball 派生的 git
夹具中缺少补丁文件、缺少持久化的 `update.channel`、旧版插件安装记录
位置、缺少 marketplace 安装记录持久化，以及 `plugins update` 期间的
配置元数据迁移。已发布的 `2026.4.26` 包可以对已经随版本发布的本地构建
元数据 stamp 文件发出警告。之后的包必须满足现代包契约；这些相同缺口
会导致发布验证失败。
当发布问题涉及实际可安装包时，请使用更宽的 Package Acceptance 配置文件：
当发布问题涉及实际可安装包时，请使用更广的 Package Acceptance 配置：
```bash
gh workflow run package-acceptance.yml \
@ -269,58 +324,80 @@ gh workflow run package-acceptance.yml \
-f suite_profile=product
```
常见包配置文件：
常见包配置：
- `smoke`：快速包安装/渠道/智能体、Gateway 网关网络和配置重载通道
- `package`：不含实时 ClawHub 的安装/更新/插件包契约；这是 release-check 默认值
- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web search 和 OpenWebUI
- `full`：包含 OpenWebUI 的 Docker 发布路径分块
- `smoke`：快速包安装/渠道/智能体、Gateway 网关网络和配置热重载通道
- `package`：不含 live ClawHub 的安装/更新/插件包契约；这是 release-check
默认值
- `product`：`package` 加上 MCP 渠道、cron/subagent 清理、OpenAI web
search 和 OpenWebUI
- `full`：带 OpenWebUI 的 Docker 发布路径分块
- `custom`：用于聚焦重跑的精确 `docker_lanes` 列表
对于包候选 Telegram 证明，请在 Package Acceptance 上启用 `telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该工作流会把已解析的 `package-under-test` tarball 传入 Telegram 通道；独立 Telegram 工作流仍接受已发布的 npm spec，用于发布后检查。
对于包候选 Telegram 证明，请在 Package Acceptance 上启用
`telegram_mode=mock-openai` 或 `telegram_mode=live-frontier`。该 workflow
会把已解析的 `package-under-test` tarball 传入 Telegram 通道；独立
Telegram workflow 仍接受已发布的 npm spec，用于发布后检查。
## NPM 工作流输入
## NPM workflow 输入
`OpenClaw NPM Release` 接受这些由操作员控制的输入：
`OpenClaw NPM Release` 接受以下由操作员控制的输入：
- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或 `v2026.4.2-beta.1`；当 `preflight_only=true` 时，它也可以是当前完整 40 字符工作流分支提交 SHA，用于仅验证的预检
- `tag`：必需的发布标签，例如 `v2026.4.2`、`v2026.4.2-1` 或
`v2026.4.2-beta.1`；当 `preflight_only=true` 时，也可以是当前完整
40 字符 workflow 分支 commit SHA，用于仅验证的预检
- `preflight_only`：`true` 表示仅验证/构建/打包，`false` 表示真实发布路径
- `preflight_run_id`：真实发布路径必需，以便工作流复用成功预检运行准备的 tarball
- `preflight_run_id`：真实发布路径必需，这样 workflow 会复用成功预检运行
准备好的 tarball
- `npm_dist_tag`：发布路径的 npm 目标标签；默认为 `beta`
`OpenClaw Release Checks` 接受这些由操作员控制的输入：
`OpenClaw Release Checks` 接受以下由操作员控制的输入：
- `ref`：要验证的分支、标签或完整提交 SHA。带密钥的检查要求已解析提交可从 OpenClaw 分支或发布标签访问。
- `ref`：要验证的分支、标签或完整 commit SHA。带密钥的检查要求解析后的
commit 可从 OpenClaw 分支或发布标签访问。
规则：
- 稳定标签和修正标签可以发布到 `beta` 或 `latest`
- 稳定版和修正版标签可以发布到 `beta` 或 `latest`
- Beta 预发布标签只能发布到 `beta`
- 对于 `OpenClaw NPM Release`，仅当 `preflight_only=true` 时才允许输入完整提交 SHA
- `OpenClaw Release Checks` 和 `Full Release Validation` 始终只做验证
- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；工作流会在发布继续前验证该元数据
- 对于 `OpenClaw NPM Release`，仅当 `preflight_only=true` 时才允许输入
完整 commit SHA
- `OpenClaw Release Checks` 和 `Full Release Validation` 始终仅用于验证
- 真实发布路径必须使用预检期间使用的同一个 `npm_dist_tag`；workflow 会
在发布继续前验证该元数据
## 稳定 npm 发布流程
## 稳定版 npm 发布序列
切稳定 npm 发布时：
切稳定版 npm 发布时：
1. 使用 `preflight_only=true` 运行 `OpenClaw NPM Release`
- 在标签存在之前，你可以使用当前完整工作流分支提交 SHA，对预检工作流进行仅验证的空运行
2. 对常规 beta 优先流程选择 `npm_dist_tag=beta`，或者仅在你有意直接发布稳定版时选择 `latest`
3. 当你希望从一个手动工作流获得常规 CI 加上实时 prompt cache、Docker、QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整提交 SHA 上运行 `Full Release Validation`
4. 如果你有意只需要确定性的常规测试图，请改为在发布 ref 上运行手动 `CI` 工作流
- 在标签存在前，可以使用当前完整 workflow 分支 commit SHA，对预检
workflow 做一次仅验证的 dry run
2. 普通 beta-first 流程选择 `npm_dist_tag=beta`；只有在有意直接发布稳定版时
才选择 `latest`
3. 当你想从一个手动 workflow 获得普通 CI 加 live prompt cache、Docker、
QA Lab、Matrix 和 Telegram 覆盖时，在发布分支、发布标签或完整 commit SHA
上运行 `Full Release Validation`
4. 如果你有意只需要确定性的普通测试图，则改为在发布 ref 上运行手动 `CI`
workflow
5. 保存成功的 `preflight_run_id`
6. 再次运行 `OpenClaw NPM Release`，并使用 `preflight_only=false`、相同的 `tag`、相同的 `npm_dist_tag` 和已保存的 `preflight_run_id`
7. 如果发布落在 `beta`，使用私有 `openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml` 工作流，将该稳定版本从 `beta` 提升到 `latest`
8. 如果发布有意直接发布到 `latest`，且 `beta` 应立即跟随同一个稳定构建，请使用同一个私有工作流将两个 dist-tag 都指向该稳定版本，或者让它的计划自修复同步稍后移动 `beta`
6. 再次运行 `OpenClaw NPM Release`，并使用 `preflight_only=false`、相同的
`tag`、相同的 `npm_dist_tag`，以及已保存的 `preflight_run_id`
7. 如果发布落在 `beta`，请使用私有
`openclaw/releases-private/.github/workflows/openclaw-npm-dist-tags.yml`
workflow 将该稳定版本从 `beta` 提升到 `latest`
8. 如果发布有意直接发布到 `latest`，并且 `beta` 应立即跟随同一个稳定构建，
请使用同一个私有 workflow 将两个 dist-tag 指向该稳定版本，或让其计划式
自修复同步稍后移动 `beta`
dist-tag 变更位于私有仓库中，是出于安全原因，因为它仍然需要 `NPM_TOKEN`，而公共仓库保持仅 OIDC 发布。
dist-tag 变更位于私有仓库中是出于安全考虑，因为它仍然需要 `NPM_TOKEN`，
而公共仓库保持仅 OIDC 发布。
这会让直接发布路径和 beta 优先提升路径都保持已文档化，并对操作员可见。
这样可以让直接发布路径和 beta-first 提升路径都得到记录，并对操作员可见。
如果维护者必须回退到本地 npm 认证，请仅在专用 tmux 会话内运行任何 1Password
CLI (`op`) 命令。不要直接从主智能体 shell 调用 `op`；将其保持在 tmux 内可以让提示、
警报和 OTP 处理过程可观察，并防止重复的主机警报。
如果维护者必须回退到本地 npm 身份验证，只能在专用的 tmux 会话中运行任何 1Password
CLI（`op`）命令。不要直接从主智能体 shell 调用 `op`；将它保留在 tmux 内可以让提示、
警报和 OTP 处理可观察，并防止重复的主机警报。
## 公共参考资料
@ -338,6 +415,6 @@ CLI (`op`) 命令。不要直接从主智能体 shell 调用 `op`；将其保持
[`openclaw/maintainers/release/README.md`](https://github.com/openclaw/maintainers/blob/main/release/README.md)
中的私有发布文档作为实际运行手册。
## 相关内容
## 相关
- [发布渠道](/zh-CN/install/development-channels)