OpenClaw 使用指南

材料与逻辑

TPE选型攻略一次搞懂PPAP：从提交到批准的完整指南铝合金阳极氧化工艺详解 APQP 第五阶段：量产、反馈、评定与纠正 APQP 第四阶段：产品与过程验证 APQP 第三阶段：过程设计开发控制计划（Control Plan）在制造业中的深度解析控制计划（CP）：制造业质量管理的核心支柱 PFMEA系统学习与制造业质量工具集成第一性原理系统学习报告：从认知底层到创新实践桌面端 EPUB 工具：Jane Reader及不同阅读器功能对比 APQP第二阶段（产品设计和开发）学习与实施指南 APQP第一阶段：顾客声音（VOC）向项目指标转化的标准化指南制造业研发技术中的WBS（工作分解结构）应用一个玩具车项目，讲清新版 APQP 怎么干质量是设计出来的：APQP 核心框架与全流程详解思维导图系统学习与职场应用指南 ISO 4892 塑料实验室光源暴露试验标准系统梳理与应用分析高分子材料挤出成型工艺系统研发技术报告制造业研发人员如何制定高效的项目开发计划：从材料开发到工艺落地的系统性指南材料耐候性评价指南：色差值 ΔE 与抗老化等级的标准转换及年限推算自动化工具：将 Markdown 文档转换为静态 PNG 思维导图脚本溯因推理：原理、应用与智能演进研究高分子加工工艺对比与选型参考归纳推理：从经验观察到知识泛化的系统化研究铝合金及其关键部件表面处理技术通过 rclone 自动备份 Lsky Pro（兰空图床）数据至 OneDrive 使用 Mole 进行 macOS 深度清理与系统优化轻量级多服务器监控：Beszel 的安装与实战部署 Python 自动化实践：Typora 自定义上传接口与兰空图床集成使用 Python 脚本一键上传图片到兰空图床并自动复制链接你的私有知识库：自托管 Markdown 笔记方案 NoteDiscovery 极简主义搜索：macOS 本地文件检索工具 Cardinal 深度解析浮中一梦告别 C 盘爆红：基于 Rust 的开源瘦身神器 WindowsClear 终端提效：用 fzf 打造极致的历史命令搜索体验使用 80/20 法则掌握演绎推理提升逻辑思维方法汇总多功能、自动化整理文件夹Python脚本 Git下如何快速提交及推送 ISO 56005 创新管理体系学习与企业实施深度报告自制多功能词云图生成程序——多文件分析、删除关键词等逻辑重构与效率革命：金字塔原理在制造业研发技术中的深度应用分析思维的算法：金字塔原理深度学习与个人认知升级指南塑料及生物材料抑菌性能评估报告：基于 ISO 16869:2008 标准的深度解析 EN 13501-1 建筑材料阻燃性能测试与分类技术指南：墙板与地板体系的深度解析 EN 13501-1:2018 建筑产品燃烧性能分级报告指南 Mac下好用的命令行工具(2026版) 六西格玛在制造业研发技术工作中的具体实践重构与共生：AI时代的职场技能趋势与人才战略蓝图使用notebooklm + Gemini生成专业报告 Git命令学习：20%核心指令 vim中tab、buffer与windows区别及使用方法 ssh生成密钥、配置及登录材料研发中的 DOE 实战：如何快速锁定最优工艺窗口 📌制造业研发与质量管理核心手册（2026版） mac 下文件及文本命令行检索方案使用80/20法则阅读红楼梦

OpenClaw 使用指南

ZhangYong · 2026-03-28 · via 材料与逻辑

使用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

┌─────────────────────────────────────────────┐
│              Gateway (单一进程)              │
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │ WhatsApp │  │ Telegram │  │  Discord  │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│                                             │
│  ┌──────────┐  ┌──────────┐  ┌───────────┐  │
│  │  Web UI  │  │    CLI   │  │   移动节点  │  │
│  └──────────┘  └──────────┘  └───────────┘  │
│                                             │
│              ┌──────────────┐               │
│              │  AI Agent    │               │
│              └──────────────┘               │
└─────────────────────────────────────────────┘

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：

1	curl -fsSL https://openclaw.ai/install.sh \| bash

