OpenClaw（原 Clawdbot/Moltbot）完全技术指南：在本地打造你的多渠道全能 AI 智能助手中枢

任侠
AI技术
3天前
249热度
0评论

[隐藏]

面向有一定技术背景的个人开发者、独立创作者和中小团队。

openclaw功能概览

一、项目背景：从 Clawdbot 到 OpenClaw

OpenClaw 是一个开源的本地 AI 助手系统，你可以把它理解为：

“运行在你自己电脑 / 服务器里的多通道 AI 助手中枢”：一侧连接各种聊天工具和开发环境，另一侧连接各类大模型和工具，在本地私有环境里长期运行，由你完全掌控。

它的命名经历了一段曲折的历史：

Clawdbot：最初名称，Logo 是一只龙虾，国内大量早期教程仍沿用这个名字。
Moltbot：2026 年初，因 Anthropic 对 “Clawd / 龙虾形象” 提出商标/形象异议，作者选择“蜕壳”更名为 Moltbot（molt = 蜕壳）。
OpenClaw：随后统一为 OpenClaw 品牌（同时强调开源、开放生态），官网为 https://openclaw.ai。

因此，你在网上看到的 Clawdbot / Moltbot / OpenClaw 基本都指同一条产品线的不同阶段，本文统一称为 OpenClaw（原 Clawdbot/Moltbot）。

适用人群大致包括：

想把 Claude、GPT 等接入日常聊天和开发工作流的开发者；
需要在私有环境部署 AI 内部助手的技术团队；
希望获得一个可操控电脑等全能智能助手，通过 AI 自动化邮件、日程、脚本任务的创造者；
对“AI Agent + 工具调用 + 多通道路由”感兴趣的高级用户。

二、OpenClaw 能做什么？

openclaw介绍

从功能上讲，OpenClaw 远不止是个“聊天机器人”，而是一个 AI 助手操作层（Orchestration Layer）：

2.1 多通道统一入口

国外 IM：Telegram、WhatsApp、Discord、Slack、LINE、Google Chat 等；
本地入口：
- Web 控制台（浏览器访问）、Web 聊天界面；
- 终端 TUI（命令行聊天界面）；
国内渠道（通过第三方插件/扩展）：
- 钉钉；
- 飞书；
- 企业微信；
- 社区在开发 QQ 机器人等更多入口。

你可以在配置中指定：

哪些通道启用 / 禁用；
哪些用户、群组可以访问（白名单 / 配对模式）；
群聊中是否必须 @ 机器人才响应。

2.2 主动式 AI：不再只是“你问我答”

OpenClaw 内置定时任务和事件触发能力，可以变成一个“主动帮你干活”的秘书。例如：

基于 Cron 的定时任务：
- 每天固定时间推送「今日待办 + 日程 + 邮件摘要」；
- 把 GitLab / GitHub 通知汇总成日报；
基于事件的触发：
- 被邮件、Webhook、系统事件唤起，自动执行某些 Workflow；
支持多 Agent 路由：
- “生活助理”管日程、家庭事项；
- “开发助理”专注代码与部署；
- “团队助理”关注项目、会议纪要等。

2.3 能动型 Agent：真正“帮你干活”

经你授权后，Agent 可以：

执行命令：通过 node-pty 等实现伪终端，执行 shell / 命令行；
读写文件：查看、修改本地项目文件、配置、日志；
操控浏览器：使用 Playwright / CDP 控制浏览器，访问网页、登录后台、自动填写表单；
访问 API / 服务：调用邮件、日历、GitHub、云厂商 API 等各种外部服务。

简单来说，Agent 可以做任何你想做的事情：用电脑能做的，它都能做到。
但这也是安全风险最大的部分，因此它提供了严格的权限与沙箱机制（见后文“安全章节”）。

2.4 Live Canvas / A2UI：从聊天到“可视化工作台”

OpenClaw 具备 Live Canvas（又称 A2UI，Agent‑to‑UI）的能力：

Agent 不再只返回纯文本，而是返回一段结构化的“UI 描述”；
前端 Canvas Host 把它渲染为可交互的画布：
- 任务看板、图表、统计面板；
- 可点击的按钮、切换器、表格等；
适合构建“个人或团队的 AI 控制面板”，比如：
- 项目进度仪表板；
- 日程 + 待办 + 邮件一体化看板。

