From 00ef214d59d21d383cb8b18b7810ad6b0241693a Mon Sep 17 00:00:00 2001 From: Peter Steinberger Date: Mon, 16 Mar 2026 07:02:46 +0000 Subject: [PATCH] docs: regenerate zh-CN onboarding references --- docs/zh-CN/automation/hooks.md | 539 ++- docs/zh-CN/channels/bluebubbles.md | 237 +- docs/zh-CN/channels/feishu.md | 565 ++- docs/zh-CN/channels/nostr.md | 119 +- docs/zh-CN/channels/synology-chat.md | 138 + docs/zh-CN/cli/index.md | 417 +- docs/zh-CN/cli/onboard.md | 152 +- docs/zh-CN/cli/setup.md | 14 +- docs/zh-CN/concepts/agent-workspace.md | 142 +- docs/zh-CN/concepts/model-providers.md | 501 ++- docs/zh-CN/concepts/models.md | 151 +- docs/zh-CN/concepts/oauth.md | 115 +- docs/zh-CN/gateway/authentication.md | 112 +- docs/zh-CN/gateway/configuration-reference.md | 3103 ++++++++++++++ docs/zh-CN/gateway/configuration.md | 3770 +++-------------- docs/zh-CN/gateway/local-models.md | 78 +- docs/zh-CN/gateway/multiple-gateways.md | 78 +- docs/zh-CN/help/faq.md | 4 +- docs/zh-CN/install/exe-dev.md | 68 +- docs/zh-CN/install/index.md | 296 +- docs/zh-CN/install/installer.md | 452 +- docs/zh-CN/install/macos-vm.md | 158 +- docs/zh-CN/platforms/digitalocean.md | 160 +- docs/zh-CN/platforms/index.md | 32 +- docs/zh-CN/platforms/linux.md | 35 +- docs/zh-CN/platforms/raspberry-pi.md | 267 +- docs/zh-CN/platforms/windows.md | 155 +- docs/zh-CN/providers/anthropic.md | 200 +- docs/zh-CN/providers/cloudflare-ai-gateway.md | 78 + docs/zh-CN/providers/glm.md | 39 +- docs/zh-CN/providers/huggingface.md | 216 + docs/zh-CN/providers/index.md | 46 +- docs/zh-CN/providers/kilocode.md | 80 + docs/zh-CN/providers/litellm.md | 160 + docs/zh-CN/providers/minimax.md | 156 +- docs/zh-CN/providers/mistral.md | 61 + docs/zh-CN/providers/models.md | 40 +- docs/zh-CN/providers/moonshot.md | 69 +- docs/zh-CN/providers/nvidia.md | 62 + docs/zh-CN/providers/ollama.md | 251 +- docs/zh-CN/providers/openai.md | 282 +- docs/zh-CN/providers/opencode-go.md | 52 + docs/zh-CN/providers/opencode.md | 60 +- docs/zh-CN/providers/openrouter.md | 21 +- docs/zh-CN/providers/qianfan.md | 45 +- docs/zh-CN/providers/sglang.md | 111 + docs/zh-CN/providers/synthetic.md | 86 +- docs/zh-CN/providers/together.md | 72 + docs/zh-CN/providers/venice.md | 255 +- docs/zh-CN/providers/vercel-ai-gateway.md | 35 +- docs/zh-CN/providers/xiaomi.md | 25 +- docs/zh-CN/providers/zai.md | 42 +- docs/zh-CN/reference/wizard.md | 243 +- docs/zh-CN/start/getting-started.md | 271 +- docs/zh-CN/start/onboarding-overview.md | 58 + docs/zh-CN/start/wizard-cli-automation.md | 222 + docs/zh-CN/start/wizard-cli-reference.md | 306 ++ docs/zh-CN/start/wizard.md | 371 +- docs/zh-CN/tools/plugin.md | 1283 +++++- 59 files changed, 10929 insertions(+), 6227 deletions(-) create mode 100644 docs/zh-CN/channels/synology-chat.md create mode 100644 docs/zh-CN/gateway/configuration-reference.md create mode 100644 docs/zh-CN/providers/cloudflare-ai-gateway.md create mode 100644 docs/zh-CN/providers/huggingface.md create mode 100644 docs/zh-CN/providers/kilocode.md create mode 100644 docs/zh-CN/providers/litellm.md create mode 100644 docs/zh-CN/providers/mistral.md create mode 100644 docs/zh-CN/providers/nvidia.md create mode 100644 docs/zh-CN/providers/opencode-go.md create mode 100644 docs/zh-CN/providers/sglang.md create mode 100644 docs/zh-CN/providers/together.md create mode 100644 docs/zh-CN/start/onboarding-overview.md create mode 100644 docs/zh-CN/start/wizard-cli-automation.md create mode 100644 docs/zh-CN/start/wizard-cli-reference.md diff --git a/docs/zh-CN/automation/hooks.md b/docs/zh-CN/automation/hooks.md index b5806e2bdd0..b0615569eec 100644 --- a/docs/zh-CN/automation/hooks.md +++ b/docs/zh-CN/automation/hooks.md @@ -1,60 +1,61 @@ --- read_when: - - 你想为 /new、/reset、/stop 和智能体生命周期事件实现事件驱动自动化 - - 你想构建、安装或调试 hooks + - 你希望为 `/new`、`/reset`、`/stop` 和智能体生命周期事件使用事件驱动自动化 + - 你希望构建、安装或调试 Hooks summary: Hooks：用于命令和生命周期事件的事件驱动自动化 title: Hooks x-i18n: - generated_at: "2026-02-03T07:50:59Z" - model: claude-opus-4-5 - provider: pi - source_hash: 853227a0f1abd20790b425fa64dda60efc6b5f93c1b13ecd2dcb788268f71d79 + generated_at: "2026-03-16T06:21:34Z" + model: gpt-5.4 + provider: openai + source_hash: fc1370a05127d778eb685f687ee9a52062aa6f5c895e80152b9de41c3a02c592 source_path: automation/hooks.md workflow: 15 --- # Hooks -Hooks 提供了一个可扩展的事件驱动系统，用于响应智能体命令和事件自动执行操作。Hooks 从目录中自动发现，可以通过 CLI 命令管理，类似于 OpenClaw 中 Skills 的工作方式。 +Hooks 提供了一个可扩展的事件驱动系统，用于在响应智能体命令和事件时自动执行操作。Hooks 会从目录中自动发现，并且可以通过 CLI 命令进行管理，方式与 OpenClaw 中的 Skills 类似。 -## 入门指南 +## 熟悉基础 -Hooks 是在事件发生时运行的小脚本。有两种类型： +Hooks 是在某些事情发生时运行的小脚本。它们有两种类型： -- **Hooks**（本页）：当智能体事件触发时在 Gateway 网关内运行，如 `/new`、`/reset`、`/stop` 或生命周期事件。 -- **Webhooks**：外部 HTTP webhooks，让其他系统触发 OpenClaw 中的工作。参见 [Webhook Hooks](/automation/webhook) 或使用 `openclaw webhooks` 获取 Gmail 助手命令。 +- **Hooks**（本页）：当智能体事件触发时，在 Gateway 网关内运行，例如 `/new`、`/reset`、`/stop` 或生命周期事件。 +- **Webhooks**：外部 HTTP webhook，可让其他系统在 OpenClaw 中触发工作。请参阅 [Webhook Hooks](/automation/webhook)，或使用 `openclaw webhooks` 获取 Gmail 辅助命令。 -Hooks 也可以捆绑在插件中；参见 [插件](/tools/plugin#plugin-hooks)。 +Hooks 也可以打包在插件中；请参阅 [Plugins](/tools/plugin#plugin-hooks)。 常见用途： -- 重置会话时保存记忆快照 -- 保留命令审计跟踪用于故障排除或合规 -- 会话开始或结束时触发后续自动化 -- 事件触发时向智能体工作区写入文件或调用外部 API +- 当你重置会话时保存一份内存快照 +- 为故障排除或合规保留命令审计轨迹 +- 当会话开始或结束时触发后续自动化 +- 当事件触发时，将文件写入智能体工作区或调用外部 API -如果你能写一个小的 TypeScript 函数，你就能写一个 hook。Hooks 会自动发现，你可以通过 CLI 启用或禁用它们。 +如果你会写一个小型 TypeScript 函数，你就能编写一个 hook。Hooks 会被自动发现，你可以通过 CLI 启用或禁用它们。 -## 概述 +## 概览 -hooks 系统允许你： +Hooks 系统允许你： -- 在发出 `/new` 时将会话上下文保存到记忆 +- 当发出 `/new` 时，将会话上下文保存到 memory - 记录所有命令以供审计 - 在智能体生命周期事件上触发自定义自动化 - 在不修改核心代码的情况下扩展 OpenClaw 的行为 -## 入门 +## 入门指南 -### 捆绑的 Hooks +### 内置 Hooks -OpenClaw 附带三个自动发现的捆绑 hooks： +OpenClaw 自带四个会被自动发现的内置 hook： -- **💾 session-memory**：当你发出 `/new` 时将会话上下文保存到智能体工作区（默认 `~/.openclaw/workspace/memory/`） +- **💾 session-memory**：当你发出 `/new` 时，将会话上下文保存到你的智能体工作区（默认是 `~/.openclaw/workspace/memory/`） +- **📎 bootstrap-extra-files**：在 `agent:bootstrap` 期间，从已配置的 glob/路径模式中注入额外的工作区引导文件 - **📝 command-logger**：将所有命令事件记录到 `~/.openclaw/logs/commands.log` - **🚀 boot-md**：当 Gateway 网关启动时运行 `BOOT.md`（需要启用内部 hooks） -列出可用的 hooks： +列出可用 hooks： ```bash openclaw hooks list @@ -80,35 +81,40 @@ openclaw hooks info session-memory ### 新手引导 -在新手引导期间（`openclaw onboard`），你将被提示启用推荐的 hooks。向导会自动发现符合条件的 hooks 并呈现供选择。 +在新手引导期间（`openclaw onboard`），系统会提示你启用推荐的 hooks。向导会自动发现符合条件的 hooks 并供你选择。 ## Hook 发现 -Hooks 从三个目录自动发现（按优先级顺序）： +Hooks 会从三个目录中自动发现（按优先级顺序）： -1. **工作区 hooks**：`/hooks/`（每智能体，最高优先级） -2. **托管 hooks**：`~/.openclaw/hooks/`（用户安装，跨工作区共享） -3. **捆绑 hooks**：`/dist/hooks/bundled/`（随 OpenClaw 附带） +1. **工作区 hooks**：`/hooks/`（每个智能体单独配置，优先级最高） +2. **托管 hooks**：`~/.openclaw/hooks/`（用户安装，在各工作区之间共享） +3. **内置 hooks**：`/dist/hooks/bundled/`（随 OpenClaw 一起提供） -托管 hook 目录可以是**单个 hook** 或 **hook 包**（包目录）。 +托管 hook 目录既可以是 **单个 hook**，也可以是 **hook 包**（包目录）。 -每个 hook 是一个包含以下内容的目录： +每个 hook 都是一个包含以下内容的目录： ``` my-hook/ ├── HOOK.md # 元数据 + 文档 -└── handler.ts # 处理程序实现 +└── handler.ts # 处理器实现 ``` -## Hook 包（npm/archives） +## Hook 包（npm/归档） -Hook 包是标准的 npm 包，通过 `package.json` 中的 `openclaw.hooks` 导出一个或多个 hooks。使用以下命令安装： +Hook 包是标准的 npm 包，它们通过 `package.json` 中的 `openclaw.hooks` 导出一个或多个 hook。使用以下命令安装它们： ```bash openclaw hooks install ``` -示例 `package.json`： +npm spec 仅支持注册表形式（包名 + 可选的精确版本或 dist-tag）。 +Git/URL/file spec 和 semver 范围会被拒绝。 + +裸 spec 和 `@latest` 会保持在稳定轨道上。如果 npm 将其中任意一种解析为预发布版本，OpenClaw 会停止并要求你通过预发布标签（例如 `@beta`/`@rc`）或精确的预发布版本显式选择加入。 + +`package.json` 示例： ```json { @@ -120,19 +126,23 @@ openclaw hooks install } ``` -每个条目指向包含 `HOOK.md` 和 `handler.ts`（或 `index.ts`）的 hook 目录。 -Hook 包可以附带依赖；它们将安装在 `~/.openclaw/hooks/` 下。 +每个条目都指向一个包含 `HOOK.md` 和 `handler.ts`（或 `index.ts`）的 hook 目录。 +Hook 包可以携带依赖；它们会安装到 `~/.openclaw/hooks/` 下。 +每个 `openclaw.hooks` 条目在解析符号链接后都必须保持在包目录内部；超出目录范围的条目会被拒绝。 + +安全说明：`openclaw hooks install` 会使用 `npm install --ignore-scripts` 安装依赖 +（不运行生命周期脚本）。请保持 hook 包依赖树为“纯 JS/TS”，并避免依赖 `postinstall` 构建的包。 ## Hook 结构 ### HOOK.md 格式 -`HOOK.md` 文件在 YAML frontmatter 中包含元数据，加上 Markdown 文档： +`HOOK.md` 文件包含 YAML frontmatter 中的元数据以及 Markdown 文档： ```markdown --- name: my-hook -description: "Short description of what this hook does" +description: "关于此 hook 功能的简短描述" homepage: https://docs.openclaw.ai/automation/hooks#my-hook metadata: { "openclaw": { "emoji": "🔗", "events": ["command:new"], "requires": { "bins": ["node"] } } } @@ -140,49 +150,47 @@ metadata: # My Hook -Detailed documentation goes here... +详细文档写在这里…… -## What It Does +## 它的作用 -- Listens for `/new` commands -- Performs some action -- Logs the result +- 监听 `/new` 命令 +- 执行某些操作 +- 记录结果 -## Requirements +## 要求 -- Node.js must be installed +- 必须安装 Node.js -## Configuration +## 配置 -No configuration needed. +无需配置。 ``` ### 元数据字段 `metadata.openclaw` 对象支持： -- **`emoji`**：CLI 的显示表情符号（例如 `"💾"`） +- **`emoji`**：CLI 显示用 emoji（例如 `"💾"`） - **`events`**：要监听的事件数组（例如 `["command:new", "command:reset"]`） - **`export`**：要使用的命名导出（默认为 `"default"`） - **`homepage`**：文档 URL - **`requires`**：可选要求 - - **`bins`**：PATH 中需要的二进制文件（例如 `["git", "node"]`） - - **`anyBins`**：这些二进制文件中至少有一个必须存在 - - **`env`**：需要的环境变量 - - **`config`**：需要的配置路径（例如 `["workspace.dir"]`） - - **`os`**：需要的平台（例如 `["darwin", "linux"]`） + - **`bins`**：PATH 中必须存在的二进制文件（例如 `["git", "node"]`） + - **`anyBins`**：这些二进制文件中至少要存在一个 + - **`env`**：必需的环境变量 + - **`config`**：必需的配置路径（例如 `["workspace.dir"]`） + - **`os`**：支持的平台（例如 `["darwin", "linux"]`） - **`always`**：绕过资格检查（布尔值） -- **`install`**：安装方法（对于捆绑 hooks：`[{"id":"bundled","kind":"bundled"}]`） +- **`install`**：安装方式（对于内置 hooks：`[{"id":"bundled","kind":"bundled"}]`） -### 处理程序实现 +### 处理器实现 -`handler.ts` 文件导出一个 `HookHandler` 函数： +`handler.ts` 文件会导出一个 `HookHandler` 函数： ```typescript -import type { HookHandler } from "../../src/hooks/hooks.js"; - -const myHandler: HookHandler = async (event) => { - // Only trigger on 'new' command +const myHandler = async (event) => { + // 仅在 'new' 命令时触发 if (event.type !== "command" || event.action !== "new") { return; } @@ -191,9 +199,9 @@ const myHandler: HookHandler = async (event) => { console.log(` Session: ${event.sessionKey}`); console.log(` Timestamp: ${event.timestamp.toISOString()}`); - // Your custom logic here + // 你的自定义逻辑写在这里 - // Optionally send message to user + // 可选：向用户发送消息 event.messages.push("✨ My hook executed!"); }; @@ -202,24 +210,31 @@ export default myHandler; #### 事件上下文 -每个事件包含： +每个事件都包含： ```typescript { - type: 'command' | 'session' | 'agent' | 'gateway', - action: string, // e.g., 'new', 'reset', 'stop' - sessionKey: string, // Session identifier - timestamp: Date, // When the event occurred - messages: string[], // Push messages here to send to user + type: 'command' | 'session' | 'agent' | 'gateway' | 'message', + action: string, // 例如 'new'、'reset'、'stop'、'received'、'sent' + sessionKey: string, // 会话标识符 + timestamp: Date, // 事件发生时间 + messages: string[], // 将消息推入这里以发送给用户 context: { + // 命令事件： sessionEntry?: SessionEntry, sessionId?: string, sessionFile?: string, - commandSource?: string, // e.g., 'whatsapp', 'telegram' + commandSource?: string, // 例如 'whatsapp'、'telegram' senderId?: string, workspaceDir?: string, bootstrapFiles?: WorkspaceBootstrapFile[], - cfg?: OpenClawConfig + cfg?: OpenClawConfig, + // 消息事件（完整详情见“消息事件”部分）： + from?: string, // message:received + to?: string, // message:sent + content?: string, + channelId?: string, + success?: boolean, // message:sent } } ``` @@ -228,28 +243,135 @@ export default myHandler; ### 命令事件 -当发出智能体命令时触发： +在发出智能体命令时触发： - **`command`**：所有命令事件（通用监听器） -- **`command:new`**：当发出 `/new` 命令时 -- **`command:reset`**：当发出 `/reset` 命令时 -- **`command:stop`**：当发出 `/stop` 命令时 +- **`command:new`**：发出 `/new` 命令时 +- **`command:reset`**：发出 `/reset` 命令时 +- **`command:stop`**：发出 `/stop` 命令时 + +### 会话事件 + +- **`session:compact:before`**：在压缩开始总结历史记录之前 +- **`session:compact:after`**：在压缩完成并带有摘要元数据之后 + +内部 hook 负载会将这些事件表示为 `type: "session"`，并将 `action` 设为 `"compact:before"` / `"compact:after"`；监听器使用上面的组合键进行订阅。 +具体处理器注册使用字面量键格式 `${type}:${action}`。对于这些事件，请注册 `session:compact:before` 和 `session:compact:after`。 ### 智能体事件 -- **`agent:bootstrap`**：在注入工作区引导文件之前（hooks 可以修改 `context.bootstrapFiles`） +- **`agent:bootstrap`**：在工作区引导文件被注入之前（hooks 可以修改 `context.bootstrapFiles`） ### Gateway 网关事件 -当 Gateway 网关启动时触发： +在 Gateway 网关启动时触发： -- **`gateway:startup`**：在渠道启动和 hooks 加载之后 +- **`gateway:startup`**：在渠道启动且 hooks 已加载之后 + +### 消息事件 + +在消息被接收或发送时触发： + +- **`message`**：所有消息事件（通用监听器） +- **`message:received`**：当从任意渠道收到入站消息时。在处理的早期阶段触发，此时媒体理解尚未完成。对于尚未处理的媒体附件，内容中可能包含类似 `` 的原始占位符。 +- **`message:transcribed`**：当一条消息已被完全处理，包括音频转写和链接理解时触发。此时，`transcript` 包含音频消息的完整转写文本。当你需要访问已转写的音频内容时，请使用此 hook。 +- **`message:preprocessed`**：在所有媒体 + 链接理解完成后，为每条消息触发，使 hooks 可以在智能体看到消息之前访问完全增强的正文（转写、图像描述、链接摘要）。 +- **`message:sent`**：当出站消息成功发送时 + +#### 消息事件上下文 + +消息事件包含关于消息的丰富上下文： + +```typescript +// message:received context +{ + from: string, // 发送者标识符（电话号码、用户 ID 等） + content: string, // 消息内容 + timestamp?: number, // 接收时的 Unix 时间戳 + channelId: string, // 渠道（例如 "whatsapp"、"telegram"、"discord"） + accountId?: string, // 多账号设置中的提供商账号 ID + conversationId?: string, // 聊天/会话 ID + messageId?: string, // 提供商返回的消息 ID + metadata?: { // 额外的提供商特定数据 + to?: string, + provider?: string, + surface?: string, + threadId?: string, + senderId?: string, + senderName?: string, + senderUsername?: string, + senderE164?: string, + } +} + +// message:sent context +{ + to: string, // 接收者标识符 + content: string, // 已发送的消息内容 + success: boolean, // 发送是否成功 + error?: string, // 如果发送失败，则为错误消息 + channelId: string, // 渠道（例如 "whatsapp"、"telegram"、"discord"） + accountId?: string, // 提供商账号 ID + conversationId?: string, // 聊天/会话 ID + messageId?: string, // 提供商返回的消息 ID + isGroup?: boolean, // 此出站消息是否属于群组/渠道上下文 + groupId?: string, // 用于与 message:received 关联的群组/渠道标识符 +} + +// message:transcribed context +{ + body?: string, // 增强前的原始入站正文 + bodyForAgent?: string, // 对智能体可见的增强正文 + transcript: string, // 音频转写文本 + channelId: string, // 渠道（例如 "telegram"、"whatsapp"） + conversationId?: string, + messageId?: string, +} + +// message:preprocessed context +{ + body?: string, // 原始入站正文 + bodyForAgent?: string, // 媒体/链接理解后的最终增强正文 + transcript?: string, // 存在音频时的转写内容 + channelId: string, // 渠道（例如 "telegram"、"whatsapp"） + conversationId?: string, + messageId?: string, + isGroup?: boolean, + groupId?: string, +} +``` + +#### 示例：消息记录器 Hook + +```typescript +const isMessageReceivedEvent = (event: { type: string; action: string }) => + event.type === "message" && event.action === "received"; +const isMessageSentEvent = (event: { type: string; action: string }) => + event.type === "message" && event.action === "sent"; + +const handler = async (event) => { + if (isMessageReceivedEvent(event as { type: string; action: string })) { + console.log(`[message-logger] Received from ${event.context.from}: ${event.context.content}`); + } else if (isMessageSentEvent(event as { type: string; action: string })) { + console.log(`[message-logger] Sent to ${event.context.to}: ${event.context.content}`); + } +}; + +export default handler; +``` ### 工具结果 Hooks（插件 API） -这些 hooks 不是事件流监听器；它们让插件在 OpenClaw 持久化工具结果之前同步调整它们。 +这些 hooks 不是事件流监听器；它们允许插件在 OpenClaw 持久化工具结果之前同步调整工具结果。 -- **`tool_result_persist`**：在工具结果写入会话记录之前转换它们。必须是同步的；返回更新后的工具结果负载或 `undefined` 保持原样。参见 [智能体循环](/concepts/agent-loop)。 +- **`tool_result_persist`**：在工具结果写入会话转录之前对其进行转换。必须是同步的；返回更新后的工具结果负载，或返回 `undefined` 以保持原样。请参阅 [Agent Loop](/concepts/agent-loop)。 + +### 插件 Hook 事件 + +通过插件 hook 运行器公开的压缩生命周期 hooks： + +- **`before_compaction`**：在压缩前运行，并带有计数/token 元数据 +- **`after_compaction`**：在压缩后运行，并带有压缩摘要元数据 ### 未来事件 @@ -258,14 +380,12 @@ export default myHandler; - **`session:start`**：当新会话开始时 - **`session:end`**：当会话结束时 - **`agent:error`**：当智能体遇到错误时 -- **`message:sent`**：当消息被发送时 -- **`message:received`**：当消息被接收时 ## 创建自定义 Hooks ### 1. 选择位置 -- **工作区 hooks**（`/hooks/`）：每智能体，最高优先级 +- **工作区 hooks**（`/hooks/`）：每个智能体单独配置，优先级最高 - **托管 hooks**（`~/.openclaw/hooks/`）：跨工作区共享 ### 2. 创建目录结构 @@ -280,27 +400,25 @@ cd ~/.openclaw/hooks/my-hook ```markdown --- name: my-hook -description: "Does something useful" +description: "执行某些有用的事情" metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } } --- # My Custom Hook -This hook does something useful when you issue `/new`. +当你发出 `/new` 时，此 hook 会执行一些有用的事情。 ``` ### 4. 创建 handler.ts ```typescript -import type { HookHandler } from "../../src/hooks/hooks.js"; - -const handler: HookHandler = async (event) => { +const handler = async (event) => { if (event.type !== "command" || event.action !== "new") { return; } console.log("[my-hook] Running!"); - // Your logic here + // 你的逻辑写在这里 }; export default handler; @@ -309,16 +427,16 @@ export default handler; ### 5. 启用并测试 ```bash -# Verify hook is discovered +# 验证 hook 已被发现 openclaw hooks list -# Enable it +# 启用它 openclaw hooks enable my-hook -# Restart your gateway process (menu bar app restart on macOS, or restart your dev process) +# 重启你的 Gateway 网关进程（macOS 上重启菜单栏应用，或重启你的开发进程） -# Trigger the event -# Send /new via your messaging channel +# 触发事件 +# 通过你的消息渠道发送 /new ``` ## 配置 @@ -339,9 +457,9 @@ openclaw hooks enable my-hook } ``` -### 每 Hook 配置 +### 每个 Hook 的配置 -Hooks 可以有自定义配置： +Hooks 可以具有自定义配置： ```json { @@ -378,9 +496,9 @@ Hooks 可以有自定义配置： } ``` -### 遗留配置格式（仍然支持） +### 旧版配置格式（仍受支持） -旧配置格式仍然有效以保持向后兼容： +旧配置格式仍可用于向后兼容： ```json { @@ -399,74 +517,76 @@ Hooks 可以有自定义配置： } ``` -**迁移**：对新 hooks 使用基于发现的新系统。遗留处理程序在基于目录的 hooks 之后加载。 +注意：`module` 必须是相对于工作区的路径。绝对路径和超出工作区范围的遍历路径会被拒绝。 + +**迁移**：对于新的 hooks，请使用基于发现的新系统。旧版 handlers 会在基于目录的 hooks 之后加载。 ## CLI 命令 ### 列出 Hooks ```bash -# List all hooks +# 列出所有 hooks openclaw hooks list -# Show only eligible hooks +# 仅显示符合条件的 hooks openclaw hooks list --eligible -# Verbose output (show missing requirements) +# 详细输出（显示缺失的要求） openclaw hooks list --verbose -# JSON output +# JSON 输出 openclaw hooks list --json ``` ### Hook 信息 ```bash -# Show detailed info about a hook +# 显示某个 hook 的详细信息 openclaw hooks info session-memory -# JSON output +# JSON 输出 openclaw hooks info session-memory --json ``` ### 检查资格 ```bash -# Show eligibility summary +# 显示资格摘要 openclaw hooks check -# JSON output +# JSON 输出 openclaw hooks check --json ``` ### 启用/禁用 ```bash -# Enable a hook +# 启用一个 hook openclaw hooks enable session-memory -# Disable a hook +# 禁用一个 hook openclaw hooks disable command-logger ``` -## 捆绑的 Hooks +## 内置 hook 参考 ### session-memory -当你发出 `/new` 时将会话上下文保存到记忆。 +当你发出 `/new` 时，将会话上下文保存到 memory。 **事件**：`command:new` **要求**：必须配置 `workspace.dir` -**输出**：`/memory/YYYY-MM-DD-slug.md`（默认为 `~/.openclaw/workspace`） +**输出**：`/memory/YYYY-MM-DD-slug.md`（默认是 `~/.openclaw/workspace`） -**功能**： +**它的作用**： -1. 使用预重置会话条目定位正确的记录 -2. 提取最后 15 行对话 -3. 使用 LLM 生成描述性文件名 slug -4. 将会话元数据保存到带日期的记忆文件 +1. 使用重置前的会话条目定位正确的转录 +2. 提取最近 15 行对话 +3. 使用 LLM 生成描述性的文件名 slug +4. 将会话元数据保存到带日期的 memory 文件中 **示例输出**： @@ -482,7 +602,7 @@ openclaw hooks disable command-logger - `2026-01-16-vendor-pitch.md` - `2026-01-16-api-design.md` -- `2026-01-16-1430.md`（如果 slug 生成失败则回退到时间戳） +- `2026-01-16-1430.md`（如果 slug 生成失败，则回退为时间戳） **启用**： @@ -490,9 +610,50 @@ openclaw hooks disable command-logger openclaw hooks enable session-memory ``` +### bootstrap-extra-files + +在 `agent:bootstrap` 期间注入额外的引导文件（例如 monorepo 本地的 `AGENTS.md` / `TOOLS.md`）。 + +**事件**：`agent:bootstrap` + +**要求**：必须配置 `workspace.dir` + +**输出**：不写入文件；仅在内存中修改引导上下文。 + +**配置**： + +```json +{ + "hooks": { + "internal": { + "enabled": true, + "entries": { + "bootstrap-extra-files": { + "enabled": true, + "paths": ["packages/*/AGENTS.md", "packages/*/TOOLS.md"] + } + } + } + } +} +``` + +**说明**： + +- 路径相对于工作区解析。 +- 文件必须保持在工作区内部（通过 realpath 检查）。 +- 仅加载已识别的引导基础文件名。 +- 会保留子智能体允许列表（仅 `AGENTS.md` 和 `TOOLS.md`）。 + +**启用**： + +```bash +openclaw hooks enable bootstrap-extra-files +``` + ### command-logger -将所有命令事件记录到集中审计文件。 +将所有命令事件记录到集中式审计文件。 **事件**：`command` @@ -500,10 +661,10 @@ openclaw hooks enable session-memory **输出**：`~/.openclaw/logs/commands.log` -**功能**： +**它的作用**： 1. 捕获事件详情（命令操作、时间戳、会话键、发送者 ID、来源） -2. 以 JSONL 格式追加到日志文件 +2. 以 JSONL 格式附加到日志文件 3. 在后台静默运行 **示例日志条目**： @@ -516,13 +677,13 @@ openclaw hooks enable session-memory **查看日志**： ```bash -# View recent commands +# 查看最近的命令 tail -n 20 ~/.openclaw/logs/commands.log -# Pretty-print with jq +# 使用 jq 美化输出 cat ~/.openclaw/logs/commands.log | jq . -# Filter by action +# 按操作筛选 grep '"action":"new"' ~/.openclaw/logs/commands.log | jq . ``` @@ -534,18 +695,18 @@ openclaw hooks enable command-logger ### boot-md -当 Gateway 网关启动时运行 `BOOT.md`（在渠道启动之后）。 -必须启用内部 hooks 才能运行。 +当 Gateway 网关启动时（渠道启动之后）运行 `BOOT.md`。 +必须启用内部 hooks，此功能才会运行。 **事件**：`gateway:startup` **要求**：必须配置 `workspace.dir` -**功能**： +**它的作用**： 1. 从你的工作区读取 `BOOT.md` -2. 通过智能体运行器运行指令 -3. 通过 message 工具发送任何请求的出站消息 +2. 通过智能体运行器执行其中的指令 +3. 通过消息工具发送任何请求的出站消息 **启用**： @@ -555,26 +716,26 @@ openclaw hooks enable boot-md ## 最佳实践 -### 保持处理程序快速 +### 保持处理器快速 -Hooks 在命令处理期间运行。保持它们轻量： +Hooks 在命令处理期间运行。请保持其轻量： ```typescript -// ✓ Good - async work, returns immediately +// ✓ 好 - 异步工作，立即返回 const handler: HookHandler = async (event) => { - void processInBackground(event); // Fire and forget + void processInBackground(event); // 触发后不等待 }; -// ✗ Bad - blocks command processing +// ✗ 差 - 阻塞命令处理 const handler: HookHandler = async (event) => { await slowDatabaseQuery(event); await evenSlowerAPICall(event); }; ``` -### 优雅处理错误 +### 优雅地处理错误 -始终包装有风险的操作： +始终包装高风险操作： ```typescript const handler: HookHandler = async (event) => { @@ -582,112 +743,117 @@ const handler: HookHandler = async (event) => { await riskyOperation(event); } catch (err) { console.error("[my-handler] Failed:", err instanceof Error ? err.message : String(err)); - // Don't throw - let other handlers run + // 不要抛出错误 - 让其他处理器继续运行 } }; ``` ### 尽早过滤事件 -如果事件不相关则尽早返回： +如果事件不相关，请尽早返回： ```typescript const handler: HookHandler = async (event) => { - // Only handle 'new' commands + // 仅处理 'new' 命令 if (event.type !== "command" || event.action !== "new") { return; } - // Your logic here + // 你的逻辑写在这里 }; ``` -### 使用特定事件键 +### 使用具体事件键 -尽可能在元数据中指定确切事件： +如果可能，请在元数据中指定精确事件： ```yaml -metadata: { "openclaw": { "events": ["command:new"] } } # Specific +metadata: { "openclaw": { "events": ["command:new"] } } # 精确 ``` 而不是： ```yaml -metadata: { "openclaw": { "events": ["command"] } } # General - more overhead +metadata: { "openclaw": { "events": ["command"] } } # 通用 - 开销更大 ``` ## 调试 ### 启用 Hook 日志 -Gateway 网关在启动时记录 hook 加载： +Gateway 网关会在启动时记录 hook 加载情况： ``` Registered hook: session-memory -> command:new +Registered hook: bootstrap-extra-files -> agent:bootstrap Registered hook: command-logger -> command Registered hook: boot-md -> gateway:startup ``` -### 检查发现 +### 检查发现情况 -列出所有发现的 hooks： +列出所有已发现的 hooks： ```bash openclaw hooks list --verbose ``` -### 检查注册 +### 检查注册情况 -在你的处理程序中，记录它被调用的时间： +在你的处理器中，记录它何时被调用： ```typescript const handler: HookHandler = async (event) => { console.log("[my-handler] Triggered:", event.type, event.action); - // Your logic + // 你的逻辑 }; ``` ### 验证资格 -检查为什么 hook 不符合条件： +检查某个 hook 为什么不符合条件： ```bash openclaw hooks info my-hook ``` -在输出中查找缺失的要求。 +查看输出中缺失的要求。 ## 测试 ### Gateway 网关日志 -监控 Gateway 网关日志以查看 hook 执行： +监控 Gateway 网关日志以查看 hook 执行情况： ```bash # macOS ./scripts/clawlog.sh -f -# Other platforms +# 其他平台 tail -f ~/.openclaw/gateway.log ``` ### 直接测试 Hooks -隔离测试你的处理程序： +单独测试你的 handlers： ```typescript import { test } from "vitest"; -import { createHookEvent } from "./src/hooks/hooks.js"; import myHandler from "./hooks/my-hook/handler.js"; test("my handler works", async () => { - const event = createHookEvent("command", "new", "test-session", { - foo: "bar", - }); + const event = { + type: "command", + action: "new", + sessionKey: "test-session", + timestamp: new Date(), + messages: [], + context: { foo: "bar" }, + }; await myHandler(event); - // Assert side effects + // 断言副作用 }); ``` @@ -696,8 +862,8 @@ test("my handler works", async () => { ### 核心组件 - **`src/hooks/types.ts`**：类型定义 -- **`src/hooks/workspace.ts`**：目录扫描和加载 -- **`src/hooks/frontmatter.ts`**：HOOK.md 元数据解析 +- **`src/hooks/workspace.ts`**：目录扫描与加载 +- **`src/hooks/frontmatter.ts`**：`HOOK.md` 元数据解析 - **`src/hooks/config.ts`**：资格检查 - **`src/hooks/hooks-status.ts`**：状态报告 - **`src/hooks/loader.ts`**：动态模块加载器 @@ -710,15 +876,15 @@ test("my handler works", async () => { ``` Gateway 网关启动 ↓ -扫描目录（工作区 → 托管 → 捆绑） +扫描目录（工作区 → 托管 → 内置） ↓ 解析 HOOK.md 文件 ↓ 检查资格（bins、env、config、os） ↓ -从符合条件的 hooks 加载处理程序 +从符合条件的 hooks 加载 handlers ↓ -为事件注册处理程序 +为事件注册 handlers ``` ### 事件流程 @@ -726,11 +892,11 @@ Gateway 网关启动 ``` 用户发送 /new ↓ -命令验证 +命令校验 ↓ 创建 hook 事件 ↓ -触发 hook（所有注册的处理程序） +触发 hook（所有已注册的 handlers） ↓ 命令处理继续 ↓ @@ -745,17 +911,18 @@ Gateway 网关启动 ```bash ls -la ~/.openclaw/hooks/my-hook/ - # Should show: HOOK.md, handler.ts + # 应显示：HOOK.md, handler.ts ``` 2. 验证 HOOK.md 格式： ```bash cat ~/.openclaw/hooks/my-hook/HOOK.md - # Should have YAML frontmatter with name and metadata + # 应包含带有 name 和 metadata 的 YAML frontmatter ``` -3. 列出所有发现的 hooks： +3. 列出所有已发现的 hooks： + ```bash openclaw hooks list ``` @@ -768,12 +935,12 @@ Gateway 网关启动 openclaw hooks info my-hook ``` -查找缺失的： +查看是否缺少： - 二进制文件（检查 PATH） - 环境变量 - 配置值 -- 操作系统兼容性 +- OS 兼容性 ### Hook 未执行 @@ -781,30 +948,31 @@ openclaw hooks info my-hook ```bash openclaw hooks list - # Should show ✓ next to enabled hooks + # 应在已启用的 hooks 旁显示 ✓ ``` 2. 重启你的 Gateway 网关进程以重新加载 hooks。 3. 检查 Gateway 网关日志中的错误： + ```bash ./scripts/clawlog.sh | grep hook ``` -### 处理程序错误 +### 处理器错误 检查 TypeScript/import 错误： ```bash -# Test import directly +# 直接测试导入 node -e "import('./path/to/handler.ts').then(console.log)" ``` ## 迁移指南 -### 从遗留配置到发现 +### 从旧版配置迁移到发现机制 -**之前**： +**迁移前**： ```json { @@ -822,7 +990,7 @@ node -e "import('./path/to/handler.ts').then(console.log)" } ``` -**之后**： +**迁移后**： 1. 创建 hook 目录： @@ -836,13 +1004,13 @@ node -e "import('./path/to/handler.ts').then(console.log)" ```markdown --- name: my-hook - description: "My custom hook" + description: "我的自定义 hook" metadata: { "openclaw": { "emoji": "🎯", "events": ["command:new"] } } --- # My Hook - Does something useful. + 执行某些有用的事情。 ``` 3. 更新配置： @@ -861,9 +1029,10 @@ node -e "import('./path/to/handler.ts').then(console.log)" ``` 4. 验证并重启你的 Gateway 网关进程： + ```bash openclaw hooks list - # Should show: 🎯 my-hook ✓ + # 应显示：🎯 my-hook ✓ ``` **迁移的好处**： @@ -876,7 +1045,7 @@ node -e "import('./path/to/handler.ts').then(console.log)" ## 另请参阅 -- [CLI 参考：hooks](/cli/hooks) -- [捆绑 Hooks README](https://github.com/openclaw/openclaw/tree/main/src/hooks/bundled) +- [CLI Reference: hooks](/cli/hooks) +- [Bundled Hooks README](https://github.com/openclaw/openclaw/tree/main/src/hooks/bundled) - [Webhook Hooks](/automation/webhook) -- [配置](/gateway/configuration#hooks) +- [Configuration](/gateway/configuration#hooks) diff --git a/docs/zh-CN/channels/bluebubbles.md b/docs/zh-CN/channels/bluebubbles.md index 4ee4cb71e3e..b7f8534065b 100644 --- a/docs/zh-CN/channels/bluebubbles.md +++ b/docs/zh-CN/channels/bluebubbles.md @@ -6,34 +6,35 @@ read_when: summary: 通过 BlueBubbles macOS 服务器使用 iMessage（REST 发送/接收、输入状态、回应、配对、高级操作）。 title: BlueBubbles x-i18n: - generated_at: "2026-02-03T10:04:52Z" - model: claude-opus-4-5 - provider: pi - source_hash: 3aae277a8bec479800a7f6268bfbca912c65a4aadc6e513694057fb873597b69 + generated_at: "2026-03-16T06:21:08Z" + model: gpt-5.4 + provider: openai + source_hash: 877592bf7b9b06abdddd7567d56e756eff229d6ffa5056ef33fa3356086aa580 source_path: channels/bluebubbles.md workflow: 15 --- # BlueBubbles（macOS REST） -状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其更丰富的 API 和更简便的设置，**推荐用于 iMessage 集成**，优于旧版 imsg 渠道。 +状态：内置插件，通过 HTTP 与 BlueBubbles macOS 服务器通信。由于其 API 更丰富且设置比旧版 imsg 渠道更简单，**推荐用于 iMessage 集成**。 -## 概述 +## 概览 - 通过 BlueBubbles 辅助应用在 macOS 上运行（[bluebubbles.app](https://bluebubbles.app)）。 -- 推荐/已测试版本：macOS Sequoia (15)。macOS Tahoe (26) 可用；但在 Tahoe 上编辑功能目前不可用，群组图标更新可能显示成功但实际未同步。 -- OpenClaw 通过其 REST API 与之通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。 -- 传入消息通过 webhook 到达；发出的回复、输入指示器、已读回执和 tapback 均为 REST 调用。 -- 附件和贴纸作为入站媒体被接收（并在可能时呈现给智能体）。 -- 配对/白名单的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。 -- 回应作为系统事件呈现，与 Slack/Telegram 类似，智能体可以在回复前"提及"它们。 +- 推荐/已测试：macOS Sequoia（15）。macOS Tahoe（26）可用；目前编辑功能在 Tahoe 上已损坏，群组图标更新可能会报告成功但不会同步。 +- OpenClaw 通过其 REST API 与其通信（`GET /api/v1/ping`、`POST /message/text`、`POST /chat/:id/*`）。 +- 传入消息通过 webhook 到达；传出回复、输入状态指示、已读回执和 tapback 都通过 REST 调用完成。 +- 附件和贴纸会作为入站媒体接收（并在可能时展示给智能体）。 +- 配对/allowlist 的工作方式与其他渠道相同（`/channels/pairing` 等），使用 `channels.bluebubbles.allowFrom` + 配对码。 +- 回应会像 Slack/Telegram 一样作为系统事件呈现，因此智能体可以在回复前“提及”它们。 - 高级功能：编辑、撤回、回复线程、消息效果、群组管理。 ## 快速开始 -1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 的说明操作）。 -2. 在 BlueBubbles 配置中，启用 web API 并设置密码。 +1. 在你的 Mac 上安装 BlueBubbles 服务器（按照 [bluebubbles.app/install](https://bluebubbles.app/install) 上的说明操作）。 +2. 在 BlueBubbles 配置中启用 Web API 并设置密码。 3. 运行 `openclaw onboard` 并选择 BlueBubbles，或手动配置： + ```json5 { channels: { @@ -46,8 +47,89 @@ x-i18n: }, } ``` + 4. 将 BlueBubbles webhook 指向你的 Gateway 网关（示例：`https://your-gateway-host:3000/bluebubbles-webhook?password=`）。 -5. 启动 Gateway 网关；它将注册 webhook 处理程序并开始配对。 +5. 启动 Gateway 网关；它会注册 webhook 处理器并开始配对。 + +安全说明： + +- 始终设置 webhook 密码。 +- 始终要求进行 webhook 身份验证。无论 loopback/代理拓扑如何，除非 BlueBubbles webhook 请求包含与 `channels.bluebubbles.password` 匹配的 password/guid（例如 `?password=` 或 `x-password`），否则 OpenClaw 会拒绝该请求。 +- 在读取/解析完整 webhook 请求体之前就会检查密码身份验证。 + +## 保持 Messages.app 处于活动状态（VM / 无头设置） + +某些 macOS VM / 常开设置可能会导致 Messages.app 进入“空闲”状态（传入事件会停止，直到应用被打开/切到前台）。一个简单的解决方法是使用 AppleScript + LaunchAgent **每 5 分钟“触碰”一次 Messages**。 + +### 1）保存 AppleScript + +将以下内容保存为： + +- `~/Scripts/poke-messages.scpt` + +示例脚本（非交互式；不会抢占焦点）： + +```applescript +try + tell application "Messages" + if not running then + launch + end if + + -- Touch the scripting interface to keep the process responsive. + set _chatCount to (count of chats) + end tell +on error + -- Ignore transient failures (first-run prompts, locked session, etc). +end try +``` + +### 2）安装 LaunchAgent + +将以下内容保存为： + +- `~/Library/LaunchAgents/com.user.poke-messages.plist` + +```xml + + + + + Label + com.user.poke-messages + + ProgramArguments + + /bin/bash + -lc + /usr/bin/osascript "$HOME/Scripts/poke-messages.scpt" + + + RunAtLoad + + + StartInterval + 300 + + StandardOutPath + /tmp/poke-messages.log + StandardErrorPath + /tmp/poke-messages.err + + +``` + +说明： + +- 这会**每 300 秒**运行一次，并且**在登录时**运行。 +- 首次运行可能会触发 macOS 的**自动化**权限提示（`osascript` → Messages）。请在运行该 LaunchAgent 的同一用户会话中批准这些提示。 + +加载它： + +```bash +launchctl unload ~/Library/LaunchAgents/com.user.poke-messages.plist 2>/dev/null || true +launchctl load ~/Library/LaunchAgents/com.user.poke-messages.plist +``` ## 新手引导 @@ -60,10 +142,10 @@ openclaw onboard 向导会提示输入： - **服务器 URL**（必填）：BlueBubbles 服务器地址（例如 `http://192.168.1.100:1234`） -- **密码**（必填）：来自 BlueBubbles 服务器设置的 API 密码 +- **密码**（必填）：来自 BlueBubbles Server 设置的 API 密码 - **Webhook 路径**（可选）：默认为 `/bluebubbles-webhook` -- **私信策略**：配对、白名单、开放或禁用 -- **白名单**：电话号码、电子邮件或聊天目标 +- **私信策略**：pairing、allowlist、open 或 disabled +- **允许列表**：电话号码、电子邮件或聊天目标 你也可以通过 CLI 添加 BlueBubbles： @@ -75,12 +157,12 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor 私信： -- 默认：`channels.bluebubbles.dmPolicy = "pairing"`。 -- 未知发送者会收到配对码；在批准之前消息会被忽略（配对码 1 小时后过期）。 -- 批准方式： +- 默认值：`channels.bluebubbles.dmPolicy = "pairing"`。 +- 未知发送者会收到一个配对码；在获得批准前，消息会被忽略（代码 1 小时后过期）。 +- 通过以下方式批准： - `openclaw pairing list bluebubbles` - `openclaw pairing approve bluebubbles ` -- 配对是默认的令牌交换方式。详情：[配对](/channels/pairing) +- 配对是默认的令牌交换方式。详情见：[配对](/channels/pairing) 群组： @@ -89,13 +171,13 @@ openclaw channels add bluebubbles --http-url http://192.168.1.100:1234 --passwor ### 提及门控（群组） -BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： +BlueBubbles 支持群聊中的提及门控，与 iMessage/WhatsApp 的行为一致： - 使用 `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）检测提及。 -- 当群组启用 `requireMention` 时，智能体仅在被提及时响应。 +- 当某个群组启用 `requireMention` 时，智能体只有在被提及时才会响应。 - 来自授权发送者的控制命令会绕过提及门控。 -单群组配置： +每群组配置： ```json5 { @@ -104,8 +186,8 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： groupPolicy: "allowlist", groupAllowFrom: ["+15555550123"], groups: { - "*": { requireMention: true }, // 所有群组的默认设置 - "iMessage;-;chat123": { requireMention: false }, // 特定群组的覆盖设置 + "*": { requireMention: true }, // 所有群组的默认值 + "iMessage;-;chat123": { requireMention: false }, // 对特定群组覆盖 }, }, }, @@ -115,14 +197,14 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： ### 命令门控 - 控制命令（例如 `/config`、`/model`）需要授权。 -- 使用 `allowFrom` 和 `groupAllowFrom` 确定命令授权。 -- 授权发送者即使在群组中未被提及也可以运行控制命令。 +- 使用 `allowFrom` 和 `groupAllowFrom` 来判断命令授权。 +- 授权发送者即使在群组中未提及，也可以运行控制命令。 ## 输入状态 + 已读回执 -- **输入指示器**：在响应生成前和生成期间自动发送。 +- **输入状态指示**：会在生成响应之前和期间自动发送。 - **已读回执**：由 `channels.bluebubbles.sendReadReceipts` 控制（默认：`true`）。 -- **输入指示器**：OpenClaw 发送输入开始事件；BlueBubbles 在发送或超时时自动清除输入状态（通过 DELETE 手动停止不可靠）。 +- **输入状态指示**：OpenClaw 会发送输入开始事件；BlueBubbles 会在发送后或超时后自动清除输入状态（通过 DELETE 手动停止并不可靠）。 ```json5 { @@ -136,7 +218,7 @@ BlueBubbles 支持群聊的提及门控，与 iMessage/WhatsApp 行为一致： ## 高级操作 -BlueBubbles 在配置中启用时支持高级消息操作： +在配置中启用后，BlueBubbles 支持高级消息操作： ```json5 { @@ -144,15 +226,15 @@ BlueBubbles 在配置中启用时支持高级消息操作： bluebubbles: { actions: { reactions: true, // tapback（默认：true） - edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上不可用） + edit: true, // 编辑已发送消息（macOS 13+，在 macOS 26 Tahoe 上已损坏） unsend: true, // 撤回消息（macOS 13+） - reply: true, // 通过消息 GUID 进行回复线程 + reply: true, // 按消息 GUID 回复线程 sendWithEffect: true, // 消息效果（slam、loud 等） renameGroup: true, // 重命名群聊 setGroupIcon: true, // 设置群聊图标/照片（在 macOS 26 Tahoe 上不稳定） - addParticipant: true, // 将参与者添加到群组 + addParticipant: true, // 向群组添加参与者 removeParticipant: true, // 从群组移除参与者 - leaveGroup: true, // 离开群聊 + leaveGroup: true, // 退出群聊 sendAttachment: true, // 发送附件/媒体 }, }, @@ -163,37 +245,37 @@ BlueBubbles 在配置中启用时支持高级消息操作： 可用操作： - **react**：添加/移除 tapback 回应（`messageId`、`emoji`、`remove`） -- **edit**：编辑已发送的消息（`messageId`、`text`） +- **edit**：编辑已发送消息（`messageId`、`text`） - **unsend**：撤回消息（`messageId`） - **reply**：回复特定消息（`messageId`、`text`、`to`） - **sendWithEffect**：带 iMessage 效果发送（`text`、`to`、`effectId`） - **renameGroup**：重命名群聊（`chatGuid`、`displayName`） -- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）— 在 macOS 26 Tahoe 上不稳定（API 可能返回成功但图标未同步）。 -- **addParticipant**：将某人添加到群组（`chatGuid`、`address`） -- **removeParticipant**：将某人从群组移除（`chatGuid`、`address`） -- **leaveGroup**：离开群聊（`chatGuid`） +- **setGroupIcon**：设置群聊图标/照片（`chatGuid`、`media`）——在 macOS 26 Tahoe 上不稳定（API 可能返回成功，但图标不会同步）。 +- **addParticipant**：向群组添加某人（`chatGuid`、`address`） +- **removeParticipant**：从群组移除某人（`chatGuid`、`address`） +- **leaveGroup**：退出群聊（`chatGuid`） - **sendAttachment**：发送媒体/文件（`to`、`buffer`、`filename`、`asVoice`） - - 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，以 iMessage 语音消息形式发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。 + - 语音备忘录：将 `asVoice: true` 与 **MP3** 或 **CAF** 音频一起设置，即可作为 iMessage 语音消息发送。BlueBubbles 在发送语音备忘录时会将 MP3 转换为 CAF。 -### 消息 ID（短格式 vs 完整格式） +### 消息 ID（短 ID 与完整 ID） OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。 - `MessageSid` / `ReplyToId` 可以是短 ID。 - `MessageSidFull` / `ReplyToIdFull` 包含提供商的完整 ID。 -- 短 ID 存储在内存中；它们可能在重启或缓存清除后过期。 -- 操作接受短或完整的 `messageId`，但如果短 ID 不再可用将会报错。 +- 短 ID 存在于内存中；它们可能会在重启或缓存清除后失效。 +- 操作接受短或完整 `messageId`，但如果短 ID 不再可用，就会报错。 对于持久化自动化和存储，请使用完整 ID： - 模板：`{{MessageSidFull}}`、`{{ReplyToIdFull}}` - 上下文：入站负载中的 `MessageSidFull` / `ReplyToIdFull` -参见[配置](/gateway/configuration)了解模板变量。 +模板变量请参见[配置](/gateway/configuration)。 ## 分块流式传输 -控制响应是作为单条消息发送还是分块流式传输： +控制响应是作为单条消息发送，还是按块流式发送： ```json5 { @@ -208,8 +290,8 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。 ## 媒体 + 限制 - 入站附件会被下载并存储在媒体缓存中。 -- 媒体上限通过 `channels.bluebubbles.mediaMaxMb` 设置（默认：8 MB）。 -- 出站文本按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 字符）。 +- 通过 `channels.bluebubbles.mediaMaxMb` 控制入站和出站媒体大小上限（默认：8 MB）。 +- 出站文本会按 `channels.bluebubbles.textChunkLimit` 分块（默认：4000 个字符）。 ## 配置参考 @@ -217,22 +299,23 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。 提供商选项： -- `channels.bluebubbles.enabled`：启用/禁用渠道。 +- `channels.bluebubbles.enabled`：启用/禁用该渠道。 - `channels.bluebubbles.serverUrl`：BlueBubbles REST API 基础 URL。 - `channels.bluebubbles.password`：API 密码。 - `channels.bluebubbles.webhookPath`：Webhook 端点路径（默认：`/bluebubbles-webhook`）。 - `channels.bluebubbles.dmPolicy`：`pairing | allowlist | open | disabled`（默认：`pairing`）。 -- `channels.bluebubbles.allowFrom`：私信白名单（句柄、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。 +- `channels.bluebubbles.allowFrom`：私信 allowlist（handle、电子邮件、E.164 号码、`chat_id:*`、`chat_guid:*`）。 - `channels.bluebubbles.groupPolicy`：`open | allowlist | disabled`（默认：`allowlist`）。 -- `channels.bluebubbles.groupAllowFrom`：群组发送者白名单。 -- `channels.bluebubbles.groups`：单群组配置（`requireMention` 等）。 +- `channels.bluebubbles.groupAllowFrom`：群组发送者 allowlist。 +- `channels.bluebubbles.groups`：每群组配置（`requireMention` 等）。 - `channels.bluebubbles.sendReadReceipts`：发送已读回执（默认：`true`）。 -- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复必需）。 -- `channels.bluebubbles.textChunkLimit`：出站分块大小（字符）（默认：4000）。 -- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时分割；`newline` 在长度分块前先按空行（段落边界）分割。 -- `channels.bluebubbles.mediaMaxMb`：入站媒体上限（MB）（默认：8）。 -- `channels.bluebubbles.historyLimit`：上下文的最大群组消息数（0 表示禁用）。 -- `channels.bluebubbles.dmHistoryLimit`：私信历史限制。 +- `channels.bluebubbles.blockStreaming`：启用分块流式传输（默认：`false`；流式回复所必需）。 +- `channels.bluebubbles.textChunkLimit`：出站分块大小（按字符计，默认：4000）。 +- `channels.bluebubbles.chunkMode`：`length`（默认）仅在超过 `textChunkLimit` 时拆分；`newline` 会先按空行（段落边界）拆分，再按长度分块。 +- `channels.bluebubbles.mediaMaxMb`：入站/出站媒体大小上限（MB，默认：8）。 +- `channels.bluebubbles.mediaLocalRoots`：允许用于出站本地媒体路径的绝对本地目录显式 allowlist。默认情况下，本地路径发送会被拒绝，除非配置了此项。每账户覆盖：`channels.bluebubbles.accounts..mediaLocalRoots`。 +- `channels.bluebubbles.historyLimit`：用于上下文的最大群组消息数（0 表示禁用）。 +- `channels.bluebubbles.dmHistoryLimit`：私信历史记录上限。 - `channels.bluebubbles.actions`：启用/禁用特定操作。 - `channels.bluebubbles.accounts`：多账户配置。 @@ -241,31 +324,31 @@ OpenClaw 可能会显示*短*消息 ID（例如 `1`、`2`）以节省 token。 - `agents.list[].groupChat.mentionPatterns`（或 `messages.groupChat.mentionPatterns`）。 - `messages.responsePrefix`。 -## 地址 / 投递目标 +## 寻址 / 送达目标 -优先使用 `chat_guid` 以获得稳定的路由： +优先使用 `chat_guid` 以获得稳定路由： -- `chat_guid:iMessage;-;+15555550123`（群组推荐） +- `chat_guid:iMessage;-;+15555550123`（群组首选） - `chat_id:123` - `chat_identifier:...` -- 直接句柄：`+15555550123`、`user@example.com` - - 如果直接句柄没有现有的私信聊天，OpenClaw 将通过 `POST /api/v1/chat/new` 创建一个。这需要启用 BlueBubbles Private API。 +- 直接 handle：`+15555550123`、`user@example.com` + - 如果某个直接 handle 没有现有私信聊天，OpenClaw 会通过 `POST /api/v1/chat/new` 创建一个。这要求启用 BlueBubbles Private API。 -## 安全性 +## 安全 -- Webhook 请求通过比较 `guid`/`password` 查询参数或头部与 `channels.bluebubbles.password` 进行身份验证。来自 `localhost` 的请求也会被接受。 -- 保持 API 密码和 webhook 端点的机密性（将它们视为凭证）。 -- localhost 信任意味着同主机的反向代理可能无意中绕过密码验证。如果你使用代理 Gateway 网关，请在代理处要求身份验证并配置 `gateway.trustedProxies`。参见 [Gateway 网关安全性](/gateway/security#reverse-proxy-configuration)。 -- 如果将 BlueBubbles 服务器暴露在局域网之外，请启用 HTTPS + 防火墙规则。 +- 通过将查询参数或请求头中的 `guid`/`password` 与 `channels.bluebubbles.password` 进行比较来验证 webhook 请求。来自 `localhost` 的请求也会被接受。 +- 请妥善保管 API 密码和 webhook 端点（将它们视为凭证）。 +- 对 localhost 的信任意味着同主机上的反向代理可能会无意中绕过密码。如果你对 Gateway 网关进行了代理，请在代理层要求身份验证，并配置 `gateway.trustedProxies`。请参见 [Gateway 网关安全](/gateway/security#reverse-proxy-configuration)。 +- 如果要在局域网外暴露 BlueBubbles 服务器，请启用 HTTPS + 防火墙规则。 ## 故障排除 -- 如果输入/已读事件停止工作，请检查 BlueBubbles webhook 日志并验证 Gateway 网关路径是否与 `channels.bluebubbles.webhookPath` 匹配。 -- 配对码在一小时后过期；使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles `。 -- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；确保服务器版本支持它。 -- 编辑/撤回需要 macOS 13+ 和兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前不可用。 -- 在 macOS 26（Tahoe）上群组图标更新可能不稳定：API 可能返回成功但新图标未同步。 -- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知不可用的操作。如果在 macOS 26（Tahoe）上编辑仍然显示，请使用 `channels.bluebubbles.actions.edit=false` 手动禁用。 -- 查看状态/健康信息：`openclaw status --all` 或 `openclaw status --deep`。 +- 如果输入状态/已读事件停止工作，请检查 BlueBubbles webhook 日志，并验证 Gateway 网关路径与 `channels.bluebubbles.webhookPath` 一致。 +- 配对码会在一小时后过期；使用 `openclaw pairing list bluebubbles` 和 `openclaw pairing approve bluebubbles `。 +- 回应需要 BlueBubbles private API（`POST /api/v1/message/react`）；请确保服务器版本提供该接口。 +- 编辑/撤回需要 macOS 13+ 以及兼容的 BlueBubbles 服务器版本。在 macOS 26（Tahoe）上，由于 private API 变更，编辑功能目前已损坏。 +- 群组图标更新在 macOS 26（Tahoe）上可能不稳定：API 可能返回成功，但新图标不会同步。 +- OpenClaw 会根据 BlueBubbles 服务器的 macOS 版本自动隐藏已知损坏的操作。如果在 macOS 26（Tahoe）上仍显示编辑操作，请手动使用 `channels.bluebubbles.actions.edit=false` 禁用它。 +- 状态/健康信息请使用：`openclaw status --all` 或 `openclaw status --deep`。 -有关通用渠道工作流参考，请参阅[渠道](/channels)和[插件](/tools/plugin)指南。 +有关通用渠道工作流程参考，请参见 [Channels](/channels) 和 [Plugins](/tools/plugin) 指南。 diff --git a/docs/zh-CN/channels/feishu.md b/docs/zh-CN/channels/feishu.md index 6a8d8633af9..af561e3a8ea 100644 --- a/docs/zh-CN/channels/feishu.md +++ b/docs/zh-CN/channels/feishu.md @@ -1,22 +1,29 @@ --- -summary: "飞书机器人支持状态、功能和配置" read_when: - - 您想要连接飞书机器人 - - 您正在配置飞书渠道 + - 你想连接一个飞书/Lark 机器人 + - 你正在配置飞书渠道 +summary: 飞书机器人概览、功能和配置 title: 飞书 +x-i18n: + generated_at: "2026-03-16T06:21:11Z" + model: gpt-5.4 + provider: openai + source_hash: 951e78c5c7264471382f863fa896a15ddeaf0717ef782da20d0f1b3eb23396ba + source_path: channels/feishu.md + workflow: 15 --- # 飞书机器人 -状态：生产就绪，支持机器人私聊和群组。使用 WebSocket 长连接模式接收消息。 +飞书（Lark）是企业用于消息沟通与协作的团队聊天平台。此插件通过平台的 WebSocket 事件订阅将 OpenClaw 连接到飞书/Lark 机器人，因此无需暴露公共 webhook URL 即可接收消息。 --- -## 内置插件 +## 捆绑插件 -当前版本的 OpenClaw 已内置 Feishu 插件，因此通常不需要单独安装。 +飞书随当前的 OpenClaw 版本一同捆绑提供，因此无需单独安装插件。 -如果你使用的是较旧版本，或是没有内置 Feishu 的自定义安装，可手动安装： +如果你使用的是较旧版本，或使用了不包含捆绑飞书的自定义安装，请手动安装： ```bash openclaw plugins install @openclaw/feishu @@ -26,75 +33,75 @@ openclaw plugins install @openclaw/feishu ## 快速开始 -添加飞书渠道有两种方式： +有两种方式可添加飞书渠道： -### 方式一：通过安装向导添加（推荐） +### 方法 1：设置向导（推荐） -如果您刚安装完 OpenClaw，可以直接运行向导，根据提示添加飞书： +如果你刚安装 OpenClaw，请运行设置向导： ```bash openclaw onboard ``` -向导会引导您完成： +向导会引导你完成以下步骤： -1. 创建飞书应用并获取凭证 -2. 配置应用凭证 -3. 启动网关 +1. 创建飞书应用并收集凭证 +2. 在 OpenClaw 中配置应用凭证 +3. 启动 Gateway 网关 -✅ **完成配置后**，您可以使用以下命令检查网关状态： +✅ **配置完成后**，检查 Gateway 网关状态： -- `openclaw gateway status` - 查看网关运行状态 -- `openclaw logs --follow` - 查看实时日志 +- `openclaw gateway status` +- `openclaw logs --follow` -### 方式二：通过命令行添加 +### 方法 2：CLI 设置 -如果您已经完成了初始安装，可以用以下命令添加飞书渠道： +如果你已经完成初始安装，可通过 CLI 添加该渠道： ```bash openclaw channels add ``` -然后根据交互式提示选择 Feishu，输入 App ID 和 App Secret 即可。 +选择 **Feishu**，然后输入 App ID 和 App Secret。 -✅ **完成配置后**，您可以使用以下命令管理网关： +✅ **配置完成后**，管理 Gateway 网关： -- `openclaw gateway status` - 查看网关运行状态 -- `openclaw gateway restart` - 重启网关以应用新配置 -- `openclaw logs --follow` - 查看实时日志 +- `openclaw gateway status` +- `openclaw gateway restart` +- `openclaw logs --follow` --- -## 第一步：创建飞书应用 +## 第 1 步：创建飞书应用 ### 1. 打开飞书开放平台 -访问 [飞书开放平台](https://open.feishu.cn/app)，使用飞书账号登录。 +访问 [Feishu Open Platform](https://open.feishu.cn/app) 并登录。 -Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设置 `domain: "lark"`。 +Lark（国际版）租户应使用 [https://open.larksuite.com/app](https://open.larksuite.com/app)，并在飞书配置中设置 `domain: "lark"`。 ### 2. 创建应用 -1. 点击 **创建企业自建应用** +1. 点击 **Create enterprise app** 2. 填写应用名称和描述 3. 选择应用图标 -![创建企业自建应用](/images/feishu-step2-create-app.png) +![Create enterprise app](../images/feishu-step2-create-app.png) -### 3. 获取应用凭证 +### 3. 复制凭证 -在应用的 **凭证与基础信息** 页面，复制： +在 **Credentials & Basic Info** 中，复制： -- **App ID**（格式如 `cli_xxx`） +- **App ID**（格式：`cli_xxx`） - **App Secret** -❗ **重要**：请妥善保管 App Secret，不要分享给他人。 +❗ **重要：**请将 App Secret 妥善保密。 -![获取应用凭证](/images/feishu-step3-credentials.png) +![Get credentials](../images/feishu-step3-credentials.png) -### 4. 配置应用权限 +### 4. 配置权限 -在 **权限管理** 页面，点击 **批量导入** 按钮，粘贴以下 JSON 配置一键导入所需权限： +在 **Permissions** 中，点击 **Batch import** 并粘贴： ```json { @@ -105,81 +112,71 @@ Lark（国际版）请使用 https://open.larksuite.com/app，并在配置中设 "application:application.app_message_stats.overview:readonly", "application:application:self_manage", "application:bot.menu:write", + "cardkit:card:read", "cardkit:card:write", "contact:user.employee_id:readonly", "corehr:file:download", - "docs:document.content:read", "event:ip_list", - "im:chat", "im:chat.access_event.bot_p2p_chat:read", "im:chat.members:bot_access", "im:message", "im:message.group_at_msg:readonly", - "im:message.group_msg", "im:message.p2p_msg:readonly", "im:message:readonly", "im:message:send_as_bot", - "im:resource", - "sheets:spreadsheet", - "wiki:wiki:readonly" + "im:resource" ], "user": ["aily:file:read", "aily:file:write", "im:chat.access_event.bot_p2p_chat:read"] } } ``` -![配置应用权限](/images/feishu-step4-permissions.png) +![Configure permissions](../images/feishu-step4-permissions.png) ### 5. 启用机器人能力 -在 **应用能力** > **机器人** 页面： +在 **App Capability** > **Bot** 中： -1. 开启机器人能力 -2. 配置机器人名称 +1. 启用机器人能力 +2. 设置机器人名称 -![启用机器人能力](/images/feishu-step5-bot-capability.png) +![Enable bot capability](../images/feishu-step5-bot-capability.png) ### 6. 配置事件订阅 -⚠️ **重要提醒**：在配置事件订阅前，请务必确保已完成以下步骤： +⚠️ **重要：**在设置事件订阅前，请确保： -1. 运行 `openclaw channels add` 添加了 Feishu 渠道 -2. 网关处于启动状态（可通过 `openclaw gateway status` 检查状态） +1. 你已经为飞书运行过 `openclaw channels add` +2. Gateway 网关正在运行（`openclaw gateway status`） -在 **事件订阅** 页面： +在 **Event Subscription** 中： -1. 选择 **使用长连接接收事件**（WebSocket 模式） -2. 添加事件： - - `im.message.receive_v1` - - `im.message.reaction.created_v1` - - `im.message.reaction.deleted_v1` - - `application.bot.menu_v6` +1. 选择 **Use long connection to receive events**（WebSocket） +2. 添加事件：`im.message.receive_v1` -⚠️ **注意**：如果网关未启动或渠道未添加，长连接设置将保存失败。 +⚠️ 如果 Gateway 网关未运行，长连接设置可能无法保存。 -![配置事件订阅](/images/feishu-step6-event-subscription.png) +![Configure event subscription](../images/feishu-step6-event-subscription.png) ### 7. 发布应用 -1. 在 **版本管理与发布** 页面创建版本 +1. 在 **Version Management & Release** 中创建版本 2. 提交审核并发布 -3. 等待管理员审批（企业自建应用通常自动通过） +3. 等待管理员批准（企业应用通常会自动批准） --- -## 第二步：配置 OpenClaw +## 第 2 步：配置 OpenClaw -### 通过向导配置（推荐） - -运行以下命令，根据提示粘贴 App ID 和 App Secret： +### 使用向导配置（推荐） ```bash openclaw channels add ``` -选择 **Feishu**，然后输入您在第一步获取的凭证即可。 +选择 **Feishu**，然后粘贴你的 App ID 和 App Secret。 -### 通过配置文件配置 +### 通过配置文件进行配置 编辑 `~/.openclaw/openclaw.json`： @@ -193,7 +190,7 @@ openclaw channels add main: { appId: "cli_xxx", appSecret: "xxx", - botName: "我的AI助手", + botName: "My AI assistant", }, }, }, @@ -201,18 +198,20 @@ openclaw channels add } ``` -若使用 `connectionMode: "webhook"`，需设置 `verificationToken`。飞书 Webhook 服务默认绑定 `127.0.0.1`；仅在需要不同监听地址时设置 `webhookHost`。 +如果你使用 `connectionMode: "webhook"`，请同时设置 `verificationToken` 和 `encryptKey`。飞书 webhook 服务器默认绑定到 `127.0.0.1`；只有在你明确需要不同绑定地址时，才设置 `webhookHost`。 -#### 获取 Verification Token（仅 Webhook 模式） +#### Verification Token 和 Encrypt Key（webhook 模式） -使用 Webhook 模式时，需在配置中设置 `channels.feishu.verificationToken`。获取方式： +使用 webhook 模式时，请在配置中同时设置 `channels.feishu.verificationToken` 和 `channels.feishu.encryptKey`。获取这些值的方法如下： -1. 在飞书开放平台打开您的应用 -2. 进入 **开发配置** → **事件与回调** -3. 打开 **加密策略** 选项卡 -4. 复制 **Verification Token**（校验令牌） +1. 在飞书开放平台中，打开你的应用 +2. 前往 **Development** → **Events & Callbacks**（开发配置 → 事件与回调） +3. 打开 **Encryption** 标签页（加密策略） +4. 复制 **Verification Token** 和 **Encrypt Key** -![Verification Token 位置](/images/feishu-verification-token.png) +下图展示了 **Verification Token** 的位置。**Encrypt Key** 位于同一个 **Encryption** 区域中。 + +![Verification Token location](../images/feishu-verification-token.png) ### 通过环境变量配置 @@ -223,7 +222,7 @@ export FEISHU_APP_SECRET="xxx" ### Lark（国际版）域名 -如果您的租户在 Lark（国际版），请设置域名为 `lark`（或完整域名），可配置 `channels.feishu.domain` 或 `channels.feishu.accounts..domain`： +如果你的租户位于 Lark（国际版），请将域名设置为 `lark`（或完整域名字串）。你可以在 `channels.feishu.domain` 设置，也可以按账户设置（`channels.feishu.accounts..domain`）。 ```json5 { @@ -241,14 +240,14 @@ export FEISHU_APP_SECRET="xxx" } ``` -### 配额优化 +### 配额优化标志 -可通过以下可选配置减少飞书 API 调用： +你可以使用两个可选标志来减少飞书 API 使用量： -- `typingIndicator`（默认 `true`）：设为 `false` 时不发送“正在输入”状态。 -- `resolveSenderNames`（默认 `true`）：设为 `false` 时不拉取发送者资料。 +- `typingIndicator`（默认 `true`）：设为 `false` 时，跳过“正在输入”反应调用。 +- `resolveSenderNames`（默认 `true`）：设为 `false` 时，跳过发送者资料查询调用。 -可在渠道级或账号级配置： +你可以在顶层或按账户进行设置： ```json5 { @@ -271,9 +270,9 @@ export FEISHU_APP_SECRET="xxx" --- -## 第三步：启动并测试 +## 第 3 步：启动并测试 -### 1. 启动网关 +### 1. 启动 Gateway 网关 ```bash openclaw gateway @@ -281,74 +280,74 @@ openclaw gateway ### 2. 发送测试消息 -在飞书中找到您创建的机器人，发送一条消息。 +在飞书中找到你的机器人并发送一条消息。 -### 3. 配对授权 +### 3. 批准配对 -默认情况下，机器人会回复一个 **配对码**。您需要批准此代码： +默认情况下，机器人会回复一个配对码。批准它： ```bash -openclaw pairing approve feishu <配对码> +openclaw pairing approve feishu ``` -批准后即可正常对话。 +批准后，你就可以正常聊天了。 --- -## 介绍 +## 概览 -- **飞书机器人渠道**：由网关管理的飞书机器人 -- **确定性路由**：回复始终返回飞书，模型不会选择渠道 -- **会话隔离**：私聊共享主会话；群组独立隔离 -- **WebSocket 连接**：使用飞书 SDK 的长连接模式，无需公网 URL +- **飞书机器人渠道**：由 Gateway 网关管理的飞书机器人 +- **确定性路由**：回复始终返回到飞书 +- **会话隔离**：私信共享主会话；群组彼此隔离 +- **WebSocket 连接**：通过飞书 SDK 建立长连接，无需公共 URL --- ## 访问控制 -### 私聊访问 +### 私信 -- **默认**：`dmPolicy: "pairing"`，陌生用户会收到配对码 +- **默认**：`dmPolicy: "pairing"`（未知用户会收到配对码） - **批准配对**： - ```bash - openclaw pairing list feishu # 查看待审批列表 - openclaw pairing approve feishu # 批准 - ``` -- **白名单模式**：通过 `channels.feishu.allowFrom` 配置允许的用户 Open ID -### 群组访问 + ```bash + openclaw pairing list feishu + openclaw pairing approve feishu + ``` + +- **Allowlist 模式**：设置 `channels.feishu.allowFrom`，填入允许的 Open ID + +### 群聊 **1. 群组策略**（`channels.feishu.groupPolicy`）： -- `"open"` = 允许群组中所有人（默认） -- `"allowlist"` = 仅允许 `groupAllowFrom` 中的群组 -- `"disabled"` = 禁用群组消息 +- `"open"` = 允许群组中的所有人（默认） +- `"allowlist"` = 仅允许 `groupAllowFrom` +- `"disabled"` = 禁用群消息 -**2. @提及要求**（`channels.feishu.groups..requireMention`）： +**2. 提及要求**（`channels.feishu.groups..requireMention`）： -- `true` = 需要 @机器人才响应（默认） -- `false` = 无需 @也响应 +- `true` = 需要 @ 提及（默认） +- `false` = 无需提及也会回复 --- ## 群组配置示例 -### 允许所有群组，需要 @提及（默认行为） +### 允许所有群组，要求 @ 提及（默认） ```json5 { channels: { feishu: { groupPolicy: "open", - // 默认 requireMention: true + // Default requireMention: true }, }, } ``` -### 允许所有群组，无需 @提及 - -需要为特定群组配置： +### 允许所有群组，无需 @ 提及 ```json5 { @@ -369,16 +368,16 @@ openclaw pairing approve feishu <配对码> channels: { feishu: { groupPolicy: "allowlist", - // 群组 ID 格式为 oc_xxx + // Feishu group IDs (chat_id) look like: oc_xxx groupAllowFrom: ["oc_xxx", "oc_yyy"], }, }, } ``` -### 仅允许特定成员在群组中发信（发送者白名单） +### 限制哪些发送者可以在群组中发消息（发送者 allowlist） -除群组白名单外，该群组内**所有消息**均按发送者 open_id 校验：仅 `groups..allowFrom` 中列出的用户消息会被处理，其他成员的消息会被忽略（此为发送者级白名单，不仅针对 /reset、/new 等控制命令）。 +除了允许群组本身外，该群组中的**所有消息**还会按发送者 `open_id` 进行限制：只有列在 `groups..allowFrom` 中的用户，其消息才会被处理；其他成员发送的消息会被忽略（这是完整的发送者级限制，而不只是对 `/reset` 或 `/new` 等控制命令生效）。 ```json5 { @@ -388,7 +387,7 @@ openclaw pairing approve feishu <配对码> groupAllowFrom: ["oc_xxx"], groups: { oc_xxx: { - // 用户 open_id 格式为 ou_xxx + // Feishu user IDs (open_id) look like: ou_xxx allowFrom: ["ou_user1", "ou_user2"], }, }, @@ -401,29 +400,31 @@ openclaw pairing approve feishu <配对码> ## 获取群组/用户 ID -### 获取群组 ID（chat_id） +### 群组 ID（`chat_id`） -群组 ID 格式为 `oc_xxx`，可以通过以下方式获取： +群组 ID 看起来像 `oc_xxx`。 -**方法一**（推荐）： +**方法 1（推荐）** -1. 启动网关并在群组中 @机器人发消息 -2. 运行 `openclaw logs --follow` 查看日志中的 `chat_id` +1. 启动 Gateway 网关并在群里 @ 提及机器人 +2. 运行 `openclaw logs --follow` 并查找 `chat_id` -**方法二**： -使用飞书 API 调试工具获取机器人所在群组列表。 +**方法 2** -### 获取用户 ID（open_id） +使用飞书 API 调试器列出群聊。 -用户 ID 格式为 `ou_xxx`，可以通过以下方式获取： +### 用户 ID（`open_id`） -**方法一**（推荐）： +用户 ID 看起来像 `ou_xxx`。 -1. 启动网关并给机器人发消息 -2. 运行 `openclaw logs --follow` 查看日志中的 `open_id` +**方法 1（推荐）** -**方法二**： -查看配对请求列表，其中包含用户的 Open ID： +1. 启动 Gateway 网关并向机器人发送私信 +2. 运行 `openclaw logs --follow` 并查找 `open_id` + +**方法 2** + +检查配对请求中的用户 Open ID： ```bash openclaw pairing list feishu @@ -433,65 +434,61 @@ openclaw pairing list feishu ## 常用命令 -| 命令 | 说明 | +| Command | Description | | --------- | -------------- | -| `/status` | 查看机器人状态 | -| `/reset` | 重置对话会话 | -| `/model` | 查看/切换模型 | +| `/status` | 显示机器人状态 | +| `/reset` | 重置会话 | +| `/model` | 显示/切换模型 | -飞书机器人菜单建议直接在飞书开放平台的机器人能力页面配置。OpenClaw 当前支持接收 `application.bot.menu_v6` 事件，并把点击事件转换成普通文本命令（例如 `/menu `）继续走现有消息路由，但不通过渠道配置自动创建或同步菜单。 +> 注意：飞书暂不支持原生命令菜单，因此命令必须以文本形式发送。 -## 网关管理命令 +## Gateway 网关管理命令 -在配置和使用飞书渠道时，您可能需要使用以下网关管理命令： - -| 命令 | 说明 | -| -------------------------- | ----------------- | -| `openclaw gateway status` | 查看网关运行状态 | -| `openclaw gateway install` | 安装/启动网关服务 | -| `openclaw gateway stop` | 停止网关服务 | -| `openclaw gateway restart` | 重启网关服务 | -| `openclaw logs --follow` | 实时查看日志输出 | +| Command | Description | +| -------------------------- | -------------------------- | +| `openclaw gateway status` | 显示 Gateway 网关状态 | +| `openclaw gateway install` | 安装/启动 Gateway 网关服务 | +| `openclaw gateway stop` | 停止 Gateway 网关服务 | +| `openclaw gateway restart` | 重启 Gateway 网关服务 | +| `openclaw logs --follow` | 跟踪 Gateway 网关日志 | --- ## 故障排除 -### 机器人在群组中不响应 +### 机器人在群聊中没有响应 -1. 检查机器人是否已添加到群组 -2. 检查是否 @了机器人（默认需要 @提及） -3. 检查 `groupPolicy` 是否为 `"disabled"` -4. 查看日志：`openclaw logs --follow` +1. 确保机器人已加入群组 +2. 确保你 @ 提及了机器人（默认行为） +3. 检查 `groupPolicy` 未设置为 `"disabled"` +4. 检查日志：`openclaw logs --follow` -### 机器人收不到消息 +### 机器人未接收到消息 -1. 检查应用是否已发布并审批通过 -2. 检查事件订阅是否配置正确（`im.message.receive_v1`） -3. 检查是否选择了 **长连接** 模式 -4. 检查应用权限是否完整 -5. 检查网关是否正在运行：`openclaw gateway status` -6. 查看实时日志：`openclaw logs --follow` +1. 确保应用已发布并获批准 +2. 确保事件订阅包含 `im.message.receive_v1` +3. 确保已启用**长连接** +4. 确保应用权限完整 +5. 确保 Gateway 网关正在运行：`openclaw gateway status` +6. 检查日志：`openclaw logs --follow` -### App Secret 泄露怎么办 +### App Secret 泄露 -1. 在飞书开放平台重置 App Secret -2. 更新配置文件中的 App Secret -3. 重启网关 +1. 在飞书开放平台中重置 App Secret +2. 在你的配置中更新 App Secret +3. 重启 Gateway 网关 -### 发送消息失败 +### 消息发送失败 -1. 检查应用是否有 `im:message:send_as_bot` 权限 -2. 检查应用是否已发布 -3. 查看日志获取详细错误信息 +1. 确保应用具有 `im:message:send_as_bot` 权限 +2. 确保应用已发布 +3. 查看日志以获取详细错误信息 --- ## 高级配置 -### 多账号配置 - -如果需要管理多个飞书机器人，可配置 `defaultAccount` 指定出站未显式指定 `accountId` 时使用的账号： +### 多账户 ```json5 { @@ -502,13 +499,13 @@ openclaw pairing list feishu main: { appId: "cli_xxx", appSecret: "xxx", - botName: "主机器人", + botName: "Primary bot", }, backup: { appId: "cli_yyy", appSecret: "yyy", - botName: "备用机器人", - enabled: false, // 暂时禁用 + botName: "Backup bot", + enabled: false, }, }, }, @@ -516,104 +513,102 @@ openclaw pairing list feishu } ``` +`defaultAccount` 用于控制当出站 API 未显式指定 `accountId` 时，使用哪个飞书账户。 + ### 消息限制 -- `textChunkLimit`：出站文本分块大小（默认 2000 字符） -- `mediaMaxMb`：媒体上传/下载限制（默认 30MB） +- `textChunkLimit`：出站文本分块大小（默认：2000 个字符） +- `mediaMaxMb`：媒体上传/下载限制（默认：30 MB） -### 流式输出 +### 流式传输 -飞书支持通过交互式卡片实现流式输出，机器人会实时更新卡片内容显示生成进度。默认配置： +飞书通过交互式卡片支持流式回复。启用后，机器人会在生成文本时更新卡片。 ```json5 { channels: { feishu: { streaming: true, // 启用流式卡片输出（默认 true） - blockStreamingCoalesce: { - enabled: true, - minDelayMs: 50, - maxDelayMs: 250, - }, + blockStreaming: true, // 启用分块流式传输（默认 true） }, }, } ``` -如需禁用流式输出（等待完整回复后一次性发送），可设置 `streaming: false`。 +将 `streaming: false` 设为等待完整回复生成后再发送。 -### 交互式卡片 +### ACP 会话 -OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的 Feishu 原生交互式卡片，也可以显式发送原始 `card` payload。 +飞书支持以下 ACP 场景： -- 默认路径：文本自动渲染或 Markdown 卡片 -- 显式卡片：通过消息动作的 `card` 参数发送原始交互卡片 -- 更新卡片：同一消息支持后续 patch/update +- 私信 +- 群组话题会话 -卡片按钮回调当前走文本回退路径： +飞书 ACP 由文本命令驱动。没有原生斜杠命令菜单，因此请直接在会话中使用 `/acp ...` 消息。 -- 若 `action.value.text` 存在，则作为入站文本继续处理 -- 若 `action.value.command` 存在，则作为命令文本继续处理 -- 其他对象值会序列化为 JSON 文本 +#### 持久化 ACP 绑定 -这样可以保持与现有消息/命令路由兼容，而不要求下游先理解 Feishu 专有的交互 payload。 - -### 表情反应 - -飞书渠道现已完整支持表情反应生命周期： - -- 接收 `reaction created` -- 接收 `reaction deleted` -- 主动添加反应 -- 主动删除自身反应 -- 查询消息上的反应列表 - -是否把入站反应转成内部消息，可通过 `reactionNotifications` 控制： - -| 值 | 行为 | -| ----- | ---------------------------- | -| `off` | 不生成反应通知 | -| `own` | 仅当反应发生在机器人消息上时 | -| `all` | 所有可验证的反应都生成通知 | - -### 消息引用 - -在群聊中，机器人的回复可以引用用户发送的原始消息，让对话上下文更加清晰。 - -配置选项： +使用顶层类型化 ACP 绑定，将飞书私信或话题会话固定到持久化 ACP 会话。 ```json5 { - channels: { - feishu: { - // 账户级别配置（默认 "all"） - replyToMode: "all", - groups: { - oc_xxx: { - // 特定群组可以覆盖 - replyToMode: "first", + agents: { + list: [ + { + id: "codex", + runtime: { + type: "acp", + acp: { + agent: "codex", + backend: "acpx", + mode: "persistent", + cwd: "/workspace/openclaw", + }, }, }, - }, + ], }, + bindings: [ + { + type: "acp", + agentId: "codex", + match: { + channel: "feishu", + accountId: "default", + peer: { kind: "direct", id: "ou_1234567890" }, + }, + }, + { + type: "acp", + agentId: "codex", + match: { + channel: "feishu", + accountId: "default", + peer: { kind: "group", id: "oc_group_chat:topic:om_topic_root" }, + }, + acp: { label: "codex-feishu-topic" }, + }, + ], } ``` -`replyToMode` 值说明： +#### 从聊天中按线程绑定 ACP 生成 -| 值 | 行为 | -| --------- | ---------------------------------- | -| `"off"` | 不引用原消息（私聊默认值） | -| `"first"` | 仅在第一条回复时引用原消息 | -| `"all"` | 所有回复都引用原消息（群聊默认值） | +在飞书私信或话题会话中，你可以就地生成并绑定一个 ACP 会话： -> 注意：消息引用功能与流式卡片输出（`streaming: true`）不能同时使用。当启用流式输出时，回复会以卡片形式呈现，不会显示引用。 +```text +/acp spawn codex --thread here +``` -### 多 Agent 路由 +说明： -通过 `bindings` 配置，您可以用一个飞书机器人对接多个不同功能或性格的 Agent。系统会根据用户 ID 或群组 ID 自动将对话分发到对应的 Agent。 +- `--thread here` 适用于私信和飞书话题。 +- 绑定后的私信/话题中的后续消息会直接路由到该 ACP 会话。 +- v1 不支持针对通用的非话题群聊。 -配置示例： +### 多智能体路由 + +使用 `bindings` 将飞书私信或群组路由到不同的智能体。 ```json5 { @@ -634,91 +629,81 @@ OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的 }, bindings: [ { - // 用户 A 的私聊 → main agent agentId: "main", match: { channel: "feishu", - peer: { kind: "dm", id: "ou_28b31a88..." }, + peer: { kind: "direct", id: "ou_xxx" }, }, }, { - // 用户 B 的私聊 → clawd-fan agent agentId: "clawd-fan", match: { channel: "feishu", - peer: { kind: "dm", id: "ou_0fe6b1c9..." }, + peer: { kind: "direct", id: "ou_yyy" }, }, }, { - // 某个群组 → clawd-xi agent agentId: "clawd-xi", match: { channel: "feishu", - peer: { kind: "group", id: "oc_xxx..." }, + peer: { kind: "group", id: "oc_zzz" }, }, }, ], } ``` -匹配规则说明： +路由字段： -| 字段 | 说明 | -| ----------------- | --------------------------------------------- | -| `agentId` | 目标 Agent 的 ID，需要在 `agents.list` 中定义 | -| `match.channel` | 渠道类型，这里固定为 `"feishu"` | -| `match.peer.kind` | 对话类型：`"dm"`（私聊）或 `"group"`（群组） | -| `match.peer.id` | 用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`） | +- `match.channel`：`"feishu"` +- `match.peer.kind`：`"direct"` 或 `"group"` +- `match.peer.id`：用户 Open ID（`ou_xxx`）或群组 ID（`oc_xxx`） -> 获取 ID 的方法：参见上文 [获取群组/用户 ID](#获取群组用户-id) 章节。 +查找提示请参见 [获取群组/用户 ID](#get-groupuser-ids)。 --- ## 配置参考 -完整配置请参考：[网关配置](/gateway/configuration) +完整配置：[Gateway 网关配置](/gateway/configuration) -主要选项： +关键选项： -| 配置项 | 说明 | 默认值 | -| ------------------------------------------------- | --------------------------------- | ---------------- | -| `channels.feishu.enabled` | 启用/禁用渠道 | `true` | -| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` | -| `channels.feishu.connectionMode` | 事件传输模式（websocket/webhook） | `websocket` | -| `channels.feishu.defaultAccount` | 出站路由默认账号 ID | `default` | -| `channels.feishu.verificationToken` | Webhook 模式必填 | - | -| `channels.feishu.webhookPath` | Webhook 路由路径 | `/feishu/events` | -| `channels.feishu.webhookHost` | Webhook 监听地址 | `127.0.0.1` | -| `channels.feishu.webhookPort` | Webhook 监听端口 | `3000` | -| `channels.feishu.accounts..appId` | 应用 App ID | - | -| `channels.feishu.accounts..appSecret` | 应用 App Secret | - | -| `channels.feishu.accounts..domain` | 单账号 API 域名覆盖 | `feishu` | -| `channels.feishu.dmPolicy` | 私聊策略 | `pairing` | -| `channels.feishu.allowFrom` | 私聊白名单（open_id 列表） | - | -| `channels.feishu.groupPolicy` | 群组策略 | `allowlist` | -| `channels.feishu.groupAllowFrom` | 群组白名单 | - | -| `channels.feishu.groups..requireMention` | 是否需要 @提及 | `true` | -| `channels.feishu.groups..enabled` | 是否启用该群组 | `true` | -| `channels.feishu.replyInThread` | 群聊回复是否进入飞书话题线程 | `disabled` | -| `channels.feishu.groupSessionScope` | 群聊会话隔离粒度 | `group` | -| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` | -| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` | -| `channels.feishu.streaming` | 启用流式卡片输出 | `true` | -| `channels.feishu.blockStreamingCoalesce.enabled` | 启用块级流式合并 | `true` | -| `channels.feishu.typingIndicator` | 发送“正在输入”状态 | `true` | -| `channels.feishu.resolveSenderNames` | 拉取发送者名称 | `true` | -| `channels.feishu.reactionNotifications` | 入站反应通知策略 | `own` | +| Setting | Description | Default | +| ------------------------------------------------- | -------------------------------- | ---------------- | +| `channels.feishu.enabled` | 启用/禁用渠道 | `true` | +| `channels.feishu.domain` | API 域名（`feishu` 或 `lark`） | `feishu` | +| `channels.feishu.connectionMode` | 事件传输模式 | `websocket` | +| `channels.feishu.defaultAccount` | 出站路由的默认账户 ID | `default` | +| `channels.feishu.verificationToken` | webhook 模式必填 | - | +| `channels.feishu.encryptKey` | webhook 模式必填 | - | +| `channels.feishu.webhookPath` | webhook 路由路径 | `/feishu/events` | +| `channels.feishu.webhookHost` | webhook 绑定主机 | `127.0.0.1` | +| `channels.feishu.webhookPort` | webhook 绑定端口 | `3000` | +| `channels.feishu.accounts..appId` | App ID | - | +| `channels.feishu.accounts..appSecret` | App Secret | - | +| `channels.feishu.accounts..domain` | 按账户覆盖 API 域名 | `feishu` | +| `channels.feishu.dmPolicy` | 私信策略 | `pairing` | +| `channels.feishu.allowFrom` | 私信 allowlist（`open_id` 列表） | - | +| `channels.feishu.groupPolicy` | 群组策略 | `open` | +| `channels.feishu.groupAllowFrom` | 群组 allowlist | - | +| `channels.feishu.groups..requireMention` | 要求 @ 提及 | `true` | +| `channels.feishu.groups..enabled` | 启用群组 | `true` | +| `channels.feishu.textChunkLimit` | 消息分块大小 | `2000` | +| `channels.feishu.mediaMaxMb` | 媒体大小限制 | `30` | +| `channels.feishu.streaming` | 启用流式卡片输出 | `true` | +| `channels.feishu.blockStreaming` | 启用分块流式传输 | `true` | --- -## dmPolicy 策略说明 +## dmPolicy 参考 -| 值 | 行为 | -| ------------- | -------------------------------------------------- | -| `"pairing"` | **默认**。未知用户收到配对码，管理员批准后才能对话 | -| `"allowlist"` | 仅 `allowFrom` 列表中的用户可对话，其他静默忽略 | -| `"open"` | 允许所有人对话（需在 allowFrom 中加 `"*"`） | -| `"disabled"` | 完全禁止私聊 | +| Value | Behavior | +| ------------- | ---------------------------------------------------- | +| `"pairing"` | **默认。**未知用户会收到配对码；必须获批准后才能使用 | +| `"allowlist"` | 只有 `allowFrom` 中的用户可以聊天 | +| `"open"` | 允许所有用户（要求 `allowFrom` 中有 `"*"`） | +| `"disabled"` | 禁用私信 | --- @@ -726,17 +711,17 @@ OpenClaw 默认会在需要时发送 Markdown 卡片；如果你需要完整的 ### 接收 -- ✅ 文本消息 -- ✅ 富文本（帖子） +- ✅ 文本 +- ✅ 富文本（post） - ✅ 图片 - ✅ 文件 - ✅ 音频 - ✅ 视频 -- ✅ 表情包 +- ✅ 贴纸 ### 发送 -- ✅ 文本消息 +- ✅ 文本 - ✅ 图片 - ✅ 文件 - ✅ 音频 diff --git a/docs/zh-CN/channels/nostr.md b/docs/zh-CN/channels/nostr.md index 7d0359ce21d..47efa40aedf 100644 --- a/docs/zh-CN/channels/nostr.md +++ b/docs/zh-CN/channels/nostr.md @@ -1,14 +1,14 @@ --- read_when: - - 你希望 OpenClaw 通过 Nostr 接收私信 - - 你正在设置去中心化消息 -summary: 通过 NIP-04 加密消息的 Nostr 私信渠道 + - 你想让 OpenClaw 通过 Nostr 接收私信 + - 你正在设置去中心化消息传递 +summary: 通过 NIP-04 加密消息实现的 Nostr 私信渠道 title: Nostr x-i18n: - generated_at: "2026-02-03T07:44:13Z" - model: claude-opus-4-5 - provider: pi - source_hash: 6b9fe4c74bf5e7c0f59bbaa129ec5270fd29a248551a8a9a7dde6cff8fb46111 + generated_at: "2026-03-16T06:20:37Z" + model: gpt-5.4 + provider: openai + source_hash: fcce57da49256971420c4bb099aebb7944f8c7e8619b17b163da685add225001 source_path: channels/nostr.md workflow: 15 --- @@ -17,21 +17,21 @@ x-i18n: **状态：** 可选插件（默认禁用）。 -Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够通过 NIP-04 接收和回复加密私信（DMs）。 +Nostr 是一种用于社交网络的去中心化协议。此渠道使 OpenClaw 能够通过 NIP-04 接收并回复加密私信。 ## 安装（按需） ### 新手引导（推荐） -- 新手引导向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选的渠道插件。 -- 选择 Nostr 会提示你按需安装插件。 +- 设置向导（`openclaw onboard`）和 `openclaw channels add` 会列出可选渠道插件。 +- 选择 Nostr 时，系统会提示你按需安装该插件。 -安装默认值： +安装默认行为： -- **Dev 渠道 + git checkout 可用：** 使用本地插件路径。 -- **Stable/Beta：** 从 npm 下载。 +- **Dev 渠道 + 可用的 git 检出：** 使用本地插件路径。 +- **稳定版 / Beta：** 从 npm 下载。 -你可以随时在提示中覆盖选择。 +你始终可以在提示中覆盖该选择。 ### 手动安装 @@ -39,24 +39,33 @@ Nostr 是一个去中心化的社交网络协议。此渠道使 OpenClaw 能够 openclaw plugins install @openclaw/nostr ``` -使用本地 checkout（开发工作流）： +使用本地检出（dev 工作流）： ```bash openclaw plugins install --link /extensions/nostr ``` -安装或启用插件后重启 Gateway 网关。 +安装或启用插件后，重启 Gateway 网关。 + +### 非交互式设置 + +```bash +openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" +openclaw channels add --channel nostr --private-key "$NOSTR_PRIVATE_KEY" --relay-urls "wss://relay.damus.io,wss://relay.primal.net" +``` + +使用 `--use-env` 可将 `NOSTR_PRIVATE_KEY` 保留在环境中，而不是将密钥存储在配置里。 ## 快速设置 -1. 生成 Nostr 密钥对（如需要）： +1. 生成一个 Nostr 密钥对（如有需要）： ```bash -# 使用 nak +# Using nak nak key generate ``` -2. 添加到配置： +2. 添加到配置中： ```json { @@ -78,19 +87,19 @@ export NOSTR_PRIVATE_KEY="nsec1..." ## 配置参考 -| 键 | 类型 | 默认值 | 描述 | +| 键 | 类型 | 默认值 | 说明 | | ------------ | -------- | ------------------------------------------- | --------------------------- | | `privateKey` | string | 必填 | `nsec` 或十六进制格式的私钥 | | `relays` | string[] | `['wss://relay.damus.io', 'wss://nos.lol']` | 中继 URL（WebSocket） | | `dmPolicy` | string | `pairing` | 私信访问策略 | -| `allowFrom` | string[] | `[]` | 允许的发送者公钥 | -| `enabled` | boolean | `true` | 启用/禁用渠道 | +| `allowFrom` | string[] | `[]` | 允许的发送方公钥 | +| `enabled` | boolean | `true` | 启用 / 禁用渠道 | | `name` | string | - | 显示名称 | -| `profile` | object | - | NIP-01 个人资料元数据 | +| `profile` | object | - | NIP-01 资料元数据 | -## 个人资料元数据 +## 资料元数据 -个人资料数据作为 NIP-01 `kind:0` 事件发布。你可以从控制界面（Channels -> Nostr -> Profile）管理它，或直接在配置中设置。 +资料数据会作为 NIP-01 `kind:0` 事件发布。你可以在控制 UI 中管理它（Channels -> Nostr -> Profile），也可以直接在配置中设置。 示例： @@ -114,19 +123,19 @@ export NOSTR_PRIVATE_KEY="nsec1..." } ``` -注意事项： +注意： -- 个人资料 URL 必须使用 `https://`。 -- 从中继导入会合并字段并保留本地覆盖。 +- 资料 URL 必须使用 `https://`。 +- 从中继导入时会合并字段，并保留本地覆盖项。 ## 访问控制 ### 私信策略 -- **pairing**（默认）：未知发送者会收到配对码。 +- **pairing**（默认）：未知发送方会收到一个配对码。 - **allowlist**：只有 `allowFrom` 中的公钥可以发送私信。 -- **open**：公开接收私信（需要 `allowFrom: ["*"]`）。 -- **disabled**：忽略接收的私信。 +- **open**：公开接收入站私信（要求 `allowFrom: ["*"]`）。 +- **disabled**：忽略入站私信。 ### 允许列表示例 @@ -166,26 +175,26 @@ export NOSTR_PRIVATE_KEY="nsec1..." 提示： -- 使用 2-3 个中继以实现冗余。 +- 使用 2 到 3 个中继以实现冗余。 - 避免使用过多中继（延迟、重复）。 - 付费中继可以提高可靠性。 -- 本地中继适合测试（`ws://localhost:7777`）。 +- 本地中继也适合测试（`ws://localhost:7777`）。 ## 协议支持 -| NIP | 状态 | 描述 | -| ------ | ------ | ----------------------------- | -| NIP-01 | 已支持 | 基本事件格式 + 个人资料元数据 | -| NIP-04 | 已支持 | 加密私信（`kind:4`） | -| NIP-17 | 计划中 | 礼物包装私信 | -| NIP-44 | 计划中 | 版本化加密 | +| NIP | 状态 | 说明 | +| ------ | ------ | ------------------------- | +| NIP-01 | 已支持 | 基础事件格式 + 资料元数据 | +| NIP-04 | 已支持 | 加密私信（`kind:4`） | +| NIP-17 | 计划中 | Gift-wrapped 私信 | +| NIP-44 | 计划中 | 版本化加密 | ## 测试 ### 本地中继 ```bash -# 启动 strfry +# Start strfry docker run -p 7777:7777 ghcr.io/hoytech/strfry ``` @@ -203,38 +212,38 @@ docker run -p 7777:7777 ghcr.io/hoytech/strfry ### 手动测试 1. 从日志中记下机器人公钥（npub）。 -2. 打开 Nostr 客户端（Damus、Amethyst 等）。 -3. 向机器人公钥发送私信。 -4. 验证响应。 +2. 打开一个 Nostr 客户端（Damus、Amethyst 等）。 +3. 向该机器人公钥发送私信。 +4. 验证回复。 ## 故障排除 -### 未收到消息 +### 未接收到消息 -- 验证私钥是否有效。 -- 确保中继 URL 可访问并使用 `wss://`（本地使用 `ws://`）。 +- 验证私钥有效。 +- 确保中继 URL 可访问，并使用 `wss://`（本地则使用 `ws://`）。 - 确认 `enabled` 不是 `false`。 - 检查 Gateway 网关日志中的中继连接错误。 -### 未发送响应 +### 未发送回复 - 检查中继是否接受写入。 -- 验证出站连接。 +- 验证出站连接性。 - 注意中继速率限制。 -### 重复响应 +### 重复回复 -- 使用多个中继时属于正常现象。 -- 消息按事件 ID 去重；只有首次投递会触发响应。 +- 使用多个中继时这是预期行为。 +- 消息会按事件 ID 去重；只有首次投递会触发回复。 -## 安全 +## 安全性 - 切勿提交私钥。 -- 使用环境变量存储密钥。 -- 生产环境机器人考虑使用 `allowlist`。 +- 对密钥使用环境变量。 +- 对生产机器人考虑使用 `allowlist`。 ## 限制（MVP） - 仅支持私信（不支持群聊）。 - 不支持媒体附件。 -- 仅支持 NIP-04（计划支持 NIP-17 礼物包装）。 +- 仅支持 NIP-04（计划支持 NIP-17 gift-wrap）。 diff --git a/docs/zh-CN/channels/synology-chat.md b/docs/zh-CN/channels/synology-chat.md new file mode 100644 index 00000000000..4323e5d12d7 --- /dev/null +++ b/docs/zh-CN/channels/synology-chat.md @@ -0,0 +1,138 @@ +--- +read_when: + - 设置 OpenClaw 与 Synology Chat + - 调试 Synology Chat webhook 路由 +summary: Synology Chat webhook 设置与 OpenClaw 配置 +title: Synology Chat +x-i18n: + generated_at: "2026-03-16T06:20:51Z" + model: gpt-5.4 + provider: openai + source_hash: 7d77598ea759f89873a1edf0a3a7e7fedc1e4a7067709aaca6b999056a89eb1a + source_path: channels/synology-chat.md + workflow: 15 +--- + +# Synology Chat（插件） + +状态：通过插件支持，作为使用 Synology Chat webhook 的私信渠道。 +该插件接受来自 Synology Chat 出站 webhook 的入站消息，并通过 Synology Chat 入站 webhook 发送回复。 + +## 需要插件 + +Synology Chat 基于插件，不属于默认的核心渠道安装内容。 + +从本地检出安装： + +```bash +openclaw plugins install ./extensions/synology-chat +``` + +详情：[插件](/tools/plugin) + +## 快速设置 + +1. 安装并启用 Synology Chat 插件。 + - `openclaw onboard` 现在会在与 `openclaw channels add` 相同的渠道设置列表中显示 Synology Chat。 + - 非交互式设置：`openclaw channels add --channel synology-chat --token --url ` +2. 在 Synology Chat 集成中： + - 创建一个入站 webhook 并复制其 URL。 + - 使用你的 secret token 创建一个出站 webhook。 +3. 将出站 webhook URL 指向你的 OpenClaw Gateway 网关： + - 默认是 `https://gateway-host/webhook/synology`。 + - 或者使用你自定义的 `channels.synology-chat.webhookPath`。 +4. 在 OpenClaw 中完成设置。 + - 引导式：`openclaw onboard` + - 直接设置：`openclaw channels add --channel synology-chat --token --url ` +5. 重启 Gateway 网关，并向 Synology Chat 机器人发送一条私信。 + +最小配置： + +```json5 +{ + channels: { + "synology-chat": { + enabled: true, + token: "synology-outgoing-token", + incomingUrl: "https://nas.example.com/webapi/entry.cgi?api=SYNO.Chat.External&method=incoming&version=2&token=...", + webhookPath: "/webhook/synology", + dmPolicy: "allowlist", + allowedUserIds: ["123456"], + rateLimitPerMinute: 30, + allowInsecureSsl: false, + }, + }, +} +``` + +## 环境变量 + +对于默认账户，你可以使用环境变量： + +- `SYNOLOGY_CHAT_TOKEN` +- `SYNOLOGY_CHAT_INCOMING_URL` +- `SYNOLOGY_NAS_HOST` +- `SYNOLOGY_ALLOWED_USER_IDS`（逗号分隔） +- `SYNOLOGY_RATE_LIMIT` +- `OPENCLAW_BOT_NAME` + +配置值会覆盖环境变量。 + +## 私信策略与访问控制 + +- 推荐的默认值是 `dmPolicy: "allowlist"`。 +- `allowedUserIds` 接受 Synology 用户 ID 列表（或逗号分隔字符串）。 +- 在 `allowlist` 模式下，空的 `allowedUserIds` 列表会被视为配置错误，webhook 路由将不会启动（如需允许所有人，请使用 `dmPolicy: "open"`）。 +- `dmPolicy: "open"` 允许任何发送方。 +- `dmPolicy: "disabled"` 会阻止私信。 +- 配对批准可配合以下命令使用： + - `openclaw pairing list synology-chat` + - `openclaw pairing approve synology-chat ` + +## 出站投递 + +使用数字形式的 Synology Chat 用户 ID 作为目标。 + +示例： + +```bash +openclaw message send --channel synology-chat --target 123456 --text "Hello from OpenClaw" +openclaw message send --channel synology-chat --target synology-chat:123456 --text "Hello again" +``` + +支持通过基于 URL 的文件投递发送媒体。 + +## 多账户 + +支持在 `channels.synology-chat.accounts` 下配置多个 Synology Chat 账户。 +每个账户都可以覆盖 token、入站 URL、webhook 路径、私信策略和限制。 + +```json5 +{ + channels: { + "synology-chat": { + enabled: true, + accounts: { + default: { + token: "token-a", + incomingUrl: "https://nas-a.example.com/...token=...", + }, + alerts: { + token: "token-b", + incomingUrl: "https://nas-b.example.com/...token=...", + webhookPath: "/webhook/synology-alerts", + dmPolicy: "allowlist", + allowedUserIds: ["987654"], + }, + }, + }, + }, +} +``` + +## 安全说明 + +- 妥善保管 `token`，如果泄露请轮换。 +- 除非你明确可信任本地 NAS 的自签名证书，否则请保持 `allowInsecureSsl: false`。 +- 入站 webhook 请求会按 token 验证，并按发送方进行速率限制。 +- 生产环境优先使用 `dmPolicy: "allowlist"`。 diff --git a/docs/zh-CN/cli/index.md b/docs/zh-CN/cli/index.md index e7ae99ef935..46be3ef8ab1 100644 --- a/docs/zh-CN/cli/index.md +++ b/docs/zh-CN/cli/index.md @@ -1,14 +1,14 @@ --- read_when: - - 添加或修改 CLI 命令或选项 - - 为新命令界面编写文档 -summary: OpenClaw `openclaw` 命令、子命令和选项的 CLI 参考 + - 添加或修改 CLI 命令或选项时 + - 为新的命令界面编写文档时 +summary: "`openclaw` 命令、子命令和选项的 OpenClaw CLI 参考" title: CLI 参考 x-i18n: - generated_at: "2026-02-03T07:47:54Z" - model: claude-opus-4-5 - provider: pi - source_hash: a73923763d7b89d4b183f569d543927ffbfd1f3e02f9e66639913f6daf226850 + generated_at: "2026-03-16T06:22:35Z" + model: gpt-5.4 + provider: openai + source_hash: a2bca34fca64558a8d91fc640ad3880e79677e81d0f605083edc6cbe86bfba53 source_path: cli/index.md workflow: 15 --- @@ -23,8 +23,10 @@ x-i18n: - [`onboard`](/cli/onboard) - [`configure`](/cli/configure) - [`config`](/cli/config) +- [`completion`](/cli/completion) - [`doctor`](/cli/doctor) - [`dashboard`](/cli/dashboard) +- [`backup`](/cli/backup) - [`reset`](/cli/reset) - [`uninstall`](/cli/uninstall) - [`update`](/cli/update) @@ -40,6 +42,7 @@ x-i18n: - [`system`](/cli/system) - [`models`](/cli/models) - [`memory`](/cli/memory) +- [`directory`](/cli/directory) - [`nodes`](/cli/nodes) - [`devices`](/cli/devices) - [`node`](/cli/node) @@ -53,42 +56,46 @@ x-i18n: - [`hooks`](/cli/hooks) - [`webhooks`](/cli/webhooks) - [`pairing`](/cli/pairing) +- [`qr`](/cli/qr) - [`plugins`](/cli/plugins)（插件命令） - [`channels`](/cli/channels) - [`security`](/cli/security) +- [`secrets`](/cli/secrets) - [`skills`](/cli/skills) +- [`daemon`](/cli/daemon)（Gateway 网关服务命令的旧别名） +- [`clawbot`](/cli/clawbot)（旧别名命名空间） - [`voicecall`](/cli/voicecall)（插件；如已安装） ## 全局标志 -- `--dev`：将状态隔离到 `~/.openclaw-dev` 下并调整默认端口。 +- `--dev`：将状态隔离到 `~/.openclaw-dev` 下，并变更默认端口。 - `--profile `：将状态隔离到 `~/.openclaw-` 下。 - `--no-color`：禁用 ANSI 颜色。 -- `--update`：`openclaw update` 的简写（仅限源码安装）。 -- `-V`、`--version`、`-v`：打印版本并退出。 +- `--update`：`openclaw update` 的简写（仅适用于源码安装）。 +- `-V`, `--version`, `-v`：打印版本并退出。 ## 输出样式 - ANSI 颜色和进度指示器仅在 TTY 会话中渲染。 -- OSC-8 超链接在支持的终端中渲染为可点击链接；否则回退到纯 URL。 -- `--json`（以及支持的地方使用 `--plain`）禁用样式以获得干净输出。 -- `--no-color` 禁用 ANSI 样式；也支持 `NO_COLOR=1`。 -- 长时间运行的命令显示进度指示器（支持时使用 OSC 9;4）。 +- OSC-8 超链接会在受支持的终端中显示为可点击链接；否则会回退为纯 URL。 +- `--json`（以及在支持处的 `--plain`）会禁用样式，以获得干净输出。 +- `--no-color` 会禁用 ANSI 样式；同时也支持 `NO_COLOR=1`。 +- 长时间运行的命令会显示进度指示器（支持时使用 OSC 9;4）。 -## 颜色调色板 +## 调色板 -OpenClaw 在 CLI 输出中使用龙虾调色板。 +OpenClaw 在 CLI 输出中使用龙虾色调调色板。 -- `accent`（#FF5A2D）：标题、标签、主要高亮。 -- `accentBright`（#FF7A3D）：命令名称、强调。 -- `accentDim`（#D14A22）：次要高亮文本。 -- `info`（#FF8A5B）：信息性值。 -- `success`（#2FBF71）：成功状态。 -- `warn`（#FFB020）：警告、回退、注意。 -- `error`（#E23D2D）：错误、失败。 -- `muted`（#8B7F77）：弱化、元数据。 +- `accent` (#FF5A2D)：标题、标签、主要高亮。 +- `accentBright` (#FF7A3D)：命令名称、强调。 +- `accentDim` (#D14A22)：次级高亮文本。 +- `info` (#FF8A5B)：信息性值。 +- `success` (#2FBF71)：成功状态。 +- `warn` (#FFB020)：警告、回退、注意事项。 +- `error` (#E23D2D)：错误、失败。 +- `muted` (#8B7F77)：弱化显示、元数据。 -调色板权威来源：`src/terminal/palette.ts`（又名"lobster seam"）。 +调色板唯一来源：`src/terminal/palette.ts`（也称为 “lobster seam”）。 ## 命令树 @@ -101,9 +108,17 @@ openclaw [--dev] [--profile ] get set unset + completion doctor + dashboard + backup + create + verify security audit + secrets + reload + migrate reset uninstall update @@ -115,6 +130,7 @@ openclaw [--dev] [--profile ] remove login logout + directory skills list info @@ -152,6 +168,13 @@ openclaw [--dev] [--profile ] stop restart run + daemon + status + install + uninstall + start + stop + restart logs system event @@ -238,49 +261,59 @@ openclaw [--dev] [--profile ] pairing list approve + qr + clawbot + qr docs dns setup tui ``` -注意：插件可以添加额外的顶级命令（例如 `openclaw voicecall`）。 +注意：插件可以添加额外的顶层命令（例如 `openclaw voicecall`）。 ## 安全 -- `openclaw security audit` — 审计配置 + 本地状态中常见的安全隐患。 +- `openclaw security audit` — 审计配置 + 本地状态中常见的安全陷阱。 - `openclaw security audit --deep` — 尽力进行实时 Gateway 网关探测。 -- `openclaw security audit --fix` — 收紧安全默认值并 chmod 状态/配置。 +- `openclaw security audit --fix` — 收紧安全默认值并对状态 / 配置执行 chmod。 + +## 密钥 + +- `openclaw secrets reload` — 重新解析引用，并以原子方式替换运行时快照。 +- `openclaw secrets audit` — 扫描明文残留、未解析引用和优先级漂移。 +- `openclaw secrets configure` — 用于提供商设置 + SecretRef 映射 + 预检 / 应用的交互式助手。 +- `openclaw secrets apply --from ` — 应用先前生成的计划（支持 `--dry-run`）。 ## 插件 管理扩展及其配置： -- `openclaw plugins list` — 发现插件（使用 `--json` 获取机器可读输出）。 +- `openclaw plugins list` — 发现插件（机器输出请使用 `--json`）。 - `openclaw plugins info ` — 显示插件详情。 - `openclaw plugins install ` — 安装插件（或将插件路径添加到 `plugins.load.paths`）。 - `openclaw plugins enable ` / `disable ` — 切换 `plugins.entries..enabled`。 - `openclaw plugins doctor` — 报告插件加载错误。 -大多数插件更改需要重启 Gateway 网关。参见 [/plugin](/tools/plugin)。 +大多数插件更改都需要重启 gateway。参见 [/plugin](/tools/plugin)。 -## 记忆 +## 内存 -对 `MEMORY.md` + `memory/*.md` 进行向量搜索： +对 `MEMORY.md` + `memory/*.md` 执行向量搜索： -- `openclaw memory status` — 显示索引统计。 -- `openclaw memory index` — 重新索引记忆文件。 -- `openclaw memory search ""` — 对记忆进行语义搜索。 +- `openclaw memory status` — 显示索引统计信息。 +- `openclaw memory index` — 重新索引内存文件。 +- `openclaw memory search ""`（或 `--query ""`）— 对内存执行语义搜索。 ## 聊天斜杠命令 聊天消息支持 `/...` 命令（文本和原生）。参见 [/tools/slash-commands](/tools/slash-commands)。 -亮点： +重点： - `/status` 用于快速诊断。 - `/config` 用于持久化配置更改。 -- `/debug` 用于仅运行时的配置覆盖（内存中，不写入磁盘；需要 `commands.debug: true`）。 +- `/debug` 用于仅运行时的配置覆盖（内存中，不写磁盘；要求 `commands.debug: true`）。 ## 设置 + 新手引导 @@ -291,32 +324,35 @@ openclaw [--dev] [--profile ] 选项： - `--workspace `：智能体工作区路径（默认 `~/.openclaw/workspace`）。 -- `--wizard`：运行新手引导向导。 +- `--wizard`：运行设置向导。 - `--non-interactive`：无提示运行向导。 - `--mode `：向导模式。 - `--remote-url `：远程 Gateway 网关 URL。 -- `--remote-token `：远程 Gateway 网关令牌。 +- `--remote-token `：远程 Gateway 网关 token。 -当存在任何向导标志（`--non-interactive`、`--mode`、`--remote-url`、`--remote-token`）时，向导自动运行。 +只要存在任意向导标志（`--non-interactive`, `--mode`, `--remote-url`, `--remote-token`），就会自动运行向导。 ### `onboard` -交互式向导，用于设置 Gateway 网关、工作区和 Skills。 +用于设置 gateway、工作区和 Skills 的交互式向导。 选项： - `--workspace ` -- `--reset`（在向导之前重置配置 + 凭证 + 会话 + 工作区） +- `--reset`（在运行向导前重置配置 + 凭据 + 会话） +- `--reset-scope `（默认 `config+creds+sessions`；使用 `full` 还会删除工作区） - `--non-interactive` - `--mode ` -- `--flow `（manual 是 advanced 的别名） -- `--auth-choice ` -- `--token-provider `（非交互式；与 `--auth-choice token` 配合使用） -- `--token `（非交互式；与 `--auth-choice token` 配合使用） +- `--flow `（`manual` 是 `advanced` 的别名） +- `--auth-choice ` +- `--token-provider `（非交互式；与 `--auth-choice token` 一起使用） +- `--token `（非交互式；与 `--auth-choice token` 一起使用） - `--token-profile-id `（非交互式；默认：`:manual`） - `--token-expires-in `（非交互式；例如 `365d`、`12h`） +- `--secret-input-mode `（默认 `plaintext`；使用 `ref` 可存储提供商默认环境引用，而非明文密钥） - `--anthropic-api-key ` - `--openai-api-key ` +- `--mistral-api-key ` - `--openrouter-api-key ` - `--ai-gateway-api-key ` - `--moonshot-api-key ` @@ -325,10 +361,17 @@ openclaw [--dev] [--profile ] - `--zai-api-key ` - `--minimax-api-key ` - `--opencode-zen-api-key ` +- `--opencode-go-api-key ` +- `--custom-base-url `（非交互式；与 `--auth-choice custom-api-key` 或 `--auth-choice ollama` 一起使用） +- `--custom-model-id `（非交互式；与 `--auth-choice custom-api-key` 或 `--auth-choice ollama` 一起使用） +- `--custom-api-key `（非交互式；可选；与 `--auth-choice custom-api-key` 一起使用；省略时回退到 `CUSTOM_API_KEY`） +- `--custom-provider-id `（非交互式；可选自定义提供商 id） +- `--custom-compatibility `（非交互式；可选；默认 `openai`） - `--gateway-port ` - `--gateway-bind ` - `--gateway-auth ` - `--gateway-token ` +- `--gateway-token-ref-env `（非交互式；将 `gateway.auth.token` 存储为环境 SecretRef；要求该环境变量已设置；不能与 `--gateway-token` 一起使用） - `--gateway-password ` - `--remote-url ` - `--remote-token ` @@ -341,35 +384,39 @@ openclaw [--dev] [--profile ] - `--skip-skills` - `--skip-health` - `--skip-ui` -- `--node-manager `（推荐 pnpm；不建议将 bun 用于 Gateway 网关运行时） +- `--node-manager `（推荐 pnpm；不推荐将 bun 用作 Gateway 网关运行时） - `--json` ### `configure` -交互式配置向导（模型、渠道、Skills、Gateway 网关）。 +交互式配置向导（模型、渠道、Skills、gateway）。 ### `config` -非交互式配置辅助工具（get/set/unset）。不带子命令运行 `openclaw config` 会启动向导。 +非交互式配置助手（get/set/unset/file/validate）。直接运行 `openclaw config` 而不带 +子命令会启动向导。 子命令： -- `config get `：打印配置值（点/括号路径）。 -- `config set `：设置值（JSON5 或原始字符串）。 -- `config unset `：删除值。 +- `config get `：打印一个配置值（点 / 方括号路径）。 +- `config set `：设置一个值（JSON5 或原始字符串）。 +- `config unset `：移除一个值。 +- `config file`：打印当前活动配置文件路径。 +- `config validate`：根据 schema 验证当前配置，而不启动 gateway。 +- `config validate --json`：输出机器可读的 JSON。 ### `doctor` -健康检查 + 快速修复（配置 + Gateway 网关 + 旧版服务）。 +健康检查 + 快速修复（配置 + gateway + 旧版服务）。 选项： -- `--no-workspace-suggestions`：禁用工作区记忆提示。 -- `--yes`：无提示接受默认值（无头模式）。 +- `--no-workspace-suggestions`：禁用工作区内存提示。 +- `--yes`：接受默认值而不提示（无头）。 - `--non-interactive`：跳过提示；仅应用安全迁移。 -- `--deep`：扫描系统服务以查找额外的 Gateway 网关安装。 +- `--deep`：扫描系统服务以查找额外的 gateway 安装。 -## 渠道辅助工具 +## 渠道助手 ### `channels` @@ -378,19 +425,21 @@ openclaw [--dev] [--profile ] 子命令： - `channels list`：显示已配置的渠道和认证配置文件。 -- `channels status`：检查 Gateway 网关可达性和渠道健康状况（`--probe` 运行额外检查；使用 `openclaw health` 或 `openclaw status --deep` 进行 Gateway 网关健康探测）。 -- 提示：`channels status` 在检测到常见配置错误时会打印带有建议修复的警告（然后指向 `openclaw doctor`）。 -- `channels logs`：显示 Gateway 网关日志文件中最近的渠道日志。 -- `channels add`：不传标志时使用向导式设置；标志切换到非交互模式。 -- `channels remove`：默认禁用；传 `--delete` 可无提示删除配置条目。 -- `channels login`：交互式渠道登录（仅限 WhatsApp Web）。 -- `channels logout`：登出渠道会话（如支持）。 +- `channels status`：检查 gateway 可达性和渠道健康状态（`--probe` 会运行额外检查；gateway 健康探测请使用 `openclaw health` 或 `openclaw status --deep`）。 +- 提示：如果能够检测到常见配置错误，`channels status` 会打印带建议修复方式的警告（随后指向 `openclaw doctor`）。 +- `channels logs`：显示 gateway 日志文件中的最近渠道日志。 +- `channels add`：未传入任何标志时为向导式设置；传入标志后切换为非交互模式。 + - 当向仍使用单账户顶层配置的渠道添加非默认账户时，OpenClaw 会先将账户作用域值移动到 `channels..accounts.default`，再写入新账户。 + - 非交互式 `channels add` 不会自动创建 / 升级绑定；仅渠道绑定会继续匹配默认账户。 +- `channels remove`：默认执行禁用；传入 `--delete` 可在无提示下删除配置项。 +- `channels login`：交互式渠道登录（仅 WhatsApp Web）。 +- `channels logout`：登出某个渠道会话（如支持）。 通用选项： - `--channel `：`whatsapp|telegram|discord|googlechat|slack|mattermost|signal|imessage|msteams` - `--account `：渠道账户 id（默认 `default`） -- `--name