Windows (PowerShell)：

1	iwr -useb https://openclaw.ai/install.ps1 \| iex

其他方式（npm）：

1	npm install -g openclaw@latest

验证安装：

1	openclaw --version

3. 快速开始

步骤 1：引导式初始化

1	openclaw onboard --install-daemon

向导会依次询问：

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

步骤 2：验证网关运行

1	openclaw gateway status

步骤 3：打开控制面板

1	openclaw dashboard

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

步骤 4：发送第一条消息

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

1	openclaw channels add --channel telegram --token $TELEGRAM_BOT_TOKEN

4. 配置

配置文件位置

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

配置方式

方式一：交互式向导

1 2	openclaw onboard openclaw configure

方式二：CLI 单行命令


openclaw config get agents.defaults.workspace


openclaw config set agents.defaults.heartbeat.every "2h"


openclaw config unset plugins.entries.brave.config.webSearch.apiKey

方式三：直接编辑

1	nano ~/.openclaw/openclaw.json

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

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

热重载规则

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

常用配置示例

最小配置（仅 WhatsApp）：

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

多渠道配置：

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
    },
    discord: {
      enabled: true,
      botToken: "xyz",
      dmPolicy: "allowlist",
      allowFrom: ["user:123", "user:456"],
    },
  },
}

多模型配置：

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-7",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-7": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

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 快速配置





openclaw channels add --channel telegram --token $TELEGRAM_BOT_TOKEN


openclaw config set channels.telegram.dmPolicy "pairing"


openclaw channels status

WhatsApp 配置


openclaw channels login --channel whatsapp


openclaw config set channels.whatsapp.allowFrom ["+15555550123"]
openclaw config set channels.whatsapp.dmPolicy "allowlist"

Discord 配置






openclaw channels add --channel discord --token $DISCORD_BOT_TOKEN
openclaw config set channels.discord.dmPolicy "pairing"

群组配置

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

{
  channels: {
    telegram: {
      groups: {
        "*": { requireMention: true },
      },
    },
  },
  agents: {
    list: [{
      id: "main",
      groupChat: {
        mentionPatterns: ["@openclaw", "openclaw"],
      },
    }],
  },
}

6. CLI 命令参考

核心命令


openclaw onboard              
openclaw configure           


openclaw gateway status       
openclaw gateway start       
openclaw gateway stop        
openclaw gateway restart     
openclaw dashboard            


openclaw config get <path>    
openclaw config set <path> <value>  
openclaw config file          
openclaw config validate     


openclaw doctor               
openclaw health               
openclaw status               
openclaw logs

渠道管理

openclaw channels list        
openclaw channels status      
openclaw channels add         
openclaw channels add --channel telegram --token xxx  
openclaw channels remove --channel discord
openclaw channels login --channel whatsapp  
openclaw channels logout --channel whatsapp

Agent 管理

openclaw agents list          
openclaw agents add <name>    
openclaw agents delete <id>   
openclaw agents bindings      


openclaw models list          
openclaw models set <model>   
openclaw models status

会话 & 消息

openclaw sessions             
openclaw message send --target <id> --message "Hello"


openclaw cron list            
openclaw cron add --name "daily" --every "1d" --system-event "..."
openclaw cron rm <id>
openclaw cron run <id>

Skills（技能）

openclaw skills list          
openclaw skills search <query>  
openclaw skills install <slug>  
openclaw skills update <slug>    
openclaw skills info <name>

配对 & 设备

openclaw pairing list          
openclaw pairing approve <channel> <code>  
openclaw devices list         
openclaw devices approve <requestId>

浏览器控制

openclaw browser status       
openclaw browser start        
openclaw browser open <url>   
openclaw browser screenshot

其他

openclaw backup create         
openclaw update               
openclaw uninstall             
openclaw docs <query>

7. Web 控制面板

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

1	http://127.0.0.1:18789/

功能

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

首次连接

打开 http://127.0.0.1:18789/
输入 Gateway Token（在初始化时生成，保存在 ~/.openclaw/openclaw.json 的 gateway.auth.token 字段）

首次在新设备连接时需要配对审批：

1 2	openclaw devices list openclaw devices approve <requestId>

远程访问

方式一：Tailscale

