diff --git a/docs/zh-CN/help/faq.md b/docs/zh-CN/help/faq.md index 4bb37277e..868432c06 100644 --- a/docs/zh-CN/help/faq.md +++ b/docs/zh-CN/help/faq.md @@ -1,29 +1,29 @@ --- read_when: - - 回答常见的设置、安装、新手引导或运行时支持问题 - - 在深入调试之前对用户报告的问题进行初步分类 + - 解答常见的设置、安装、新手引导或运行时支持问题 + - 在进行更深入的调试之前，对用户报告的问题进行初步分类和排查 summary: 关于 OpenClaw 设置、配置和使用的常见问题 title: 常见问题 x-i18n: - generated_at: "2026-04-24T04:03:10Z" + generated_at: "2026-04-24T06:59:00Z" model: gpt-5.4 provider: openai - source_hash: dd0e951ed4accd924b94d6aa2963547e06b6961c7c3c98563397a9b6d36e4979 + source_hash: 0ae635d7ade265e3e79d1f5489ae23034a341843bd784f68a985b18bee5bdf6f source_path: help/faq.md workflow: 15 --- -面向真实环境设置的快速解答与更深入的故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）。有关运行时诊断，请参见 [故障排除](/zh-CN/gateway/troubleshooting)。有关完整配置参考，请参见 [配置](/zh-CN/gateway/configuration)。 +针对真实环境配置的快速解答与更深入的故障排除（本地开发、VPS、多智能体、OAuth/API 密钥、模型故障切换）。如需运行时诊断，请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。如需完整配置参考，请参阅 [Configuration](/zh-CN/gateway/configuration)。 -## 最初的六十秒：如果出了问题 +## 如果出现问题，最初的六十秒 -1. **快速状态（第一项检查）** +1. **快速状态（第一步检查）** ```bash openclaw status ``` - 快速本地摘要：操作系统 + 更新、gateway/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 gateway 可达时）。 + 快速本地摘要：操作系统 + 更新、Gateway 网关/服务可达性、智能体/会话、提供商配置 + 运行时问题（当 Gateway 网关可达时）。 2. **可粘贴的报告（可安全分享）** @@ -39,7 +39,7 @@ x-i18n: openclaw gateway status ``` - 显示 supervisor 运行时与 RPC 可达性、探测目标 URL，以及服务可能使用了哪个配置。 + 显示 supervisor 运行时与 RPC 可达性、探测目标 URL，以及服务可能使用的是哪个配置。 4. **深度探测** @@ -47,22 +47,22 @@ x-i18n: openclaw status --deep ``` - 运行实时 gateway 健康探测，包括在支持时的渠道探测 - （需要 gateway 可达）。参见 [Health](/zh-CN/gateway/health)。 + 运行实时 Gateway 网关健康探测，包括支持时的渠道探测 + （需要可访问的 Gateway 网关）。请参阅 [Health](/zh-CN/gateway/health)。 -5. **跟踪最新日志** +5. **查看最新日志** ```bash openclaw logs --follow ``` - 如果 RPC 不可用，请回退到： + 如果 RPC 不可用，则退回到： ```bash tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - 文件日志与服务日志是分开的；参见 [日志](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 + 文件日志与服务日志是分开的；请参阅 [Logging](/zh-CN/logging) 和 [故障排除](/zh-CN/gateway/troubleshooting)。 6. **运行 Doctor（修复）** @@ -70,7 +70,7 @@ x-i18n: openclaw doctor ``` - 修复/迁移配置/状态 + 运行健康检查。参见 [Doctor](/zh-CN/gateway/doctor)。 + 修复/迁移配置/状态 + 运行健康检查。请参阅 [Doctor](/zh-CN/gateway/doctor)。 7. **Gateway 网关快照** @@ -79,92 +79,91 @@ x-i18n: openclaw health --verbose # 出错时显示目标 URL + 配置路径 ``` - 向正在运行的 gateway 请求完整快照（仅 WS）。参见 [Health](/zh-CN/gateway/health)。 + 向正在运行的 Gateway 网关请求完整快照（仅 WS）。请参阅 [Health](/zh-CN/gateway/health)。 ## 快速开始与首次运行设置 -首次运行设置问答——安装、新手引导、认证路径、订阅、初始 -失败——已移至专门页面： -[FAQ——快速开始与首次运行设置](/zh-CN/help/faq-first-run)。 +首次运行问答——安装、新手引导、认证路径、订阅、初始失败—— +位于 [首次运行 FAQ](/zh-CN/help/faq-first-run)。 ## 什么是 OpenClaw？ - - OpenClaw 是你运行在自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及内置的渠道插件，例如 QQ Bot），并且在支持的平台上还能提供语音 + 实时 Canvas。**Gateway 网关** 是始终在线的控制平面；助手才是产品本身。 + + OpenClaw 是一个运行在你自己设备上的个人 AI 助手。它会在你已经使用的消息界面上回复你（WhatsApp、Telegram、Slack、Mattermost、Discord、Google Chat、Signal、iMessage、WebChat，以及内置的渠道插件，如 QQ Bot），并且在受支持的平台上还可以提供语音 + 实时 Canvas。**Gateway 网关**是始终在线的控制平面；助手才是产品本身。 - OpenClaw 不只是“Claude 的封装器”。它是一个**本地优先的控制平面**，让你可以在**自己的硬件**上运行一个 - 功能强大的助手，可从你已经使用的聊天应用访问，并具备 - 有状态会话、记忆和工具——而无需把你的工作流控制权交给托管式 + OpenClaw 不只是“一个 Claude 封装器”。它是一个**本地优先的控制平面**，让你能够在**你自己的硬件上**运行一个 + 功能强大的助手，并可通过你已经使用的聊天应用访问，同时具备 + 有状态会话、记忆和工具能力——无需把你的工作流控制权交给托管式 SaaS。 亮点： - - **你的设备，你的数据：** 你可以在任何地方运行 Gateway 网关（Mac、Linux、VPS），并将 + - **你的设备，你的数据：** 你可以在任意位置运行 Gateway 网关（Mac、Linux、VPS），并将 工作区 + 会话历史保留在本地。 - **真实渠道，而不是网页沙箱：** WhatsApp/Telegram/Slack/Discord/Signal/iMessage 等， - 以及在支持平台上的移动语音和 Canvas。 + 以及在受支持平台上的移动语音和 Canvas。 - **模型无关：** 使用 Anthropic、OpenAI、MiniMax、OpenRouter 等，并支持按智能体路由 和故障切换。 - - **纯本地选项：** 运行本地模型，这样**所有数据都可以保留在你的设备上**，如果你愿意的话。 - - **多智能体路由：** 为每个渠道、账户或任务使用不同智能体，每个智能体都有自己的 - 工作区和默认设置。 - - **开源且可定制：** 可检查、可扩展、可自托管，无供应商锁定。 + - **仅本地选项：** 运行本地模型，这样**所有数据都可以保留在你的设备上**，如果你愿意的话。 + - **多智能体路由：** 按渠道、账号或任务区分不同智能体，每个智能体都有自己的 + 工作区和默认值。 + - **开源且可改造：** 可检查、扩展并自托管，无需受制于供应商锁定。 文档： [Gateway 网关](/zh-CN/gateway)、[Channels](/zh-CN/channels)、[Multi-agent](/zh-CN/concepts/multi-agent)、 [Memory](/zh-CN/concepts/memory)。 - - 很适合作为起步的项目： + + 适合入门的项目： - - 搭建一个网站（WordPress、Shopify，或一个简单的静态网站）。 - - 为移动应用制作原型（大纲、界面、API 计划）。 + - 搭建一个网站（WordPress、Shopify，或一个简单的静态站点）。 + - 制作一个移动应用原型（梳理、大纲、界面、API 方案）。 - 整理文件和文件夹（清理、命名、打标签）。 - - 连接 Gmail，并自动生成摘要或后续跟进。 + - 连接 Gmail，并自动生成摘要或跟进事项。 - 它可以处理大型任务，但当你将任务拆分为多个阶段，并且 - 使用子智能体并行工作时，效果通常最好。 + 它可以处理大型任务，但当你把它们拆分成多个阶段，并 + 使用子智能体进行并行工作时，效果最好。 - - 日常最有价值的用法通常包括： + + 日常收益通常体现在： - **个人简报：** 汇总你关心的收件箱、日历和新闻。 - - **研究与起草：** 快速研究、总结，以及为邮件或文档生成初稿。 - - **提醒与跟进：** 由 cron 或 heartbeat 驱动的提醒和检查清单。 - - **浏览器自动化：** 填表、收集数据、重复执行网页任务。 - - **跨设备协作：** 从手机发送任务，让 Gateway 网关在服务器上运行，然后把结果返回到聊天中。 + - **研究与草拟：** 快速研究、总结，以及邮件或文档的初稿。 + - **提醒与跟进：** 由 cron 或 heartbeat 驱动的提醒和清单。 + - **浏览器自动化：** 填写表单、收集数据、重复执行网页任务。 + - **跨设备协作：** 从手机发送任务，让 Gateway 网关在服务器上运行，并在聊天中把结果返回给你。 - 可以，用于**研究、筛选和起草**。它可以扫描网站、建立候选名单、 - 总结潜在客户，并撰写外联文案或广告文案草稿。 + 可以，用于**研究、筛选和草拟**。它可以扫描网站、建立候选名单、 + 总结潜在客户信息，并撰写外联文案或广告文案草稿。 - 对于**外联或广告投放**，请让人工参与审核。避免垃圾信息，遵守当地法律和 - 平台政策，并在发送前审核所有内容。最安全的方式是让 - OpenClaw 起草，由你批准。 + 对于**外联或广告投放**，请始终让人工参与把关。避免垃圾信息，遵守当地法律和 + 平台政策，并在发送前审查所有内容。最安全的模式是让 + OpenClaw 起草，然后由你批准。 - 文档： [安全](/zh-CN/gateway/security)。 + 文档： [Security](/zh-CN/gateway/security)。 - - OpenClaw 是一个**个人助手**和协作层，而不是 IDE 替代品。在仓库内部需要最快的直接编码循环时， - 请使用 Claude Code 或 Codex。需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。 + + OpenClaw 是一个**个人助手**和协作协调层，而不是 IDE 替代品。要在仓库内部获得最快的直接编码循环，请使用 + Claude Code 或 Codex。当你需要持久记忆、跨设备访问和工具编排时，请使用 OpenClaw。 优势： - **跨会话的持久记忆 + 工作区** - **多平台访问**（WhatsApp、Telegram、TUI、WebChat） - **工具编排**（浏览器、文件、调度、hooks） - - **始终在线的 Gateway 网关**（运行在 VPS 上，随处交互） - - 用于本地浏览器/屏幕/摄像头/exec 的 **Nodes** + - **始终在线的 Gateway 网关**（运行在 VPS 上，随时随地交互） + - 用于本地浏览器/屏幕/相机/执行的 **Nodes** 展示： [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -175,68 +174,68 @@ x-i18n: - 使用受管覆盖，而不是编辑仓库副本。将你的修改放在 `~/.openclaw/skills//SKILL.md` 中（或者通过 `~/.openclaw/openclaw.json` 里的 `skills.load.extraDirs` 添加文件夹）。优先级顺序是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此受管覆盖在不修改 git 的情况下仍会优先于内置 skills。如果你需要全局安装该 skill，但只让某些智能体可见，请将共享副本保存在 `~/.openclaw/skills` 中，并用 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有值得上游采纳的修改才应该保存在仓库中并以 PR 形式提交。 + 使用受管覆盖，而不是直接编辑仓库副本。把你的更改放在 `~/.openclaw/skills//SKILL.md` 中（或者通过 `~/.openclaw/openclaw.json` 里的 `skills.load.extraDirs` 添加文件夹）。优先级顺序为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`，因此受管覆盖仍然会优先于内置 skills，而无需修改 git。如果你需要全局安装某个 skill，但只希望部分智能体可见，请将共享副本放在 `~/.openclaw/skills` 中，并通过 `agents.defaults.skills` 和 `agents.list[].skills` 控制可见性。只有适合上游的修改才应保存在仓库中，并通过 PR 提交出去。 - 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级是 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果该 skill 只应对某些智能体可见，请再配合使用 `agents.defaults.skills` 或 `agents.list[].skills`。 + 可以。通过 `~/.openclaw/openclaw.json` 中的 `skills.load.extraDirs` 添加额外目录（最低优先级）。默认优先级为 `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → 内置 → `skills.load.extraDirs`。`clawhub` 默认安装到 `./skills`，OpenClaw 会在下一个会话中将其视为 `/skills`。如果该 skill 只应对某些智能体可见，请同时配合 `agents.defaults.skills` 或 `agents.list[].skills` 使用。 - - 当前支持的模式有： + + 目前支持的模式包括： - - **Cron 作业**：隔离作业可以为每个作业设置 `model` 覆盖。 - - **子智能体**：将任务路由到具有不同默认模型的独立智能体。 + - **Cron jobs**：隔离任务可以为每个任务设置 `model` 覆盖。 + - **子智能体**：将任务路由到使用不同默认模型的独立智能体。 - **按需切换**：随时使用 `/model` 切换当前会话模型。 - 参见 [Cron jobs](/zh-CN/automation/cron-jobs)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 + 请参阅 [Cron jobs](/zh-CN/automation/cron-jobs)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent) 和 [Slash commands](/zh-CN/tools/slash-commands)。 - - 对于长时间或并行任务，请使用**子智能体**。子智能体在自己的会话中运行， - 返回摘要，并让你的主聊天保持响应。 + + 对于长时间运行或可并行的任务，请使用**子智能体**。子智能体会在自己的会话中运行， + 返回摘要，并保持你的主聊天仍然可响应。 - 让你的 bot “为这个任务生成一个子智能体”，或者使用 `/subagents`。 - 在聊天中使用 `/status` 可查看 Gateway 网关当前正在做什么（以及它是否繁忙）。 + 让你的机器人“为这个任务启动一个子智能体”，或者使用 `/subagents`。 + 使用聊天中的 `/status` 查看 Gateway 网关当前正在做什么（以及它是否繁忙）。 - 令牌提示：长任务和子智能体都会消耗令牌。如果你关心成本，请通过 `agents.defaults.subagents.model` 为子智能体设置一个 + 令牌提示：长任务和子智能体都会消耗令牌。如果你担心成本，可以通过 `agents.defaults.subagents.model` 为子智能体设置 更便宜的模型。 文档： [Sub-agents](/zh-CN/tools/subagents)、[Background Tasks](/zh-CN/automation/tasks)。 - - 使用线程绑定。你可以将 Discord 线程绑定到某个子智能体或会话目标，这样该线程中的后续消息就会停留在那个绑定的会话上。 + + 使用线程绑定。你可以将 Discord 线程绑定到某个 subagent 或会话目标，这样该线程中的后续消息就会保持在该绑定会话上。 基本流程： - - 使用 `sessions_spawn` 并设置 `thread: true` 来生成（也可选择设置 `mode: "session"` 以启用持久后续跟进）。 - - 或使用 `/focus ` 手动绑定。 - - 使用 `/agents` 查看绑定状态。 - - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消焦点。 + - 使用 `sessions_spawn` 并设置 `thread: true` 启动（也可以选择设置 `mode: "session"` 以支持持久后续跟进）。 + - 或者使用 `/focus ` 手动绑定。 + - 使用 `/agents` 检查绑定状态。 + - 使用 `/session idle ` 和 `/session max-age ` 控制自动取消聚焦。 - 使用 `/unfocus` 解除线程绑定。 - 所需配置： + 必需配置： - 全局默认值：`session.threadBindings.enabled`、`session.threadBindings.idleHours`、`session.threadBindings.maxAgeHours`。 - Discord 覆盖：`channels.discord.threadBindings.enabled`、`channels.discord.threadBindings.idleHours`、`channels.discord.threadBindings.maxAgeHours`。 - - 生成时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 + - 在启动时自动绑定：设置 `channels.discord.threadBindings.spawnSubagentSessions: true`。 文档： [Sub-agents](/zh-CN/tools/subagents)、[Discord](/zh-CN/channels/discord)、[Configuration Reference](/zh-CN/gateway/configuration-reference)、[Slash commands](/zh-CN/tools/slash-commands)。 - - 先检查解析后的请求者路由： + + 先检查已解析的请求方路由： - - 完成模式下的子智能体投递会优先使用任何已绑定的线程或会话路由（如果存在）。 - - 如果完成来源只携带渠道，OpenClaw 会回退到请求者会话存储的路由（`lastChannel` / `lastTo` / `lastAccountId`），以便直接投递仍然可以成功。 - - 如果既没有绑定路由，也没有可用的存储路由，直接投递可能失败，结果会回退到排队的会话投递，而不是立即发到聊天中。 - - 无效或过期的目标仍可能强制回退为队列投递，或导致最终投递失败。 - - 如果子会话中最后一条可见助手回复恰好是静默令牌 `NO_REPLY` / `no_reply`，或恰好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发布之前已过时的进度。 - - 如果子会话在只执行了工具调用后超时，公告可能会将其折叠为简短的部分进度摘要，而不是回放原始工具输出。 + - 完成模式的 subagent 投递会优先使用任何已绑定的线程或会话路由（如果存在）。 + - 如果完成来源只携带渠道，OpenClaw 会回退到请求方会话保存的路由（`lastChannel` / `lastTo` / `lastAccountId`），以便直接投递仍然可以成功。 + - 如果既没有绑定路由，也没有可用的已保存路由，直接投递可能失败，结果会回退为排队的会话投递，而不是立即发布到聊天中。 + - 无效或过期的目标仍可能导致队列回退或最终投递失败。 + - 如果子会话最后一个可见的助手回复恰好是静默令牌 `NO_REPLY` / `no_reply`，或者恰好是 `ANNOUNCE_SKIP`，OpenClaw 会有意抑制公告，而不是发布更早的过时进度。 + - 如果子会话在仅进行了工具调用后超时，公告可能会将其折叠为简短的部分进度摘要，而不是重放原始工具输出。 调试： @@ -250,13 +249,13 @@ x-i18n: Cron 在 Gateway 网关进程内部运行。如果 Gateway 网关没有持续运行， - 定时作业就不会执行。 + 定时任务就不会运行。 检查清单： - - 确认已启用 cron（`cron.enabled`），并且没有设置 `OPENCLAW_SKIP_CRON`。 - - 检查 Gateway 网关是否 24/7 运行（没有休眠/重启）。 - - 验证作业的时区设置（`--tz` 与主机时区）。 + - 确认 cron 已启用（`cron.enabled`），并且未设置 `OPENCLAW_SKIP_CRON`。 + - 检查 Gateway 网关是否 24/7 持续运行（没有休眠/重启）。 + - 验证任务的时区设置（`--tz` 与主机时区）。 调试： @@ -272,14 +271,14 @@ x-i18n: 先检查投递模式： - - `--no-deliver` / `delivery.mode: "none"` 表示不会有 runner 回退发送。 + - `--no-deliver` / `delivery.mode: "none"` 表示不应预期有 runner 回退发送。 - 缺少或无效的公告目标（`channel` / `to`）表示 runner 跳过了出站投递。 - - 渠道认证失败（`unauthorized`、`Forbidden`）表示 runner 已尝试投递，但被凭证阻止了。 + - 渠道认证失败（`unauthorized`、`Forbidden`）表示 runner 尝试投递了，但凭证阻止了它。 - 静默的隔离结果（仅有 `NO_REPLY` / `no_reply`）会被视为有意不可投递，因此 runner 也会抑制排队回退投递。 - 对于隔离的 cron 作业，如果存在聊天路由，智能体仍然可以通过 `message` - 工具直接发送。`--announce` 仅控制 runner 的 - 最终文本回退路径，不影响智能体已经自行发送的内容。 + 对于隔离的 cron 任务，如果聊天路由可用，智能体仍然可以通过 `message` + 工具直接发送。`--announce` 只控制 runner 的 + 最终文本回退路径，即智能体尚未自行发送的文本。 调试： @@ -292,22 +291,22 @@ x-i18n: - + 这通常是实时模型切换路径，而不是重复调度。 - 隔离的 cron 可以在当前运行抛出 `LiveSessionModelSwitchError` 时， + 隔离的 cron 可以在活动运行抛出 `LiveSessionModelSwitchError` 时， 持久化运行时模型切换并重试。重试会保留切换后的 - 提供商/模型；如果该切换携带了新的认证配置文件覆盖，cron + provider/model，如果切换还带有新的认证配置覆盖，cron 也会在重试前将其持久化。 相关选择规则： - 如果适用，Gmail hook 模型覆盖优先级最高。 - - 然后是每个作业的 `model`。 + - 然后是每个任务的 `model`。 - 然后是任何已存储的 cron 会话模型覆盖。 - 最后是正常的智能体/默认模型选择。 - 重试循环是有界的。初始尝试加上 2 次切换重试之后， + 重试循环是有上限的。在初始尝试加上 2 次切换重试之后， cron 会中止，而不是无限循环。 调试： @@ -322,7 +321,7 @@ x-i18n: - 使用原生 `openclaw skills` 命令，或将 skills 放入你的工作区。macOS Skills UI 在 Linux 上不可用。 + 使用原生 `openclaw skills` 命令，或将 skills 放入你的工作区。macOS 的 Skills UI 在 Linux 上不可用。 可在 [https://clawhub.ai](https://clawhub.ai) 浏览 skills。 ```bash @@ -338,37 +337,37 @@ x-i18n: 原生 `openclaw skills install` 会写入当前工作区的 `skills/` 目录。只有当你想发布或 - 同步自己的 skills 时，才需要额外安装 `clawhub` CLI。对于跨智能体共享安装，请将 skill 放到 - `~/.openclaw/skills` 下，并在需要限制可见智能体时使用 `agents.defaults.skills` 或 - `agents.list[].skills`。 + 同步你自己的 skills 时，才需要单独安装 `clawhub` CLI。对于跨智能体共享安装，请将 skill 放在 + `~/.openclaw/skills` 下，并使用 `agents.defaults.skills` 或 + `agents.list[].skills`，如果你想限制哪些智能体可以看到它。 - + 可以。使用 Gateway 网关调度器： - - **Cron jobs**：用于计划或周期性任务（重启后仍会保留）。 - - **Heartbeat**：用于“主会话”的周期检查。 - - **隔离作业**：用于会发布摘要或投递到聊天的自治智能体。 + - **Cron jobs**：用于定时或周期性任务（重启后仍会保留）。 + - **Heartbeat**：用于“主会话”的周期性检查。 + - **隔离任务**：用于会发布摘要或投递到聊天的自主智能体。 文档： [Cron jobs](/zh-CN/automation/cron-jobs)、[Automation & Tasks](/zh-CN/automation)、 [Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不能直接运行。macOS skills 受 `metadata.openclaw.os` 和所需二进制文件控制，且 skills 只有在 **Gateway 网关主机** 上符合条件时才会出现在系统提示中。在 Linux 上，仅限 `darwin` 的 skills（例如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这些限制条件。 + + 不能直接运行。macOS skills 受 `metadata.openclaw.os` 与所需二进制文件限制，而且 skills 只有在 **Gateway 网关主机** 上符合条件时，才会出现在系统提示中。在 Linux 上，仅限 `darwin` 的 skills（如 `apple-notes`、`apple-reminders`、`things-mac`）不会加载，除非你覆盖这些限制。 你有三种受支持的模式： **选项 A - 在 Mac 上运行 Gateway 网关（最简单）。** - 在存在 macOS 二进制文件的地方运行 Gateway 网关，然后通过[远程模式](#gateway-ports-already-running-and-remote-mode)或 Tailscale 从 Linux 连接。由于 Gateway 网关主机是 macOS，这些 skills 会正常加载。 + 在存在 macOS 二进制文件的地方运行 Gateway 网关，然后通过 [远程模式](#gateway-ports-already-running-and-remote-mode) 或 Tailscale 从 Linux 连接。由于 Gateway 网关主机是 macOS，这些 skills 会正常加载。 - **选项 B - 使用 macOS 节点（不使用 SSH）。** - 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为“Always Ask”或“Always Allow”。OpenClaw 可以在节点上存在所需二进制文件时，将仅限 macOS 的 skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 skills。如果你选择“Always Ask”，在提示中批准“Always Allow”会将该命令加入 allowlist。 + **选项 B - 使用 macOS 节点（无需 SSH）。** + 在 Linux 上运行 Gateway 网关，配对一个 macOS 节点（菜单栏应用），并在 Mac 上将 **Node Run Commands** 设置为 “Always Ask” 或 “Always Allow”。当节点上存在所需二进制文件时，OpenClaw 可以将仅限 macOS 的 skills 视为符合条件。智能体会通过 `nodes` 工具运行这些 skills。如果你选择 “Always Ask”，在提示中批准 “Always Allow” 会将该命令添加到允许列表。 **选项 C - 通过 SSH 代理 macOS 二进制文件（高级）。** - 保持 Gateway 网关运行在 Linux 上，但让所需的 CLI 二进制文件解析为在 Mac 上运行的 SSH 包装器。然后覆盖该 skill，使其允许 Linux，从而保持可用。 + 保持 Gateway 网关运行在 Linux 上，但让所需的 CLI 二进制文件解析为通过 SSH 在 Mac 上运行的包装器。然后覆盖该 skill，使其允许 Linux，从而保持其符合条件。 1. 为该二进制文件创建一个 SSH 包装器（示例：Apple Notes 的 `memo`）： @@ -389,7 +388,7 @@ x-i18n: --- ``` - 4. 启动一个新会话，以刷新 skills 快照。 + 4. 启动一个新会话，以便刷新 skills 快照。 @@ -398,13 +397,13 @@ x-i18n: 可选方案： - - **自定义 skill / 插件：** 最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 - - **浏览器自动化：** 无需编写代码即可使用，但速度更慢，也更脆弱。 + - **自定义 skill / plugin：** 最适合可靠的 API 访问（Notion/HeyGen 都有 API）。 + - **浏览器自动化：** 无需编写代码即可使用，但更慢且更脆弱。 - 如果你希望为每个客户保留上下文（代理机构工作流），一种简单模式是： + 如果你想为每个客户保留上下文（代理工作流），一种简单模式是： - - 每个客户一个 Notion 页面（上下文 + 偏好 + 当前工作）。 - - 在会话开始时让智能体抓取该页面。 + - 为每个客户创建一个 Notion 页面（上下文 + 偏好 + 当前工作）。 + - 让智能体在会话开始时获取该页面。 如果你想要原生集成，请提交功能请求，或构建一个 面向这些 API 的 skill。 @@ -416,130 +415,130 @@ x-i18n: openclaw skills update --all ``` - 原生安装会落到当前工作区的 `skills/` 目录中。若需在多个智能体之间共享 skills，请将它们放在 `~/.openclaw/skills//SKILL.md` 中。如果共享安装只应对部分智能体可见，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。某些 skills 预期通过 Homebrew 安装二进制文件；在 Linux 上这意味着 Linuxbrew（参见上面的 Homebrew Linux FAQ 条目）。参见 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 + 原生安装会落在当前工作区的 `skills/` 目录中。对于跨智能体共享的 skills，请将它们放在 `~/.openclaw/skills//SKILL.md`。如果只希望某些智能体看到共享安装，请配置 `agents.defaults.skills` 或 `agents.list[].skills`。某些 skills 需要通过 Homebrew 安装的二进制文件；在 Linux 上这意味着 Linuxbrew（参见上面的 Homebrew Linux FAQ 条目）。请参阅 [Skills](/zh-CN/tools/skills)、[Skills 配置](/zh-CN/tools/skills-config) 和 [ClawHub](/zh-CN/tools/clawhub)。 - 使用内置的 `user` 浏览器配置文件，它会通过 Chrome DevTools MCP 连接： + 使用内置的 `user` 浏览器配置文件，它通过 Chrome DevTools MCP 进行连接： ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - 如果你想使用自定义名称，请创建一个显式 MCP 配置文件： + 如果你想使用自定义名称，请创建一个显式的 MCP 配置文件： ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - 这一路径可以使用本地主机浏览器，也可以使用已连接的浏览器节点。如果 Gateway 网关运行在其他地方，请在浏览器所在机器上运行一个节点主机，或改用远程 CDP。 + 此路径可以使用本地主机浏览器或已连接的浏览器节点。如果 Gateway 网关运行在其他地方，请在浏览器所在机器上运行一个节点主机，或改用远程 CDP。 - `existing-session` / `user` 当前限制： + `existing-session` / `user` 当前限制如下： - - 操作基于 ref 驱动，而不是基于 CSS 选择器驱动 - - 上传需要 `ref` / `inputRef`，且当前一次只支持一个文件 + - 操作基于 ref，而不是基于 CSS 选择器 + - 上传需要 `ref` / `inputRef`，并且当前一次只支持一个文件 - `responsebody`、PDF 导出、下载拦截和批量操作仍然需要受管浏览器或原始 CDP 配置文件 -## 沙箱隔离与记忆 +## 沙箱隔离与内存 - - 有。参见 [沙箱隔离](/zh-CN/gateway/sandboxing)。有关 Docker 专用设置（Docker 中运行完整 gateway 或沙箱镜像），请参见 [Docker](/zh-CN/install/docker)。 + + 有。请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing)。对于 Docker 专用设置（Docker 中运行完整 gateway 或沙箱镜像），请参阅 [Docker](/zh-CN/install/docker)。 - - 默认镜像以安全优先为原则，并以 `node` 用户运行，因此它不 - 包含系统软件包、Homebrew 或内置浏览器。若要获得更完整的设置： + + 默认镜像以安全优先，并以 `node` 用户身份运行，因此它 + 不包含系统软件包、Homebrew 或内置浏览器。若要获得更完整的配置： - 使用 `OPENCLAW_HOME_VOLUME` 持久化 `/home/node`，以便缓存得以保留。 - - 使用 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖打包进镜像。 + - 通过 `OPENCLAW_DOCKER_APT_PACKAGES` 将系统依赖烘焙进镜像。 - 通过内置 CLI 安装 Playwright 浏览器： `node /app/node_modules/playwright-core/cli.js install chromium` - - 设置 `PLAYWRIGHT_BROWSERS_PATH`，并确保该路径已持久化。 + - 设置 `PLAYWRIGHT_BROWSERS_PATH` 并确保该路径已持久化。 文档： [Docker](/zh-CN/install/docker)、[Browser](/zh-CN/tools/browser)。 - - 可以——前提是你的私有流量是**私信**，公开流量是**群组**。 + + 可以——前提是你的私有流量是 **私信**，而你的公开流量是 **群组**。 - 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非主键）会在已配置的沙箱后端中运行，而主私信会话仍在主机上运行。如果你不选择后端，Docker 是默认后端。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 + 使用 `agents.defaults.sandbox.mode: "non-main"`，这样群组/渠道会话（非主键）会在配置的沙箱后端中运行，而主私信会话则保留在主机上运行。如果你不选择后端，Docker 是默认后端。然后通过 `tools.sandbox.tools` 限制沙箱隔离会话中可用的工具。 - 设置演练 + 示例配置： [群组：私有私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) + 设置演练 + 示例配置： [群组：个人私信 + 公开群组](/zh-CN/channels/groups#pattern-personal-dms-public-groups-single-agent) 关键配置参考： [Gateway 网关配置](/zh-CN/gateway/config-agents#agentsdefaultssandbox) - - 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局绑定和按智能体绑定会合并；当 `scope: "shared"` 时，按智能体绑定会被忽略。对任何敏感内容都使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 + + 将 `agents.defaults.sandbox.docker.binds` 设置为 `["host:path:mode"]`（例如 `"/home/user/src:/src:ro"`）。全局绑定和每个智能体的绑定会合并；当 `scope: "shared"` 时，会忽略每个智能体的绑定。对任何敏感内容请使用 `:ro`，并记住绑定会绕过沙箱文件系统边界。 - OpenClaw 会同时根据规范化路径以及通过最深现有祖先解析出的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，通过符号链接父路径逃逸也仍会以安全关闭方式失败，并且在符号链接解析之后仍会应用允许根路径检查。 + OpenClaw 会根据规范化路径以及通过最深现有父目录解析出的规范路径来验证绑定源。这意味着即使最后一个路径段尚不存在，通过符号链接父目录逃逸仍会以关闭方式失败，并且在解析符号链接后，允许根目录检查仍然适用。 - 示例和安全说明请参见 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [沙箱 vs 工具策略 vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 + 示例和安全说明请参阅 [沙箱隔离](/zh-CN/gateway/sandboxing#custom-bind-mounts) 和 [Sandbox vs Tool Policy vs Elevated](/zh-CN/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check)。 - - OpenClaw 的记忆其实就是智能体工作区中的 Markdown 文件： + + OpenClaw 的记忆实际上就是智能体工作区中的 Markdown 文件： - - `memory/YYYY-MM-DD.md` 中的每日笔记 - - `MEMORY.md` 中的长期整理笔记（仅主/私有会话） + - `memory/YYYY-MM-DD.md` 中的每日日志 + - `MEMORY.md` 中整理后的长期笔记（仅主/私密会话） - OpenClaw 还会运行一个**静默的压缩前记忆刷新**，提醒模型 - 在自动压缩之前写入可持久保存的笔记。此功能只会在工作区 - 可写时运行（只读沙箱会跳过）。参见 [Memory](/zh-CN/concepts/memory)。 + OpenClaw 还会运行一个**静默的压缩前记忆刷新**，以提醒模型 + 在自动压缩之前写入持久笔记。这仅在工作区 + 可写时运行（只读沙箱会跳过）。请参阅 [Memory](/zh-CN/concepts/memory)。 - - 让 bot **把这个事实写入记忆**。长期笔记应写入 `MEMORY.md`， - 短期上下文则写入 `memory/YYYY-MM-DD.md`。 + + 请让机器人**把这个事实写入记忆**。长期笔记应写入 `MEMORY.md`， + 短期上下文应写入 `memory/YYYY-MM-DD.md`。 - 这仍是我们正在持续改进的领域。提醒模型存储记忆会有帮助； - 它会知道该怎么做。如果它仍然总忘记，请确认 Gateway 网关每次运行时都在使用同一个 - 工作区。 + 这是我们仍在持续改进的领域。提醒模型存储记忆会有帮助； + 它会知道该怎么做。如果它仍然经常遗忘，请确认 Gateway 网关每次运行时 + 使用的是同一个工作区。 文档： [Memory](/zh-CN/concepts/memory)、[Agent workspace](/zh-CN/concepts/agent-workspace)。 - 记忆文件存储在磁盘上，除非你删除它们，否则会一直存在。限制来自你的 + 记忆文件保存在磁盘上，除非你删除它们，否则会一直存在。限制来自你的 存储空间，而不是模型。**会话上下文** 仍然受模型 - 上下文窗口限制，因此长对话可能会被压缩或截断。这也是为什么 - 存在记忆搜索——它只会把相关部分重新拉回上下文中。 + 上下文窗口限制，因此长对话可能会被压缩或截断。这就是为什么 + 存在记忆搜索——它只会将相关部分重新拉回上下文。 文档： [Memory](/zh-CN/concepts/memory)、[Context](/zh-CN/concepts/context)。 - + 只有在你使用 **OpenAI embeddings** 时才需要。Codex OAuth 仅覆盖 chat/completions， - **不**提供 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 - Codex CLI 登录）**对语义记忆搜索没有帮助。OpenAI embeddings + **不**授予 embeddings 访问权限，因此**使用 Codex 登录（OAuth 或 + Codex CLI 登录）**并不能帮助启用语义记忆搜索。OpenAI embeddings 仍然需要真实的 API 密钥（`OPENAI_API_KEY` 或 `models.providers.openai.apiKey`）。 - 如果你没有显式设置提供商，OpenClaw 会在能够解析出 API 密钥时 - 自动选择一个提供商（认证配置文件、`models.providers.*.apiKey` 或环境变量）。 + 如果你没有显式设置 provider，OpenClaw 会在 + 能解析出 API 密钥时自动选择 provider（认证配置、`models.providers.*.apiKey` 或环境变量）。 如果能解析出 OpenAI 密钥，它会优先选择 OpenAI；否则如果能解析出 Gemini 密钥， - 就选择 Gemini；然后是 Voyage；再然后是 Mistral。如果没有可用的远程密钥， - 记忆搜索会保持禁用状态，直到你完成配置。如果你配置并提供了本地模型路径，OpenClaw + 就选择 Gemini；接着是 Voyage，然后是 Mistral。如果没有可用的远程密钥，记忆 + 搜索会保持禁用状态，直到你完成配置。如果你已经配置并存在本地模型路径，OpenClaw 会优先选择 `local`。当你显式设置 `memorySearch.provider = "ollama"` 时，也支持 Ollama。 - 如果你更希望保持本地化，可设置 `memorySearch.provider = "local"`（并可选设置 - `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，请设置 - `memorySearch.provider = "gemini"`，并提供 `GEMINI_API_KEY`（或 - `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** embedding - 模型——设置详情请参见 [Memory](/zh-CN/concepts/memory)。 + 如果你更希望保持本地化，请设置 `memorySearch.provider = "local"`（并可选地 + 设置 `memorySearch.fallback = "none"`）。如果你想使用 Gemini embeddings，请设置 + `memorySearch.provider = "gemini"` 并提供 `GEMINI_API_KEY`（或 + `memorySearch.remote.apiKey`）。我们支持 **OpenAI、Gemini、Voyage、Mistral、Ollama 或 local** + embedding 模型——设置详情请参阅 [Memory](/zh-CN/concepts/memory)。 @@ -548,49 +547,49 @@ x-i18n: - 不会——**OpenClaw 的状态是本地的**，但**外部服务仍然会看到你发送给它们的内容**。 + 不会——**OpenClaw 的状态在本地**，但**外部服务仍然会看到你发送给它们的内容**。 - - **默认本地：** 会话、记忆文件、配置和工作区都保存在 Gateway 网关主机上 + - **默认本地：** 会话、记忆文件、配置和工作区都位于 Gateway 网关主机上 （`~/.openclaw` + 你的工作区目录）。 - - **因需求而远程：** 你发送给模型提供商（Anthropic/OpenAI 等）的消息会发往 - 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会在它们的 - 服务器上存储消息数据。 - - **你可以控制数据范围：** 使用本地模型可让提示词保留在你的机器上，但渠道 + - **因需要而远程：** 你发送给模型 provider（Anthropic/OpenAI 等）的消息会发送到 + 它们的 API，而聊天平台（WhatsApp/Telegram/Slack 等）会将消息数据存储在其 + 服务器上。 + - **你可以控制数据范围：** 使用本地模型可以让提示词留在你的机器上，但渠道 流量仍会经过对应渠道的服务器。 相关内容： [Agent workspace](/zh-CN/concepts/agent-workspace)、[Memory](/zh-CN/concepts/memory)。 - - 一切都位于 `$OPENCLAW_STATE_DIR` 下（默认：`~/.openclaw`）： + + 所有内容都位于 `$OPENCLAW_STATE_DIR` 下（默认：`~/.openclaw`）： - | 路径 | 用途 | + | Path | 用途 | | --------------------------------------------------------------- | ------------------------------------------------------------------ | | `$OPENCLAW_STATE_DIR/openclaw.json` | 主配置（JSON5） | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到认证配置文件中） | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证配置文件（OAuth、API 密钥，以及可选的 `keyRef`/`tokenRef`） | - | `$OPENCLAW_STATE_DIR/secrets.json` | 用于 `file` SecretRef 提供商的可选文件后端密钥有效负载 | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | 旧版 OAuth 导入（首次使用时复制到认证配置中） | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | 认证配置（OAuth、API 密钥，以及可选的 `keyRef`/`tokenRef`） | + | `$OPENCLAW_STATE_DIR/secrets.json` | `file` SecretRef provider 的可选文件后端 secret 负载 | | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | 旧版兼容文件（静态 `api_key` 条目已清理） | - | `$OPENCLAW_STATE_DIR/credentials/` | 提供商状态（例如 `whatsapp//creds.json`） | - | `$OPENCLAW_STATE_DIR/agents/` | 按智能体划分的状态（agentDir + sessions） | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史与状态（按智能体） | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（按智能体） | + | `$OPENCLAW_STATE_DIR/credentials/` | provider 状态（例如 `whatsapp//creds.json`） | + | `$OPENCLAW_STATE_DIR/agents/` | 每个智能体的状态（agentDir + sessions） | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | 对话历史与状态（每个智能体） | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | 会话元数据（每个智能体） | 旧版单智能体路径：`~/.openclaw/agent/*`（由 `openclaw doctor` 迁移）。 - 你的**工作区**（AGENTS.md、记忆文件、skills 等）是分开的，通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 + 你的**工作区**（AGENTS.md、记忆文件、skills 等）是独立的，并通过 `agents.defaults.workspace` 配置（默认：`~/.openclaw/workspace`）。 - 这些文件位于**智能体工作区**中，而不是 `~/.openclaw`。 + 这些文件位于**智能体工作区**，而不是 `~/.openclaw`。 - - **工作区（按智能体）**：`AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 + - **工作区（每个智能体）：** `AGENTS.md`、`SOUL.md`、`IDENTITY.md`、`USER.md`、 `MEMORY.md`、`memory/YYYY-MM-DD.md`，以及可选的 `HEARTBEAT.md`。 - 根目录下的小写 `memory.md` 仅作为旧版修复输入；当两个文件都存在时， - `openclaw doctor --fix` 可将其合并到 `MEMORY.md` 中。 - - **状态目录（`~/.openclaw`）**：配置、渠道/提供商状态、认证配置文件、会话、日志， + 小写根目录 `memory.md` 仅作为旧版修复输入；当两个文件都存在时，`openclaw doctor --fix` + 可以将其合并到 `MEMORY.md` 中。 + - **状态目录（`~/.openclaw`）：** 配置、渠道/provider 状态、认证配置、会话、日志， 以及共享 skills（`~/.openclaw/skills`）。 默认工作区为 `~/.openclaw/workspace`，可通过以下方式配置： @@ -601,42 +600,42 @@ x-i18n: } ``` - 如果 bot 在重启后“忘记了东西”，请确认 Gateway 网关每次启动时都在使用同一个 - 工作区（并记住：远程模式使用的是**gateway 主机的** + 如果机器人在重启后“遗忘”了内容，请确认 Gateway 网关每次启动时 + 使用的都是同一个工作区（并记住：远程模式使用的是**Gateway 网关主机的** 工作区，而不是你本地笔记本的）。 - 提示：如果你想保留长期有效的行为或偏好，请让 bot **把它写入 - AGENTS.md 或 MEMORY.md**，而不是依赖聊天历史。 + 提示：如果你希望某个行为或偏好可以长期保留，请让机器人**把它写入 + AGENTS.md 或 MEMORY.md**，而不要只依赖聊天历史。 - 参见 [Agent workspace](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 + 请参阅 [Agent workspace](/zh-CN/concepts/agent-workspace) 和 [Memory](/zh-CN/concepts/memory)。 - 将你的**智能体工作区**放入一个**私有** git 仓库，并把它备份到某个 - 私有位置（例如 GitHub 私有仓库）。这样可以保存记忆 + AGENTS/SOUL/USER - 文件，并让你之后能够恢复助手的“思维”。 + 将你的**智能体工作区**放入一个**私有** git 仓库，并将其备份到某个 + 私密位置（例如 GitHub 私有仓库）。这样可以保留记忆 + AGENTS/SOUL/USER + 文件，并让你稍后恢复助手的“思维”。 - **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、令牌或加密密钥有效负载）。 + **不要**提交 `~/.openclaw` 下的任何内容（凭证、会话、令牌或加密的 secrets 负载）。 如果你需要完整恢复，请分别备份工作区和状态目录 - （参见上面的迁移相关问题）。 + （参见上面的迁移问题）。 文档： [Agent workspace](/zh-CN/concepts/agent-workspace)。 - 请参见专门指南： [Uninstall](/zh-CN/install/uninstall)。 + 请参阅专门指南： [Uninstall](/zh-CN/install/uninstall)。 可以。工作区是**默认 cwd** 和记忆锚点，而不是硬性沙箱。 - 相对路径会在工作区内解析，但绝对路径可以访问主机上的其他 - 位置，除非启用了沙箱隔离。如果你需要隔离，请使用 - [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或按智能体设置的沙箱配置。如果你 - 想让某个仓库成为默认工作目录，可将该智能体的 - `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源代码；除非你有意让智能体在其中工作，否则请将 - 工作区与其分开。 + 相对路径会在工作区内解析，但绝对路径可以访问其他 + 主机位置，除非启用了沙箱隔离。如果你需要隔离，请使用 + [`agents.defaults.sandbox`](/zh-CN/gateway/sandboxing) 或每个智能体的沙箱设置。如果你 + 希望某个仓库作为默认工作目录，请将该智能体的 + `workspace` 指向仓库根目录。OpenClaw 仓库本身只是源代码；除非你有意让智能体在其中工作，否则请保持 + 工作区与其分离。 示例（将仓库作为默认 cwd）： @@ -653,29 +652,29 @@ x-i18n: - 会话状态由**gateway 主机**持有。如果你处于远程模式，你真正关心的会话存储位于远程机器上，而不是本地笔记本。参见 [Session management](/zh-CN/concepts/session)。 + 会话状态由**Gateway 网关主机**持有。如果你处于远程模式，你需要关心的会话存储位于远程机器上，而不是本地笔记本上。请参阅 [Session management](/zh-CN/concepts/session)。 ## 配置基础 - - OpenClaw 会从 `$OPENCLAW_CONFIG_PATH` 读取可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： + + OpenClaw 从 `$OPENCLAW_CONFIG_PATH` 读取一个可选的 **JSON5** 配置（默认：`~/.openclaw/openclaw.json`）： ``` $OPENCLAW_CONFIG_PATH ``` - 如果文件缺失，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 + 如果该文件不存在，它会使用相对安全的默认值（包括默认工作区 `~/.openclaw/workspace`）。 - 非 loopback 绑定**需要有效的 gateway 认证路径**。实际来说，这意味着： + 非 loopback 绑定**需要有效的 gateway 认证路径**。实际中这意味着： - - 共享密钥认证：token 或 password - - 在正确配置的非 loopback 身份感知反向代理之后使用 `gateway.auth.mode: "trusted-proxy"` + - shared-secret 认证：token 或 password + - `gateway.auth.mode: "trusted-proxy"`，并且位于配置正确的非 loopback 身份感知反向代理之后 ```json5 { @@ -689,33 +688,33 @@ x-i18n: } ``` - 注意事项： + 说明： - `gateway.remote.token` / `.password` **不会**单独启用本地 gateway 认证。 - - 只有当 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 用作回退。 + - 只有当 `gateway.auth.*` 未设置时，本地调用路径才可以将 `gateway.remote.*` 作为回退。 - 对于 password 认证，请改为设置 `gateway.auth.mode: "password"` 加上 `gateway.auth.password`（或 `OPENCLAW_GATEWAY_PASSWORD`）。 - - 如果 `gateway.auth.token` / `gateway.auth.password` 通过 SecretRef 显式配置但无法解析，解析会以安全关闭方式失败（不会由远程回退掩盖）。 - - 共享密钥 Control UI 设置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在应用/UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的身份携带模式则改用请求头。避免将共享密钥放入 URL 中。 - - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机的 loopback 反向代理**仍然不能**满足 trusted-proxy 认证要求。受信任代理必须是已配置的非 loopback 来源。 + - 如果通过 SecretRef 显式配置了 `gateway.auth.token` / `gateway.auth.password` 但无法解析，则解析会以关闭方式失败（不会被远程回退掩盖）。 + - shared-secret Control UI 配置通过 `connect.params.auth.token` 或 `connect.params.auth.password` 进行认证（存储在 app/UI 设置中）。像 Tailscale Serve 或 `trusted-proxy` 这样的带身份模式则改用请求头。避免将 shared secrets 放入 URL。 + - 使用 `gateway.auth.mode: "trusted-proxy"` 时，同主机的 loopback 反向代理仍然**不能**满足 trusted-proxy 认证。trusted proxy 必须是已配置的非 loopback 来源。 - - OpenClaw 默认强制启用 gateway 认证，包括 loopback。在正常默认路径下，这意味着 token 认证：如果没有配置显式认证路径，gateway 启动时会解析为 token 模式并自动生成一个 token，将其保存到 `gateway.auth.token`，因此**本地 WS 客户端也必须认证**。这样可以阻止其他本地进程调用 Gateway 网关。 + + OpenClaw 默认强制启用 gateway 认证，包括 loopback。在正常默认路径中，这意味着 token 认证：如果没有配置显式认证路径，gateway 启动时会解析为 token 模式并自动生成一个 token，将其保存到 `gateway.auth.token`，因此**本地 WS 客户端必须进行认证**。这样可以阻止其他本地进程调用 Gateway 网关。 - 如果你更倾向于其他认证方式，可以显式选择 password 模式（或者，对于非 loopback 的身份感知反向代理，可使用 `trusted-proxy`）。如果你**确实**想使用开放的 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 随时都可以为你生成 token：`openclaw doctor --generate-gateway-token`。 + 如果你希望使用其他认证路径，可以显式选择 password 模式（或者，对于非 loopback 的身份感知反向代理，使用 `trusted-proxy`）。如果你**确实**想要开放的 loopback，请在配置中显式设置 `gateway.auth.mode: "none"`。Doctor 可以随时为你生成 token：`openclaw doctor --generate-gateway-token`。 - + Gateway 网关会监视配置并支持热重载： - - `gateway.reload.mode: "hybrid"`（默认）：安全变更热应用，关键变更重启 + - `gateway.reload.mode: "hybrid"`（默认）：安全变更热应用，关键变更则重启 - 也支持 `hot`、`restart`、`off` - + 在配置中设置 `cli.banner.taglineMode`： ```json5 @@ -730,21 +729,21 @@ x-i18n: - `off`：隐藏标语文本，但保留横幅标题/版本行。 - `default`：每次都使用 `All your chats, one OpenClaw.`。 - - `random`：轮换有趣/季节性标语（默认行为）。 - - 如果你完全不想显示横幅，可设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 + - `random`：轮换显示有趣/季节性标语（默认行为）。 + - 如果你希望完全不显示横幅，请设置环境变量 `OPENCLAW_HIDE_BANNER=1`。 - - `web_fetch` 无需 API 密钥即可工作。`web_search` 取决于你所选的 - 提供商： + + `web_fetch` 无需 API 密钥即可使用。`web_search` 取决于你选择的 + provider： - - 依赖 API 的提供商，如 Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily，需要按其常规方式配置 API 密钥。 - - Ollama Web 搜索 不需要密钥，但它会使用你配置的 Ollama 主机，并且需要 `ollama signin`。 - - DuckDuckGo 不需要密钥，但它是一个基于 HTML 的非官方集成。 - - SearXNG 不需要密钥/可自托管；请配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 + - Brave、Exa、Firecrawl、Gemini、Grok、Kimi、MiniMax Search、Perplexity 和 Tavily 等基于 API 的 provider 需要正常配置对应 API 密钥。 + - Ollama Web 搜索无需密钥，但它使用你配置的 Ollama 主机，并需要执行 `ollama signin`。 + - DuckDuckGo 无需密钥，但它是基于 HTML 的非官方集成。 + - SearXNG 无需密钥/可自托管；配置 `SEARXNG_BASE_URL` 或 `plugins.entries.searxng.config.webSearch.baseUrl`。 - **推荐：** 运行 `openclaw configure --section web` 并选择一个提供商。 + **推荐：** 运行 `openclaw configure --section web` 并选择一个 provider。 环境变量替代方案： - Brave：`BRAVE_API_KEY` @@ -780,75 +779,75 @@ x-i18n: }, fetch: { enabled: true, - provider: "firecrawl", // 可选；省略时自动检测 + provider: "firecrawl", // 可选；省略则自动检测 }, }, }, } ``` - 提供商专用的网页搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 - 为了兼容，旧版 `tools.web.search.*` 提供商路径仍会暂时加载，但新配置不应继续使用它们。 - Firecrawl 的网页抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 + provider 专属的 Web 搜索配置现在位于 `plugins.entries..config.webSearch.*` 下。 + 旧版 `tools.web.search.*` provider 路径目前仍会临时加载以保持兼容，但不应再用于新配置。 + Firecrawl 的 Web 抓取回退配置位于 `plugins.entries.firecrawl.config.webFetch.*` 下。 - 注意事项： + 说明： - - 如果你使用 allowlist，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 - - `web_fetch` 默认启用（除非显式禁用）。 - - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个已就绪的抓取回退提供商。目前内置提供商是 Firecrawl。 - - 守护进程会从 `~/.openclaw/.env`（或服务环境）读取环境变量。 + - 如果你使用允许列表，请添加 `web_search`/`web_fetch`/`x_search` 或 `group:web`。 + - `web_fetch` 默认启用（除非你显式禁用）。 + - 如果省略 `tools.web.fetch.provider`，OpenClaw 会从可用凭证中自动检测第一个已就绪的抓取回退 provider。当前内置 provider 是 Firecrawl。 + - 守护进程从 `~/.openclaw/.env`（或服务环境）读取环境变量。 文档： [Web tools](/zh-CN/tools/web)。 - - `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其他所有内容 + + `config.apply` 会替换**整个配置**。如果你发送的是部分对象，其余所有内容 都会被移除。 - 当前的 OpenClaw 会防止许多意外覆盖： + 当前 OpenClaw 会防护许多意外覆盖： - - OpenClaw 自身发起的配置写入会在写入前验证变更后的完整配置。 - - 无效或具有破坏性的 OpenClaw 自身写入会被拒绝，并保存为 `openclaw.json.rejected.*`。 - - 如果直接编辑导致启动或热重载失败，Gateway 网关会恢复最后一个已知良好配置，并将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 + - OpenClaw 自有的配置写入会在写入前校验完整的变更后配置。 + - 无效或破坏性的 OpenClaw 自有写入会被拒绝，并保存为 `openclaw.json.rejected.*`。 + - 如果直接编辑导致启动或热重载失败，Gateway 网关会恢复最后一个已知良好的配置，并将被拒绝的文件保存为 `openclaw.json.clobbered.*`。 - 恢复后，主智能体会收到启动警告，以避免它再次盲目写入错误配置。 恢复方法： - - 检查 `openclaw logs --follow` 中的 `Config auto-restored from last-known-good`、`Config write rejected:` 或 `config reload restored last-known-good config`。 + - 检查 `openclaw logs --follow` 中是否有 `Config auto-restored from last-known-good`、`Config write rejected:` 或 `config reload restored last-known-good config`。 - 检查活动配置旁边最新的 `openclaw.json.clobbered.*` 或 `openclaw.json.rejected.*`。 - - 如果当前已恢复的活动配置可以正常工作，就保留它，然后仅通过 `openclaw config set` 或 `config.patch` 把你原本想改的键复制回去。 + - 如果恢复后的活动配置可用，就保留它，然后仅通过 `openclaw config set` 或 `config.patch` 复制回你原本想要的键。 - 运行 `openclaw config validate` 和 `openclaw doctor`。 - - 如果你没有最后一个已知良好配置或被拒绝的有效负载，请从备份恢复，或重新运行 `openclaw doctor` 并重新配置渠道/模型。 - - 如果这是意料之外的情况，请提交 bug，并附上你最后已知的配置或任何备份。 - - 本地编码智能体通常也能根据日志或历史记录重建一个可工作的配置。 + - 如果你没有 last-known-good 或被拒绝的负载，请从备份恢复，或重新运行 `openclaw doctor` 并重新配置渠道/模型。 + - 如果这属于意外情况，请提交 bug，并附上你最后已知的配置或任何备份。 + - 本地编码智能体通常可以根据日志或历史记录重建可用配置。 - 避免方式： + 避免方法： - - 小改动请使用 `openclaw config set`。 - - 交互式编辑请使用 `openclaw configure`。 - - 如果你不确定准确路径或字段形状，请先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及直接子项摘要，便于逐层深入。 - - 局部 RPC 编辑请使用 `config.patch`；仅在需要完整替换配置时才使用 `config.apply`。 - - 如果你是在智能体运行中使用仅限所有者的 `gateway` 工具，它仍会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化到相同受保护 exec 路径的旧版 `tools.bash.*` 别名）。 + - 对小改动使用 `openclaw config set`。 + - 交互式编辑使用 `openclaw configure`。 + - 如果你不确定精确路径或字段形状，请先使用 `config.schema.lookup`；它会返回一个浅层 schema 节点以及直接子项摘要，便于逐层深入。 + - 对部分 RPC 编辑使用 `config.patch`；仅在需要完整替换配置时使用 `config.apply`。 + - 如果你在智能体运行中使用仅限 owner 的 `gateway` 工具，它仍然会拒绝写入 `tools.exec.ask` / `tools.exec.security`（包括会规范化为同一受保护 exec 路径的旧版 `tools.bash.*` 别名）。 文档： [配置](/zh-CN/cli/config)、[Configure](/zh-CN/cli/configure)、[Gateway 网关故障排除](/zh-CN/gateway/troubleshooting#gateway-restored-last-known-good-config)、[Doctor](/zh-CN/gateway/doctor)。 - + 常见模式是**一个 Gateway 网关**（例如 Raspberry Pi）加上**节点**和**智能体**： - - **Gateway 网关（中心）：** 持有渠道（Signal/WhatsApp）、路由和会话。 + - **Gateway 网关（中央）：** 负责渠道（Signal/WhatsApp）、路由和会话。 - **节点（设备）：** Mac/iOS/Android 作为外设连接，并暴露本地工具（`system.run`、`canvas`、`camera`）。 - - **智能体（工作节点）：** 为特定角色提供独立的大脑/工作区（例如“Hetzner 运维”“个人数据”）。 - - **子智能体：** 当你需要并行工作时，从主智能体生成后台任务。 - - **TUI：** 连接到 Gateway 网关，并切换智能体/会话。 + - **智能体（工作节点）：** 为特定角色提供独立的大脑/工作区（例如 “Hetzner 运维”、“个人数据”）。 + - **子智能体：** 当你需要并行处理时，从主智能体生成后台工作。 + - **TUI：** 连接到 Gateway 网关并切换智能体/会话。 文档： [Nodes](/zh-CN/nodes)、[Remote access](/zh-CN/gateway/remote)、[Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[TUI](/zh-CN/web/tui)。 - + 可以。这是一个配置选项： ```json5 @@ -862,47 +861,46 @@ x-i18n: } ``` - 默认值为 `false`（有界面模式）。在某些网站上，无头模式更容易触发反机器人检查。参见 [Browser](/zh-CN/tools/browser)。 + 默认值为 `false`（有头模式）。在某些网站上，headless 更容易触发反机器人检查。请参阅 [Browser](/zh-CN/tools/browser)。 - 无头模式使用**相同的 Chromium 引擎**，适用于大多数自动化任务（表单、点击、抓取、登录）。主要区别在于： + Headless 使用**相同的 Chromium 引擎**，适用于大多数自动化任务（表单、点击、抓取、登录）。主要区别是： - - 没有可见的浏览器窗口（如果你需要可视内容，可使用截图）。 - - 某些网站在无头模式下对自动化更严格（CAPTCHA、反机器人）。 - 例如，X/Twitter 经常会阻止无头会话。 + - 没有可见的浏览器窗口（如果你需要可视化，请使用截图）。 + - 有些网站在 headless 模式下对自动化更严格（CAPTCHA、反机器人）。 + 例如，X/Twitter 经常会拦截 headless 会话。 将 `browser.executablePath` 设置为你的 Brave 二进制文件（或任何基于 Chromium 的浏览器），然后重启 Gateway 网关。 - 完整配置示例请参见 [Browser](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 + 完整配置示例请参阅 [Browser](/zh-CN/tools/browser#use-brave-or-another-chromium-based-browser)。 ## 远程 Gateway 网关与节点 - - Telegram 消息由 **gateway** 处理。gateway 运行智能体， - 然后仅在需要节点工具时，才通过 **Gateway WebSocket** - 调用节点： + + Telegram 消息由 **Gateway 网关** 处理。Gateway 网关运行智能体， + 只有在需要节点工具时，才会通过 **Gateway WebSocket** 调用节点： - Telegram → Gateway → 智能体 → `node.*` → 节点 → Gateway → Telegram + Telegram → Gateway 网关 → 智能体 → `node.*` → 节点 → Gateway 网关 → Telegram - 节点看不到入站提供商流量；它们只接收节点 RPC 调用。 + 节点不会看到入站 provider 流量；它们只会接收节点 RPC 调用。 - + 简短回答：**把你的电脑配对为一个节点**。Gateway 网关运行在别处，但它可以 - 通过 Gateway WebSocket 调用你本地机器上的 `node.*` 工具（屏幕、摄像头、system）。 + 通过 Gateway WebSocket 在你的本地机器上调用 `node.*` 工具（屏幕、摄像头、系统）。 典型设置： - 1. 在始终在线的主机（VPS/家庭服务器）上运行 Gateway 网关。 - 2. 将 Gateway 网关主机和你的电脑放到同一个 tailnet 中。 - 3. 确保 Gateway WS 可达（tailnet 绑定或 SSH 隧道）。 - 4. 在本地打开 macOS 应用，并以 **Remote over SSH** 模式（或直接 tailnet） - 连接，以便它注册为一个节点。 + 1. 在常开主机上运行 Gateway 网关（VPS/家庭服务器）。 + 2. 将 Gateway 网关主机和你的电脑加入同一个 tailnet。 + 3. 确保 Gateway 网关 WS 可达（tailnet 绑定或 SSH 隧道）。 + 4. 在本地打开 macOS 应用，并以**通过 SSH 远程连接**模式（或直接 tailnet） + 连接，以便它可以注册为一个节点。 5. 在 Gateway 网关上批准该节点： ```bash @@ -912,77 +910,78 @@ x-i18n: 不需要单独的 TCP bridge；节点通过 Gateway WebSocket 连接。 - 安全提醒：配对 macOS 节点意味着允许在该机器上执行 `system.run`。只应 - 配对你信任的设备，并阅读[安全](/zh-CN/gateway/security)。 + 安全提醒：配对 macOS 节点意味着该机器允许执行 `system.run`。只 + 配对你信任的设备，并查看 [Security](/zh-CN/gateway/security)。 - 文档： [Nodes](/zh-CN/nodes)、[Gateway 网关协议](/zh-CN/gateway/protocol)、[macOS 远程模式](/zh-CN/platforms/mac/remote)、[安全](/zh-CN/gateway/security)。 + 文档： [Nodes](/zh-CN/nodes)、[Gateway protocol](/zh-CN/gateway/protocol)、[macOS remote mode](/zh-CN/platforms/mac/remote)、[Security](/zh-CN/gateway/security)。 - + 先检查基础项： - - Gateway 网关是否正在运行：`openclaw gateway status` + - Gateway 网关正在运行：`openclaw gateway status` - Gateway 网关健康状态：`openclaw status` - 渠道健康状态：`openclaw channels status` 然后验证认证和路由： - - 如果你使用 Tailscale Serve，请确保 `gateway.auth.allowTailscale` 设置正确。 - - 如果你通过 SSH 隧道连接，请确认本地隧道已启动并指向正确端口。 - - 确认你的 allowlist（私信或群组）包含你的账户。 + - 如果你使用 Tailscale Serve，请确认 `gateway.auth.allowTailscale` 已正确设置。 + - 如果你通过 SSH 隧道连接，请确认本地隧道已建立并指向正确端口。 + - 确认你的允许列表（私信或群组）包含你的账号。 文档： [Tailscale](/zh-CN/gateway/tailscale)、[Remote access](/zh-CN/gateway/remote)、[Channels](/zh-CN/channels)。 - - 可以。没有内置的“bot 到 bot”桥接，但你可以通过几种 - 可靠方式把它连起来： + + 可以。虽然没有内置的“机器人到机器人”桥接，但你可以通过几种 + 可靠方式将其连接起来： - **最简单的方式：** 使用两个 bot 都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 - 让 Bot A 向 Bot B 发送消息，然后让 Bot B 正常回复。 + **最简单：** 使用两个机器人都能访问的普通聊天渠道（Telegram/Slack/WhatsApp）。 + 让 Bot A 向 Bot B 发送消息，然后让 Bot B 像平常一样回复。 - **CLI bridge（通用）：** 运行一个脚本，通过 - `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，并将目标指定为另一个 bot - 正在监听的聊天。如果其中一个 bot 位于远程 VPS 上，可让你的 CLI 指向该远程 Gateway 网关， - 通过 SSH/Tailscale 访问（参见 [Remote access](/zh-CN/gateway/remote)）。 + **CLI 桥接（通用）：** 运行一个脚本，通过 + `openclaw agent --message ... --deliver` 调用另一个 Gateway 网关，并将目标指向另一个机器人 + 监听的聊天。如果其中一个机器人运行在远程 VPS 上，请将你的 CLI 指向那个远程 Gateway 网关， + 可通过 SSH/Tailscale（参见 [Remote access](/zh-CN/gateway/remote)）。 - 示例模式（在能够访问目标 Gateway 网关的机器上运行）： + 示例模式（在一台可访问目标 Gateway 网关的机器上运行）： ```bash - openclaw agent --message "来自本地 bot 的问候" --deliver --channel telegram --reply-to + openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - 提示：添加一个护栏，避免两个 bot 无休止地循环回复（仅在被提及时回复、使用渠道 - allowlist，或设置“不要回复 bot 消息”的规则）。 + 提示：添加一个护栏，以避免两个机器人无限循环（仅在提及时回复、渠道 + 允许列表，或“不要回复机器人消息”的规则）。 文档： [Remote access](/zh-CN/gateway/remote)、[Agent CLI](/zh-CN/cli/agent)、[Agent send](/zh-CN/tools/agent-send)。 - 不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、默认模型 - 和路由。这是常规设置，比为每个智能体运行 + 不需要。一个 Gateway 网关可以托管多个智能体，每个智能体都有自己的工作区、模型默认值 + 和路由。这是标准设置，比为每个智能体分别运行 一个 VPS 更便宜也更简单。 - 只有在你需要硬隔离（安全边界）或完全不同且不想共享的配置时，才需要使用多个 VPS。否则，请保留一个 Gateway 网关， - 并使用多个智能体或子智能体。 + 只有在你需要硬隔离（安全边界）或非常 + 不同且不想共享的配置时，才需要使用独立 VPS。否则，保留一个 Gateway 网关， + 并使用多个智能体或子智能体即可。 - - 有——节点是从远程 Gateway 网关访问你笔记本的首选方式，而且 - 它提供的不只是 shell 访问。Gateway 网关运行在 macOS/Linux（Windows 通过 WSL2）上， - 资源占用很轻（小型 VPS 或 Raspberry Pi 级设备即可；4 GB 内存已足够），因此一种常见 - 设置是始终在线的主机加上你的笔记本作为节点。 + + 有——节点是从远程 Gateway 网关访问你笔记本的一级方式，而且 + 它提供的不仅仅是 shell 访问。Gateway 网关运行在 macOS/Linux 上（Windows 通过 WSL2），并且 + 很轻量（小型 VPS 或 Raspberry Pi 级设备就足够；4 GB RAM 已很充裕），因此一种常见 + 配置是使用一个始终在线的主机，再将你的笔记本作为一个节点。 - **无需入站 SSH。** 节点会主动连接到 Gateway WebSocket，并使用设备配对。 - - **更安全的执行控制。** `system.run` 在该笔记本上受节点 allowlist/审批控制。 - - **更多设备工具。** 除了 `system.run` 之外，节点还会暴露 `canvas`、`camera` 和 `screen`。 - - **本地浏览器自动化。** 将 Gateway 网关保留在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或者通过 Chrome MCP 连接到主机上的本地 Chrome。 + - **更安全的执行控制。** `system.run` 在该笔记本上受到节点允许列表/审批机制保护。 + - **更多设备工具。** 除了 `system.run` 之外，节点还暴露 `canvas`、`camera` 和 `screen`。 + - **本地浏览器自动化。** 保持 Gateway 网关运行在 VPS 上，但通过笔记本上的节点主机在本地运行 Chrome，或者通过 Chrome MCP 连接到主机上的本地 Chrome。 - SSH 适合临时 shell 访问，但对于持续性的智能体工作流和 + 对于临时 shell 访问，SSH 没问题，但对于持续性的智能体工作流和 设备自动化，节点更简单。 文档： [Nodes](/zh-CN/nodes)、[Nodes CLI](/zh-CN/cli/nodes)、[Browser](/zh-CN/tools/browser)。 @@ -990,26 +989,26 @@ x-i18n: - 不会。每台主机上通常只应运行**一个 gateway**，除非你有意运行隔离的配置文件（参见 [Multiple gateways](/zh-CN/gateway/multiple-gateways)）。节点是连接到 - gateway 的外设（iOS/Android 节点，或菜单栏应用中的 macOS“节点模式”）。有关无头节点 - 主机和 CLI 控制，请参见 [Node host CLI](/zh-CN/cli/node)。 + 不会。每台主机上通常应只运行**一个 gateway**，除非你有意运行隔离配置文件（参见 [Multiple gateways](/zh-CN/gateway/multiple-gateways)）。节点是连接到 + gateway 的外设（iOS/Android 节点，或菜单栏应用中的 macOS “node mode”）。关于无头节点 + 主机和 CLI 控制，请参阅 [Node host CLI](/zh-CN/cli/node)。 - `gateway`、`discovery` 和 `canvasHost` 的变更需要完全重启。 + 修改 `gateway`、`discovery` 和 `canvasHost` 后需要完整重启。 有。 - - `config.schema.lookup`：在写入前检查某个配置子树及其浅层 schema 节点、匹配的 UI 提示和直接子项摘要 + - `config.schema.lookup`：在写入前检查某个配置子树，包括其浅层 schema 节点、匹配到的 UI 提示以及直接子项摘要 - `config.get`：获取当前快照 + hash - - `config.patch`：安全的局部更新（大多数 RPC 编辑的首选）；在可能时热重载，必要时重启 - - `config.apply`：验证并替换完整配置；在可能时热重载，必要时重启 - - 仅限所有者的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化到相同的受保护 exec 路径 + - `config.patch`：安全的部分更新（大多数 RPC 编辑推荐使用）；可热重载时热重载，必要时重启 + - `config.apply`：校验并替换完整配置；可热重载时热重载，必要时重启 + - 仅限 owner 的 `gateway` 运行时工具仍然拒绝重写 `tools.exec.ask` / `tools.exec.security`；旧版 `tools.bash.*` 别名会规范化为相同的受保护 exec 路径 - + ```json5 { agents: { defaults: { workspace: "~/.openclaw/workspace" } }, @@ -1017,12 +1016,12 @@ x-i18n: } ``` - 这会设置你的工作区，并限制哪些人可以触发 bot。 + 这样会设置你的工作区，并限制哪些人可以触发机器人。 - 最简步骤： + 最小步骤如下： 1. **在 VPS 上安装并登录** @@ -1032,31 +1031,31 @@ x-i18n: ``` 2. **在你的 Mac 上安装并登录** - - 使用 Tailscale 应用，并登录到同一个 tailnet。 + - 使用 Tailscale 应用并登录到同一个 tailnet。 3. **启用 MagicDNS（推荐）** - - 在 Tailscale 管理控制台中启用 MagicDNS，这样 VPS 会有一个稳定名称。 + - 在 Tailscale 管理控制台中启用 MagicDNS，让 VPS 拥有稳定名称。 4. **使用 tailnet 主机名** - SSH：`ssh user@your-vps.tailnet-xxxx.ts.net` - - Gateway WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` + - Gateway 网关 WS：`ws://your-vps.tailnet-xxxx.ts.net:18789` - 如果你想在不使用 SSH 的情况下访问 Control UI，请在 VPS 上使用 Tailscale Serve： + 如果你希望在不使用 SSH 的情况下使用 Control UI，请在 VPS 上使用 Tailscale Serve： ```bash openclaw gateway --tailscale serve ``` - 这样会让 gateway 保持绑定到 loopback，并通过 Tailscale 暴露 HTTPS。参见 [Tailscale](/zh-CN/gateway/tailscale)。 + 这会让 gateway 保持绑定在 loopback 上，并通过 Tailscale 暴露 HTTPS。请参阅 [Tailscale](/zh-CN/gateway/tailscale)。 - + Serve 会暴露 **Gateway 网关 Control UI + WS**。节点通过同一个 Gateway WS 端点连接。 推荐设置： 1. **确保 VPS 和 Mac 位于同一个 tailnet 中**。 - 2. **在 macOS 应用中使用 Remote 模式**（SSH 目标可以是 tailnet 主机名）。 - 应用会为 Gateway 端口建立隧道，并作为节点连接。 + 2. **在 Remote 模式下使用 macOS 应用**（SSH 目标可以是 tailnet 主机名）。 + 该应用会隧道转发 Gateway 网关端口，并以节点身份连接。 3. **在 gateway 上批准该节点**： ```bash @@ -1064,34 +1063,34 @@ x-i18n: openclaw devices approve ``` - 文档： [Gateway 网关协议](/zh-CN/gateway/protocol)、[Discovery](/zh-CN/gateway/discovery)、[macOS 远程模式](/zh-CN/platforms/mac/remote)。 + 文档： [Gateway protocol](/zh-CN/gateway/protocol)、[设备发现](/zh-CN/gateway/discovery)、[macOS remote mode](/zh-CN/platforms/mac/remote)。 - - 如果你只需要在第二台笔记本上使用**本地工具**（screen/camera/exec），就把它添加为一个 - **节点**。这样可以保留单一 Gateway 网关，避免重复配置。本地节点工具 - 当前仅支持 macOS，但我们计划将其扩展到其他操作系统。 + + 如果你只需要第二台笔记本上的**本地工具**（屏幕/摄像头/执行），就把它添加为一个 + **节点**。这样可以保持单一 Gateway 网关，并避免重复配置。本地节点工具 + 当前仅支持 macOS，但我们计划扩展到其他操作系统。 - 只有当你需要**硬隔离**或两个完全独立的 bot 时，才安装第二个 Gateway 网关。 + 只有当你需要**硬隔离**或两个完全独立的机器人时，才安装第二个 Gateway 网关。 文档： [Nodes](/zh-CN/nodes)、[Nodes CLI](/zh-CN/cli/nodes)、[Multiple gateways](/zh-CN/gateway/multiple-gateways)。 -## 环境变量与 .env 加载 +## 环境变量和 `.env` 加载 OpenClaw 会从父进程（shell、launchd/systemd、CI 等）读取环境变量，并额外加载： - 当前工作目录中的 `.env` - - 来自 `~/.openclaw/.env`（也就是 `$OPENCLAW_STATE_DIR/.env`）的全局回退 `.env` + - 来自 `~/.openclaw/.env`（即 `$OPENCLAW_STATE_DIR/.env`）的全局回退 `.env` - 这两个 `.env` 文件都不会覆盖现有环境变量。 + 两个 `.env` 文件都不会覆盖已有的环境变量。 - 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时才应用）： + 你也可以在配置中定义内联环境变量（仅在进程环境中缺失时应用）： ```json5 { @@ -1102,15 +1101,15 @@ x-i18n: } ``` - 完整优先级和来源请参见 [/environment](/zh-CN/help/environment)。 + 完整优先级和来源请参阅 [/environment](/zh-CN/help/environment)。 - - 两种常见修复方式： + + 常见的两种修复方式： - 1. 把缺失的键放到 `~/.openclaw/.env` 中，这样即使服务没有继承你的 shell 环境，也能读取到。 - 2. 启用 shell 导入（可选的便利功能）： + 1. 将缺失的键放入 `~/.openclaw/.env`，这样即使服务没有继承你的 shell 环境，也会被读取。 + 2. 启用 shell 导入（可选便捷功能）： ```json5 { @@ -1123,36 +1122,36 @@ x-i18n: } ``` - 这会运行你的登录 shell，并且只导入缺失的预期键名（绝不覆盖现有值）。对应的环境变量： + 这会运行你的登录 shell，并且只导入缺失的预期键名（绝不覆盖）。对应的环境变量为： `OPENCLAW_LOAD_SHELL_ENV=1`、`OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`。 - `openclaw models status` 报告的是**shell 环境导入**是否启用。“Shell env: off” - **并不**表示你的环境变量缺失——它只是表示 OpenClaw 不会 + `openclaw models status` 报告的是**shell 环境导入**是否已启用。“Shell env: off” + **并不**表示你的环境变量丢失了——它只表示 OpenClaw 不会 自动加载你的登录 shell。 如果 Gateway 网关作为服务运行（launchd/systemd），它不会继承你的 shell 环境。可通过以下任一方式修复： - 1. 将令牌放入 `~/.openclaw/.env`： + 1. 将 token 放入 `~/.openclaw/.env`： ``` COPILOT_GITHUB_TOKEN=... ``` 2. 或启用 shell 导入（`env.shellEnv.enabled: true`）。 - 3. 或将其添加到你的配置 `env` 块中（仅在缺失时应用）。 + 3. 或将它添加到配置中的 `env` 块（仅在缺失时应用）。 - 然后重启 gateway 并重新检查： + 然后重启 gateway 并再次检查： ```bash openclaw models status ``` - Copilot 令牌从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 - 参见 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 + Copilot token 从 `COPILOT_GITHUB_TOKEN` 读取（也支持 `GH_TOKEN` / `GITHUB_TOKEN`）。 + 请参阅 [/concepts/model-providers](/zh-CN/concepts/model-providers) 和 [/environment](/zh-CN/help/environment)。 @@ -1161,14 +1160,14 @@ x-i18n: - 发送 `/new` 或 `/reset` 作为单独消息。参见 [Session management](/zh-CN/concepts/session)。 + 发送 `/new` 或 `/reset` 作为独立消息。请参阅 [Session management](/zh-CN/concepts/session)。 - 会话可以在 `session.idleMinutes` 之后过期，但这**默认是关闭的**（默认值为 **0**）。 - 将其设置为正值即可启用空闲过期。启用后，空闲期之后的**下一条** - 消息会为该聊天键启动一个新的会话 ID。 - 这不会删除记录——它只是开始一个新会话。 + 会话可以在 `session.idleMinutes` 之后过期，但这**默认是禁用的**（默认值为 **0**）。 + 将其设置为正数即可启用空闲过期。启用后，空闲期之后的**下一条** + 消息会为该聊天键启动一个全新的会话 ID。 + 这不会删除转录记录——它只是开始一个新会话。 ```json5 { @@ -1180,41 +1179,41 @@ x-i18n: - - 有，可以通过**多智能体路由**和**子智能体**实现。你可以创建一个协调者 + + 可以，通过**多智能体路由**和**子智能体**实现。你可以创建一个协调者 智能体，以及多个拥有各自工作区和模型的工作智能体。 - 不过，这最好被视为一种**有趣的实验**。它会消耗很多令牌，而且通常 - 不如使用一个 bot 搭配多个独立会话高效。我们通常设想的模型是： - 一个你与之交互的 bot，加上多个会话用于并行工作。该 - bot 也可以在需要时生成子智能体。 + 不过，最好把这看作一种**有趣的实验**。它会消耗大量令牌，而且通常 + 不如使用一个机器人配合多个独立会话高效。我们设想的典型模式 + 是你与一个机器人交谈，并通过不同会话进行并行工作。该 + 机器人也可以在需要时启动子智能体。 - 文档： [Multi-agent routing](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[Agents CLI](/zh-CN/cli/agents)。 + 文档： [多智能体路由](/zh-CN/concepts/multi-agent)、[Sub-agents](/zh-CN/tools/subagents)、[Agents CLI](/zh-CN/cli/agents)。 - + 会话上下文受模型窗口限制。长聊天、大量工具输出或很多 文件都可能触发压缩或截断。 有帮助的做法： - - 让 bot 总结当前状态并将其写入文件。 + - 让机器人总结当前状态并写入文件。 - 在长任务前使用 `/compact`，切换主题时使用 `/new`。 - - 将重要上下文保存在工作区中，并让 bot 重新读取它。 - - 对长时间或并行工作使用子智能体，让主聊天保持更小。 - - 如果这种情况经常发生，请选择上下文窗口更大的模型。 + - 将重要上下文保存在工作区中，并让机器人重新读取。 + - 对长任务或并行工作使用子智能体，这样主聊天可以保持更小。 + - 如果这种情况经常发生，选择上下文窗口更大的模型。 - + 使用 reset 命令： ```bash openclaw reset ``` - 非交互式完整重置： + 非交互式完全重置： ```bash openclaw reset --scope full --yes --non-interactive @@ -1226,15 +1225,15 @@ x-i18n: openclaw onboard --install-daemon ``` - 注意事项： + 说明： - - 如果检测到已有配置，新手引导也会提供**重置**选项。参见 [新手引导（CLI）](/zh-CN/start/wizard)。 - - 如果你使用了 profiles（`--profile` / `OPENCLAW_PROFILE`），请分别重置每个状态目录（默认是 `~/.openclaw-`）。 - - 开发重置：`openclaw gateway --dev --reset`（仅开发用途；会清除开发配置 + 凭证 + 会话 + 工作区）。 + - 如果新手引导检测到现有配置，也会提供 **Reset**。请参阅 [新手引导（CLI）](/zh-CN/start/wizard)。 + - 如果你使用了 profiles（`--profile` / `OPENCLAW_PROFILE`），请重置每个状态目录（默认是 `~/.openclaw-`）。 + - 开发重置：`openclaw gateway --dev --reset`（仅开发模式；会清空开发配置 + 凭证 + 会话 + 工作区）。 - + 使用以下任一方式： - **压缩**（保留对话，但总结较早的轮次）： @@ -1243,9 +1242,9 @@ x-i18n: /compact ``` - 或使用 `/compact ` 来指导摘要内容。 + 或使用 `/compact ` 来引导摘要内容。 - - **重置**（为同一聊天键启动新的会话 ID）： + - **重置**（为同一聊天键创建新的会话 ID）： ``` /new @@ -1254,50 +1253,50 @@ x-i18n: 如果这种情况持续发生： - - 启用或调整**会话裁剪**（`agents.defaults.contextPruning`）以裁剪旧的工具输出。 + - 启用或调优**会话修剪**（`agents.defaults.contextPruning`）以裁剪旧的工具输出。 - 使用上下文窗口更大的模型。 文档： [Compaction](/zh-CN/concepts/compaction)、[Session pruning](/zh-CN/concepts/session-pruning)、[Session management](/zh-CN/concepts/session)。 - - 这是提供商验证错误：模型发出了一个缺少必需 - `input` 的 `tool_use` 块。通常意味着会话历史已过期或损坏（常见于长线程 + + 这是 provider 校验错误：模型发出了一个 `tool_use` 块，但缺少必需的 + `input`。这通常意味着会话历史已过期或损坏（常见于长线程 或工具/schema 变更之后）。 - 修复方式：发送 `/new`（单独消息）以开始一个新会话。 + 修复方法：使用 `/new`（独立消息）开始一个全新的会话。 - heartbeat 默认每 **30 分钟** 运行一次（使用 OAuth 认证时为 **1 小时**）。你可以调整或禁用它： + heartbeat 默认每 **30m** 运行一次（使用 OAuth 认证时为 **1h**）。你可以调整或禁用它： ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // 或设为 "0m" 以禁用 + every: "2h", // 或 "0m" 以禁用 }, }, }, } ``` - 如果 `HEARTBEAT.md` 存在但实际上为空（只有空行和 Markdown - 标题，如 `# Heading`），OpenClaw 会跳过 heartbeat 运行，以节省 API 调用。 - 如果文件缺失，heartbeat 仍会运行，并由模型决定该做什么。 + 如果 `HEARTBEAT.md` 存在，但实际上是空的（只有空行和 markdown + 标题，如 `# Heading`），OpenClaw 会跳过 heartbeat 运行以节省 API 调用。 + 如果该文件不存在，heartbeat 仍会运行，并由模型决定要做什么。 - 按智能体覆盖请使用 `agents.list[].heartbeat`。文档： [Heartbeat](/zh-CN/gateway/heartbeat)。 + 每个智能体的覆盖使用 `agents.list[].heartbeat`。文档： [Heartbeat](/zh-CN/gateway/heartbeat)。 - - 不需要。OpenClaw 运行在**你自己的账号**上，所以只要你在群组里，OpenClaw 就能看到它。 + + 不需要。OpenClaw 运行在**你自己的账号**上，所以只要你在群里，OpenClaw 就能看到它。 默认情况下，在你允许发送者之前，群组回复会被阻止（`groupPolicy: "allowlist"`）。 - 如果你希望只有**你自己**能够触发群组回复： + 如果你希望只有**你自己**可以触发群组回复： ```json5 { @@ -1313,7 +1312,7 @@ x-i18n: - 选项 1（最快）：跟踪日志，然后在群组中发送一条测试消息： + 方式 1（最快）：查看日志并在群里发送一条测试消息： ```bash openclaw logs --follow --json @@ -1322,7 +1321,7 @@ x-i18n: 查找以 `@g.us` 结尾的 `chatId`（或 `from`），例如： `1234567890-1234567890@g.us`。 - 选项 2（如果已经配置/加入 allowlist）：从配置中列出群组： + 方式 2（如果已经配置/加入允许列表）：从配置中列出群组： ```bash openclaw directory groups list --channel whatsapp @@ -1335,38 +1334,38 @@ x-i18n: 两个常见原因： - - 提及门控已开启（默认）。你必须 @提及 bot（或匹配 `mentionPatterns`）。 - - 你配置了 `channels.whatsapp.groups` 但没有包含 `"*"`，而且该群组不在 allowlist 中。 + - 提及门控已开启（默认）。你必须 @ 提及机器人（或匹配 `mentionPatterns`）。 + - 你配置了 `channels.whatsapp.groups` 但没有 `"*"`，而该群组不在允许列表中。 - 参见 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + 请参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 - 默认情况下，直接聊天会合并到主会话。群组/渠道拥有各自的会话键，而 Telegram topic / Discord thread 则是独立会话。参见 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 + 直接聊天默认会折叠到主会话。群组/渠道有各自独立的会话键，而 Telegram 话题 / Discord 线程也是独立会话。请参阅 [Groups](/zh-CN/channels/groups) 和 [Group messages](/zh-CN/channels/group-messages)。 - 没有硬性限制。几十个（甚至几百个）都没问题，但请注意： + 没有硬性限制。几十个（甚至几百个）都没问题，但要注意： - - **磁盘增长：** 会话 + 记录保存在 `~/.openclaw/agents//sessions/` 下。 - - **令牌成本：** 智能体越多，并发模型使用越多。 - - **运维开销：** 按智能体划分的认证配置文件、工作区和渠道路由。 + - **磁盘增长：** 会话 + 转录记录存储在 `~/.openclaw/agents//sessions/` 下。 + - **令牌成本：** 智能体越多，并发模型使用也越多。 + - **运维开销：** 每个智能体的认证配置、工作区和渠道路由。 提示： - 为每个智能体保留一个**活动**工作区（`agents.defaults.workspace`）。 - - 如果磁盘增长，请裁剪旧会话（删除 JSONL 或 store 条目）。 - - 使用 `openclaw doctor` 发现零散工作区和配置文件不匹配问题。 + - 如果磁盘持续增长，修剪旧会话（删除 JSONL 或 store 条目）。 + - 使用 `openclaw doctor` 发现零散工作区和 profile 不匹配问题。 - - 可以。使用**多智能体路由**来运行多个彼此隔离的智能体，并按 - 渠道/账户/对端路由入站消息。Slack 作为一个渠道受支持，也可以绑定到特定智能体。 + + 可以。使用**多智能体路由**来运行多个相互隔离的智能体，并按 + 渠道/账号/对等方对入站消息进行路由。Slack 支持作为渠道，并且可以绑定到特定智能体。 - 浏览器访问功能很强大，但并不意味着“能做人类能做的一切”——反机器人机制、CAPTCHA 和 MFA - 仍然可能阻止自动化。若要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， + 浏览器访问功能很强大，但并不等于“人类能做的都能做”——反机器人机制、CAPTCHA 和 MFA + 仍然可能阻止自动化。要获得最可靠的浏览器控制，请在主机上使用本地 Chrome MCP， 或在实际运行浏览器的机器上使用 CDP。 最佳实践设置： @@ -1374,7 +1373,7 @@ x-i18n: - 始终在线的 Gateway 网关主机（VPS/Mac mini）。 - 每个角色一个智能体（bindings）。 - 将 Slack 渠道绑定到这些智能体。 - - 在需要时通过 Chrome MCP 或节点使用本地浏览器。 + - 需要时通过 Chrome MCP 或节点使用本地浏览器。 文档： [Multi-Agent Routing](/zh-CN/concepts/multi-agent)、[Slack](/zh-CN/channels/slack)、 [Browser](/zh-CN/tools/browser)、[Nodes](/zh-CN/nodes)。 @@ -1382,59 +1381,58 @@ x-i18n: -## 模型、故障切换与认证配置文件 +## 模型、故障切换和认证配置 -有关模型的问答——默认值、选择、别名、切换、故障切换、认证配置文件—— -已移至专门页面： -[FAQ——模型与认证配置文件](/zh-CN/help/faq-models)。 +模型问答——默认值、选择、别名、切换、故障切换、认证配置—— +位于 [Models FAQ](/zh-CN/help/faq-models)。 -## Gateway 网关：端口、“已在运行”与远程模式 +## Gateway 网关：端口、“已在运行”和远程模式 - `gateway.port` 控制用于 WebSocket + HTTP（Control UI、hooks 等）的单一复用端口。 + `gateway.port` 控制单一复用端口，用于 WebSocket + HTTP（Control UI、hooks 等）。 优先级： ``` - --port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认 18789 + --port > OPENCLAW_GATEWAY_PORT > gateway.port > 默认值 18789 ``` - 因为“running”是 **supervisor** 的视角（launchd/systemd/schtasks）。而连接性探测是 CLI 实际去连接 gateway WebSocket 的结果。 + 因为 “running” 是 **supervisor** 的视角（launchd/systemd/schtasks）。连接探测则是 CLI 实际连接到 gateway WebSocket 的结果。 - 使用 `openclaw gateway status`，并重点查看以下行： + 使用 `openclaw gateway status` 并重点查看这些行： - `Probe target:`（探测实际使用的 URL） - `Listening:`（端口上实际绑定的内容） - - `Last gateway error:`（当进程活着但端口没有监听时，常见的根本原因） + - `Last gateway error:`（进程存活但端口未监听时的常见根因） - - 这是因为你正在编辑一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 + + 你正在编辑一个配置文件，而服务运行的是另一个配置文件（通常是 `--profile` / `OPENCLAW_STATE_DIR` 不匹配）。 - 修复： + 修复方法： ```bash openclaw gateway install --force ``` - 请在你希望服务使用的同一个 `--profile` / 环境下运行此命令。 + 从你希望服务使用的相同 `--profile` / 环境中运行该命令。 - OpenClaw 会在启动时立即绑定 WebSocket 监听器来强制执行运行时锁（默认 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，就会抛出 `GatewayLockError`，表示已有另一个实例正在监听。 + OpenClaw 会在启动时立即绑定 WebSocket 监听器，以强制执行运行时锁（默认 `ws://127.0.0.1:18789`）。如果绑定因 `EADDRINUSE` 失败，它会抛出 `GatewayLockError`，表示另一个实例已经在监听。 - 修复方式：停止另一个实例、释放端口，或使用 `openclaw gateway --port ` 运行。 + 修复方法：停止另一个实例、释放端口，或使用 `openclaw gateway --port ` 运行。 - 设置 `gateway.mode: "remote"`，并指向远程 WebSocket URL；如有需要，也可附带共享密钥远程凭证： + 设置 `gateway.mode: "remote"` 并指向远程 WebSocket URL，可选地附带 shared-secret 远程凭证： ```json5 { @@ -1449,79 +1447,79 @@ x-i18n: } ``` - 注意事项： + 说明： - 只有当 `gateway.mode` 为 `local` 时，`openclaw gateway` 才会启动（除非你传入覆盖标志）。 - - macOS 应用会监视配置文件，并在这些值更改时实时切换模式。 - - `gateway.remote.token` / `.password` 仅是客户端侧远程凭证；它们本身不会启用本地 gateway 认证。 + - macOS 应用会监视配置文件，并在这些值变化时实时切换模式。 + - `gateway.remote.token` / `.password` 仅是客户端侧的远程凭证；它们本身不会启用本地 gateway 认证。 - - 这是因为你的 gateway 认证路径与 UI 使用的认证方法不匹配。 + + 你的 gateway 认证路径与 UI 的认证方式不匹配。 - 事实（来自代码）： + 事实（基于代码）： - - Control UI 会将 token 保存在当前浏览器标签页会话和所选 gateway URL 的 `sessionStorage` 中，因此同一标签页刷新后仍可继续工作，而无需恢复长期的 localStorage token 持久化。 - - 当出现 `AUTH_TOKEN_MISMATCH` 时，如果 gateway 返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`），受信任客户端可以使用缓存的设备 token 尝试一次有界重试。 - - 该缓存 token 重试现在会复用与设备 token 一起存储的已批准 scopes。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留自己请求的 scope 集，而不会继承缓存 scopes。 - - 除该重试路径外，连接认证优先级依次为：显式共享 token/password、显式 `deviceToken`、存储的设备 token、bootstrap token。 - - Bootstrap token 的 scope 检查使用角色前缀。内置的 bootstrap operator allowlist 仅满足 operator 请求；节点或其他非 operator 角色仍需要它们各自角色前缀下的 scopes。 + - Control UI 会将 token 保存在当前浏览器标签页会话和所选 gateway URL 对应的 `sessionStorage` 中，因此在同一标签页刷新后仍可正常工作，而无需恢复长期 `localStorage` token 持久化。 + - 在 `AUTH_TOKEN_MISMATCH` 时，如果 gateway 返回重试提示（`canRetryWithDeviceToken=true`、`recommendedNextStep=retry_with_device_token`），受信任客户端可以使用缓存的设备 token 尝试一次有界重试。 + - 该缓存 token 重试现在会复用与设备 token 一起存储的已批准 scopes。显式 `deviceToken` / 显式 `scopes` 调用方仍会保留其请求的 scope 集，而不会继承缓存 scopes。 + - 在该重试路径之外，连接认证优先级依次为：显式 shared token/password、显式 `deviceToken`、存储的设备 token、bootstrap token。 + - Bootstrap token 的 scope 检查带有角色前缀。内置的 bootstrap operator 允许列表只能满足 operator 请求；node 或其他非 operator 角色仍然需要带其自身角色前缀的 scopes。 - 修复： + 修复方法： - - 最快方式：`openclaw dashboard`（会打印并复制 dashboard URL，尝试打开；如果是无头环境则显示 SSH 提示）。 + - 最快方式：`openclaw dashboard`（打印并复制 dashboard URL，尝试打开；如果是无头环境则显示 SSH 提示）。 - 如果你还没有 token：`openclaw doctor --generate-gateway-token`。 - - 如果是远程模式，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 - - 共享密钥模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴匹配的密钥。 - - Tailscale Serve 模式：确保 `gateway.auth.allowTailscale` 已启用，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份头的原始 loopback/tailnet URL。 - - trusted-proxy 模式：确保你是通过已配置的非 loopback 身份感知代理访问，而不是通过同主机 loopback 代理或原始 gateway URL 访问。 - - 如果一次重试后仍然不匹配，请轮换/重新批准配对的设备 token： + - 如果是远程环境，先建立隧道：`ssh -N -L 18789:127.0.0.1:18789 user@host`，然后打开 `http://127.0.0.1:18789/`。 + - shared-secret 模式：设置 `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` 或 `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`，然后在 Control UI 设置中粘贴匹配的 secret。 + - Tailscale Serve 模式：确保已启用 `gateway.auth.allowTailscale`，并且你打开的是 Serve URL，而不是绕过 Tailscale 身份头的原始 loopback/tailnet URL。 + - trusted-proxy 模式：确保你是通过已配置的非 loopback 身份感知代理访问，而不是通过同主机 loopback 代理或原始 gateway URL。 + - 如果在那一次重试之后仍然不匹配，请轮换/重新批准已配对的设备 token： - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - 如果该轮换调用提示被拒绝，请检查两点： - - 配对设备会话只能轮换**自己的**设备，除非它们还拥有 `operator.admin` - - 显式 `--scope` 值不能超过调用方当前的 operator scopes - - 仍然卡住？运行 `openclaw status --all`，并按照 [故障排除](/zh-CN/gateway/troubleshooting) 操作。认证细节请参见 [Dashboard](/zh-CN/web/dashboard)。 + - 如果该 rotate 调用提示被拒绝，请检查两点： + - 已配对设备会话只能轮换其**自己的**设备，除非它还具有 `operator.admin` + - 显式 `--scope` 值不能超出调用方当前的 operator scopes + - 仍然卡住？运行 `openclaw status --all`，并按照 [故障排除](/zh-CN/gateway/troubleshooting) 操作。认证详情请参阅 [Dashboard](/zh-CN/web/dashboard)。 - - `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果这台机器不在 Tailscale 网络中（或接口已关闭），就没有可供绑定的地址。 + + `tailnet` 绑定会从你的网络接口中选择一个 Tailscale IP（100.64.0.0/10）。如果机器未加入 Tailscale（或接口已关闭），就没有可绑定的地址。 - 修复： + 修复方法： - - 在该主机上启动 Tailscale（使其获得一个 100.x 地址），或 + - 在该主机上启动 Tailscale（使其拥有一个 100.x 地址），或 - 切换到 `gateway.bind: "loopback"` / `"lan"`。 - 注意：`tailnet` 是显式选择。`auto` 会优先选择 loopback；如果你想要仅 tailnet 绑定，请使用 `gateway.bind: "tailnet"`。 + 注意：`tailnet` 是显式设置。`auto` 会优先选择 loopback；如果你想要仅绑定 tailnet，请使用 `gateway.bind: "tailnet"`。 - - 通常不建议——一个 Gateway 网关就可以运行多个消息渠道和智能体。只有在你需要冗余（例如救援 bot）或硬隔离时，才使用多个 Gateway 网关。 + + 通常不建议——一个 Gateway 网关可以运行多个消息渠道和智能体。只有在你需要冗余（例如救援机器人）或硬隔离时，才使用多个 Gateway 网关。 - 可以，但你必须隔离以下内容： + 但也可以，只是你必须隔离以下内容： - - `OPENCLAW_CONFIG_PATH`（按实例划分的配置） - - `OPENCLAW_STATE_DIR`（按实例划分的状态） + - `OPENCLAW_CONFIG_PATH`（每个实例独立配置） + - `OPENCLAW_STATE_DIR`（每个实例独立状态） - `agents.defaults.workspace`（工作区隔离） - `gateway.port`（唯一端口） 快速设置（推荐）： - - 对每个实例使用 `openclaw --profile ...`（会自动创建 `~/.openclaw-`）。 - - 在每个 profile 配置中设置唯一的 `gateway.port`（或在手动运行时传入 `--port`）。 - - 安装按 profile 划分的服务：`openclaw --profile gateway install`。 + - 每个实例使用 `openclaw --profile ...`（会自动创建 `~/.openclaw-`）。 + - 在每个 profile 配置中设置唯一的 `gateway.port`（或对手动运行传入 `--port`）。 + - 安装按 profile 区分的服务：`openclaw --profile gateway install`。 - Profiles 也会为服务名添加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 + Profiles 还会给服务名加后缀（`ai.openclaw.`；旧版为 `com.openclaw.*`、`openclaw-gateway-.service`、`OpenClaw Gateway ()`）。 完整指南： [Multiple gateways](/zh-CN/gateway/multiple-gateways)。 - Gateway 网关是一个 **WebSocket 服务器**，它期望收到的第一条消息 - 是一个 `connect` 帧。如果收到其他内容，它会以 + Gateway 网关是一个 **WebSocket 服务器**，并且它要求第一条消息 + 必须是 `connect` 帧。如果收到的是其他内容，它会以 **code 1008**（策略违规）关闭连接。 常见原因： @@ -1536,13 +1534,13 @@ x-i18n: 2. 不要在普通浏览器标签页中打开 WS 端口。 3. 如果启用了认证，请在 `connect` 帧中包含 token/password。 - 如果你使用的是 CLI 或 TUI，URL 应该类似： + 如果你使用的是 CLI 或 TUI，URL 应该如下所示： ``` openclaw tui --url ws://:18789 --token ``` - 协议详情： [Gateway 网关协议](/zh-CN/gateway/protocol)。 + 协议详情： [Gateway protocol](/zh-CN/gateway/protocol)。 @@ -1557,9 +1555,9 @@ x-i18n: /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - 你可以通过 `logging.file` 设置一个稳定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 + 你可以通过 `logging.file` 设置固定路径。文件日志级别由 `logging.level` 控制。控制台详细程度由 `--verbose` 和 `logging.consoleLevel` 控制。 - 最快的日志跟踪方式： + 最快查看日志尾部的方法： ```bash openclaw logs --follow @@ -1567,11 +1565,11 @@ x-i18n: 服务/supervisor 日志（当 gateway 通过 launchd/systemd 运行时）： - - macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` 和 `gateway.err.log`（默认：`~/.openclaw/logs/...`；profiles 使用 `~/.openclaw-/logs/...`） + - macOS：`$OPENCLAW_STATE_DIR/logs/gateway.log` 和 `gateway.err.log`（默认：`~/.openclaw/logs/...`；profile 使用 `~/.openclaw-/logs/...`） - Linux：`journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows：`schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - 更多内容请参见 [故障排除](/zh-CN/gateway/troubleshooting)。 + 更多信息请参阅 [故障排除](/zh-CN/gateway/troubleshooting)。 @@ -1583,11 +1581,11 @@ x-i18n: openclaw gateway restart ``` - 如果你手动运行 gateway，`openclaw gateway --force` 可以重新占用端口。参见 [Gateway 网关](/zh-CN/gateway)。 + 如果你是手动运行 gateway，`openclaw gateway --force` 可以重新夺回端口。请参阅 [Gateway 网关](/zh-CN/gateway)。 - + Windows 有**两种安装模式**： **1）WSL2（推荐）：** Gateway 网关运行在 Linux 内部。 @@ -1600,7 +1598,7 @@ x-i18n: openclaw gateway restart ``` - 如果你从未安装过服务，就在前台启动它： + 如果你从未安装过服务，请在前台启动它： ```bash openclaw gateway run @@ -1615,18 +1613,18 @@ x-i18n: openclaw gateway restart ``` - 如果你是手动运行它（没有服务），请使用： + 如果你是手动运行它（无服务），请使用： ```powershell openclaw gateway run ``` - 文档： [Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关服务操作手册](/zh-CN/gateway)。 + 文档： [Windows（WSL2）](/zh-CN/platforms/windows)、[Gateway 网关服务运行手册](/zh-CN/gateway)。 - - 先进行快速健康检查： + + 先进行一次快速健康检查： ```bash openclaw status @@ -1637,11 +1635,11 @@ x-i18n: 常见原因： - - 模型认证未在**gateway 主机**上加载（检查 `models status`）。 - - 渠道配对/allowlist 阻止了回复（检查渠道配置 + 日志）。 - - WebChat/Dashboard 打开时没有使用正确的 token。 + - 模型认证没有加载到**Gateway 网关主机**上（检查 `models status`）。 + - 渠道配对/允许列表阻止了回复（检查渠道配置 + 日志）。 + - WebChat/Dashboard 在没有正确 token 的情况下打开。 - 如果你处于远程模式，请确认隧道/Tailscale 连接已建立，并且 + 如果你处于远程环境，请确认隧道/Tailscale 连接正常，并且 Gateway WebSocket 可达。 文档： [Channels](/zh-CN/channels)、[故障排除](/zh-CN/gateway/troubleshooting)、[Remote access](/zh-CN/gateway/remote)。 @@ -1651,12 +1649,12 @@ x-i18n: 这通常表示 UI 丢失了 WebSocket 连接。请检查： - 1. Gateway 网关是否正在运行？`openclaw gateway status` - 2. Gateway 网关是否健康？`openclaw status` - 3. UI 是否使用了正确的 token？`openclaw dashboard` - 4. 如果是远程模式，隧道/Tailscale 链路是否已连接？ + 1. Gateway 网关正在运行吗？`openclaw gateway status` + 2. Gateway 网关健康吗？`openclaw status` + 3. UI 是否有正确的 token？`openclaw dashboard` + 4. 如果是远程环境，隧道/Tailscale 链接是否正常？ - 然后跟踪日志： + 然后查看日志尾部： ```bash openclaw logs --follow @@ -1666,7 +1664,7 @@ x-i18n: - + 先查看日志和渠道状态： ```bash @@ -1674,10 +1672,10 @@ x-i18n: openclaw channels logs --channel telegram ``` - 然后根据错误匹配原因： + 然后对照错误信息： - - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单条目过多。OpenClaw 已经会裁剪到 Telegram 限制内，并使用更少命令重试，但有些菜单条目仍需要删减。请减少插件/skill/自定义命令，或者如果你不需要菜单，可禁用 `channels.telegram.commands.native`。 - - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理之后，请确认允许出站 HTTPS，且 `api.telegram.org` 的 DNS 正常工作。 + - `BOT_COMMANDS_TOO_MUCH`：Telegram 菜单中的条目过多。OpenClaw 已经会裁剪到 Telegram 限制并用更少命令重试，但有些菜单条目仍需要移除。请减少 plugin/skill/自定义命令，或者如果你不需要菜单，可禁用 `channels.telegram.commands.native`。 + - `TypeError: fetch failed`、`Network request for 'setMyCommands' failed!` 或类似网络错误：如果你在 VPS 上或位于代理后面，请确认允许出站 HTTPS，并且对 `api.telegram.org` 的 DNS 解析正常。 如果 Gateway 网关是远程的，请确保你查看的是 Gateway 网关主机上的日志。 @@ -1685,8 +1683,8 @@ x-i18n: - - 先确认 Gateway 网关可达，并且智能体能够运行： + + 先确认 Gateway 网关可达，并且智能体可以运行： ```bash openclaw status @@ -1694,44 +1692,45 @@ x-i18n: openclaw logs --follow ``` - 在 TUI 中，使用 `/status` 查看当前状态。如果你希望回复发送到某个聊天 - 渠道，请确认已启用投递（`/deliver on`）。 + 在 TUI 中，使用 `/status` 查看当前状态。如果你希望在聊天 + 渠道中收到回复，请确保已启用投递（`/deliver on`）。 文档： [TUI](/zh-CN/web/tui)、[Slash commands](/zh-CN/tools/slash-commands)。 - - 如果你安装了服务： + + 如果你已安装服务： ```bash openclaw gateway stop openclaw gateway start ``` - 这会停止/启动**受管服务**（macOS 上是 launchd，Linux 上是 systemd）。 - 当 Gateway 网关作为守护进程在后台运行时，请使用这种方式。 + 这会停止/启动**受监管的服务**（macOS 上是 launchd，Linux 上是 systemd）。 + 当 Gateway 网关作为后台守护进程运行时，请使用此方法。 - 如果你是在前台运行，请用 Ctrl-C 停止，然后执行： + 如果你是在前台运行，使用 Ctrl-C 停止，然后执行： ```bash openclaw gateway run ``` - 文档： [Gateway 网关服务操作手册](/zh-CN/gateway)。 + 文档： [Gateway 网关服务运行手册](/zh-CN/gateway)。 - + - `openclaw gateway restart`：重启**后台服务**（launchd/systemd）。 - `openclaw gateway`：在当前终端会话中**前台**运行 gateway。 - 如果你安装了服务，请使用 gateway 命令。需要一次性的前台运行时，再使用 `openclaw gateway`。 + 如果你安装了服务，请使用 gateway 命令。若你 + 想要一次性的前台运行，请使用 `openclaw gateway`。 - - 使用 `--verbose` 启动 Gateway 网关，以获得更详细的控制台输出。然后检查日志文件，以查看渠道认证、模型路由和 RPC 错误。 + + 使用 `--verbose` 启动 Gateway 网关，以获取更多控制台细节。然后检查日志文件中的渠道认证、模型路由和 RPC 错误。 @@ -1739,7 +1738,7 @@ x-i18n: - 智能体发出的出站附件必须包含一行 `MEDIA:`（单独占一行）。参见 [OpenClaw 助手设置](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 + 智能体发出的附件必须包含一行 `MEDIA:`（单独占一行）。请参阅 [OpenClaw 助手设置](/zh-CN/start/openclaw) 和 [Agent send](/zh-CN/tools/agent-send)。 CLI 发送： @@ -1747,14 +1746,14 @@ x-i18n: openclaw message send --target +15555550123 --message "给你" --media /path/to/file.png ``` - 还请检查： + 还需要检查： - - 目标渠道支持出站媒体，且未被 allowlist 阻止。 - - 文件在提供商的大小限制内（图片会被调整到最大 2048px）。 - - `tools.fs.workspaceOnly=true` 会将本地路径发送限制为工作区、temp/media-store 以及经过沙箱验证的文件。 - - `tools.fs.workspaceOnly=false` 会允许 `MEDIA:` 发送智能体已能读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 和 Office 文档）。纯文本和类似密钥的文件仍会被阻止。 + - 目标渠道支持出站媒体，并且没有被允许列表阻止。 + - 文件在 provider 的大小限制范围内（图片会调整到最大 2048 px）。 + - `tools.fs.workspaceOnly=true` 会将本地路径发送限制在工作区、temp/media-store 和经过沙箱校验的文件内。 + - `tools.fs.workspaceOnly=false` 允许 `MEDIA:` 发送智能体已可读取的主机本地文件，但仅限媒体和安全文档类型（图片、音频、视频、PDF 以及 Office 文档）。纯文本和类似 secret 的文件仍会被阻止。 - 参见 [Images](/zh-CN/nodes/images)。 + 请参阅 [Images](/zh-CN/nodes/images)。 @@ -1762,73 +1761,73 @@ x-i18n: ## 安全与访问控制 - - 应将入站私信视为不受信任输入。默认设置旨在降低风险： + + 请将入站私信视为不受信任输入。默认设置旨在降低风险： - - 支持私信的渠道默认行为是**配对**： - - 未知发送者会收到一个配对码；bot 不会处理他们的消息。 + - 具备私信能力的渠道默认行为是**配对**： + - 未知发送者会收到一个配对码；机器人不会处理他们的消息。 - 使用以下命令批准：`openclaw pairing approve --channel [--account ] ` - - 待处理请求每个渠道最多 **3 个**；如果没有收到配对码，请检查 `openclaw pairing list --channel [--account ]`。 - - 要公开开放私信，需要显式选择加入（`dmPolicy: "open"` 且 allowlist 为 `"*"`）。 + - 待处理请求每个渠道最多 **3 个**；如果代码未收到，请检查 `openclaw pairing list --channel [--account ]` + - 公开开放私信需要显式选择加入（`dmPolicy: "open"` 和允许列表 `"*"`）。 - 运行 `openclaw doctor` 可发现存在风险的私信策略。 + 运行 `openclaw doctor` 以发现有风险的私信策略。 - - 不会。Prompt injection 关乎的是**不受信任内容**，而不只是哪些人能给 bot 发私信。 - 如果你的助手会读取外部内容（web search/fetch、浏览器页面、邮件、 - 文档、附件、粘贴的日志），这些内容就可能包含试图 - 劫持模型的指令。即使**你是唯一发送者**，这种情况也可能发生。 + + 不是。Prompt injection 关乎的是**不受信任的内容**，而不仅仅是谁可以给机器人发私信。 + 如果你的助手会读取外部内容（Web 搜索/抓取、浏览器页面、邮件、 + 文档、附件、粘贴的日志），这些内容都可能包含试图 + 劫持模型的指令。即使**只有你自己是发送者**，这也可能发生。 - 当启用工具时，风险最大：模型可能被诱导 - 窃取上下文或代表你调用工具。降低影响范围的方法包括： + 最大风险出现在启用了工具时：模型可能被诱导 + 泄露上下文或代表你调用工具。降低影响范围的方法包括： - 使用只读或禁用工具的“reader”智能体来总结不受信任内容 - - 对启用了工具的智能体关闭 `web_search` / `web_fetch` / `browser` - - 也将解码后的文件/文档文本视为不受信任：OpenResponses - `input_file` 和媒体附件提取都会把提取出的文本包装在 - 显式的外部内容边界标记中，而不是直接传递原始文件文本 - - 使用沙箱隔离和严格的工具 allowlist + - 对启用工具的智能体关闭 `web_search` / `web_fetch` / `browser` + - 同样将解码后的文件/文档文本视为不受信任：OpenResponses + `input_file` 和媒体附件提取都会将提取出的文本包装在 + 明确的外部内容边界标记中，而不是直接传递原始文件文本 + - 使用沙箱隔离和严格的工具允许列表 - 详情： [安全](/zh-CN/gateway/security)。 + 详情： [Security](/zh-CN/gateway/security)。 - - 对大多数设置来说，是的。使用单独的账号和电话号码来隔离 bot， - 可以在发生问题时减少影响范围。这也更便于轮换 - 凭证或撤销访问，而不会影响你的个人账户。 + + 对大多数配置来说，是的。使用独立账号和手机号来隔离机器人， + 可以在出问题时缩小影响范围。这也更容易轮换 + 凭证或撤销访问，而不会影响你的个人账号。 - 从小做起。只授予它你真正需要的工具和账号访问权限，必要时 - 再逐步扩展。 + 从小规模开始。只授予它你实际需要的工具和账号访问权限，并在 + 以后确有需要时再逐步扩展。 - 文档： [安全](/zh-CN/gateway/security)、[Pairing](/zh-CN/channels/pairing)。 + 文档： [Security](/zh-CN/gateway/security)、[Pairing](/zh-CN/channels/pairing)。 - 我们**不建议**让它完全自主处理你的个人消息。最安全的模式是： + 我们**不**建议让它完全自主处理你的个人消息。最安全的模式是： - - 将私信保持在**配对模式**或严格的 allowlist 中。 + - 将私信保持在**配对模式**或严格的允许列表模式。 - 如果你希望它代表你发送消息，请使用**单独的号码或账号**。 - - 让它先起草，然后**发送前由你批准**。 + - 让它先起草，然后在发送前**由你审批**。 - 如果你想试验，请在专用账号上进行，并保持隔离。参见 - [安全](/zh-CN/gateway/security)。 + 如果你想尝试，请在专用账号上进行，并保持隔离。请参阅 + [Security](/zh-CN/gateway/security)。 - - 可以，**前提是**智能体仅用于聊天，且输入是受信任的。较小档位的模型 - 更容易受到指令劫持，因此不要将它们用于启用了工具的智能体， + + 可以，**前提是**该智能体只用于聊天，且输入是可信的。较小档位的模型 + 更容易受到指令劫持，因此不要将它们用于启用工具的智能体， 或用于读取不受信任内容的场景。如果你必须使用较小模型，请锁定 - 工具，并在沙箱中运行。参见 [安全](/zh-CN/gateway/security)。 + 工具，并在沙箱中运行。请参阅 [Security](/zh-CN/gateway/security)。 - 只有当未知发送者给 bot 发消息且 - `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独执行 `/start` 不会生成配对码。 + 只有当未知发送者给机器人发消息，并且 + `dmPolicy: "pairing"` 已启用时，才会发送配对码。单独发送 `/start` 不会生成代码。 检查待处理请求： @@ -1836,12 +1835,12 @@ x-i18n: openclaw pairing list telegram ``` - 如果你希望立即获得访问权限，请将你的发送者 ID 加入 allowlist，或为该账户设置 `dmPolicy: "open"`。 + 如果你想立即获得访问权限，请将你的发送者 ID 加入允许列表，或为该账号设置 `dmPolicy: "open"`。 - - 不会。默认的 WhatsApp 私信策略是**配对**。未知发送者只会收到一个配对码，他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送。 + + 不会。WhatsApp 默认的私信策略是**配对**。未知发送者只会收到一个配对码，而且他们的消息**不会被处理**。OpenClaw 只会回复它收到的聊天，或你显式触发的发送。 使用以下命令批准配对： @@ -1855,18 +1854,19 @@ x-i18n: openclaw pairing list whatsapp ``` - 向导中的电话号码提示：它用于设置你的**allowlist/owner**，以便允许你自己的私信。它不会用于自动发送。如果你在个人 WhatsApp 号码上运行，请使用该号码，并启用 `channels.whatsapp.selfChatMode`。 + 向导中的手机号提示：它用于设置你的**允许列表/owner**，以便允许你自己的私信。它不会用于自动发送。如果你是在自己的个人 WhatsApp 号码上运行，请使用该号码并启用 `channels.whatsapp.selfChatMode`。 -## 聊天命令、终止任务，以及“它停不下来” +## 聊天命令、中止任务与“它停不下来” - 大多数内部或工具消息只会在该会话启用了 **verbose**、**trace** 或 **reasoning** 时出现。 + 大多数内部或工具消息仅会在该会话启用了 **verbose**、**trace** 或 **reasoning** + 时显示。 - 在你看到这些消息的聊天中执行以下命令： + 在出现该问题的聊天中执行修复： ``` /verbose off @@ -1876,14 +1876,14 @@ x-i18n: 如果仍然很吵，请检查 Control UI 中的会话设置，并将 verbose 设为 **inherit**。同时确认你没有使用在配置中将 `verboseDefault` 设为 - `on` 的 bot 配置文件。 + `on` 的机器人 profile。 - 文档： [Thinking and verbose](/zh-CN/tools/thinking)、[安全](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 + 文档： [Thinking and verbose](/zh-CN/tools/thinking)、[Security](/zh-CN/gateway/security#reasoning-verbose-output-in-groups)。 - 发送以下任一内容，且**必须是单独一条消息**（不要加斜杠）： + 将以下任一内容**作为独立消息发送**（不要带斜杠）： ``` stop @@ -1907,7 +1907,7 @@ x-i18n: interrupt ``` - 这些都是终止触发词（不是 slash 命令）。 + 这些都是中止触发词（不是 slash 命令）。 对于后台进程（来自 exec 工具），你可以让智能体运行： @@ -1915,17 +1915,17 @@ x-i18n: process action:kill sessionId:XXX ``` - Slash 命令概览：参见 [Slash commands](/zh-CN/tools/slash-commands)。 + Slash commands 概览：请参阅 [Slash commands](/zh-CN/tools/slash-commands)。 - 大多数命令都必须作为**单独消息**发送，并且以 `/` 开头，但少数快捷方式（如 `/status`）对于 allowlist 中的发送者也支持内联使用。 + 大多数命令都必须作为**以 `/` 开头的独立消息**发送，但少数快捷方式（如 `/status`）对加入允许列表的发送者也可在内联消息中使用。 - 默认情况下，OpenClaw 会阻止**跨提供商**消息发送。如果某次工具调用绑定到了 + OpenClaw 默认会阻止**跨 provider** 消息发送。如果某个工具调用绑定到了 Telegram，它就不会发送到 Discord，除非你显式允许。 - 为该智能体启用跨提供商消息发送： + 为该智能体启用跨 provider 消息发送： ```json5 { @@ -1940,38 +1940,38 @@ x-i18n: } ``` - 编辑配置后请重启 gateway。 + 编辑配置后重启 gateway。 - - 队列模式控制新消息如何与正在进行的运行交互。使用 `/queue` 更改模式： + + 队列模式控制新消息如何与正在进行中的运行交互。使用 `/queue` 更改模式： - - `steer` - 新消息会重定向当前任务 - - `followup` - 按顺序逐条运行消息 - - `collect` - 批量收集消息并统一回复（默认） - - `steer-backlog` - 先重定向，再处理积压消息 - - `interrupt` - 终止当前运行并重新开始 + - `steer` - 新消息重定向当前任务 + - `followup` - 按顺序逐条处理消息 + - `collect` - 批量收集消息并统一回复一次（默认） + - `steer-backlog` - 先重定向当前任务，再处理积压消息 + - `interrupt` - 中止当前运行并重新开始 - 你还可以为 followup 模式添加选项，例如 `debounce:2s cap:25 drop:summarize`。 + 你可以为 followup 模式添加选项，如 `debounce:2s cap:25 drop:summarize`。 -## 其他 +## 杂项 - 在 OpenClaw 中，凭证和模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在认证配置文件中存储 Anthropic API 密钥）会启用认证，但实际默认模型取决于你在 `agents.defaults.model.primary` 中的配置（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这意味着 Gateway 网关无法在当前运行智能体对应的 `auth-profiles.json` 中找到 Anthropic 凭证。 + 在 OpenClaw 中，凭证与模型选择是分开的。设置 `ANTHROPIC_API_KEY`（或在认证配置中存储 Anthropic API 密钥）会启用认证，但实际的默认模型取决于你在 `agents.defaults.model.primary` 中配置的内容（例如 `anthropic/claude-sonnet-4-6` 或 `anthropic/claude-opus-4-6`）。如果你看到 `No credentials found for profile "anthropic:default"`，这意味着 Gateway 网关无法在正在运行的智能体对应的预期 `auth-profiles.json` 中找到 Anthropic 凭证。 --- -仍然卡住？请在 [Discord](https://discord.com/invite/clawd) 中提问，或发起一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 +仍然卡住？请到 [Discord](https://discord.com/invite/clawd) 提问，或发起一个 [GitHub discussion](https://github.com/openclaw/openclaw/discussions)。 ## 相关内容 -- [FAQ——快速开始与首次运行设置](/zh-CN/help/faq-first-run) -- [FAQ——模型与认证配置文件](/zh-CN/help/faq-models) -- [故障排除](/zh-CN/help/troubleshooting) +- [首次运行 FAQ](/zh-CN/help/faq-first-run) — 安装、新手引导、认证、订阅、早期故障 +- [Models FAQ](/zh-CN/help/faq-models) — 模型选择、故障切换、认证配置 +- [故障排除](/zh-CN/help/troubleshooting) — 按症状优先的初步排查 diff --git a/docs/zh-CN/help/index.md b/docs/zh-CN/help/index.md index fe3a08df4..0f4eb6426 100644 --- a/docs/zh-CN/help/index.md +++ b/docs/zh-CN/help/index.md @@ -1,33 +1,45 @@ --- read_when: - - 你是新手，想要一份“我该点什么 / 运行什么”的指南 - - 某些地方出问题了，你想用最快的路径修复它 -summary: 帮助中心：常见修复、安装完整性检查，以及出问题时应查看的位置 + - 你是新手，想要一份“我该点击/运行什么”的指南 + - 出了问题，你想要最快的修复路径 +summary: 帮助中心：常见修复、安装完整性检查，以及出现问题时该去哪里查看 title: 帮助 x-i18n: - generated_at: "2026-04-23T20:51:09Z" + generated_at: "2026-04-24T06:58:56Z" model: gpt-5.4 provider: openai - source_hash: 22d4649ba47cfbd8ca3e415a1ae99884867ca80c44cbe39f8a30b29d64e95a05 + source_hash: f4ea596c304ceee2422fd0ba67f61ad6e38c423a476a41cabec06f53f7a55b38 source_path: help/index.md workflow: 15 --- -如果你想要一条快速“解决问题”的路径，请从这里开始： +最常见问题的快速“解决问题”路径： -- **故障排除：** [从这里开始](/zh-CN/help/troubleshooting) -- **安装完整性检查（Node/npm/PATH）：** [安装](/zh-CN/install/node#troubleshooting) -- **Gateway 网关问题：** [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) -- **日志：** [日志](/zh-CN/logging) 和 [Gateway 网关日志](/zh-CN/gateway/logging) -- **修复：** [Doctor](/zh-CN/gateway/doctor) +- [故障排除](/zh-CN/help/troubleshooting) — 按症状优先的决策树 +- [调试](/zh-CN/help/debugging) — 监视模式、原始流、开发配置文件 +- [安装完整性检查](/zh-CN/install/node#troubleshooting) — Node / npm / PATH 检查 +- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关特定问题 +- [Doctor](/zh-CN/gateway/doctor) — 自动修复 + 诊断包 -如果你想找的是概念性问题（而不是“某些地方坏了”）： +## 常见问题 -- [常见问题（概念）](/zh-CN/help/faq) +- [常见问题](/zh-CN/help/faq) — 日常概念与操作问题 +- [首次运行常见问题](/zh-CN/help/faq-first-run) — 安装、新手引导、凭证、订阅、早期失败 +- [模型常见问题](/zh-CN/help/faq-models) — 模型选择、故障切换、认证配置文件 -## 环境与调试 +## 诊断 -- **环境变量：** [OpenClaw 在哪里加载环境变量及其优先级](/zh-CN/help/environment) -- **调试：** [监视模式、原始流和开发 profile](/zh-CN/help/debugging) -- **测试：** [测试套件、实时测试和 Docker runners](/zh-CN/help/testing) -- **脚本：** [仓库辅助脚本](/zh-CN/help/scripts) +- [环境变量](/zh-CN/help/environment) — OpenClaw 在哪里加载环境变量以及优先级 +- [诊断标志](/zh-CN/diagnostics/flags) — 运行时诊断与详细模式 +- [Node + tsx 崩溃](/zh-CN/debug/node-issue) — 特定的 Node / tsx 运行时崩溃场景 + +## 测试 + +- [测试](/zh-CN/help/testing) — 测试套件与 Docker 运行器 +- [实时测试](/zh-CN/help/testing-live) — 涉及网络的提供商与 CLI 冒烟测试 + +## 社区与其他 + +- [OpenClaw 背景故事](/zh-CN/start/lore) — 故事背景 +- [文档中心](/zh-CN/start/hubs) — 本文档的组织方式 +- [文档目录](/zh-CN/start/docs-directory) — 完整文件映射 diff --git a/docs/zh-CN/help/troubleshooting.md b/docs/zh-CN/help/troubleshooting.md index 7d2ad0943..83dbe0150 100644 --- a/docs/zh-CN/help/troubleshooting.md +++ b/docs/zh-CN/help/troubleshooting.md @@ -1,25 +1,23 @@ --- read_when: - - OpenClaw 无法正常工作，你需要最快的修复路径 - - 你希望在深入查看详细操作手册之前，先走一遍分诊流程 -summary: OpenClaw 按症状分类的故障排除中心 -title: 常规故障排除 + - OpenClaw 无法正常工作，而你需要最快速的解决方案。 + - 你想在深入查看详细操作手册之前，先进行分诊流程。 +summary: OpenClaw 的按症状排查故障中心 +title: 常见故障排除 x-i18n: - generated_at: "2026-04-23T20:51:23Z" + generated_at: "2026-04-24T06:58:59Z" model: gpt-5.4 provider: openai - source_hash: ce06ddce9de9e5824b4c5e8c182df07b29ce3ff113eb8e29c62aef9a4682e8e9 + source_hash: c832c3f7609c56a5461515ed0f693d2255310bf2d3958f69f57c482bcbef97f0 source_path: help/troubleshooting.md workflow: 15 --- -# 故障排除 - -如果你只有 2 分钟时间，请把本页当作分诊入口。 +如果你只有 2 分钟，请把这个页面当作分诊入口。 ## 最初的六十秒 -按顺序运行下面这组命令： +按顺序运行这组命令，不要跳步： ```bash openclaw status @@ -31,15 +29,15 @@ openclaw channels status --probe openclaw logs --follow ``` -良好的输出可以概括为： +一行判断“正常输出”： -- `openclaw status` → 显示已配置的渠道，且没有明显的认证错误。 -- `openclaw status --all` → 完整报告存在且可分享。 -- `openclaw gateway probe` → 预期的 gateway 目标可达（`Reachable: yes`）。`Capability: ...` 表示探测所能证明的认证级别，而 `Read probe: limited - missing scope: operator.read` 表示诊断能力受限，不代表连接失败。 -- `openclaw gateway status` → 显示 `Runtime: running`、`Connectivity probe: ok` 以及合理的 `Capability: ...` 行。如果你还需要读作用域的 RPC 证明，可使用 `--require-rpc`。 -- `openclaw doctor` → 没有阻塞性的配置/服务错误。 -- `openclaw channels status --probe` → 当 gateway 可达时，会返回实时的逐账户传输状态，以及如 `works` 或 `audit ok` 之类的 probe/audit 结果；如果 gateway 不可达，该命令会回退为仅配置摘要。 -- `openclaw logs --follow` → 有稳定活动，没有重复出现的致命错误。 +- `openclaw status` → 显示已配置的渠道，且没有明显的身份验证错误。 +- `openclaw status --all` → 完整报告存在，并且可以分享。 +- `openclaw gateway probe` → 预期的 Gateway 网关目标可达（`Reachable: yes`）。`Capability: ...` 会告诉你探测能够证明的认证级别，而 `Read probe: limited - missing scope: operator.read` 表示诊断能力受限，不是连接失败。 +- `openclaw gateway status` → 显示 `Runtime: running`、`Connectivity probe: ok`，以及合理的 `Capability: ...` 行。如果你还需要具备读取作用域的 RPC 证明，可使用 `--require-rpc`。 +- `openclaw doctor` → 没有阻塞性的配置或服务错误。 +- `openclaw channels status --probe` → 如果 Gateway 网关可达，会返回每个账号的实时传输状态，以及 `works` 或 `audit ok` 之类的探测 / 审计结果；如果 Gateway 网关不可达，该命令会回退为仅基于配置的摘要。 +- `openclaw logs --follow` → 活动稳定，没有重复出现的致命错误。 ## Anthropic 长上下文 429 @@ -47,30 +45,28 @@ openclaw logs --follow `HTTP 429: rate_limit_error: Extra usage is required for long context requests`， 请前往 [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/zh-CN/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context)。 -## 本地 OpenAI 兼容后端可直接工作，但在 OpenClaw 中失败 +## 本地 OpenAI 兼容后端直接可用，但在 OpenClaw 中失败 -如果你的本地或自托管 `/v1` 后端能响应小型直接 +如果你的本地或自托管 `/v1` 后端能够响应小型直接 `/v1/chat/completions` 探测，但在 `openclaw infer model run` 或正常 -智能体轮次中失败： +智能体对话中失败： -1. 如果错误提到 `messages[].content` 需要字符串，请设置 +1. 如果错误提到 `messages[].content` 需要是字符串，请设置 `models.providers..models[].compat.requiresStringContent: true`。 -2. 如果后端仍只在 OpenClaw 智能体轮次中失败，请设置 - `models.providers..models[].compat.supportsTools: false` 并重试。 -3. 如果微小的直接调用仍然可以工作，但更大的 OpenClaw 提示导致后端崩溃， - 则应将剩余问题视为上游模型/服务器限制，并继续阅读详细操作手册： +2. 如果后端仍然只在 OpenClaw 智能体对话中失败，请设置 + `models.providers..models[].compat.supportsTools: false` 然后重试。 +3. 如果很小的直接调用仍然可用，但较大的 OpenClaw 提示词会让后端崩溃，请将剩余问题视为上游模型 / 服务器限制，并继续查看详细操作手册： [/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail](/zh-CN/gateway/troubleshooting#local-openai-compatible-backend-passes-direct-probes-but-agent-runs-fail) -## 插件安装因缺少 openclaw extensions 而失败 +## 插件安装失败，并提示缺少 openclaw extensions -如果安装因 `package.json missing openclaw.extensions` 失败，说明该插件包 -使用了 OpenClaw 已不再接受的旧结构。 +如果安装失败并提示 `package.json missing openclaw.extensions`，说明该插件包使用了 OpenClaw 已不再接受的旧结构。 -在插件包中修复： +在插件包中这样修复： 1. 在 `package.json` 中添加 `openclaw.extensions`。 -2. 将条目指向已构建的运行时文件（通常是 `./dist/index.js`）。 -3. 重新发布插件，再次运行 `openclaw plugins install `。 +2. 将条目指向构建后的运行时文件（通常是 `./dist/index.js`）。 +3. 重新发布该插件，然后再次运行 `openclaw plugins install `。 示例： @@ -84,25 +80,25 @@ openclaw logs --follow } ``` -参考：[插件架构](/zh-CN/plugins/architecture) +参考：[Plugin architecture](/zh-CN/plugins/architecture) ## 决策树 ```mermaid flowchart TD - A[OpenClaw 无法正常工作] --> B{首先坏掉的是什么} + A[OpenClaw 无法正常工作] --> B{最先出问题的是什么} B --> C[没有回复] B --> D[Dashboard 或 Control UI 无法连接] - B --> E[Gateway 无法启动或服务未运行] - B --> F[渠道已连接，但消息无法流动] + B --> E[Gateway 网关无法启动或服务未运行] + B --> F[渠道已连接但消息没有流动] B --> G[Cron 或 heartbeat 未触发或未送达] - B --> H[节点已配对，但 camera canvas screen exec 失败] + B --> H[节点已配对但 camera canvas screen exec 工具失败] B --> I[浏览器工具失败] C --> C1[/“没有回复”部分/] D --> D1[/“Control UI”部分/] - E --> E1[/“Gateway”部分/] - F --> F1[/“渠道流动”部分/] + E --> E1[/“Gateway 网关”部分/] + F --> F1[/“渠道流转”部分/] G --> G1[/“自动化”部分/] H --> H1[/“节点工具”部分/] I --> I1[/“浏览器”部分/] @@ -118,21 +114,21 @@ flowchart TD openclaw logs --follow ``` - 良好的输出应表现为： + 正常输出通常如下： - `Runtime: running` - `Connectivity probe: ok` - `Capability: read-only`、`write-capable` 或 `admin-capable` - - 你的渠道显示传输已连接，并且在支持时，`channels status --probe` 中会出现 `works` 或 `audit ok` - - 发送者显示为已批准（或私信策略为 open/allowlist） + - 你的渠道显示传输已连接，并且在支持的情况下，`channels status --probe` 中会显示 `works` 或 `audit ok` + - 发送者显示已获批准（或私信策略为 open / allowlist） 常见日志特征： - - `drop guild message (mention required` → Discord 中，提及门控阻止了该消息。 + - `drop guild message (mention required` → 在 Discord 中，提及门控阻止了该消息。 - `pairing request` → 发送者尚未获批，正在等待私信配对批准。 - 渠道日志中的 `blocked` / `allowlist` → 发送者、房间或群组被过滤。 - 深入页面： + 详细页面： - [/gateway/troubleshooting#no-replies](/zh-CN/gateway/troubleshooting#no-replies) - [/channels/troubleshooting](/zh-CN/channels/troubleshooting) @@ -149,28 +145,27 @@ flowchart TD openclaw channels status --probe ``` - 良好的输出应表现为： + 正常输出通常如下： - - `openclaw gateway status` 中显示 `Dashboard: http://...` + - 在 `openclaw gateway status` 中显示 `Dashboard: http://...` - `Connectivity probe: ok` - `Capability: read-only`、`write-capable` 或 `admin-capable` - 日志中没有认证循环 常见日志特征： - - `device identity required` → HTTP/非安全上下文无法完成设备认证。 - - `origin not allowed` → 浏览器 `Origin` 不在 Control UI - gateway 目标的允许范围内。 - - `AUTH_TOKEN_MISMATCH` 并带有重试提示（`canRetryWithDeviceToken=true`）→ 可能会自动进行一次受信任的 device-token 重试。 - - 该缓存 token 重试会复用与已配对 - 设备 token 一起存储的缓存作用域集合。显式 `deviceToken` / 显式 `scopes` 调用方则保留其请求的作用域集合。 - - 在异步 Tailscale Serve Control UI 路径中，对于相同 - `{scope, ip}` 的失败尝试，会在 limiter 记录失败前进行串行化，因此第二个并发错误重试可能已经显示 `retry later`。 - - 来自 localhost 浏览器 origin 的 `too many failed authentication attempts (retry later)` → 同一 `Origin` 的重复失败已被暂时锁定；另一个 localhost origin 使用的是单独的配额桶。 - - 在那次重试之后仍反复出现 `unauthorized` → token/密码错误、认证模式不匹配，或已配对设备 token 已过期。 - - `gateway connect failed:` → UI 指向了错误的 URL/端口，或 gateway 不可达。 + - `device identity required` → HTTP / 非安全上下文无法完成设备认证。 + - `origin not allowed` → 浏览器 `Origin` 不在 Control UI 的 + Gateway 网关目标允许范围内。 + - 带有重试提示（`canRetryWithDeviceToken=true`）的 `AUTH_TOKEN_MISMATCH` → 可能会自动执行一次受信任的设备令牌重试。 + - 该缓存令牌重试会复用与已配对设备令牌一起存储的缓存作用域集合。显式传入 `deviceToken` / 显式传入 `scopes` 的调用方则会保留它们请求的作用域集合。 + - 在异步 Tailscale Serve Control UI 路径上，同一 + `{scope, ip}` 的失败尝试会在限流器记录失败之前被串行化，因此第二个并发的错误重试可能已经显示 `retry later`。 + - 来自 localhost 浏览器来源的 `too many failed authentication attempts (retry later)` → 同一 `Origin` 的重复失败会被暂时锁定；另一个 localhost 来源会使用单独的桶。 + - 该次重试之后仍反复出现 `unauthorized` → 令牌 / 密码错误、认证模式不匹配，或已配对的设备令牌已过期。 + - `gateway connect failed:` → UI 指向了错误的 URL / 端口，或 Gateway 网关不可达。 - 深入页面： + 详细页面： - [/gateway/troubleshooting#dashboard-control-ui-connectivity](/zh-CN/gateway/troubleshooting#dashboard-control-ui-connectivity) - [/web/control-ui](/zh-CN/web/control-ui) @@ -178,7 +173,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -187,7 +182,7 @@ flowchart TD openclaw channels status --probe ``` - 良好的输出应表现为： + 正常输出通常如下： - `Service: ... (loaded)` - `Runtime: running` @@ -196,11 +191,11 @@ flowchart TD 常见日志特征： - - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → gateway 模式是 remote，或者配置文件缺少 local-mode 标记，需要修复。 - - `refusing to bind gateway ... without auth` → 在没有有效 gateway 认证路径（token/password，或在已配置时使用 trusted-proxy）的情况下，尝试进行非 loopback 绑定。 + - `Gateway start blocked: set gateway.mode=local` 或 `existing config is missing gateway.mode` → Gateway 网关模式为 remote，或配置文件缺少 local 模式标记，需要修复。 + - `refusing to bind gateway ... without auth` → 在没有有效 Gateway 网关认证路径的情况下尝试绑定到非 loopback 地址（令牌 / 密码，或在已配置时使用 trusted-proxy）。 - `another gateway instance is already listening` 或 `EADDRINUSE` → 端口已被占用。 - 深入页面： + 详细页面： - [/gateway/troubleshooting#gateway-service-not-running](/zh-CN/gateway/troubleshooting#gateway-service-not-running) - [/gateway/background-process](/zh-CN/gateway/background-process) @@ -208,7 +203,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -217,19 +212,19 @@ flowchart TD openclaw channels status --probe ``` - 良好的输出应表现为： + 正常输出通常如下： - 渠道传输已连接。 - - 配对/允许列表检查通过。 - - 在需要时，提及可被检测到。 + - 配对 / allowlist 检查通过。 + - 在需要时，能够检测到提及。 常见日志特征： - `mention required` → 群组提及门控阻止了处理。 - `pairing` / `pending` → 私信发送者尚未获批。 - - `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 渠道权限 token 问题。 + - `not_in_channel`、`missing_scope`、`Forbidden`、`401/403` → 渠道权限令牌问题。 - 深入页面： + 详细页面： - [/gateway/troubleshooting#channel-connected-messages-not-flowing](/zh-CN/gateway/troubleshooting#channel-connected-messages-not-flowing) - [/channels/troubleshooting](/zh-CN/channels/troubleshooting) @@ -246,23 +241,23 @@ flowchart TD openclaw logs --follow ``` - 良好的输出应表现为： + 正常输出通常如下： - - `cron.status` 显示已启用，并有下次唤醒时间。 - - `cron runs` 显示最近的 `ok` 条目。 - - heartbeat 已启用，且不在静默时段之外。 + - `cron.status` 显示已启用，并带有下一次唤醒时间。 + - `cron runs` 显示最近的 `ok` 记录。 + - heartbeat 已启用，且不在活跃时间之外。 常见日志特征： - `cron: scheduler disabled; jobs will not run automatically` → cron 已禁用。 - - `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于配置的静默时段外。 - - `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空白/仅标题脚手架。 - - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 任务模式已启用，但当前没有到期的任务间隔。 - - `heartbeat skipped` 且 `reason=alerts-disabled` → 所有 heartbeat 可见性都被禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。 + - `heartbeat skipped` 且 `reason=quiet-hours` → 当前处于配置的活跃时间之外。 + - `heartbeat skipped` 且 `reason=empty-heartbeat-file` → `HEARTBEAT.md` 存在，但只包含空白 / 仅标题的骨架内容。 + - `heartbeat skipped` 且 `reason=no-tasks-due` → `HEARTBEAT.md` 任务模式已启用，但目前还没有任何任务到达间隔时间。 + - `heartbeat skipped` 且 `reason=alerts-disabled` → 所有 heartbeat 可见性都已禁用（`showOk`、`showAlerts` 和 `useIndicator` 全部关闭）。 - `requests-in-flight` → 主通道繁忙；heartbeat 唤醒被延后。 - - `unknown accountId` → heartbeat 投递目标账户不存在。 + - `unknown accountId` → heartbeat 投递目标账号不存在。 - 深入页面： + 详细页面： - [/gateway/troubleshooting#cron-and-heartbeat-delivery](/zh-CN/gateway/troubleshooting#cron-and-heartbeat-delivery) - [/automation/cron-jobs#troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting) @@ -270,7 +265,7 @@ flowchart TD - + ```bash openclaw status openclaw gateway status @@ -279,20 +274,20 @@ flowchart TD openclaw logs --follow ``` - 良好的输出应表现为： + 正常输出通常如下： - - 节点被列为已连接，并以 `node` 角色完成配对。 - - 你调用的命令所需能力存在。 - - 工具的权限状态已授予。 + - 节点列为已连接，并已针对 `node` 角色完成配对。 + - 你调用的命令具备相应能力。 + - 该工具的权限状态为已授予。 常见日志特征： - - `NODE_BACKGROUND_UNAVAILABLE` → 请将节点应用切回前台。 - - `*_PERMISSION_REQUIRED` → OS 权限被拒绝或缺失。 - - `SYSTEM_RUN_DENIED: approval required` → exec 批准仍在等待中。 - - `SYSTEM_RUN_DENIED: allowlist miss` → 命令不在 exec 允许列表中。 + - `NODE_BACKGROUND_UNAVAILABLE` → 将节点应用切换到前台。 + - `*_PERMISSION_REQUIRED` → 操作系统权限被拒绝或缺失。 + - `SYSTEM_RUN_DENIED: approval required` → exec 批准正在等待中。 + - `SYSTEM_RUN_DENIED: allowlist miss` → 该命令不在 exec allowlist 中。 - 深入页面： + 详细页面： - [/gateway/troubleshooting#node-paired-tool-fails](/zh-CN/gateway/troubleshooting#node-paired-tool-fails) - [/nodes/troubleshooting](/zh-CN/nodes/troubleshooting) @@ -300,7 +295,7 @@ flowchart TD - + ```bash openclaw config get tools.exec.host openclaw config get tools.exec.security @@ -310,14 +305,14 @@ flowchart TD 发生了什么变化： - - 如果未设置 `tools.exec.host`，默认值是 `auto`。 - - `host=auto` 在存在沙箱运行时时会解析为 `sandbox`，否则解析为 `gateway`。 - - `host=auto` 只负责路由；无提示的 “YOLO” 行为来自于 gateway/node 上的 `security=full` 加 `ask=off`。 - - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认值为 `full`。 - - 未设置的 `tools.exec.ask` 默认值为 `off`。 - - 结果是：如果你现在看到了批准提示，说明某些宿主机本地策略或按会话策略，相对于当前默认值收紧了 exec。 + - 如果 `tools.exec.host` 未设置，默认值是 `auto`。 + - 当沙箱运行时处于激活状态时，`host=auto` 会解析为 `sandbox`；否则解析为 `gateway`。 + - `host=auto` 仅影响路由；无提示的 “YOLO” 行为来自 gateway/node 上的 `security=full` 加 `ask=off`。 + - 在 `gateway` 和 `node` 上，未设置的 `tools.exec.security` 默认是 `full`。 + - 未设置的 `tools.exec.ask` 默认是 `off`。 + - 结果：如果你现在看到了批准请求，说明某些主机本地或按会话生效的策略，相比当前默认值收紧了 exec 行为。 - 恢复为当前默认的无批准行为： + 恢复当前默认的无批准行为： ```bash openclaw config set tools.exec.host gateway @@ -328,17 +323,17 @@ flowchart TD 更安全的替代方案： - - 如果你只是想要稳定的宿主机路由，只设置 `tools.exec.host=gateway`。 - - 如果你想使用宿主机 exec，但仍希望在 allowlist 未命中时进行审核，可使用 `security=allowlist` 搭配 `ask=on-miss`。 - - 如果你希望 `host=auto` 重新解析为 `sandbox`，请启用沙箱模式。 + - 如果你只想要稳定的主机路由，仅设置 `tools.exec.host=gateway`。 + - 如果你希望使用主机 exec，但在 allowlist 未命中时仍进行审查，请使用 `security=allowlist` 搭配 `ask=on-miss`。 + - 如果你希望 `host=auto` 重新解析回 `sandbox`，请启用沙箱模式。 常见日志特征： - `Approval required.` → 命令正在等待 `/approve ...`。 - - `SYSTEM_RUN_DENIED: approval required` → node-host exec 批准仍在等待中。 - - `exec host=sandbox requires a sandbox runtime for this session` → 已隐式/显式选择了 sandbox，但当前会话的沙箱模式已关闭。 + - `SYSTEM_RUN_DENIED: approval required` → node 主机 exec 批准正在等待中。 + - `exec host=sandbox requires a sandbox runtime for this session` → 已隐式 / 显式选择沙箱，但沙箱模式处于关闭状态。 - 深入页面： + 详细页面： - [/tools/exec](/zh-CN/tools/exec) - [/tools/exec-approvals](/zh-CN/tools/exec-approvals) @@ -355,24 +350,24 @@ flowchart TD openclaw doctor ``` - 良好的输出应表现为： + 正常输出通常如下： - - 浏览器状态显示 `running: true`，并已选定某个浏览器/profile。 - - `openclaw` 能启动，或者 `user` 能看到本地 Chrome 标签页。 + - 浏览器状态显示 `running: true`，并且已选定浏览器 / 配置文件。 + - `openclaw` 已启动，或者 `user` 能看到本地 Chrome 标签页。 常见日志特征： - `unknown command "browser"` 或 `unknown command 'browser'` → 设置了 `plugins.allow`，但其中不包含 `browser`。 - `Failed to start Chrome CDP on port` → 本地浏览器启动失败。 - `browser.executablePath not found` → 配置的二进制路径错误。 - - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的 scheme。 - - `browser.cdpUrl has invalid port` → 配置的 CDP URL 使用了错误或超范围的端口。 - - `No Chrome tabs found for profile="user"` → Chrome MCP 附加 profile 没有打开的本地 Chrome 标签页。 - - `Remote CDP for profile "" is not reachable` → 从当前主机无法访问所配置的远程 CDP 端点。 - - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加 profile 没有可用的实时 CDP 目标。 - - attach-only 或远程 CDP profile 上出现过期的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile `，即可关闭当前控制会话并释放仿真状态，而无需重启 gateway。 + - `browser.cdpUrl must be http(s) or ws(s)` → 配置的 CDP URL 使用了不受支持的协议。 + - `browser.cdpUrl has invalid port` → 配置的 CDP URL 端口错误或超出范围。 + - `No Chrome tabs found for profile="user"` → Chrome MCP 附加配置文件没有打开的本地 Chrome 标签页。 + - `Remote CDP for profile "" is not reachable` → 配置的远程 CDP 端点从当前主机无法访问。 + - `Browser attachOnly is enabled ... not reachable` 或 `Browser attachOnly is enabled and CDP websocket ... is not reachable` → 仅附加配置文件没有可用的实时 CDP 目标。 + - 对 attach-only 或远程 CDP 配置文件，若存在陈旧的 viewport / dark-mode / locale / offline 覆盖状态 → 运行 `openclaw browser stop --browser-profile `，关闭当前活动控制会话并释放模拟状态，而无需重启 Gateway 网关。 - 深入页面： + 详细页面： - [/gateway/troubleshooting#browser-tool-fails](/zh-CN/gateway/troubleshooting#browser-tool-fails) - [/tools/browser#missing-browser-command-or-tool](/zh-CN/tools/browser#missing-browser-command-or-tool) @@ -385,8 +380,8 @@ flowchart TD ## 相关内容 -- [常见问题](/zh-CN/help/faq) — 常见问题 -- [Gateway 网关故障排除](/zh-CN/gateway/troubleshooting) — Gateway 网关特定问题 -- [Doctor](/zh-CN/gateway/doctor) — 自动健康检查与修复 -- [渠道故障排除](/zh-CN/channels/troubleshooting) — 渠道连接问题 -- [自动化故障排除](/zh-CN/automation/cron-jobs#troubleshooting) — cron 和 heartbeat 问题 +- [常见问题](/zh-CN/help/faq) — 常见问题解答 +- [Gateway Troubleshooting](/zh-CN/gateway/troubleshooting) — Gateway 网关专属问题 +- [Doctor](/zh-CN/gateway/doctor) — 自动化健康检查与修复 +- [Channel Troubleshooting](/zh-CN/channels/troubleshooting) — 渠道连接问题 +- [Automation Troubleshooting](/zh-CN/automation/cron-jobs#troubleshooting) — cron 和 heartbeat 问题 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index 9b6932b15..2a56f9422 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,27 +1,26 @@ --- read_when: - 为插件导入选择合适的 plugin-sdk 子路径 - - 审查 bundled-plugin 子路径和辅助接口 -summary: 插件 SDK 子路径目录：按领域分组说明各个导入位于何处 -title: Plugin SDK 子路径 + - 审查 bundled-plugin 子路径和辅助接口 surface +summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于哪里 +title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-24T04:27:27Z" + generated_at: "2026-04-24T06:58:59Z" model: gpt-5.4 provider: openai - source_hash: 753c7202a8a59ae9e420d436c7f3770ea455d810f2af52b716d438b84b8b986e + source_hash: ff4b934501a3163e36b402db72dd75a260fe9f849b3823a7a05e4867a1a5e655 source_path: plugins/sdk-subpaths.md workflow: 15 --- - 插件 SDK 以 `openclaw/plugin-sdk/` 下的一组窄子路径形式公开。 - 本页按用途对常用子路径进行归类整理。生成的完整 200+ 子路径列表位于 `scripts/lib/plugin-sdk-entrypoints.json`； - 其中也包含保留给 bundled-plugin 辅助接口的子路径，但除非某个文档页面明确将其作为公开能力推荐，否则它们都属于实现细节。 + 插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径公开。 + 本页按用途对常用子路径进行归类整理。生成的完整清单包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；其中也会列出保留给 bundled-plugin 辅助功能的子路径，但除非某个文档页面明确将其作为公开能力推广，否则它们都属于实现细节。 - 有关插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 - | 子路径 | 关键导出 | + | 子路径 | 关键导出 | | --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `plugin-sdk/plugin-entry` | `definePluginEntry` | | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | @@ -33,183 +32,183 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | + | `plugin-sdk/config-schema` | 根级 `openclaw.json` Zod schema 导出（`OpenClawSchema`） | | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共享的设置向导辅助函数、allowlist 提示、设置状态构建器 | + | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 | | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助函数，以及默认账户回退辅助函数 | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助函数 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助函数 | - | `plugin-sdk/account-helpers` | 窄范围的账户列表 / 账户操作辅助函数 | + | `plugin-sdk/account-core` | 多账户配置 / 操作门控辅助工具、默认账户回退辅助工具 | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 | + | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | + | `plugin-sdk/account-helpers` | 精简的账户列表 / 账户操作辅助工具 | | `plugin-sdk/channel-pairing` | `createChannelPairingController` | | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | | `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 | - | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助函数，并在需要时回退到 bundled contract | - | `plugin-sdk/command-gating` | 窄范围的命令授权门控辅助函数 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助工具，带 bundled-contract 回退 | + | `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助函数 | - | `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助函数 | - | `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助函数 | - | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 | - | `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助函数 | - | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助函数 | - | `plugin-sdk/poll-runtime` | 窄范围的投票规范化辅助函数 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | - | `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 | - | `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对以及已配置绑定辅助函数 | - | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | - | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | - | `plugin-sdk/channel-status` | 共享的渠道状态快照 / 摘要辅助函数 | - | `plugin-sdk/channel-config-primitives` | 窄范围的渠道配置 schema 原语 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 | - | `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助函数 | - | `plugin-sdk/group-access` | 共享的群组访问决策辅助函数 | - | `plugin-sdk/direct-dm` | 共享的直接私信认证 / 守卫辅助函数 | - | `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递以及旧版交互式回复辅助函数。参见 [消息呈现](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 面向兼容性的 barrel，包含入站防抖、提及匹配、提及策略辅助函数以及 envelope 辅助函数 | - | `plugin-sdk/channel-inbound-debounce` | 窄范围的入站防抖辅助函数 | - | `plugin-sdk/channel-mention-gating` | 不包含更大范围入站运行时接口的窄范围提及策略和提及文本辅助函数 | - | `plugin-sdk/channel-envelope` | 窄范围的入站 envelope 格式化辅助函数 | - | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助函数 | - | `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助函数 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助工具 | + | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助工具 | + | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助工具 | + | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助工具 | + | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 | + | `plugin-sdk/outbound-runtime` | 出站身份、发送委托和载荷规划辅助工具 | + | `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 | + | `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 | + | `plugin-sdk/conversation-runtime` | 会话 / 线程绑定、配对和已配置绑定辅助工具 | + | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 | + | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | + | `plugin-sdk/channel-status` | 共享渠道状态快照 / 摘要辅助工具 | + | `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 基元 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | + | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | + | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑 / 读取辅助工具 | + | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | + | `plugin-sdk/direct-dm` | 共享直接私信认证 / 守卫辅助工具 | + | `plugin-sdk/interactive-runtime` | 语义消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | 兼容性 barrel，包含入站去抖、提及匹配、提及策略辅助工具和 envelope 辅助工具 | + | `plugin-sdk/channel-inbound-debounce` | 精简的入站去抖辅助工具 | + | `plugin-sdk/channel-mention-gating` | 精简的提及策略和提及文本辅助工具，不包含更广泛的入站运行时接口 | + | `plugin-sdk/channel-envelope` | 精简的入站 envelope 格式化辅助工具 | + | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 | + | `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing / ack 失败的渠道日志辅助工具 | | `plugin-sdk/channel-send-result` | 回复结果类型 | - | `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 | - | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 | - | `plugin-sdk/channel-contract` | 渠道 contract 类型 | + | `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 | + | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助工具 | + | `plugin-sdk/channel-contract` | 渠道契约类型 | | `plugin-sdk/channel-feedback` | 反馈 / reaction 接线 | - | `plugin-sdk/channel-secret-runtime` | 窄范围的 secret-contract 辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 以及 secret target 类型 | + | `plugin-sdk/channel-secret-runtime` | 精简的 secret 契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 | | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助函数 | - | `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的专用设置辅助函数 | + | `plugin-sdk/provider-setup` | 精选的本地 / 自托管提供商设置辅助工具 | + | `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的聚焦设置辅助工具 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助函数 | - | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置档写入辅助函数，例如 `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-runtime` | 用于提供商插件的运行时 API key 解析辅助工具 | + | `plugin-sdk/provider-auth-api-key` | API key 新手引导 / 配置文件写入辅助工具，例如 `upsertApiKeyProfile` | | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | - | `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助函数 | - | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助函数 | + | `plugin-sdk/provider-auth-login` | 用于提供商插件的共享交互式登录辅助工具 | + | `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 | | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助函数，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助函数 | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及模型 ID 规范化辅助工具，例如 `normalizeNativeXaiModelId` | | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助函数，包括音频转写 multipart form 辅助函数 | - | `plugin-sdk/provider-web-fetch-contract` | 窄范围的 web-fetch 配置 / 选择 contract 辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Web-fetch 提供商注册 / 缓存辅助函数 | - | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的窄范围 web-search 配置 / 凭证辅助函数 | - | `plugin-sdk/provider-web-search-contract` | 窄范围的 web-search 配置 / 凭证 contract 辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及有作用域的凭证 setter / getter | - | `plugin-sdk/provider-web-search` | Web-search 提供商注册 / 缓存 / 运行时辅助函数 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助函数 | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似函数 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 | - | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换以及可写的传输事件流 | - | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 | - | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 | - | `plugin-sdk/group-activation` | 窄范围的群组激活模式和命令解析辅助函数 | + | `plugin-sdk/provider-http` | 通用提供商 HTTP / endpoint 能力辅助工具，包括音频转录 multipart form 辅助工具 | + | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助工具 | + | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精简 web-search 配置 / 凭证辅助工具 | + | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及带作用域的凭证 setter / getter | + | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助工具 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似功能 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助工具 | + | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | + | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助工具 | + | `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助工具 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数、发送者授权辅助函数 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 | | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助函数 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置档 / 过滤器辅助函数 | + | `plugin-sdk/approval-auth-runtime` | 审批者解析和同聊天操作认证辅助工具 | + | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件 / 过滤器辅助工具 | | `plugin-sdk/approval-delivery-runtime` | 原生审批能力 / 投递适配器 | - | `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助函数 | - | `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助函数 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助函数；如果更窄的 adapter / gateway 接口已经足够，优先使用它们 | - | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助函数 | - | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复负载辅助函数 | - | `plugin-sdk/reply-dedupe` | 窄范围的入站回复去重重置辅助函数 | - | `plugin-sdk/channel-contract-testing` | 不包含宽泛 testing barrel 的窄范围渠道 contract 测试辅助函数 | - | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助函数 | - | `plugin-sdk/command-detection` | 共享的命令检测辅助函数 | - | `plugin-sdk/command-primitives-runtime` | 用于热渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令体规范化和命令表面辅助函数 | + | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | + | `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量原生审批适配器加载辅助工具 | + | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更精简的 adapter / gateway 接口已足够，优先使用它们 | + | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | + | `plugin-sdk/approval-reply-runtime` | exec / 插件审批回复载荷辅助工具 | + | `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助工具 | + | `plugin-sdk/channel-contract-testing` | 精简的渠道契约测试辅助工具，不包含宽泛的 testing barrel | + | `plugin-sdk/command-auth-native` | 原生命令认证 + 原生 session target 辅助工具 | + | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | + | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量命令文本谓词 | + | `plugin-sdk/command-surface` | 命令体规范化和命令接口辅助工具 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的窄范围 secret-contract 收集辅助函数 | - | `plugin-sdk/secret-ref-runtime` | 面向 secret-contract / 配置解析的窄范围 `coerceSecretRef` 和 SecretRef 类型辅助函数 | - | `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和 secret 收集辅助函数 | - | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 | - | `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时接口的窄范围固定 dispatcher 辅助函数 | - | `plugin-sdk/ssrf-runtime` | 固定 dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助函数 | - | `plugin-sdk/secret-input` | secret 输入解析辅助函数 | - | `plugin-sdk/webhook-ingress` | Webhook 请求 / 目标辅助函数 | - | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件 secret 接口的精简 secret 契约收集辅助工具 | + | `plugin-sdk/secret-ref-runtime` | 用于 secret 契约 / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 | + | `plugin-sdk/security-runtime` | 共享 trust、私信门控、外部内容和 secret 收集辅助工具 | + | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | + | `plugin-sdk/ssrf-dispatcher` | 精简的 pinned-dispatcher 辅助工具，不包含宽泛的基础设施运行时接口 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch，以及 SSRF 策略辅助工具 | + | `plugin-sdk/secret-input` | secret 输入解析辅助工具 | + | `plugin-sdk/webhook-ingress` | webhook 请求 / 目标辅助工具 | + | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助工具 | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助函数 | - | `plugin-sdk/runtime-env` | 窄范围的运行时环境、日志器、超时、重试和退避辅助函数 | - | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助函数 | + | `plugin-sdk/runtime` | 宽泛的运行时 / 日志 / 备份 / 插件安装辅助工具 | + | `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和 backoff 辅助工具 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享的插件命令 / hook / HTTP / 交互辅助函数 | - | `plugin-sdk/hook-runtime` | 共享的 webhook / 内部 hook 管道辅助函数 | - | `plugin-sdk/lazy-runtime` | 惰性运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程 exec 辅助函数 | - | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助函数 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助函数 | - | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助函数，以及插件配置查找辅助函数 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使 bundled Telegram contract 接口不可用也可使用 | - | `plugin-sdk/text-autolink-runtime` | 不依赖宽泛 text-runtime barrel 的文件引用自动链接检测 | - | `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / 配置档辅助函数、原生路由 / 运行时辅助函数 | - | `plugin-sdk/reply-runtime` | 共享的入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围的回复分发 / 完成辅助函数 | - | `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | 共享插件命令 / hook / http / 交互式辅助工具 | + | `plugin-sdk/hook-runtime` | 共享 webhook / 内部 hook 管道辅助工具 | + | `plugin-sdk/lazy-runtime` | 延迟运行时导入 / 绑定辅助工具，例如 `createLazyRuntimeModule`, `createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程 exec 辅助工具 | + | `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 | + | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助工具，以及插件配置查找辅助工具 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化及重复 / 冲突检查，即使 bundled Telegram 契约接口不可用时也可使用 | + | `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，不包含宽泛的 text-runtime barrel | + | `plugin-sdk/approval-runtime` | exec / 插件审批辅助工具、审批能力构建器、认证 / 配置文件辅助工具、原生路由 / 运行时辅助工具 | + | `plugin-sdk/reply-runtime` | 共享入站 / 回复运行时辅助工具、分块、分发、心跳、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发 / 完成辅助工具 | + | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具，例如 `buildHistoryContext`, `recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | 窄范围的文本 / Markdown 分块辅助函数 | - | `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助函数 | - | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助函数 | - | `plugin-sdk/routing` | 路由 / 会话键 / 账户绑定辅助函数，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | 共享的渠道 / 账户状态摘要辅助函数、运行时状态默认值，以及问题元数据辅助函数 | - | `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助函数 | - | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 | + | `plugin-sdk/reply-chunking` | 精简的文本 / Markdown 分块辅助工具 | + | `plugin-sdk/session-store-runtime` | session store 路径 + updated-at 辅助工具 | + | `plugin-sdk/state-paths` | 状态 / OAuth 目录路径辅助工具 | + | `plugin-sdk/routing` | 路由 / session-key / 账户绑定辅助工具，例如 `resolveAgentRoute`, `buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | 共享渠道 / 账户状态摘要辅助工具、运行时状态默认值，以及 issue 元数据辅助工具 | + | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助工具 | + | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助工具 | | `plugin-sdk/request-url` | 从 fetch / request 类输入中提取字符串 URL | - | `plugin-sdk/run-command` | 带计时功能的命令运行器，返回已规范化的 stdout / stderr 结果 | + | `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout / stderr 结果 | | `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 | - | `plugin-sdk/tool-payload` | 从工具结果对象中提取已规范化的负载 | - | `plugin-sdk/tool-send` | 从工具参数中提取规范的发送目标字段 | - | `plugin-sdk/temp-path` | 共享的临时下载路径辅助函数 | - | `plugin-sdk/logging-core` | 子系统日志器和脱敏辅助函数 | - | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助函数 | - | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助函数 | - | `plugin-sdk/file-lock` | 可重入文件锁辅助函数 | - | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助函数 | - | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助函数 | - | `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 | - | `plugin-sdk/agent-config-primitives` | 窄范围的智能体运行时 config-schema 原语 | - | `plugin-sdk/boolean-param` | 宽松的布尔参数读取器 | - | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | - | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 | - | `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助原语 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 | - | `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助函数 | - | `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助函数 | - | `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层 agent harness 接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数，以及 attempt 结果工具函数 | - | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助函数 | - | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 | - | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助函数 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和固定查找辅助函数 | - | `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入 proxy / guarded-fetch 导入 | - | `plugin-sdk/response-limit-runtime` | 不依赖宽泛 media runtime 接口的有界响应体读取器 | + | `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化载荷 | + | `plugin-sdk/tool-send` | 从工具参数中提取规范化发送目标字段 | + | `plugin-sdk/temp-path` | 共享临时下载路径辅助工具 | + | `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 | + | `plugin-sdk/markdown-table-runtime` | Markdown 表格模式和转换辅助工具 | + | `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 | + | `plugin-sdk/file-lock` | 可重入 file-lock 辅助工具 | + | `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 | + | `plugin-sdk/acp-runtime` | ACP 运行时 / 会话和回复分发辅助工具 | + | `plugin-sdk/acp-binding-resolve-runtime` | 只读 ACP 绑定解析，不引入生命周期启动导入 | + | `plugin-sdk/agent-config-primitives` | 精简的智能体运行时配置 schema 基元 | + | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | + | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | + | `plugin-sdk/device-bootstrap` | 设备 bootstrap 和配对令牌辅助工具 | + | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助基元 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助工具 | + | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助工具 | + | `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助工具 | + | `plugin-sdk/agent-harness` | 面向可信插件的实验性低层智能体 harness 接口：harness 类型、活动运行 steer / abort 辅助工具、OpenClaw 工具桥接辅助工具、工具进度格式化 / 详情辅助工具，以及尝试结果实用工具 | + | `plugin-sdk/provider-zai-endpoint` | Z.A.I endpoint 检测辅助工具 | + | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助工具 | + | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | + | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned lookup 辅助工具 | + | `plugin-sdk/runtime-fetch` | 具备 dispatcher 感知能力的运行时 fetch，不包含 proxy / guarded-fetch 导入 | + | `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不包含宽泛的媒体运行时接口 | | `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 | - | `plugin-sdk/session-store-runtime` | 不引入宽泛配置写入 / 维护导入的会话存储读取辅助函数 | - | `plugin-sdk/context-visibility-runtime` | 不引入宽泛配置 / 安全导入的上下文可见性解析和补充上下文过滤 | - | `plugin-sdk/string-coerce-runtime` | 不依赖 markdown / logging 导入的窄范围原始记录 / 字符串强制转换与规范化辅助函数 | - | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | - | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助函数 | - | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 | + | `plugin-sdk/session-store-runtime` | session-store 读取辅助工具，不包含宽泛的配置写入 / 维护导入 | + | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不包含宽泛的配置 / 安全导入 | + | `plugin-sdk/string-coerce-runtime` | 精简的原始 record / 字符串强制转换与规范化辅助工具，不包含 markdown / 日志导入 | + | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | + | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 | + | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助工具 | | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | @@ -217,64 +216,64 @@ x-i18n: | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享的媒体获取 / 转换 / 存储辅助函数，以及媒体负载构建器 | - | `plugin-sdk/media-store` | 窄范围媒体存储辅助函数，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障切换辅助函数、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图片 / 音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享的文本 / Markdown / 日志辅助函数，例如对智能体可见文本的剥离、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数以及安全文本工具函数 | - | `plugin-sdk/text-chunking` | 出站文本分块辅助函数 | - | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助函数 | - | `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、directive 和规范化辅助函数 | - | `plugin-sdk/realtime-transcription` | 实时转写提供商类型、注册表辅助函数以及共享 WebSocket 会话辅助函数 | - | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 | + | `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助工具，以及媒体载荷构建器 | + | `plugin-sdk/media-store` | 精简的媒体存储辅助工具，例如 `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成功能故障转移辅助工具、候选项选择和缺失模型消息 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本 / Markdown / 日志辅助工具，例如对 assistant 可见文本的剥离、Markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 | + | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | + | `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 | + | `plugin-sdk/speech-core` | 共享语音提供商类型、注册表、directive 和规范化辅助工具 | + | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | + | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 | | `plugin-sdk/image-generation` | 图像生成提供商类型 | - | `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障切换、认证和注册表辅助函数 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助工具 | | `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 | - | `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | | `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 | - | `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障切换辅助函数、提供商查找和 model-ref 解析 | - | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助函数 | - | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助函数 | - | `plugin-sdk/web-media` | 共享的远程 / 本地媒体加载辅助函数 | - | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | + | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 | + | `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 | + | `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 | + | `plugin-sdk/web-media` | 共享远程 / 本地媒体加载辅助工具 | + | `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` | | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于 manager / config / file / CLI 辅助函数 | + | `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于 manager / config / file / CLI 辅助工具 | | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时门面 | | `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 | - | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding contract、注册表访问、本地提供商以及通用批处理 / 远程辅助函数 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用批处理 / 远程辅助工具 | | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD engine 导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储 engine 导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助函数 | - | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助函数 | - | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助函数 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助函数 | - | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助函数 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助函数 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助函数 | - | `plugin-sdk/memory-host-core` | 面向厂商中立的 memory host 核心运行时辅助函数别名 | - | `plugin-sdk/memory-host-events` | 面向厂商中立的 memory host 事件日志辅助函数别名 | - | `plugin-sdk/memory-host-files` | 面向厂商中立的 memory host 文件 / 运行时辅助函数别名 | - | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助函数 | - | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向厂商中立的 memory host 状态辅助函数别名 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory host storage engine 导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 | + | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | + | `plugin-sdk/memory-core-host-secret` | Memory host secret 辅助工具 | + | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | + | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件 / 运行时辅助工具 | + | `plugin-sdk/memory-host-core` | 面向供应商中立的 memory host 核心运行时辅助工具别名 | + | `plugin-sdk/memory-host-events` | 面向供应商中立的 memory host 事件日志辅助工具别名 | + | `plugin-sdk/memory-host-files` | 面向供应商中立的 memory host 文件 / 运行时辅助工具别名 | + | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助工具 | + | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活跃 Memory 运行时门面 | + | `plugin-sdk/memory-host-status` | 面向供应商中立的 memory host 状态辅助工具别名 | | `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 | | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser 插件支持辅助函数（`browser-support` 仍然是兼容性 barrel） | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser 插件支持辅助工具（`browser-support` 仍为兼容性 barrel） | | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | bundled Matrix 辅助 / 运行时接口 | | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE 辅助 / 运行时接口 | | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled IRC 辅助接口 | - | 渠道专用辅助函数 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled 渠道兼容性 / 辅助接口 | - | 认证 / 插件专用辅助函数 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled 功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled 渠道兼容性 / 辅助接口 | + | 认证 / 插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled 功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |