从过年折腾到现在我终于在 Linux 服务器上把 OpenClaw原 Clawdbot完整跑通了。这项目的坑说多不多说少也不少尤其是微信接入、消息回包这类问题社区里隔几天就有人问。所以我把整套流程重新梳理了一遍从环境准备、依赖安装、初始化配置到微信接入、模型对接、常见报错排查全部整理成这篇指南照着操作基本能少走一半弯路。OpenClaw 是一个开源的消息机器人网关它能把微信、QQ、飞书、Telegram 这些聊天渠道接进来统一对接 OpenAI、Ollama、ModelScope 等多个大模型实现自动回复、定时任务、智能助手这类功能。适合想把个人微信/办公软件接入大模型、快速做一版智能客服或私人助理的开发者、运维同学。我这次部署用的是 Ubuntu 22.04下面所有操作都基于这个环境其他主流 Linux 发行版大同小异。1. 项目认知与部署思路1.1 OpenClaw 到底是什么OpenClaw 的前身叫 Clawdbot身边不少老人儿还是习惯叫老名字。人如其名Claw 这个核心动作就是“抓取消息”它本身不是一个大模型产品而是一个把消息渠道和大模型串起来的网关层。你可以在微信里跟它聊天它收到消息后把上下文带给后端模型模型生成回复再通过渠道发送回来。架构上OpenClaw 分了几个层次渠道适配层负责对接不同聊天平台对话策略层负责处理上下文、指令、多轮会话模型调用层负责对接 OpenAI、Gemini、Ollama 这类推理服务。最早项目是基于 Node.js 和 TypeScript 写的好处是跨平台、生态成熟社区插件也多想在群里 机器人让它总结聊天记录、定时推送天气这种活儿改改配置就能实现。为什么叫“智能体网关”因为 OpenClaw 的重心不只是“聊天”。它可以通过工具调用、Webhook、插件机制去操作外部系统比如查询数据库、调用内部 API、对接 Dify 这类应用平台。简单类比大模型是大脑OpenClaw 就是连接手脚的神经中枢。理解了这层后面配置渠道和模型时你就能明白每个参数到底在干什么。1.2 为什么优先选 Linux 部署我一开始其实是在自己的 Windows 笔记本上折腾的想本地跑起来看看效果。结果遇到一个很典型的问题Windows 下需要依赖 WSL2 环境而 OpenClaw 在校验 WSL2 时会弹出类似 “could not safely verify the WSL2 environment” 的报错要么是 WSL 内核版本不一致要么是环境变量没带上。虽然最终能绕过去但每一步都在还环境债体验很差。Linux 服务器部署就清爽很多原生内核、没有虚拟机层、systemd 天然接管进程、服务器长期开机也不怕掉线。尤其微信这类渠道需要 7x24 小时在线你用笔记本跑根本不现实手机锁屏、断网、休眠都会让服务挂掉。所以我的建议是生产环境老老实实买台便宜云服务器Ubuntu 22.04 或者 Debian 12 都行2 核 4G 跑 OpenClaw 加几个小模型绰绰有余。部署平台安装难度长期稳定性推荐指数备注Linux 原生Ubuntu/Debian低高五星生产首选systemd 托管方便Windows WSL2中中两星环境校验问题多适合本地调试macOS低中三星M 系列芯片注意原生模块编译TermuxAndroid中低两星可原生部署但不适合长期跑如果你也只是想本地测试一下那 Windows 和 macOS 都能跑起来但只要你想认真用起来、挂微信、接团队消息直接上 Linux 服务器是最省心的路线。下面我就按这个思路来写整套部署流程。2. 环境准备与依赖安装2.1 服务器基础要求与系统初始化先说硬件底线。OpenClaw 本身占用资源不高Node.js 进程加上微信客户端这类的依赖进程内存占用大概在 600MB 到 1GB 之间。如果你想在本地再跑 Ollama 这种模型推理至少得 16G 内存起步如果只是对接云端 API2G 内存就足够。磁盘建议预留 10GB因为依赖安装、日志文件、可能的本地数据库都会占空间别只留 2、3G 那种极限容量。系统我用的 Ubuntu 22.04 LTS内核直接支持不需要额外虚拟化。拿到服务器之后第一步先做基础配置创建新用户避免所有操作都在 root 下进行这是 Linux 运维的基本习惯。微信登录后会产生临时缓存文件用专门用户运行服务权限上也更清晰。# 建议用 sudo 权限用户操作而不是 root sudo apt update sudo apt upgrade -y sudo useradd -m -s /bin/bash openclaw sudo passwd openclaw顺手把常用工具装上curl、wget、git、build-essential。后面安装 Node.js 原生模块时需要编译工具链这一步经常被忽略等报错了再回来装很浪费时间。sudo apt install -y curl wget git build-essential python3这里提醒一句如果你用的是 CentOS 或 rocky 这类系统包管理器是 yum/dnf命令要相应改成yum install -y ...。核心流程不受影响但别把 apt 的命令粘贴到 yum 的机器上硬跑。2.2 Node.js 与包管理工具安装OpenClaw 是基于 Node.js 的项目所以 Node 环境是绕不开的。官方要求 Node.js 18 以上我个人建议直接装 20 LTS稳定且生态兼容最好。服务器上装 Node 的方式有好几种我推荐 nvm因为它不污染系统目录切换版本也方便后面升级 Node 时不用重装项目。# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20装完顺手验证一下版本号避免 PATH 混乱导致命令找不到node -v npm -v接下来装 pnpm。OpenClaw 项目使用 pnpm 作为包管理器原因是它节省磁盘空间、依赖安装速度快而且能很好地处理 monorepo 结构。如果项目里有多个包需要互相引用pnpm 的 workspace 机制会舒服得多。# 通过 corepack 启用 pnpm corepack enable corepack prepare pnpmlatest --activate国内服务器如果 npm 官方源下载依赖太慢建议配一下国内镜像源能省不少时间npm config set registry https://registry.npmmirror.com2.3 获取 OpenClaw 项目代码环境齐了就可以拉代码了。OpenClaw 的官方仓库在 GitHub如果你在服务器上直接 git clone 速度慢也可以找社区维护的国内镜像仓库或者从 ModelScope 魔塔社区下载部署包。这一步没有什么特殊技巧关键是选稳定分支别一上来就用 dev 分支很可能跑着跑着遇到未发布的 bug。# 创建项目目录 sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw # 切换到 openclaw 用户 sudo su - openclaw # 拉取代码 cd /opt/openclaw git clone https://github.com/openclaw/openclaw.git .多说一句“/opt/openclaw” 是我习惯的目录你完全可以用~/openclaw这种用户目录只要注意后续 systemd 服务里 WorkingDirectory 路径保持一致就行。拉完代码后先看一下目录结构确认有 package.json 和 pnpm-workspace.yaml这就说明代码没问题。3. 核心安装流程与初始化配置3.1 安装依赖与构建项目项目代码拉下来之后第一步是安装依赖。这里强调一下OpenClaw 是用 pnpm workspace 组织的所以一定要用 pnpm 而不是 npm 装依赖否则依赖树会乱掉。整个过程根据网速不同需要几分钟耐心等就行。cd /opt/openclaw pnpm install安装过程中如果出现 “ERR_PNPM_NO_MATCHING_VERSION” 这类报错多半是 pnpm 版本太旧升级到最新版再试。如果出现 node-gyp 相关的编译错误说明 build-essential 没装全或者缺少 python3回头检查一下上一节的工具链。依赖安装完成后一般还需要构建项目。很多 Node 项目会把 TypeScript 编译成 JavaScript 放到 dist 目录OpenClaw 也类似。这一步官方文档通常写的是 pnpm build 或 pnpm run build具体看 package.json 里的 scripts 字段。pnpm build构建结束后检查一下apps/clawdbot/dist这类目录是否生成了 index.js 文件确认构建产物完整。到这里项目已经具备启动条件接下来是初始化配置。3.2 首次启动与交互式配置我第一次跑 OpenClaw 时多多少少被初始化流程绕了一下。它不像传统项目让你手动编辑 .env 文件而是启动时进入交互式配置向导你选择模型渠道、填写 API Key、启用消息渠道向导会把配置写入本地配置文件。启动命令根据你的运行模式来选。首次配置我推荐用开发模式直接前台跑方便看日志输出cd /opt/openclaw pnpm run dev启动后终端会进入一个交互界面大致流程是这样先选择模型服务商比如 OpenAI、ModelScope、Ollama填 API Key 和模型名称然后选择要接入的渠道比如微信、Telegram、飞书最后向导会让你确认配置。每一步都有默认值不确定就直接回车跳过后面到配置文件里再改。交互配置完成后推荐退出交互界面直接改配置文件因为可视化的终端界面修改多行配置效率很低。配置文件一般生成在~/.openclaw/或项目目录下的.env每个版本位置可能有差异启动日志里会明确打印“配置文件已保存到 xxx”。3.3 生产环境运行与 systemd 托管配置确认没问题后正式运行时不要再用 pnpm run dev 了。dev 模式会启动文件监听和调试接口白白占用资源。生产模式一般是pnpm start或者直接启动构建后的产物比如node apps/clawdbot/dist/index.js。为了让服务开机自启、崩溃自动拉起我建议用 systemd 写一个服务单元文件这也是 Linux 生态下的标准姿势。[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Typesimple Useropenclaw WorkingDirectory/opt/openclaw ExecStart/usr/bin/pnpm start Restartalways RestartSec10 EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.target把上面内容保存到/etc/systemd/system/openclaw.service然后执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw查看运行状态和日志的方式sudo systemctl status openclaw journalctl -u openclaw -f用 systemd 托管有一个非常实用的好处服务崩了自动重启。微信这类渠道偶尔会断连进程退出后 10 秒内自动拉起比自己在后台写个 while 循环靠谱太多。日志也无缝接到了 journalctl排查问题时翻日志特别方便。3.4 版本升级与数据备份OpenClaw 现在迭代非常快基本一两周就有一个新版本。升级流程不算复杂核心三连拉代码、装依赖、构建重启。cd /opt/openclaw git pull pnpm install pnpm build sudo systemctl restart openclaw但我强烈建议升级前先备份配置文件和本地数据目录。别问我是怎么知道的有一次升级后配置格式变更整个微信通道失效重新扫码登录才恢复。备份目录一般涉及~/.openclaw和项目目录下的 data 文件夹cp -r ~/.openclaw ~/.openclaw.bak.$(date %Y%m%d)如果你启用了本地数据库也一并备份。这些操作看起来基础但关键时候能救命。4. 微信集成实操与坑位复盘4.1 微信接入的原理与限制微信是 OpenClaw 社区里最热门、也最容易出问题的接入渠道。先说一句不好听但实在的话OpenClaw 接入微信走的基本是非官方协议渠道腾讯官方并没有开放个人微信机器人 API所以这种接入方式存在账号风控风险。我建议使用小号进行测试并且不要在核心账号上跑高频消息触发以免被限制登录。实操接入时OpenClaw 的微信渠道大致分两类工作模式同步消息和发送消息。同步消息指接收来自微信联系人、群聊的消息并把它们送入对话流程发送消息指 OpenClaw 主动调用接口把回复发出去。很多人配置完发现机器人能发消息但是微信发消息给它却没有任何反应问题往往出在同步消息这一侧没有正确配置。原理并不复杂消息进入微信后客户端或协议端需要把事件回调给 OpenClaw 的消息监听器监听器校验来源、解析内容再交由模型处理。如果同步消息开关没开、回调地址不对、或者账号登录态失效就会出现“单向通”的现象。这个观念先记住后面排查会反复用到。4.2 微信扫码登录配置实操在 OpenClaw 的配置文件中微信渠道的配置项大致长这样具体字段名不同版本略有差异但核心选项是这几项# 微信渠道开关 WECHAT_ENABLEDtrue # 是否同步接收消息 WECHAT_SYNC_MESSAGEtrue # 是否允许监听群聊 WECHAT_ENABLE_GROUPtrue # 是否只响应 机器人的群消息 WECHAT_GROUP_AT_ONLYtrue # 登录态有效期过期后需要重新扫码 WECHAT_AUTO_LOGINtrue配置完成后重启服务日志里会出现一张二维码图片路径或终端二维码。在服务器环境下建议把二维码图片复制到本地再扫或者用支持终端二维码的 SSH 客户端直接展示。# 查看最新日志里的二维码路径 journalctl -u openclaw -f扫完码后确认日志出现“login success”或“微信登录成功”的提示然后向自己的微信小号发一条测试消息。如果机器人回复了恭喜微信渠道已经通了。4.3 “能发不能收”问题排查实录首先说明我在群里看到最多的问题是这句“openclaw能发消息微信但微信发消息没回复”。我自己也踩过一次排查过程还算典型分享给大家参考。第一次遇到时我先看了日志发现机器人确实收到了消息事件但事件进入消息队列后没有任何后续输出。看配置后发现WECHAT_SYNC_MESSAGEfalse也就是说项目只开启了发送能力接收消息的开关没开。问题就这么简单所以第一条排查项就是这个开关。第二类情况是「日志里完全没有任何收到消息的记录」这时要分两种情况如果微信账号是扫码登录的大概率是登录态失效了重新扫码即可如果日志显示“message received”但模型未回复排查模型调用链路检查 API Key 是否过期、上下文长度是不是超了。第三类群聊场景机器人要回复群消息通常需要满足触发条件。默认设置下WECHAT_ENABLE_GROUPfalse或WECHAT_GROUP_AT_ONLYtrue机器人只回复被 的消息群里 一下如果还是没反应检查这两项配置的取值是否正确。有几次我看日志里根本没有事件进来结果发现是WECHAT_ENABLE_GROUPfalse把群消息直接过滤掉了。故障现象可能原因排查方向机器人能发消息但收不到消息同步消息开关未开启检查 WECHAT_SYNC_MESSAGE 配置日志完全无消息记录登录态失效重新扫码用 WECHAT_AUTO_LOGIN 自动续期群聊不响应 群监听未开启开启 WECHAT_ENABLE_GROUP个人消息有回复群消息全静默 触发条件限制按需调整 WECHAT_GROUP_AT_ONLY扫码后反复要求重扫风控限制换小号、降低发送频率、检查 IP 状态4.4 微信渠道的稳定性与降频策略微信接入最大的敌人不是代码 bug 而是风控。社区里有人反馈跑了一周被限制登录的也有大神稳定跑了几个月的差别主要在于使用习惯。我的经验是降低触发频率不要做那种“群里每句话都回复”的机器人至少要设置冷却时间或关键词过滤。这也是为什么很多 OpenClaw 配置里会有“是否只响应 消息”这个选项本质就是在保护你的账号。同时建议开启自动登录登录态过期后尽量自动恢复减少人工介入。但自动登录不等于不会风控如果服务器 IP 被标记扫再多次也没用这时可以考虑换绑小号、检查出口 IP 的稳定性。5. 渠道扩展与大模型对接5.1 更多渠道的接入对比微信搞定之后如果你有跨平台消息分发的需求可以考虑再把其他渠道接进来。OpenClaw 目前主流的渠道支持包括 Telegram、飞书、Discord、QQ 等。每个渠道的接入难度差异不小上面这张表格可以帮你做预判渠道接入方式维护成本适合场景微信扫码登录非官方协议中有风控风险个人助理、小范围测试飞书开放平台自建应用低官方 API 稳定企业内部群、办公自动化TelegramBot Token官方 Bot API低技术群、海外用户DiscordBot Token低社区群、游戏社群QQ协议登录中风控风险备选方案飞书和 Telegram 这类走官方 API 的渠道稳定性远强于微信。如果你想在生产环境给团队用我建议认真考虑飞书机器人它通过开放平台创建应用、设置事件订阅即可出问题的概率很小。微信更适合个人玩一玩或者小范围测试。5.2 对接魔塔 ModelScope 平台大模型服务商的选择决定了你的使用成本和回复效果。如果你在国内、不想折腾网络问题ModelScope魔塔社区是一个非常顺滑的方案。它提供开源模型的在线推理 API也提供 Serverless API 服务。OpenClaw 中可以直接把 ModelScope 配成一个模型 provider。先在魔塔社区注册账号在控制台创建 API Key。然后在 OpenClaw 的模型配置中把 provider 切换到 ModelScope填入 API Key 和模型名。推荐直接用通义千问系列的 qwen-plus 或 qwen-max稳定性和中文语感都很不错。# 模型配置参考 MODEL_PROVIDERmodel-scope MODEL_API_KEYsk-xxxxxxxxxxxxxxxx MODEL_NAMEqwen-plus关键一点是模型名称必须和 ModelScope 平台上完全一致大小写都不能错。填错了启动时会报 “model not found” 之类的错误。另外ModelScope 有些模型是限时免费或部分免费长期使用前要看清楚定价规则。5.3 对接 Ollama 与 Dify 等本地/业务平台如果你的服务器内存足够想完全本地化运行可以考虑 Ollama。安装 Ollama 后拉取一个量化模型比如 qwen2.5:7b然后把 OpenClaw 的模型 provider 指向http://localhost:11434即可。# 安装 OllamaLinux 一键脚本 curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:7bOllama 的部署优势是数据不出服务器隐私性好劣势是高负载时占用 CPU/内存明显建议 16G 内存以下就别折腾 7B 以上的模型了。我自己的测试服务器是 4G 内存跑 qwen2.5:3b 都勉强只能说能用、不流畅。如果你已经有了 Dify 这类 Agent 平台OpenClaw 也可以作为渠道网关接入前面几节提过的 gateway 模式就是为此设计的。由 Dify 负责工作流编排、知识库检索和工具调用OpenClaw 只做消息收发与事件转发架构上职责清晰、耦合小。配置思路是把 OpenClaw 的出站消息通过 Webhook 转发到 Dify 的 API收到回复后再推回原渠道。这一块各家版本差异较大具体字段以官方文档为准但架构思路是通用的。6. 常见问题速查与安装卸载6.1 高频报错整理折腾这几次我把社区里出现频率最高的几类问题整理了一下按可能原因和解决方向做了个速查表方便你排查时对号入座。报错/现象可能原因解决方向pnpm install 超时或卡住网络问题或源过慢配置 npmmirror 镜像源或使用全局代理配置node-gyp 编译失败缺少 build-essential安装build-essential python3提示 could not safely verify the WSL2 environmentWindows 环境下 WSL2 校验不通过Linux原生部署可完全绕开Windows 用户检查 WSL 版本并升级内核端口被占用如 3000项目进程未关闭或冲突lsof -i :3000查看占用进程kill 后重启服务频繁重启journalctl 有 OOM 日志内存不足关闭部分插件或加 swap / 升级内存微信二维码过期过快登录态不一致重启服务检查本地缓存目录权限模型报错 invalid_api_keyAPI Key 配置错误检查 key 前后是否有空格或换行重新粘贴6.2 其他平台部署差异除了标准 Linux 服务器我再简单说一下其他平台部署时的一些差异。热词里有人提到在安卓 Termux 中部署 OpenClaw这个方案确实可行基于 Termux 的原生环境不需要 proot 虚拟化流程和 Linux 类似但需要注意 Termux 的包源和目录结构与常规 Linux 不完全一样Node.js 版本可能偏旧建议先pkg upgrade再安装 nodejs。还有一个限制是手机息屏后 Termux 后台可能被系统清理长期运行稳定性一般适合临时体验。macOS 上部署相对简单安装 Homebrew 后brew install node20 pnpm git即可依赖编译一般都能过。但如果你是 Apple Silicon 芯片部分原生模块可能需要额外编译工具装上 Xcode Command Line Tools 能解决大部分问题。macOS 跑微信渠道有个优势就是日常开着电脑就能第一个体验功能劣势和 Windows 一样不适合长期无人值守场景。6.3 完全卸载与干净重装如果你配置改乱了或者想升级个大版本不想在旧环境上修修补补直接删除重装往往更干净。卸载要彻底因为 OpenClaw 的数据并不都在项目目录里配置文件和数据库可能散落在系统其他位置。# 停止服务 sudo systemctl stop openclaw sudo systemctl disable openclaw # 删除 systemd 服务文件 sudo rm /etc/systemd/system/openclaw.service sudo systemctl daemon-reload # 删除项目目录 sudo rm -rf /opt/openclaw # 删除用户数据目录根据版本可能变化 rm -rf ~/.openclaw # 可选清理数据库和缓存 rm -rf ~/.cache/openclaw干净重装的建议是换个全新目录比如从/opt/openclaw换到/srv/openclaw这样可以确认没有旧文件干扰。重装完成后如果发现某配置异常大概率就是旧的残留数据没删干净这是最容易踩的坑。另外要说一下如果你后续从 Windows 迁移到 Linux注意把原来 Windows 下生成的环境变量和键值对一起迁移过来。有些配置字段的格式在两种平台下可能不一样最典型的是路径分隔符Windows 用反斜杠Linux 用正斜杠这个细节很隐蔽但会让程序找不到文件。我个人实际跑下来的最大体会是OpenClaw 的部署流程本身难度不大依赖的就是 Node.js 生态那套常规操作真正花时间的是微信渠道的调试和账号风控的规避。所以真心建议你在 Linux 上用 systemd 托管服务配一个国内可用的模型服务商日常测试用小号、低频运行。配置文件记得养成备份习惯升级前 cp 一份。上面的流程已经帮你把能踩的坑都填得差不多了照着做应该能稳稳跑起来。如果还遇到别的奇怪报错先翻 journalctl 日志大多数问题在日志里都有明确答案。
OpenClaw Linux服务器部署指南：微信接入与大模型对接实战
从过年折腾到现在我终于在 Linux 服务器上把 OpenClaw原 Clawdbot完整跑通了。这项目的坑说多不多说少也不少尤其是微信接入、消息回包这类问题社区里隔几天就有人问。所以我把整套流程重新梳理了一遍从环境准备、依赖安装、初始化配置到微信接入、模型对接、常见报错排查全部整理成这篇指南照着操作基本能少走一半弯路。OpenClaw 是一个开源的消息机器人网关它能把微信、QQ、飞书、Telegram 这些聊天渠道接进来统一对接 OpenAI、Ollama、ModelScope 等多个大模型实现自动回复、定时任务、智能助手这类功能。适合想把个人微信/办公软件接入大模型、快速做一版智能客服或私人助理的开发者、运维同学。我这次部署用的是 Ubuntu 22.04下面所有操作都基于这个环境其他主流 Linux 发行版大同小异。1. 项目认知与部署思路1.1 OpenClaw 到底是什么OpenClaw 的前身叫 Clawdbot身边不少老人儿还是习惯叫老名字。人如其名Claw 这个核心动作就是“抓取消息”它本身不是一个大模型产品而是一个把消息渠道和大模型串起来的网关层。你可以在微信里跟它聊天它收到消息后把上下文带给后端模型模型生成回复再通过渠道发送回来。架构上OpenClaw 分了几个层次渠道适配层负责对接不同聊天平台对话策略层负责处理上下文、指令、多轮会话模型调用层负责对接 OpenAI、Gemini、Ollama 这类推理服务。最早项目是基于 Node.js 和 TypeScript 写的好处是跨平台、生态成熟社区插件也多想在群里 机器人让它总结聊天记录、定时推送天气这种活儿改改配置就能实现。为什么叫“智能体网关”因为 OpenClaw 的重心不只是“聊天”。它可以通过工具调用、Webhook、插件机制去操作外部系统比如查询数据库、调用内部 API、对接 Dify 这类应用平台。简单类比大模型是大脑OpenClaw 就是连接手脚的神经中枢。理解了这层后面配置渠道和模型时你就能明白每个参数到底在干什么。1.2 为什么优先选 Linux 部署我一开始其实是在自己的 Windows 笔记本上折腾的想本地跑起来看看效果。结果遇到一个很典型的问题Windows 下需要依赖 WSL2 环境而 OpenClaw 在校验 WSL2 时会弹出类似 “could not safely verify the WSL2 environment” 的报错要么是 WSL 内核版本不一致要么是环境变量没带上。虽然最终能绕过去但每一步都在还环境债体验很差。Linux 服务器部署就清爽很多原生内核、没有虚拟机层、systemd 天然接管进程、服务器长期开机也不怕掉线。尤其微信这类渠道需要 7x24 小时在线你用笔记本跑根本不现实手机锁屏、断网、休眠都会让服务挂掉。所以我的建议是生产环境老老实实买台便宜云服务器Ubuntu 22.04 或者 Debian 12 都行2 核 4G 跑 OpenClaw 加几个小模型绰绰有余。部署平台安装难度长期稳定性推荐指数备注Linux 原生Ubuntu/Debian低高五星生产首选systemd 托管方便Windows WSL2中中两星环境校验问题多适合本地调试macOS低中三星M 系列芯片注意原生模块编译TermuxAndroid中低两星可原生部署但不适合长期跑如果你也只是想本地测试一下那 Windows 和 macOS 都能跑起来但只要你想认真用起来、挂微信、接团队消息直接上 Linux 服务器是最省心的路线。下面我就按这个思路来写整套部署流程。2. 环境准备与依赖安装2.1 服务器基础要求与系统初始化先说硬件底线。OpenClaw 本身占用资源不高Node.js 进程加上微信客户端这类的依赖进程内存占用大概在 600MB 到 1GB 之间。如果你想在本地再跑 Ollama 这种模型推理至少得 16G 内存起步如果只是对接云端 API2G 内存就足够。磁盘建议预留 10GB因为依赖安装、日志文件、可能的本地数据库都会占空间别只留 2、3G 那种极限容量。系统我用的 Ubuntu 22.04 LTS内核直接支持不需要额外虚拟化。拿到服务器之后第一步先做基础配置创建新用户避免所有操作都在 root 下进行这是 Linux 运维的基本习惯。微信登录后会产生临时缓存文件用专门用户运行服务权限上也更清晰。# 建议用 sudo 权限用户操作而不是 root sudo apt update sudo apt upgrade -y sudo useradd -m -s /bin/bash openclaw sudo passwd openclaw顺手把常用工具装上curl、wget、git、build-essential。后面安装 Node.js 原生模块时需要编译工具链这一步经常被忽略等报错了再回来装很浪费时间。sudo apt install -y curl wget git build-essential python3这里提醒一句如果你用的是 CentOS 或 rocky 这类系统包管理器是 yum/dnf命令要相应改成yum install -y ...。核心流程不受影响但别把 apt 的命令粘贴到 yum 的机器上硬跑。2.2 Node.js 与包管理工具安装OpenClaw 是基于 Node.js 的项目所以 Node 环境是绕不开的。官方要求 Node.js 18 以上我个人建议直接装 20 LTS稳定且生态兼容最好。服务器上装 Node 的方式有好几种我推荐 nvm因为它不污染系统目录切换版本也方便后面升级 Node 时不用重装项目。# 安装 nvm curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 source ~/.bashrc # 安装 Node.js 20 LTS nvm install 20 nvm use 20 nvm alias default 20装完顺手验证一下版本号避免 PATH 混乱导致命令找不到node -v npm -v接下来装 pnpm。OpenClaw 项目使用 pnpm 作为包管理器原因是它节省磁盘空间、依赖安装速度快而且能很好地处理 monorepo 结构。如果项目里有多个包需要互相引用pnpm 的 workspace 机制会舒服得多。# 通过 corepack 启用 pnpm corepack enable corepack prepare pnpmlatest --activate国内服务器如果 npm 官方源下载依赖太慢建议配一下国内镜像源能省不少时间npm config set registry https://registry.npmmirror.com2.3 获取 OpenClaw 项目代码环境齐了就可以拉代码了。OpenClaw 的官方仓库在 GitHub如果你在服务器上直接 git clone 速度慢也可以找社区维护的国内镜像仓库或者从 ModelScope 魔塔社区下载部署包。这一步没有什么特殊技巧关键是选稳定分支别一上来就用 dev 分支很可能跑着跑着遇到未发布的 bug。# 创建项目目录 sudo mkdir -p /opt/openclaw sudo chown -R openclaw:openclaw /opt/openclaw # 切换到 openclaw 用户 sudo su - openclaw # 拉取代码 cd /opt/openclaw git clone https://github.com/openclaw/openclaw.git .多说一句“/opt/openclaw” 是我习惯的目录你完全可以用~/openclaw这种用户目录只要注意后续 systemd 服务里 WorkingDirectory 路径保持一致就行。拉完代码后先看一下目录结构确认有 package.json 和 pnpm-workspace.yaml这就说明代码没问题。3. 核心安装流程与初始化配置3.1 安装依赖与构建项目项目代码拉下来之后第一步是安装依赖。这里强调一下OpenClaw 是用 pnpm workspace 组织的所以一定要用 pnpm 而不是 npm 装依赖否则依赖树会乱掉。整个过程根据网速不同需要几分钟耐心等就行。cd /opt/openclaw pnpm install安装过程中如果出现 “ERR_PNPM_NO_MATCHING_VERSION” 这类报错多半是 pnpm 版本太旧升级到最新版再试。如果出现 node-gyp 相关的编译错误说明 build-essential 没装全或者缺少 python3回头检查一下上一节的工具链。依赖安装完成后一般还需要构建项目。很多 Node 项目会把 TypeScript 编译成 JavaScript 放到 dist 目录OpenClaw 也类似。这一步官方文档通常写的是 pnpm build 或 pnpm run build具体看 package.json 里的 scripts 字段。pnpm build构建结束后检查一下apps/clawdbot/dist这类目录是否生成了 index.js 文件确认构建产物完整。到这里项目已经具备启动条件接下来是初始化配置。3.2 首次启动与交互式配置我第一次跑 OpenClaw 时多多少少被初始化流程绕了一下。它不像传统项目让你手动编辑 .env 文件而是启动时进入交互式配置向导你选择模型渠道、填写 API Key、启用消息渠道向导会把配置写入本地配置文件。启动命令根据你的运行模式来选。首次配置我推荐用开发模式直接前台跑方便看日志输出cd /opt/openclaw pnpm run dev启动后终端会进入一个交互界面大致流程是这样先选择模型服务商比如 OpenAI、ModelScope、Ollama填 API Key 和模型名称然后选择要接入的渠道比如微信、Telegram、飞书最后向导会让你确认配置。每一步都有默认值不确定就直接回车跳过后面到配置文件里再改。交互配置完成后推荐退出交互界面直接改配置文件因为可视化的终端界面修改多行配置效率很低。配置文件一般生成在~/.openclaw/或项目目录下的.env每个版本位置可能有差异启动日志里会明确打印“配置文件已保存到 xxx”。3.3 生产环境运行与 systemd 托管配置确认没问题后正式运行时不要再用 pnpm run dev 了。dev 模式会启动文件监听和调试接口白白占用资源。生产模式一般是pnpm start或者直接启动构建后的产物比如node apps/clawdbot/dist/index.js。为了让服务开机自启、崩溃自动拉起我建议用 systemd 写一个服务单元文件这也是 Linux 生态下的标准姿势。[Unit] DescriptionOpenClaw Service Afternetwork.target [Service] Typesimple Useropenclaw WorkingDirectory/opt/openclaw ExecStart/usr/bin/pnpm start Restartalways RestartSec10 EnvironmentNODE_ENVproduction [Install] WantedBymulti-user.target把上面内容保存到/etc/systemd/system/openclaw.service然后执行sudo systemctl daemon-reload sudo systemctl enable openclaw sudo systemctl start openclaw查看运行状态和日志的方式sudo systemctl status openclaw journalctl -u openclaw -f用 systemd 托管有一个非常实用的好处服务崩了自动重启。微信这类渠道偶尔会断连进程退出后 10 秒内自动拉起比自己在后台写个 while 循环靠谱太多。日志也无缝接到了 journalctl排查问题时翻日志特别方便。3.4 版本升级与数据备份OpenClaw 现在迭代非常快基本一两周就有一个新版本。升级流程不算复杂核心三连拉代码、装依赖、构建重启。cd /opt/openclaw git pull pnpm install pnpm build sudo systemctl restart openclaw但我强烈建议升级前先备份配置文件和本地数据目录。别问我是怎么知道的有一次升级后配置格式变更整个微信通道失效重新扫码登录才恢复。备份目录一般涉及~/.openclaw和项目目录下的 data 文件夹cp -r ~/.openclaw ~/.openclaw.bak.$(date %Y%m%d)如果你启用了本地数据库也一并备份。这些操作看起来基础但关键时候能救命。4. 微信集成实操与坑位复盘4.1 微信接入的原理与限制微信是 OpenClaw 社区里最热门、也最容易出问题的接入渠道。先说一句不好听但实在的话OpenClaw 接入微信走的基本是非官方协议渠道腾讯官方并没有开放个人微信机器人 API所以这种接入方式存在账号风控风险。我建议使用小号进行测试并且不要在核心账号上跑高频消息触发以免被限制登录。实操接入时OpenClaw 的微信渠道大致分两类工作模式同步消息和发送消息。同步消息指接收来自微信联系人、群聊的消息并把它们送入对话流程发送消息指 OpenClaw 主动调用接口把回复发出去。很多人配置完发现机器人能发消息但是微信发消息给它却没有任何反应问题往往出在同步消息这一侧没有正确配置。原理并不复杂消息进入微信后客户端或协议端需要把事件回调给 OpenClaw 的消息监听器监听器校验来源、解析内容再交由模型处理。如果同步消息开关没开、回调地址不对、或者账号登录态失效就会出现“单向通”的现象。这个观念先记住后面排查会反复用到。4.2 微信扫码登录配置实操在 OpenClaw 的配置文件中微信渠道的配置项大致长这样具体字段名不同版本略有差异但核心选项是这几项# 微信渠道开关 WECHAT_ENABLEDtrue # 是否同步接收消息 WECHAT_SYNC_MESSAGEtrue # 是否允许监听群聊 WECHAT_ENABLE_GROUPtrue # 是否只响应 机器人的群消息 WECHAT_GROUP_AT_ONLYtrue # 登录态有效期过期后需要重新扫码 WECHAT_AUTO_LOGINtrue配置完成后重启服务日志里会出现一张二维码图片路径或终端二维码。在服务器环境下建议把二维码图片复制到本地再扫或者用支持终端二维码的 SSH 客户端直接展示。# 查看最新日志里的二维码路径 journalctl -u openclaw -f扫完码后确认日志出现“login success”或“微信登录成功”的提示然后向自己的微信小号发一条测试消息。如果机器人回复了恭喜微信渠道已经通了。4.3 “能发不能收”问题排查实录首先说明我在群里看到最多的问题是这句“openclaw能发消息微信但微信发消息没回复”。我自己也踩过一次排查过程还算典型分享给大家参考。第一次遇到时我先看了日志发现机器人确实收到了消息事件但事件进入消息队列后没有任何后续输出。看配置后发现WECHAT_SYNC_MESSAGEfalse也就是说项目只开启了发送能力接收消息的开关没开。问题就这么简单所以第一条排查项就是这个开关。第二类情况是「日志里完全没有任何收到消息的记录」这时要分两种情况如果微信账号是扫码登录的大概率是登录态失效了重新扫码即可如果日志显示“message received”但模型未回复排查模型调用链路检查 API Key 是否过期、上下文长度是不是超了。第三类群聊场景机器人要回复群消息通常需要满足触发条件。默认设置下WECHAT_ENABLE_GROUPfalse或WECHAT_GROUP_AT_ONLYtrue机器人只回复被 的消息群里 一下如果还是没反应检查这两项配置的取值是否正确。有几次我看日志里根本没有事件进来结果发现是WECHAT_ENABLE_GROUPfalse把群消息直接过滤掉了。故障现象可能原因排查方向机器人能发消息但收不到消息同步消息开关未开启检查 WECHAT_SYNC_MESSAGE 配置日志完全无消息记录登录态失效重新扫码用 WECHAT_AUTO_LOGIN 自动续期群聊不响应 群监听未开启开启 WECHAT_ENABLE_GROUP个人消息有回复群消息全静默 触发条件限制按需调整 WECHAT_GROUP_AT_ONLY扫码后反复要求重扫风控限制换小号、降低发送频率、检查 IP 状态4.4 微信渠道的稳定性与降频策略微信接入最大的敌人不是代码 bug 而是风控。社区里有人反馈跑了一周被限制登录的也有大神稳定跑了几个月的差别主要在于使用习惯。我的经验是降低触发频率不要做那种“群里每句话都回复”的机器人至少要设置冷却时间或关键词过滤。这也是为什么很多 OpenClaw 配置里会有“是否只响应 消息”这个选项本质就是在保护你的账号。同时建议开启自动登录登录态过期后尽量自动恢复减少人工介入。但自动登录不等于不会风控如果服务器 IP 被标记扫再多次也没用这时可以考虑换绑小号、检查出口 IP 的稳定性。5. 渠道扩展与大模型对接5.1 更多渠道的接入对比微信搞定之后如果你有跨平台消息分发的需求可以考虑再把其他渠道接进来。OpenClaw 目前主流的渠道支持包括 Telegram、飞书、Discord、QQ 等。每个渠道的接入难度差异不小上面这张表格可以帮你做预判渠道接入方式维护成本适合场景微信扫码登录非官方协议中有风控风险个人助理、小范围测试飞书开放平台自建应用低官方 API 稳定企业内部群、办公自动化TelegramBot Token官方 Bot API低技术群、海外用户DiscordBot Token低社区群、游戏社群QQ协议登录中风控风险备选方案飞书和 Telegram 这类走官方 API 的渠道稳定性远强于微信。如果你想在生产环境给团队用我建议认真考虑飞书机器人它通过开放平台创建应用、设置事件订阅即可出问题的概率很小。微信更适合个人玩一玩或者小范围测试。5.2 对接魔塔 ModelScope 平台大模型服务商的选择决定了你的使用成本和回复效果。如果你在国内、不想折腾网络问题ModelScope魔塔社区是一个非常顺滑的方案。它提供开源模型的在线推理 API也提供 Serverless API 服务。OpenClaw 中可以直接把 ModelScope 配成一个模型 provider。先在魔塔社区注册账号在控制台创建 API Key。然后在 OpenClaw 的模型配置中把 provider 切换到 ModelScope填入 API Key 和模型名。推荐直接用通义千问系列的 qwen-plus 或 qwen-max稳定性和中文语感都很不错。# 模型配置参考 MODEL_PROVIDERmodel-scope MODEL_API_KEYsk-xxxxxxxxxxxxxxxx MODEL_NAMEqwen-plus关键一点是模型名称必须和 ModelScope 平台上完全一致大小写都不能错。填错了启动时会报 “model not found” 之类的错误。另外ModelScope 有些模型是限时免费或部分免费长期使用前要看清楚定价规则。5.3 对接 Ollama 与 Dify 等本地/业务平台如果你的服务器内存足够想完全本地化运行可以考虑 Ollama。安装 Ollama 后拉取一个量化模型比如 qwen2.5:7b然后把 OpenClaw 的模型 provider 指向http://localhost:11434即可。# 安装 OllamaLinux 一键脚本 curl -fsSL https://ollama.com/install.sh | sh ollama pull qwen2.5:7bOllama 的部署优势是数据不出服务器隐私性好劣势是高负载时占用 CPU/内存明显建议 16G 内存以下就别折腾 7B 以上的模型了。我自己的测试服务器是 4G 内存跑 qwen2.5:3b 都勉强只能说能用、不流畅。如果你已经有了 Dify 这类 Agent 平台OpenClaw 也可以作为渠道网关接入前面几节提过的 gateway 模式就是为此设计的。由 Dify 负责工作流编排、知识库检索和工具调用OpenClaw 只做消息收发与事件转发架构上职责清晰、耦合小。配置思路是把 OpenClaw 的出站消息通过 Webhook 转发到 Dify 的 API收到回复后再推回原渠道。这一块各家版本差异较大具体字段以官方文档为准但架构思路是通用的。6. 常见问题速查与安装卸载6.1 高频报错整理折腾这几次我把社区里出现频率最高的几类问题整理了一下按可能原因和解决方向做了个速查表方便你排查时对号入座。报错/现象可能原因解决方向pnpm install 超时或卡住网络问题或源过慢配置 npmmirror 镜像源或使用全局代理配置node-gyp 编译失败缺少 build-essential安装build-essential python3提示 could not safely verify the WSL2 environmentWindows 环境下 WSL2 校验不通过Linux原生部署可完全绕开Windows 用户检查 WSL 版本并升级内核端口被占用如 3000项目进程未关闭或冲突lsof -i :3000查看占用进程kill 后重启服务频繁重启journalctl 有 OOM 日志内存不足关闭部分插件或加 swap / 升级内存微信二维码过期过快登录态不一致重启服务检查本地缓存目录权限模型报错 invalid_api_keyAPI Key 配置错误检查 key 前后是否有空格或换行重新粘贴6.2 其他平台部署差异除了标准 Linux 服务器我再简单说一下其他平台部署时的一些差异。热词里有人提到在安卓 Termux 中部署 OpenClaw这个方案确实可行基于 Termux 的原生环境不需要 proot 虚拟化流程和 Linux 类似但需要注意 Termux 的包源和目录结构与常规 Linux 不完全一样Node.js 版本可能偏旧建议先pkg upgrade再安装 nodejs。还有一个限制是手机息屏后 Termux 后台可能被系统清理长期运行稳定性一般适合临时体验。macOS 上部署相对简单安装 Homebrew 后brew install node20 pnpm git即可依赖编译一般都能过。但如果你是 Apple Silicon 芯片部分原生模块可能需要额外编译工具装上 Xcode Command Line Tools 能解决大部分问题。macOS 跑微信渠道有个优势就是日常开着电脑就能第一个体验功能劣势和 Windows 一样不适合长期无人值守场景。6.3 完全卸载与干净重装如果你配置改乱了或者想升级个大版本不想在旧环境上修修补补直接删除重装往往更干净。卸载要彻底因为 OpenClaw 的数据并不都在项目目录里配置文件和数据库可能散落在系统其他位置。# 停止服务 sudo systemctl stop openclaw sudo systemctl disable openclaw # 删除 systemd 服务文件 sudo rm /etc/systemd/system/openclaw.service sudo systemctl daemon-reload # 删除项目目录 sudo rm -rf /opt/openclaw # 删除用户数据目录根据版本可能变化 rm -rf ~/.openclaw # 可选清理数据库和缓存 rm -rf ~/.cache/openclaw干净重装的建议是换个全新目录比如从/opt/openclaw换到/srv/openclaw这样可以确认没有旧文件干扰。重装完成后如果发现某配置异常大概率就是旧的残留数据没删干净这是最容易踩的坑。另外要说一下如果你后续从 Windows 迁移到 Linux注意把原来 Windows 下生成的环境变量和键值对一起迁移过来。有些配置字段的格式在两种平台下可能不一样最典型的是路径分隔符Windows 用反斜杠Linux 用正斜杠这个细节很隐蔽但会让程序找不到文件。我个人实际跑下来的最大体会是OpenClaw 的部署流程本身难度不大依赖的就是 Node.js 生态那套常规操作真正花时间的是微信渠道的调试和账号风控的规避。所以真心建议你在 Linux 上用 systemd 托管服务配一个国内可用的模型服务商日常测试用小号、低频运行。配置文件记得养成备份习惯升级前 cp 一份。上面的流程已经帮你把能踩的坑都填得差不多了照着做应该能稳稳跑起来。如果还遇到别的奇怪报错先翻 journalctl 日志大多数问题在日志里都有明确答案。
