如果你曾听闻火爆大江南北的 Manus ,你可以将 OpenClaw 看作其开源版本;如果你并不了解,也没关系,如果配置合理,它可以是你的 贾维斯 或者 红皇后 。
OpenClaw 一般有三种安装方式:全量安装到宿主机(Host)、网关(Gateway)在宿主机而 Agent 在 Docker(Sandbox),以及全量安装到 Docker。
本文介绍 全量安装到宿主机(Host) 这一方式,也是三种方式中最简单的一种。

1 一些提示
教程以 debian \ ubuntu 为例 教程以 bash 为例
可以执行如下指令,查看终端类型:
echo $0该指令的输出示例如下:
# -bash or -zsh对于 bash 使用 ~/.bashrc 配置环境变量;
对于 zsh 使用 ~/.zshrc 配置环境变量。
2 准备工作
如果使用
apt安装工具的过程遇到了网络问题,可以参考文档末尾的附录一的apt换源教程 如果使用apt安装软件报错,你也可以尝试查阅文档末尾的附录一的apt换源教程
2.1 安装基础工具
执行如下指令安装 curl、git 以及编译原生模块所需的构建工具:
sudo apt update && sudo apt install -y curl git build-essential python3 make g++ cmake验证安装:
curl --versiongit --versionmake --version2.2 安装 nvm
请按照顺序执行如下指令
使用最简单的
nvm安装方式(跳过git)
export METHOD=script指定 nvm 的国内安装地址(使用 gitee 镜像)
export NVM_SOURCE="https://gitee.com/mirrors/nvm/raw/v0.40.4/nvm.sh"下载
nvm并安装
curl -o- https://gitee.com/mirrors/nvm/raw/v0.40.4/install.sh | bash让
nvm指令在终端中立即可用
source ~/.bashrc检测是否安装成功
nvm -v出现类似如下输出,代表安装成功:
# 0.40.42.3 安装 node
请按照顺序执行如下指令
设置
nvm使用阿里镜像加速下载
tee -a ~/.bashrc > /dev/null << 'EOF'
export NVM_NODEJS_ORG_MIRROR=https://npmmirror.com/mirrors/node
export NVM_NPM_MIRROR=https://npmmirror.com/mirrors/npm
EOF按照
openclaw官方推荐,安装版本号为 22 的node
nvm install 22检测是否安装成功
node -v出现类似如下输出,代表安装成功:
# v22.22.0npm -v出现类似如下输出,代表安装成功:
# 10.9.42.4 安装 openclaw
请按照顺序执行如下指令
设置
npm使用阿里镜像加速下载
npm config -g set registry https://registry.npmmirror.com安装
openclaw(安装到node所在目录);
npm i -g openclaw@2026.2.13提示:如果在安装过程中遇到 GitHub 访问错误(如
npm error code 128),请查阅 附录四:常见问题解答 (FAQ)。
检测是否安装成功。执行安装指令后,若终端不报错,或,执行如下指令可以看到版本号为
2026.2.13,代表安装成功:
openclaw -v出现类似如下输出,代表安装成功:
# 2026.2.133 注册飞书机器人
打开你的浏览器按照步骤操作
3.1 注册飞书
在飞书官网登录或者注册自己的飞书账号。
3.2 注册飞书机器人(Part 1 of 2)
飞书机器人是飞书企业自建应用提供的众多能力的一种,所以注册飞书机器人就是注册飞书企业自建应用
进入飞书开发者后台;
点击【创建企业自建应用】按钮;
在弹出的对话框,按照要求填写 应用名称 和 应用描述 信息,随意填写,如果你和我一样是选择困难症,可以:
应用名称:openclaw
应用描述:hello openclaw
应用图标保持默认即可
创建成功后会自动跳转到 应用管理页面 或手动点击 应用列表里面刚刚创建的 openclaw 应用卡片 ;
在应用管理页面,左侧是菜单,从上到下依次分类为:基础信息、应用能力、开发配置、应用发布、运营监控;
依次点击【应用能力 > 添加应用能力】,在右侧的添加应用能力页面,默认是在【按能力添加】这一列,点击 机器人 卡片(按照惯例,第一个)左下方的【添加】按钮,短暂的等待后,左侧的 应用能力 菜单会出现新的【机器人】二级菜单;
进入openclaw官网复制 可以一键导入权限的代码(JSON),并按照其要求导入到【开发配置 > 权限管理】,点击页面右侧中的【批量导入/导出权限】在弹出的对话框中,在 导入 这一列的输入框(JSON)中清空默认的无任何意义的示例代码,并将刚刚从官网复制的代码(JSON)粘贴到该输入框,然后点击【下一步,确认新增权限】按钮,在随后弹出的 确认导入权限 对话框中,点击弹窗右下方的 【申请开通】按钮,点击后,会再次弹出一个 “应用身份权限”可访问的数据范围 弹窗,再次点击右下方的 【确认】按钮即可;
点击【开发配置 > 事件与回调】,此时页面右侧应该默认在【事件配置】这一列,其下方有 订阅方式 和 已添加事件 两个配置项,其中,已添加事件 标题的右侧有一个【添加事件】按钮,为了继续配置这两个配置项,我们需要先启动
openclaw服务器,请你记住这一步还没有完成,我们继续;点击左侧菜单【基础信息 > 凭证与基础信息】,在页面的右侧可以看见 应用凭证 ,包括 App ID 和 App Secret,请不要关闭浏览器,稍后我们会将其复制到服务器的配置文件内;
3.3 注册 openrouter
Openrouter 是知名的大语言模型(LLM)服务提供商(Provider),它提供免费的调用额度(额度限制),仅需邮箱即可注册。
LLM 是
openclaw的大脑。
前往openrouter 官网,发挥你的聪明才智,想办法登录进去;
前往密钥管理后台,点击页面上非常显眼的【Create】按钮,在弹出的对话框中填写 Name 字段,如果你是选择困难症,建议:
Name:openclaw;
其它字段保持默认,无须编辑; 然后点击弹窗的【Create】按钮,然后你要注意到随后的弹窗中显示了 Your new key ,紧随其下方有一串字符, 字符的右侧有【“复制”】按钮,请你记住这个即可,请不要关闭浏览器;
3.4 启动 openclaw
将下方包含了
openclaw最小配置的 指令模版 复制到 任意可以编辑文字的编辑器 ,按照 指令模版 中的中文注释的要求,用对应信息替换这些中文注释。请注意在替换中文注释过程中 不要引入多余的空格 或者删除任何除中文注释外的其它字符,请不要删除中文注释两端的引号 :
mkdir -p ~/.openclaw && cat > ~/.openclaw/openclaw.json << 'EOF'
{
"env": {
"OPENROUTER_API_KEY": "请你将本教程 3.3节 步骤2 的 openrouter 的 Your new key 复制到这里"
},
"auth": {
"profiles": {
"openrouter:default": {
"provider": "openrouter",
"mode": "api_key"
}
}
},
"agents": {
"defaults": {
"model": {
"primary": "openrouter/openrouter/free"
}
}
},
"channels": {
"feishu": {
"enabled": true,
"accounts": {
"main": {
"appId": "请你将本教程 3.2节 步骤9 的 飞书 的 APP ID 复制到这里",
"appSecret": "请你将本教程 3.2节 步骤9 的 飞书 的 App Secret 复制到这里"
}
}
}
},
"plugins": {
"entries": {
"feishu": {
"enabled": true
}
}
},
"gateway": {
"mode": "local"
}
}
EOF将 步骤1 编辑过后的 指令 复制到终端,执行;
运行
openclaw自带的检验指令对最小化配置进行补全:
openclaw doctor --fix停止可能正在运行的网关服务。执行
openclaw doctor --fix补全配置时,可能会自动启动gateway网关服务并占用默认的18789端口。由于 OpenClaw 具备自动重启机制,常规的kill命令可能无法彻底释放端口。建议在正式启动网关前,先执行openclaw gateway stop以确保端口未被占用:
openclaw gateway stop启动
openclaw!
openclaw gateway3.5 注册飞书机器人(Part 2 of 2)
本节接续 3.2节 步骤9
请你回头看看 3.2节 步骤8,请你按照 步骤8 提示打开 【开发配置 > 事件与回调】,此时页面的右侧应该默认在【事件配置】列,点击订阅方式右侧的表示编辑含义的【铅笔、钢笔】图标,此时在其下方会出现两个单选框,默认是【使用长连接接收事件】,保持此选项不动,点击下方非常显眼的【保存】按钮,如果在 3.4节 步骤4 已经成功启动
openclaw,那么点击按钮后会显示一个短暂的加载动画,随之动画消失,表示配置成功;点击【已添加事件】右侧的【添加事件】按钮,在随后弹出的对话框的搜索框中输入 im.message.receive_v1,这会过滤出一个【接收消息】选项,点击其左侧的【复选框】,如果你成功选中,在对话框的右下方一个【确认添加】按钮会高亮,点击这个按钮;
点击【应用发布 > 版本管理与发布】,点击页面右侧非常显眼的【创建版本】按钮,在随后的表单填写页面按照要求填写必填的 应用版本号 和 更新说明 字段,如果你是一个选择困难症患者,可以:
应用版本号:1.0.0
更新说明:Hello OpenClaw !
然后滚动页面到底部,会看见一个非常显眼的【保存】按钮,点击,如果后续弹出了一个 确认提交发布申请? 弹窗,提示“本次发布免审,提交后自动通过并在线上生效”,选择【确认发布】;否则,将滚动页面到顶部,你会在页面的右上方看见一个【确认发布】的按钮,点击即可发布;
4 与 OpenClaw 对话
在飞书客户端、网页端(没错,飞书有网页端)直接搜索在 3.2节 步骤3 填写的 应用名称 ,它也是你的机器人名称,检索出来后,点击进入与机器人的聊天界面,发送任意消息以激活;
发送消息后,如果机器人没有返回一条消息,提示你在
openclaw需要为飞书这个消息渠道授权,那么,恭喜你,配置到此结束了,可以开心的探索了;否则,需要继续在终端为飞书授权;我们打开一个 新的终端,并 保持旧的终端不断开连接,因为旧的终端正在运行
openclaw服务,一旦断开,服务将会停止(如果你觉得这样不够优雅,请查阅 附录二 );在新的终端执行下面的指令,执行后,你会看到一个 Pairing requests 表格,表格的第一列存放着飞书授权码:
openclaw pairing list feishu提示:如遇到类似
openclaw: command not found的信息,请查阅 附录四:常见问题解答 (FAQ)。
复制表格中的授权码,替换下方指令模版中的中文注释并执行:
openclaw pairing approve feishu 你的授权码大功告成,恭喜你,终于可以愉快的探索
openclaw。
提示:在与机器人对话过程中,如果遇到飞书提示权限不足或授权链接无法点击的问题,请查阅 附录四:常见问题解答 (FAQ)。
附录一:apt 换源
你可以将 apt 理解为 debian \ ubuntu 等 linux 操作系统的软件商店,与安卓等设备上的通过点击图形页面上的按钮安装软件不同,通过终端操控 linux 一般通过如下指令安装软件:
apt install -y 软件名就像在国内无法安装发布在 Google Play (谷歌官方应用商店,安卓是谷歌开源的移动端操作系统) 的软件一样,国内也可能无法安装位于 debian \ ubuntu 官方的软件商城的软件。
就像在国内有很多国内的软件商城一样(华为应用商店、小米应用商店、...),有很多国内的组织、企业(阿里巴巴、中科大等)为了方便国内用户访问这些软件提供了加速服务,也叫镜像,下面以阿里巴巴阿里云镜像为例,对 apt 进行换源:
备份默认源(小心使得万年船)
sudo mv /etc/apt/sources.list /etc/apt/sources.list.bak检查系统版本
在更换源之前,请务必确认你的系统版本(如 bookworm 或 bullseye)。执行如下指令:
cat /etc/os-release | grep VERSION_CODENAME出现类似如下输出,代表检测成功(以 trixie 为例):
# VERSION_CODENAME=trixie替换阿里源
注意:以下配置以 Debian 13 (trixie) 为例。如果你使用的是 Ubuntu 或其他版本的 Debian,请前往 阿里巴巴开源镜像站 获取对应的配置。
sudo tee /etc/apt/sources.list > /dev/null << 'EOF'
deb https://mirrors.aliyun.com/debian/ trixie main contrib non-free non-free-firmware
deb-src https://mirrors.aliyun.com/debian/ trixie main contrib non-free non-free-firmware
deb https://mirrors.aliyun.com/debian/ trixie-updates main contrib non-free non-free-firmware
deb-src https://mirrors.aliyun.com/debian/ trixie-updates main contrib non-free non-free-firmware
deb https://mirrors.aliyun.com/debian-security/ trixie-security main contrib non-free non-free-firmware
deb-src https://mirrors.aliyun.com/debian-security/ trixie-security main contrib non-free non-free-firmware
deb https://mirrors.aliyun.com/debian/ trixie-backports main contrib non-free non-free-firmware
deb-src https://mirrors.aliyun.com/debian/ trixie-backports main contrib non-free non-free-firmware
EOF刷新软件商城
sudo apt update附录二:如何让 openclaw 持久运行
tmux可以理解为终端里的“虚拟窗口”,即便你的ssh断开了连接,它也能让机器人一直在后台 24 小时在线。
检查是否已经安装了
tmux:
which tmux如果出现类似如下的输出,可以直接跳转到 步骤3:
# /usr/bin/tmux安装
tmux:
sudo apt install -y tmux使用 tmux 开启一个“虚拟窗口”,并命名为“openclaw":
tmux new -s openclaw在终端内启动
openclaw:
openclaw gateway退出
tmux虚拟窗口:先按下
Ctrl+b组合键而后按下
d没错,你没看错,就是很抽象
如果想要再次进入:
tmux attach -t openclaw如果想要删除这个“虚拟窗口”,分为两种情况:
一种是你按照 步骤6 的提示进入了“虚拟窗口”,此时先按下
Ctrl+c结束活动的进程,然后按下组合键Ctrl+d就可以删除;你在“虚拟窗口”外,执行
tmux kill-session -t openclaw
附录三:关于在飞书个人版中创建机器人的一点提示
虽然我们在教程中一直称呼我们创建的机器人属于 企业自建应用 ,很多朋友可能会好奇,自己明明使用的是个人版,并没有什么企业,但仍然可以成功创建,那是因为你没有遇到下面的问题,所以体感并不强烈。
在飞书个人版中是允许创建 企业自建应用 的,但是不可以 删除 ,是的,你没有看错,通过现有的客户端或者是网页端的用户界面,你无法直接通过点击两个按钮删除自己创建的应用(截至 2026/02/14),暂且不讨论这个设计的合理性,下面给出解决方案:
要想删除应用,需要先去企业管理后台停用这个应用,但是个人版用户是没有企业后台的,因为你不是企业;
但是飞书提供了 SDK,可以通过代码调用接口的方式停用应用;
你可以通过跟飞书开放平台智能助手对话,让其帮你编写一个可以直接关闭应用的代码,参考的提示词:“如何通过调用接口停用企业自建应用,请给我一段可以直接执行的 python 代码“;通过这样一段提示词,智能助手会询问你是否生成代码,还可以通过下拉框选择你喜欢的语言,非常方便。值得注意的是,不要在提示词中提及”个人版“或”飞书个人版“等信息,因为根据文档的描述,个人版确实不支持这个操作。
在执行代码的时候注意根据控制台的提示在应用的管理后台开启通过接口停用/启用企业自建应用的相关权限,祝君好运!
这里给出一段 AI 生成的 Python 代码,将 App ID 和 App Secret 填写在对应的位置就可以执行:
import os
import json
import requests
import sys
from typing import Dict, Any, Tuple
# === input params start
app_id = "" # app_id, required, 应用 ID
# 应用唯一标识,创建应用后获得。有关app_id 的详细介绍。请参考通用参数https://go.feishu.cn/s/63iHnI02M03
app_secret = "" # app_secret, required, 应用密钥
# 应用秘钥,创建应用后获得。有关 app_secret 的详细介绍,请参考https://go.feishu.cn/s/63iHnI02M03
# === input params end
def get_tenant_access_token(app_id: str, app_secret: str) -> Tuple[str, Exception]:
"""获取 tenant_access_token
Args:
app_id: 应用ID
app_secret: 应用密钥
Returns:
Tuple[str, Exception]: (access_token, error)
"""
url = "https://open.feishu.cn/open-apis/auth/v3/app_access_token/internal"
payload = {
"app_id": app_id,
"app_secret": app_secret
}
headers = {
"Content-Type": "application/json; charset=utf-8"
}
try:
print(f"POST: {url}")
print(f"Request body: {json.dumps(payload)}")
response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
result = response.json()
print(f"Response: {json.dumps(result, indent=2)}")
if result.get("code", 0) != 0:
print(f"Error: failed to get tenant_access_token: {result.get('msg', 'unknown error')}", file=sys.stderr)
return "", Exception(f"failed to get tenant_access_token: {response.text}")
return result["tenant_access_token"], None
except Exception as e:
print(f"Error: getting tenant_access_token: {e}", file=sys.stderr)
if hasattr(e, 'response') and e.response is not None:
print(f"Response: {e.response.text}", file=sys.stderr)
return "", e
def disable_application(tenant_access_token: str, target_app_id: str) -> Tuple[bool, Exception]:
"""停用自建应用
Args:
tenant_access_token: 租户访问令牌
target_app_id: 要停用的目标应用ID
Returns:
Tuple[bool, Exception]: (是否成功, 错误信息)
"""
url = f"https://open.feishu.cn/open-apis/application/v6/applications/{target_app_id}/management"
headers = {
"Authorization": f"Bearer {tenant_access_token}",
"Content-Type": "application/json; charset=utf-8"
}
payload = {
"enable": False
}
try:
print(f"PUT: {url}")
print(f"Request body: {json.dumps(payload)}")
response = requests.put(url, json=payload, headers=headers)
response.raise_for_status()
result = response.json()
print(f"Response: {json.dumps(result, indent=2)}")
if result.get("code", 0) != 0:
print(f"Error: failed to disable application: {result.get('msg', 'unknown error')}", file=sys.stderr)
return False, Exception(f"failed to disable application: {response.text}")
print("应用停用成功")
return True, None
except Exception as e:
print(f"Error: disabling application: {e}", file=sys.stderr)
if hasattr(e, 'response') and e.response is not None:
print(f"Response: {e.response.text}", file=sys.stderr)
return False, e
def get_application_info(tenant_access_token: str, target_app_id: str) -> Tuple[Dict[str, Any], Exception]:
"""获取应用信息以验证停用状态
Args:
tenant_access_token: 租户访问令牌
target_app_id: 目标应用ID
Returns:
Tuple[Dict[str, Any], Exception]: (应用信息, 错误信息)
"""
url = f"https://open.feishu.cn/open-apis/application/v6/applications/{target_app_id}"
headers = {
"Authorization": f"Bearer {tenant_access_token}",
"Content-Type": "application/json; charset=utf-8"
}
try:
print(f"GET: {url}")
response = requests.get(url, headers=headers)
response.raise_for_status()
result = response.json()
print(f"Response: {json.dumps(result, indent=2)}")
if result.get("code", 0) != 0:
print(f"Error: failed to get application info: {result.get('msg', 'unknown error')}", file=sys.stderr)
return {}, Exception(f"failed to get application info: {response.text}")
if not result.get("data") or not result["data"].get("app"):
return {}, Exception("未获取到应用信息")
app_info = result["data"]["app"]
status = app_info.get("status", -1)
if status == 0:
print("应用状态已确认为停用状态(0)")
else:
print(f"应用当前状态: {status} (0=停用, 1=启用, 2=未启用, 3=未知)")
return app_info, None
except Exception as e:
print(f"Error: getting application info: {e}", file=sys.stderr)
if hasattr(e, 'response') and e.response is not None:
print(f"Response: {e.response.text}", file=sys.stderr)
return {}, e
if __name__ == "__main__":
# 验证必要参数
if not app_id:
print("ERROR: APP_ID 环境变量未设置", file=sys.stderr)
exit(1)
if not app_secret:
print("ERROR: APP_SECRET 环境变量未设置", file=sys.stderr)
exit(1)
# 获取 tenant_access_token
tenant_access_token, err = get_tenant_access_token(app_id, app_secret)
if err:
print(f"Error: getting tenant_access_token: {err}", file=sys.stderr)
exit(1)
print("成功获取 tenant_access_token")
# 停用应用(使用当前应用的app_id作为目标)
success, err = disable_application(tenant_access_token, app_id)
if err:
print(f"Error: disabling application: {err}", file=sys.stderr)
exit(1)
# 验证停用结果
app_info, err = get_application_info(tenant_access_token, app_id)
if err:
print(f"Warning: could not verify application status: {err}", file=sys.stderr)
exit(0) # 停用操作已成功,验证失败不影响主要功能
print("应用停用流程完成")附录四:常见问题解答 (FAQ)
Q:在安装 openclaw 或访问 GitHub 过程中,终端抛出类似如下错误:
# npm error code 128
# npm error An unknown git error occurred
# npm error command git --no-replace-objects ls-remote ssh://git@github.com/whiskeysockets/libsignal-node.git
# npm error Connection closed by 127.0.0.1 port 7897
# npm error fatal: Could not read from remote repository.
# npm error Please make sure you have the correct access rights and the repository exists.A:这是因为 openclaw 的部分三方依赖(如 libsignal-node)托管在 GitHub 仓库中,且配置为通过 SSH 协议进行访问。如果你的服务器未配置 GitHub 的 SSH 密钥,或者 SSH 代理连接中断,则会导致权限验证失败。
解决方案一:Git 协议替换(推荐)
在终端执行以下指令,强制 Git 使用 HTTPS 协议代替 SSH 协议访问 GitHub。这种方式通常不需要配置任何密钥,能解决大部分环境下的权限问题:
git config --global url."https://github.com/".insteadOf "ssh://git@github.com/"解决方案二:手动配置 SSH 密钥
如果方案一无效,请按照以下步骤为你的服务器配置 GitHub SSH 密钥:
生成 SSH 密钥(如果已有密钥可跳过此步): 在终端执行以下指令,并将邮箱替换为你自己的 GitHub 邮箱;
ssh-keygen -t ed25519 -C "你的邮箱@example.com"
提示:一路回车即可,无需设置密码。
获取公钥内容: 执行以下指令查看并复制输出的内容;
cat ~/.ssh/id_ed25519.pub添加到 GitHub: 复制上述以
ssh-ed25519开头的整行内容,登录 GitHub,进入 SSH and GPG keys 页面,点击 New SSH key,将内容粘贴进去并保存;验证连接: 执行以下指令,若看到
Hi [你的用户名]! You've successfully authenticated则表示配置成功。
ssh -T git@github.comQ:在与机器人对话时,提示需要“授权访问联系人通讯录”权限,且提供的链接无法直接点击跳转,该怎么办?
A:这是由于飞书对包含特定域名的链接识别存在 Bug,导致链接参数被截断。即使你已经按照文档配置了权限,飞书有时仍会额外请求该权限。
解决方案:
将 3.2 的 App ID 替换到下方模版中的 中文注释 处,复制到浏览器打开。在弹出的 开通权限 页面中,确认当前位于 用户身份权限 user_access_token(1) 选项卡(通常为默认选中),勾选 获取通讯录基本信息 复选框,最后点击弹窗右下方的 确认开通权限 即可:
https://open.feishu.cn/app/你的AppID/auth?q=contact:contact.base:readonlyQ:在终端执行指令时,系统提示 openclaw: command not found 怎么办?
A:这通常是由于当前终端窗口未能正确加载环境变量导致的。你可以按照以下步骤尝试解决:
解决方案一:刷新环境变量
在当前报错的终端中执行以下指令,手动刷新 shell 配置:
source ~/.bashrc执行完上述指令后,再次输入以下指令检查是否生效:
openclaw -v如果依然报错,请尝试关闭当前终端窗口并重新打开一个新的终端。
解决方案二:刷新 nvm
确保你已经完成了 2.4 节(安装 openclaw);
为 nvm 设置默认 Node.js 版本:
nvm alias default 22刷新 nvm 环境:
nvm use default执行完上述指令后,再次输入以下指令检查是否生效:
openclaw -v解决方案三:nvm use 22
执行以下指令将 Node.js 22 加载到当前终端会话中:
nvm use 22执行完上述指令后,再次输入以下指令检查是否生效:
openclaw -v