openclaw

OpenClaw（运维手册）

此技能内容完整，直接在本文件中包含运维文档。

链接

• 文档
• 发行版本
• GitHub

快速导航

• 安装 / 迁移：references/installation.md
• 配置模型与工作区引导：references/configuration.md
• 架构与多 Agent 路由：references/architecture.md
• 扩展概念：references/concepts.md
• 工具治理与安全：references/tools.md
• 网关运行手册与安全：references/gateway.md
• 入门与首次运行：references/getting-started.md
• 通道与提供方：references/channels-and-providers.md
• 节点与远程执行：references/nodes.md
• CLI 操作与故障排查：references/operations.md

核心模型

• OpenClaw 以网关为中心：每台主机运行一个长期驻留的 Gateway，作为控制平面。
• 客户端和节点通过类型化的 WebSocket API 连接；通道 / 提供方由网关统一编排。
• 会话安全依赖确定性路由、排队机制和明确的策略控制。

首日设置

1. 运行引导流程并安装守护进程。
2. 确认当前配置路径，并在首次编辑前验证配置。
3. 检查网关的健康状态 / 运行状态。
4. 打开 Control UI / 仪表板，开始首次对话。
5. 仅在基线运行状态稳定后，才添加通道 / 提供方。

如果尚未安装 OpenClaw，请参阅 references/installation.md。

网关运维

• 默认保持回环地址绑定并启用身份验证。
• 需要远程访问时，优先使用 Tailscale Serve 或 SSH 隧道，而不是绑定公共地址。
• 非回环地址绑定必须严格控制令牌 / 密码。
• 使用受监管的进程模式（launchd/systemd）来确保可靠性。
• 对于配置变更，将 config.apply 视为受控部署，将 config.patch 视为定向合并。
• 请记住补丁语义：对象合并、数组替换、null 删除。
• 明确处理重启边界：通道 / Agent / 消息 / 工具通常可热应用，而绑定地址 / 端口及其他网关基础设施设置通常需要运行 openclaw gateway restart。

版本更新（v2026.3.11-v2026.3.13）

• 安全： 即使在 trusted-proxy 模式下，现在也会对源自浏览器的 WebSocket 连接执行来源验证；浏览器客户端仅应使用获准的来源，且不得将代理标头视为绕过验证的手段。
• 重大变更： 隔离式 cron 投递的限制更加严格；升级后，应使用 openclaw doctor --fix 迁移旧版 cron 存储及旧版 notify/webhook 元数据。
• 网关 / 引导流程：远程 macOS 引导流程现在会检测是否需要共享网关身份验证令牌，并说明如何在网关主机上获取该令牌。
• 网关 / 控制 UI：令牌身份验证的仪表板会话现在将身份验证信息保存在会话范围的浏览器存储中，而不是长期使用的本地存储中；同一标签页刷新后应能保留会话，但不应认为重启浏览器后身份验证仍然有效。
• 网关可达性：范围受限的探测 RPC 现在会报告可达性下降，而不是显示为完全健康；事件分诊时请参考此信号。
• 通道：Slack 新增可选的交互式回复指令；Telegram 入站媒体获取现在支持 IPv4 重试回退。
• 插件 / 工具：插件通道 / 绑定冲突现在会快速失败，而不是产生含糊不清的运行时行为。
• 节点：网关现已提供 node.pending.enqueue / node.pending.drain 基元，为休眠节点投递待处理工作奠定基础。

发布更新（v2026.3.14–v2026.3.28）

