二环外的开阳里

OpenClaw，曾用名 ClawdBot 或 Moltbot，是一个开源的个人 AI 助理项目。它并非运行在云端的 SaaS 服务，而是部署在你自己的计算机上，让你能够完全掌控自己的数据与工作流。通过 WhatsApp、Telegram、飞书、钉钉等日常聊天工具，你就可以与它交互，让它处理邮件、管理日历、编写代码，甚至控制你的智能家居。

这个项目的核心理念在于，它不仅仅是一个能对话的聊天机器人，更是一个能实际执行任务的“行动者”。它拥有持久的记忆，可以访问你的文件系统和网络，并通过不断学习和扩展“技能”（Skills）来变得更强大。

由于其开源和可本地部署的特性，OpenClaw 吸引了大量开发者和技术爱好者，社区中涌现出许多富有创造力的用法，从自动化公司运营到管理个人生活，展现了个人 AI 助理的巨大潜力。

本篇教程将从零开始，详细介绍如何下载、安装并开始使用 OpenClaw，帮助你搭建属于自己的第一个 AI 助理。

一、OpenClaw的安装

1.1. 环境准备

在开始安装之前，需要确保你的系统满足以下基本要求。OpenClaw 主要为类 Unix 环境设计，但在 Windows 上可以通过 WSL2 (Windows Subsystem for Linux 2) 完美运行。

系统要求:

Node.js: 版本需要大于或等于 22。Node.js 是 OpenClaw 的运行环境。
操作系统: macOS, Linux, 或 Windows (通过 WSL2)。
包管理器: 如果选择从源码编译，需要安装 pnpm。对于大多数用户，推荐使用 npm，它会随 Node.js 一起安装。

本文演示环境为Ubuntu24.04

1.1.1. 安装Nodejs

参照官网安装方法 Node.js — 下载 Node.js®

 # 安装必要依赖
 apt update
 apt -y install git libatomic1
 
 # 下载并安装 nvm （如该步骤因网络原因不成功，请手动安装nodejs）
 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
 
 # 代替重启 shell
 \. "$HOME/.nvm/nvm.sh"
 
 # 下载并安装 Node.js：
 nvm install 24
 
 # 验证 Node.js 版本：
 node -v # Should print "v24.13.0".
 
 # 验证 npm 版本：
 npm -v # Should print "11.6.2".

1.2. 开始安装OpenClaw

OpenClaw 提供了多种安装方式，以适应不同用户的需求。对于初学者，官方推荐使用一键安装脚本，它能自动处理大部分环境配置。

1.2.1. 快速安装 (推荐)

这是最简单、最快捷的安装方式。它会自动检测你的操作系统，安装必要的依赖，并将 openclaw 命令部署到全局。

 curl -fsSL https://openclaw.bot/install.sh | bash

安装时间较长！

安装脚本执行完成后，会自动进入一个名为 onboard 的交互式设置向导，引导你完成初始配置。如果因为某些原因中断了向导，可以随时通过以下命令重新启动：

 openclaw onboard --install-daemon

1.2.2. 安装方式概览（可选）

除了推荐的快速安装脚本，OpenClaw 还支持其他几种安装方式。了解它们的区别可以帮助你根据自己的技术背景和使用场景做出更合适的选择。

安装方式	描述	适用场景
安装脚本	官方推荐的一键式脚本，通过 npm 全局安装，并运行设置向导。	绝大多数初学者和普通用户。
手动全局安装	如果已安装 Node.js，可直接使用 `npm` 或 `pnpm` 命令手动安装。	熟悉 Node.js 生态，希望对安装过程有更多控制的用户。
从源码安装	从 GitHub 克隆项目仓库，然后手动编译和构建。	开发者、贡献者，或希望修改、调试 OpenClaw 核心代码的用户。
Docker	使用官方提供的 Docker 镜像来运行 OpenClaw。	熟悉容器化技术，希望在隔离环境中运行服务的用户。

二、OpenClaw的配置和使用

2.1. 初始化和配置

安装完成后，下一步是进行初始化配置，让 OpenClaw 连接到大语言模型 (LLM) 并设置好通信渠道。

2.1.1. 运行 Onboarding 向导

onboard 向导是完成初始配置最简单的方式。它会一步步引导你设置所有必需的选项。

 openclaw onboard --install-daemon

接下来根据向导快速处理选项：

Onboarding mode

对于首次配置的用户，建议优先选择 QuickStart 模式——该模式以「最小配置+最快部署」为目标，可跳过非必要配置项，快速完成 OpenClaw 基础部署。

Model/auth provider

配置要使用的模型，可以在这里直接配置，也可以后续通过配置文件处理。

笔者使用 Qwen 国内模型

当出现下面链接时，请点击并前往 Qwen 网站进行认证关联：

Select channel