三、技术架构：微核 + 插件 + 网关

openclaw技术架构

OpenClaw 在工程上采用了 “微核（Microkernel）+ 插件（Skills/Channels）+ 统一网关（Gateway）” 的模式：

3.1 运行时与语言栈

Node.js ≥ 22：强制要求，利用原生 fetch、node:sqlite、更好的 HTTP 栈和新语法；
TypeScript 全栈：
- Gateway、Agent 运行时、插件框架均用 TS 实现；
- 使用 TypeBox、Zod 对配置和数据结构做运行时校验；
HTTP 与 WebSocket：
- HTTP：Express 5 + Hono 4.x 路由；
- WebSocket：ws 库，承载聊天流与控制流。

3.2 Agent 四要素：LLM + Tools + Memory + Planning

可以把每个 Agent 理解为由四部分组成：

LLM（大脑）
通过统一的 Provider 抽象对接：
- 云端模型：Anthropic Claude、OpenAI、AWS Bedrock 等；
- 本地模型：Ollama、本地推理服务等。
  配置集中在 models.providers 字段中（包括 baseUrl、apiKey、models 等）。
Tools（手）
把各种能力封装为可调用工具：
- Shell 工具：执行命令、脚本；
- 浏览器工具：打开网页、点击、抓取数据；
- 业务工具：邮件、日历、GitHub、云 API 等。
  工具以 Skills/插件 形式加载，模型通过“函数调用式”结构化输出告知要用哪个工具、携带什么参数。
Memory（记忆）
- 短期记忆：会话历史（消息列表）；
- 长期记忆：
  - 用户画像、偏好写入 Markdown 文档（如 USER.md、SOUL.md）；
  - 对话、文件内容向量化后存入 sqlite‑vec 等向量存储；
    Agent 可以主动调用“查询记忆”的工具，从而“记住你是谁”。
Planning（规划）
- 使用类似 ReAct 的循环：思考 → 选择工具 → 执行 → 观察 → 再思考；
- 对复杂任务进行分解、排序和多轮执行；
- 可以调用子 Agent 形成多 Agent 协作。

OpenClaw 的核心价值，就是在这四要素之上提供一个安全、可配置的协调层。

3.3 微核与插件

微核（Gateway）提供：
- 配置管理、会话路由、安全策略；
- Web UI 和 WebSocket 控制面板；
- 日志与诊断工具。
插件（Skills/Channels）：
- 工具插件：系统命令、浏览器自动化、RAG 检索、第三方 API；
- 通道插件：Telegram、WhatsApp、Slack、Discord、钉钉、飞书、企业微信等；
- 全部通过统一接口注入到 Agent 中，被 LLM 以函数调用方式调度。

四、ACP 协议：让 OpenClaw 成为“可插拔的编码 Agent”

OpenClaw 之所以能很好地与编辑器 / IDE 联动，很大程度上依赖 ACP（Agent Client Protocol，Agent 客户端协议）。

4.1 ACP 是什么？

ACP 的定位可以类比 LSP（Language Server Protocol）之于语言服务：

一套基于 JSON‑RPC 2.0 的标准协议，用来定义“客户端应用（如 IDE）如何与 AI Agent 交互”。

特点包括：

JSON‑RPC 2.0：结构化请求/响应，便于多语言实现；
传输层无关：可以用 stdin/stdout、本地 socket、WebSocket 等；
双向通信：
- IDE 请求 Agent（如“根据当前文件生成测试用例”）；
- Agent 反过来请求 IDE 执行操作（如“替换这段代码 / 展示 diff”）；
MCP 类型复用：
- ACP 复用 MCP（Model Context Protocol）定义的一部分数据结构（工具描述、文档片段等），
- 再对编码场景扩展了 diff、诊断信息等内容。

可参考这篇文章 https://lzw.me/a/acp-intro.html 进一步了解。

4.2 OpenClaw 的 ACP Bridge

OpenClaw 内部有一层 ACP Bridge：

