跳到主要内容
OpenClaw Ubuntu 安装与飞书接入教程及问题排查 | 极客日志
Shell / Bash Node.js AI
OpenClaw Ubuntu 安装与飞书接入教程及问题排查 综述由AI生成 介绍在 Ubuntu 系统上从零安装 OpenClaw 并接入飞书（Lark）的完整流程。涵盖环境准备、官方脚本安装、Node 版本选择、后台服务配置及 systemd linger 设置。详细说明了 QuickStart 向导选项、模型 Provider 筛选、MiniMax 认证方式以及 Feishu 插件连接模式。针对常见报错如 Bot 能力未启用、插件信任警告、配置文件路径错误及登出后服务停止等问题提供了解决方案。最后总结了最小可用流程和常用命令速查，帮助用户快速部署并使用 OpenClaw 机器人。
古灵精怪 发布于 2026/3/26 更新于 2026/5/8 面向 Ubuntu 用户，整理从零安装 OpenClaw、完成 QuickStart 向导、接入 Feishu/Lark，以及安装过程中常见报错的含义与解决方法。本文以 Ubuntu 20.04/22.04 这类常见环境为例。OpenClaw 官方当前推荐使用安装脚本；运行时推荐 Node 24，Node 22 LTS（当前要求 22.16+）也仍兼容。
1. 安装前准备
OpenClaw 官方推荐环境是 macOS、Linux 或 Windows（Windows 推荐 WSL2）。在 Linux 上，官方推荐直接用安装脚本，它会自动处理 Node 检测、安装以及 onboarding。Ubuntu 这类 VPS/本地机都适合这个流程。
先更新系统并安装基础工具：
sudo apt update
sudo apt upgrade -y
sudo apt install -y curl git build-essential
如果你想先检查本机 Node 版本，也可以执行：
node --version
npm --version
Node 24 是推荐版本；如果你已自行管理 Node，Node 22.16+ 也可以。
2. 安装 OpenClaw
2.1 推荐安装方式
官方推荐在 Ubuntu 上直接执行：
curl -fsSL https://openclaw.ai/install.sh | bash
这个脚本会自动检测系统、安装或升级 Node、安装 OpenClaw，并在适合的情况下启动 onboarding。官方也明确建议在 VPS/云主机上优先使用干净的 Ubuntu LTS 镜像，而不是第三方一键镜像。
2.2 安装后标准入口
安装完成后，推荐执行：
openclaw onboard --install-daemon
这是官方 Getting Started 里的标准路径：先安装，再运行 onboarding，并安装后台服务。
3. Ubuntu 上的后台运行方式
OpenClaw 在 Linux 上默认使用 systemd user service 。也就是说，它默认不是系统级 service，而是当前用户级别的 service。官方文档说明：如果没有启用 linger，用户退出登录或进入 idle 时，这个 user service 可能会被 systemd 停掉。
如果你希望它在登出后继续运行，执行：
sudo loginctl enable-linger $USER
OpenClaw 的 onboarding 一般会尝试自动帮你做这件事，但如果没有成功，可以手动执行。对长期运行、多人共用或生产环境主机，官方建议考虑 systemd system service。
常用服务命令：
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
4. QuickStart 向导推荐选择
4.1 Onboarding mode 选什么
如果看到：
建议选择 QuickStart 。官方 CLI 文档说明，QuickStart 是最少提示的流程，并会自动生成 gateway token；Manual 则会让你手动配置端口、bind、auth 等完整参数。
4.2 Model provider filter 选什么
如果看到：
All providersopenaiminimaxanthropic…
在首次安装时，建议直接选 All providers ，先把安装走通，再在后续模型选择步骤里决定实际模型。这个筛选仅影响你后面看到的候选模型列表，本身不是一个最终绑定。这个行为来自 onboarding/CLI 的模型配置流程。
4.3 MiniMax 认证方式怎么选 如果你使用的是国际站 MiniMax 账号，看到下面几项时：
MiniMax Global — OAuth (minimax.io)MiniMax Global — API Key (minimax.io)MiniMax CN — OAuth (minimaxi.com)MiniMax CN — API Key (minimaxi.com) 通常优先选 MiniMax Global — OAuth (minimax.io) 。如果你已经持有 Global API Key，也可以用 API Key。CN 选项只适用于中国站账号。这个区分来自 OpenClaw 当前的 MiniMax provider 接入逻辑。
5. Feishu/Lark 接入指南
5.1 Feishu 插件是否要单独安装 当前版本 OpenClaw 文档明确说明：Feishu 已随当前 OpenClaw 版本捆绑提供 ，通常不需要单独安装插件。只有在较旧版本或自定义安装中，才需要手动安装 @openclaw/feishu。
如果向导中出现'Install Feishu plugin?'：
若当前版本自带 Feishu，优先使用内置/默认方案
如果向导只给出一个本地路径，也可以先继续，但之后可能出现非 bundled plugin 的信任警告
5.2 Feishu connection mode 选什么 一般直接使用默认的 WebSocket 。OpenClaw 的 Feishu 接入就是基于 Feishu/Lark 的 WebSocket 事件订阅，因此不需要你暴露公网 webhook。
5.3 Group chat policy 里的 Allowlist 是什么意思
Allowlist - only respond in specific groupsOpen - respond in all groupsDisabled - don't respond in groups 其中 Allowlist 的意思是：机器人只会在你明确列出的群 chat_id 中响应 。这是一种更稳妥的群聊控制策略。官方配置里群聊默认策略与 groupPolicy、groupAllowFrom/允许列表相关。
对初次部署来说，建议先选 Allowlist ，避免机器人误入所有群后到处回应。
5.4 群里为什么不回消息 即使群聊允许，OpenClaw 的群默认往往仍要求 mention 才会回复。也就是说，在群里通常要 @机器人，或者你后续去改 requireMention 一类的设置。
6. Search provider 和 Hooks 建议
6.1 Search provider 是做什么的 这个选项决定 OpenClaw 后续使用哪个 Web 搜索后端。官方文档说明，web_search 可接入 Brave、Gemini、Grok、Kimi、Perplexity 等，但需要对应 provider 的 API key 。如果暂时没有 key，可以先跳过，后面用 openclaw configure --section web 再补。
有 Brave API Key：可选 Brave Search
没有任何搜索 API Key：直接 Skip for now
6.2 Hooks 要不要开启
boot-mdbootstrap-extra-filescommand-loggersession-memory 官方文档里，session-memory 会在你执行 /new 时把会话上下文保存到工作区记忆目录；command-logger 会记录命令日志；boot-md 会在 Gateway 启动时运行 BOOT.md；bootstrap-extra-files 用于额外注入 bootstrap 文件。
最稳妥：只开 session-memory
或者更简化：全部跳过，后续再启用
7. Feishu 机器人创建后，如何给它发消息 OpenClaw 官方 Feishu 测试流程很直接：
启动 Gateway
在 Feishu 中找到你的 bot
给它发消息
如果启用了默认 DM pairing，会先收到 pairing code
在 Ubuntu 终端执行批准命令
批准后即可正常聊天
然后在 Feishu 中给 bot 发一条私聊消息，例如：
8. 第一次发消息时出现 pairing code，是什么意思 OpenClaw: access not configured. Your Feishu user id: ... Pairing code: 8 VRYD6XX Ask the bot owner to approve with : openclaw pairing approve feishu 8 VRYD6XX
这不是报错，而是 OpenClaw 的 DM pairing 安全机制。官方说明，pairing 是显式批准谁可以和机器人聊天的步骤；未知发送者默认会收到一次性 pairing code。
openclaw pairing approve feishu 2VRYD4WW
9. 安装过程中常见问题与解决方法
9.1 API error: app do not have bot Connection failed: API error : app do not have bot
这通常表示你在 Feishu 开发者后台创建了应用，但没有给应用启用 Bot 能力 。Feishu 官方文档说明，要让应用收发消息，必须先在开发者后台给它添加 Bot capability。
打开 Feishu Developer Console
进入你的应用
点击 Add Features / Add Application Capabilities
添加 Bot
保存并重新测试
9.2 plugins.allow is empty; discovered non-bundled plugins may auto-load [plugins] plugins.allow is empty
这不是崩溃，而是 安全警告 。OpenClaw 官方插件文档说明：原生插件与 Gateway 同进程运行，不是沙箱隔离；对于非 bundled plugin，建议使用 allowlist 和显式加载路径。plugins.allow 信任的是插件 ID。
如果你确实在用本地 Feishu 插件路径，就在配置里显式加上 allow：
{
"plugins" : {
"allow" : [ "feishu" ] ,
"load" : {
"paths" : [ "/home/jinghu/.npm-global/lib/node_modules/openclaw/extensions/feishu" ]
} ,
"entries" : {
"feishu" : { "enabled" : true }
}
}
}
9.3 配置文件在哪，不是 config.yaml 吗 ~/.openclaw/openclaw.json
并且格式是 JSON5 。官方配置文档明确写的是这个路径。
如果你之前编辑了 ~/.openclaw/config.yaml，很可能 OpenClaw 根本没在读取它。
9.4 我输入 ~/.openclaw/openclaw.json 后提示 Permission denied 这是因为你把配置文件当命令执行了。正确方式是'打开它'，不是'运行它'。
~/.openclaw/openclaw.json
sudo ~/.openclaw/openclaw.json
nano ~/.openclaw/openclaw.json
cat ~/.openclaw/openclaw.json
less ~/.openclaw/openclaw.json
配置文件的正确用法来自 OpenClaw 当前配置文档。
9.5 用 nano 编辑后，怎么保存 cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak
9.6 改完配置后要不要重启 官方文档说明，OpenClaw 会监听 ~/.openclaw/openclaw.json，大多数设置会自动热更新 ；但像 gateway.* 这类关键服务端设置需要重启。
9.7 登出后 OpenClaw 不运行了 这通常是 Linux 的 systemd user service 在登出后被停掉。官方给出的标准修复方式是启用 linger：
sudo loginctl enable-linger $USER
9.8 群聊中机器人不回复
你是否把群聊策略设成了 Allowlist
当前群的 chat_id 是否真的在 allowlist 里
你是否在群里 @机器人
OpenClaw 的默认群聊访问控制与 mention 规则都可能导致'看起来在线但不回话'。
10. 推荐的最小可用流程 如果你只想最快跑通 Ubuntu + Feishu，可以按下面走：
第一步：安装 sudo apt update
sudo apt install -y curl git build-essential
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
第二步：向导里这样选
Onboarding mode：QuickStart
模型 provider filter：All providers
Feishu：按向导接入
Group chat policy：先选 Allowlist
Search provider：没有 API key 就 Skip for now
Hooks：建议只开 session-memory，或者全跳过
第三步：Feishu 开发者后台
创建应用
启用 Bot 能力
填好 App ID / App Secret
回到 OpenClaw 完成配置
第四步：首次发消息并 approve pairing 在 Feishu 里私聊 bot，拿到 pairing code 后执行：
openclaw pairing approve feishu <CODE>
第五步：如果出现插件信任告警 nano ~/.openclaw/openclaw.json
{
"plugins" : {
"allow" : [ "feishu" ] ,
"load" : {
"paths" : [ "/home/jinghu/.npm-global/lib/node_modules/openclaw/extensions/feishu" ]
} ,
"entries" : {
"feishu" : { "enabled" : true }
}
}
}
依据 OpenClaw 官方插件安全模型，这一步的作用是显式信任本地 Feishu 插件。
11. 常用命令速查
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw gateway
openclaw gateway restart
openclaw gateway stop
openclaw dashboard
openclaw doctor
openclaw health
openclaw status --deep
openclaw logs
openclaw logs --follow
openclaw configure --section web
openclaw pairing approve feishu <CODE>
这些命令都来自当前官方 Getting Started、Gateway、Web Tools 与 Feishu 文档。
12. 结语
用官方安装脚本安装
用 openclaw onboard --install-daemon 完成首次配置
在 Linux 上确认 systemd user service 与 linger
接入 Feishu 时先确保 Feishu 应用已启用 Bot
首次私聊后完成 pairing
若使用本地插件路径，再补上 plugins.allow 明确信任。
相关免费在线工具 RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
随机西班牙地址生成器 随机生成西班牙地址（支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选），支持数量快捷选择、显示全部与下载。 在线工具，随机西班牙地址生成器在线工具，online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
Markdown转HTML 将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