• MCP 远程服务：mcp.servers 现在支持带身份验证标头的远程 HTTP/SSE URL，并能更安全地隐藏凭据。捆绑的 MCP 工具使用对提供方安全的名称（serverName__toolName），支持 streamable-http 传输、每个服务单独设置连接超时，并保留已中止轮次的工具结果。
• 插件 before_install 钩子：提供包含来源信息、内置扫描状态和安装目标元数据的结构化请求，供外部安全扫描器使用。可使用 --dangerously-force-unsafe-install 作为紧急覆盖选项。如果发现危险代码的 critical 级问题，除非设置了覆盖选项，否则会阻止通过网关安装技能依赖项。
• 后台任务 → 统一控制平面：ACP、子 Agent、cron 和后台 CLI 统一到一个由 SQLite 支持的账本中，支持审计、维护和状态查看、自动清理以及丢失运行的恢复。
• ClawFlow：首个线性流程控制界面（openclaw flows list|show|cancel）。多任务流程与单任务自动同步流程相互独立。Doctor 会为孤立的流程/任务关联提供恢复提示。
• 记忆/QMD：每个 Agent 的 memorySearch.qmd.extraCollections 支持跨 Agent 搜索；分块大小支持 CJK 感知；会话索引器会纳入已重置/删除的转录记录；memory.qmd.searchTool 可用作 mcporter 工具覆盖项。
• WhatsApp 表情回应：Agent 可以对收到的 WhatsApp 消息使用表情回应。
• Matrix：channels.matrix.historyLimit 用于设置群组触发时的房间历史上下文；可覆盖每个 DM 的 threadReplies；通过 channels.matrix.proxy 配置代理。
• Slack：支持原生 Slack 执行审批路由，并验证审批者身份。
• LINE：通过 LINE 专用传输路径发送图片/视频/音频。
• Android：通知转发控制支持按软件包过滤、静默时段和速率限制。
• Agents/大模型：支持为嵌入式运行器配置流式传输空闲超时；text.verbosity 会通过 Responses HTTP/WebSocket 传输转发。
• 安全性：验证 Nostr 入站 DM 签名；对 LINE webhook 执行时序安全的 HMAC 比较；沙盒浏览器支持 CJK 字体；强化网关身份验证（来源验证、本地直连令牌强制要求）。

发布更新（v2026.5.12）

• 更精简的安装：Slack、WhatsApp、Amazon Bedrock、Anthropic Vertex 及相关提供方/插件的依赖项已移出核心运行时，因此安装时只会拉取实际使用的依赖项。
• Telegram 韧性：隔离轮询、持久化本地暂存、更安全的群组媒体处理，以及保留 HTML/Markdown 格式，提升了默认频道路径的运维可靠性。
• Codex/OpenAI/媒体：强化了由身份验证配置文件支持的媒体工具、MCP 服务映射、上下文引擎线程轮换和运行时回退行为。
• 运维/安全/UI：插件安装/更新流程、pnpm 11 处理、网关/浏览器/沙盒/节点配对强化，以及 Control UI/WebChat 回复传递均得到显著改进。
• ACP 回退机制：ACP 轮次可在输出内容前尝试已配置的备用运行时后端，这对优雅降级运行尤为重要。

发布更新（v2026.5.22）

• 会议记录插件：新增仅提供源代码的外部会议记录路径，支持自动开始录制配置、手动导入转录文本、只读 openclaw meeting-notes CLI 访问，并以 Discord 语音作为首个实时来源。
• 网关就绪状态：启动时现在会延迟加载空闲插件任务、核心处理程序树和嵌入式 ACPX 运行时，因此健康检查和就绪检查不再等待未使用的子系统。
• 插件元数据缓存：在启动、配置和密钥读取过程中复用不可变的插件元数据快照，从而减少操作期间重复读取清单和文件状态的开销。
• 频道／运行时调优：复用频道目录读取；Signal 获得 configPath；Telegram 新增通配符主题默认值；备份归档使用本地时间命名。
• 媒体质量控制：模型感知型图像压缩现在遵循 agents.defaults.imageQuality，因此运维人员可以明确选择节省 token、均衡或高细节处理方式。
• 插件 SDK 迁移：新增行级会话工作流辅助工具，并弃用 loadSessionStore；插件维护应改为避免访问整个会话存储。
• 提供商身份验证复用：xAI OAuth 身份验证配置现在可用于 Grok web_search，并且提供商端媒体操作的默认超时行为更加明确。