设置你希望通过哪个聊天软件与 OpenClaw 交流，比如 Telegram 或 WhatsApp。向导会引导你完成配对。目前都是一些国外软件，我们先跳过

Configure skills now?

问你要不要 skills，无脑选 Yes 就行（先按空格键再按 Enter 回车键），或者直接跳过。Hooks 的话推荐安装。

其它的配置用不到，选择NO

How do you want to hatch your bot?

选择 Hatch in TUI，通过终端使用，后面也可以通过配置 Web UI 以便我们可以通过网页访问 OpenClaw。

最后查看界面输出的信息，将这些信息保存下来。

之后就可以在终端和AI进行对话了

同时访问 http://127.0.0.1:18789/?token=xxx 这个地址也可以在web界面中访问

2.1.2 使用公网访问 OpenClaw（非必须）

不用暴露访问到外网也可以，如果不需要接入 Telegram、WebUI 公开访问，可以跳过这一节内容。

如果有域名，建议使用域名绑定，而不是使用暴露端口的方式映射 OpenClaw 到公网。

执行命令配置 OpenClaw。

 openclaw configure

Where will the Gateway run?

选择 Remote (info-only) 以便能够在外部访问服务器中你的 OpenClaw。

接着要注意 Gateway WebSocket URL 下面提示的地址是可以修改的，找到你的云服务器公网 IP，替换里面的 127.0.0.1。

Gateway auth

选择 Token，也就是要有凭证才能访问 OpenClaw。

Gateway token

相当于输入密码，后续访问 OpenClaw 需要提供此密码，

停止gateway

 openclaw gateway stop

将 ~/.openclaw/openclaw.json 里面的 mode 改成 remote，bind 改成 lan，并添加配置

 "controlUi": {
     "allowInsecureAuth": true
 }

使用 --allow-unconfigured 启动不安全的模式。

 openclaw gateway --allow-unconfigured

此时，在web界面中用公网ip:端口访问（记得加token）

三、Openclaw的使用

3.1. 命令速查

 openclaw onboard
 # 引导
 openclaw configure
 # 配置
 openclaw models status 
 # 用于检查已配置的 AI 模型及其 API Key 的状态，包括是否有效或即将过期。确保模型可用是助理正常工作的前提。
 openclaw channels list
 # 可以列出所有已配置的通信渠道及其当前状态。
 openclaw memory search
 # 对 AI 助理的长期记忆进行语义搜索。你之前告诉它的所有信息，都可以通过这个命令快速找回。
 openclaw docs
 # 快速搜索官方文档。
 openclaw health
 openclaw doctor
 # 状态检查

3.2 配置文件总览

 ~/.openclaw/openclaw.json           # 主配置文件
 ~/.openclaw/workspace/              # 技能、提示词、记忆
 ~/.openclaw/credentials/            # OAuth 和 API 凭证
 ~/.openclaw/agents/                 # 多代理配置
 ~/.openclaw/credentials/oauth.json  # OAuth 令牌（Claude 等）

3.3 Gateway 核心服务

在配置过程中，你坑可能频繁遇到一个概念：Gateway。Gateway 是 OpenClaw 的心脏，一个始终在后台运行的核心进程。它负责管理与大语言模型的连接、维护与 WhatsApp 或 Telegram 等聊天工具的会话，并处理所有的事件和指令。

简单来说，你通过聊天工具发送的每一条消息，都会先到达 Gateway，Gateway 再调用 AI 模型进行思考，并将结果返回给你或执行相应的操作。将 Gateway 安装为系统服务，就相当于拥有了一个永不离线的数字助理。

可以使用以下命令来控制 Gateway 服务：

安装 Gateway: openclaw gateway install
启动 Gateway: openclaw gateway start（这个若用不了用 openclaw gateway ）
停止 Gateway: openclaw gateway stop
重启 Gateway: openclaw gateway restart
卸载 Gateway: openclaw gateway uninstall
查看 Gateway 状态: openclaw gateway status

四、openclaw接入各大应用

4.1. 准备阶段

让OpenClaw在后台保持运行

 loginctl enable-linger $(whoami) && export XDG_RUNTIME_DIR=/run/user/$(id -u)
 
 openclaw gateway

此时，关闭中断，openclaw也会在运行中

4.2. 接入飞书

4.2.1. 创建飞书机器人

4.2.1.1. 来到飞书开发者后台

飞书开放平台地址：https://open.feishu.cn

登录并进入开发者后台

4.2.1.2. 创建应用

点击创建企业自建应用

创建后可以查看到应用凭证，后续我们需要用该凭证接入到openclaw

4.2.1.3. 创建机器人

点击【添加应用能力】，并添加机器人

添加后在左侧菜单栏中应用能力模块下可以看到已创建的机器人

4.2.1.3. 添加权限

点击【权限管理】，并【开通权限】

