支持的引导分区：workspace、model、web、gateway、daemon、channels、plugins、skills、health。

示例

openclaw config file
openclaw config --section model
openclaw config --section gateway --section daemon
openclaw config schema
openclaw config get browser.executablePath
openclaw config set browser.executablePath "/usr/bin/google-chrome"
openclaw config set browser.profiles.work.executablePath "/Applications/Google Chrome.app/Contents/MacOS/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/gpt-5.4":{}}' --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 patch --file ./openclaw.patch.json5 --dry-run
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN --dry-run
openclaw config validate
openclaw config validate --json

config schema

将为 openclaw.json 生成的 JSON schema 以 JSON 形式打印到 stdout。

- 当前根配置 schema，以及供编辑器工具使用的根 $schema 字符串字段。
- Control UI 使用的字段 title 和 description 文档元数据。
- 当存在匹配字段文档时，嵌套对象、通配符（*）和数组项（[]）节点会继承相同的 title / description 元数据。
- 当存在匹配字段文档时，anyOf / oneOf / allOf 分支也会继承相同的文档元数据。
- 当可加载运行时清单时，尽力提供实时插件 + 渠道 schema 元数据。
- 即使当前配置无效，也会提供干净的回退 schema。

config.schema.lookup 会返回一个规范化配置路径，并附带浅层 schema 节点（title、description、type、enum、const、常见边界）、匹配的 UI 提示元数据以及直接子项摘要。可在 Control UI 或自定义客户端中用于按路径下钻。

openclaw config schema

如果想用其他工具检查或验证它，可以将其管道输出到文件：

openclaw config schema > openclaw.schema.json

路径

路径使用点号或方括号表示法：

openclaw config get agents.defaults.workspace
openclaw config get agents.list[0].id

使用智能体列表索引来定位特定智能体：

openclaw config get agents.list
openclaw config set agents.list[1].tools.exec.node "node-id-or-name"

值

值会在可能时按 JSON5 解析；否则会被视为字符串。使用 --strict-json 要求必须进行 JSON5 解析。--json 仍作为旧版别名受支持。

openclaw config set agents.defaults.heartbeat.every "0m"
openclaw config set gateway.port 19001 --strict-json
openclaw config set channels.whatsapp.groups '["*"]' --strict-json

config get <path> --json 会将原始值以 JSON 形式打印，而不是终端格式化文本。

对象赋值默认会替换目标路径。常用于保存用户添加条目的受保护映射/列表路径，例如 agents.defaults.models、models.providers、models.providers.<id>.models、plugins.entries 和 auth.profiles，会拒绝可能移除现有条目的替换，除非你传入 --replace。

向这些映射添加条目时，请使用 --merge：

openclaw config set agents.defaults.models '{"openai/gpt-5.4":{}}' --strict-json --merge
openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge

只有在你明确希望提供的值成为完整目标值时，才使用 --replace。

config set 模式

openclaw config set 支持四种赋值样式：

bash
openclaw config set <path> <value>

bash
openclaw config set channels.discord.token \
--ref-provider default \
--ref-source env \
--ref-id DISCORD_BOT_TOKEN

提供商构建器模式仅针对 secrets.providers.<alias> 路径：

```bash
openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-timeout-ms 5000
```

bash
openclaw config set --batch-json '[
{
"path": "secrets.providers.default",
"provider": { "source": "env" }
},
{
"path": "channels.discord.token",
"ref": { "source": "env", "provider": "default", "id": "DISCORD_BOT_TOKEN" }
}
]'

```bash
openclaw config set --batch-file ./config-set.batch.json --dry-run
```

SecretRef 赋值会在不支持运行时可变的表面上被拒绝（例如 hooks.token、commands.ownerDisplaySecret、Discord 线程绑定 webhook token，以及 WhatsApp 凭据 JSON）。请参阅 SecretRef 凭据表面。

批量解析始终使用批量载荷（--batch-json/--batch-file）作为真实来源。--strict-json / --json 不会改变批量解析行为。

config patch

当你想粘贴或管道传入配置形状的补丁，而不是运行许多基于路径的 config set 命令时，请使用 config patch。输入是 JSON5 对象。对象会递归合并，数组和标量值会替换目标值，null 会删除目标路径。

openclaw config patch --file ./openclaw.patch.json5 --dry-run
openclaw config patch --file ./openclaw.patch.json5

你也可以通过 stdin 管道传入补丁，这对远程设置脚本很有用：

ssh openclaw-host 'openclaw config patch --stdin --dry-run' < ./openclaw.patch.json5
ssh openclaw-host 'openclaw config patch --stdin' < ./openclaw.patch.json5

