#OpenClaw-Ubuntu-飞书小龙虾安装与问题排查教程

Im静湖

990人浏览 · 2026-03-18 23:50:16

Im静湖 · 2026-03-18 23:50:16 发布

面向 Ubuntu 用户，整理从零安装 OpenClaw、完成 QuickStart 向导、接入 Feishu/Lark，以及安装过程中常见报错的含义与解决方法。本文以 Ubuntu 20.04/22.04 这类常见环境为例。OpenClaw 官方当前推荐使用安装脚本；运行时推荐 Node 24，Node 22 LTS（当前要求 22.16+）也仍兼容。(docs.openclaw.ai)

1. 安装前准备

OpenClaw 官方推荐环境是 macOS、Linux 或 Windows（Windows 推荐 WSL2）。在 Linux 上，官方推荐直接用安装脚本，它会自动处理 Node 检测、安装以及 onboarding。Ubuntu 这类 VPS/本地机都适合这个流程。(docs.openclaw.ai)

先更新系统并安装基础工具：

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+ 也可以。(docs.openclaw.ai)

2. 安装 OpenClaw

2.1 推荐安装方式

官方推荐在 Ubuntu 上直接执行：

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

这个脚本会自动检测系统、安装或升级 Node、安装 OpenClaw，并在适合的情况下启动 onboarding。官方也明确建议在 VPS/云主机上优先使用干净的 Ubuntu LTS 镜像，而不是第三方一键镜像。(docs.openclaw.ai)

2.2 安装后标准入口

安装完成后，推荐执行：

openclaw onboard --install-daemon

这是官方 Getting Started 里的标准路径：先安装，再运行 onboarding，并安装后台服务。(docs.openclaw.ai)

3. Ubuntu 上的后台运行方式

OpenClaw 在 Linux 上默认使用 systemd user service。也就是说，它默认不是系统级 service，而是当前用户级别的 service。官方文档说明：如果没有启用 linger，用户退出登录或进入 idle 时，这个 user service 可能会被 systemd 停掉。(docs.openclaw.ai)

如果你希望它在登出后继续运行，执行：

sudo loginctl enable-linger $USER

OpenClaw 的 onboarding 一般会尝试自动帮你做这件事，但如果没有成功，可以手动执行。对长期运行、多人共用或生产环境主机，官方建议考虑 systemd system service。(docs.openclaw.ai)

常用服务命令：

openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop

(docs.openclaw.ai)

4. QuickStart 向导推荐选择

4.1 Onboarding mode 选什么

如果看到：

QuickStart
Manual

建议选择 QuickStart。官方 CLI 文档说明，QuickStart 是最少提示的流程，并会自动生成 gateway token；Manual 则会让你手动配置端口、bind、auth 等完整参数。(docs.openclaw.ai)

4.2 Model provider filter 选什么

如果看到：

All providers
openai
minimax
anthropic
…

在首次安装时，建议直接选 All providers，先把安装走通，再在后续模型选择步骤里决定实际模型。这个筛选仅影响你后面看到的候选模型列表，本身不是一个最终绑定。这个行为来自 onboarding/CLI 的模型配置流程。(docs.openclaw.ai)

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 接入逻辑。(docs.openclaw.ai)

5. Feishu/Lark 接入指南 (OpenClaw 飞书官方插件使用指南（公开版）)

5.1 Feishu 插件是否要单独安装

当前版本 OpenClaw 文档明确说明：Feishu 已随当前 OpenClaw 版本捆绑提供，通常不需要单独安装插件。只有在较旧版本或自定义安装中，才需要手动安装 @openclaw/feishu。(docs.openclaw.ai)

如果向导中出现“Install Feishu plugin?”：

若当前版本自带 Feishu，优先使用内置/默认方案
如果向导只给出一个本地路径，也可以先继续，但之后可能出现非 bundled plugin 的信任警告

5.2 Feishu connection mode 选什么

一般直接使用默认的 WebSocket。OpenClaw 的 Feishu 接入就是基于 Feishu/Lark 的 WebSocket 事件订阅，因此不需要你暴露公网 webhook。(docs.openclaw.ai)

5.3 Group chat policy 里的 Allowlist 是什么意思

如果看到：

Allowlist - only respond in specific groups
Open - respond in all groups
Disabled - don't respond in groups

其中 Allowlist 的意思是：机器人只会在你明确列出的群 chat_id 中响应。这是一种更稳妥的群聊控制策略。官方配置里群聊默认策略与 groupPolicy、groupAllowFrom/允许列表相关。(docs.openclaw.ai)

对初次部署来说，建议先选 Allowlist，避免机器人误入所有群后到处回应。

5.4 群里为什么不回消息

即使群聊允许，OpenClaw 的群默认往往仍要求 mention 才会回复。也就是说，在群里通常要 @机器人，或者你后续去改 requireMention 一类的设置。(docs.openclaw.ai)

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 再补。(docs.openclaw.ai)

