OpenClaw 使用指南

材料与逻辑，从原子到结构，从数据到洞察关注

使用OpenClaw来生成的OpenClaw使用文档，文档写的挺专业，配置OpenClaw时查找命令非常不错。

OpenClaw 是一个开源、自托管的 AI 网关，将多种聊天应用（WhatsApp、Telegram、Discord、iMessage 等）与 AI 助手连接起来。运行在你自己选择的机器上，数据完全由你掌控。

1. 核心概念

Gateway（网关）

OpenClaw 的核心是一个长时间运行的 Gateway 进程，它：

管理所有聊天渠道的连接（WhatsApp、Telegram、Discord 等）
处理与 AI Agent 的通信
提供 WebSocket API 给控制面板、CLI、移动端节点使用
默认监听 http://127.0.0.1:18789

Agent

Agent 是 AI 对话的实际执行者。每个 Agent 有：

独立的 workspace — 文件系统上的工作目录
独立的会话 — 对话历史和上下文
独立的工具策略 — 允许使用哪些工具
独立的身份和绑定 — 绑定到特定的渠道或账号

Session（会话）

会话决定了同一对话中的消息如何被关联：

模式	行为
`main`	所有 DM 共享一个主会话
`per-peer`	每个发送者一个会话
`per-channel-peer`	每个渠道+发送者组合一个会话
`per-account-channel-peer`	每个账号+渠道+发送者一个会话

Channel（渠道）

渠道是 OpenClaw 连接的具体聊天平台。内置支持：

WhatsApp — 通过 Baileys 库，需要 QR 码配对
Telegram — 通过 Bot API，最快配置
Discord — 机器人账号
iMessage — 通过 BlueBubbles（macOS）

插件渠道：

Mattermost、Slack、Microsoft Teams、Signal、Matrix 等

DM 安全策略

每个渠道独立控制谁可以发送 DM：

pairing（默认）：未知发送者获得一次性配对码，需管理员审批
allowlist：仅 allowFrom 列表中的用户可以 DM
open：允许所有人 DM（需要 allowFrom: ["*"]）
disabled：禁用所有 DM

配置存储

OpenClaw 的配置文件位于 ~/.openclaw/openclaw.json（JSON5 格式，支持注释）。

2. 安装

环境要求

Node.js：Node 24（推荐）或 Node 22.14+
操作系统：macOS、Linux、Windows (WSL2 推荐)
API Key：来自模型提供商（Anthropic、OpenAI、Google 等）

安装命令

macOS / Linux：

Windows (PowerShell)：

其他方式（npm）：

验证安装：

3. 快速开始

步骤 1：引导式初始化

向导会依次询问：

模型/认证 — 选择提供商并输入 API Key
工作空间 — Agent 文件存储位置（默认 ~/.openclaw/workspace）
网关 — 端口、绑定地址、认证方式
渠道 — 配置 WhatsApp/Telegram/Discord 等
守护进程 — 安装系统服务使网关后台运行
健康检查 — 验证网关是否正常运行
技能 — 安装推荐的 Skills

步骤 2：验证网关运行

步骤 3：打开控制面板

浏览器访问 http://127.0.0.1:18789/ ，输入网关令牌登录。

步骤 4：发送第一条消息

在控制面板中直接发送消息，或配置 Telegram 以手机聊天：

4. 配置

配置文件位置

~/.openclaw/openclaw.json（JSON5 格式）

配置方式

方式一：交互式向导

方式二：CLI 单行命令

方式三：直接编辑

网关会自动监视文件并热重载大部分配置（无需重启）。

方式四：控制面板
打开 http://127.0.0.1:18789/ → Config tab，以表单或原始 JSON 编辑。

热重载规则

分类	字段	是否需要重启
渠道	`channels.*`	❌ 无需
Agent & 模型	`agents.`, `models.`	❌ 无需
自动化	`hooks`, `cron`, `heartbeat`	❌ 无需
会话 & 消息	`session`, `messages`	❌ 无需
网关服务	`gateway.*`（端口、绑定、TLS）	✅ 需要

常用配置示例

最小配置（仅 WhatsApp）：

多渠道配置：

多模型配置：

5. 渠道（Channels）

支持的渠道

渠道	类型	配置难度	说明
Telegram	内置	⭐ 最简单	只需 Bot Token
WhatsApp	内置	⭐⭐	需要 QR 码配对
Discord	内置	⭐⭐	需要机器人账号
iMessage	内置	⭐⭐⭐	通过 BlueBubbles（macOS）
Signal	内置	⭐⭐⭐	通过 signal-cli
Slack	插件	⭐⭐	Bolt SDK
Microsoft Teams	插件	⭐⭐⭐	Bot Framework
Mattermost	插件	⭐⭐	WebSocket 支持
Matrix	插件	⭐⭐	协议支持
Google Chat	内置	⭐⭐	HTTP Webhook

Telegram 快速配置

