Linux 环境下 OpenClaw AI 助手部署实战（飞书机器人接入）

前言

最近在折腾云手机项目时，发现了一个宝藏项目 OpenClaw，它能让你在各种 IM 平台上部署自己的 AI 助手。经过几天的实战，成功在 Linux 系统上完成了部署，并接入了飞书企业应用。整个过程踩了不少坑，特此记录分享给大家。

本文适合人群：

想在服务器上部署私有 AI 助手的开发者
需要在企业 IM 中集成 AI 能力的团队
对智能办公自动化感兴趣的极客

技术栈：

运行环境：Linux（本文基于云手机 Linux 系统测试）
AI 模型：Moonshot Kimi（国内可用，无需魔法上网）
即时通讯：飞书企业自建应用
核心工具：OpenClaw 2026.2.9

一、环境准备与依赖安装

1.1 系统环境说明

我的测试环境是云手机上的 Linux 系统，理论上任何 Linux 发行版都可以，包括 Ubuntu、CentOS、Debian 等。唯一的硬性要求是 Node.js 版本必须 ≥ 22.0。

1.2 安装 Node.js 22

这里有个坑：很多 Linux 系统自带的 Node.js 版本都比较老，直接用 apt 装的可能只有 12.x 或 14.x，完全不够用。

正确姿势是使用 NodeSource 官方源：

bash 复制代码

# 添加 NodeSource 22.x 仓库
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -

# 安装 Node.js 和 npm
sudo apt-get install -y nodejs

# 更新包索引（可选但推荐）
sudo apt update
sudo apt install -y nodejs npm

# 验证版本（重要！）
node --version  # 应该显示 v22.x.x
npm --version   # 应该显示 9.x.x 或更高

# 升级 npm 到最新版
npm install -g npm@11.9.0

踩坑提示： 如果之前装过旧版本 Node.js，建议先卸载干净再装，避免版本冲突。

二、获取 Kimi API 密钥

2.1 为什么选择 Kimi

市面上的 AI 服务商很多，但考虑到：

OpenAI 需要魔法上网 + 信用卡
Claude API 国内访问不稳定
国产大模型中 Kimi 的代码能力比较强

所以选了 Moonshot 的 Kimi Coding API，国内直连，按量付费，新用户还送体验额度。

2.2 申请步骤

访问 Kimi Code 平台：https://www.kimi.com/code/
注册/登录账号（支持手机号）
进入控制台，开通付费服务（支持支付宝/微信）
点击"创建 API Key"，记录下生成的密钥

格式示例：

sk-kimi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

⚠️ 安全提醒： API Key 相当于你的账号密码，千万别泄露到 GitHub 或公开渠道！

三、OpenClaw 一键安装

3.1 执行安装脚本

OpenClaw 提供了官方安装脚本，非常方便：

bash 复制代码

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

3.2 交互式配置流程

脚本运行后会进入交互式配置，下面是我的选择路径，供参考：

Step 1: 安全声明确认

复制代码

I understand this is powerful and inherently risky. Continue?
→ 选择 Yes

这一步主要是告诉你 OpenClaw 可以执行文件操作和系统命令，有一定风险。如果是生产环境，务必做好权限控制。

Step 2: 选择配置模式

复制代码

Onboarding mode
→ 选择 QuickStart

QuickStart 模式会自动配置大部分参数，适合新手。如果你是老司机，也可以选 Advanced 逐项配置。

Step 3: 网关默认配置

系统会展示默认的网关配置信息：

复制代码

Gateway port: 18789
Gateway bind: Loopback (127.0.0.1)
Gateway auth: Token (default)
Tailscale exposure: Off

划重点：

端口 18789 是 Web 控制台和 WebSocket 服务
绑定本地回环表示只能本机访问，需要外网访问的话后续要改配置
Token 认证是默认方式，记得保管好生成的 token

Step 4: 选择 AI 模型提供商

复制代码

Model/auth provider
→ 选择 Moonshot AI (Kimi K2.5)

Step 5: 认证方式