发布更新（v2026.5.29-v2026.6.6）

• 安全性：收紧了转录文本、沙盒绑定、主机环境变量继承、MCP stdio 和 Codex HTTP 访问的边界；执行审批超时现在会默认拒绝；Feishu 不再将提示词前置运行时上下文泄露到回复中；强化了 WebSocket 载荷处理；Skill Workshop 会在提交元数据前验证符号链接写入。
• 频道：Telegram 正确路由账户范围内的主题，在工具调用期间流式传输文本，将 /compact 扩展至通用入口，并从缓存／提示词中排除未经授权的 DM 文本；iMessage 新增始终启用的入站重启、持久化回声标记、分块流式传输、空闲审批发现和启动诊断。
• 提供商／模型：Kimi K2.7 Code 修复了工具调用 ID 和推理重放问题；Claude Fable 5 支持自适应思考；增强了 Mistral 架构处理的稳健性；Fireworks 目录参数改为从清单获取；修复了 Anthropic 思考重放；恢复了 Vertex／ADC 目录。
• MCP／浏览器：支持现有会话的 Chrome DevTools Protocol、WebSocket 发现验证、可流式传输的 HTTP 环回传输、更安全的浏览器输出边界，以及在物化边界将 MCP 工具结果中的 resource_link／resource／audio／格式错误的图像强制转换为相应类型。
• 插件：npm 发布改用可信路径，并将 ClawHub 发布拆分；向运维人员报告插件版本漂移；托管安装保留可信的完整性固定值；预发布回退完整性检查避免沿用过期值。
• 界面／性能：缓存模型元数据并移除启动时的目录等待，降低了 Control UI 延迟；延迟加载斜杠命令；新增首个事件跟踪和慢回复诊断、无障碍修复，并要求先明确用户意图再打开聊天会话。

发布更新（v2026.5.27-v2026.5.28）

• 运行时恢复：Codex/app-server 和子 Agent 路径保留工作区与 cwd 的隔离，通过工具路由工作区记忆，在重启后保持原生钩子中继代际运行，在超时中止时释放会话锁，并避免执行过时的重启续接操作。
• 安全与输入边界：群组提示词元数据不会进入系统提示词，重复点号主机名会进行规范化，拒绝不安全的命令包装器和 Node 环境变量覆盖，阻止未启用身份验证的 Tailscale 暴露，明确将 Teams 服务 URL 设为可信，并更早拦截格式错误的数字、浏览器、cron、媒体、架构和 Telegram 回调输入。
• 频道与移动端界面：Telegram 投递更加可靠，Slack 最终回复不会因延迟清理而丢失，Matrix/iMessage/Discord/WhatsApp/Teams 路径更加妥善地保留身份和审批上下文，iOS/WebChat/Talk 界面在重新连接后能保留更多状态。
• 提供方/媒体覆盖范围：OpenAI 兼容的嵌入功能纳入核心，新增 Pixverse 视频、DeepInfra 目录加载、Claude Opus 4.8、Fal Krea 架构、NVIDIA 目录、MiniMax 流式音乐、提供方语音目录、加密 PDF 提取、GitHub Copilot 运行时和 Codex Supervisor 插件支持。
• 插件与工作协调：ClawHub 展示/信任界面、回复载荷发送钩子、按需安装 GitHub Copilot/Tokenjuice 插件，以及 Workboard 协调工具扩展了插件/运维工作流，同时保持更严格的目录和缓存行为。

发布更新（v2026.4.15）