一端用 ACP/JSON‑RPC 接收来自 IDE 的请求（通常通过 stdin/stdout）；
另一端通过 WebSocket 与 Gateway 通信；
维护 IDE 会话 ID 与 Gateway 会话 key 的映射：
- 确保“VS Code 里开一个面板”对应 Gateway 中的某个持久会话；
- 让不同编辑器共享同一个 Agent 记忆与工作区。

在这个架构下：

VS Code / Zed / 其它编辑器只需实现 ACP 客户端；
就可以直接把 OpenClaw 当成一个“远程编码 Agent 后端”来用；
由 OpenClaw 统一处理模型调用、工具权限、记忆、规划等细节。

五、A2UI / Live Canvas：在 ACP 之上的生成式 UI

在 ACP 的基础上，OpenClaw 又叠加了一层 A2UI（Agent‑to‑UI）/ Live Canvas 协议：

Agent 输出的不是 HTML/JS，而是一段描述 UI 意图的 JSON：
- 例如“渲染一个折线图、一个任务列表、一排按钮”；
前端 Canvas Host（通常监听 18793 端口）接收这段 JSON；
使用 Web Components / 前端组件库渲染成真实 UI；
这种结构化 UI 描述可以被版本化、记录和回放，也便于权限和安全控制。

结合 ACP + A2UI，OpenClaw 做到：

在 IDE 中：作为“编码 Agent”，插入到编辑器侧边栏或面板；
在浏览器中：作为“控制面板 Agent”，动态搭建看板和工具界面。

六、安装与首次启动：从 0 到 1

6.1 安装环境

(1) 确认 Node 版本：

node --version   # 若低于 22.5.0，请升级至最新版本

用 nvm 管理和安装 Node.js 示例：

nvm install 22.22.0
nvm use 22.22.0
nvm alias default 22.22.0

用 fnm 管理和安装 Node.js 示例：

fnm install 22
fnm use 22
fnm default 22

(2) 全局安装 OpenClaw：

npm install -g openclaw

openclaw --version

6.2 第一次运行：onboard 向导

在终端执行：

openclaw onboard

主要步骤：

安全声明：告知 Agent 可能拥有命令执行、文件访问能力；
配置模型：
- Claude Pro/Max 用户可用 setup-token；
- 也可以填 Claude/OpenAI/国内代理 API Key 和自定义 baseUrl；
暂不配置通道：建议先不用 Telegram/Slack，只用 Web 控制台测试。

向导完成后，会输出 Web UI 地址：

Web UI: http://127.0.0.1:18789/
Web UI (with token): http://127.0.0.1:18789/?token=xxx

浏览器打开带 token 的地址，发一条消息测试即可。

七、国内环境推荐：通过浏览器 + 局域网形式使用

考虑到国内对境外 IM 的使用限制，最现实的方案是：

在本地或 NAS 上运行 OpenClaw，
然后用 浏览器 + 局域网 访问 Web 控制台。

7.1 启用局域网访问

找到配置文件（视安装版本而定）：

~/.openclaw/openclaw.json
~/.clawdbot/clawdbot.json

修改 gateway 段：

{
  "gateway": {
    "mode": "local",
    "bind": "lan",
    "port": 18789,
    "auth": {
      "mode": "token",
      "token": "可用 openssl rand -hex 32 命令随机生成"
    }
  }
}

重启网关：

openclaw gateway restart

在手机/平板访问：

假设运行机器的局域网 IP 是 192.168.1.100：

http://192.168.1.100:18789/?token=刚才设置的token

只要在同一 Wi‑Fi / 局域网内，就可以像访问“家庭版 ChatGPT + 控制台”一样使用。

提醒：如果只在本机使用，保持 bind=loopback 是更安全的选择。18789 端口可以改为其它端口，但要确保防火墙放行。

八、接入国内应用：钉钉、飞书、企业微信

在“浏览器 + LAN”跑稳之后，你可以按需把 OpenClaw 接到国内 IM。

8.1 钉钉接入：从零搭一个“AI 数字员工”

路线一：钉钉 + 阿里云 AppFlow 模板（低代码）