复制代码

Moonshot AI (Kimi K2.5) auth method
→ 选择 Kimi Code API key (subscription)

Step 6: 输入 API Key

复制代码

Enter Kimi Coding API key
→ 粘贴你在第二步获取的 API Key
│  sk-kimi-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

粘贴后会自动验证，如果配置成功，会显示：

复制代码

Model configured
Default model set to kimi-coding/k2p5

Step 7: 确认默认模型

复制代码

Default model
→ 选择 Keep current (kimi-coding/k2p5)

k2p5 是 Kimi 的代码增强版本，支持更长的上下文和更好的代码理解能力。

Step 8: 跳过初始 IM 配置

这一步会列出所有支持的即时通讯平台：

复制代码

Channel status
  Telegram: not configured
  WhatsApp: not configured
  Discord: not configured
  Feishu: install plugin to enable
  ...

暂时不用管，后面我们会单独配置飞书。

Step 9: 选择启动方式

复制代码

How do you want to hatch your bot?
→ 选择 Hatch in TUI (recommended)

TUI（Terminal User Interface）是终端界面模式，可以直接在命令行里和 AI 对话，非常适合调试。

Step 10: 安装完成

看到以下信息说明安装成功：

复制代码

openclaw tui - ws://127.0.0.1:18789 - agent main - session main
session agent:main:main
Wake up, my friend!

此时按 Ctrl+C 两次退出 TUI 模式，准备配置飞书接入。

四、飞书机器人接入配置

4.1 安装飞书插件

OpenClaw 采用插件化架构，飞书支持需要额外安装：

bash 复制代码

openclaw plugins install @m1heng-clawd/feishu

安装成功后会显示插件版本信息。

安装成功提示：

复制代码

xxxx@xxxx-alip:~$ openclaw plugins install @m1heng-clawd/feishu

🦞 OpenClaw 2026.2.9 (33c75cb) --- If something's on fire, I can't extinguish it---but I can write a beautiful postmortem.

Downloading @m1heng-clawd/feishu...
Extracting /tmp/openclaw-npm-pack-KqWCiI/m1heng-clawd-feishu-0.1.9.tgz...
WARNING: Plugin "feishu" contains dangerous code patterns: Environment variable access combined with network send --- possible credential harvesting (/tmp/openclaw-plugin-7ubCNF/extract/package/src/media.ts:484)
Installing to /home/linaro/.openclaw/extensions/feishu...
Installing plugin dependencies...
Config warnings:
- plugins.entries.feishu: plugin feishu: duplicate plugin id detected; later plugin may be overridden (/home/linaro/.nvm/versions/node/v22.22.0/lib/node_modules/openclaw/extensions/feishu/index.ts)
Installed plugin: feishu
Restart the gateway to load plugins.

4.2 创建飞书企业自建应用

4.2.1 进入开发者后台

浏览器访问：https://open.feishu.cn/
使用企业管理员账号登录
点击"创建企业自建应用"

4.2.2 填写应用基本信息

应用名称： 比如 "智能助理" / "clawbot" / "办公小助手"
应用描述： 简单介绍功能，比如 "基于 AI 的智能问答和任务处理机器人"
应用图标： 上传一个 Logo（可选）

点击"创建"后会自动跳转到应用详情页。

4.2.3 获取应用凭证

在应用详情页左侧菜单点击"凭证与基础信息"，会看到两个关键信息：

复制代码

App ID: cli_xxxxxxxxxxxx
App Secret: xxxxxxxxxxxxxxxxxxxx

复制这两个值，后面要用。

4.3 配置 OpenClaw 飞书频道

回到 Linux 终端，执行以下命令：

bash 复制代码

# 设置 App ID
openclaw config set channels.feishu.appId "cli_xxxxxxxxxxxx"

# 设置 App Secret
openclaw config set channels.feishu.appSecret "xxxxxxxxxxxxxxxxxxxx"

# 启用飞书频道
openclaw config set channels.feishu.enabled true

**注意替换成你自己的凭证！