• Anthropic/模型默认设置：捆绑的 Anthropic 默认设置和 opus 别名现已指向 Claude Opus 4.7，捆绑的图像理解功能也包含在内。
• Google TTS：捆绑的 google 插件现已支持文本转语音、语音选择、WAV 回复和 PCM 电话输出。
• 控制界面 / 网关：由 models.authStatus 提供支持的模型身份验证状态卡片可显示 OAuth 令牌健康状况和提供方速率限制压力。
• 记忆：LanceDB 可使用云对象存储，GitHub Copilot 可作为记忆搜索嵌入提供方使用，Dreaming 默认使用 separate 存储，而非内联每日记忆块。
• Agent/工具：agents.defaults.experimental.localModelLean: true 会为较弱的本地模型精简重量级默认工具；未知工具循环保护现已默认启用；在写入 skills.* 配置时，会更严格地使技能快照失效。
• 安全强化：拒绝内置工具名称冲突，/mcp 身份验证使用恒定时间比较并检查浏览器来源，HTTP bearer 轮换会在密钥重新加载后立即生效，WebChat/媒体路径会实施更严格的本地根目录/文件限制。

发布更新（v2026.3.13-1）

• 这是针对损坏的 v2026.3.13 发布路径的恢复 Git 标签；npm/运行时版本仍为 2026.3.13。
• 网关/界面：对 control-ui 连接失败的分类更加清晰，并恢复了不安全 control-ui 共享身份验证行为，以满足预期的兼容性路径。
• 运维：压缩后健全性检查现会检查完整会话的令牌数量，使事件分流期间更容易发现压缩回归。
• 会话/频道：会话重置会保留 lastAccountId 和 lastThreadId；Telegram 入站媒体重试会保留 IPv4 回退行为。
• 运行时/平台：Docker 新增 OPENCLAW_TZ；当可达性下降时，网关探测处理和未应答客户端请求的限制会更加便于运维人员掌握。

发布更新（v2026.3.7）

• 重大变更： 如果同时配置了 gateway.auth.token 和 gateway.auth.password（包括 SecretRef），现在必须明确设置 gateway.auth.mode（token 或 password）。请在升级前设置，以避免启动或配对失败。
• Agent：新增 ContextEngine 插件接口，提供完整的生命周期钩子（bootstrap、ingest、assemble、compact、afterTurn、prepareSubagentSpawn、onSubagentEnded）。无需修改核心压缩逻辑，即可采用替代的上下文管理策略（例如 lossless-claw）。
• Agent：可配置 postCompactionSections，用于选择压缩后重新注入哪些 AGENTS.md 章节。
• Agent：对超长工具结果进行头尾截断（保留尾部诊断信息）。
• Telegram：论坛群组和私信话题支持按话题设置 agentId 覆盖值，可路由到专用 Agent 并隔离会话。
• Telegram/ACP：持久化话题绑定（--thread here|auto）、通过带前缀的 ID 解析审批按钮，以及绑定固定确认。
• ACP：持久化存储 Discord 频道和 Telegram 话题绑定，重启后仍会保留。
• 插件：支持在系统提示词区域通过 prependSystemContext/appendSystemContext 添加静态指引（支持提供商缓存，降低重复成本）。
• 插件：新增 hooks.allowPromptInjection 策略，并在运行时验证未知钩子名称。
• 钩子：新增 session:compact:before/session:compact:after 事件，包含会话和计数元数据。
• 配置：通过经过验证的配置项开放 recentTurnsPreserve 和质量保护重试参数。
• 工具／网页搜索：Perplexity 提供商改用 Search API，支持结构化结果以及语言／区域／时间筛选。
• 工具／差异：指引从提示词钩子注入改为通过配套技能路径提供（减少无关轮次中的干扰）。
• Gateway：支持 gateway.auth.token 使用 SecretRef，并增加认证模式保护措施。
• Docker：采用多阶段构建生成精简运行时镜像；新增 OPENCLAW_VARIANT=slim 构建参数；支持通过 OPENCLAW_EXTENSIONS 预先打包扩展依赖。
• TTS：支持使用 messages.tts.openai.baseUrl 配置 OpenAI 兼容端点。
• Google：原生支持 gemini-3.1-flash-lite-preview。
• Slack：当助手无法显示正在输入状态时，支持通过 typingReaction 显示私信处理状态。
• Discord：新增 allowBots: "mentions"，可通过提及来限制机器人消息。
• Mattermost：支持交互式浏览 /oc_model 提供商／模型。
• Cron：保留 jobs.json.bak 作为编辑前快照，以便恢复。