在钉钉开放平台创建企业内部应用，开启机器人与卡片能力，获取：
- ClientID / ClientSecret；
- AI 卡片模板 ID；
在 OpenClaw 中开启 HTTP 响应路径（如 /dingtalk），并配置认证 token；
在阿里云 AppFlow 控制台使用“钉钉 ⇆ OpenClaw”模板：
- 一端配置钉钉凭证；
- 一端配置 OpenClaw 网关地址和 token；
启用后，在钉钉群聊中 @ 机器人，即可触发 AppFlow → OpenClaw → 钉钉 AI 卡片回复的闭环。

路线二：openclaw-dingtalk / @openclaw-china/dingtalk 插件

安装插件：

openclaw plugins install @openclaw-china/dingtalk

配置钉钉通道（示例）：

openclaw config set channels.dingtalk '{
  "enabled": true,
  "clientId": "dingXXXX",
  "clientSecret": "your-app-secret",
  "enableAICard": true
}' --json

在配置文件中进一步细化权限：

{
  "channels": {
    "dingtalk": {
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "requireMention": true
    }
  }
}

这种方案不依赖 AppFlow，更灵活，更适合有一定 Node/运维能力的团队。

8.2 飞书 / 企业微信：用 `moltbot-china` 一键集成

社区维护的 moltbot-china 项目（现已适配 OpenClaw）提供了国内渠道插件合集：

支持：钉钉、飞书、企业微信（未来还会补齐 QQ 等）；
一次安装，多通道齐开。

安装统一插件包：

openclaw plugins install @openclaw-china/channels

飞书配置：

openclaw config set channels.feishu '{
  "enabled": true,
  "appId": "cli_xxxxxx",
  "appSecret": "your-app-secret"
}' --json

企业微信配置：

openclaw config set channels.wecom '{
  "enabled": true,
  "webhookPath": "/wecom",
  "token": "your-token",
  "encodingAESKey": "43-char-key"
}' --json

然后在企业微信后台配置回调 URL https://你的域名/wecom，完成校验即可。

九、安全：高权限 Agent 必须有“牢笼”

OpenClaw 的 Agent 具备以下潜在高危能力：

执行系统命令；
读写文件、访问项目代码；
操控浏览器、访问带登录状态的页面；
通过 Skills 调用敏感外部 API（云账号、支付、CI/CD 等）。

因此，需要重点关注安全配置：

9.1 必做三件事

网关不要裸露公网
- 尽可能只在 bind=loopback 或内网 + VPN/Tailscale；
- 如确需公网访问，务必配合防火墙和 IP 白名单。
强制认证
- 使用 gateway.auth.mode=token 或 password；
- Token/密码必须足够随机、定期更换。
收紧通道策略
- 私聊：dmPolicy=pairing 或 allowlist；
- 群聊：groupPolicy=allowlist + requireMention=true；
- 对含有 shell/browser 等高危工具的 Agent，限制可调用通道。

建议：不要在有重要资料的工作电脑上运行 OpenClaw。可以使用：废旧不用的活全新的电脑、云服务器、虚拟机、Docker、云服务器等环境。

9.2 自带安全审计工具

建议安装完第一时间运行：

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

它会自动检查：

网关是否缺少认证；
配置文件和凭证目录权限是否过宽；
通道策略是否有明显风险。

十、Skills 生态：从“聊天”走向“平台”

OpenClaw 的能力高度依赖 Agent Skills（插件）生态。
社区维护的技能列表已经超过 500+，包括：

DevOps & Cloud：GitHub/GitLab 集成、部署脚本、监控告警；
办公与创作：日历、待办、Notion/Obsidian 同步、Markdown 处理；
数据分析与可视化：CSV/Excel 转换、图表生成、报表自动化；
个人效率：邮件整理、订阅管理、计划复盘。

添加 Skills 的步骤

(1) 创建技能文件:

每个技能都是一个 Markdown 文件，包含指令、命令语法和示例。你可以在本地工作区的 ~/openclaw/skills/ 目录中创建这些文件。

(2) 加载技能:

OpenClaw 会在启动时加载技能。技能的加载顺序为：
- <workspace>/skills（最高优先级）
- ~/.openclaw/skills（中等优先级）
- Bundled skills（最低优先级）
- 如果有多个地方存在同名技能，Clawdbot 会根据上述优先级进行加载。