4.4 重启网关服务

配置修改后需要重启才能生效：

bash 复制代码

openclaw gateway restart

如果一切正常，会显示：

复制代码

Gateway restarted successfully

4.5 飞书应用权限配置

这一步是关键，很多人卡在这里。必须开通以下权限，否则机器人无法正常工作。

4.5.1 添加应用权限

返回飞书开发者后台，点击"权限管理" → "添加权限"，勾选以下项：

权限	权限 ID	用途说明
获取与发送单聊、群组消息	im:message	核心消息功能
接收群聊中@机器人消息事件	im:message.group_at_msg:readonly	群聊响应
读取用户发给机器人的单聊消息	im:message.p2p_msg:readonly	私聊响应
以应用的身份发消息	im:message:send_as_bot	主动发送消息
获取与上传图片或文件资源	im:resource	图片和文件处理
获取通讯录基本信息	contact:contact.base:readonly	识别用户身份
获取用户基本信息	contact:user.base:readonly	用户信息查询

全部勾选后点击"申请权限"。

⚠️ 常见错误： 少开一个权限都会导致某些功能不可用，建议全开。

4.5.2 配置事件订阅（核心步骤！）

点击左侧"事件与回调"菜单，分两步配置：

第一步：设置回调方式

复制代码

回调配置 → 订阅方式 → 选择"长连接" → 保存

第二步：设置事件推送

复制代码

事件配置 → 订阅方式 → 选择"长连接" → 保存

⚠️ 重点提醒： 必须选"长连接"！如果选了 HTTP 回调，需要公网 IP 和域名，云手机环境很难搞定。

第三步：添加事件订阅

点击"添加事件"，搜索并添加以下 4 个事件：

事件	事件 ID	说明
机器人进群	im.chat.member.bot.added_v1	检测被拉进群聊
机器人被移出群	im.chat.member.bot.deleted_v1	检测被移出群聊
消息已读	im.message.message_read_v1	已读状态同步
接收消息	im.message.receive_v1	接收用户消息（最重要！）

4.6 发布应用版本

最后一步，发布应用：

点击"版本管理与发布"
点击"创建版本"
填写版本号（如 1.0.0）和更新说明
点击"保存并发布"

部分企业需要管理员审核，等待审核通过即可。

五、功能测试与使用

5.1 基础对话测试

打开飞书 APP 或网页版
在搜索框输入你的应用名称（如"clawbot"）
点击进入对话窗口
发送消息：你好，请介绍一下自己

如果机器人能正常回复，说明配置成功！

5.2 实用功能演示

示例 1：代码审查

复制代码

帮我看看这段 Python 代码有没有问题：

def calc_sum(nums):
    total = 0
    for i in range(len(nums)):
        total = total + nums[i]
    return total

AI 会指出代码可以优化为 sum(nums) 或使用列表推导式。

示例 2：文本总结

复制代码

请总结以下会议记录的要点：
[粘贴会议记录内容]

示例 3：多轮对话

复制代码

用户：给我推荐一本适合新手的 Python 书
AI：推荐《Python编程：从入门到实践》...
用户：这本书讲数据分析吗？
AI：[基于上下文继续回答]

OpenClaw 会自动维护会话上下文，支持多轮对话。

六、进阶玩法：自动化任务

6.1 定时任务自动化

OpenClaw 配合 Skills 可以实现很多自动化场景，下面分享几个实用案例。

场景 1：代码仓库监控

需求： 监控 GitLab 仓库，有新的 Merge Request 时自动通知

实现：

bash 复制代码

# 安装 Git 相关插件
openclaw plugins install @openclaw/git-tools

# 在飞书中配置
请帮我监控 GitLab 的 main 分支，
每当有新的 MR 提交时，自动：
1. 检查代码规范
2. 运行单元测试
3. 生成审查报告
4. 发送到"开发组"群聊

场景 2：文档自动归档

需求： 每周五自动整理本周的工作文档

配置：

复制代码