发布更新（v2026.3.2）

• 重大变更： 新安装默认将 tools.profile 设为 messaging（而非宽泛的编码／系统配置）。如果希望首日即可使用编码工具，请显式设置 tools.profile。
• 重大变更： 除非显式禁用（acp.dispatch.enabled=false），否则 ACP 派发默认启用。
• 重大变更： 插件 SDK 移除了 api.registerHttpHandler(...)；请改用 api.registerHttpRoute(...)。
• 重大变更： Zalo 个人版插件（@openclaw/zalouser）不再使用外部 CLI 传输方式；升级后请使用 openclaw channels login --channel zalouser 重新登录。
• 扩展了用户提供凭据相关界面的密钥／SecretRef 支持范围；活动界面中的未解析引用会立即导致失败。
• 工具：新增原生 pdf 工具（原生支持 Anthropic/Google，并提供后备提取功能，且限制可配置）。
• CLI：新增 openclaw config validate（以及 --json），可在 Gateway 启动前验证配置。
• Telegram：新设置默认采用 partial 流式传输；更新私信预览的流式传输行为。
• Memory：支持通过 Ollama 为记忆搜索生成嵌入（memorySearch.provider/fallback = "ollama"）。
• 工具／diffs 插件：支持 PDF 输出，并提供差异产物的渲染质量控制。

发布更新（v2026.3.1）

• Gateway：内置容器探测端点（/healthz、/readyz，以及别名 /health、/ready），用于 Docker/Kubernetes。
• CLI：openclaw config file 会打印当前生效的配置路径（解析 OPENCLAW_CONFIG_PATH 或默认路径）。
• Discord：线程绑定的会话生命周期现在支持不活动时长（idleHours）和最长时长（maxAgeHours），以及 /session idle 和 /session max-age。
• Telegram：新增按私信配置的 direct 和私信话题配置界面（支持话题感知策略、技能、系统提示词和允许列表）。
• 节点（Android）：扩展节点工具集（摄像头/设备/通知/照片/联系人/日历/运动）。
• 工具：可选的 diffs 插件工具，支持只读差异视图和 PNG 渲染。

发布更新（v2026.2.23）

• Providers：首次提供一流的 kilocode 提供方支持（认证、引导、隐式提供方检测和模型默认值）。
• Tools/web_search：新增提供方 "kimi"（Moonshot），并修正两步式 $web_search 工具流程（合成前回显工具结果）。
• Gateway：对于直接 HTTPS 部署，可通过 gateway.http.securityHeaders.strictTransportSecurity 启用可选的 HSTS。
• Sessions：通过 openclaw sessions cleanup 强化维护功能，支持磁盘预算控制，并更安全地清理对话记录/归档。
• **破坏性变更：**浏览器 SSRF 策略默认值已更改，配置键也已重命名（browser.ssrfPolicy.allowPrivateNetwork -> browser.ssrfPolicy.dangerouslyAllowPrivateNetwork）；使用 openclaw doctor --fix 进行迁移。

架构和运行时概念

Agent 循环

• Agent 循环按会话串行执行（也可选择全局串行），以避免工具/历史记录竞争。
• 运行生命周期会发出助手/工具/生命周期流，以便观察运行情况。
• 等待超时和运行时超时是不同的控制项。

系统提示词和上下文

• 每次运行的系统提示词由 OpenClaw 组合生成（而非使用提供方默认提示词）。
• 根据运行上下文，提示词模式可以是 full、minimal 或 none。
• 上下文包括系统提示词、对话记录、工具/结果、附件和架构。
• 引导文件会注入上下文窗口并占用预算。