1	openclaw gateway --tailscale serve

方式二：SSH 隧道

1	ssh -L 18789:127.0.0.1:18789 user@your-server

8. 多 Agent 与路由

为什么要多 Agent？

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

添加新 Agent

1	openclaw agents add work --workspace ~/.openclaw/workspace-work

配置路由绑定

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

指令中切换 Agent

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

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

9. 自动化与定时任务

Cron 定时任务


openclaw cron add \
  --name "daily-briefing" \
  --cron "0 9 * * *" \
  --system-event "发送每日简报"


openclaw cron add \
  --name "health-check" \
  --every "30m" \
  --message --target "#alerts" "健康检查"


openclaw cron list


openclaw cron run <jobId>


openclaw cron rm <jobId>

Heartbeat（心跳）

定期让 Agent 执行检查任务：

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",      // 间隔
        target: "last",    // 回复到最后一个活跃会话
      },
    },
  },
}

Webhooks / Hooks

接入外部 HTTP 服务：

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

10. 节点（Nodes）

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

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

macOS 节点

在 macOS 上安装节点：

1	openclaw nodes install

iOS / Android

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

审批配对请求：

1 2	openclaw nodes pending openclaw nodes approve <requestId>

节点命令示例


openclaw nodes status


openclaw nodes camera snap --node my-iphone


openclaw nodes canvas snapshot --node my-iphone


openclaw nodes run --node my-mac --command "echo hello"

11. 安全设置

DM 访问控制

{
  channels: {
    telegram: {
      dmPolicy: "pairing",    // 默认：需要配对审批
      allowFrom: ["tg:123"],  // allowlist 模式下允许的用户
    },
  },
}

配对审批


openclaw pairing list


openclaw pairing approve telegram ABC123

设备管理


openclaw devices list


openclaw devices revoke --device <deviceId> --role operator


openclaw devices clear --yes --pending

安全审计

1
2
3

openclaw security audit       
openclaw security audit --deep 
openclaw security audit --fix

建议的安全实践

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

12. 故障排除

常见问题

Gateway 无法启动


openclaw doctor


openclaw logs --lines 100

WhatsApp 连接断开

1
2
3


openclaw channels logout --channel whatsapp
openclaw channels login --channel whatsapp

Telegram Bot 无响应


openclaw config get channels.telegram.botToken


openclaw channels status --probe

配置验证失败


openclaw config validate


openclaw doctor --fix

日志查看


openclaw logs --follow


openclaw logs --lines 200


openclaw logs --json

健康检查

1
2
3

openclaw doctor              
openclaw doctor --deep       
openclaw doctor --fix

重置


openclaw reset --scope config --yes


openclaw reset --scope full --yes

附录：配置文件完整参考

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

获取帮助

📘 官方文档：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架构 #隐私优先

此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。原文来自 — 版权归原作者所有。

推荐订阅源

材料与逻辑

1. 核心概念

Gateway（网关）

Agent

Session（会话）

Channel（渠道）

DM 安全策略

配置存储

2. 安装

环境要求

安装命令

3. 快速开始

步骤 1：引导式初始化

步骤 2：验证网关运行

步骤 3：打开控制面板

步骤 4：发送第一条消息

4. 配置

配置文件位置

配置方式

热重载规则

常用配置示例

5. 渠道（Channels）

支持的渠道

Telegram 快速配置

WhatsApp 配置

Discord 配置

群组配置

6. CLI 命令参考

核心命令

渠道管理

Agent 管理

会话 & 消息

Skills（技能）

配对 & 设备

浏览器控制

其他

7. Web 控制面板

功能

首次连接

远程访问

8. 多 Agent 与路由

为什么要多 Agent？

添加新 Agent

配置路由绑定

指令中切换 Agent

9. 自动化与定时任务

Cron 定时任务

Heartbeat（心跳）

Webhooks / Hooks

10. 节点（Nodes）

macOS 节点

iOS / Android

节点命令示例

11. 安全设置

DM 访问控制

配对审批

设备管理

安全审计

建议的安全实践

12. 故障排除

常见问题

日志查看

健康检查

重置

附录：配置文件完整参考

获取帮助

AI 总结 (Qwen API)

深度总结：

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