在 Linux (Debian 13.3.0) 从源码安装 OpenClaw + Feishu Bot

本指南介绍如何在没有预装 Node.js 环境的 Debian/Ubuntu Linux 系统上，从克隆的代码仓库构建并运行 OpenClaw。

前置条件

Debian/Ubuntu 系系统（已在 Debian 13 / amd64 上验证）
可用的 curl 或 wget
已克隆代码仓库（git clone https://github.com/openclaw/openclaw.git）
需要 Node.js 22+（如未安装，参见第 1 步）

第 1 步 — 通过 nvm 安装 Node.js 22

OpenClaw 需要 Node.js 22 或更高版本。在无 root 权限的情况下，最干净的安装方式是使用
nvm（Node 版本管理器），它完全安装在用户主目录中。

# 下载并运行 nvm 安装脚本
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash

# 在当前 Shell 会话中加载 nvm
. ~/.nvm/nvm.sh

# 安装 Node.js 22 (LTS)
nvm install 22

# 验证
node --version   # v22.x.x
npm --version

要让 nvm 在之后每个 Shell 会话中自动生效，在 ~/.bashrc 中添加以下内容
（安装脚本会自动完成这一步）：

export NVM_DIR="$HOME/.nvm"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh"

第 2 步 — 安装 pnpm

OpenClaw 使用 pnpm 作为包管理器。安装 package.json（packageManager 字段）中锁定的版本：

npm install -g pnpm@10.23.0
pnpm --version   # 10.23.0

第 3 步 — 安装项目依赖

在仓库根目录执行：

cd openclaw
pnpm install