示例补丁：

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      groupPolicy: "open",
      requireMention: false,
    },
    discord: {
      enabled: true,
      token: { source: "env", provider: "default", id: "DISCORD_BOT_TOKEN" },
      dmPolicy: "disabled",
      dm: { enabled: false },
      groupPolicy: "allowlist",
    },
  },
  agents: {
    defaults: {
      model: { primary: "openai/gpt-5.5" },
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}

当某个对象或数组必须精确变成提供的值，而不是递归修补时，请使用 --replace-path <path>：

openclaw config patch --file ./discord.patch.json5 --replace-path 'channels.discord.guilds["123"].channels'

--dry-run 会运行 schema 和 SecretRef 可解析性检查，但不会写入。dry-run 期间默认跳过由 exec 支持的 SecretRef；当你明确希望 dry-run 执行提供商命令时，请添加 --allow-exec。

JSON 路径/值模式仍支持 SecretRef 和提供商：

openclaw config set channels.discord.token \
  '{"source":"env","provider":"default","id":"DISCORD_BOT_TOKEN"}' \
  --strict-json

openclaw config set secrets.providers.vaultfile \
  '{"source":"file","path":"/etc/openclaw/secrets.json","mode":"json"}' \
  --strict-json

提供商构建器标志

提供商构建器目标必须使用 secrets.providers.<alias> 作为路径。

- --provider-source <env|file|exec>
- --provider-timeout-ms <ms>（file、exec）

- --provider-allowlist <ENV_VAR>（可重复）

- --provider-path <path>（必需）
- --provider-mode <singleValue|json>
- --provider-max-bytes <bytes>
- --provider-allow-insecure-path

- --provider-command <path>（必需）
- --provider-arg <arg>（可重复）
- --provider-no-output-timeout-ms <ms>
- --provider-max-output-bytes <bytes>
- --provider-json-only
- --provider-env <KEY=VALUE>（可重复）
- --provider-pass-env <ENV_VAR>（可重复）
- --provider-trusted-dir <path>（可重复）
- --provider-allow-insecure-path
- --provider-allow-symlink-command

强化的 exec 提供商示例：

openclaw config set secrets.providers.vault \
  --provider-source exec \
  --provider-command /usr/local/bin/openclaw-vault \
  --provider-arg read \
  --provider-arg openai/api-key \
  --provider-json-only \
  --provider-pass-env VAULT_TOKEN \
  --provider-trusted-dir /usr/local/bin \
  --provider-timeout-ms 5000

Dry run

使用 --dry-run 验证更改，而不写入 openclaw.json。

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run

openclaw config set channels.discord.token \
  --ref-provider default \
  --ref-source env \
  --ref-id DISCORD_BOT_TOKEN \
  --dry-run \
  --json

openclaw config set channels.discord.token \
  --ref-provider vault \
  --ref-source exec \
  --ref-id discord/token \
  --dry-run \
  --allow-exec

- 构建器模式：对已更改的引用/提供商运行 SecretRef 可解析性检查。
- JSON 模式（--strict-json、--json 或批量模式）：运行 schema 验证以及 SecretRef 可解析性检查。
- 策略验证也会针对已知不受支持的 SecretRef 目标表面运行。
- 策略检查会评估完整的更改后配置，因此父对象写入（例如将 hooks 设置为对象）无法绕过不受支持表面的验证。
- dry-run 期间默认跳过 exec SecretRef 检查，以避免命令副作用。
- 将 --allow-exec 与 --dry-run 一起使用可选择启用 exec SecretRef 检查（这可能会执行提供商命令）。
- --allow-exec 仅适用于 dry-run；如果不与 --dry-run 一起使用，会报错。

--dry-run --json 会打印机器可读报告：

- `ok`：dry-run 是否通过
- `operations`：已评估的赋值数量
- `checks`：是否运行了 schema/可解析性检查
- `checks.resolvabilityComplete`：可解析性检查是否运行完成（跳过 exec 引用时为 false）
- `refsChecked`：dry-run 期间实际解析的引用数量
- `skippedExecRefs`：由于未设置 `--allow-exec` 而跳过的 exec 引用数量
- `errors`：`ok=false` 时的结构化 schema/可解析性失败

JSON 输出结构

{
  ok: boolean,
  operations: number,
  configPath: string,
  inputModes: ["value" | "json" | "builder", ...],
  checks: {
    schema: boolean,
    resolvability: boolean,
    resolvabilityComplete: boolean,
  },
  refsChecked: number,
  skippedExecRefs: number,
  errors?: [
    {
      kind: "schema" | "resolvability",
      message: string,
      ref?: string, // present for resolvability errors
    },
  ],
}

json
{
"ok": true,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0
}

json
{
"ok": false,
"operations": 1,
"configPath": "~/.openclaw/openclaw.json",
"inputModes": ["builder"],
"checks": {
"schema": false,
"resolvability": true,
"resolvabilityComplete": true
},
"refsChecked": 1,
"skippedExecRefs": 0,
"errors": [
{
"kind": "resolvability",
"message": "Error: Environment variable \"MISSING_TEST_SECRET\" is not set.",
"ref": "env:default:MISSING_TEST_SECRET"
}
]
}

- config schema validation failed：变更后的配置结构无效；修正路径/值或 提供商/ref 对象结构。
- Config policy validation failed: unsupported SecretRef usage：将该凭证移回明文/字符串输入，并仅在受支持的表面上保留 SecretRefs。
- SecretRef assignment(s) could not be resolved：引用的 提供商/ref 当前无法解析（缺少环境变量、文件指针无效、exec 提供商失败，或 提供商/source 不匹配）。
- Dry run note: skipped <n> exec SecretRef resolvability check(s)：dry-run 跳过了 exec 引用；如果需要 exec 可解析性验证，请使用 --allow-exec 重新运行。
- 对于批处理模式，请修正失败条目，并在写入前重新运行 --dry-run。

写入安全

openclaw config set 和其他由 OpenClaw 拥有的配置写入器会在提交到磁盘前验证完整的变更后配置。如果新载荷未通过 schema 验证，或看起来像破坏性覆盖，活动配置会保持不变，被拒绝的载荷会以 openclaw.json.rejected.* 保存到旁边。

活动配置路径必须是常规文件。不支持对符号链接的 openclaw.json 布局执行写入；请改用 OPENCLAW_CONFIG_PATH 直接指向真实文件。

小改动优先使用 CLI 写入：

openclaw config set gateway.reload.mode hybrid --dry-run
openclaw config set gateway.reload.mode hybrid
openclaw config validate

如果写入被拒绝，请检查保存的载荷并修正完整配置结构：

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".rejected.* 2>/dev/null | head
openclaw config validate

仍然允许直接用编辑器写入，但运行中的 Gateway 网关会在其通过验证前将其视为不可信。无效的直接编辑会导致启动失败，或被热重载跳过；Gateway 网关不会重写 openclaw.json。运行 openclaw doctor --fix 可修复带前缀/被覆盖的配置，或恢复最后一个已知良好的副本。参见 Gateway 网关故障排除。

整文件恢复保留给 Doctor 修复。插件 schema 变更或 minHostVersion 偏差会明确报错，而不是回滚无关的用户设置，例如 模型、提供商、凭证配置文件、渠道、Gateway 网关暴露、工具、memory、browser 或 cron 配置。

子命令

• config file：打印活动配置文件路径（从 OPENCLAW_CONFIG_PATH 或默认位置解析）。该路径应指向常规文件，而不是符号链接。

编辑后重启 Gateway 网关。

验证

在不启动 Gateway 网关的情况下，根据活动 schema 验证当前配置。

openclaw config validate
openclaw config validate --json

openclaw config validate 通过后，你可以使用本地 TUI，让嵌入式智能体在你从同一个终端验证每项更改时，将活动配置与文档进行比较：

如果验证已经失败，请先运行 openclaw configure 或 openclaw doctor --fix。openclaw chat 不会绕过无效配置保护。

openclaw chat

然后在 TUI 内：

!openclaw config file
!openclaw docs gateway auth token secretref
!openclaw config validate
!openclaw doctor

典型修复循环：

让智能体将你的当前配置与相关文档页面进行比较，并建议最小修复。

使用 openclaw config set 或 openclaw configure 应用定向编辑。

每次更改后重新运行 openclaw config validate。

如果验证通过但运行时仍不健康，请运行 openclaw doctor 或 openclaw doctor --fix 获取迁移和修复帮助。

相关内容

• CLI 参考
• 配置

📄 配置

原文：https://docs.openclaw.ai/zh-CN/cli/configure

openclaw configure

用于对现有设置进行定向更改的交互式提示：凭证、设备、智能体默认值、Gateway 网关、渠道、插件、Skills 和健康检查。

使用 openclaw onboard 完成完整的首次运行引导流程，使用 openclaw setup 仅设置基线配置/工作区，只需要设置渠道账号时使用 openclaw channels add。

模型部分包含一个用于 agents.defaults.models 允许列表的多选项（会显示在 /model 和模型选择器中）。按提供商范围设置的选择会将所选模型合并到现有允许列表中，而不是替换配置中已有的其他无关提供商。

从 configure 重新运行提供商认证会保留现有的 agents.defaults.model.primary，即使提供商的认证步骤返回了带有其推荐默认模型的配置补丁也是如此。这意味着添加或重新认证 xAI、OpenRouter 或其他提供商时，应会让新模型可用，而不会接管你当前的主模型。只有在你明确想更改默认模型时，才使用 openclaw models auth login --provider <id> --set-default 或 openclaw models set <model>。

当 configure 从提供商认证选择启动时，默认模型和允许列表选择器会自动优先使用该提供商。对于 Volcengine 和 BytePlus 等成对提供商，相同的偏好也会匹配它们的编码计划变体（volcengine-plan/*、byteplus-plan/*）。如果首选提供商筛选器会生成空列表，configure 会回退到未筛选的目录，而不是显示空白选择器。

不带子命令的 openclaw config 会打开同一个向导。使用 openclaw config get|set|unset 进行非交互式编辑。

对于 Web 搜索，openclaw configure --section web 可让你选择提供商
并配置其凭证。某些提供商还会显示特定于提供商的
后续提示：

• Grok 可以使用相同的 XAI_API_KEY 提供可选的 x_search 设置，并
  让你选择一个 x_search 模型。
• Kimi 可以询问 Moonshot API 区域（api.moonshot.ai 与
  api.moonshot.cn）以及默认 Kimi Web 搜索模型。

相关：

• Gateway 网关配置参考：配置
• 配置 CLI：配置

选项

• --section <section>：可重复的部分筛选器

可用部分：

• workspace
• model
• web
• gateway
• daemon
• channels
• plugins
• skills
• health

注意事项：

• 选择 Gateway 网关运行位置总是会更新 gateway.mode。如果这就是你需要的全部内容，可以在不选择其他部分的情况下选择“继续”。
• 写入本地配置后，如果所选设置路径需要可下载插件，configure 会安装所选插件。远程 Gateway 网关配置不会安装本地插件包。
• 面向渠道的服务（Slack/Discord/Matrix/Microsoft Teams）会在设置期间提示输入渠道/房间允许列表。你可以输入名称或 ID；向导会在可能的情况下将名称解析为 ID。
• 如果你运行 daemon 安装步骤，令牌认证需要令牌，并且 gateway.auth.token 由 SecretRef 管理，configure 会验证 SecretRef，但不会将解析后的明文令牌值持久化到 supervisor 服务环境元数据中。
• 如果令牌认证需要令牌，而配置的令牌 SecretRef 未解析，configure 会阻止 daemon 安装，并给出可执行的修复指导。
• 如果同时配置了 gateway.auth.token 和 gateway.auth.password，且 gateway.auth.mode 未设置，configure 会阻止 daemon 安装，直到显式设置模式。

示例

openclaw configure
openclaw configure --section web
openclaw configure --section model --section channels
openclaw configure --section gateway --section daemon

相关

• CLI 参考
• 配置

📄 Cron

原文：https://docs.openclaw.ai/zh-CN/cli/cron

openclaw cron

管理 Gateway 网关调度器的 cron 任务。

运行 openclaw cron --help 查看完整命令界面。概念指南请参阅 Cron 任务。

会话

--session 接受 main、isolated、current 或 session:<id>。

- main 绑定到智能体的主会话。
- isolated 为每次运行创建新的转录记录和会话 ID。
- current 绑定到创建时的活动会话。
- session:<id> 固定到一个显式的持久会话键。

隔离运行会重置环境对话上下文。渠道和群组路由、发送/排队策略、提权、来源以及 ACP 运行时绑定都会为新运行重置。安全偏好设置以及用户显式选择的模型或凭证覆盖项可以跨运行保留。

递送

openclaw cron list 和 openclaw cron show <job-id> 会预览解析后的递送路由。对于 channel: "last"，预览会显示路由是从主会话还是当前会话解析得到，或者会以关闭失败告终。

带提供商前缀的目标可以消除未解析公告渠道的歧义。例如，to: "telegram:123" 会在省略 delivery.channel 或其为 last 时选择 Telegram。只有已加载插件声明的前缀才是提供商选择器。如果 delivery.channel 是显式的，前缀必须与该渠道匹配；channel: "whatsapp" 搭配 to: "telegram:123" 会被拒绝。imessage: 和 sms: 等服务前缀仍然是由渠道拥有的目标语法。

隔离的 cron add 任务默认使用 --announce 递送。使用 --no-deliver 可将输出保留在内部。--deliver 仍作为 --announce 的已弃用别名保留。

递送所有权

隔离 cron 聊天递送由智能体和运行器共享：

• 当聊天路由可用时，智能体可以使用 message 工具直接发送。
• 只有当智能体未直接发送到解析后的目标时，announce 才会回退递送最终回复。
• webhook 将完成后的负载发布到 URL。
• none 禁用运行器回退递送。

--announce 是最终回复的运行器回退递送。--no-deliver 会禁用该回退，但当聊天路由可用时，不会移除智能体的 message 工具。

从活动聊天创建的提醒会保留实时聊天递送目标，用于回退公告递送。内部会话键可能是小写；不要把它们当作用于区分大小写的提供商 ID 的事实来源，例如 Matrix 房间 ID。

失败递送

失败通知按以下顺序解析：

1. 任务上的 delivery.failureDestination。
2. 全局 cron.failureDestination。
3. 任务的主要公告目标（未设置显式失败目标时）。

主会话任务仅在主要递送模式为 webhook 时才可使用 delivery.failureDestination。隔离任务在所有模式下都接受它。

注意：隔离 cron 运行会将运行级智能体失败视为任务错误，即使没有生成回复负载也是如此，因此模型/提供商失败仍会递增错误计数器并触发失败通知。

如果隔离运行在首次模型请求前超时，openclaw cron show 和 openclaw cron runs 会包含阶段特定错误，例如 setup timed out before runner start 或 stalled before first model call (last phase: context-engine)。对于 CLI 支持的提供商，预模型看门狗会保持活动状态，直到外部 CLI 轮次开始，因此会话查找、钩子、凭证、提示词和 CLI 设置卡顿会被报告为预模型 cron 失败。

调度

一次性任务

--at <datetime> 会调度一次性运行。不带偏移量的日期时间会被视为 UTC，除非你同时传入 --tz <iana>，此时会按给定时区解释挂钟时间。

一次性任务默认在成功后删除。使用 --keep-after-run 可保留它们。

周期性任务

周期性任务在连续错误后使用指数重试退避：30 秒、1 分钟、5 分钟、15 分钟、60 分钟。下一次成功运行后，调度会恢复正常。

跳过的运行与执行错误分开跟踪。它们不会影响重试退避，但 openclaw cron edit <job-id> --failure-alert-include-skipped 可以让失败警报包含重复的跳过运行通知。

对于以本地配置模型提供商为目标的隔离任务，cron 会在启动智能体轮次前运行轻量级提供商预检。Loopback、私有网络和 .local 的 api: "ollama" 提供商会在 /api/tags 上探测；本地 OpenAI 兼容提供商（例如 vLLM、SGLang 和 LM Studio）会在 /models 上探测。如果端点不可达，该运行会记录为 skipped，并在之后的调度中重试；匹配的失效端点会缓存 5 分钟，以避免大量任务冲击同一个本地服务器。

注意：cron 任务定义位于 jobs.json，而待处理运行时状态位于 jobs-state.json。如果 jobs.json 被外部编辑，Gateway 网关会重新加载已更改的调度并清除陈旧的待处理槽位；仅格式化的重写不会清除待处理槽位。

手动运行

openclaw cron run 会在手动运行排队后立即返回。成功响应包含 { ok: true, enqueued: true, runId }。使用 openclaw cron runs --id <job-id> 跟踪最终结果。

openclaw cron run <job-id> 默认强制运行。使用 --due 可保留旧的“仅在到期时运行”行为。

Models

cron add|edit --model <ref> 为任务选择允许的模型。

如果模型不被允许或无法解析，cron 会让运行因显式验证错误而失败，而不是回退到任务的智能体或默认模型选择。

Cron --model 是任务主模型，不是聊天会话 /model 覆盖。这意味着：

• 当所选任务模型失败时，配置的模型回退仍然适用。
• 当存在按任务负载的 fallbacks 时，它会替换配置的回退列表。
• 空的按任务回退列表（任务负载/API 中的 fallbacks: []）会使 cron 运行严格执行。
• 当任务有 --model 但未配置回退列表时，OpenClaw 会传入显式空回退覆盖项，这样智能体主模型就不会作为隐藏重试目标追加。

隔离 cron 模型优先级

隔离 cron 按以下顺序解析活动模型：

1. Gmail 钩子覆盖项。
2. 按任务的 --model。
3. 已存储的 cron 会话模型覆盖项（当用户选择了一个时）。
4. 智能体或默认模型选择。

快速模式

隔离 cron 快速模式遵循解析后的实时模型选择。模型配置 params.fastMode 默认适用，但已存储的会话 fastMode 覆盖项仍优先于配置。

实时模型切换重试

如果隔离运行抛出 LiveSessionModelSwitchError，cron 会在重试前为活动运行持久化切换后的提供商和模型（以及存在时切换后的凭证配置覆盖项）。外层重试循环在初始尝试后最多允许两次切换重试，随后中止而不是无限循环。

运行输出和拒绝

陈旧确认抑制

隔离 cron 轮次会抑制陈旧的仅确认回复。如果第一个结果只是临时状态更新，并且没有后代子智能体运行负责最终答案，cron 会在递送前重新提示一次以获取真实结果。

静默令牌抑制

如果隔离 cron 运行只返回静默令牌（NO_REPLY 或 no_reply），cron 会同时抑制直接出站递送和回退排队摘要路径，因此不会向聊天发回任何内容。

结构化拒绝

隔离 cron 运行优先使用嵌入式运行中的结构化执行拒绝元数据，然后回退到最终输出中的已知拒绝标记，例如 SYSTEM_RUN_DENIED、INVALID_REQUEST 和审批绑定拒绝短语。

cron list 和运行历史会显示拒绝原因，而不是将被阻止的命令报告为 ok。

保留

保留和修剪在配置中控制：

• cron.sessionRetention（默认 24h）会修剪已完成的隔离运行会话。
• cron.runLog.maxBytes 和 cron.runLog.keepLines 会修剪 ~/.openclaw/cron/runs/<jobId>.jsonl。

迁移旧任务

如果你有当前递送和存储格式之前的 cron 任务，请运行 openclaw doctor --fix。Doctor 会规范化旧版 cron 字段（jobId、schedule.cron、顶层递送字段，包括旧版 threadId、负载 provider 递送别名），并在配置了 cron.webhook 时，将简单的 notify: true webhook 回退任务迁移为显式 webhook 递送。

常见编辑

更新递送设置而不更改消息：

openclaw cron edit <job-id> --announce --channel telegram --to "123456789"

禁用隔离任务的递送：

openclaw cron edit <job-id> --no-deliver

为隔离任务启用轻量级引导上下文：

openclaw cron edit <job-id> --light-context

公告到特定渠道：

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"

公告到 Telegram 论坛话题：

openclaw cron edit <job-id> --announce --channel telegram --to "-1001234567890" --thread-id 42

创建带轻量级引导上下文的隔离任务：

openclaw cron add \
  --name "Lightweight morning brief" \
  --cron "0 7 * * *" \
  --session isolated \
  --message "Summarize overnight updates." \
  --light-context \
  --no-deliver

--light-context 仅适用于隔离智能体轮次任务。对于 cron 运行，轻量级模式会保持引导上下文为空，而不是注入完整的工作区引导集。

常见管理命令

手动运行和检查：

openclaw cron list
openclaw cron list --agent ops
openclaw cron get <job-id>
openclaw cron show <job-id>
openclaw cron run <job-id>
openclaw cron run <job-id> --due
openclaw cron runs --id <job-id> --limit 50

openclaw cron list 默认显示所有匹配的任务。传入 --agent <id> 可仅显示有效规范化智能体 ID 匹配的任务；没有存储智能体 ID 的任务会计为配置的默认智能体。

openclaw cron get <job-id> 会直接返回存储的任务 JSON。当你需要带递送路由预览的可读视图时，请使用 cron show <job-id>。

cron list --json 和 cron show <job-id> --json 在每个任务上包含顶层 status 字段，该字段根据 enabled、state.runningAtMs 和 state.lastRunStatus 计算。取值：disabled、running、ok、error、skipped 或 idle。这与可读状态列保持一致，因此外部工具可以读取任务状态，而无需重新推导。

cron runs 条目包含递送诊断信息，包括预期的 cron 目标、解析后的目标、message 工具发送、回退使用情况以及已递送状态。

智能体和会话重定向：

openclaw cron edit <job-id> --agent ops
openclaw cron edit <job-id> --clear-agent
openclaw cron edit <job-id> --session current
openclaw cron edit <job-id> --session "session:daily-brief"

openclaw cron add 会在智能体轮次任务省略 --agent 时发出警告，并回退到默认智能体（main）。创建时传入 --agent <id> 可固定到特定智能体。

递送微调：

openclaw cron edit <job-id> --announce --channel slack --to "channel:C1234567890"
openclaw cron edit <job-id> --best-effort-deliver
openclaw cron edit <job-id> --no-best-effort-deliver
openclaw cron edit <job-id> --no-deliver

相关

• CLI 参考
• 定时任务

📄 仪表盘

原文：https://docs.openclaw.ai/zh-CN/cli/dashboard

openclaw dashboard

使用你当前的认证信息打开控制 UI。

openclaw dashboard
openclaw dashboard --no-open

注意事项：

• dashboard 会尽可能解析已配置的 gateway.auth.token SecretRefs。
• dashboard 遵循 gateway.tls.enabled：启用 TLS 的 Gateway 网关会打印/打开
  https:// 控制 UI URL，并通过 wss:// 连接。
• 如果带令牌认证的仪表板 URL 的剪贴板/浏览器传递失败，
  dashboard 会记录一条安全的手动认证提示，提到 OPENCLAW_GATEWAY_TOKEN、
  gateway.auth.token 和片段键 token，但不会打印令牌
  值。
• 对于由 SecretRef 管理的令牌（无论已解析或未解析），dashboard 会打印/复制/打开不含令牌的 URL，以避免在终端输出、剪贴板历史记录或浏览器启动参数中暴露外部密钥。
• 如果 gateway.auth.token 由 SecretRef 管理，但在此命令路径中未解析，该命令会打印不含令牌的 URL 和明确的修复指导，而不是嵌入无效的令牌占位符。

相关

• CLI 参考
• 仪表板

📄 设备

原文：https://docs.openclaw.ai/zh-CN/cli/devices

openclaw devices

管理设备配对请求和设备作用域的令牌。

命令

openclaw devices list

列出待处理的配对请求和已配对设备。

openclaw devices list
openclaw devices list --json

当设备已经配对时，待处理请求输出会在设备当前已批准访问权限旁显示请求的访问权限。这样会明确显示作用域/角色升级，而不是看起来像配对丢失了。

openclaw devices remove <deviceId>

移除一个已配对设备条目。

当你使用已配对设备令牌进行身份验证时，非管理员调用者只能移除自己的设备条目。移除其他设备需要 operator.admin。

openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json

openclaw devices clear --yes [--pending]

批量清除已配对设备。

openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json

openclaw devices approve [requestId] [--latest]

通过精确的 requestId 批准待处理的设备配对请求。如果省略 requestId 或传入 --latest，OpenClaw 只会打印选中的待处理请求并退出；请在确认详情后，用精确的请求 ID 重新运行批准命令。

如果设备使用已更改的凭证详情（角色、作用域或公钥）重试配对，OpenClaw 会取代之前的待处理条目，并签发新的 requestId。请在批准前立即运行 openclaw devices list，以使用当前 ID。

如果设备已经配对，并请求更广的作用域或更高的角色，OpenClaw 会保留现有批准，并创建新的待处理升级请求。请在 openclaw devices list 中查看 Requested 与 Approved 列，或使用 openclaw devices approve --latest 在批准前预览精确的升级内容。

如果 Gateway 网关显式配置了 gateway.nodes.pairing.autoApproveCidrs，来自匹配客户端 IP 的首次 role: node 请求可以在出现在此列表之前被批准。该策略默认禁用，并且绝不适用于操作员/浏览器客户端或升级请求。

openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest

openclaw devices reject <requestId>

拒绝待处理的设备配对请求。

openclaw devices reject <requestId>

openclaw devices rotate --device <id> --role <role> [--scope <scope...>]

轮换特定角色的设备令牌（可选择更新作用域）。
目标角色必须已经存在于该设备已批准的配对契约中；轮换不能生成新的未批准角色。
如果省略 --scope，后续使用已存储轮换令牌重新连接时，会复用该令牌缓存的已批准作用域。如果传入显式的 --scope 值，这些值会成为未来缓存令牌重新连接的已存储作用域集合。
非管理员的已配对设备调用者只能轮换自己的设备令牌。
目标令牌作用域集合必须保持在调用者会话自身的操作员作用域内；轮换不能生成或保留比调用者已拥有权限更广的操作员令牌。

openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write

以 JSON 返回轮换元数据。如果调用者在使用该设备令牌进行身份验证时轮换自己的令牌，响应还会包含替换令牌，以便客户端在重新连接前持久化它。共享/管理员轮换不会回显 bearer 令牌。

openclaw devices revoke --device <id> --role <role>

撤销特定角色的设备令牌。

非管理员的已配对设备调用者只能撤销自己的设备令牌。撤销其他设备的令牌需要 operator.admin。
目标令牌作用域集合也必须符合调用者会话自身的操作员作用域；仅配对调用者不能撤销管理员/写入操作员令牌。

openclaw devices revoke --device <deviceId> --role node

以 JSON 返回撤销结果。

常用选项

• --url <url>：Gateway 网关 WebSocket URL（配置后默认为 gateway.remote.url）。
• --token <token>：Gateway 网关令牌（如需要）。
• --password <password>：Gateway 网关密码（密码凭证）。
• --timeout <ms>：RPC 超时。
• --json：JSON 输出（推荐用于脚本）。

设置 --url 时，CLI 不会回退到配置或环境凭证。请显式传入 --token 或 --password。缺少显式凭证是错误。

说明

• 令牌轮换会返回新令牌（敏感）。请像处理密钥一样处理它。
• 这些命令需要 operator.pairing（或 operator.admin）作用域。某些批准还要求调用者持有目标设备将生成或继承的操作员作用域；请参阅操作员作用域。
• gateway.nodes.pairing.autoApproveCidrs 是仅用于新节点设备配对的可选 Gateway 网关策略；它不会更改 CLI 批准权限。
• 令牌轮换和撤销会保持在该设备已批准的配对角色集合和已批准作用域基线内。游离的缓存令牌条目不会授予令牌管理目标。
• 对于已配对设备令牌会话，跨设备管理仅限管理员：除非调用者拥有 operator.admin，否则 remove、rotate 和 revoke 仅限自操作。
• 令牌变更也受调用者作用域约束：仅配对会话不能轮换或撤销当前携带 operator.admin 或 operator.write 的令牌。
• devices clear 有意要求使用 --yes。
• 如果 local loopback 上配对作用域不可用（且未传入显式 --url），list/approve 可以使用本地配对回退。
• devices approve 在生成令牌前需要显式请求 ID；省略 requestId 或传入 --latest 只会预览最新的待处理请求。

令牌漂移恢复检查清单

当控制 UI 或其他客户端持续因 AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH 或 AUTH_SCOPE_MISMATCH 失败时使用此清单。

1. 确认当前 Gateway 网关令牌来源：

openclaw config get gateway.auth.token

2. 列出已配对设备并识别受影响的设备 ID：

openclaw devices list

3. 为受影响设备轮换操作员令牌：

openclaw devices rotate --device <deviceId> --role operator

4. 如果轮换还不够，移除过时配对并重新批准：

openclaw devices remove <deviceId>
openclaw devices list
openclaw devices approve <requestId>

5. 使用当前共享令牌/密码重试客户端连接。

说明：

• 正常重新连接凭证优先级为：显式共享令牌/密码优先，其次是显式 deviceToken，再其次是已存储设备令牌，最后是引导令牌。
• 可信的 AUTH_TOKEN_MISMATCH 恢复可以在一次有界重试中临时同时发送共享令牌和已存储设备令牌。
• AUTH_SCOPE_MISMATCH 表示设备令牌已被识别，但不携带请求的作用域集合；请先修复配对/作用域批准契约，再更改共享 Gateway 网关凭证。

相关：

• 仪表盘凭证故障排除
• Gateway 网关故障排除

相关

• CLI 参考
• 节点

📄 目录

原文：https://docs.openclaw.ai/zh-CN/cli/directory

openclaw directory

用于支持目录查找的渠道（联系人/对等方、群组和 "me"）的目录查找。

常用标志

• --channel <name>：渠道 ID/别名（配置了多个渠道时必需；仅配置一个渠道时自动使用）
• --account <id>：账户 ID（默认：渠道默认值）
• --json：输出 JSON

说明

• directory 旨在帮助你找到可粘贴到其他命令中的 ID（尤其是 openclaw message send --target ...）。
• 对许多渠道来说，结果由配置支持（允许列表/已配置群组），而不是来自实时提供商目录。
• 已安装的渠道插件仍可省略目录支持；在这种情况下，命令会报告不支持的目录操作，而不是重新安装插件。
• 默认输出为 id（有时还有 name），用制表符分隔；脚本使用请加 --json。

将结果用于 message send

openclaw directory peers list --channel slack --query "U0"
openclaw message send --channel slack --target user:U012ABCDEF --message "hello"

ID 格式（按渠道）

• WhatsApp：+15551234567（私信）、1234567890-1234567890@g.us（群组）、120363123456789@newsletter（频道/Newsletter 出站目标）
• Telegram：@username 或数字聊天 ID；群组是数字 ID
• Slack：user:U… 和 channel:C…
• Discord：user:<id> 和 channel:<id>
• Matrix（插件）：user:@user:server、room:!roomId:server 或 #alias:server
• Microsoft Teams（插件）：user:<id> 和 conversation:<id>
• Zalo（插件）：用户 ID（Bot API）
• Zalo Personal / zalouser（插件）：来自 zca（me、friend list、group list）的线程 ID（私信/群组）

自己（"me"）

openclaw directory self --channel zalouser

对等方（联系人/用户）

openclaw directory peers list --channel zalouser
openclaw directory peers list --channel zalouser --query "name"
openclaw directory peers list --channel zalouser --limit 50

群组

openclaw directory groups list --channel zalouser
openclaw directory groups list --channel zalouser --query "work"
openclaw directory groups members --channel zalouser --group-id <id>

相关

• CLI 参考

📄 DNS

原文：https://docs.openclaw.ai/zh-CN/cli/dns

openclaw dns

用于广域设备发现（Tailscale + CoreDNS）的 DNS 辅助工具。目前专注于 macOS + Homebrew CoreDNS。

相关内容：

• Gateway 网关设备发现：设备发现
• 广域设备发现配置：配置

设置

openclaw dns setup
openclaw dns setup --domain openclaw.internal
openclaw dns setup --apply

dns setup

规划或应用用于单播 DNS-SD 设备发现的 CoreDNS 设置。

选项：

• --domain <domain>：广域设备发现域名（例如 openclaw.internal）
• --apply：安装或更新 CoreDNS 配置并重启服务（需要 sudo；仅限 macOS）

它会显示：

• 解析后的设备发现域名
• 区域文件路径
• 当前 tailnet IP
• 推荐的 openclaw.json 设备发现配置
• 需要设置的 Tailscale Split DNS 名称服务器/域名值

注意事项：

• 不带 --apply 时，该命令仅作为规划辅助工具，并会打印推荐设置。
• 如果省略 --domain，OpenClaw 会使用配置中的 discovery.wideArea.domain。
• --apply 目前仅支持 macOS，并要求使用 Homebrew CoreDNS。
• --apply 会在需要时初始化区域文件，确保 CoreDNS import stanza 存在，并重启 coredns brew 服务。

相关内容

• CLI 参考
• 设备发现

📄 文档

原文：https://docs.openclaw.ai/zh-CN/cli/docs

openclaw docs

从终端搜索实时 OpenClaw 文档索引。该命令会调用公开的 Mintlify 托管文档 MCP 搜索端点 https://docs.openclaw.ai/mcp.SearchOpenClaw，并在你的终端中呈现结果。

用法

openclaw docs                       # print docs entrypoint and example search
openclaw docs <query...>            # search the live docs index

参数：

示例

openclaw docs browser existing-session
openclaw docs sandbox allowHostControl
openclaw docs gateway token secretref

没有查询时，openclaw docs 会打印文档入口 URL 和一个示例搜索命令，而不是运行搜索。

工作原理

openclaw docs 会调用 mcporter CLI 来调用文档搜索 MCP 工具，然后将工具输出中的 Title: / Link: / Content: 块解析为结果列表。

为解析 mcporter，OpenClaw 会按顺序检查：

1. PATH 上的 mcporter（如果存在则直接使用）。
2. 如果已安装 pnpm，则使用 pnpm dlx mcporter ...。
3. 如果已安装 npx，则使用 npx -y mcporter ...。

如果都不可用，该命令会失败，并提示安装 pnpm（npm install -g pnpm）。

搜索调用使用固定的 30 秒超时。结果摘要会被截断为每条约 220 个字符。

输出

在富文本（TTY）终端中，结果会呈现为一个标题，后跟项目符号列表。每个项目符号会显示页面标题、链接的文档 URL，以及下一行的简短摘要。空结果会打印 “No results.”。

在非富文本输出中（管道、--no-color、脚本），相同数据会呈现为 Markdown：

# Docs search: <query>

- [Title](https://docs.openclaw.ai/...) - snippet
- [Title](https://docs.openclaw.ai/...) - snippet

退出代码

相关内容

• CLI 参考
• 实时文档

📄 Doctor

原文：https://docs.openclaw.ai/zh-CN/cli/doctor

openclaw doctor

Gateway 网关和渠道的健康检查 + 快速修复。

相关：

• 故障排除：故障排除
• 安全审计：安全

示例

openclaw doctor
openclaw doctor --repair
openclaw doctor --deep
openclaw doctor --repair --non-interactive
openclaw doctor --generate-gateway-token

对于渠道特定权限，请使用渠道探测，而不是 doctor：

openclaw channels capabilities --channel discord --target channel:<channel-id>
openclaw channels status --probe

定向的 Discord 能力探测会报告机器人的有效渠道权限；状态探测会审计已配置的 Discord 渠道和语音自动加入目标。

选项

• --no-workspace-suggestions：禁用工作区记忆/搜索建议
• --yes：不提示，接受默认值
• --repair：不提示，应用推荐的非服务修复；Gateway 网关服务安装和重写仍需要交互式确认或显式 Gateway 网关命令
• --fix：--repair 的别名
• --force：应用激进修复，包括在需要时覆盖自定义服务配置
• --non-interactive：不提示运行；仅执行安全迁移和非服务修复
• --generate-gateway-token：生成并配置 Gateway 网关令牌
• --deep：扫描系统服务中额外的 Gateway 网关安装，并报告最近的 Gateway supervisor 重启移交

注意事项：

• 在 Nix 模式（OPENCLAW_NIX_MODE=1）下，只读的 Doctor 检查仍可工作，但 doctor --fix、doctor --repair、doctor --yes 和 doctor --generate-gateway-token 会被禁用，因为 openclaw.json 是不可变的。请改为编辑此安装的 Nix 源；对于 nix-openclaw，请使用以智能体优先的快速开始。
• 交互式提示（如钥匙串/OAuth 修复）仅在标准输入是 TTY 且未设置 --non-interactive 时运行。无头运行（cron、Telegram、无终端）会跳过提示。
• 性能：非交互式 doctor 运行会跳过预先加载插件，因此无头健康检查保持快速。交互式会话在检查需要插件参与时仍会完整加载插件。
• --fix（--repair 的别名）会将备份写入 ~/.openclaw/openclaw.json.bak，并删除未知配置键，同时列出每项移除。
• doctor --fix --non-interactive 会报告缺失或过期的 Gateway 网关服务定义，但在更新修复模式之外不会安装或重写它们。对于缺失的服务，运行 openclaw gateway install；当你有意替换启动器时，运行 openclaw gateway install --force。
• 状态完整性检查现在会检测会话目录中的孤立转录文件。将它们归档为 .deleted.<timestamp> 需要交互式确认；--fix、--yes 和无头运行会将它们保留在原处。
• Doctor 还会扫描 ~/.openclaw/cron/jobs.json（或 cron.store）中的旧版 cron 任务形态，并可在调度器必须在运行时自动规范化它们之前就地重写。
• 在 Linux 上，如果用户的 crontab 仍运行旧版 ~/.openclaw/bin/ensure-whatsapp.sh，Doctor 会发出警告；该脚本已不再维护，并且当 cron 缺少 systemd 用户总线环境时，可能记录错误的 WhatsApp Gateway 网关故障。
• 启用 WhatsApp 时，Doctor 会检查是否存在退化的 Gateway 网关事件循环且本地 openclaw-tui 客户端仍在运行。doctor --fix 只会停止已验证的本地 TUI 客户端，因此 WhatsApp 回复不会排在过期的 TUI 刷新循环之后。
• Doctor 会在主模型、回退模型、heartbeat/subagent/compaction 覆盖项、钩子、渠道模型覆盖项和过期会话路由固定项中，将旧版 openai-codex/* 模型引用重写为规范的 openai/* 引用。--fix 会将 Codex 意图移到按提供商/模型作用域配置的 agentRuntime.id: "codex" 条目上，保留会话 auth-profile 固定项（如 openai-codex:...），移除过期的整智能体/会话运行时固定项，并让已修复的 OpenAI 智能体引用继续使用 Codex 凭证路由，而不是直接使用 OpenAI API-key 凭证。
• Doctor 会清理旧版 OpenClaw 创建的旧版插件依赖暂存状态，并为声明 openclaw 为 peer dependency 的托管 npm 插件重新链接主机 openclaw 包。它还会修复配置中引用的缺失可下载插件，例如 plugins.entries、已配置渠道、已配置提供商/搜索设置或已配置 Agent Runtimes。在包更新期间，Doctor 会跳过 package-manager 插件修复，直到包替换完成；如果已配置插件仍需恢复，请随后重新运行 openclaw doctor --fix。如果下载失败，Doctor 会报告安装错误，并保留已配置插件条目以供下一次修复尝试。
• 当插件发现正常时，Doctor 会通过从 plugins.allow/plugins.deny/plugins.entries 中移除缺失的插件 id，并移除匹配的悬空渠道配置、Heartbeat 目标和渠道模型覆盖项，来修复过期插件配置。
• Doctor 会隔离无效插件配置，方法是禁用受影响的 plugins.entries.<id> 条目并移除其无效的 config 载荷。Gateway 网关启动已只会跳过该问题插件，因此其他插件和渠道可以继续运行。
• 当另一个 supervisor 拥有 Gateway 网关生命周期时，请设置 OPENCLAW_SERVICE_REPAIR_POLICY=external。Doctor 仍会报告 Gateway 网关/服务健康状况并应用非服务修复，但会跳过服务安装/启动/重启/bootstrap 和旧版服务清理。
• 在 Linux 上，Doctor 会忽略非活动的额外类似 Gateway 网关的 systemd 单元，并且在修复期间不会重写正在运行的 systemd Gateway 网关服务的命令/入口点元数据。当你有意替换活动启动器时，请先停止服务，或使用 openclaw gateway install --force。
• Doctor 会将旧版扁平 Talk 配置（talk.voiceId、talk.modelId 及类似项）自动迁移到 talk.provider + talk.providers.<provider>。
• 当唯一差异是对象键顺序时，重复运行 doctor --fix 不再报告/应用 Talk 规范化。
• Doctor 包含记忆搜索就绪性检查，并可在缺少嵌入凭证时推荐 openclaw configure --section model。
• 当没有配置命令所有者时，Doctor 会发出警告。命令所有者是允许运行仅所有者命令并批准危险操作的人类操作员账户。私信配对只允许某人与机器人对话；如果你在首次所有者 bootstrap 存在之前批准了发送者，请显式设置 commands.ownerAllowFrom。
• 当配置了 Codex 模式智能体且操作员的 Codex 主目录中存在个人 Codex CLI 资产时，Doctor 会发出警告。本地 Codex app-server 启动使用隔离的按智能体主目录，因此请使用 openclaw migrate codex --dry-run 清点应有意提升的资产。
• Doctor 会移除已退役的 plugins.entries.codex.config.codexDynamicToolsProfile；Codex app-server 始终保持 Codex 原生工作区工具为原生。
• 当默认智能体允许的技能因缺少二进制、环境变量、配置或操作系统要求而在当前运行时环境不可用时，Doctor 会发出警告。doctor --fix 可以通过 skills.entries.<skill>.enabled=false 禁用这些不可用技能；当你希望保持该技能活跃时，请改为安装/配置缺失要求。
• 如果已启用沙箱模式但 Docker 不可用，Doctor 会报告高信号警告并附带修复建议（install Docker 或 openclaw config set agents.defaults.sandbox.mode off）。
• 如果存在旧版沙箱注册表文件（~/.openclaw/sandbox/containers.json 或 ~/.openclaw/sandbox/browsers.json），Doctor 会报告它们；openclaw doctor --fix 会将有效条目迁移到分片注册表目录，并隔离无效的旧版文件。
• 如果 gateway.auth.token/gateway.auth.password 由 SecretRef 管理且在当前命令路径中不可用，Doctor 会报告只读警告，并且不会写入明文回退凭证。
• 如果渠道 SecretRef 检查在修复路径中失败，Doctor 会继续并报告警告，而不是提前退出。
• 状态目录迁移后，当已启用的默认 Telegram 或 Discord 账户依赖环境回退且 TELEGRAM_BOT_TOKEN 或 DISCORD_BOT_TOKEN 对 Doctor 进程不可用时，Doctor 会发出警告。
• Telegram allowFrom 用户名自动解析（doctor --fix）要求当前命令路径中有可解析的 Telegram 令牌。如果令牌检查不可用，Doctor 会报告警告，并跳过本轮自动解析。

macOS：launchctl 环境覆盖

如果你之前运行过 launchctl setenv OPENCLAW_GATEWAY_TOKEN ...（或 ...PASSWORD），该值会覆盖你的配置文件，并可能导致持续的“未授权”错误。

launchctl getenv OPENCLAW_GATEWAY_TOKEN
launchctl getenv OPENCLAW_GATEWAY_PASSWORD

launchctl unsetenv OPENCLAW_GATEWAY_TOKEN
launchctl unsetenv OPENCLAW_GATEWAY_PASSWORD

相关

• CLI 参考
• Gateway 网关 Doctor

📄 Gateway 网关

原文：https://docs.openclaw.ai/zh-CN/cli/gateway

Gateway 网关是 OpenClaw 的 WebSocket 服务器（渠道、节点、会话、钩子）。本页中的子命令位于 openclaw gateway … 之下。

本地 mDNS + 广域 DNS-SD 设置。

OpenClaw 如何广播和发现 Gateway 网关。

顶层 Gateway 网关配置键名。

运行 Gateway 网关

运行本地 Gateway 网关进程：

openclaw gateway

前台别名：

openclaw gateway run

- 默认情况下，除非在 ~/.openclaw/openclaw.json 中设置了 gateway.mode=local，否则 Gateway 网关会拒绝启动。对临时/开发运行使用 --allow-unconfigured。
- openclaw onboard --mode local 和 openclaw setup 应写入 gateway.mode=local。如果文件存在但缺少 gateway.mode，应将其视为损坏或被覆盖的配置并修复，而不是隐式假定为本地模式。
- 如果文件存在且缺少 gateway.mode，Gateway 网关会将其视为可疑的配置损坏，并拒绝为你“猜测本地模式”。
- 未经身份验证绑定到 loopback 之外会被阻止（安全防护栏）。
- SIGUSR1 会在已授权时触发进程内重启（默认启用 commands.restart；设置 commands.restart: false 可阻止手动重启，同时仍允许 Gateway 网关工具/配置应用/更新）。
- SIGINT/SIGTERM 处理程序会停止 Gateway 网关进程，但不会恢复任何自定义终端状态。如果你用 TUI 或 raw-mode 输入包装 CLI，请在退出前恢复终端。

选项

<ParamField path="--port \" type="number">
WebSocket 端口（默认值来自配置/环境；通常为 18789）。

<ParamField path="--bind \" type="string">
监听器绑定模式。

<ParamField path="--auth \" type="string">
身份验证模式覆盖。

<ParamField path="--token \" type="string">
Token 覆盖（也会为该进程设置 OPENCLAW_GATEWAY_TOKEN）。

<ParamField path="--password \" type="string">
密码覆盖。

<ParamField path="--password-file \" type="string">
从文件读取 Gateway 网关密码。

<ParamField path="--tailscale \" type="string">
通过 Tailscale 暴露 Gateway 网关。

关闭时重置 Tailscale serve/funnel 配置。

允许在配置中没有 gateway.mode=local 的情况下启动 Gateway 网关。仅为临时/开发 bootstrap 绕过启动防护；不会写入或修复配置文件。

如果缺失，则创建开发配置 + 工作区（跳过 BOOTSTRAP.md）。

重置开发配置 + 凭据 + 会话 + 工作区（需要 --dev）。

启动前杀掉所选端口上的任何现有监听器。

详细日志。

仅在控制台显示 CLI 后端日志（并启用 stdout/stderr）。

<ParamField path="--ws-log \" type="string" default="auto">
Websocket 日志样式。

--ws-log compact 的别名。

将原始模型流事件记录到 jsonl。

<ParamField path="--raw-stream-path \" type="string">
原始流 jsonl 路径。

重启 Gateway 网关

openclaw gateway restart
openclaw gateway restart --safe
openclaw gateway restart --safe --skip-deferral
openclaw gateway restart --force

openclaw gateway restart --safe 会要求正在运行的 Gateway 网关在重启前预检活跃的 OpenClaw 工作。如果队列操作、回复投递、嵌入式运行或任务运行处于活跃状态，Gateway 网关会报告阻塞项、合并重复的安全重启请求，并在活跃工作排空后重启。普通 restart 会保留现有服务管理器行为以保持兼容性。仅当你明确需要立即覆盖路径时才使用 --force。

openclaw gateway restart --safe --skip-deferral 会运行与 --safe 相同的 OpenClaw 感知协调重启，但会绕过活跃工作延迟门控，因此即使报告了阻塞项，Gateway 网关也会立即发出重启。当延迟被卡住的任务运行固定住，而单独使用 --safe 会无限期等待时，可将其作为操作员逃生口。--skip-deferral 需要 --safe。

内联 --password 可能会暴露在本地进程列表中。优先使用 --password-file、环境变量，或由 SecretRef 支持的 gateway.auth.password。

启动性能分析

• 设置 OPENCLAW_GATEWAY_STARTUP_TRACE=1 以记录 Gateway 网关启动期间的阶段耗时，包括每个阶段的 eventLoopMax 延迟，以及 installed-index、清单注册表、启动规划和 owner-map 工作的插件查找表耗时。
• 设置 OPENCLAW_DIAGNOSTICS=timeline 并配合 OPENCLAW_DIAGNOSTICS_TIMELINE_PATH=<path>，为外部 QA harness 写入尽力而为的 JSONL 启动诊断时间线。你也可以在配置中通过 diagnostics.flags: ["timeline"] 启用该标志；路径仍由环境提供。添加 OPENCLAW_DIAGNOSTICS_EVENT_LOOP=1 可包含事件循环采样。
• 运行 pnpm test:startup:gateway -- --runs 5 --warmup 1 来基准测试 Gateway 网关启动。该基准会记录首次进程输出、/healthz、/readyz、启动跟踪耗时、事件循环延迟，以及插件查找表耗时详情。

查询正在运行的 Gateway 网关

所有查询命令都使用 WebSocket RPC。

- 默认：人类可读（TTY 中带颜色）。
- --json：机器可读 JSON（无样式/加载动画）。
- --no-color（或 NO_COLOR=1）：在保留人类布局的同时禁用 ANSI。

- --url <url>：Gateway 网关 WebSocket URL。
- --token <token>：Gateway 网关 token。
- --password <password>：Gateway 网关密码。
- --timeout <ms>：超时/预算（因命令而异）。
- --expect-final：等待“final”响应（智能体调用）。

设置 --url 时，CLI 不会回退到配置或环境凭据。请显式传入 --token 或 --password。缺少显式凭据会报错。

gateway health

openclaw gateway health --url ws://127.0.0.1:18789

HTTP /healthz 端点是存活探针：服务器能够响应 HTTP 后即返回。HTTP /readyz 端点更严格，在启动插件 sidecar、渠道或已配置钩子仍在稳定期间会保持红色。本地或已认证的详细就绪响应会包含一个 eventLoop 诊断块，其中有事件循环延迟、事件循环利用率、CPU 核心比率和 degraded 标志。

gateway usage-cost

从会话日志获取 usage-cost 摘要。

openclaw gateway usage-cost
openclaw gateway usage-cost --days 7
openclaw gateway usage-cost --json

<ParamField path="--days \" type="number" default="30">
要包含的天数。

gateway stability

从正在运行的 Gateway 网关获取最近的诊断稳定性记录器。

openclaw gateway stability
openclaw gateway stability --type payload.large
openclaw gateway stability --bundle latest
openclaw gateway stability --bundle latest --export
openclaw gateway stability --json

<ParamField path="--limit \" type="number" default="25">
要包含的最近事件最大数量（最大 1000）。

<ParamField path="--type \" type="string">
按诊断事件类型过滤，例如 payload.large 或 diagnostic.memory.pressure。

<ParamField path="--since-seq \" type="number">
仅包含某个诊断序列号之后的事件。

读取已持久化的稳定性包，而不是调用正在运行的 Gateway 网关。使用 --bundle latest（或仅 --bundle）读取状态目录下的最新包，或直接传入包 JSON 路径。

写入可共享的支持诊断 zip，而不是打印稳定性详情。

<ParamField path="--output \" type="string">
--export 的输出路径。

- 记录会保留运行元数据：事件名称、计数、字节大小、内存读数、队列/会话状态、渠道/插件名称，以及已脱敏的会话摘要。它们不会保留聊天文本、webhook 正文、工具输出、原始请求或响应正文、token、cookie、密钥值、主机名或原始会话 ID。设置 diagnostics.enabled: false 可完全禁用记录器。
- 在 Gateway 网关致命退出、关闭超时和重启启动失败时，如果记录器有事件，OpenClaw 会将同一诊断快照写入 ~/.openclaw/logs/stability/openclaw-stability-*.json。使用 openclaw gateway stability --bundle latest 检查最新包；--limit、--type 和 --since-seq 也适用于包输出。

gateway diagnostics export

写入本地诊断 zip，设计用于附加到错误报告。有关隐私模型和包内容，请参阅 诊断导出。

openclaw gateway diagnostics export
openclaw gateway diagnostics export --output openclaw-diagnostics.zip
openclaw gateway diagnostics export --json

<ParamField path="--output \" type="string">
输出 zip 路径。默认写入状态目录下的支持导出。

<ParamField path="--log-lines \" type="number" default="5000">
要包含的已清理日志行最大数量。

<ParamField path="--log-bytes \" type="number" default="1000000">
要检查的最大日志字节数。

<ParamField path="--url \" type="string">
用于健康快照的 Gateway 网关 WebSocket URL。

<ParamField path="--token \" type="string">
用于健康快照的 Gateway 网关 token。

<ParamField path="--password \" type="string">
用于健康快照的 Gateway 网关密码。

<ParamField path="--timeout \" type="number" default="3000">
Status/健康快照超时。

跳过已持久化稳定性包查找。

将写入路径、大小和清单打印为 JSON。

导出内容包含清单、Markdown 摘要、配置形状、已清理的配置详情、已清理的日志摘要、已清理的 Gateway 网关 Status/健康快照，以及存在时的最新稳定性包。

它用于共享。它会保留有助于调试的运行细节，例如安全的 OpenClaw 日志字段、子系统名称、状态码、时长、已配置模式、端口、插件 ID、提供商 ID、非密钥功能设置，以及已脱敏的运行日志消息。它会省略或脱敏聊天文本、webhook 正文、工具输出、凭据、cookie、账号/消息标识符、提示/指令文本、主机名和密钥值。当 LogTape 风格的消息看起来像用户/聊天/工具载荷文本时，导出只保留一条消息被省略及其字节数。

gateway status

gateway status 会显示 Gateway 网关服务（launchd/systemd/schtasks），以及一个可选的连通性/身份验证能力探针。

openclaw gateway status
openclaw gateway status --json
openclaw gateway status --require-rpc

<ParamField path="--url \" type="string">
添加显式探测目标。已配置的远程目标 + localhost 仍会被探测。

<ParamField path="--token \" type="string">
探测使用的令牌认证。

<ParamField path="--password \" type="string">
探测使用的密码认证。

<ParamField path="--timeout \" type="number" default="10000">
探测超时时间。

跳过连通性探测（仅服务视图）。

同时扫描系统级服务。

将默认连通性探测升级为读取探测，并在该读取探测失败时以非零状态退出。不能与 --no-probe 组合使用。

- 即使本地 CLI 配置缺失或无效，gateway status 仍可用于诊断。
- 默认的 gateway status 会证明服务状态、WebSocket 连接，以及握手时可见的认证能力。它不会证明读/写/管理操作。
- 对首次设备认证，诊断探测不会产生变更：当已有缓存设备令牌时会复用它们，但不会仅为检查状态而创建新的 CLI 设备身份或只读设备配对记录。
- 可行时，gateway status 会解析已配置的认证 SecretRefs 用于探测认证。
- 如果此命令路径中所需的认证 SecretRef 未解析，gateway status --json 会在探测连通性/认证失败时报告 rpc.authWarning；请显式传入 --token/--password，或先解析密钥来源。
- 如果探测成功，未解析的认证引用警告会被抑制，以避免误报。
- 当监听服务本身还不够，而你还需要读取范围的 RPC 调用也健康时，请在脚本和自动化中使用 --require-rpc。
- --deep 会添加对额外 launchd/systemd/schtasks 安装的尽力扫描。当检测到多个类似 Gateway 网关的服务时，人类可读输出会打印清理提示，并警告大多数设置应在每台机器上运行一个 Gateway 网关。
- 当服务进程为外部监督器重启而干净退出时，--deep 也会报告最近一次 Gateway 网关监督器重启交接。
- --deep 会以插件感知模式（pluginValidation: "full"）运行配置验证，并显示已配置插件清单警告（例如缺少渠道配置元数据），以便安装和更新冒烟检查能捕获它们。默认的 gateway status 保持快速只读路径，跳过插件验证。
- 人类可读输出包含解析后的文件日志路径，以及 CLI 与服务配置路径/有效性快照，用于帮助诊断配置文件或状态目录漂移。

- 在 Linux systemd 安装上，服务认证漂移检查会从单元中读取 Environment= 和 EnvironmentFile= 值（包括 %h、带引号的路径、多个文件以及可选的 - 文件）。
- 漂移检查会使用合并后的运行时环境解析 gateway.auth.token SecretRefs（先使用服务命令环境，再回退到进程环境）。
- 如果令牌认证实际上未启用（显式 gateway.auth.mode 为 password/none/trusted-proxy，或模式未设置且密码可能优先、没有令牌候选可能优先），令牌漂移检查会跳过配置令牌解析。

gateway probe

gateway probe 是“调试所有内容”的命令。它始终会探测：

• 你已配置的远程 Gateway 网关（如果已设置），以及
• localhost（loopback），即使已配置远程目标。

如果你传入 --url，该显式目标会被添加到两者之前。人类可读输出会将目标标记为：

• URL (explicit)
• Remote (configured) 或 Remote (configured, inactive)
• Local loopback

如果多个 Gateway 网关可达，它会全部打印出来。当你使用隔离的配置文件/端口（例如救援 bot）时，支持多个 Gateway 网关，但大多数安装仍只运行单个 Gateway 网关。

openclaw gateway probe
openclaw gateway probe --json

- Reachable: yes 表示至少一个目标接受了 WebSocket 连接。
- Capability: read-only|write-capable|admin-capable|pairing-pending|connect-only 报告探测能证明的认证情况。它与可达性是分开的。
- Read probe: ok 表示读取范围的详细 RPC 调用（health/status/system-presence/config.get）也成功了。
- Read probe: limited - missing scope: operator.read 表示连接成功，但读取范围的 RPC 受限。这会被报告为降级可达性，而不是完全失败。
- Connect: ok 之后的 Read probe: failed 表示 Gateway 网关接受了 WebSocket 连接，但后续读取诊断超时或失败。这同样是降级可达性，而不是 Gateway 网关不可达。
- 与 gateway status 一样，probe 会复用现有缓存设备认证，但不会创建首次设备身份或配对状态。
- 只有在没有任何被探测目标可达时，退出码才为非零。

顶层：

- `ok`：至少一个目标可达。
- `degraded`：至少一个目标接受了连接，但未完成完整的详细 RPC 诊断。
- `capability`：在可达目标中看到的最佳能力（`read_only`、`write_capable`、`admin_capable`、`pairing_pending`、`connected_no_operator_scope` 或 `unknown`）。
- `primaryTargetId`：按以下顺序视为当前活跃胜出者的最佳目标：显式 URL、SSH 隧道、已配置远程目标，然后是 local loopback。
- `warnings[]`：尽力而为的警告记录，包含 `code`、`message` 和可选的 `targetIds`。
- `network`：从当前配置和主机网络派生的 local loopback/tailnet URL 提示。
- `discovery.timeoutMs` 和 `discovery.count`：此探测轮次使用的实际设备发现预算/结果数量。

每个目标（`targets[].connect`）：

- `ok`：连接后的可达性 + 降级分类。
- `rpcOk`：完整详细 RPC 成功。
- `scopeLimited`：详细 RPC 因缺少 operator scope 而失败。

每个目标（`targets[].auth`）：

- `role`：可用时，`hello-ok` 中报告的认证角色。
- `scopes`：可用时，`hello-ok` 中报告的已授予 scope。
- `capability`：该目标显示的认证能力分类。

- ssh_tunnel_failed：SSH 隧道设置失败；命令回退到直接探测。
- multiple_gateways：多个目标可达；除非你有意运行隔离的配置文件（例如救援 bot），否则这并不常见。
- auth_secretref_unresolved：无法为失败目标解析已配置的认证 SecretRef。
- probe_scope_limited：WebSocket 连接成功，但读取探测因缺少 operator.read 而受限。

通过 SSH 访问远程目标（与 Mac 应用一致）

macOS 应用的“通过 SSH 访问远程目标”模式使用本地端口转发，因此远程 Gateway 网关（它可能只绑定到 loopback）会在 ws://127.0.0.1:<port> 可达。

CLI 等效命令：

openclaw gateway probe --ssh user@gateway-host

<ParamField path="--ssh \" type="string">
user@host 或 user@host:port（端口默认为 22）。

<ParamField path="--ssh-identity \" type="string">
身份文件。

从解析后的设备发现端点（local. 加上已配置的广域域名，如果有）中选择第一个发现的 Gateway 网关主机作为 SSH 目标。仅 TXT 的提示会被忽略。

配置（可选，用作默认值）：

• gateway.remote.sshTarget
• gateway.remote.sshIdentity

gateway call <method>

低层 RPC 辅助命令。

openclaw gateway call status
openclaw gateway call logs.tail --params '{"sinceMs": 60000}'

<ParamField path="--params \" type="string" default="{}">
params 的 JSON 对象字符串。

<ParamField path="--url \" type="string">
Gateway 网关 WebSocket URL。

<ParamField path="--token \" type="string">
Gateway 网关令牌。

<ParamField path="--password \" type="string">
Gateway 网关密码。

<ParamField path="--timeout \" type="number">
超时预算。

主要用于 agent 风格的 RPC，这类 RPC 会在最终载荷之前流式传输中间事件。

机器可读的 JSON 输出。

--params 必须是有效的 JSON。

管理 Gateway 网关服务

openclaw gateway install
openclaw gateway start
openclaw gateway stop
openclaw gateway restart
openclaw gateway uninstall

使用包装器安装

当托管服务必须通过另一个可执行文件启动时，请使用 --wrapper，例如密钥管理器 shim 或 run-as 辅助程序。包装器会接收普通 Gateway 网关参数，并负责最终用这些参数 exec openclaw 或 Node。

cat > ~/.local/bin/openclaw-doppler <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
exec doppler run --project my-project --config production -- openclaw "$@"
EOF
chmod +x ~/.local/bin/openclaw-doppler

openclaw gateway install --wrapper ~/.local/bin/openclaw-doppler --force
openclaw gateway restart

你也可以通过环境设置包装器。gateway install 会验证路径是可执行文件，将包装器写入服务 ProgramArguments，并在服务环境中持久化 OPENCLAW_WRAPPER，供后续强制重新安装、更新和 Doctor 修复使用。

OPENCLAW_WRAPPER="$HOME/.local/bin/openclaw-doppler" openclaw gateway install --force
openclaw doctor

要移除已持久化的包装器，请在重新安装时清空 OPENCLAW_WRAPPER：

OPENCLAW_WRAPPER= openclaw gateway install --force
openclaw gateway restart

- gateway status：--url、--token、--password、--timeout、--no-probe、--require-rpc、--deep、--json
- gateway install：--port、--runtime <node|bun>、--token、--wrapper <path>、--force、--json
- gateway restart：--safe、--skip-deferral、--force、--wait <duration>、--json
- gateway uninstall|start：--json
- gateway stop：--disable、--json

- 使用 gateway restart 重启托管服务。不要把 gateway stop 和 gateway start 串联起来作为重启替代方式。
- 在 macOS 上，gateway stop 默认使用 launchctl bootout，这会从当前启动会话中移除 LaunchAgent，但不会持久化禁用设置 —— KeepAlive 自动恢复会在后续崩溃时继续生效，并且 gateway start 可以干净地重新启用，无需手动执行 launchctl enable。传入 --disable 可持久化抑制 KeepAlive 和 RunAtLoad，使 Gateway 网关在下一次显式执行 gateway start 之前不会重新生成；当手动停止需要在重启或系统重启后仍然保持时，请使用此选项。
- gateway restart --safe 会要求正在运行的 Gateway 网关预检活跃的 OpenClaw 工作，并将重启推迟到回复交付、嵌入式运行和任务运行全部排空之后。--safe 不能与 --force 或 --wait 组合使用。
- gateway restart --wait 30s 会覆盖该次重启配置的重启排空预算。裸数字表示毫秒；也接受 s、m 和 h 等单位。--wait 0 会无限期等待。
- gateway restart --safe --skip-deferral 会运行感知 OpenClaw 的安全重启，但绕过延迟门控，因此即使报告了阻塞项，Gateway 网关也会立即发出重启。用于任务运行延迟卡住时的操作员逃生口；需要 --safe。
- gateway restart --force 会跳过活跃工作排空并立即重启。当操作员已经检查过列出的任务阻塞项，并希望 Gateway 网关立即恢复时使用。
- 生命周期命令接受 --json，用于脚本编写。

- 当令牌认证需要令牌且 gateway.auth.token 由 SecretRef 管理时，gateway install 会验证 SecretRef 可解析，但不会将解析后的令牌持久化到服务环境元数据中。
- 如果令牌认证需要令牌，而配置的令牌 SecretRef 未解析，安装会关闭失败，而不是持久化回退明文。
- 对于 gateway run 上的密码认证，优先使用 OPENCLAW_GATEWAY_PASSWORD、--password-file，或由 SecretRef 支持的 gateway.auth.password，而不是内联 --password。
- 在推断认证模式下，仅存在于 shell 中的 OPENCLAW_GATEWAY_PASSWORD 不会放宽安装令牌要求；安装托管服务时，请使用持久化配置（gateway.auth.password 或配置 env）。
- 如果同时配置了 gateway.auth.token 和 gateway.auth.password，并且 gateway.auth.mode 未设置，安装会被阻止，直到显式设置模式。

发现 Gateway 网关（Bonjour）

gateway discover 会扫描 Gateway 网关信标（_openclaw-gw._tcp）。

• 组播 DNS-SD：local.
• 单播 DNS-SD（广域 Bonjour）：选择一个域（示例：openclaw.internal.）并设置拆分 DNS + DNS 服务器；请参阅 Bonjour。

只有启用了 Bonjour 发现（默认）的 Gateway 网关才会广播该信标。

广域发现记录可以包含这些 TXT 提示：

• role（Gateway 网关角色提示）
• transport（传输提示，例如 gateway）
• gatewayPort（WebSocket 端口，通常为 18789）
• sshPort（仅完整发现模式；缺失时，客户端默认 SSH 目标为 22）
• tailnetDns（MagicDNS 主机名，可用时）
• gatewayTls / gatewayTlsSha256（已启用 TLS + 证书指纹）
• cliPath（仅完整发现模式）

gateway discover

openclaw gateway discover

<ParamField path="--timeout \" type="number" default="2000">
每条命令的超时（浏览/解析）。

机器可读输出（也会禁用样式和 spinner）。

示例：

openclaw gateway discover --timeout 4000
openclaw gateway discover --json | jq '.beacons[].wsUrl'

- CLI 会扫描 local.，以及启用后配置的广域域。
- JSON 输出中的 wsUrl 派生自已解析的服务端点，而不是仅来自 TXT 的提示，例如 lanHost 或 tailnetDns。
- 在 local. mDNS 和广域 DNS-SD 上，只有当 discovery.mdns.mode 为 full 时，才会发布 sshPort 和 cliPath。

相关

• CLI 参考
• Gateway 网关运行手册

📄 健康状态

原文：https://docs.openclaw.ai/zh-CN/cli/health

openclaw health

从正在运行的 Gateway 网关获取健康状态。

选项

示例：

openclaw health
openclaw health --json
openclaw health --timeout 2500
openclaw health --verbose
openclaw health --debug

备注：

• 默认的 openclaw health 会向正在运行的 Gateway 网关请求其健康状态快照。当该
  Gateway 网关已有新的缓存快照时，它可以返回该缓存负载，并在后台刷新。
• --verbose 会强制执行实时探测，打印 Gateway 网关连接详情，并展开所有已配置账户和智能体的
  人类可读输出。
• 当配置了多个智能体时，输出会包含每个智能体的会话存储。

相关内容

• CLI 参考
• Gateway 网关健康状态

📄 钩子

原文：https://docs.openclaw.ai/zh-CN/cli/hooks

openclaw hooks

管理智能体钩子（用于 /new、/reset 和 Gateway 网关启动等命令的事件驱动自动化）。

不带子命令运行 openclaw hooks 等同于 openclaw hooks list。

相关内容：

• 钩子：钩子
• 插件钩子：插件钩子

列出所有钩子

openclaw hooks list

列出从工作区、托管目录、额外目录和内置目录发现的所有钩子。
Gateway 网关启动时不会加载内部钩子处理程序，除非至少配置了一个内部钩子。

选项：

• --eligible：仅显示符合条件的钩子（满足要求）
• --json：以 JSON 输出
• -v, --verbose：显示详细信息，包括缺失的要求

示例输出：

Hooks (4/4 ready)

Ready:
  🚀 boot-md ✓ - Run BOOT.md on gateway startup
  📎 bootstrap-extra-files ✓ - Inject extra workspace bootstrap files during agent bootstrap
  📝 command-logger ✓ - Log all command events to a centralized audit file
  💾 session-memory ✓ - Save session context to memory when /new or /reset command is issued

示例（详细）：

openclaw hooks list --verbose

显示不符合条件的钩子缺失的要求。

示例（JSON）：

openclaw hooks list --json

返回用于程序化使用的结构化 JSON。

获取钩子信息

openclaw hooks info <name>

显示特定钩子的详细信息。

参数：

• <name>：钩子名称或钩子键（例如 session-memory）

选项：

• --json：以 JSON 输出

示例：

openclaw hooks info session-memory

输出：

💾 session-memory ✓ Ready

Save session context to memory when /new or /reset command is issued

Details:
  Source: openclaw-bundled
  Path: /path/to/openclaw/hooks/bundled/session-memory/HOOK.md
  Handler: /path/to/openclaw/hooks/bundled/session-memory/handler.ts
  Homepage: https://docs.openclaw.ai/automation/hooks#session-memory
  Events: command:new, command:reset

Requirements:
  Config: ✓ workspace.dir

检查钩子资格

openclaw hooks check

显示钩子资格状态摘要（多少已就绪、多少未就绪）。

选项：

• --json：以 JSON 输出

示例输出：

Hooks Status

Total hooks: 4
Ready: 4
Not ready: 0

启用钩子

openclaw hooks enable <name>

通过将特定钩子添加到你的配置中来启用它（默认是 ~/.openclaw/openclaw.json）。

注意： 工作区钩子默认处于禁用状态，直到在这里或配置中启用。由插件管理的钩子会在 openclaw hooks list 中显示 plugin:<id>，不能在这里启用或禁用。请改为启用或禁用对应插件。

参数：

• <name>：钩子名称（例如 session-memory）

示例：

openclaw hooks enable session-memory

输出：

✓ Enabled hook: 💾 session-memory

它会做什么：

• 检查钩子是否存在且符合条件
• 在你的配置中更新 hooks.internal.entries.<name>.enabled = true
• 将配置保存到磁盘

如果钩子来自 <workspace>/hooks/，则必须先执行此选择启用步骤，
Gateway 网关才会加载它。

启用后：

• 重启 Gateway 网关以重新加载钩子（在 macOS 上重启菜单栏应用，或在开发环境中重启你的 Gateway 网关进程）。

禁用钩子

openclaw hooks disable <name>

通过更新你的配置来禁用特定钩子。

参数：

• <name>：钩子名称（例如 command-logger）

示例：

openclaw hooks disable command-logger

输出：

⏸ Disabled hook: 📝 command-logger

禁用后：

• 重启 Gateway 网关以重新加载钩子

备注

• openclaw hooks list --json、info --json 和 check --json 会将结构化 JSON 直接写入 stdout。
• 由插件管理的钩子不能在这里启用或禁用；请改为启用或禁用所属插件。

安装钩子包

openclaw plugins install <package>        # npm by default
openclaw plugins install npm:<package>    # npm only
openclaw plugins install <package> --pin  # pin version
openclaw plugins install <path>           # local path

通过统一的插件安装器安装钩子包。

openclaw hooks install 仍可作为兼容别名使用，但它会打印弃用警告，
并转发到 openclaw plugins install。

npm 规范仅限注册表（包名 + 可选的精确版本或
dist-tag）。Git/URL/file 规范和 semver 范围会被拒绝。为了安全，即使你的
shell 配置了全局 npm 安装设置，依赖安装也会以项目本地方式运行，并带上 --ignore-scripts。

裸规范和 @latest 会留在稳定轨道上。如果 npm 将其中任何一种解析为预发布版本，
OpenClaw 会停止并要求你使用 @beta/@rc 等预发布标签或精确预发布版本来显式选择加入。

它会做什么：

• 将钩子包复制到 ~/.openclaw/hooks/<id>
• 在 hooks.internal.entries.* 中启用已安装的钩子
• 在 hooks.internal.installs 下记录安装

选项：

• -l, --link：链接本地目录而不是复制（将其添加到 hooks.internal.load.extraDirs）
• --pin：将 npm 安装记录为 hooks.internal.installs 中解析后的精确 name@version

支持的归档格式： .zip、.tgz、.tar.gz、.tar

示例：

# Local directory
openclaw plugins install ./my-hook-pack

# Local archive
openclaw plugins install ./my-hook-pack.zip

# NPM package
openclaw plugins install @openclaw/my-hook-pack

# Link a local directory without copying
openclaw plugins install -l ./my-hook-pack

已链接的钩子包会被视为来自操作员配置目录的托管钩子，
而不是工作区钩子。

更新钩子包

openclaw plugins update <id>
openclaw plugins update --all

通过统一的插件更新器更新已跟踪的基于 npm 的钩子包。

openclaw hooks update 仍可作为兼容别名使用，但它会打印弃用警告，
并转发到 openclaw plugins update。

选项：

• --all：更新所有已跟踪的钩子包
• --dry-run：显示会发生什么变化但不写入

当已存储完整性哈希且获取到的制品哈希发生变化时，
OpenClaw 会打印警告并在继续之前请求确认。在 CI/非交互式运行中使用
全局 --yes 可绕过提示。

内置钩子

session-memory

当你发出 /new 或 /reset 时，将会话上下文保存到记忆中。

启用：

openclaw hooks enable session-memory

输出： 默认写入 ~/.openclaw/workspace/memory/YYYY-MM-DD-HHMM.md。设置 hooks.internal.entries.session-memory.llmSlug: true 可使用模型生成的文件名 slug。

参见： session-memory 文档

bootstrap-extra-files

在 agent:bootstrap 期间注入额外的启动文件（例如 monorepo 本地的 AGENTS.md / TOOLS.md）。

启用：

openclaw hooks enable bootstrap-extra-files

参见： bootstrap-extra-files 文档

command-logger

将所有命令事件记录到集中式审计文件。

启用：

openclaw hooks enable command-logger

输出： ~/.openclaw/logs/commands.log

查看日志：

# Recent commands
tail -n 20 ~/.openclaw/logs/commands.log

# Pretty-print
cat ~/.openclaw/logs/commands.log | jq .

# Filter by action
grep '"action":"new"' ~/.openclaw/logs/commands.log | jq .

参见： command-logger 文档

boot-md

Gateway 网关启动时（在渠道启动后）运行 BOOT.md。

事件：gateway:startup

启用：

openclaw hooks enable boot-md

参见： boot-md 文档

相关内容

• CLI 参考
• 自动化钩子

📄 日志

原文：https://docs.openclaw.ai/zh-CN/cli/logs

openclaw logs

通过 RPC 追踪 Gateway 网关文件日志（适用于远程模式）。

相关：

• 日志概览：日志
• Gateway 网关 CLI：Gateway 网关

选项

• --limit <n>：要返回的最大日志行数（默认 200）
• --max-bytes <n>：从日志文件读取的最大字节数（默认 250000）
• --follow：跟随日志流
• --interval <ms>：跟随时的轮询间隔（默认 1000）
• --json：输出按行分隔的 JSON 事件
• --plain：不带样式格式的纯文本输出
• --no-color：禁用 ANSI 颜色
• --local-time：按你的本地时区渲染时间戳

共享 Gateway 网关 RPC 选项

openclaw logs 也接受标准 Gateway 网关客户端标志：

• --url <url>：Gateway 网关 WebSocket URL
• --token <token>：Gateway 网关令牌
• --timeout <ms>：超时时间，单位为 ms（默认 30000）
• --expect-final：当 Gateway 网关调用由智能体支持时，等待最终响应

传入 --url 时，CLI 不会自动应用配置或环境凭证。如果目标 Gateway 网关需要认证，请显式包含 --token。

示例

openclaw logs
openclaw logs --follow
openclaw logs --follow --interval 2000
openclaw logs --limit 500 --max-bytes 500000
openclaw logs --json
openclaw logs --plain
openclaw logs --no-color
openclaw logs --limit 500
openclaw logs --local-time
openclaw logs --follow --local-time
openclaw logs --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

备注

• 使用 --local-time 按你的本地时区渲染时间戳。
• 如果隐式 local loopback Gateway 网关要求配对、在连接期间关闭，或在 logs.tail 应答之前超时，openclaw logs 会自动回退到已配置的 Gateway 网关文件日志。显式 --url 目标不会使用此回退。
• 使用 --follow 时，临时性 gateway 断开（WebSocket 关闭、超时、连接中断）会触发带指数退避的自动重连（最多 8 次重试，尝试间隔上限为 30 s）。每次重试都会向 stderr 打印警告，轮询成功后会打印一次 [logs] gateway reconnected 通知。在 --json 模式下，重试警告和重连转换都会作为 {"type":"notice"} 记录输出到 stderr。不可恢复的错误（认证失败、配置错误）仍会立即退出。

相关

• CLI 参考
• Gateway 网关日志

📄 记忆

原文：https://docs.openclaw.ai/zh-CN/cli/memory

openclaw memory

管理语义记忆索引和搜索。
由主动记忆插件提供（默认：memory-core；设置 plugins.slots.memory = "none" 可禁用）。

相关内容：

• 记忆概念：记忆
• Memory Wiki：Memory Wiki
• Wiki CLI：wiki
• 插件：插件

示例

openclaw memory status
openclaw memory status --deep
openclaw memory status --fix
openclaw memory index --force
openclaw memory search "meeting notes"
openclaw memory search --query "deployment" --max-results 20
openclaw memory promote --limit 10 --min-score 0.75
openclaw memory promote --apply
openclaw memory promote --json --min-recall-count 0 --min-unique-queries 0
openclaw memory promote-explain "router vlan"
openclaw memory promote-explain "router vlan" --json
openclaw memory rem-harness
openclaw memory rem-harness --json
openclaw memory status --json
openclaw memory status --deep --index
openclaw memory status --deep --index --verbose
openclaw memory status --agent main
openclaw memory index --agent main --verbose

选项

memory status 和 memory index：

• --agent <id>：限定到单个智能体。如果未提供，这些命令会为每个已配置的智能体运行；如果未配置智能体列表，则回退到默认智能体。
• --verbose：在探测和索引期间输出详细日志。

memory status：

• --deep：探测本地向量存储就绪状态、嵌入提供商就绪状态，以及语义向量搜索就绪状态。普通 memory status 保持快速，不会运行实时嵌入或提供商发现工作；未知的向量存储或语义向量状态表示该命令中未探测它。QMD 词法 searchMode: "search" 即使带有 --deep，也会跳过语义向量探测和嵌入维护。
• --index：如果存储为脏状态，则运行重新索引（隐含 --deep）。
• --fix：修复过期的召回锁并规范化提升元数据。
• --json：打印 JSON 输出。

如果 memory status 显示 Dreaming status: blocked，则表示托管的 Dreaming cron 已启用，但驱动它的 Heartbeat 未针对默认智能体触发。请参阅 Dreaming 从不运行，了解两个常见原因。

memory index：

• --force：强制完整重新索引。

memory search：

• 查询输入：传入位置参数 [query] 或 --query <text>。
• 如果两者都提供，--query 优先。
• 如果两者都未提供，命令会以错误退出。
• --agent <id>：限定到单个智能体（默认：默认智能体）。
• --max-results <n>：限制返回的结果数量。
• --min-score <n>：过滤掉低分匹配项。
• --json：打印 JSON 结果。

memory promote：

预览并应用短期记忆提升。

openclaw memory promote [--apply] [--limit <n>] [--include-promoted]

• --apply -- 将提升写入 MEMORY.md（默认：仅预览）。
• --limit <n> -- 限制显示的候选项数量。
• --include-promoted -- 包含在先前周期中已提升的条目。

完整选项：

• 使用加权提升信号（frequency、relevance、query diversity、recency、consolidation、conceptual richness）对来自 memory/YYYY-MM-DD.md 的短期候选项排序。
• 使用来自记忆召回和每日摄取流程的短期信号，以及 light/REM 阶段强化信号。
• 启用 Dreaming 后，memory-core 会自动管理一个在后台运行完整扫描（light -> REM -> deep）的 cron 作业（无需手动 openclaw cron add）。
• --agent <id>：限定到单个智能体（默认：默认智能体）。
• --limit <n>：返回/应用的最大候选项数量。
• --min-score <n>：最低加权提升分数。
• --min-recall-count <n>：候选项所需的最低召回次数。
• --min-unique-queries <n>：候选项所需的最低不同查询数。
• --apply：将选中的候选项追加到 MEMORY.md 并将其标记为已提升。
• --include-promoted：在输出中包含已提升的候选项。
• --json：打印 JSON 输出。

memory promote-explain：

解释特定提升候选项及其分数细分。

openclaw memory promote-explain <selector> [--agent <id>] [--include-promoted] [--json]

• <selector>：要查找的候选项键、路径片段或片段内容。
• --agent <id>：限定到单个智能体（默认：默认智能体）。
• --include-promoted：包含已提升的候选项。
• --json：打印 JSON 输出。

memory rem-harness：

预览 REM 反思、候选真相和深度提升输出，而不写入任何内容。

openclaw memory rem-harness [--agent <id>] [--include-promoted] [--json]

• --agent <id>：限定到单个智能体（默认：默认智能体）。
• --include-promoted：包含已提升的 deep 候选项。
• --json：打印 JSON 输出。

Dreaming

Dreaming 是后台记忆整合系统，包含三个协作阶段：light（整理/暂存短期材料）、deep（将持久事实提升到 MEMORY.md）和 REM（反思并呈现主题）。

• 使用 plugins.entries.memory-core.config.dreaming.enabled: true 启用。
• 通过聊天中的 /dreaming on|off 切换（或使用 /dreaming status 查看）。
• Dreaming 按一个托管扫描计划（dreaming.frequency）运行，并按顺序执行阶段：light、REM、deep。
• 只有 deep 阶段会将持久记忆写入 MEMORY.md。
• 人类可读的阶段输出和日记条目会写入 DREAMS.md（或现有的 dreams.md），也可在 memory/dreaming/<phase>/YYYY-MM-DD.md 中生成可选的分阶段报告。
• 排名使用加权信号：召回频率、检索相关性、查询多样性、时间新近度、跨日整合，以及派生概念丰富度。
• 提升会在写入 MEMORY.md 前重新读取实时每日笔记，因此已编辑或删除的短期片段不会从过期的召回存储快照中被提升。
• 定时和手动 memory promote 运行共享相同的 deep 阶段默认值，除非你传入 CLI 阈值覆盖项。
• 自动运行会分发到已配置的记忆工作区。

默认调度：

• 扫描节奏：dreaming.frequency = 0 3 * * *
• Deep 阈值：minScore=0.8、minRecallCount=3、minUniqueQueries=3、recencyHalfLifeDays=14、maxAgeDays=30

示例：

{
  "plugins": {
    "entries": {
      "memory-core": {
        "config": {
          "dreaming": {
            "enabled": true
          }
        }
      }
    }
  }
}

注意事项：

• memory index --verbose 会打印每个阶段的详细信息（提供商、模型、来源、批处理活动）。
• memory status 包含通过 memorySearch.extraPaths 配置的任何额外路径。
• 如果实际生效的主动记忆远程 API key 字段配置为 SecretRefs，该命令会从活跃的 Gateway 网关快照解析这些值。如果 Gateway 网关不可用，该命令会快速失败。
• Gateway 网关版本偏差说明：此命令路径需要支持 secrets.resolve 的 Gateway 网关；较旧的 Gateway 网关会返回 unknown-method 错误。
• 使用 dreaming.frequency 调整定时扫描节奏。Deep 提升策略除此之外为内部策略；需要一次性手动覆盖时，在 memory promote 上使用 CLI 标志。
• memory rem-harness --path <file-or-dir> --grounded 会从历史每日笔记预览有依据的 What Happened、Reflections 和 Possible Lasting Updates，而不写入任何内容。
• memory rem-backfill --path <file-or-dir> 会将可逆的有依据日记条目写入 DREAMS.md，供 UI 审查。
• memory rem-backfill --path <file-or-dir> --stage-short-term 还会将有依据的持久候选项播种到实时短期提升存储中，使普通 deep 阶段可以对其排序。
• memory rem-backfill --rollback 会移除先前写入的有依据日记条目，memory rem-backfill --rollback-short-term 会移除先前暂存的有依据短期候选项。
• 请参阅 Dreaming，了解完整阶段描述和配置参考。

相关内容

• CLI 参考
• 记忆概览

📄 消息

原文：https://docs.openclaw.ai/zh-CN/cli/message

openclaw message

用于发送消息和频道操作的单一出站命令
（Discord/Google Chat/iMessage/Matrix/Mattermost（插件）/Microsoft Teams/Signal/Slack/Telegram/WhatsApp）。

用法

openclaw message <subcommand> [flags]

频道选择：

• 如果配置了多个渠道，则必须提供 --channel。
• 如果只配置了一个渠道，它会成为默认值。
• 值：discord|googlechat|imessage|matrix|mattermost|msteams|signal|slack|telegram|whatsapp（Mattermost 需要插件）
• 当存在 --channel 或带渠道前缀的目标时，openclaw message 会将所选渠道解析为其所属插件；否则会加载已配置的渠道插件来推断默认渠道。

目标格式（--target）：

• WhatsApp：E.164、群组 JID，或 WhatsApp 频道/Newsletter JID（...@newsletter）
• Telegram：聊天 ID、@username，或论坛主题目标（-1001234567890:topic:42，或 --thread-id 42）
• Discord：channel:<id> 或 user:<id>（或 <@id> 提及；原始数字 ID 会被视为频道）
• Google Chat：spaces/<spaceId> 或 users/<userId>
• Slack：channel:<id> 或 user:<id>（接受原始频道 ID）
• Mattermost（插件）：channel:<id>、user:<id>，或 @username（裸 ID 会被视为频道）
• Signal：+E.164、group:<id>、signal:+E.164、signal:group:<id>，或 username:<name>/u:<name>
• iMessage：句柄、chat_id:<id>、chat_guid:<guid>，或 chat_identifier:<id>
• Matrix：@user:server、!room:server，或 #alias:server
• Microsoft Teams：会话 ID（19:...@thread.tacv2）或 conversation:<id> 或 user:<aad-object-id>