如果只是想先把系统装起来：

有 Brave API Key：可选 Brave Search
没有任何搜索 API Key：直接 Skip for now

6.2 Hooks 要不要开启

如果看到这些可选 hook：

boot-md
bootstrap-extra-files
command-logger
session-memory

官方文档里，session-memory 会在你执行 /new 时把会话上下文保存到工作区记忆目录；command-logger 会记录命令日志；boot-md 会在 Gateway 启动时运行 BOOT.md；bootstrap-extra-files 用于额外注入 bootstrap 文件。(docs.openclaw.ai)

首次安装建议：

最稳妥：只开 session-memory
或者更简化：全部跳过，后续再启用

7. Feishu 机器人创建后，如何给它发消息

OpenClaw 官方 Feishu 测试流程很直接：

启动 Gateway
在 Feishu 中找到你的 bot
给它发消息
如果启用了默认 DM pairing，会先收到 pairing code
在 Ubuntu 终端执行批准命令
批准后即可正常聊天 (docs.openclaw.ai)

先启动：

openclaw gateway

然后在 Feishu 中给 bot 发一条私聊消息，例如：

Hello

8. 第一次发消息时出现 pairing code，是什么意思

如果机器人回你类似下面的内容：

OpenClaw: access not configured.
Your Feishu user id: ...
Pairing code: 8VRYD6XX
Ask the bot owner to approve with:
openclaw pairing approve feishu 8VRYD6XX

这不是报错，而是 OpenClaw 的 DM pairing 安全机制。官方说明，pairing 是显式批准谁可以和机器人聊天的步骤；未知发送者默认会收到一次性 pairing code。(docs.openclaw.ai)

你只需要回到 Ubuntu 终端执行：

openclaw pairing approve feishu 2VRYD4WW

配对码默认 1 小时过期。(docs.openclaw.ai)

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 Open Platform)

解决方法：

打开 Feishu Developer Console
进入你的应用
点击 Add Features / Add Application Capabilities
添加 Bot
保存并重新测试 (Feishu Open Platform)

9.2 `plugins.allow is empty; discovered non-bundled plugins may auto-load`

警告示例：

[plugins] plugins.allow is empty; discovered non-bundled plugins may auto-load: feishu (...)

这不是崩溃，而是 安全警告。OpenClaw 官方插件文档说明：原生插件与 Gateway 同进程运行，不是沙箱隔离；对于非 bundled plugin，建议使用 allowlist 和显式加载路径。plugins.allow 信任的是插件 ID。(docs.openclaw.ai)

如果你确实在用本地 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/openclaw.json

并且格式是 JSON5。官方配置文档明确写的是这个路径。(docs.openclaw.ai)

如果你之前编辑了 ~/.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 当前配置文档。(docs.openclaw.ai)

9.5 用 nano 编辑后，怎么保存

在 nano 里保存文件的按键顺序是：

Ctrl + O
Enter
Ctrl + X

如果你怕改坏，先备份：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak

9.6 改完配置后要不要重启

官方文档说明，OpenClaw 会监听 ~/.openclaw/openclaw.json，大多数设置会自动热更新；但像 gateway.* 这类关键服务端设置需要重启。(docs.openclaw.ai)

在实际使用里，改完关键项后执行一次重启更稳妥：

openclaw gateway restart

9.7 登出后 OpenClaw 不运行了

这通常是 Linux 的 systemd user service 在登出后被停掉。官方给出的标准修复方式是启用 linger：

sudo loginctl enable-linger $USER

(docs.openclaw.ai)

9.8 群聊中机器人不回复

优先检查三件事：

你是否把群聊策略设成了 Allowlist
当前群的 chat_id 是否真的在 allowlist 里
你是否在群里 @机器人

OpenClaw 的默认群聊访问控制与 mention 规则都可能导致“看起来在线但不回话”。(docs.openclaw.ai)

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

(docs.openclaw.ai)

第二步：向导里这样选

Onboarding mode：QuickStart
模型 provider filter：All providers
Feishu：按向导接入
Group chat policy：先选 Allowlist
Search provider：没有 API key 就 Skip for now
Hooks：建议只开 session-memory，或者全跳过 (docs.openclaw.ai)

第三步：Feishu 开发者后台

创建应用
启用 Bot 能力
填好 App ID / App Secret
回到 OpenClaw 完成配置 (Feishu Open Platform)

第四步：首次发消息并 approve pairing

在 Feishu 里私聊 bot，拿到 pairing code 后执行：

openclaw pairing approve feishu <CODE>

(docs.openclaw.ai)

第五步：如果出现插件信任告警

编辑：

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 插件。(docs.openclaw.ai)

11. 常用命令速查

# 安装
curl -fsSL https://openclaw.ai/install.sh | bash

# 启动 onboarding
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

# 配置 web search
openclaw configure --section web

# 批准 Feishu pairing
openclaw pairing approve feishu <CODE>