(3) 配置额外的技能目录:

你可以通过在 ~/.clawdbot/clawdbot.json 文件中配置 skills.load.extraDirs 来添加额外的技能目录，这些目录的优先级最低。

(4) 使用 Clawdhub:

ClawHub 是 Clawdbot 的公共技能注册中心，你可以在 Clawdhub 上浏览、安装和更新技能。默认情况下，Clawdhub 会将技能安装到当前工作目录下的 ./skills 目录中。

npx clawhub@latest install sonoscli

实用建议：

初期只安装 1–3 个高优先级技能（如 GitHub、邮件、日程），避免一口气装太多；
每个技能逐个调试，熟悉其权限与行为；
对涉及生产环境和敏感数据的技能，务必阅读源码并评估安全性。

十一、推荐实践路线：不同用户怎么用？

11.1 个人 / 家庭用户

用 nvm 装好 Node 22+；
npm i -g openclaw 安装；
openclaw onboard 配好模型；
先在本机 http://127.0.0.1:18789 测试使用；
再调整 bind=lan，在家庭 Wi‑Fi 下用手机/平板访问；
跑一遍 openclaw security audit --fix；
按需求加少量 Skills（邮件、日程、笔记等）。

11.2 小团队 / 创业公司

在云服务器或内网服务器上用 Docker 部署 OpenClaw；
网关只绑定内网地址，配合 VPN/Tailscale 访问；
安装 @openclaw-china/channels，优先打通钉钉或飞书；
为不同用途创建不同 Agent（独立 workspace、工具权限）：
- “开发助理”“运营助理”“知识库助手”等；
日志接入现有日志/监控系统，观测长时间运行状态。

11.3 对安全敏感的企业 / 团队

仅在隔离环境（测试网 / 沙箱区）部署 OpenClaw；
默认开启 Docker/Nix 沙箱，对执行类工具做白名单；
所有渠道使用 pairing 或 allowlist 策略，杜绝外部用户访问；
安全部门参与插件/技能代码评审；
定期执行 openclaw security audit --deep 并按报告整改。

结语：把 AI 接入你的世界，构建全能智能助理中枢

OpenClaw（原 Clawdbot/Moltbot）代表的是一种新的形态：
不是“再造一个 ChatGPT 网站”，而是 在你的机器、你的网络、你的规则下，构建一个真正能帮你干活的本地 AI 助手中枢。

从最简单的“浏览器 + 局域网”体验开始，再逐步加上 Skills 和国内通道（钉钉、飞书、企微），你可以一步一步把它塑造成一个深度融入你工作流和生活方式的“数字同事”。

如果你愿意为搭建环境和配置安全多花一点耐心，这会是一件非常值得的长期投资。

openclaw能做什么

References

[1] README: OpenClaw — Personal AI Assistant. https://github.com/openclaw/openclaw/blob/main/README.md.
[2] Clawdbot Rebrands to Moltbot / OpenClaw（更名报道汇总）. https://laravel-news.com/clawdbot-rebrands-to-moltbot-after-trademark-request-from-anthropic.
[3] Moltbot(Clawdbot)对接本地大模型完整配置指南. https://juejin.cn/post/7600562816458784810.
[4] Clawdbot 零基础接入钉钉. http://www.sohu.com/a/981560949_400678.
[5] BytePioneer-AI/moltbot-china（国内渠道插件合集：钉钉/飞书/企微）. https://github.com/BytePioneer-AI/moltbot-china.
[6] adongguo/openclaw-dingtalk（OpenClaw 钉钉渠道插件）. https://github.com/adongguo/openclaw-dingtalk.
[7] VoltAgent/awesome-moltbot-skills（Skills 生态列表）. https://github.com/VoltAgent/awesome-moltbot-skills.
[8] 初识 Moltbot(原名 Clawdbot)（ACP 协议与架构分析）. https://new.qq.com/rain/a/20260128A06M3F00.
[9] Agent Client Protocol 官方文档. https://agentclientprotocol.com/.
[10] ClawHub. https://www.clawhub.ai