设置每周五下午 5 点：
1. 扫描飞书云文档"工作记录"文件夹
2. 按日期归类本周创建的文档
3. 生成目录索引
4. 移动到"归档/2026年第X周"文件夹
5. 在群里发送归档完成通知

场景 3：智能问答知识库

需求： 基于公司文档建立问答系统

步骤：

上传公司的产品文档、API 文档到飞书云盘
在飞书中对话：

请学习"产品文档"文件夹中的所有内容，
当团队成员在群里提问相关问题时，
自动引用文档内容给出准确答案。
后续有人问"怎么使用 XX 功能"，AI 会自动从文档中提取相关内容回答

场景 4：日报周报自动生成

需求： 根据飞书日历和聊天记录生成工作报告

对话配置：

复制代码

每天下午 6 点自动生成我的工作日报：
1. 从飞书日历提取今天完成的会议和任务
2. 从聊天记录中提取我的工作交流内容
3. 按"完成事项、进行中事项、明日计划"分类
4. 生成 Markdown 格式日报
5. 发送到"工作汇报"群并 @ 我

场景 5：异常告警自动处理

需求： 监控服务器日志，发现异常自动响应

实现思路：

bash 复制代码

# 结合 crontab 和 OpenClaw
# 1. 定时读取日志文件
# 2. 发现 ERROR 关键字时调用 OpenClaw API
# 3. AI 分析日志并给出处理建议
# 4. 严重问题自动发送告警到飞书群

6.2 自定义自动化的万能公式

OpenClaw 的强大之处在于用自然语言描述流程，它会自动理解并执行：

复制代码

模板：
请创建一个自动化任务：
【触发条件】每天/每周/每当XX发生时
【数据来源】从XX获取XX数据
【处理逻辑】按XX规则处理，如果XX则XX
【输出目标】将结果发送到XX，通知XX

实例：

复制代码

请创建一个自动化任务：
每当有人在"Bug 反馈"群里提交新问题时，
从消息中提取问题描述、复现步骤、优先级，
自动创建 Jira Issue，
并回复"已创建 Issue XXX-123，研发同学会尽快处理"。

七、常见问题与解决方案

Q1: 安装时提示 Node.js 版本过低

错误信息：

复制代码

System Node 12.22.12 is below the required Node 22+

解决方案：

卸载旧版本，按本文"第一章"重新安装 Node.js 22：

bash 复制代码

sudo apt remove nodejs npm
curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash -
sudo apt-get install -y nodejs

Q2: 飞书机器人不回复消息

排查步骤：

检查权限是否全部开通（im:message.receive_v1 最容易漏）
确认事件订阅已添加且选择了"长连接"
查看 OpenClaw 日志：

bash 复制代码

openclaw logs --tail 50

重启网关：

bash 复制代码

openclaw gateway restart

Q3: API Key 配置后无法连接

可能原因：

API Key 复制时包含了空格或换行符
Kimi 账户余额不足
网络连接问题

验证方法：

bash 复制代码

# 查看当前配置
openclaw config get providers.moonshot.apiKey

# 重新设置
openclaw config set providers.moonshot.apiKey "sk-kimi-xxx"

Q4: 如何查看和修改配置

查看所有配置：

bash 复制代码

openclaw config

查看特定配置：

bash 复制代码

openclaw config get channels.feishu.appId

修改配置：

bash 复制代码

openclaw config set channels.feishu.enabled true

配置文件位置：

复制代码

~/.openclaw/openclaw.json

Q5: 如何控制服务启停

bash 复制代码

# 查看服务状态
openclaw gateway status

# 启动服务
openclaw gateway start

# 停止服务
openclaw gateway stop

# 重启服务
openclaw gateway restart

# 查看日志
openclaw logs

# 实时查看日志
openclaw logs --follow

Q6: 如何升级 OpenClaw

bash 复制代码

# 拉取最新代码
cd ~/.openclaw
git pull

# 重新安装依赖
npm install

# 重启服务
openclaw gateway restart

八、性能优化与安全建议

