先把结论放在前面如果你手里有一台 Ubuntu 服务器想跑一个真正能常驻、能对接飞书、能顺着 Kimi 模型直接干活的 AI 智能体这套 OpenClaw v2026.3.23-2内部代号龙虾部署方案应该能让你少走两三天弯路。我这次是拿一台 4C8G 的 Ubuntu 24.04 云主机从零开始装的从系统初始化到飞书里能正常对话加上中间踩坑和返工一共花了一个下午。整个过程不涉及任何商业化工具全部基于官方发布的主程序和配置文件手写适合有一定 Linux 基础、想彻底搞懂每一条配置在干什么的人。文章会按实际部署顺序写命令直接复制可用重点地方我会解释为什么这么做最后还有一份高频报错速查表。1. 方案选型为什么是 OpenClaw、Ubuntu、Kimi、飞书这四件套先聊选型因为这一步决定了你后面所有配置的走向。我最初其实在 LangChain、Dify 和 OpenClaw 之间纠结过但实际用下来发现如果你要的是一个挂在 IM 里随叫随到的助理而不是一个拖拽编排的 workflow 平台OpenClaw 的定位是最合适的。它的核心思路很直白把模型、渠道飞书、钉钉、企业微信这类 IM、技能Skill、记忆Active Memory四层解耦每个环节都能独立配置日常使用只需要通过某个 IM 入口自然对话就行不用打开网页端操作一堆节点。Ubuntu 就不用多说了OpenClaw 的官方脚本对 Debian 系支持最完整Ubuntu 22.04/24.04 LTS 都是长期维护版本apt 源里的 Node.js、git、curl 等基础组件稳定出问题也好搜。我实际测试下来2C4G 的机器就能跑起来但如果你打算让模型上下文开得很大或者挂着多个渠道4C8G 会更从容内存不够的时候 Node 进程很容易被 OOM 杀掉这个我后面在常见问题里会详细讲。Kimi 模型这一块我选它最直接的原因是接口兼容性好。Moonshot 开放平台提供的 API 是 OpenAI 兼容格式OpenClaw 配置里把 provider 指到对应的 base_url 就行不需要写任何适配代码。再加上 Kimi 系列本身的上下文窗口足够大拿来做长对话和文档摘要很划算。如果以后想换 DeepSeek、通义或者本地模型配置文件里改几个字段就能切不会锁死在一个供应商上。飞书作为 IM 入口优势在于开发者生态比较完整。飞书开放平台支持事件订阅的长连接模式WebSocket这意味着你的服务器不用有公网 IP 或域名也能收到消息对自部署非常友好。微信个人号接入一直在封禁边缘钉钉回调又要校验一堆东西飞书的开放程度在三者里面是最省心的。这套方案的整体链路也很清晰用户在飞书里给机器人发消息飞书开放平台通过长连接把事件推给 OpenClawOpenClaw 调用 Kimi API 生成回复再通过机器人接口发回聊天窗口。2. 部署前的环境准备Ubuntu 服务器与运行时依赖2.1 服务器初始化与基础组件安装我建议拿到一台全新的 Ubuntu 24.04 云主机后先别急着装 OpenClaw把系统基础环境收拾干净能避免很多莫名其妙的坑。首先是更新 apt 源并安装常用工具sudo apt update sudo apt upgrade -y sudo apt install -y curl git vim htop unzip然后是最关键的一步安装 Node.js。OpenClaw 的运行时是 Node.js版本要求比较严格官方发布会明确标注需要 Node 20 及以上。Ubuntu 24.04 自带的 apt 源里 Node 版本往往偏低不要直接用apt install nodejs我建议用 NodeSource 的安装脚本装 20 LTScurl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash - sudo apt install -y nodejs装完务必检查版本OpenClaw 控制台启动失败的一大原因就是 Node 版本不满足要求node -v # 我这边输出 v20.18.0 npm -v # 10.8.22.2 创建专用用户与工作目录这里是我自己的经验教训不要用 root 直接跑 OpenClaw。一是 OpenClaw 默认会在用户目录下创建~/.openclaw作为配置和数据目录不同用户运行会生成完全不同的实例容易搞混二是万一智能体被注入恶意指令普通用户权限能减少破坏范围。我创建了一个叫openclaw的系统用户sudo useradd -m -s /bin/bash openclaw后续的安装和运行都切到这个用户下执行配置文件、日志和技能目录互相隔离以后就算同一个服务器要跑多个实例也不会打架。2.3 内存与交换分区检查OpenClaw 主进程加控制台 UI实测空闲状态下大概占 300MB 左右内存但如果把技能加载多了或者模型返回特别长的内容内存会明显上涨。在 2G 内存的机器上部署建议先开一个 2G 的 swap 保底sudo fallocate -l 2G /swapfile sudo chmod 600 /swapfile sudo mkswap /swapfile sudo swapon /swapfile echo /swapfile none swap sw 0 0 | sudo tee -a /etc/fstab这个步骤不是必须的但我的建议是宁可有不用不要用的时候没有。内存不够导致的进程被杀日志里往往不会给出明确提示排查非常浪费时间。3. 安装 OpenClaw 主程序初始化、接管配置、启动控制台3.1 官方安装脚本与 npm 安装两种方式OpenClaw 的安装方式我在不同机器上试过两种官方安装脚本是首选它会自动检测系统架构、装好依赖并写入 PATHcurl -fsSL https://openclaw.sh/install.sh | bash装完以后执行openclaw --version正常情况下会输出 v2026.3.23-2 这样的版本号。如果你不喜欢管道到 bash 这种方式也可以从 npm 全局安装npm install -g openclaw/core2026.3.23-2两种方式装出来的主程序是同一套区别在于脚本方式还会帮你生成 shell 补全和默认目录结构。我这次用的脚本方式整体两分钟左右就完成了。3.2 首次运行的交互式引导几个容易忽略的细节安装完成后第一件事是执行openclaw onboard。这是 OpenClaw 的交互式引导命令会依次问你智能体叫什么名字、默认联网方式、要不要启动控制台 UI、默认使用哪套模型配置。这里有个细节容易踩坑在模型这一步它会弹出几个预设 provider 给你选如果你已经想好要用 Kimi可以直接选自定义 OpenAI 兼容接口也可以在引导完成后手动改配置文件我个人推荐后者因为引导界面里的配置项不全后面还是要进文件。引导结束后会在~/.openclaw/下生成完整的配置目录进去看一眼结构ls -la ~/.openclaw/目录下包括config.yaml主配置、assets/记忆和技能数据、logs/运行日志。先不要急着改任何文件用默认配置启动一次看看整体有没有问题openclaw serve看到类似OpenClaw is running on port 3071的输出就说明主程序没问题。这时候如果要访问控制台 UI浏览器打开http://服务器IP:3071初次访问会要求设置一个管理密码这个密码也保存在配置文件里用openclaw ui reset-password可以随时重置。3.3 控制台 UI 启动失败的两个排查方向在安装 Windows 版本或者 Docker 环境下很多人会遇到control ui did not start这个提示。在 Ubuntu 上我虽然没有直接踩到但排查逻辑是相通的第一确认 3071 端口没有被占用ss -lntp | grep 3071看一眼第二打开~/.openclaw/logs/control-ui.log看具体的 Node 报错。如果确认是端口冲突在 config.yaml 里找到webui.port改成别的端口即可。另外一个很隐蔽的问题是如果你之前用 root 初始化过再用普通用户跑控制台会因为权限问题起不来所以环境和用户选择一定要在第一步就定清楚。4. Kimi 模型接入API 配置、参数调优与成本控制4.1 获取 API Key 与模型基本信息Kimi 的开放平台地址是platform.moonshot.cn注册后进入控制台创建一个 API Key。这个 Key 创建后会完整显示一次务必复制保存后面填配置文件要用。Kimi 平台的接口地址是https://api.moonshot.cn/v1和 OpenAI 的https://api.openai.com/v1结构完全一致所以任何支持 OpenAI 兼容协议的客户端都能直接用。至于模型名平台文档会实时列出。我这次用的版本里kimi-k2系列和moonshot-v1-32k都可以在 OpenClaw 里正常调用长文本场景建议选 32k 或以上的版本。有一点要特别注意模型名必须精确匹配平台当前提供的标识符OpenClaw 本身不会帮你做模糊匹配写错了就会报unknown model之类的错误这个我在后面常见问题里会专门展开。4.2 修改 OpenClaw 主配置编辑~/.openclaw/config.yaml把模型部分改成这样agent: name: 阿龙 model: provider: openai-compatible base_url: https://api.moonshot.cn/v1 api_key: sk-你的Keys替换这里 model: kimi-k2-0905-preview temperature: 0.6 max_output_tokens: 2048 timeout: 120这里我故意把 provider 写成openai-compatible而不是kimi原因是 OpenClaw 的模型层对已经内置适配器的 provider 会做额外处理但走通用 OpenAI 兼容协议是最不容易出问题的路径任何兼容接口都能靠这个配置跑通。如果你想用 OpenClaw 对 Kimi 的专门适配需要在配置里写provider: kimi并激活对应的内置适配器两种方式效果差别不大我推荐新手先走通用协议等跑通了再折腾优化。还有一个细节api_key 不建议直接明文写在 config.yaml 里。OpenClaw 支持从环境变量读取敏感字段把 Key 放到系统环境变量里配置文件用${MOONSHOT_API_KEY}引用这样就算以后把配置文件分享出去也不会泄露密钥。4.3 实测对话从命令行验证到飞书前的最后一步配置修改完以后先不要急着接飞书在命令行里用 OpenClaw 自带的调试对话模式验证模型连通性openclaw chat输入你好介绍一下你自己如果模型正常返回说明 Kimi 接入成功。这时候如果返回超时或者报Connection error优先排查 base_url 是否写对、API Key 是否有效、服务器能否访问api.moonshot.cn。用curl -I https://api.moonshot.cn/v1能快速验证网络连通性。我这边第一次测试时模型通是通了但回复速度有点慢排查后发现是timeout设成了 30 秒而 Kimi 在思考较长答案时经常超过这个时间。把timeout调到 120 秒后就稳定了。另外temperature的建议是 0.6 左右太低了回复会变得僵硬太高了容易跑题这个值适合大多数助理场景。4.4 参数调优与成本控制经验Kimi 的计费主要是按 token 算的max_output_tokens设得过大不会直接扣费但会让模型有机会生成超长回复实际成本会无感上升。我的经验是日常对话 2048 够用需要长文总结时才临时调大。另外飞书对接后如果智能体被拉到群里群里的每一条消息都可能触发上下文累积token 消耗会明显加快。OpenClaw 提供了上下文长度上限配置我建议在 config.yaml 里加上max_context_tokens: 32768这样超过上限后会自动折叠旧消息避免单次请求费用失控。如果你的 Key 是企业付费套餐或者有预算限制直接在平台控制台设置月度消费上限会更稳妥。5. 飞书机器人对接从开放平台建应用到消息互通5.1 在飞书开放平台创建应用飞书机器人接入的第一步是去open.feishu.cn创建一个企业自建应用。登录后选择开发者后台创建企业自建应用填个名字和描述就行。创建完成后进入应用详情左侧菜单能看到添加应用能力在这里添加机器人能力。这个步骤很重要不加机器人能力后面所有消息收发都无法生效。然后打开凭证与基础信息找到 App ID 和 App Secret这两个值稍后要填进 OpenClaw 的飞书通道配置里。App Secret 只显示一次如果忘了可以重置但重置之后旧配置立即失效需要同步更新 OpenClaw 配置并重启服务。5.2 配置权限一个都不能少飞书的权限模型比较严格机器人要收发消息至少需要这几项权限im:message读取用户发给机器人的单聊消息im:message:send_as_bot以机器人的身份发送消息im:chat:readonly读取群组基本信息如果要进群这个必须有在权限管理页面搜索这些权限并逐一开通。很多人的机器人能收到消息但发不出去八成就是只开了接收权限忘了开发送权限。开通权限后还要在版本管理与发布里创建一个版本并发布。这个坑一定要注意未发布的应用只能自己应用创建者在飞书里使用别的用户根本搜不到这个机器人测试阶段没问题但要让整个团队用就必须发布并通过审核企业自建应用通常审核很快甚至免审。5.3 事件订阅用长连接还是公网回调飞书开放平台的事件订阅有两种方式这是整个对接过程中最需要想清楚的一个选择。一种是公网回调模式你需要提供一个公网 HTTPS 地址作为请求地址飞书会把消息事件 POST 到这个地址上OpenClaw 里要开对应的 webhook 端口还要解决域名和 HTTPS 证书问题。另一种是长连接模式OpenClaw 主动和飞书服务器建立 WebSocket 连接飞书事件通过这个连接推过来服务器不需要有公网入口。我强烈推荐长连接模式。原因很现实云服务器没有域名和可信 HTTPS 证书的情况下公网回调模式配置繁琐每次飞书平台发校验请求你都得保证服务在线调试体验很差。长连接模式下只要服务器能访问飞书开放平台的接口地址就行不需要额外开放任何入站端口。在飞书后台的事件订阅页面订阅方式选择长连接添加事件im.message.receive_v1然后发布应用。5.4 OpenClaw 侧飞书通道配置回到 OpenClaw 的config.yaml把飞书通道配置补上channels: feishu: enabled: true app_id: cli_xxxxxxxxxxxx app_secret: 你的AppSecret mode: websocket verify_token: # 如果后台设置了令牌就填 encrypt_key: # 如果开启了消息加密就填 allowed_users: [] # 留空表示允许所有用户 allowed_groups: [] # 留空表示允许所有群保存后重启 OpenClaw 服务。注意先杀掉旧进程再启动避免端口和连接冲突pkill -f openclaw serve openclaw serve看到日志里出现类似feishu websocket connected的输出说明长连接建立成功这是整个对接过程中最让我安心的一条日志。5.5 首次对话测试与发布验证打开飞书客户端在搜索栏搜索你创建的机器人应用名称发布前可能直接搜到自己的应用进入会话后发一条你好。如果一切正常机器人会在几秒内回复。这里有一个我自己踩过的坑测试消息发出去后飞书完全没反应我一度以为是配置错了后来才发现应用版本根本没有发布应用还处于开发模式只有创建者自己能看到机器人但事件回调实际上也没生效。所以务必先发布应用版本再开始测试。如果机器人已发布但仍然不回复可以按这个顺序排查第一看 OpenClaw 日志有没有收到事件推送第二确认权限管理里的im:message已开通且应用版本已发布第三确认长连接是 connected 状态而不是 reconnecting。这一套走下来绝大多数问题都能定位到具体环节。5.6 群聊场景的额外配置要让机器人进群响应除了开通权限还需要在 OpenClaw 里明确是否允许群聊。我有个习惯是把allowed_groups配置成明确的白名单而不是留空放行所有群。原因是群里的上下文混乱加上多用户同时 机器人token 消耗会比单聊高很多倍。白名单方式虽然多一步配置但能有效控制成本也避免机器人在不相关的群里被疯狂打扰。群聊里建议只响应 机器人的消息OpenClaw 默认行为就是如此不用额外配置这点很省心。6. 技能、记忆与访问控制把智能体从能聊变成能用6.1 Skill 技能体系按需扩展别一上来装一大堆OpenClaw 的技能Skill体系是它区别于普通聊天机器人的核心优势。技能本质上是一些预先定义好的工具函数智能体在对话中判断需要时会自动调用。比如你给它装一个待办管理技能它就能在本地创建、查询、完成任务清单把帮我记一下明天下午三点和客户开会这类需求落成结构化数据。查看和安装技能的命令很直观openclaw skill list # 查看已安装技能 openclaw skill search todo # 搜索技能仓库 openclaw skill install todo # 安装指定技能我的建议是刚开始只装最核心的两三个技能比如日程待办和网页搜索。装太多技能会让模型在每次请求时都要遍历一遍技能列表既增加 token 消耗还可能让模型选错工具。之前有个朋友一上手就装了 20 多个技能结果智能体经常把计算器技能当作搜索技能用最后删到只剩三个就正常了。技能配置本身在~/.openclaw/skills/技能名/目录下每个技能包含一个描述文件和一个实现脚本。如果你想二次开发官方说明里对自定义技能定义得很清楚直接在已有技能基础上改描述文件让模型更清楚什么场景该调用它是性价比最高的优化方式。6.2 Active Memory让智能体有长期记忆OpenClaw 的 Active Memory 是一个让我比较惊喜的功能。默认情况下模型对话是无状态的关掉上下文就什么都不记得了。Active Memory 会把重要的对话内容抽取出来按实体、任务、偏好等维度存到本地下次对话时自动加载相关内容。比如我在飞书里提到过我习惯下午三点以后开会过几天再问它帮我安排一个会议时间它会把下午三点以后这个偏好带上这个体验就很接近真人助理了。记忆数据存放在~/.openclaw/assets/memory/下打开可以看到按主题整理的结构化文件也可以手动编辑修正。高阶一点的做法是定期检查记忆删除过时内容。因为记忆会在每次请求时作为上下文注入积累到几百条以后token 开销也会成为负担。我把这看成是给智能体定期整理办公桌一次删掉一批过期的临时任务整个响应速度都会提升。6.3 访问控制与安全边界把智能体接到 IM 里以后安全边界就很重要。OpenClaw 的权限配置除了前面说的允许用户和群组白名单还支持对技能进行授权控制。比如某个技能可以操作服务器文件系统你肯定不想让它被任何群成员触发。我的做法是高风险技能设为仅限管理员低风险的日常技能放行agent: permissions: admin_users: - ou_你的飞书OpenID skill_policy: filesystem: admin_only shell: admin_only search: everyone这个设计的核心思路是最小权限原则。智能体能做的事情越少出问题的面就越小。很多人觉得我的机器人只在自己的小群里用不会有问题但一旦技能被恶意指令利用比如让它读一下服务器上的某个文件后果其实很直接。7. 生产化部署systemd 守护、日志管理与升级策略7.1 用 systemd 让 OpenClaw 常驻运行前面开发调试阶段我是手动起openclaw serve的但正式用起来SSH 一断开进程就没了这显然不行。用 systemd 托管是最标准的做法。在/etc/systemd/system/openclaw.service里写入[Unit] DescriptionOpenClaw Agent Service Afternetwork.target [Service] Typesimple Useropenclaw WorkingDirectory/home/openclaw EnvironmentFile/home/openclaw/.openclaw/env ExecStart/home/openclaw/.local/share/openclaw/bin/openclaw serve Restartalways RestartSec10 LimitNOFILE65536 [Install] WantedBymulti-user.target注意ExecStart里的路径要根据你实际的安装位置调整用which openclaw查一下即可。EnvironmentFile 里放环境变量比如MOONSHOT_API_KEYsk-xxx这样就不用写在配置文件里了。启用并启动sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw systemctl status openclaw7.2 日志查看与轮转systemd 托管之后日志都用 journalctl 查看journalctl -u openclaw -f # 实时滚动 journalctl -u openclaw --since 1 hour ago # 最近一小时日志默认会占用一定磁盘空间我建议设置一下 journal 大小上限避免日志把磁盘塞满sudo journalctl --vacuum-size200M还可以在/etc/systemd/journald.conf里修改SystemMaxUse200M来永久限制。7.3 主程序升级步骤OpenClaw 的版本迭代比较快升级方法很简单但我吃过亏这里特意强调下顺序。先备份配置目录再升级主程序最后检查兼容性cp -r ~/.openclaw ~/.openclaw.bak curl -fsSL https://openclaw.sh/install.sh | bash openclaw --version openclaw onboard --check # 检查配置兼容性升级后如果之前正常的功能突然失效先看日志不要急着回滚。多数情况是配置项格式有更新比如某个字段改了名字日志里会明确提示。备份目录在确认一切正常后可以删掉我一般会保留最近两个版本的备份。8. 高频问题排查与避坑清单8.1 典型报错对照表结合我自己的经历和社区里常见反馈整理了一份问题速查表按出现频率排序现象直接原因处理方法agent failed before reply: unknown model模型名写错或平台不支持去平台文档确认模型标识符精确填写control ui did not start端口被占用/Node 版本过低/权限问题检查 3071 端口、确认 Node 20、用非 root 用户启动feishu websocket reconnectingApp Secret 错误或应用未发布核对凭证信息创建版本并发布应用机器人收得到消息但不回复缺发送权限或事件未订阅成功检查im:message:send_as_bot权限和事件订阅状态Node runtime not foundPATH 未包含 Node 安装目录确认node -v可执行检查 systemd 的 EnvironmentFileresource busy or locked (Windows)旧进程占用配置目录文件任务管理器杀掉 node 进程后重试8.2 三个最容易被忽视的坑第一个坑是零 token 配置造成的模型不可用。新版 OpenClaw 在首次初始化时如果你选择零配置快速体验它会默认用一个内置的公共模型端点这个端点经常触发agent failed before reply错误日志里提示的模型名甚至可能是系统内置占位符。解决办法就是彻底不走快速体验路径直接配置自己的 Kimi API Key一劳永逸。第二个坑是服务器内存不足导致进程无声消失。OpenClaw 进程崩溃时不一定留下明显的 error 日志有时候就是你发消息它不回进服务器一看进程没了。打开dmesg | tail -20如果看到out of memory相关记录那就是内存不够。处理方法要么加内存要么开 swap要么减少同时加载的技能数量。第三个坑是飞书应用版本没有发布。这个我前面提过但值得再说一次因为出错率太高了。在飞书后台配置完权限和事件后很多人以为保存就生效了实际上必须到版本管理与发布里创建一个版本并发布新权限和新事件才真正对用户生效。如果你发现我自己能用但同事用不了或者权限明明加了还报没有权限百分之九十是版本没发布。8.3 我个人的日常维护清单最后分享一份我每天/每周会做的检查清单虽然是手工活但能避免 90% 的机器人突然不干活每天看一眼journalctl -u openclaw --since 24 hours ago | grep ERROR有异常提前处理每周清一次 Active Memory 里过期的待办和临时任务模型平台控制台看一眼 token 消耗确认没有异常暴涨每隔一两周跑一次curl -I https://api.moonshot.cn/v1确认网络路径稳定升级前永远先备份~/.openclaw整个目录9. 后续还能怎么扩展这套部署跑通以后扩展方向其实很多。比如你可以在 OpenClaw 里再加一个定时任务技能每天早上九点自动把当天待办推送到飞书群或者接上 Obsidian 的本地笔记目录让智能体帮你检索笔记、整理项目信息再或者把多个模型配置成路由模式简单的闲聊走便宜模型复杂任务自动切换到 Kimi 的大上下文模型。我个人实际使用中体会最深的一点是这套东西刚跑通的第一个月我会频繁查看后台日志总担心它挂掉用了一个季度之后除了每周的例行维护基本不需要额外操心。稳定性来源不在于某个神秘配置而在于把环境、权限、日志、备份这几件基础事做扎实。如果你也打算在 Ubuntu 上部署 OpenClaw 接飞书按照这篇实录的顺序走一遍遇到问题就对着第 8 节的速查表排查大概率一个下午就能把整套系统跑起来。