工作区和记忆

• 工作区是默认执行目录和记忆载体，并非严格的沙箱。
• 需要严格的文件系统隔离时，请使用沙箱设置。
• 记忆以 Markdown 为主：每日笔记 + 精选的持久记忆。
• 压缩会将摘要持久化到对话记录中；裁剪会在内存中删减较旧的工具结果。
• AGENTS.md、SOUL.md、USER.md、TOOLS.md、HEARTBEAT.md、IDENTITY.md 和 MEMORY.md 等引导文件都会占用上下文预算；请有意识地控制内容并保持精简。

消息、排队和在线状态

• 消息处理使用去重、可选的入站防抖、队列模式和感知渠道的交付机制。
• 队列/流式传输/分块行为由策略驱动，并可按渠道调整。
• 在线状态用于尽力而为的可观测性；必须使用稳定的 instanceId，以避免重复条目。

工具治理

• 从最小权限配置开始，然后明确允许所需工具。
• 拒绝列表优先于允许列表。
• 将 exec、sessions_*、gateway、nodes 视为高影响面。
• 媒体捕获操作必须获得用户明确同意。
• 工具可能形成无进展循环时，请启用循环检测。

渠道和提供方策略

• 使用最快且稳定的渠道路径（通常是 Telegram）进行基线验证。
• 确认配对/允许列表无误后，再添加 WhatsApp 和高级渠道。
• 通过 provider/model 明确选择提供方，避免模型隐式漂移。
• 分离工作和个人上下文时，请为每个 Agent 隔离认证配置文件。

节点和远程执行

• 节点是能力执行器，并非 Gateway 的替代品。
• 明确配对节点，并在调用操作前验证其能力。
• 节点执行审批应保留在节点主机本地，并进行审计。
• 使用显式节点绑定，以确定远程执行的目标。

安全基线

• 始终假设可能发生提示词注入。
• 按以下顺序应用控制措施：身份（配对／允许列表）-> 范围（工具／沙箱／提及）-> 模型策略。
• 确保控制界面处于安全上下文中（loopback／HTTPS）；避免降级到不安全的身份验证方式。
• 对配置和状态文件设置严格的文件系统权限，并对敏感日志进行脱敏。

故障排查步骤

1. openclaw status
2. openclaw gateway status
3. openclaw logs --follow
4. openclaw doctor
5. openclaw channels status --probe

常见问题排查对照表：

• 没有回复 -> 配对／允许列表／提及策略。
• 连接循环 -> 身份验证模式 + 端点 + 安全上下文。
• 启动失败 -> 模式／绑定／身份验证／端口冲突。
• 工具故障 -> 权限／审批／前台运行限制。

概念 URL 状态（来自左侧导航）

• 提取的概念已直接整合到此技能中。
• 文档导航中的部分源 URL 目前返回 404 或内容为空。
• 这些页面的内容已汇总到 references/concepts.md，并提供回退指导。

适用场景

• 你需要设计或运维 OpenClaw 部署。
• 你需要安全地连接渠道、提供商和工具。
• 你需要一份实用清单，用于新手引导和网关设置。

核心操作工作流

1. 根据架构说明确认拓扑和职责。
2. 围绕六个运维模块规划 openclaw.json：网关、Agent、渠道、绑定、会话／消息、心跳／工具／cron／hooks。
3. 选择渠道／提供商以及所需工具。
4. 配置网关访问、密钥和远程连接。
5. 验证新手引导流程、配置健康状况和控制界面的可访问性。
6. 执行故障排查和安全加固清单。

严格禁止事项

• 不要将供应商文档中的大段原文复制到此技能中。
• 没有文档依据时，不要臆造默认值或隐藏行为。
• 不要为了生产环境中的便利而削弱安全控制（配对、允许列表、身份验证、沙箱）。

链接

• 文档
• 发行版本

主要文档页面：架构、工具、网关