董云舟花了一个周末，我把 OpenClaw v2026.3.23-2 在 Ubuntu 上完整跑通了，模型侧接的是 Kimi，IM 侧对接的是飞书。这套组合跑起来之后，等于多了一个能 7x24 小时在线对话、能干活、能接技能的智能体。整个过程比预想的要曲折，尤其是在模型配置和飞书事件订阅这两个环节，官方文档写得比较省略。这篇实录把步骤、踩过的坑、以及最后的解决办法全部记下来，给后面要搭同款方案的朋友一份可以直接照着操作的参考。我先把方案选型说清楚，再按时间线走完整流程，最后是问题排查清单。不管你是第一次接触 OpenClaw，还是已经在别的系统上折腾过，应该都能找到对自己有用的部分。
1. 整体设计与选型思路
1.1 为什么把宿主放在 Linux Ubuntu 上
先说结论：OpenClaw 这种面向服务端的智能体框架，Linux 是更舒服的宿主环境。我自己最开始是在 Windows 上尝试的，结果遇到了几个非常典型的报错，比如 oneclaw node runtime not found，还有删除 ~/.openclaw 目录时提示 EBUSY resource busy or locked。这些问题在 Linux 上几乎不会出现。根源在于 OpenClaw 的大量脚本和依赖工具都按照 Unix 路径约定和权限模型来设计，Windows 的文件锁机制、路径分隔符、命令行参数解析都会带来额外麻烦。
换到 Ubuntu 之后，整个安装过程顺畅了一大截。另外还有一个更实际的理由：智能体这个东西，部署完了是要长期在线的。你可能希望它半夜帮你盯消息、定时跑任务、对接工作流，这种场景下，一台云服务器或者老旧的 Linux 小主机比你的个人电脑可靠得多。把 OpenClaw 跑在 Ubuntu 上，再用 systemd 托管，重启机器都能自动拉起，这才是正经的生产级玩法。所以我这次直接选了一台 Ubuntu 22.04 LTS 的服务器，安安静静让它自己跑，不用我操心。
1.2 模型选型与 IM 工具选择逻辑
这次选 Kimi 不是随手定的。OpenClaw 本身是多模型架构，理论上你可以接 OpenAI、Claude、DeepSeek、本地 Ollama 模型等等。但我觉得对大多数中文用户来说，Kimi 是一个很省心的选择：Moonshot 开放平台的 API Key 注册就能拿，计费清晰，中文语境下的理解能力也够强，上下文窗口对长文档和复杂任务比较友好。我还专门对比了一下，它在多轮对话中的稳定性不错，日常作为智能体的“大脑”是够用的。
选飞书也有明确理由。飞书的开放平台提供机器人能力和长连接事件订阅，不需要你有公网 IP 或者独立域名就能把消息推给机器人，这在个人部署场景里实在太重要了。微信个人号接入恰恰相反，第三方协议不稳定，还要面对风控，长期用的体验并不好。飞书作为 IM 工作入口，既适合个人使用，也可以直接放到团队里用，一次配置，大家都能和智能体对话。如果你后面想接钉钉，思路也差不多，OpenClaw 的 channel 机制是通用的，核心逻辑就是同样的配置套路换一个平台参数而已。
对了，如果你用默认配置跑 OpenClaw，第一次启动时它可能自带 DeepSeek 之类的模型预设，没改配置就去启动，你会看到 unknown model: deepseek 这种报错。这个不是部署失败，纯粹是配置没跟上，后面我详细讲怎么改。
需要模型API调用？ 免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。
2. 部署前准备：环境与依赖
2.1 系统与基础依赖安装
这次用的系统是 Ubuntu 22.04 LTS，内存分配了 4G，磁盘 40G。OpenClaw 本身的资源占用不算高，2G 内存也能跑，但考虑到还有 Node.js 进程、Control UI、日志文件，建议至少 2G 起步，4G 会更稳。如果你在云服务器上买的是 1G 内存的小机器，后面跑起来大概率会频繁 OOM，别问我怎么知道的。
先做一轮系统更新，然后安装基础工具：
bash复制sudo apt update && sudo apt upgrade -y
sudo apt install -y git curl build-essential
git 用来拉取项目，curl 用来装 Node.js 版本管理器，build-essential 提供编译工具链。即使 OpenClaw 是纯 JS/TS 项目，某些依赖在安装时也可能需要本地编译，少装 build-essential 可能让你在 npm install 阶段碰到莫名其妙的 gyp 报错。这一步没什么技术含量，但做不做会让后面的体验差很多。
2.2 Node.js 运行时安装与版本选择
OpenClaw 对 Node.js 版本有要求，官方写的是 Node 18+，但我实测下来，Node 20 LTS 是最稳的。原因并不复杂：18 的某些版本对 ES Module 的细节处理和 20 有差异，而 OpenClaw 在新版本里用到的依赖，比如语言模型 SDK、WebSocket 库，都在 20 上才表现得最好。如果你用的是 Node 21 或 22 这类比较新的奇数或偶数版本，也不是不行，但遇到莫名奇妙的兼容性问题时，第一个怀疑对象就应该是它。
推荐用 nvm 安装，这样以后想切版本也方便：
bash复制curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
source ~/.bashrc
nvm install 20
nvm alias default 20
node -v
执行完应该能看到 v20.x.x 的输出。这里有个小经验：安装完 nvm 之后，记得重新加载 shell 配置，或者直接重开一个终端，不然 node 命令找不到，很多人卡在这一步以为是安装失败了，其实就是环境变量没生效。如果你之前已经装过 Node 但版本不对，也不需要重装系统，nvm 可以多版本共存，把 OpenClaw 的服务用 v20 跑起来就行。
2.3 拉取源码与版本锁定
OpenClaw 的项目仓库在 GitHub 上，拉代码很简单：
bash复制git clone https://github.com/<你的仓库地址>/openclaw.git
cd openclaw
git tag
先看 tag 列表，找到 v2026.3.23-2 这个版本，然后切换过去：
bash复制git checkout v2026.3.23-2
为什么要锁定 tag 而不是直接用 main 分支？因为 main 分支是滚动开发的，今天的 main 明天可能就变了一个行为，你按教程配好的配置可能就被新代码破坏了。用发布 tag 部署，能保证你看到的问题、踩到的坑和其他人一致，排查起来也有统一的基准。特别是 OpenClaw 这种迭代非常快的项目，锁定版本几乎是一条铁律。
接下来安装依赖。OpenClaw 内部使用 pnpm 管理依赖，所以先全局装 pnpm：
bash复制npm install -g pnpm
pnpm install
这里要提醒一下：如果网络环境不是很好，pnpm install 可能会比较慢，某些包甚至下载超时。可以给 npm 和 pnpm 配上镜像源，速度会快很多：
bash复制npm config set registry https://registry.npmmirror.com
pnpm config set registry https://registry.npmmirror.com
装完依赖之后，跑一次构建：
bash复制pnpm build
构建过程会把 TypeScript 编译成可执行的 JS，这个过程一般不会有啥意外。构建成功之后再进入下一步，避免后面启动时报一些模块缺失的怪错。
3. 完整部署流程与 Kimi 接入
3.1 初始化配置流程
OpenClaw 提供了一个 onboard 式的初始化命令，在项目根目录执行：
bash复制npx openclaw onboard
这一步会引导你完成初始配置，包括选择模型、填写 API Key、指定数据目录等。它会生成一个默认配置文件，位置在用户主目录下的 .openclaw 目录里：
code复制~/.openclaw/openclaw.json
如果 onboard 过程中你只是随便选的模型，没关系，后面我们可以直接改配置文件。这一步最核心的目标是把配置骨架生成出来，不要卡在选择哪个模型上。有些朋友可能在 onboard 阶段就遇到问题，比如终端提示没有交互窗口、或者命令不存在，先确认一下 npx 是否正常、node 是否在 PATH 里。在 Linux 上，通常你把 nvm 默认版本设置好就不会有这个问题。我在第一次跑的时候，因为之前切换过 Node 版本，npx 缓存了一些旧路径，清一下缓存或者重开终端就正常了。
3.2 Kimi 模型配置与参数详解
打开 ~/.openclaw/openclaw.json，你会看到一份比较长的配置。不要慌，我们只需要关注 model 相关字段。以我用的版本为例，模型配置大致长这样：
json复制{
"model": {
"provider": "kimi",
"name": "kimi-latest",
"baseUrl": "https://api.moonshot.cn/v1",
"apiKey": "sk-你的APIKey"
}
}
provider 要填 kimi，name 填你在 Moonshot 平台开通的具体模型名，一般是 kimi-latest 或者 moonshot-v1-128k 这类。baseUrl 是 Kimi 开放平台的标准 API 地址，apiKey 去 platform.moonshot.cn 注册后创建即可。这里有几个容易踩的坑：
第一，默认配置文件里可能自带了 deepseek 或者 openai 的模型预设，如果你只改了 provider 没改 name，启动时就会报 unknown model。我后来仔细看了一下日志，发现它会在启动阶段调用一次模型接口来校验配置，模型名对不上直接失败，而不会等到你发消息才报错。所以你在改配置的时候，provider 和 name 要一起改，不要漏掉任何一个。
第二，baseUrl 别加多余的路径。有的人会把 /chat/completions 这种接口路径也拼上去，这是不对的。OpenClaw 会自己拼接完整接口地址，你只需要给到域名加 /v1 这一层。
第三，API Key 不要直接写死在代码里或者提交到 Git 仓库。配置好之后，建议把 .openclaw 目录加入忽略列表，或者至少不要把自己的整个配置目录推到公共仓库。配置改完之后，可以先跑一个快速验证命令，确认模型调用通不通：
bash复制npx openclaw test model
如果输出正常，说明模型侧已经就绪，后面飞书对接时如果出问题，至少可以排除模型因素。
3.3 启动服务与 Control UI 验证
模型配置好之后，启动 OpenClaw：
bash复制npx openclaw start
首次启动会加载配置、建立模型连接、启动 Control UI。Control UI 是 OpenClaw 自带的一个 Web 管理界面，默认监听在 8080 端口，具体端口看你的配置，你可以直接用浏览器访问 http://服务器IP:8080 查看运行状态、日志和技能管理。如果访问不到 Control UI，第一件事检查进程是否真的起来了，看日志里有没有 control ui 相关的输出。第二件事检查端口：
bash复制netstat -tlnp | grep 8080
看端口有没有被监听。很多时候是端口被别的应用占了，比如你自己跑的 Nginx 或者别的开发服务器，这种直接把 OpenClaw 的端口改掉就行。启动日志里如果看到类似 control ui did not start 的字样，大概率是端口占用或者 Node 版本不对，把 Node 切到 20 再重启一轮，基本都能解决。这一步通过之后，整个核心引擎就是活的了，接下来就是让飞书和它连起来。
4. 对接飞书：完整配置实录
4.1 飞书开放平台应用创建
飞书对接是整个方案里最需要耐心的一步，因为它的配置牵扯两个系统：飞书开放平台和 OpenClaw 本地配置。先说飞书开放平台要做的事。打开飞书开放平台，创建一个企业自建应用。注意是“企业自建应用”，不是商店应用。创建应用的关键信息包括名称、描述这些，随便填一个能认出来的名字就行，比如“我的智能助手”。
创建完之后，在应用功能里启用“机器人”能力。这一步做完，你的应用就已经具备机器人身份了。然后到“凭证与基础信息”页面，找到 App ID 和 App Secret，这两个值后面要填到 OpenClaw 里。App Secret 只在创建时显示一次，如果忘了就只能重置，重置之后旧的 Secret 会立即失效，所以拿到手就存好。我有一次就是没存，后来重新生成了一版，结果配置文件里忘了同步，排查半天才发现是旧 Secret 失效导致的鉴权失败。
4.2 事件订阅与权限配置
飞书机器人要接收用户消息，必须配置事件订阅。在事件订阅页面，注意不要选“将事件发送至开发者服务器”这种需要公网回调地址的模式，选“使用长连接接收事件”。长连接模式是飞书提供的 WebSocket 通道，机器人主动和飞书服务器建连，不需要你有公网 IP，非常适合本地部署和云服务器上不想暴露端口的情况。
事件订阅这里需要添加事件：接收消息 im.message.receive_v1。这个事件负责把用户发给机器人的消息推给你的智能体。不订阅这个事件，飞书机器人就是个哑巴，你发消息它完全没反应。然后是权限管理。飞书机器人的权限体系比较细，建议开通这几个：
im:message：读取消息im:message:send_as_bot：以机器人身份发消息im:chat：读取群信息
如果后面你要让机器人在群里 @ 响应，还要再加群消息相关权限。注意：权限配置完要重新发布版本才会生效。我在第一次配置完之后，权限加了一堆，结果没有发布版本，机器人收不到任何事件，折腾了好久才发现是这个原因。
4.3 OpenClaw 侧飞书配置与联调
回到 OpenClaw 的配置文件，把飞书通道打开。在 openclaw.json 里找到 channels 相关配置，加一段：
json复制{
"channels": {
"feishu": {
"enabled": true,
"appId": "cli_xxxxxxxx",
"appSecret": "你的AppSecret",
"mode": "websocket"
}
}
}
appId 填飞书应用的 App ID，appSecret 填对应的 Secret，mode 固定为 websocket，对应飞书的长连接模式。配置完保存，重启 OpenClaw：
bash复制npx openclaw restart
然后盯日志。如果飞书连接建立成功，日志里会出现 feishu channel connected 或者类似的输出，同时飞书开放平台上的应用事件订阅状态也会显示“长连接已连接”。这个时候去飞书里找到你的机器人，发一条消息，智能体应该会在几秒内回复你。
这里有一个联调时非常容易踩的坑：如果应用创建之后没有发布版本，机器人虽然有，但外部账号（包括你自己）发消息时，事件根本推不过来。所以一定要去“版本管理与发布”里创建一个版本并发布。企业自建应用的发布，如果审批人是你自己的企业管理员，通常很快就能通过，甚至可以直接通过。我建议你在配置权限和事件订阅之后，第一时间发布版本，再回来测试，这样可以避免白等一轮。
5. 常见问题与排查技巧实录
5.1 部署期高频报错速查表
我在部署和给朋友帮忙的过程中，汇总了这几个最高频的问题，做成表格方便你快速对照：
| 报错/现象 | 可能原因 | 排查与解决 |
|---|---|---|
| oneclaw node runtime not found | Node 不在 PATH 或版本不匹配 | 确认 nvm 默认版本是 20，重开终端再试 |
failed to remove ~\.openclaw: ebusy |
文件被占用（常见于 Windows） | 关闭占用进程或切到 Linux 环境删除 |
| unknown model: deepseek | 默认模型配置没改成 Kimi | 修改 openclaw.json 中的 provider/name |
| control ui did not start | 端口占用或 Node 版本问题 | 查端口占用，切换 Node 20 重启 |
| pnpm install 报网络错误 | 网络环境差 | 配置 npm 镜像源后重试 |
| 启动后进程闪退 | 配置 JSON 格式错误 | 用 node -e "JSON.parse(...)" 校验配置文件 |
这些报错里，绝大多数都不是 OpenClaw 本身的 bug，而是环境差异和配置没对齐。如果你遇到表里没有的错误，建议先看日志里的堆栈信息，OpenClaw 的日志一般会打印得很详细，定位到具体模块之后再去查，比瞎猜高效得多。
5.2 模型调用异常的隐蔽原因
模型配置看起来简单，但调用异常的隐蔽原因不少。最常见的是 API Key 过期或额度不够。Kimi 平台新用户一般有免费额度，但用完就需要充值，余额不足时接口会返回错误，OpenClaw 日志里会有 401 或 402 之类的 HTTP 状态码。遇到这种问题，先去 Moonshot 平台看一下余额和 Key 状态，别在配置里瞎折腾。
还有一个隐蔽点是模型上下文长度设置。如果你在 OpenClaw 里把 maxTokens 或上下文窗口配置得过大，超过了模型上限，调用时也可能报错。Kimi 的模型有不同的上下文规格，比如 32k、128k 版本，你配置的 maxTokens 要跟所选模型匹配，不能凭感觉填一个很大的数。我一开始图省事，把上下文窗口拉满，结果每次请求都超时，后来才发现是模型规格根本不支持那么大。
5.3 飞书通道问题排查顺序
飞书消息不回复，是大家最容易卡壳的地方。按照这个顺序排查，基本几十秒就能定位：
第一，看 OpenClaw 日志里有没有收到飞书消息的打印。没有的话，问题在飞书侧——检查应用是否发布、事件是否订阅、长连接是否建立。有的话，问题在模型侧或回复发送权限上。
第二，检查机器人是否在目标聊天中。单聊场景最简单，直接把机器人加为联系人。群聊场景，机器人要先被拉进群，并且权限里要包含群消息读取和 @ 机器人响应的能力。第三，检查长连接是否还在。飞书的长连接偶尔会因为网络波动断开，OpenClaw 一般会自动重连，但如果你关了服务再启动，一定要等日志出现 connected 再测试，不然消息会丢失。这个顺序很重要，很多人一上来就去改配置，结果发现日志里压根没收到消息，白白浪费时间。
5.4 长期运行的稳定性优化
智能体不是跑起来就完事了。我在 Ubuntu 上跑了一段时间之后，发现直接前台跑服务，SSH 一断进程就没了，非常不优雅。强烈建议用 systemd 把 OpenClaw 托管起来。下面是一个服务文件模板，可以根据自己的路径调整：
ini复制[Unit]
Description=OpenClaw Service
After=network.target
[Service]
Type=simple
User=ubuntu
WorkingDirectory=/home/ubuntu/openclaw
ExecStart=/home/ubuntu/.nvm/versions/node/v20.19.0/bin/npx openclaw start
Restart=always
RestartSec=10
[Install]
WantedBy=multi-user.target
把这段保存到 /etc/systemd/system/openclaw.service，然后：
bash复制sudo systemctl daemon-reload
sudo systemctl enable openclaw
sudo systemctl start openclaw
这样即使服务器重启，OpenClaw 也会自动拉起。再配合日志查看：
bash复制journalctl -u openclaw -f
可以实时看输出，排查问题就不用登录后还不知道进程怎么起来的了。顺便说一句，systemd 的 Restart=always 很关键，模型接口偶尔超时或者飞书 WebSocket 断开，进程可能直接挂掉，有了这个自动拉起机制，你基本不用管它了。
6. 部署之后的扩展方向与个人体会
6.1 技能系统与多模型协同
OpenClaw 支持 skill 机制，这算是它和普通聊天机器人最大的区别。你可以给智能体注册各种自定义技能，比如查天气、写周报、处理文件。技能本质上是一段可以被模型调用的工具代码，你可以用 Python 或 JS 写，然后放到技能的目录里，模型会在需要时自动选择合适的技能执行。我试过写一个简单的“读取 URL 并总结”的技能，配合 Kimi 的长上下文，效果相当好。
多模型协同也是一个值得尝试的方向。虽然主对话模型是 Kimi，但 OpenClaw 允许不同场景用不同模型。比如日常聊天用 Kimi，复杂的长文档总结用上下文更大的模型，本地模型可以做埋点或预处理。这种配置思路有点像给团队里不同的人分不同的活，各取所长。不过刚上手时不要搞太复杂，先把一个模型跑顺畅，再慢慢加。
6.2 长期记忆与项目管理结合
热词里提到的 active memory 是 OpenClaw 的高阶玩法。打开记忆功能之后，智能体可以把对话中的关键信息持久化，下次你再问它，它能记起上次聊的内容。这听起来简单，实际体验差异很大——没有记忆的智能体每句话都是重新开始，有记忆的智能体才像一个真正的助手。我建议你部署完第一件事就是把这套配置研究一下，因为“记性”决定了智能体能不能真正融入你的工作流。
我还看到有人把 Obsidian 和 OpenClaw 结合起来做项目管理，思路是把项目笔记、任务清单放在 Obsidian 库中，让智能体通过技能读写这些笔记，再通过飞书对话触发任务记录和更新。相当于一个飞书入口 + 模型大脑 + Obsidian 仓库的轻量级项目管理闭环。这个我还没完全跑通，但方向和思路是可行的，后面有时间再单独写一篇。
6.3 我的几点实际体会
整套部署下来，最耗费时间的不是安装，而是理解两个系统之间的配置对应关系。飞书开放平台里的 App ID、App Secret、事件订阅，OpenClaw 配置里的 appId、appSecret、mode，每一对都要一一对应，错一个节点整条链路就断。建议你在动手之前先想清楚整个数据流：用户发消息，飞书长连接推送，OpenClaw 收到，调用 Kimi，返回结果，飞书发送。任何一个环节出问题，对着这条链路去查就能很快定位。
最后一个小建议：改配置之前先把 openclaw.json 备份一份。升级版本、调试 skill、切换模型的时候，可能一改就改坏，备份能让你秒回退。我就是因为一开始没备份，有一次把配置改乱了，折腾半天才想起来有备份文件，恢复之后一分钟就回到了正常状态。这套方案跑起来之后，我现在基本把日常的信息汇总、简单查询、定时提醒都交给它了。它不完美，但作为个人智能体的起点，已经足够好用。希望这篇实录能帮你顺利跑通，省下一点折腾的时间。