把即时通讯相关的权限全部开通：

具体的权限需求以及配置可参考：m1heng/clawdbot-feishu
下面列出部分权限

必需权限

权限	范围	说明
`im:message`	消息	发送和接收消息
`im:message.p2p_msg:readonly`	私聊	读取发给机器人的私聊消息
`im:message.group_at_msg:readonly`	群聊	接收群内 @机器人的消息
`im:message:send_as_bot`	发送	以机器人身份发送消息
`im:resource`	媒体	上传和下载图片/文件

可选权限

权限	范围	说明
`contact:user.base:readonly`	用户信息	获取用户基本信息（用于解析发送者姓名，避免群聊/私聊把不同人当成同一说话者）
`im:message.group_msg`	群聊	读取所有群消息（敏感）
`im:message:readonly`	读取	获取历史消息
`im:message:update`	编辑	更新/编辑已发送消息
`im:message:recall`	撤回	撤回已发送消息
`im:message.reactions:read`	表情	查看消息表情回复

工具权限

只读权限（最低要求）：

权限	工具	说明
`docx:document:readonly`	`feishu_doc`	读取文档
`drive:drive:readonly`	`feishu_drive`	列出文件夹、获取文件信息
`wiki:wiki:readonly`	`feishu_wiki`	列出空间、列出节点、获取节点详情、搜索
`bitable:app:readonly`	`feishu_bitable`	读取多维表格记录和字段

读写权限（可选，用于创建/编辑/删除操作）：

权限	工具	说明
`docx:document`	`feishu_doc`	创建/编辑文档
`docx:document.block:convert`	`feishu_doc`	Markdown 转 blocks（write/append 必需）
`drive:drive`	`feishu_doc`, `feishu_drive`	上传图片到文档、创建文件夹、移动/删除文件
`wiki:wiki`	`feishu_wiki`	创建/移动/重命名知识库节点
`bitable:app`	`feishu_bitable`	创建/更新多维表格记录

云空间访问权限 ⚠️

重要： 机器人没有自己的"我的空间"（根目录）。机器人只能访问被分享给它的文件/文件夹。

要让机器人管理文件：

在你的飞书云空间创建一个文件夹
右键文件夹 → 分享 → 搜索机器人名称
授予相应权限（查看/编辑）

如果不做这一步，feishu_drive 的 create_folder 等操作会失败，因为机器人没有根目录可以创建文件夹。

知识库空间权限 ⚠️

重要： 仅有 API 权限不够，还需要将机器人添加到知识库空间。

打开需要机器人访问的知识库空间
点击设置（齿轮图标）→ 成员管理
点击 添加成员 → 搜索机器人名称
选择权限级别（查看/编辑）

如果不做这一步，即使 API 权限正确，feishu_wiki 也会返回空结果。

参考文档：知识库常见问题 - 如何将应用添加为知识库成员

多维表格访问权限 ⚠️

重要： 与其他资源一样，机器人只能访问被分享给它的多维表格。

要让机器人访问多维表格：

打开需要机器人访问的多维表格
点击分享按钮 → 搜索机器人名称
授予相应权限（查看/编辑）

feishu_bitable 工具支持两种 URL 格式：

/base/XXX?table=YYY - 标准多维表格链接
/wiki/XXX?table=YYY - 嵌入在知识库中的多维表格（自动转换为 app_token）

事件订阅 ⚠️

这是最容易遗漏的配置！ 如果机器人能发消息但收不到消息，请检查此项。

在飞书开放平台的应用后台，进入 事件与回调 页面：

事件配置方式：选择 使用长连接接收事件（推荐）
添加事件订阅，勾选以下事件：

事件	说明
`im.message.receive_v1`	接收消息（必需）
`im.message.message_read_v1`	消息已读回执
`im.chat.member.bot.added_v1`	机器人进群
`im.chat.member.bot.deleted_v1`	机器人被移出群

确保事件订阅的权限已申请并通过审核

 openclaw config set channels.feishu.appId "cli_xxxxx"
 openclaw config set channels.feishu.appSecret "your_app_secret"
 openclaw config set channels.feishu.enabled true

4.2.1.4. 创建版本并发布

填写版本号相关信息

保存后自动发布，如果没有自动发布，则需要到飞书客户端手动审批

4.2.2. 安装插件

之前版本的openclaw 默认不内置飞书 Channel，需要额外安装插件，参考地址：https://github.com/m1heng/clawdbot-feishu
现在版本的openclaw 已经内置飞书了，并且两者的插件ID都是“feishu”，会产生冲突
冲突报错： duplicate plugin id detected; later plugin may be overridden (/root/.nvm/versions/node/v24.13.0/lib/node_modules/openclaw/extensions/feishu/index.ts)
处理办法：只用一个飞书就可以了

在 clawdbot 运行的服务器 / 容器中执行：