WhatsApp 配置

Discord 配置

群组配置

群组消息默认需要 @提及才响应。配置：

6. CLI 命令参考

核心命令

渠道管理

Agent 管理

会话 & 消息

Skills（技能）

配对 & 设备

浏览器控制

其他

7. Web 控制面板

控制面板是浏览器中的管理界面，默认地址：

功能

Chat — 直接发送消息给 Agent
Sessions — 查看和管理对话会话
Config — 可视化配置编辑器
Nodes — 管理配对的移动节点
Logs — 实时日志查看

首次连接

打开 http://127.0.0.1:18789/
输入 Gateway Token（在初始化时生成，保存在 ~/.openclaw/openclaw.json 的 gateway.auth.token 字段）
首次在新设备连接时需要配对审批：

远程访问

方式一：Tailscale

方式二：SSH 隧道

8. 多 Agent 与路由

为什么要多 Agent？

为不同场景隔离工作空间（工作/个人）
不同渠道绑定不同 Agent
不同 Agent 使用不同模型或工具策略

添加新 Agent

配置路由绑定

指令中切换 Agent

在支持 slash 命令的渠道（如 Discord）：

/focus — 进入专注会话
/unfocus — 退出专注会话
/agents — 列出可用 Agent
/session idle — 空闲会话超时设置

9. 自动化与定时任务

Cron 定时任务

Heartbeat（心跳）

定期让 Agent 执行检查任务：

Webhooks / Hooks

接入外部 HTTP 服务：

10. 节点（Nodes）

OpenClaw 支持配对 iOS、Android、macOS 设备作为节点，提供：

Canvas — 屏幕截图、URL 导航
Camera — 拍照和录制视频
Screen Recording — 屏幕录制
Location — 获取位置
Voice — 语音交互
通知 — 推送系统通知

macOS 节点

在 macOS 上安装节点：

iOS / Android

从 App Store / Play Store 安装 OpenClaw 应用
扫描网关上的配对二维码
审批配对请求：

节点命令示例

11. 安全设置

DM 访问控制

配对审批

设备管理

安全审计

建议的安全实践

不要设置 dmPolicy: "open" — 使用 pairing 或 allowlist
为每个渠道配置 allowFrom 白名单
群组中启用 requireMention: true
定期运行 openclaw security audit
使用 Token 认证而非密码认证

12. 故障排除

常见问题

Gateway 无法启动

WhatsApp 连接断开

Telegram Bot 无响应

配置验证失败

日志查看

健康检查

重置

附录：配置文件完整参考

完整配置字段参考请查阅官方文档：

获取帮助

📘 官方文档：https://docs.openclaw.ai
💬 Discord：https://discord.com/invite/clawd
🛒 ClawHub（技能市场）：https://clawhub.ai
🐛 问题反馈：https://github.com/openclaw/openclaw

祝你使用愉快，🦞 OpenClaw 会是你最得力的 AI 助手！

AI 总结 (Qwen API)

生成时间: 2026-03-28 23:28:57

深度总结：

OpenClaw 是一个面向隐私优先、自托管场景的 AI 网关系统，其核心价值在于将异构即时通讯平台（WhatsApp/Telegram/Discord/iMessage 等）统一接入本地运行的 AI 助手生态，实现“消息即接口、聊天即工作流”的智能代理架构。它并非单一聊天机器人，而是一个可编程、可扩展、安全可控的AI 对话基础设施层。

系统采用清晰的分层设计：
🔹 Gateway（网关） 作为中央协调进程，承担连接管理、协议适配、API 路由与状态同步；
🔹 Agent 是语义与能力单元——每个 Agent 拥有独立工作空间、会话上下文、工具权限和模型策略，支持细粒度隔离与专业化分工；
🔹 Channel（渠道） 是双向通信端点，内置主流平台支持 + 插件化扩展机制，兼顾开箱即用性与企业集成能力；
🔹 Session 模型 提供多级会话粒度（per-peer 到 per-account-channel-peer），精准建模真实对话关系；
🔹 安全模型 以“默认最小权限”为原则，通过 pairing 配对审批、白名单 DM 控制、设备信任链、Token 认证等机制构筑纵深防御；
🔹 运维体系 高度成熟：支持热重载配置、CLI 全生命周期管理、Web 控制面板、跨平台节点（iOS/macOS/Android）、自动化 Cron/Heartbeat/Hooks，以及一键诊断（openclaw doctor）与审计（security audit）。

其技术哲学体现为：去中心化控制权 + 中心化协调能力 + 边缘化执行智能——数据永不离境，逻辑高度可定制，部署极度轻量（Node.js 单进程），同时通过 Skills（ClawHub 技能市场）和插件渠道实现生态可延展性。

核心关键词标签（3–5 个）：

#AI网关 #自托管AI #多渠道集成 #Agent架构 #隐私优先

添加评论

点踩

分享查看原文

参与讨论