对于OpenClaw：核心命令以及飞书钉钉等渠道的解析

从命令行操控到 AI 自主执行 ------ 逐条拆解 OpenClaw 的日常操作命令、内置工具的核心机制，以及飞书、钉钉等 IM 平台的完整接入流程

---

目录

1. [引言：掌握 OpenClaw 的"操控杆"](#引言：掌握 OpenClaw 的"操控杆")
2. [CLI 命令体系全景](#CLI 命令体系全景)
   • 2.1 命令分类总览
   • 2.2 网关管理命令
   • 2.3 用户界面命令
   • 2.4 配置管理命令
   • 2.5 [Skills 管理命令](#Skills 管理命令)
   • 2.6 模型管理命令
   • 2.7 版本与更新命令
   • 2.8 全局标志与输出模式
   • 2.9 对话内斜杠命令
   • 2.10 渠道管理命令
   • 2.11 配对管理命令
   • 2.12 消息管理命令
   • 2.13 [Agent 管理命令](#Agent 管理命令)
   • 2.14 安全与密钥管理命令
   • 2.15 沙箱管理命令
   • 2.16 审批管理命令
   • 2.17 日志与状态管理命令
   • 2.18 更多实用命令
3. 内置工具深度解析
   • 3.1 工具体系概览
   • 3.2 文件操作工具
   • 3.3 [执行工具 exec](#执行工具 exec)
   • 3.4 [进程管理工具 process](#进程管理工具 process)
   • 3.5 [网络搜索工具 web_search](#网络搜索工具 web_search)
   • 3.6 [网页抓取工具 web_fetch](#网页抓取工具 web_fetch)
   • 3.7 [浏览器工具 browser](#浏览器工具 browser)
   • 3.8 [定时任务工具 cron](#定时任务工具 cron)
   • 3.9 工具配置策略
   • 3.10 循环检测与安全防护
   • 3.11 [Gateway 管理工具](#Gateway 管理工具)
   • 3.12 会话管理工具
   • 3.13 工具组合实战：从单一工具到工作流
   • 3.14 [图像分析工具 image](#图像分析工具 image)
   • 3.15 [PDF 分析工具 pdf](#PDF 分析工具 pdf)
   • 3.16 [Canvas 画布工具 canvas](#Canvas 画布工具 canvas)
   • 3.17 [节点管理工具 nodes](#节点管理工具 nodes)
   • 3.18 [消息工具 message](#消息工具 message)
   • 3.19 [记忆工具 memory_search / memory_get](#记忆工具 memory_search / memory_get)
4. 飞书渠道配置完整指南
   • 4.1 飞书开放平台创建应用
   • 4.2 安装飞书插件
   • 4.3 配置事件与回调
   • 4.4 配对与授权
   • 4.5 测试与使用
5. 钉钉渠道配置完整指南
   • 5.1 [一键创建 OpenClaw 机器人](#一键创建 OpenClaw 机器人)
   • 5.2 官方插件配置
   • 5.3 社区插件配置
   • 5.4 插件卸载与清理
6. 其他渠道配置详解
   • 6.1 [Telegram 接入](#Telegram 接入)
   • 6.2 [Discord 接入](#Discord 接入)
   • 6.3 [Slack 接入](#Slack 接入)
   • 6.4 企业微信接入
   • 6.5 [QQ 接入](#QQ 接入)
   • 6.6 渠道接入对比总结
7. 渠道配置故障排查指南
   • 7.1 飞书渠道常见问题
   • 7.2 钉钉渠道常见问题
8. 安全实践与操作建议
   • 8.1 [exec 工具的安全边界](#exec 工具的安全边界)
   • 8.2 沙箱隔离
   • 8.3 日常操作建议
   • 8.4 渠道配置检查清单

---

一、引言：掌握 OpenClaw 的"操控杆"

Install OpenClaw 之后，摆在面前的第一件事就是：怎么用？ 命令行怎么敲？内置工具有哪些，各自能做什么？怎么把 AI 助手接入飞书或钉钉，让它在日常工作的聊天框里随时待命？

这些问题看似基础，但它们是后续一切高阶用法的前提。如果对基础命令不熟悉，遇到问题时只能盲目搜索；如果对内置工具的能力边界不清楚，就不知道 AI 能帮你做什么、不能帮你做什么；如果渠道配置没有走通，AI 助手就始终"困"在命令行里，无法融入日常协作。

本章节将 OpenClaw 的日常操作拆解为三个维度：

• CLI 命令：OpenClaw 提供了一套超过 40 个顶层命令的 CLI 工具集，覆盖网关管理、配置、Skills、模型、会话、沙箱、安全等方方面面。本章节将这些命令按使用场景分类，逐一给出用途说明和参数解析。
• 内置工具：OpenClaw 内置了 15 个以上的第一方工具，它们让 AI 从"只能说话"进化为"能够动手"。每一个工具的名称、参数、返回值、适用场景和注意事项，都会在本章节中讲解清楚。
• 渠道配置：以飞书和钉钉为主线，完整走通从创建应用、安装插件、配置回调到发送测试消息的全流程。同时给出企业微信、QQ、Telegram、Discord 等渠道的接入指引。

最后，本章节会专门用一节讨论安全实践------因为 OpenClaw 的强大之处恰恰也是它的风险所在，exec 工具相当于把系统控制权交给了 AI，需要在使用前充分理解其安全边界。

---

二、CLI 命令体系全景

2.0 为什么 CLI 是 OpenClaw 的核心控制界面

OpenClaw 的设计哲学是"配置即代码，命令行即界面"。与其他 AI 助手产品不同------它们通常以图形界面为默认入口------OpenClaw 选择 CLI 作为主要控制界面。这个选择有几个深层次的原因：

• 可脚本化：CLI 命令可以被 Shell 脚本调用，可以被 CI/CD 管道集成，可以被定时任务触发。图形界面很难做到这一点
• 远程友好：在 SSH 连接中，CLI 是唯一可用的交互方式。意味着你可以在任何地方管理你的 OpenClaw 实例
• 精确控制：每个参数都有明确的语义，不存在"我点了这个按钮到底做了什么"的模糊
• 配置即代码 ：CLI 命令（如 config set）直接修改 JSON 配置文件，这些文件可以被版本控制，可以被团队共享

理解了 CLI 在 OpenClaw 中的角色，再看下面的命令分类，就会明白为什么 OpenClaw 命令体系如此丰富------它不仅是操作工具，更是 OpenClaw 的"编程接口"。

2.1 命令分类总览

OpenClaw 的 CLI 命令体系可以按功能分为 12 个类别，超过 40 个顶层命令，每个命令下还有子命令和可选参数。下表按使用场景做了分类，便于快速定位：

类别	核心命令	用途
初始化和配置	onboard, setup, configure, config, doctor	初始化环境、配置向导、诊断
网关管理	gateway start/stop/restart/status/install/uninstall	网关服务生命周期管理
用户界面	tui, dashboard	终端界面和 Web 界面
模型管理	models list/status/set, infer	查看和切换 AI 模型
Skills 管理	skills list/install/uninstall/enable/disable/search	技能扩展管理
插件管理	plugins list/install/uninstall/update	第三方插件管理
会话管理	sessions, message, transcripts	查看和管理对话会话
渠道管理	channels list/add/remove, pairing	通信渠道配置和配对
定时任务	cron list/add/remove/run, tasks	定时任务调度
安全与沙箱	security, secrets, sandbox, approvals	安全策略和审批管理
系统与运维	update, backup, reset, uninstall, logs, status	版本更新、备份、日志
节点与网络	nodes, devices, directory	多节点管理和设备发现

命令树结构 ：所有命令都以 openclaw 为入口，格式为 openclaw <command> [subcommand] [flags]。OpenClaw 支持全局标志（Global Flags），可以在任何命令前使用 --dev、--profile <name> 等参数来改变运行环境。

openclaw [--dev] [--profile <name>] <command> [subcommand] [flags]

2.2 网关管理命令

网关（Gateway）是 OpenClaw 的核心后台进程，所有 Agent 的推理、工具调用、渠道通信都通过 Gateway 进行。对网关的管理是日常操作中最频繁的动作。

openclaw gateway ------ 启动网关服务

这是最基础的启动命令，执行后 Gateway 在前台运行，终端会被占用，日志实时输出到终端。

openclaw gateway

如果在启动时需要指定端口或开启详细日志：

openclaw gateway --port 18789 --verbose

参数	类型	说明
--port	number	指定 Gateway 监听端口。默认 18789，可自定义
--verbose	flag	开启详细日志输出，便于排查问题
--bind	string	绑定地址。loopback（仅本机）、lan（局域网）、auto（自动检测）

openclaw gateway stop ------ 停止网关服务

openclaw gateway stop

这个命令会向正在运行的 Gateway 进程发送停止信号，等待其安全退出。正在进行的 Agent 任务会被妥善终止，不会留下僵尸进程。

openclaw gateway restart ------ 重启网关服务

openclaw gateway restart

重启是最常用的"修好了"操作。修改配置文件后，通常需要重启 Gateway 才能使变更生效。内部实现是先停止再启动，整个过程通常只需要 2-3 秒。

openclaw gateway status ------ 查看网关运行状态

openclaw gateway status

返回信息包括：Gateway 是否在运行、进程 ID、监听端口、运行时长、当前连接的渠道数量、活跃会话数。这是一个快速检查"系统是否正常"的命令。

openclaw gateway install ------ 安装为系统服务

openclaw gateway install

这个命令将 Gateway 注册为系统服务------在 Linux 上使用 systemd，在 macOS 上使用 launchd。安装后，Gateway 会在系统启动时自动运行，不需要手动启动。适合服务器场景。

openclaw gateway uninstall ------ 卸载系统服务

openclaw gateway uninstall

从系统服务中移除 Gateway，但不会删除配置文件和数据。

日常使用流程：

# 1. 启动服务
openclaw gateway

# 2. 在另一个终端中开始对话
openclaw tui

# 3. 使用完毕后停止服务
openclaw gateway stop

配置变更后：

# 1. 修改配置
openclaw config set gateway.port 19000

# 2. 重启生效
openclaw gateway restart

# 3. 确认运行正常
openclaw doctor

2.3 用户界面命令

OpenClaw 提供两种交互界面：TUI（终端界面）和 WebUI（网页界面），两者可以同时使用，互不干扰。

openclaw tui ------ 终端用户界面

openclaw tui

TUI 是一个基于终端的交互式对话界面。启动后，光标会停留在输入行，你可以直接输入自然语言与 AI 对话。AI 的回复会实时流式显示在终端中。TUI 的优势在于：不需要浏览器、在 SSH 远程连接中也能使用、响应速度快。

openclaw tui 有两个别名：openclaw chat 和 openclaw terminal，它们的行为完全一致，都会启动本地对话模式。

openclaw dashboard ------ Web 用户界面

openclaw dashboard

执行后，OpenClaw 会自动打开系统默认浏览器，访问 http://127.0.0.1:18789。Dashboard 提供了完整的图形化管理界面，包括：

• 对话界面：与 Agent 进行多轮对话，支持 Markdown 渲染和代码高亮
• Agent 管理：查看和切换不同的 Agent 配置
• 会话列表：查看历史对话记录，可以恢复之前的会话
• Skills 管理：浏览、安装、启用/禁用 Skills
• 系统状态：查看 Gateway 状态、资源使用情况、最近的日志

TUI vs Dashboard 的选择建议：

场景	推荐
SSH 远程连接、无图形界面	TUI
快速提问、一次性操作	TUI
长时间对话、需要查看历史	Dashboard
管理 Skills、配置渠道	Dashboard
日常开发环境	两者配合使用

2.4 配置管理命令

配置管理是 OpenClaw 日常使用中频率仅次于网关管理的操作类别。

openclaw onboard ------ 运行初始配置向导

openclaw onboard

这是首次安装 OpenClaw 后运行的第一个命令。它以交互式问答的方式引导完成：选择 AI 模型提供商、输入 API Key、选择通信渠道、设置 Gateway 访问模式和认证方式。向导完成后，会在 ~/.openclaw/ 目录下生成 openclaw.json 配置文件。

openclaw configure ------ 进入配置向导

openclaw configure

configure 和 onboard 的区别在于：onboard 是完整的首次配置流程，configure 是对已有配置的针对性修改。configure 允许只修改特定部分------比如只更换模型、只添加渠道、只调整 Gateway 设置------而不需要重新走完整的配置流程。

openclaw config get ------ 查看当前配置

openclaw config get

这个命令输出当前合并后的完整配置。它显示的不是 openclaw.json 的原始内容，而是将默认值、配置文件和运行时参数合并后的最终生效配置。这有助于排查"我明明在配置文件里改了，为什么没生效"这类问题。

openclaw config set <key> <value> ------ 修改特定配置项

openclaw config set gateway.port 19000
openclaw config set agents.defaults.model.primary "deepseek/deepseek-chat"

config set 使用点号分隔的路径语法来定位配置项。它直接修改 openclaw.json 文件中的对应字段，不需要手动编辑 JSON。这个命令的优势在于：它会进行格式校验，不会写入无效的配置值。

openclaw config unset <key> ------ 删除配置项

openclaw config unset channels.telegram

删除后，该配置项回退到默认值。

openclaw doctor ------ 系统诊断

openclaw doctor

doctor 命令对系统环境进行全面检查，包括：

• 配置文件格式是否正确
• API Key 是否有效（会尝试连接验证）
• 依赖版本是否兼容
• Skills 签名是否有效
• Gateway 端口是否被占用
• 网络连接是否正常

openclaw doctor --repair ------ 诊断并自动修复

openclaw doctor --repair

在 doctor 的基础上，添加 --repair 标志会尝试自动修复发现的问题。例如：修复配置文件中的格式错误、重新生成损坏的 Skills 缓存、清理无效的会话数据。

2.5 Skills 管理命令

Skills 是 OpenClaw 的功能扩展机制，管理 Skills 是日常使用中的重要操作。

openclaw skills list ------ 列出已安装的 Skills

openclaw skills list

输出包含每个 Skill 的名称、版本、状态（启用/禁用）、来源（本地/ClawHub）和简短描述。

openclaw skills install <name> ------ 安装 Skill

openclaw skills install @openclaw/github-issue-triage

Skill 名称格式通常为 @namespace/skill-name。从 ClawHub 安装的 Skills 会自动绑定到固定的 commit hash（v2026.6.5 起），防止开发者后续恶意修改。

openclaw skills uninstall <name> ------ 卸载 Skill

openclaw skills uninstall @openclaw/weather

卸载会删除 Skill 的所有文件，包括 SKILL.md 和关联的测试数据。如果该 Skill 正在被某个 Agent 使用，卸载后 Agent 将无法再调用它。

openclaw skills enable <name> / openclaw skills disable <name> ------ 启用/禁用

openclaw skills enable @openclaw/file-organizer
openclaw skills disable @openclaw/file-organizer

禁用不等于卸载。禁用的 Skill 仍在系统中，但 Agent 不会调用它。这比卸载更灵活------当你暂时不需要某个 Skill 但又不想重新安装时，禁用它即可。

openclaw skills search <keyword> ------ 搜索 Skill

openclaw skills search "weather"

在 ClawHub 上搜索包含指定关键词的 Skills。返回结果包括 Skill 名称、描述、安装量、评分。

openclaw skills check <name> ------ 检查 Skill 状态

openclaw skills check @openclaw/weather

检查指定 Skill 的完整性------SKILL.md 格式是否正确、依赖的工具是否可用、是否有安全更新。

openclaw skills update ------ 更新所有 Skills

openclaw skills update

将所有已安装的 Skills 更新到最新版本。建议在更新前备份配置，以防新版本引入不兼容的变更。

2.6 模型管理命令

openclaw models list ------ 列出可用模型

openclaw models list

输出当前配置的所有模型提供商及其下可用的模型列表。每个模型显示其 ID、名称、是否支持推理（reasoning）、上下文窗口大小和最大输出 token 数。

openclaw models status ------ 查看模型状态

openclaw models status

更详细地显示每个模型的当前状态：是否可用、API 连接状态、最近的响应延迟、token 使用量统计。

openclaw models set <provider/model> ------ 切换默认模型

openclaw models set deepseek/deepseek-chat

这个命令修改 agents.defaults.model.primary 配置项，将默认模型切换为指定的模型。切换后需要重启 Gateway 才能生效。

2.7 版本与更新命令

openclaw version 或 openclaw --version ------ 查看版本

openclaw --version
# 输出示例: 2026.3.22

OpenClaw 使用 CalVer（日历版本号）格式 YYYY.M.D，而非传统的语义版本号。这种命名方式让你一眼就能看出当前版本是何时发布的。

openclaw update ------ 更新 OpenClaw

openclaw update

将 OpenClaw 更新到最新稳定版。更新过程包括：检查新版本、下载更新包、安装更新、重启 Gateway。建议在更新前先用 openclaw backup 备份配置。

openclaw backup ------ 备份配置

openclaw backup

将当前配置和数据打包备份到 ~/.openclaw/backups/ 目录下。备份内容包括：openclaw.json、SOUL.md、MEMORY.md、HEARTBEAT.md、已安装的 Skills 列表。

openclaw uninstall ------ 卸载 OpenClaw

openclaw uninstall

完全移除 OpenClaw。执行时会提示是否保留配置文件和数据------如果选择保留，以后重新安装时可以恢复之前的配置。

2.8 全局标志与输出模式

OpenClaw 提供了一套全局标志，可以在任何命令前使用，用于改变运行环境或输出格式。

标志	用途
--dev	将状态隔离到 ~/.openclaw-dev 目录，并偏移默认端口。用于开发和测试，避免影响生产环境
--profile <name>	将状态隔离到 ~/.openclaw-<name> 目录。用于管理多个独立的 OpenClaw 实例
--container <name>	指定目标容器执行命令
--no-color	禁用 ANSI 颜色输出。在脚本中捕获输出时使用
--json	以 JSON 格式输出，禁用样式。适合脚本解析
-V, --version, -v	打印版本号并退出

输出模式说明：

• 在 TTY 会话中（终端直接交互），OpenClaw 默认使用 ANSI 颜色和进度指示器
• 在非 TTY 会话中（如脚本管道），自动禁用颜色和进度指示器
• 使用 --json 标志可以强制输出 JSON 格式，适合与其他工具链集成
• 长时间运行的命令会显示进度指示器（OSC 9;4 协议）

2.9 对话内斜杠命令

在 TUI 或 Dashboard 的对话中，可以使用斜杠（/）开头的快捷命令，无需退出对话界面。

命令	用途
/status	快速查看系统状态
/trace	开启会话级插件追踪和调试
/config	持久化配置变更
/debug	运行时配置覆盖（仅内存，不写入磁盘；需要 commands.debug: true）
/model <name>	切换当前会话使用的模型
/clear	清除当前会话的上下文
/help	显示可用命令列表

这些命令在飞书、钉钉等 IM 渠道中同样有效------只需要在聊天框中输入 /status，Agent 就会返回当前系统状态。

2.10 渠道管理命令

渠道（Channel）命令用于管理 OpenClaw 与 IM 平台的连接，包括添加、删除、查看状态等操作。

openclaw channels list ------ 列出所有渠道

openclaw channels list

返回当前配置的所有渠道及其状态：渠道名称、类型（feishu/dingtalk/telegram 等）、连接状态（active/inactive/error）、最近活动时间。

openclaw channels add ------ 添加渠道

openclaw channels add

不带参数运行时，channels add 启动引导式配置------交互式选择渠道类型（飞书/钉钉/Telegram/Discord 等），然后根据所选渠道提示输入相应的凭证。带参数运行时，可以脚本化添加渠道：

# 脚本化添加 Telegram 渠道
openclaw channels add telegram --bot-token "123456:ABCdef"

# 脚本化添加飞书渠道
openclaw channels add feishu --app-id "cli_xxx" --app-secret "xxx"

openclaw channels remove <name> ------ 删除渠道

openclaw channels remove telegram

从配置中删除指定渠道。删除后，该渠道的所有连接会被关闭。

openclaw channels status <name> ------ 查看渠道状态

openclaw channels status feishu

返回指定渠道的详细状态：连接类型（WebSocket/HTTP）、是否在线、连接时长、最近消息时间、是否有待处理的配对请求。

openclaw channels capabilities <name> ------ 查看渠道能力

openclaw channels capabilities feishu

返回该渠道支持的消息类型和能力：文本消息、图片、文件、语音、视频、交互式卡片、群聊、私聊等。

2.11 配对管理命令

配对（Pairing）是 OpenClaw 的安全机制------防止未授权用户通过 IM 渠道访问 Agent。

openclaw pairing list ------ 查看待审批配对

openclaw pairing list

列出所有等待审批的配对请求。每条记录包含：渠道名称、用户标识、请求时间。

openclaw pairing approve <channel> <code> ------ 批准配对

openclaw pairing approve feishu ABC123
openclaw pairing approve telegram 987654321 --notify

参数	说明
<channel>	渠道名称。如 feishu、telegram、dingtalk
<code>	配对码。用户在 IM 平台上与机器人交互后获得
--notify	审批完成后通过该渠道通知对方

openclaw qr <channel> ------ 生成配对二维码

openclaw qr feishu

在终端中生成一个二维码，用户扫描后可以快速完成配对。这在飞书等支持扫码的平台上尤其方便。

2.12 消息管理命令

消息命令允许从 CLI 直接发送消息、广播通知、管理对话。

openclaw message send ------ 发送消息

openclaw message send --target telegram --message "系统备份已完成"
openclaw message send --target feishu:group/oc_xxx --message "服务器告警：CPU 使用率超过 90%"

参数	说明
--target	目标。格式为 channel:target，如 telegram:123456、feishu:group/oc_xxx
--message	消息内容
--media	可选的附件路径（图片、文件）

openclaw message broadcast ------ 广播消息

openclaw message broadcast --message "系统维护通知：今晚 22:00-23:00 服务暂停"

向所有已连接的渠道广播同一条消息。适合发送系统级通知。

openclaw message poll ------ 创建投票

openclaw message poll --target telegram:group/-123456 --question "今天午饭吃什么？" --options "中餐,日料,西餐,沙拉"

在指定群聊中创建一个投票。支持 WhatsApp、Discord 和 MS Teams 平台。

openclaw message search ------ 搜索消息

openclaw message search --channel telegram --keyword "部署"

在指定渠道中搜索包含关键词的历史消息。返回匹配消息的列表，包含发送者、时间戳和内容摘要。

2.13 Agent 管理命令

Agent 命令用于管理多个 Agent 实例的创建、配置和绑定。

openclaw agent ------ 直接调用 Agent

openclaw agent "帮我分析一下当前服务器的性能状况"

从 CLI 直接向 Agent 发送一条指令并获取回复。这本质上是 openclaw message 的简化版------不需要指定目标，默认为当前默认 Agent。

openclaw agents list ------ 列出所有 Agent

openclaw agents list

返回所有已配置的 Agent 列表，包括：Agent ID、名称、使用的模型、绑定的渠道和当前状态。

openclaw agents add ------ 创建新 Agent

openclaw agents add --id "tech-support" --model "deepseek/deepseek-chat" --soul "./souls/tech-support.md"

创建一个新 Agent 配置。这个命令修改 openclaw.json 中的 agents.list 节点。

openclaw agents delete <id> ------ 删除 Agent

openclaw agents delete tech-support

从配置中删除指定的 Agent。

openclaw agents bindings ------ Agent 渠道绑定

openclaw agents bindings set tech-support --channel feishu:group/oc_xxx

将 Agent 绑定到特定渠道或群组。绑定后，该渠道/群组的所有消息都路由到这个 Agent 处理。

2.14 安全与密钥管理命令

openclaw security audit ------ 安全审计

openclaw security audit

对当前 OpenClaw 实例进行全面的安全审计。检查项包括：

• 配置文件权限（是否过于宽松）
• Gateway 绑定地址（是否暴露到公网）
• API Key 存储方式（是否明文存储）
• Skills 签名验证状态
• 沙箱启用状态
• 审批策略配置

审计结果以报告形式输出，包含每个检查项的状态（通过/警告/危险）和修复建议。

openclaw secrets reload ------ 重新加载密钥

openclaw secrets reload

从环境变量和系统密钥链中重新加载密钥。当你更新了环境变量中的 API Key 但不想重启 Gateway 时，使用这个命令。

openclaw secrets audit ------ 密钥审计

openclaw secrets audit

检查所有已配置的密钥状态：是否有效、是否即将过期、是否有泄露风险（如在 Skill 日志中意外暴露）。

openclaw secrets configure ------ 配置密钥

openclaw secrets configure

交互式地添加、更新或删除密钥。支持的系统密钥链：macOS Keychain、Windows Credential Manager、Linux Secret Service。

2.15 沙箱管理命令

openclaw sandbox list ------ 列出沙箱

openclaw sandbox list

返回所有沙箱实例的状态：沙箱 ID、创建时间、状态（running/stopped）、使用的镜像。

openclaw sandbox recreate ------ 重建沙箱

openclaw sandbox recreate

销毁当前沙箱并创建一个新的。当你更新了沙箱镜像或需要清理沙箱中的临时数据时使用。

openclaw sandbox explain <sessionId> ------ 沙箱执行解释

openclaw sandbox explain abc123

对指定会话在沙箱中的执行过程进行解释------展示 Agent 的推理链、工具调用序列和每个步骤的结果。这在调试 Agent 的异常行为时非常有用。

2.16 审批管理命令

审批（Approvals）机制是 OpenClaw 安全体系的重要组成部分，它允许你对 Agent 的敏感操作设置审批规则。

openclaw approvals get ------ 查看审批策略

openclaw approvals get

返回当前的审批策略配置：哪些工具需要审批、审批模式（always/on-miss/off）、白名单规则。

openclaw approvals set <tool>.<param> <value> ------ 设置审批策略

openclaw approvals set exec.ask always
openclaw approvals set browser.ask on-miss

设置项	说明
exec.ask	exec 工具的审批模式。always（始终审批）、on-miss（白名单未命中时审批）、off（不审批）
browser.ask	browser 工具的审批模式

openclaw approvals allowlist add <pattern> ------ 添加白名单

openclaw approvals allowlist add "ls -la"
openclaw approvals allowlist add "git status"

白名单中的命令不需要审批即可执行。这对常用的安全命令（如 ls、git status）非常实用------不需要每次执行都点"确认"。

openclaw approvals allowlist remove <pattern> ------ 移除白名单

openclaw approvals allowlist remove "ls -la"

2.17 日志与状态管理命令

openclaw logs ------ 查看日志

openclaw logs

查看 Gateway 的实时日志流。默认显示最近 100 行，持续输出新日志。

# 查看最近 500 行
openclaw logs --lines 500

# 过滤包含特定关键词的日志
openclaw logs --filter "error"

# 查看指定渠道的日志
openclaw logs --channel feishu

openclaw status ------ 查看系统状态

openclaw status

返回 OpenClaw 的综合状态报告：Gateway 运行状态、活跃会话数、已连接渠道数、内存使用量、CPU 使用率、最近错误数。

openclaw health ------ 健康检查

openclaw health

执行快速健康检查：Gateway 是否在运行、API 是否可访问、渠道连接是否正常。适合在自动化监控脚本中使用（可以配合 --json 标志获取结构化输出）。

openclaw system event ------ 查看系统事件

openclaw system event

列出最近的系统事件：Gateway 启动/停止、配置变更、渠道连接/断开、定时任务执行、错误日志。

openclaw system heartbeat last ------ 查看最近心跳

openclaw system heartbeat last

查看 Heartbeat 调度器的最近执行记录：哪些定时任务被执行了、执行结果（成功/失败）、执行耗时。

2.18 更多实用命令

openclaw browser status ------ 浏览器状态

openclaw browser status

查看 OpenClaw 管理的浏览器实例状态：是否在运行、当前标签页数量、截图存储路径。

openclaw reset ------ 重置 OpenClaw

openclaw reset

将 OpenClaw 恢复到初始状态------清除所有配置、会话数据、Skills 安装记录。执行前会提示确认。适合在"从头开始"时使用。

openclaw sessions cleanup ------ 清理会话

openclaw sessions cleanup

清理旧的、不活跃的会话数据，释放磁盘空间。默认清理超过 7 天不活跃的会话。

openclaw transcripts list ------ 查看对话记录

openclaw transcripts list
openclaw transcripts list --session abc123
openclaw transcripts show abc123

列出或查看指定会话的完整对话记录。每轮对话包含用户消息、Agent 回复和工具调用信息。

openclaw memory status ------ 记忆状态

openclaw memory status

查看 Agent 的记忆系统状态：已存储的记忆条目数、最近索引时间、存储空间使用量。

openclaw memory search <keyword> ------ 搜索记忆

openclaw memory search "项目部署"

在 Agent 的记忆库中搜索包含指定关键词的记忆条目。Agent 可以跨会话"记住"重要信息------用户的偏好、项目背景、常用命令------这个命令让你可以查看 Agent 都记住了什么。

---

三、内置工具深度解析

3.1 工具体系概览

内置工具（Built-in Tools）是 OpenClaw 的核心能力载体。它们让 AI 从"只能说话"进化为"能够动手"。当 Agent 需要执行具体操作时------读取文件、发送 HTTP 请求、执行系统命令、搜索网页------它会调用相应的工具来完成。

内置工具与 Skills 的关系：

• 内置工具是基础能力，由 OpenClaw 核心提供，无需安装，开箱即用
• Skills 是基于内置工具或外部 API 构建的更高层功能模块，可单独安装和卸载
• Skill 本质上是对内置工具的"编排"------它告诉 Agent 在什么场景下、以什么顺序、用哪些参数来调用内置工具

一个直观的类比：内置工具像是编程语言的内置函数（如 read()、write()、exec()），而 Skills 像是你用这些函数写出来的库（如"GitHub Issue 自动分类"这个 Skill 内部调用了 HTTP 工具和文件读写工具）。

OpenClaw 4.x 内置工具完整列表 1：

工具分组	工具名	核心功能
group:fs	read	读取文件内容
group:fs	write	创建或覆盖写入文件
group:fs	edit	精确替换文件中的内容
group:fs	apply_patch	跨多文件应用结构化补丁
group:runtime	exec	在工作区中运行 shell 命令
group:runtime	process	管理后台 exec 会话
group:web	web_search	搜索引擎查询（需配置 API Key）
group:web	web_fetch	获取网页内容（HTML → Markdown/文本）
group:ui	browser	控制 OpenClaw 管理的专用浏览器
group:ui	canvas	驱动节点 Canvas（展示、评估、截图）
group:automation	cron	管理定时任务和唤醒事件
group:automation	gateway	重启或应用更新到 Gateway 进程
group:sessions	sessions_list / sessions_history / sessions_send / sessions_spawn / session_status	会话管理
group:memory	memory_search / memory_get	记忆搜索和检索
group:nodes	nodes	节点发现、配对、通知
group:messaging	message	跨渠道消息发送和管理
---	image	使用配置的图像模型分析图片
---	pdf	分析 PDF 文档
---	loop-detection	工具调用循环检测（防止 Agent 陷入死循环）

3.2 文件操作工具

文件操作是 Agent 最基础的能力之一。OpenClaw 提供了四个文件操作工具：read、write、edit 和 apply_patch，它们属于 group:fs 分组。

read ------ 读取文件内容

read 工具用于读取本地文件系统中的文本文件。它支持按行读取、指定偏移量和限制读取行数。

# Agent 在对话中调用 read 工具读取文件
# 用户指令示例：
"帮我把这个文件 D:\资料\test.txt 中'你好'改成'您好'"

Agent 收到指令后，首先调用 read 工具读取文件内容，然后调用 edit 工具进行精确替换。

write ------ 创建或覆盖写入文件

write 工具用于创建新文件或覆盖已有文件的内容。它接受文件路径和内容两个核心参数。

edit ------ 精确替换文件中的内容

edit 是 OpenClaw 文件操作中最精细的工具。它通过"搜索-替换"模式来修改文件中的特定片段，而不是整个文件重写。这种机制的优势在于：只修改需要改的部分，不会影响文件的其他内容。

apply_patch ------ 跨文件补丁应用

apply_patch 是一个实验性工具，支持跨多个文件的结构化补丁操作。它需要显式启用：tools.exec.applyPatch.enabled 设为 true。默认情况下，apply_patch 只允许在工作区目录内操作（tools.exec.applyPatch.workspaceOnly 默认为 true）。

文件操作工具的安全边界 ：所有文件操作工具默认被限制在 Agent 的工作区目录内。要访问工作区以外的文件，需要在配置中显式指定 allowed_paths 或 allowed_dirs。

3.3 执行工具 exec

exec 是 OpenClaw 中最强大也最需要谨慎使用的工具。它允许 Agent 在工作区中执行 shell 命令，相当于将系统命令执行权交给了 AI 2。

exec 工具的核心参数：

参数	类型	必需	说明
command	string	是	要执行的 shell 命令
yieldMs	number	否	自动转入后台的等待时间（毫秒），默认 10000（10 秒）
background	boolean	否	立即在后台执行，不等待命令完成
timeout	number	否	超时时间（秒），超时后强制终止进程，默认 1800（30 分钟）
elevated	boolean	否	在宿主机上以提升权限运行（仅当 Agent 运行在沙箱中且 elevated 模式被允许时生效）
host	string	否	执行目标。sandbox（沙箱内）、gateway（Gateway 宿主机）、node（远程节点）
security	string	否	安全策略。deny（禁止）、allowlist（白名单）、full（完全放开）
ask	string	否	审批策略。off（不询问）、on-miss（白名单未命中时询问）、always（总是询问）
node	string	否	目标节点 ID 或名称（当 host=node 时使用）
pty	boolean	否	是否分配伪终端。需要真正 TTY 的命令（如 ssh、sudo）应设为 true

exec 的工作机制：

当 Agent 调用 exec 时，命令在指定环境中执行。默认情况下，命令在沙箱（如果启用了沙箱）或工作区目录中运行。命令执行完成后，exec 返回以下信息：

• exitCode：命令的退出码（0 表示成功）
• stdout：标准输出内容
• stderr：标准错误输出内容
• status：如果命令转入后台，返回 "running" 及 sessionId

exec 的使用示例：

# 用户指令：
"帮我列出这个目录 D:\虚拟机共享文件夹 下的所有文件"

# Agent 内部调用 exec 工具：
# command: "ls -la 'D:\虚拟机共享文件夹'"
# 返回目录下的文件列表

沙箱模式下的 exec ：当沙箱启用时，exec 命令被包装在 docker exec 中执行。沙箱提供了一个隔离的环境：工作目录被映射到 /workspace，Agent 无法访问宿主机级别的目录，无法修改系统配置，无法与其他容器交互。这本质上为 exec 增加了一层安全保护。

exec 的安全警告 ：exec 是 OpenClaw 中最强大也最危险的组件。它允许 Agent 执行任意系统命令，相当于将系统控制权交给了 AI。如果使用不当或被恶意利用，可能导致严重后果。下文"安全实践"章节会详细讨论防范措施。

3.4 进程管理工具 process

process 工具与 exec 紧密配合，用于管理通过 exec 转入后台运行的进程。当 exec 使用 background: true 参数或执行时间超过 yieldMs 时，命令会转入后台，返回一个 sessionId。之后就可以通过 process 工具来监控和管理这个后台进程。

process 工具的核心操作：

操作	说明
list	列出当前 Agent 的所有后台进程
poll	获取后台进程的最新输出和退出状态
log	查看后台进程的日志，支持 offset 和 limit 参数
write	向后台进程的标准输入写入数据
kill	终止后台进程
clear	清除后台进程的日志缓冲区
remove	从进程列表中移除已结束的进程

process 的隔离性 ：process 是按 Agent 隔离的------一个 Agent 只能看到和管理自己启动的后台进程，无法访问其他 Agent 的进程。这确保了多 Agent 环境下的安全性。

process 与 exec 的协作流程：

1. Agent 调用 exec(command="long-running-task", background=true)
2. exec 返回 { status: "running", sessionId: "abc123" }
3. Agent 继续执行其他任务...
4. Agent 调用 process.poll(sessionId="abc123") 检查进度
5. process 返回 { status: "running", newOutput: "..." }
6. Agent 再次调用 process.poll(sessionId="abc123")
7. process 返回 { status: "completed", exitCode: 0, finalOutput: "..." }

如果 process 工具被禁用，exec 会退化为同步模式------所有命令必须等待执行完成，yieldMs 和 background 参数被忽略。

3.5 网络搜索工具 web_search

web_search 让 Agent 可以直接查询搜索引擎，获取实时的网络信息。与其他工具不同，web_search 返回的是结构化的搜索结果（标题、URL、摘要），而不是完整的网页内容 3。

web_search 的核心参数：

参数	类型	必需	说明
query	string	是	搜索查询字符串
count	number	否	返回结果数量，范围 1-10，默认 5

web_search 支持的后端 ：OpenClaw 支持多种搜索引擎后端，包括 Brave（默认）、Perplexity、Gemini、Grok 和 Kimi。你需要为选定的后端配置 API Key。推荐使用 openclaw configure --section web 进行配置。

web_search 的返回格式：每次搜索返回一个结构化的结果列表，每个结果包含：

• title：页面标题
• url：页面 URL
• snippet：内容摘要（简短描述）

web_search 的缓存机制：搜索结果会被缓存 15 分钟。在缓存有效期内，相同查询的重复调用不会消耗 API 配额。

web_search 的适用场景：

• 快速事实查证：验证一个说法、查找一个统计数字
• 研究起点：找到相关 URL 后，再用 web_fetch 深入获取完整内容
• 实时信息获取：获取当前新闻、股价、天气等时效性信息

web_search 的配置示例：

{
    "tools": {
        "web": {
            "search": {
                "enabled": true,
                "maxResults": 5
            }
        }
    }
}

3.6 网页抓取工具 web_fetch

web_fetch 用于从指定 URL 提取可读内容，将 HTML 页面转换为 Markdown 或纯文本格式 4。

web_fetch 的核心参数：

参数	类型	必需	说明
url	string	是	要抓取的网页 URL
extractMode	string	否	提取模式。markdown（转换为 Markdown 格式）或 text（纯文本）
maxChars	number	否	最大字符数限制。超出的内容会被截断。受 tools.web.fetch.maxCharsCap 限制（默认 50000）

web_fetch 的工作机制 ：web_fetch 向目标 URL 发起 HTTP GET 请求，下载 HTML 内容，然后使用可读性提取算法去除导航栏、广告、页脚等非正文内容，提取出干净的正文文本。

web_fetch 的缓存机制 ：与 web_search 一样，web_fetch 的结果也会被缓存 15 分钟。

web_fetch 的使用示例：

# 用户指令：
"读取这篇新闻的正文：
https://finance.sina.com.cn/wm/2026-03-25/doc-inhseupy3578551.shtml"

# Agent 内部调用 web_fetch 工具：
# url: "https://finance.sina.com.cn/wm/2026-03-25/doc-inhseupy3578551.shtml"
# extractMode: "markdown"
# 返回以 Markdown 格式展示的新闻正文

web_fetch 的局限性：

• 对于 JavaScript 重度依赖的网站（SPA 应用），web_fetch 无法正确渲染页面内容。此时应使用 browser 工具
• 某些网站有反爬虫机制，可能拒绝 web_fetch 的请求。OpenClaw 提供了 Firecrawl 作为可选的抗反爬虫回退方案

web_search 与 web_fetch 的组合使用：

1. Agent 调用 web_search(query="OpenClaw 最新版本特性")
2. web_search 返回 5 条搜索结果（标题 + URL + 摘要）
3. Agent 从中挑选最相关的 2 条结果
4. Agent 调用 web_fetch(url="https://example.com/release-notes")
5. web_fetch 返回完整的发布说明内容
6. Agent 整合信息，生成回答

3.7 浏览器工具 browser

browser 工具是 OpenClaw 中功能最全面的 UI 交互工具。它控制一个 OpenClaw 管理的专用浏览器实例，支持导航、截图、页面操作、多用户配置等完整功能 5。

browser 的核心操作类别：

类别	操作	说明
生命周期	status, start, stop	浏览器的启动、停止和状态查询
导航	navigate, open, focus, close	标签页的导航和关闭
截图	screenshot	页面截图，返回图片块
快照	snapshot	页面可访问性快照（aria 模式）或 AI 快照
交互	act	UI 操作：click、type、press、hover、drag、select、fill、resize、wait、evaluate
工具	console, pdf, upload, dialog	控制台日志、PDF 生成、文件上传、对话框处理
配置	profiles, create-profile, delete-profile, reset-profile	多用户配置管理

browser 的多配置支持 ：browser 支持多用户配置（Profile），每个配置有独立的浏览器实例、Cookie、会话和端口。配置名称限制为：小写字母、数字和连字符，最多 64 个字符。端口范围 18800-18899，最多支持约 100 个配置。

browser 的常⽤参数：

• profile：指定使用的浏览器配置。不指定时使用默认配置（browser.defaultProfile，默认为 chrome）
• target：执行目标。sandbox（沙箱内）、host（宿主机）、node（远程节点）
• node：指定目标节点 ID 或名称

snapshot 和 act 的配合使用 ：这是 browser 工具最核心的使用模式。snapshot 返回页面的可访问性树或 AI 快照，其中每个可交互元素都有一个引用（ref）。act 使用这些引用（如 e12）来精确操作页面元素，而不需要依赖 CSS 选择器。

1. browser.snapshot() → 返回页面快照，包含 ref 如 e12、e15
2. browser.act(action="click", ref="e12") → 点击"登录"按钮
3. browser.act(action="type", ref="e15", text="username") → 在输入框中输入
4. browser.act(action="press", key="Enter") → 按回车键

browser 与 web_fetch 的选择：

场景	推荐工具
静态网页、博客文章、API 文档	web_fetch
SPA 应用、JavaScript 渲染页面	browser
需要登录、Cookie 的页面	browser
需要填写表单、点击按钮	browser
批量获取多个页面的内容	web_fetch（更快，无浏览器开销）

3.8 定时任务工具 cron

cron 工具让 Agent 可以管理 Gateway 的定时任务------添加、编辑、删除、立即运行和查看运行历史。与 HEARTBEAT.md 的自然语言定时任务不同，cron 工具提供的是精确的程序化控制。

cron 工具的核心操作：

操作	说明
status	查看 cron 调度器的运行状态
list	列出所有已配置的定时任务
add	添加新的定时任务（需要完整的 cron job 对象）
update	更新已有定时任务（使用 { jobId, patch } 格式）
remove	删除定时任务
run	立即执行一次定时任务（不等待调度时间）
runs	查看定时任务的执行历史
wake	入队系统事件，可选立即触发心跳

cron 与 HEARTBEAT.md 的关系：

• HEARTBEAT.md 是用自然语言描述定时任务，Agent 在启动时自动解析并注册到 cron 调度器
• cron 工具允许 Agent 在运行时动态管理定时任务------添加、修改、删除
• 两者最终都通过同一个 cron 调度器执行，区别在于配置方式和使用场景

cron 工具的使用场景：

1. Agent 根据用户指令动态创建定时任务：
   "每周五下午 5 点自动汇总本周的 GitHub 活动"

2. Agent 在执行过程中发现需要定期检查某个状态：
   "每 30 分钟检查一次服务器健康状态，如果异常就通知我"

3. Agent 在任务完成后自动清理不再需要的定时任务

3.9 工具配置策略

OpenClaw 提供了三层工具配置策略，让你可以精确控制哪些工具对哪些 Agent 可用 1。

第一层：全局工具配置

在 openclaw.json 的 tools 节点中配置全局工具策略：

{
    "tools": {
        "allow": ["group:fs", "group:web", "browser"],
        "deny": ["group:runtime"]
    }
}

allow 和 deny 使用工具名称或分组名（group:* 前缀）。deny 优先级高于 allow------如果同一个工具同时出现在两个列表中，它会被禁用。支持 * 通配符（"*" 表示所有工具）。

第二层：工具配置档案（Profiles）

tools.profile 设置一个基础工具允许列表，然后再用 allow/deny 做微调：

Profile	包含的工具
minimal	仅 session_status
coding	group:fs、group:runtime、group:sessions、group:memory、image
messaging	group:messaging、sessions_list、sessions_history、sessions_send、session_status
full	无限制（默认行为）

{
    "tools": {
        "profile": "coding",
        "deny": ["group:runtime"]
    }
}

这个配置的含义是：使用 coding 档案作为基础（包含文件操作、运行时、会话、记忆和图像工具），然后显式禁用运行时工具（exec 和 process）。结果是：Agent 可以读写文件、管理会话、使用图像工具，但不能执行 shell 命令。

第三层：Agent 级别的工具覆盖

每个 Agent 可以有自己的工具配置，覆盖全局设置：

{
    "agents": {
        "list": [
            {
                "id": "support",
                "tools": {
                    "profile": "messaging",
                    "allow": ["slack"]
                }
            }
        ]
    }
}

第四层：提供商特定的工具策略

tools.byProvider 允许你针对特定模型提供商（或特定模型）进一步限制工具：

{
    "tools": {
        "profile": "coding",
        "byProvider": {
            "google-antigravity": { "profile": "minimal" }
        }
    }
}

这个配置的含义是：全局使用 coding 档案，但通过 Google Antigravity 模型时只使用 minimal 档案（仅 session_status）。这在某些模型对工具调用的支持不完善时非常实用。

3.10 循环检测与安全防护

loop-detection 是 OpenClaw 内置的工具调用循环检测机制。它追踪 Agent 最近的工具调用历史，当检测到重复、无进展的调用模式时，发出警告或阻止 6。

循环检测的配置：

{
    "tools": {
        "loopDetection": {
            "enabled": true,
            "warningThreshold": 10,
            "criticalThreshold": 20,
            "globalCircuitBreakerThreshold": 30,
            "historySize": 30,
            "detectors": {
                "genericRepeat": true,
                "knownPollNoProgress": true,
                "pingPong": true
            }
        }
    }
}

参数	说明
enabled	是否启用循环检测。默认 false
warningThreshold	警告阈值。达到此数量的重复调用时发出警告
criticalThreshold	严重阈值。达到此数量时阻止继续调用
globalCircuitBreakerThreshold	全局熔断阈值。整个会话级别，超过后强制中断
historySize	追踪的历史调用数量
detectors.genericRepeat	检测"相同工具 + 相同参数"的重复调用
detectors.knownPollNoProgress	检测轮询类工具（如 process.poll）的重复无进展调用
detectors.pingPong	检测 A/B/A/B 交替无进展模式

循环检测的典型场景 ：Agent 在调用 web_search 后没有找到结果，然后调整关键词再次搜索，仍然没有找到，再次调整......这种"搜索-失败-搜索"的循环如果没有检测机制，可能会一直持续下去，消耗大量 API 配额。loopDetection 在检测到这种模式后，会先警告 Agent，如果继续则阻止调用，让 Agent 意识到需要改变策略。

3.11 Gateway 管理工具

gateway 工具允许 Agent 在运行时管理 Gateway 自身------重启、更新配置、应用更新。这听起来有点危险（Agent 能自己重启自己的运行时），但它是实现"自主运维"的关键能力。

gateway 工具的核心操作：

操作	说明
restart	授权后发送 SIGUSR1 信号，触发 Gateway 进程内重启
config.get	读取当前配置
config.apply	验证、写入配置、重启 Gateway、触发唤醒
config.patch	合并部分更新、重启 Gateway、触发唤醒
config.schema.lookup	查询特定配置路径的 schema（不会将完整 schema 加载到提示词中）
update.run	运行更新、重启 Gateway、触发唤醒

restart 的机制 ：gateway.restart 不会创建新的进程，而是在现有进程内热重启。重启过程包括：重新加载配置文件、重新初始化渠道连接、重新注册 Skills。这比 openclaw gateway restart（完整的进程停止+启动）更快，通常在 1-2 秒内完成。

restart 的安全控制 ：默认情况下 gateway.restart 是启用的。如果你不希望 Agent 自己重启 Gateway，可以在配置中关闭：

{
    "commands": {
        "restart": false
    }
}

config.schema.lookup 的使用场景：当 Agent 需要知道某个配置路径的有效值范围时，它可以查询该路径的 schema，而不是加载整个配置 schema。例如：

Agent 想知道 gateway.auth.mode 的有效值有哪些
→ 调用 gateway.config.schema.lookup(path="gateway.auth")
→ 返回 schema 片段，显示 mode 可选值为 "token" | "password" | "none"

3.12 会话管理工具

会话（Session）是 OpenClaw 中 Agent 与用户交互的基本单位。每次对话都对应一个会话，Agent 可以在会话间切换、查看历史、甚至向其他会话发送消息。

sessions_list：列出所有会话。参数包括：

• kinds：过滤会话类型。可选值如 main（直接对话）、group（群聊）、thread（主题帖）
• limit：返回数量限制
• activeMinutes：只返回最近 N 分钟内活跃的会话
• messageLimit：每个会话返回最近 N 条消息。设为 0 表示不返回消息

sessions_history：查看会话的对话历史。参数包括：

• sessionKey 或 sessionId：目标会话标识
• limit：返回的消息数量
• includeTools：是否包含工具调用的消息（默认过滤掉）

sessions_send：向另一个会话发送消息。参数包括：

• sessionKey 或 sessionId：目标会话
• message：要发送的消息内容
• timeoutSeconds：等待回复的超时时间。设为 0 表示"发送后不等待回复"（fire-and-forget）

sessions_spawn：创建子会话，用于并行执行任务。参数包括：

• task：子会话要执行的任务描述
• label：可选的标签
• agentId：指定使用哪个 Agent 配置
• model：覆盖默认模型
• runTimeoutSeconds：任务超时时间
• mode：执行模式
• streamTo：将结果流式传输到指定会话

session_status ：查看当前会话的状态。接受可选的 sessionKey 参数（默认当前会话），以及 model 参数（设为 default 清除模型覆盖）。

3.13 工具组合实战：从单一工具到工作流

单个工具的能力是有限的，但当它们组合在一起时，可以完成复杂的自动化工作流。以下是几个典型的工具组合场景。

场景一：代码审查工作流

1. exec(command="git diff HEAD~1") → 获取最新的代码变更
2. Agent 分析 diff 内容，识别潜在问题
3. write(path="review.md", content="...") → 将审查意见写入文件
4. message.send(target="slack", message="代码审查完成") → 通知团队

场景二：信息采集与整理工作流

1. web_search(query="2026年AI Agent发展趋势") → 获取搜索结果
2. web_fetch(url="https://example.com/article1") → 获取文章 1 的完整内容
3. web_fetch(url="https://example.com/article2") → 获取文章 2 的完整内容
4. Agent 综合分析两篇文章，提取关键观点
5. write(path="ai_trends_summary.md", content="...") → 保存为本地文件
6. cron.add(job) → 设置每周自动执行一次

场景三：文件批量处理工作流

1. exec(command="ls *.log") → 列出所有日志文件
2. Agent 分析文件列表，找出需要处理的文件
3. read(path="app.log") → 读取第一个文件
4. edit(old="ERROR:", new="[ERROR] 2026-06-16:") → 修正格式
5. 重复步骤 3-4 处理其他文件
6. process.clear → 清理临时数据

3.14 图像分析工具 image

image 工具让 Agent 可以使用配置的图像模型来分析图片内容。与其他工具的不同之处在于：image 使用独立的图像模型（agents.defaults.imageModel），而不是默认的对话模型 1。

image 的核心参数：

参数	类型	必需	说明
image	string	是	图片路径或 URL
prompt	string	否	分析提示词。默认值为 "Describe the image."
model	string	否	覆盖默认的图像模型
maxBytesMb	number	否	图片大小上限（MB）。超过此大小的图片会被拒绝

image 的工作机制 ：当 Agent 调用 image 时，OpenClaw 将图片发送给配置的图像模型（如 GPT-4o、Claude Sonnet 4.5 等支持视觉能力的模型），模型根据 prompt 参数对图片进行分析并返回描述。这个过程独立于主对话------Agent 收到图片分析结果后，将其整合到自己的推理中。

image 的启用条件 ：image 工具只有在 agents.defaults.imageModel 配置了主模型（或回退模型）时才可用。如果未显式配置图像模型，OpenClaw 会尝试从默认模型和已配置的认证信息中推断合适的图像模型。

image 的使用场景：

1. Agent 收到用户发送的截图："帮我分析这张错误截图"
   → image(image="screenshot.png", prompt="分析这张截图中的错误信息")

2. Agent 需要理解图表内容："这张图表展示了什么趋势？"
   → image(image="chart.png", prompt="描述这张图表的数据趋势")

3. Agent 需要识别图片中的文字："帮我把这张图片中的文字提取出来"
   → image(image="document.jpg", prompt="提取图片中的所有文字")

3.15 PDF 分析工具 pdf

pdf 工具用于分析 PDF 文档内容。它支持多页 PDF、文本提取和结构化信息检索 1。

pdf 的核心参数：

参数	类型	必需	说明
path	string	是	PDF 文件路径或 URL
query	string	否	针对 PDF 内容的具体查询。如果不提供，返回全文摘要
pages	string	否	指定分析的页码范围。如 "1-5"、"3,5,7"
maxChars	number	否	最大返回字符数

pdf 的工作机制：PDF 工具首先将 PDF 内容提取为文本（使用 OCR 处理扫描件中的图片文字），然后将文本分块发送给 AI 模型进行分析。对于大型 PDF 文档，它支持分页查询------只分析你关心的页面。

pdf 的使用场景：

1. "帮我总结这份 PDF 报告的核心结论"
   → pdf(path="report.pdf")

2. "这份合同的第 3-5 页关于违约条款的内容是什么？"
   → pdf(path="contract.pdf", pages="3-5", query="违约条款")

3. "这份技术白皮书中关于性能优化的部分在哪里？"
   → pdf(path="whitepaper.pdf", query="性能优化")

3.16 Canvas 画布工具 canvas

canvas 工具用于操控 OpenClaw 的节点 Canvas------一个可以展示内容、执行代码、生成截图的交互式界面 1。

canvas 的核心操作：

操作	说明
present	在 Canvas 上展示内容（HTML/Markdown/文本）
hide	隐藏当前 Canvas 内容
navigate	导航到指定 URL
eval	在 Canvas 上下文中执行 JavaScript 代码
snapshot	截取 Canvas 当前画面，返回图片和路径
a2ui_push	推送 A2UI（v0.8）界面组件
a2ui_reset	重置 A2UI 界面

canvas 的典型使用场景：

1. Agent 生成数据可视化后，在 Canvas 上展示
   → canvas.present(content="<html>...chart...</html>")

2. 截取 Canvas 截图发送给用户
   → canvas.snapshot() → 返回 MEDIA:<path>
   → message.send(media="canvas_screenshot.png")

3. 在 Canvas 上执行交互式代码
   → canvas.eval(code="document.querySelector('#result').textContent")

canvas 的底层实现 ：canvas 工具通过 Gateway 的 node.invoke 机制与节点通信。如果未指定节点，会自动选择默认节点（单个已连接节点或本地 macOS 节点）。

3.17 节点管理工具 nodes

nodes 工具用于发现和管理 OpenClaw 的节点（Node）------分布在不同设备上的 Agent 执行端点 1。

nodes 的核心操作：

操作	说明
status	查看所有节点的状态
describe	查看指定节点的详细信息
pending	列出待审批的节点配对请求
approve / reject	批准/拒绝节点配对
notify	向节点发送 macOS 系统通知
run	在节点上执行命令（macOS system.run）
camera_list / camera_snap / camera_clip	节点摄像头操作
screen_record	节点屏幕录制
location_get	获取节点地理位置
device_status / device_info / device_permissions / device_health	设备信息查询

nodes 的使用场景：

1. 查看所有已连接的设备
   → nodes.status()

2. 在远程 macOS 节点上执行命令
   → nodes.run(node="office-mac", command=["open", "-a", "Calculator"])

3. 使用远程节点的摄像头拍照
   → nodes.camera_snap(node="office-mac") → 返回 MEDIA:<path>

4. 向远程节点发送通知
   → nodes.notify(node="office-mac", title="提醒", body="会议即将开始")

nodes 的安全机制：所有节点操作都需要配对（Pairing）------节点必须先被批准连接，才能被 Agent 操控。这确保了只有经过授权的设备才能被 Agent 访问。

3.18 消息工具 message

message 工具是 OpenClaw 中功能最全面的跨渠道通信工具。它让 Agent 可以在 Discord、Google Chat、Slack、Telegram、WhatsApp、Signal、iMessage、MS Teams 等渠道上发送消息、创建投票、管理表情回应、管理频道 1。

message 的核心操作：

类别	操作	说明
消息	send	发送文本消息（可选附件）。MS Teams 还支持 card 类型的 Adaptive Cards
消息	read	读取消息内容
消息	edit	编辑已发送的消息
消息	delete	删除消息
消息	pin / unpin / list-pins	置顶/取消置顶/列出置顶消息
消息	search	搜索消息
消息	permissions	查看频道权限
投票	poll	创建投票（WhatsApp/Discord/MS Teams）
回应	react	添加表情回应
回应	reactions	查看消息的表情回应
主题	thread-create	创建主题帖
主题	thread-list	列出主题帖
主题	thread-reply	回复主题帖
频道	channel-info	查看频道信息
频道	channel-list	列出频道
成员	member-info	查看成员信息
成员	role-info / role-add / role-remove	角色管理
成员	timeout / kick / ban	成员管理
表情	emoji-list / emoji-upload	表情管理
贴纸	sticker-send / sticker-upload	贴纸管理
语音	voice-status	语音状态
事件	event-list / event-create	事件管理

message 的安全约束 ：当 message 工具调用绑定到活跃的聊天会话时，发送操作被限制在该会话的目标范围内，防止跨会话的消息泄露。

message.send 的核心参数：

参数	类型	必需	说明
target	string	是	发送目标。格式为 channel:recipient
message	string	是	消息内容
media	string	否	附件路径（图片、文件）
replyTo	string	否	回复的消息 ID

message 的渠道路由 ：message.send 通过 Gateway 路由 WhatsApp 消息，其他渠道直接发送。投票（poll）通过 Gateway 处理 WhatsApp 和 MS Teams，Discord 投票直接发送。

3.19 记忆工具 memory_search / memory_get

记忆工具让 Agent 拥有跨会话的"记忆力"。Agent 在对话过程中可以主动将重要信息存储到记忆库中，后续对话中可以通过 memory_search 和 memory_get 检索这些信息 1。

memory_search ------ 搜索记忆

{
    "tool": "memory_search",
    "query": "用户的API Key偏好",
    "limit": 5
}

参数	说明
query	搜索查询。支持自然语言查询和关键词
limit	返回结果数量上限

memory_get ------ 获取特定记忆

{
    "tool": "memory_get",
    "memoryId": "mem_abc123"
}

获取指定 ID 的记忆条目的完整内容。

记忆系统的使用场景：

对话 1:
用户: "我的项目部署在 AWS us-east-1 区域，使用 Ubuntu 22.04"
Agent: [自动存储：用户部署环境 = AWS us-east-1 + Ubuntu 22.04]

对话 2 (一周后):
用户: "帮我检查一下部署状态"
Agent: [调用 memory_search("部署") → 找到之前的记忆]
Agent: "你的项目部署在 AWS us-east-1，使用 Ubuntu 22.04。需要我 SSH 进去检查吗？"

---

四、飞书渠道配置完整指南

飞书是国内企业广泛使用的协作平台。将 OpenClaw 接入飞书后，团队成员可以在飞书群里 @机器人 直接使用 AI 助手，不需要安装任何额外的应用。

4.1 飞书开放平台创建应用

第一步：创建企业自建应用

1. 访问飞书开放平台（open.feishu.cn），使用企业管理员账号登录
2. 点击"创建企业自建应用"，填写应用名称（如"OpenClaw 助手"）和应用描述
3. 进入应用详情页，在"凭证与基础信息"中获取 App ID 和 App Secret
   

这两个凭证是后续配置的关键信息，App ID 用于标识应用身份，App Secret 用于验证请求的合法性。将它们妥善保存，不要提交到公开的代码仓库中。

第二步：启用机器人能力

1. 在左侧目录树选择"添加应用能力"，单击"机器人"能力卡片的"添加"按钮
2. 在左侧目录树选择"权限管理"，单击"批量导入/导出权限"按钮
3. 在"导入"页签中，替换原有示例权限，至少需要以下权限：
   

权限	说明
im:message	获取消息内容
im:message:send	发送消息
im:user	获取用户信息
im:message:reaction	消息 reaction 事件

4. 单击"下一步，确认新增权限" → "申请开通" → "确定"

第三步：创建版本并发布

1. 单击顶部的"创建版本"按钮

2. 配置应用版本号、默认能力及更新说明

3. 单击页面底部的"保存"按钮

4. 单击页面右上角的"确认发布"按钮

   

   

应用发布后，组织内的成员才能搜索到并使用这个机器人。如果应用未发布，只有应用管理员可以测试。

4.2 安装飞书插件

飞书插件是 OpenClaw 与飞书之间的桥梁，它负责处理消息的接收、格式转换和发送。

安装命令：

npx -y @larksuite/openclaw-lark install

这个命令会执行以下操作：

1. 下载飞书插件包（@larksuite/openclaw-lark）
2. 安装依赖
3. 在 OpenClaw 中注册插件
4. 启动交互式配置向导

配置凭证：安装过程中，会提示配置机器人。在 Windows 终端中可能无法扫描二维码，等待超时后，手动输入在飞书开放平台创建的应用凭证：

• App ID（应用的唯一标识）
• App Secret（应用的密钥）
  

输入完成后，等待 OpenClaw 重启。重启成功后，飞书插件即处于激活状态。

4.3 配置事件与回调

第一步：配置事件订阅

1. 在飞书开放平台的应用详情页，选择"事件与回调"
2. 单击"订阅方式"旁的编辑按钮
3. 选择"使用长连接接收事件 "，并单击"保存"
   

为什么选择长连接（WebSocket）？ 传统的 Webhook 方式需要应用有一个公网 IP 地址，飞书服务器才能把事件推送过来。而长连接模式是由 OpenClaw 主动连接到飞书服务器建立 WebSocket 连接，消息通过这个长连接双向传输。这意味着 OpenClaw 可以部署在没有公网 IP 的内网环境中------只需要能访问飞书服务器即可。这是飞书渠道在实际部署中最受好评的特性。

4. 在"已添加事件"区域，单击"添加事件"按钮
5. 选择"应用身份订阅"页签，搜索"消息"并勾选 im.message.receive_v1 事件
6. 如果需要使用 reaction 功能，同时勾选"消息被 reaction"和"消息被取消 reaction"事件
7. 单击"确认添加"
   

群聊场景的注意事项 ：如果期望将机器人添加到聊天群组中使用，需要额外开通获取群组消息的权限。由于 OpenClaw 是个人 AI 助手，在群聊场景下可能存在凭证泄露等风险，请谨慎评估后再启用。

第二步：配置回调

1. 选择"回调配置"页签，单击"订阅方式"旁的编辑按钮

2. 选择"使用长连接接收回调 "，并单击"保存"

3. 在添加回调对话框中，选择"卡片"页签，勾选"卡片回传交互"

4. 单击"确认添加"

第三步：发布新版本

事件和回调配置修改后，需要创建新版本并重新发布应用才能生效。步骤与 4.1 中的"创建版本并发布"一致。

4.4 配对与授权

配对（Pairing）是 OpenClaw 的安全机制，确保只有被授权的用户才能与 Agent 对话。

配对步骤：

1. 向飞书机器人发送任意消息

2. 机器人会返回一个 Pairing Code（5 分钟内有效）

3. 打开终端，输入配对命令：

openclaw pairing approve feishu <Pairing Code> --notify

4. 回到飞书机器人聊天框，根据提示完成授权

pairing approve 命令详解：

参数	说明
feishu	渠道名称。指定要对哪个渠道的配对请求进行审批
<Pairing Code>	机器人返回的配对码。5 分钟内有效，过期需要重新获取
--notify	审批完成后通知对方（通过飞书消息）

如果暂时不想授权，也可以直接与飞书机器人开始对话。需要授权时，在飞书机器人对话框中输入 /feishu auth 发起批量授权。

4.5 测试与使用

配对完成后，就可以在飞书中与 AI 助手对话了。以下是一些测试建议：

基础测试：发送"你好"，确认机器人能正常回复。

渠道能力测试：为了让 OpenClaw 了解飞书插件的新能力，建议发送：

学习一下我安装的新飞书插件，列出有哪些能力

Agent 会读取飞书插件的 SKILL.md 文件，了解它可以使用的飞书特有功能（如创建会议、发送审批卡片、查询日历等），并在后续对话中利用这些能力。

功能测试：

帮忙创建会议
帮我查一下飞书日历中明天的安排

这些指令会触发飞书插件特有的能力，验证插件是否完整安装并正确配置。

---

五、钉钉渠道配置完整指南

钉钉是另一款国内广泛使用的企业办公平台。OpenClaw 提供了两种钉钉接入方案：官方插件（@dingtalk-real-ai/dingtalk-connector）和社区插件（@soimy/dingtalk）。官方插件由钉钉团队维护，功能更完善；社区插件更轻量，配置更灵活。

5.1 一键创建 OpenClaw 机器人

前提条件：选择一个有开发者权限的钉钉组织，或者注册账号并创建企业/团队。

创建步骤 7：

1. 登录钉钉开发者后台（open.dingtalk.com）

2. 在"应用开发"下，点击"立即创建"，选择一键创建 OpenClaw 机器人

3. 填写机器人基本信息（名称、简介、图标），也可使用默认信息，直接点击"确定"

4. 创建成功后，系统自动展示应用的 Client ID 和 Client Secret

重要提醒 ：Client ID 和 Client Secret 是应用的关键凭证，也是操作应用数据的核心参数。请妥善保管，不要轻易提供给他人，不要提交到公开的代码仓库。如果这些凭证泄露，攻击者可以冒充你的机器人收发消息。

创建成功后，在应用的"凭证与基础信息"页面也可以随时查看 Client ID 和 Client Secret。

5.2 官方插件配置

官方插件 @dingtalk-real-ai/dingtalk-connector 由钉钉官方团队维护，推荐优先使用。

第一步：安装插件

openclaw plugins install @dingtalk-real-ai/dingtalk-connector

安装过程包括：下载插件包、安装依赖、在 OpenClaw 中注册插件。安装时间可能较长，请耐心等待日志不再滚动。

第二步：配置 openclaw.json

打开 ~/.openclaw/openclaw.json，在 channels 节点中添加钉钉配置：

{
    "channels": {
        "dingtalk-connector": {
            "clientId": "钉钉应用的Client ID",
            "clientSecret": "钉钉应用的Client Secret",
            "gatewayToken": "Gateway 认证 token",
            "sessionTimeout": 1800000
        }
    },
    "gateway": {
        "auth": {
            "mode": "token",
            "token": "Gateway 认证 token"
        },
        "http": {
            "endpoints": {
                "chatCompletions": {
                    "enabled": true
                }
            }
        }
    }
}

字段	类型	必需	说明
clientId	string	是	钉钉应用的 Client ID（AppKey），格式如 dinge9fjs5bijaq65z3m
clientSecret	string	是	钉钉应用的 Client Secret（AppSecret）
gatewayToken	string	是	Gateway 认证 token。必须与 gateway.auth.token 的值一致
gatewayPassword	string	否	Gateway 认证密码（与 token 二选一）
sessionTimeout	number	否	会话超时时间（毫秒），默认 1800000（30 分钟）

重要提示 ：gateway.http.endpoints.chatCompletions.enabled 必须设为 true，这是钉钉机器人接收消息所必需的 HTTP 端点。

第三步：重启 Gateway

openclaw gateway restart

第四步：验证

openclaw plugins list

确认 dingtalk-connector 在列表中且状态为已加载。

第五步：发送测试消息

在钉钉中找到机器人，发送一条消息，确认能收到回复。

5.3 社区插件配置

社区插件 @soimy/dingtalk 是一个轻量级的替代方案，配置更简洁。

第一步：安装插件

openclaw plugins install @soimy/dingtalk

第二步：配置 openclaw.json

在 channels 节点中添加：

{
    "channels": {
        "dingtalk": {
            "enabled": true,
            "clientId": "你的钉钉Client ID",
            "clientSecret": "你的钉钉Client Secret",
            "robotCode": "你的钉钉Client ID",
            "dmPolicy": "open",
            "groupPolicy": "open"
        }
    }
}

同时需要添加 plugins 配置：

{
    "plugins": {
        "allow": ["dingtalk"],
        "entries": {
            "dingtalk": {
                "enabled": true
            }
        }
    }
}

字段	说明
dmPolicy	私聊策略。open（开放）、pairing（配对）、allow（白名单）
groupPolicy	群聊策略。open（开放）、pairing（配对）、allow（白名单）
robotCode	机器人标识。通常与 Client ID 相同

第三步：重启并验证

openclaw gateway restart
openclaw plugins list

5.4 插件卸载与清理

如果需要卸载钉钉插件，可以执行卸载命令，或者手动清理残留文件。

方法一：卸载命令

openclaw plugins uninstall @dingtalk-real-ai/dingtalk-connector

方法二：手动清理

如果命令卸载不彻底，可以手动删除：

1. 删除安装目录：~/.openclaw/extensions/dingtalk-connector
2. 编辑 ~/.openclaw/openclaw.json，删除以下三处与 dingtalk-connector 相关的配置：
   • channels 节点：删除 "dingtalk-connector": { ... } 对象
   • plugins.entries 节点：删除 "dingtalk-connector": { "enabled": true }
   • plugins.allow 数组：删除 "dingtalk-connector" 项

手动清理后需要重启 Gateway 使变更生效。

---

六、其他渠道配置详解

6.1 Telegram 接入

Telegram 是 OpenClaw 支持最完善的渠道之一，也是个人用户最常使用的接入方式。它的接入流程极其简单------只需要在 Telegram 中创建一个 Bot，获取 Token，然后填入配置即可。不需要公网 IP、不需要配置 Webhook、不需要在开放平台申请 API 权限。

第一步：创建 Telegram Bot

1. 在 Telegram 中搜索 @BotFather，点击开始对话
2. 发送 /newbot 命令
3. 按提示输入 Bot 的名称（显示名称，如 "我的 AI 助手"）
4. 按提示输入 Bot 的用户名（必须以 bot 结尾，如 my_ai_assistant_bot）
5. BotFather 返回 Bot Token，格式如 123456789:ABCdefGHIjklMNOpqrsTUVwxyz

第二步：获取用户 ID

为了配置白名单（限制只有特定用户能使用 Bot），需要获取你的 Telegram 数字 ID：

1. 搜索 @userinfobot，发送任意消息
2. 它会返回你的数字 User ID，如 987654321

第三步：配置 openclaw.json

{
    "channels": {
        "telegram": {
            "enabled": true,
            "botToken": "${TELEGRAM_BOT_TOKEN}",
            "dmPolicy": "allow",
            "allowFrom": ["987654321"]
        }
    }
}

字段	说明
botToken	BotFather 返回的 Token。强烈建议使用环境变量 ${TELEGRAM_BOT_TOKEN} 而非明文
dmPolicy	私聊策略。open（开放）、allow（白名单）、pairing（配对）
allowFrom	白名单用户 ID 列表。仅 dmPolicy: "allow" 时生效

第四步：重启并配对

openclaw gateway restart

在 Telegram 中搜索你的 Bot 用户名，发送 /start。然后根据 dmPolicy 的设置，可能需要完成配对。

Telegram 渠道的技术细节 ：Telegram Bot API 使用 HTTP Long Polling 机制接收消息------OpenClaw 定期向 Telegram 服务器发起 HTTP 请求，检查是否有新消息。这种方式不需要公网 IP，也不需要配置 Webhook，开箱即用。Telegram 渠道几乎支持所有消息类型：文本、图片、文件、语音、视频、贴纸。在群聊中，Bot 默认只响应 @提及它的消息和 / 开头的命令。

6.2 Discord 接入

Discord 渠道的接入同样简单，适合社区和团队协作场景。

第一步：创建 Discord 应用

1. 访问 Discord Developer Portal（discord.com/developers/applications）
2. 点击 "New Application"，填写名称
3. 在左侧菜单中选择 "Bot"，点击 "Add Bot"
4. 在 Bot 页面获取 Token，点击 "Reset Token" 生成新的 Token
5. 开启必要的 Privileged Gateway Intents：MESSAGE CONTENT INTENT（读取消息内容）、SERVER MEMBERS INTENT（获取服务器成员）、PRESENCE INTENT（在线状态）

第二步：邀请 Bot 到服务器

1. 在左侧菜单中选择 "OAuth2" → "URL Generator"
2. 在 Scopes 中选择 bot
3. 在 Bot Permissions 中选择：Send Messages、Read Message History、Attach Files、Add Reactions、Use Slash Commands
4. 复制生成的 URL，在浏览器中打开，选择目标服务器，完成授权

第三步：配置 openclaw.json

{
    "channels": {
        "discord": {
            "enabled": true,
            "botToken": "${DISCORD_BOT_TOKEN}",
            "dmPolicy": "open"
        }
    }
}

第四步：重启并验证

openclaw gateway restart

在 Discord 服务器中，@机器人发送消息，确认能收到回复。

Discord 渠道的技术细节：Discord 使用 WebSocket 连接进行实时通信，延迟极低（通常 < 100ms）。Bot 在频道中默认只响应 @提及它的消息。Discord 渠道支持文本频道、私信、线程回复、表情回应、投票和角色管理。

6.3 Slack 接入

Slack 是企业协作场景的主流选择，OpenClaw 的 Slack 集成功能完善。

第一步：创建 Slack App

1. 访问 api.slack.com/apps，点击 "Create New App"，选择 "From scratch"
2. 填写 App 名称，选择目标工作空间
3. 在左侧菜单中选择 "Socket Mode"，启用 Socket Mode（这样不需要公网 Webhook URL）
4. 记录生成的 App Token（以 xapp- 开头）

第二步：配置权限

1. 在左侧菜单中选择 "OAuth & Permissions"
2. 在 Bot Token Scopes 中添加以下权限：
   • chat:write（发送消息）
   • chat:read（读取消息）
   • app_mentions:read（读取 @提及）
   • channels:history（频道历史）
   • groups:history（私密频道历史）
   • reactions:read（读取表情回应）
3. 点击 "Install to Workspace" 安装应用
4. 记录生成的 Bot User OAuth Token（以 xoxb- 开头）

第三步：配置 openclaw.json

{
    "channels": {
        "slack": {
            "enabled": true,
            "botToken": "${SLACK_BOT_TOKEN}",
            "appToken": "${SLACK_APP_TOKEN}",
            "dmPolicy": "open"
        }
    }
}

字段	说明
botToken	Bot User OAuth Token（xoxb- 开头）
appToken	App Token（xapp- 开头）

Slack 渠道的技术细节：Slack 渠道使用 Socket Mode（WebSocket 连接），不需要配置公网 HTTP 端点。Bot 在频道中只响应 @提及它的消息。Slack 渠道支持富文本消息（使用 Slack Block Kit 格式）、文件上传和线程回复。

6.4 企业微信接入

企业微信是国内广泛使用的企业通讯工具，OpenClaw 通过插件支持企业微信渠道。

接入方式：使用企业微信的"长连接智能机器人"能力，配合 OpenClaw 插件实现消息收发。具体步骤：

1. 在企业微信管理后台创建应用
2. 获取 Corp ID、Agent ID 和 Secret
3. 安装 OpenClaw 企业微信插件
4. 配置 openclaw.json 中的企业微信渠道节点
5. 重启 Gateway 并完成配对

参考文档：企业微信 OpenClaw 插件

6.5 QQ 接入

QQ 渠道通过 QClaw 集成或直接使用 QQ 开放平台的机器人能力。

接入方式一（QClaw）：安装 QClaw 桌面应用，在图形界面中完成 QQ Bot 的创建和绑定，支持最多 5 个 QQ Bot。

接入方式二（QQ 开放平台） ：在 QQ 开放平台注册机器人，获取 App ID 和 Token，配置到 openclaw.json 中。

参考文档：QQ 开放平台机器人

6.6 渠道接入对比总结

渠道	连接方式	是否需要公网 IP	接入难度	功能完整度	最适合场景
Telegram	HTTP Long Polling	否	极低	极高	个人使用、技术社群
Discord	WebSocket	否	极低	极高	社区运营、游戏社群
飞书	WebSocket 长连接	否	中等	极高	国内企业协作
钉钉	Stream 模式	否	中等	高	国内企业协作
Slack	Socket Mode (WebSocket)	否	中等	高	国际企业协作
企业微信	长连接	否	中等	中	国内企业协作
WhatsApp	Baileys (WebSocket)	否	中等	中	个人手机使用
iMessage	AppleScript (macOS 桥接)	否	高	中	Apple 生态深度用户
QQ	QClaw 或开放平台	否	低-中	中	国内个人用户

每个渠道的接入都可以通过 openclaw channels add 命令启动引导式配置，或者直接编辑 openclaw.json 手动添加渠道配置。建议从最简单的渠道（Telegram）开始，熟悉流程后再接入更复杂的平台。

---

七、渠道配置故障排查指南

7.1 飞书渠道常见问题

问题 1：机器人不回复消息

这是飞书渠道配置中最常见的问题。排查步骤：

1. 检查应用是否已发布。在飞书开放平台中，进入应用详情页，确认右上角显示"已发布"状态。如果应用未发布，只有应用管理员可以测试
2. 检查事件订阅。确认"事件与回调"中选择了"使用长连接接收事件"，并已添加 im.message.receive_v1 事件
3. 检查 Gateway 日志：

openclaw logs

查找包含 "feishu" 或 "lark" 关键词的日志行，看看是否有连接错误或认证失败的信息

4. 检查插件是否正常加载：

openclaw plugins list

确认 @larksuite/openclaw-lark 在列表中且状态为"已加载"

问题 2：配对码过期

配对码只有 5 分钟有效期。如果过期了，在飞书对话框中重新发送任意消息，机器人会返回新的配对码。然后立即执行配对命令。

问题 3：长连接中断

长连接（WebSocket）偶尔会因为网络波动而中断。OpenClaw 会自动重连，但如果重连失败，可以尝试：

openclaw gateway restart

7.2 钉钉渠道常见问题

问题 1：插件安装失败

# 安装时间可能较长，请耐心等待
openclaw plugins install @dingtalk-real-ai/dingtalk-connector

# 如果失败，可以尝试使用 sudo（Linux/macOS）
sudo openclaw plugins install @dingtalk-real-ai/dingtalk-connector

# Windows 使用管理员身份运行终端

问题 2：配置后机器人不响应

确认 gateway.http.endpoints.chatCompletions.enabled 设置为 true。这是钉钉机器人接收消息所必需的 HTTP 端点，如果未启用，钉钉服务器无法将消息推送到 OpenClaw。

问题 3：Client ID 和 Client Secret 不匹配

在钉钉开放平台中，确认使用的 Client ID 和 Client Secret 与应用详情页显示的一致。特别注意：钉钉有多个环境（正式环境、测试环境），确保使用的是正确的环境凭证。

---

八、安全实践与操作建议

8.1 exec 工具的安全边界

exec 工具是 OpenClaw 中最强大的工具，也是最危险的工具。它允许 Agent 执行任意系统命令，相当于将系统控制权交给了 AI。以下是在使用 exec 时必须遵守的安全准则：

环境隔离：

• 在隔离环境中运行 OpenClaw（虚拟机、Docker 容器、WSL2），避免直接影响宿主机重要数据
• 绝对不要在生产服务器或个人主力机上不加限制地运行 OpenClaw 的 exec 工具
• 使用 Docker 部署时，限制容器的文件系统访问、网络访问和系统调用

权限最小化：

• 不要在 OpenClaw 中配置具有过高权限的 API Key 或系统账户
• 使用 tools.profile 限制工具集，只在必要时才启用 exec 和 process
• 为不同用途的 Agent 配置不同的工具权限------比如"客服 Agent"只需要 messaging profile，"开发 Agent"可以使用 coding profile

审批机制：

• 配置 exec 的 ask 参数为 always 或 on-miss，确保高风险操作需要人工确认
• 使用 approvals 命令管理审批规则：

openclaw approvals set exec.ask always
openclaw approvals allowlist add "ls -la"

监控与审计：

• 定期使用 openclaw doctor 检查配置安全状态
• 使用 openclaw logs 查看 Agent 的操作日志，关注异常的命令执行
• 关注 OpenClaw 官方的安全公告，在安全补丁发布后及时更新

8.2 沙箱隔离

OpenClaw 支持沙箱模式，将 Agent 的执行环境与宿主机隔离开来。当沙箱启用时，exec 命令被包装在 docker exec 中执行，Agent 只能访问沙箱内的文件系统，无法触及宿主机系统。

启用沙箱：

openclaw sandbox recreate

配置沙箱策略：

{
    "sandbox": {
        "enabled": true,
        "image": "openclaw/sandbox:latest",
        "workspace": "/workspace"
    }
}

8.3 日常操作建议

配置变更后务必重启 ：修改 openclaw.json 后，执行 openclaw gateway restart 使变更生效。之后运行 openclaw doctor 确认一切正常。

定期备份配置：

# 备份到指定目录
openclaw backup

# 或手动备份
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d)

保持版本更新：

# 检查当前版本
openclaw --version

# 更新到最新版
openclaw update

# 更新后检查兼容性
openclaw doctor

监控资源使用：

# 查看系统状态
openclaw status

# 查看 Gateway 运行状态
openclaw gateway status

# 查看最近的日志
openclaw logs

8.4 渠道配置检查清单

在完成渠道配置后，按以下清单逐项检查：

• 应用已创建并获取了 App ID 和 App Secret（或 Client ID 和 Client Secret）
• 机器人能力已启用
• 权限已正确配置（至少包含消息收发权限）
• 事件订阅已配置（长连接模式）
• 回调已配置
• 应用已发布
• 插件已安装并注册
• openclaw.json 中的渠道配置正确
• Gateway 已重启
• 插件状态为已加载
• 配对已完成
• 测试消息能正常收发

---

附录 A：常用命令速查表

网关操作

命令	说明
openclaw gateway	启动 Gateway 服务
openclaw gateway stop	停止 Gateway 服务
openclaw gateway restart	重启 Gateway 服务
openclaw gateway status	查看 Gateway 运行状态
openclaw gateway install	安装为系统服务
openclaw gateway uninstall	卸载系统服务

用户界面

命令	说明
openclaw tui	启动终端用户界面
openclaw dashboard	启动 Web 控制台

配置管理

命令	说明
openclaw onboard	运行初始配置向导
openclaw configure	修改已有配置
openclaw config get	查看当前完整配置
openclaw config set <k> <v>	修改特定配置项
openclaw config unset <k>	删除配置项
openclaw doctor	系统诊断
openclaw doctor --repair	诊断并自动修复

Skills 管理

命令	说明
openclaw skills list	列出已安装 Skills
openclaw skills install <n>	安装 Skill
openclaw skills uninstall <n>	卸载 Skill
openclaw skills enable <n>	启用 Skill
openclaw skills disable <n>	禁用 Skill
openclaw skills search <k>	搜索 Skill
openclaw skills check <n>	检查 Skill 状态
openclaw skills update	更新所有 Skills

插件管理

命令	说明
openclaw plugins list	列出已安装插件
openclaw plugins install <n>	安装插件
openclaw plugins uninstall <n>	卸载插件
openclaw plugins update	更新插件

模型管理

命令	说明
openclaw models list	列出可用模型
openclaw models status	查看模型状态
openclaw models set <m>	切换默认模型

系统维护

命令	说明
openclaw --version	查看版本号
openclaw update	更新到最新版本
openclaw backup	备份配置和数据
openclaw uninstall	卸载 OpenClaw
openclaw logs	查看日志
openclaw status	查看系统状态

渠道管理

命令	说明
openclaw channels list	列出已配置渠道
openclaw channels add	添加渠道（引导式）
openclaw pairing approve <c> <code>	批准渠道配对
openclaw pairing list	查看待审批配对

---

附录 B：工具分组速查

分组名	包含的工具	说明
group:runtime	exec, bash, process	运行时执行工具
group:fs	read, write, edit, apply_patch	文件系统操作工具
group:sessions	sessions_list, sessions_history, sessions_send, sessions_spawn, session_status	会话管理工具
group:memory	memory_search, memory_get	记忆管理工具
group:web	web_search, web_fetch	网络工具
group:ui	browser, canvas	用户界面交互工具
group:automation	cron, gateway	自动化调度工具
group:messaging	message	消息发送工具
group:nodes	nodes	节点管理工具
group:openclaw	所有内置 OpenClaw 工具	完整工具集

---

Sources

1. OpenClaw Built-in Tools Documentation --- OpenClaw 内置工具完整参考文档
2. OpenClaw Exec Tool Reference --- exec 工具参数和行为详解
3. OpenClaw Web Search Guide --- web_search 和 web_fetch 工具使用指南
4. OpenClaw Web Tools --- 网络工具配置详解
5. OpenClaw Built-in Tools Overview --- 内置工具体系概览
6. OpenClaw Sandbox Security --- 沙箱安全机制详解
7. OpenClaw DingTalk Channel --- 钉钉渠道官方配置文档
8. OpenClaw CLI Reference --- CLI 命令完整参考
9. OpenClaw Cheat Sheet 2026 --- 命令速查表
10. OpenClaw Feishu Channel --- 飞书渠道官方配置文档
11. OpenClaw 钉钉集成指南 --- 阿里云部署 OpenClaw 集成钉钉
12. OpenClaw Config Reference --- openclaw.json 字段参考