这会安装所有工作区依赖（包括 extensions/* 下的扩展插件），并运行 prepare 钩子配置 git hooks。首次运行时需要拉取和构建原生插件（sharp、@lydell/node-pty 等），可能需要几分钟。

安装过程中可能会看到以下警告，属正常现象，不影响构建：

Ignored build scripts: @discordjs/opus, @tloncorp/tlon-skill.
Run "pnpm approve-builds" to pick which dependencies should be allowed to run scripts.

第 4 步 — 构建项目

pnpm build

此命令使用 tsdown 编译 TypeScript、生成 plugin-sdk 类型声明、打包 Web UI 资源，
并将 hook 元数据和 HTML 导出模板复制到 dist/。构建成功时输出类似：

327 files, total: 10.20 MB
Build complete in 17704ms

dist/ 目录现在包含可由 Node.js 直接运行的所有编译产物。

第 5 步 — 验证 CLI

node openclaw.mjs --version
# 2026.3.7

node openclaw.mjs --help

--help 输出正常即表示 CLI 入口 openclaw.mjs 已正确解析到 dist/。

第 6 步 — 运行引导向导

向导引导你完成 gateway 配置、连接 AI 模型凭证，并可选安装 systemd 用户服务以在登录时自动启动。

node openclaw.mjs onboard --install-daemon

向导过程中会提示：

选择 AI 提供商并粘贴 API Key（如 Anthropic、OpenAI、Google Gemini）。
配置 gateway 端口（默认：18789）。
可选安装 systemd 用户级守护进程（--install-daemon 会预先勾选此项）。

第 7 步 — 启动 Gateway

如果跳过了守护进程安装，手动启动 gateway：

node openclaw.mjs gateway --port 18789 --verbose

让它在终端中保持运行（或使用 tmux）。Gateway 现在监听并准备好处理 Agent 请求和频道连接。

第 8 步 — 发送测试消息

在另一个终端中（如需要，先执行 . ~/.nvm/nvm.sh）：

node openclaw.mjs agent --message "Hello, OpenClaw"

Agent 会调用已配置的 AI 提供商，并将回复打印到标准输出。

开发期间使用 `pnpm openclaw`

在修改源码时，可通过 tsx 直接运行 TypeScript，无需重新构建：

pnpm openclaw --version
pnpm openclaw agent --message "Hello"

等效于 node openclaw.mjs，但跳过了构建步骤。

将 `openclaw` 注册为全局 Shell 命令

pnpm build 完成后，将包安装到 nvm 管理的 Node 全局目录：

. ~/.nvm/nvm.sh      # 确保当前会话已加载 nvm
npm install -g .     # 将 openclaw 二进制安装到 nvm 的 bin 目录

然后重新加载 Shell 配置，使 nvm bin 目录进入 PATH：

source ~/.bashrc
openclaw --version   # 2026.3.7

这是一次性操作。此后所有加载 ~/.bashrc 的交互终端都能直接使用 openclaw。

为什么出现 command not found？ nvm 将自身写入 ~/.bashrc，而该文件只在
交互式 Shell 启动时被加载。如果当前终端会话早于 nvm 安装，或处于非交互上下文
（tmux、无登录 Shell 的 SSH），需手动执行 . ~/.nvm/nvm.sh 激活，再执行
source ~/.bashrc 使其完全生效。

常见问题排查

现象	解决方法
`node: command not found`	执行 `. ~/.nvm/nvm.sh` 在当前会话加载 nvm
`pnpm: command not found`	重新 source nvm，再执行 `npm install -g pnpm@10.23.0`
克隆后 `dist/` 缺失	执行 `pnpm install && pnpm build`
构建时原生依赖失败	确保已安装 `python3`、`make` 和 C++ 编译器：`sudo apt install build-essential python3`
Gateway 端口被占用	换端口：`openclaw gateway --port 18790`
`openclaw doctor` 报警告	执行 `openclaw doctor` 并按提示修复

快速安装汇总

# 从新克隆一键安装
. ~/.nvm/nvm.sh                              # 加载 nvm（未安装则先安装）
nvm install 22                               # Node 22+
npm install -g pnpm@10.23.0
pnpm install                                 # 安装依赖
pnpm ui:build                                # 构建 Control UI 资源
pnpm build                                   # 编译 TypeScript -> dist/

# 最小化配置（无需交互向导）
node openclaw.mjs config set gateway.mode local
node openclaw.mjs config set gateway.bind loopback
node openclaw.mjs config set gateway.port 18789
node openclaw.mjs config set gateway.auth.mode token
node openclaw.mjs config set agents.defaults.model google/gemini-2.0-flash

# 启动 gateway（先导出 API Key）
export GEMINI_API_KEY="your-key-here"
node openclaw.mjs gateway run --port 18789 &

# 第一次测试
node openclaw.mjs agent --agent main --message "你好，OpenClaw！"

完整文档：https://docs.openclaw.ai/start/getting-started

第二部分 — 开始使用 OpenClaw

Gateway 运行起来、CLI 配置完成后，下面是一个实用功能导览。前几节不需要任何频道凭证——
Control UI 和 agent 命令在引导完成后即刻可用。

最快的入口：Control UI

内置 Web UI 无需配置任何频道，gateway 启动后即可使用：

openclaw dashboard

默认会在浏览器中打开 http://127.0.0.1:18789/，你可以：

直接在浏览器中与 Agent 对话。
实时观看工具调用事件和推理过程流式输出。
查看会话历史，管理工作区。
通过界面配置频道、技能和 gateway 设置。

若浏览器未自动打开，手动访问 http://127.0.0.1:18789/（远程访问时将 127.0.0.1 替换为 gateway 主机 IP）。

通过 CLI 与 Agent 对话

agent 命令向助手发送单轮消息并打印回复。必须指定会话目标——最简单的方式是 --agent main（默认 Agent）：

# 向默认 Agent 发送消息
openclaw agent --agent main --message "今天是几号？"

# 更高推理预算（off | minimal | low | medium | high）
openclaw agent --agent main --message "分析 gateway 架构" --thinking high

# 列出主目录文件（Agent 会使用内置工具）
openclaw agent --agent main --message "列出我主目录下的文件" --thinking low

# 查询天气（使用 weather 技能，无需 API Key）
openclaw agent --agent main --message "东京现在天气怎么样？"

Agent 可访问的内置工具（文件浏览、网页搜索、Shell 执行、画布、定时任务等）取决于已安装的技能和已授权的执行权限。

注意： 省略 --agent（或 --to / --session-id）会报错：
Pass --to <E.164>, --session-id, or --agent to choose a session。
三者必选其一。

查看运行状态

# Gateway 是否运行？端口是多少？
openclaw gateway status

# 频道是否已连接？
openclaw channels status

# 包含频道探测的完整健康检查
openclaw channels status --probe

# 发现配置问题
openclaw doctor

随时重新运行向导（重新配置）

引导向导可安全地重复运行——它保留现有配置，只更新你修改的部分：

# 完整向导（QuickStart 或 Advanced）
openclaw onboard

# 只重新配置某一节
openclaw configure --section models
openclaw configure --section gateway
openclaw configure --section channels
openclaw configure --section web        # 网页搜索提供商

完全重置（清空所有配置重新引导）：

openclaw onboard --reset

向导路径说明

运行 openclaw onboard 时提供两种路径：

路径	适用场景
QuickStart	使用合理默认值：本地 gateway（18789 端口）、令牌认证、工作区 `~/.openclaw/workspace`、编码工具配置文件、按频道隔离 DM。适合首次安装。
Advanced	完全控制每一步——绑定地址、Tailscale 广域暴露、自定义模型端点、每频道策略等。

向导按顺序经过以下节：

模型 / 认证 — 选择提供商（Anthropic、OpenAI、Gemini 或自定义兼容端点），通过 API Key 或 OAuth 认证。
工作区 — Agent 读写文件的位置（默认：~/.openclaw/workspace）。
Gateway — 端口、绑定地址、认证令牌、可选 Tailscale 广域暴露。
频道 — 连接 WhatsApp、Telegram、Discord、Slack、Google Chat、Signal、BlueBubbles、iMessage 等，每个频道有独立的凭证配置流程。
守护进程 — 安装 systemd 用户服务，重启后自动启动 gateway。
健康检查 — 确认 gateway 启动成功。
技能 — 安装推荐工具包（网页搜索、编码工具、记忆等）。

添加第二个 Agent（多 Agent 路由）

OpenClaw 支持多个隔离的 Agent，每个 Agent 拥有独立的工作区、模型和频道路由：

# 创建名为 "research" 的新 Agent
openclaw agents add research

# 列出所有已配置的 Agent
openclaw agents list

# 将特定 Telegram 对话路由到 "research" Agent
openclaw config set agents.research.channels.telegram.allowFrom "@myhandle"

管理技能

技能扩展 Agent 的能力（网页浏览、记忆、代码执行等）：

# 列出已安装技能及状态
openclaw skills list

# 按名称安装技能
openclaw skills install web-search

# 查看技能详情
openclaw skills show web-search

向已连接的频道发送消息

配置好频道（如 Telegram 或 WhatsApp）后，可以从 CLI 主动推送消息：

# 通过 Telegram 发送（从 `openclaw directory self` 获取联系人 ID）
openclaw message send --target @username --message "来自 CLI 的问候"

# 通过 WhatsApp 发送（E.164 格式电话号码）
openclaw message send --target +15555550123 --message "测试"

查询自己的频道 ID：

openclaw directory self

审批配对请求

默认情况下，未知发件人会收到配对码，在审批前不会被处理。
列出待审批配对码并批准（必须指定频道）：

openclaw pairing list telegram
openclaw pairing approve telegram <配对码>

日常常用命令速查

目标	命令
查看版本	`openclaw --version`
前台启动 gateway	`openclaw gateway --port 18789 --verbose`
打开 Control UI	`openclaw dashboard`
单轮 Agent 对话	`openclaw agent --agent main --message "..."`
健康检查	`openclaw doctor`
频道状态 + 探测	`openclaw channels status --probe`
重新配置	`openclaw configure`
查看/编辑配置文件	`openclaw config file`
设置配置项	`openclaw config set <key> <value>`
列出技能	`openclaw skills list`
列出 Agent	`openclaw agents list`
查看 gateway 日志	`openclaw logs`
更新 OpenClaw	`openclaw update`

环境变量覆盖

变量	作用
`GEMINI_API_KEY`	Google Gemini API Key（gateway 和 CLI 自动读取）
`OPENAI_API_KEY`	OpenAI API Key
`ANTHROPIC_API_KEY`	Anthropic API Key
`OPENCLAW_HOME`	覆盖路径解析的根主目录
`OPENCLAW_STATE_DIR`	覆盖状态目录（会话、配对存储）
`OPENCLAW_CONFIG_PATH`	覆盖配置文件路径
`OPENCLAW_SKIP_CHANNELS`	设为 `1` 可在不加载任何频道的情况下启动 gateway（调试用）
`OPENCLAW_NO_RESPAWN`	设为 `1` 跳过自重启包装器（低配主机上加速启动）
`NODE_COMPILE_CACHE`	V8 编译缓存目录路径，加快 CLI 冷启动

不将凭证写入配置文件的最简方式是在 Shell 配置文件中导出，或按需内联传入：

# 写入 ~/.bashrc，所有 Shell 自动继承
export GEMINI_API_KEY="your-key-here"

# 或单次命令内联传入
GEMINI_API_KEY="your-key-here" openclaw agent --agent main --message "你好"

下一步

连接消息频道：频道概览
安装记忆或网页搜索技能：技能
配置 macOS 伴侣应用：macOS
查阅完整引导参考：Onboarding
阅读向导指南：Wizard

第三部分 — 接入飞书/Lark 频道

飞书（Lark）使用官方社区插件，而非内置频道。
本节记录了在本机上验证过的完整安装步骤。

第 1 步 — 安装引导 CLI

飞书提供了一个独立的引导助手 CLI，托管在其 CDN：

npm config set registry https://registry.npmjs.org

curl -o /tmp/feishu-openclaw-plugin-onboard-cli.tgz \
  https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz

npm install /tmp/feishu-openclaw-plugin-onboard-cli.tgz -g
rm /tmp/feishu-openclaw-plugin-onboard-cli.tgz

feishu-plugin-onboard --help   # 验证：显示 install/info/doctor/update 子命令

第 2 步 — 手动安装插件

feishu-plugin-onboard install 向导调用的是不带版本号的
openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin，
截至 2026-03-08 会解析到预发布版（2026.3.8-beta.0），该版本无法通过 OpenClaw 的路径包含检查。
请明确指定最新稳定版本：

openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin@2026.3.7

安装成功后会打印 Installed plugin: feishu-openclaw-plugin，
并列出约 30 个已注册的飞书工具（日历、IM、多维表格、云盘、知识库、电子表格等）。

为什么不用 @beta？ @beta dist-tag 会解析到较旧的 2026.3.4-beta.0，
其 package.json 声明了 "extensions": ["./index.ts"]。
OpenClaw 的路径包含检查会拒绝 .ts 源文件入口——只接受编译后的 .js 入口。
稳定版 2026.3.7 使用 "extensions": ["./index.js"]，可正常工作。

如果插件目录消失： gateway 的进程内重启有时会清理 extensions 目录。
若 ~/.openclaw/extensions/feishu-openclaw-plugin/ 不见了，重新执行上方安装命令即可，
该命令可安全重复执行。

第 3 步 — 配置频道默认值

openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.domain feishu
openclaw config set channels.feishu.connectionMode websocket
openclaw config set channels.feishu.requireMention true
openclaw config set channels.feishu.dmPolicy pairing
openclaw config set channels.feishu.groupPolicy open

第 4 步 — 创建飞书应用并获取凭证

前往 https://open.feishu.cn/app（国际版 Lark 使用
open.larksuite.com/app）。
创建自建应用（或打开已有应用）。
进入凭证与基础信息，复制 App ID（以 cli_ 开头）和 App Secret。

openclaw config set channels.feishu.appId cli_your_app_id_here
openclaw config set channels.feishu.appSecret your_app_secret_here

第 5 步 — 在开发者后台启用长连接

插件使用 WebSocket 长连接模式。未启用此设置时，Bot 能启动但会立即报错且无法接收消息。

在飞书开发者后台（你的应用页面）：

左侧菜单 → 事件与回调
找到订阅方式
选择使用长连接接收事件
保存。

同时添加以下事件订阅，使 Bot 能接收消息：

事件	用途
`im.message.receive_v1`	接收发送给 Bot 的消息
`im.chat.member.bot.added_v1`	Bot 被加入群组
`im.chat.member.bot.deleted_v1`	Bot 被移出群组

并在权限管理中开通以下权限：

权限	用途
`im:message`	读取和发送消息
`im:message.group_at_msg`	在群组中接收 @ 消息
`contact:user.id:readonly`	解析用户信息

第 6 步 — 重启 Gateway 并确认连接

# 终止旧进程后重启
openclaw gateway run --port 18789

确认频道在线：

openclaw channels status --probe
# 预期输出：Feishu default: enabled, configured, running, works

第 7 步 — 审批第一个发件人

由于 dmPolicy 为 pairing，Bot 收到首条私信时会向发件人回复配对码。
审批方式：

openclaw pairing approve feishu <配对码>
# 示例：openclaw pairing approve feishu CEJMLSFZ
# 输出：  Approved feishu sender ou_xxxxxxxxxxxxxxxxxxxxxxxx.

审批后，该发件人的所有后续私信将被路由到 main Agent，并通过飞书回复。

第 8 步 — 显式信任插件

通过将插件加入允许列表，消除启动时关于自动加载未验证插件的警告。
由于 openclaw config set plugins.allow 需要 gateway 正在运行时的插件发现列表进行验证，
最简便的方式是直接编辑 JSON：

python3 -c "
import json
with open('/home/\$USER/.openclaw/openclaw.json') as f: cfg = json.load(f)
cfg.setdefault('plugins', {})['allow'] = ['feishu-openclaw-plugin']
with open('/home/\$USER/.openclaw/openclaw.json', 'w') as f: json.dump(cfg, f, indent=2)
"
openclaw config validate   # 应输出：Config valid

飞书安装汇总

# 1. 安装引导 CLI（一次性）
npm config set registry https://registry.npmjs.org
curl -o /tmp/feishu.tgz https://sf3-cn.feishucdn.com/obj/open-platform-opendoc/4d184b1ba733bae2423a89e196a2ef8f_QATOjKH1WN.tgz
npm install /tmp/feishu.tgz -g && rm /tmp/feishu.tgz

# 2. 安装插件（稳定版，非 @beta）
openclaw plugins install @larksuiteoapi/feishu-openclaw-plugin@2026.3.7

# 3. 配置频道
openclaw config set channels.feishu.enabled true
openclaw config set channels.feishu.domain feishu
openclaw config set channels.feishu.connectionMode websocket
openclaw config set channels.feishu.requireMention true
openclaw config set channels.feishu.dmPolicy pairing
openclaw config set channels.feishu.groupPolicy open
openclaw config set channels.feishu.appId cli_your_app_id
openclaw config set channels.feishu.appSecret your_app_secret

# 4. 在飞书开发者后台启用长连接（手动操作）

# 5. 重启 gateway 并验证
openclaw channels status --probe
# → Feishu default: enabled, configured, running, works

# 6. 审批第一个发件人
openclaw pairing approve feishu <配对码>

飞书频道文档：https://docs.openclaw.ai/channels/feishu

posted @ 2026-03-08 05:19 LexLuc 阅读(208) 评论(0) 收藏举报

刷新页面返回顶部

Lex个人随想乡

Attention before pay attention

在 Linux (Debian 13.3.0) 从源码安装 OpenClaw + Feishu Bot

前置条件

第 1 步 — 通过 nvm 安装 Node.js 22

第 2 步 — 安装 pnpm

第 3 步 — 安装项目依赖

第 4 步 — 构建项目

第 5 步 — 验证 CLI

第 6 步 — 运行引导向导

第 7 步 — 启动 Gateway

第 8 步 — 发送测试消息

开发期间使用 `pnpm openclaw`

将 `openclaw` 注册为全局 Shell 命令

常见问题排查

快速安装汇总

第二部分 — 开始使用 OpenClaw

最快的入口：Control UI

通过 CLI 与 Agent 对话

查看运行状态

随时重新运行向导（重新配置）

向导路径说明

添加第二个 Agent（多 Agent 路由）

管理技能

向已连接的频道发送消息

审批配对请求

日常常用命令速查

环境变量覆盖

下一步

第三部分 — 接入飞书/Lark 频道

第 1 步 — 安装引导 CLI

第 2 步 — 手动安装插件

第 3 步 — 配置频道默认值

第 4 步 — 创建飞书应用并获取凭证

第 5 步 — 在开发者后台启用长连接

第 6 步 — 重启 Gateway 并确认连接

第 7 步 — 审批第一个发件人

第 8 步 — 显式信任插件

飞书安装汇总

Lex个人随想乡

Attention before pay attention

在 Linux (Debian 13.3.0) 从源码安装 OpenClaw + Feishu Bot

前置条件

第 1 步 — 通过 nvm 安装 Node.js 22

第 2 步 — 安装 pnpm

第 3 步 — 安装项目依赖

第 4 步 — 构建项目

第 5 步 — 验证 CLI

第 6 步 — 运行引导向导

第 7 步 — 启动 Gateway

第 8 步 — 发送测试消息

开发期间使用 pnpm openclaw

将 openclaw 注册为全局 Shell 命令

常见问题排查

快速安装汇总

第二部分 — 开始使用 OpenClaw

最快的入口：Control UI

通过 CLI 与 Agent 对话

查看运行状态

随时重新运行向导（重新配置）

向导路径说明

添加第二个 Agent（多 Agent 路由）

管理技能

向已连接的频道发送消息

审批配对请求

日常常用命令速查

环境变量覆盖

下一步

第三部分 — 接入飞书/Lark 频道

第 1 步 — 安装引导 CLI

第 2 步 — 手动安装插件

第 3 步 — 配置频道默认值

第 4 步 — 创建飞书应用并获取凭证

第 5 步 — 在开发者后台启用长连接

第 6 步 — 重启 Gateway 并确认连接

第 7 步 — 审批第一个发件人

第 8 步 — 显式信任插件

飞书安装汇总

开发期间使用 `pnpm openclaw`

将 `openclaw` 注册为全局 Shell 命令