8.1 性能优化

调整并发限制

bash 复制代码

# 限制最大并发会话数（默认无限制）
openclaw config set gateway.maxConcurrentSessions 10

配置缓存策略

bash 复制代码

# 启用响应缓存（适合重复性问题多的场景）
openclaw config set cache.enabled true
openclaw config set cache.ttl 3600  # 缓存 1 小时

优化上下文窗口

bash 复制代码

# 设置最大上下文长度（减少 token 消耗）
openclaw config set session.maxMessages 20

8.2 安全加固

1. 启用访问控制

bash 复制代码

# 只允许特定用户使用（白名单模式）
openclaw config set channels.feishu.allowedUsers '["user_id_1", "user_id_2"]'

# 只允许在特定群聊中使用
openclaw config set channels.feishu.allowedGroups '["group_id_1"]'

2. 限制工具权限

bash 复制代码

# 禁用文件系统访问（生产环境推荐）
openclaw config set tools.filesystem.enabled false

# 禁用代码执行
openclaw config set tools.codeExec.enabled false

3. 敏感信息脱敏

bash 复制代码

# 启用日志脱敏
openclaw config set logging.sanitize true

4. 定期审计

bash 复制代码

# 运行安全审计
openclaw security audit --deep

# 自动修复安全问题
openclaw security audit --fix

8.3 备份与恢复

备份配置和会话

bash 复制代码

# 备份配置文件
cp ~/.openclaw/openclaw.json ~/openclaw-backup-$(date +%Y%m%d).json

# 备份会话数据
tar -czf ~/openclaw-sessions-$(date +%Y%m%d).tar.gz ~/.openclaw/agents/main/sessions/

恢复配置

bash 复制代码

# 恢复配置
cp ~/openclaw-backup-20260210.json ~/.openclaw/openclaw.json

# 重启服务
openclaw gateway restart

九、总结与展望

9.1 本文要点回顾

环境准备： Linux 系统 + Node.js 22+
AI 服务： Kimi API（国内可用，按量付费）
核心工具： OpenClaw 开源框架
IM 集成： 飞书企业自建应用（长连接模式）
进阶能力： 自动化任务 + 自然语言编排

9.2 适用场景

🏢 企业办公自动化： 日报周报、会议纪要、文档归档
💻 研发效能提升： 代码审查、Git 监控、CI/CD 集成
📊 数据监控告警： 服务器监控、业务指标预警
🤖 智能客服系统： 基于知识库的自动问答
🎯 个人效率工具： 任务提醒、日程管理、信息聚合

9.3 后续可以探索的方向

多模态能力： 接入图像识别、语音转文字
私有化部署： 使用本地大模型（如 Ollama）替代云端 API
多渠道联动： 同时接入钉钉、企业微信、Slack 等
工作流引擎： 结合 n8n、Zapier 实现更复杂的自动化
数据分析： 接入 BI 工具，生成可视化报表

十、参考资源

OpenClaw 官方文档： https://docs.openclaw.ai/
OpenClaw GitHub： https://github.com/openclaw/openclaw
Kimi API 文档： https://platform.moonshot.cn/docs
飞书开放平台： https://open.feishu.cn/document/
飞书机器人开发指南： https://open.feishu.cn/document/home/develop-a-bot-in-5-minutes/create-an-app
Node.js 官方下载： https://nodejs.org/

写在最后

从尝试到成功部署，前后折腾了两天，主要时间都花在飞书权限配置和事件订阅上。希望这篇教程能帮助到想要部署私有 AI 助手的朋友们少走弯路。

如果你在部署过程中遇到问题，欢迎在评论区留言，我会尽量解答。觉得有用的话，别忘了点赞收藏！

我的部署环境：

系统：Linux (云手机)
OpenClaw 版本：2026.2.9
Node.js 版本：22.22.0
AI 模型：Kimi K2.5 Coding

原创不易，转载请注明出处。

发布时间：2026-02-10# Linux 环境下 OpenClaw AI 助手部署实战（飞书机器人接入）