搞这个OpenClaw其实是被朋友问了三回才下决心认真折腾的。原因是这家伙现在挂在嘴边的一句话是“我要一个7x24小时在线干活儿的AI助手”最好还能直接在微信里喊它干活。听完需求我第一反应就是那为什么不直接上OpenClaw呢。OpenClaw是一个开源的AI助理框架官方定位是“本地部署的个人AI助理”它把浏览器自动化、代码执行、文件操作、各类IM接入能力整合到一起相当于在你自己的服务器上养了一个能看网页、能跑脚本、能回复消息的全能数字员工。这篇保姆级教程就围绕Ubuntu服务器上从零安装OpenClaw并且打通企业微信全流程展开。整篇内容对应的是我实际踩过一遍坑之后的完整复盘适合刚接触Linux的萌新、想给团队做AI助理的运维同学、以及想在自己服务器上折腾开源大模型应用的技术爱好者照着做基本都能跑通。1. 先搞清楚OpenClaw到底是个什么玩意1.1 一句话讲明白它是什么OpenClaw本质上是一套完整的AI Agent运行框架名字里有“Open”但它和OpenAI没有直接关系它是一个开源社区项目目标是让你能用一套本地服务管理多个AI模型、多种消息渠道、多套自动化工具链。打个比方大模型本身就像一个高智商的实习生聪明但没手没脚OpenClaw就是给这个实习生配上电脑、手机、网络和一套工作流让他能在你的服务器里真正“干活”。我见过不少人第一次听这个名字时误以为它是一个像ChatGPT那样的聊天网页。实际上OpenClaw是跑在服务器上的后台服务它没有自带酷炫的聊天界面它的工作方式更像一个消息中转调度中心你通过企业微信、飞书、Discord、Telegram甚至本地网页给它下达指令它调度底层大模型去理解任务再调用浏览器自动化、终端命令、文件读写等能力去执行任务最后把结果原路返回给你。对普通用户来说最直观的使用场景就是在企业微信里机器人让“他”去查一个网页上的数据、汇总一份Excel表格、定时监控某个服务状态并在群里告警他都能接得住。和单纯把大模型接入聊天软件不同OpenClaw有完整的任务记忆、技能插件体系和多轮会话管理更像是把一个员工真正培训上岗而不是只放一个自动回复客服在那里。1.2 为什么要装在Ubuntu上而不是Windows先说结论生产环境跑OpenClawUbuntu是最省心的选择没有之一。原因有三点。第一OpenClaw底层依赖大量Linux生态工具比如Chromium无头浏览器、Node.js运行时、各种网络代理组件在Ubuntu上是用apt包管理器一把梭的“原生体验”在Windows上光是装编译工具链就能劝退一批人。第二长期运行的服务必须考虑稳定性和资源占用Ubuntu Server没有图形界面负担系统占用低、内存全部让给业务而且不容易被莫名其妙的重启和补丁打断。第三服务器场景的运维习惯就是SSH远程连接Ubuntu自带完整的SSH体系和systemd进程管理配合pm2做守护能做到开机自启、崩溃自动拉起Windows在这方面体验要差一大截。当然也有人说我就想在Windows上用WSL跑OpenClaw行不行。说实话开发调试没问题但生产环境我不建议WSL的网络代理模式、systemd支持和端口转发偶尔会有幺蛾子尤其是企业微信回调需要公网能访问你的端口时WSL那层网络地址转换会让自己排查问题怀疑人生。1.3 整个系统由哪几块组成OpenClaw不是单一的一个可执行文件它是一套多组件协作的系统。我根据自己的部署经验梳理了下面这张内部结构图用文字描述OpenClaw主服务负责会话管理、任务调度、技能Skill加载、与大模型API通信是整套系统的大脑。ClawID与设备认证OpenClaw使用一套账号体系来绑定设备和同步配置首次启动时需要在浏览器里打开一个本地认证页面完成登录。浏览器自动化运行时底层调用Chromium的无头模式用来执行打开网页、点击按钮、抓取数据等任务这也是系统安装依赖时最耗时间和最容易出问题的模块。消息通道适配器负责对接企业微信、飞书、Discord等IM平台把来自各端的消息统一转成OpenClaw内部事件格式。内存数据库OpenClaw使用KeyDBRedis的一个开源分支来缓存会话上下文和任务状态保证多轮对话有记忆。理解这五块之后再回头看安装过程你就能明白为什么有些步骤看起来“无关紧要”比如明明装的是Node.js程序为什么还非要拉一个数据库镜像、装一个浏览器内核。这些都是它干活时候的“手和脚”缺一块整套系统就跑不顺。2. 装之前的环境准备少走弯路2.1 系统与硬件要求OpenClaw官方没有给出特别严格的硬件下限表但根据我的实际使用经验可以给大家一个清晰的参考标准。操作系统Ubuntu 20.04 LTS及以上都支持强烈建议用22.04 LTS或24.04 LTS太老的版本某些依赖源会出问题。CPU至少2核推荐4核以上。因为除了OpenClaw主进程还要同时跑Chromium和大模型API的请求转发CPU太弱会出现明显卡顿。内存最低4GB推荐8GB以上。Chromium每个标签页大概吃掉200-400MB内存加上Node.js主进程和KeyDB缓存4G内存跑简单任务还行一旦让AI同时开多个浏览器标签页或处理长文档就会开始疯狂使用Swap分区磁盘IO被拖死。磁盘建议至少20GB空闲空间系统、依赖、Chromium浏览器、日志文件都会占空间。网络服务器必须在公网可达或至少能被企业微信服务器访问到因为企业微信回调消息需要主动推送到你的服务器端口。如果服务器在NAT后面就需要用内网穿透方案处理这点后面会详细说。我踩过的一个坑就是一开始图省事用了一台1核2G的云服务器测试结果npm install的时候直接OOM进程被杀。后来换到2核4G才算勉强能跑但让AI开浏览器解码网页时还是有点吃力。所以内存这块千万别省这钱不值得省。2.2 Node.js安装的正确姿势OpenClaw主程序是Node.js写的所以Node.js运行时是第一个必须装好的依赖。很多人习惯直接sudo apt install nodejs装完一看版本是v12或者v14OpenClaw直接报错跑不起来。Ubuntu官方源里的Node.js版本更新太慢不适合用来部署对新版本有要求的应用。正确打开方式是用**nvmNode Version Manager**来安装和管理Node.js版本这样以后想切换版本也就一条命令的事儿。先装nvmcurl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc装完之后确认nvm可用nvm --version接着安装Node.js 20 LTS版本我实测OpenClaw在Node 18、20、22上都能跑但20 LTS最稳坑最少nvm install 20 nvm use 20 nvm alias default 20这里有个细节nvm alias default 20必须执行否则服务器重启后Node.js可能不在PATH里pm2守护的OpenClaw进程会因为找不到node命令而启动失败。装完检查一下node -v npm -v看到v20.x.x就说明环境正常了。顺手把npm源切到国内镜像安装依赖速度会快非常多npm config set registry https://registry.npmmirror.com2.3 拉取OpenClaw代码与基础镜像代码克隆这一步推荐把OpenClaw部署在/opt/openclaw目录下因为生产环境服务放/opt是惯例权限清晰且不容易被误删。如果只是个人测试放~/openclaw也行。sudo mkdir -p /opt/openclaw sudo chown -R $USER:$USER /opt/openclaw cd /opt/openclaw git clone https://github.com/openclaw/openclaw.git .国内网络环境直接clone GitHub有时候会超时这属于常见问题不用慌。可以临时用ghproxy这类加速代理或者改用镜像站。我的建议是别在网络上花费太多时间直接配一个可靠的GitHub加速方式把代码拉下来是最省事的。代码拉下来之后会看到项目里有docker-compose.yml里面有KeyDBRedis兼容数据库的镜像配置。OpenClaw官方推荐用Docker或者Podman跑数据库如果你服务器上已经装了Docker直接一条命令把数据库拉起来cd /opt/openclaw docker compose up -d keydb如果没有Docker环境又不想装Docker毕竟Docker本身也要占资源可以单独装一个Redis替代sudo apt update sudo apt install redis-server -y sudo systemctl enable redis-server sudo systemctl start redis-server这两种方式我都用过Docker方式环境更干净Redis直装方式少一层容器开销。OpenClaw默认会尝试连接localhost:6379的KeyDB/Redis实例所以不管用哪种方式只要能保证6379端口上有Redis的兼容服务就行。3. 完整安装与首次启动3.1 配置文件的骨架长什么样OpenClaw的主配置文件是config.main.json仓库里一般会有一个config.main.example.json首次使用需要复制一份出来改cd /opt/openclaw cp config.main.example.json config.main.json配置文件里最核心的几个字段我先给你翻译一下model指定OpenClaw使用哪个大模型作为默认推理引擎。官方默认会连接OpenClaw自家的Clawnet API服务但配置上支持OpenAI格式兼容接口所以你也可以填DeepSeek、通义千问、Ollama本地模型的地址。webhook服务器配置HTTP服务的监听端口默认是9000端口企业微信回调就是往这个端口上推消息的。存储路径配置会话历史、技能缓存的存放位置默认在项目目录下的data文件夹。全局指令前缀比如设置!作为命令前缀群里发消息时只有以!开头的内容才触发AI响应避免机器人回复群里所有无关消息。我建议第一次配置时除了把模型API换成自己可用的Key其余字段先保持默认能不动就不动。等系统跑通了再按需调整端口、前缀这些参数。一上来就到处改出了问题反而不好排查。关于模型这里单拎出来说一句。OpenClaw对接模型API的方式是OpenAI兼容格式这意味着国内很多模型服务都能直接填进去比如DeepSeek的https://api.deepseek.com/v1智谱的https://open.bigmodel.cn/api/paas/v4/。只需要在配置里填上baseURL、apiKey、model名称三个字段即可。我后面会附一个用本地Ollama模型跑的配置示例那个适合希望完全离线运行、不把对话数据送到第三方API的朋友。3.2 npm install和第一次npm start依赖安装是整套部署里最考验耐心的一步因为OpenClaw除了npm包之外还需要下载Chromium浏览器内核和几个系统级的原生库。官方文档里其实有提供一个安装脚本cd /opt/openclaw ./scripts/install.sh这个脚本会帮你把npm依赖、Chromium和系统依赖一起装好。但我个人的经验是脚本执行到下载Chromium那一步时很容易因为网络问题卡住或失败所以更推荐分步执行每装一步确认一次结果效率反而更高npm install如果npm install中途报错大概率是缺系统级的构建工具链先补上再重新装sudo apt install -y build-essential python3 pkg-config libtool automake npm install依赖装完之后还有一步关键操作。OpenClaw底层浏览器自动化依赖Puppeteer而Puppeteer在Ubuntu上运行Chromium需要一堆共享库最常见的报错是缺libgbm.so.1。预防办法是提前装好这些库sudo apt install -y libgbm1 libnss3 libnspr4 libatk1.0-0 libatk-bridge2.0-0 libcups2 libdrm2 libxkbcommon0 libxcomposite1 libxdamage1 libxfixes3 libxrandr2 libpango-1.0-0 libcairo2 libasound2 libatspi2.0-0这个过程虽然长但它是保证浏览器自动化任务能真正跑起来的基础。缺一个库Chromium在启动时会直接闪退而且很多时候错误信息非常隐晦新手很容易卡在这一步。一切就绪后启动OpenClawnpm start看到日志里出现类似OpenClaw is running on port 9000的输出说明主服务已经起来了。3.3 登录ClawID与设备授权走到这一步有一个特别容易让新手迷路的环节OpenClaw第一次启动时并不会直接进入可用状态而是要求你先登录ClawID账号并完成设备授权。简单理解ClawID就是OpenClaw的账号系统用来管理你的设备绑定和云端配置同步。启动日志里会提示你打开一个本地认证页面一般是http://localhost:4455。如果你是直接在服务器显示器上操作就浏览器打开这个地址如果你是SSH远程连接需要做端口转发比如ssh -L 4455:localhost:4455 你的服务器用户名服务器IP然后在本地浏览器里打开http://localhost:4455就能看到授权页面。用你的ClawID账号登录或者在页面上注册一个新账号然后点击授权设备。完成这一步后控制台日志会显示设备绑定成功这时候OpenClaw才算真正“活”了。这个环节我当初卡了很久因为日志里关于这个认证页面的提示夹杂在其他启动信息里不仔细看就漏过去了。建议大家在npm start之后把日志刷到底看到Please visit http://localhost:4455这行字再操作。4. 企业微信接入真正的重头戏4.1 先用一句话分清企微三种接入方式企业微信和OpenClaw对接首先得搞明白接入方式因为很多人分不清导致消息收不到。企业微信目前有三种常见的机器人接入形态企业内部自建应用在企业的自建应用里创建一个机器人企业内部员工可以通过私聊或群聊它。这种方式适合公司内部使用配置最正规权限控制最完善。企业微信群机器人智能机器人在群聊里添加一个Webhook机器人只能主动往群里推送消息不能接收群里成员发给它的消息需要配合回调能力或者使用智能机器人模式才能交互。企微客服/外部联系人针对企业外部客户用于客服场景OpenClaw也能接入但需要企业认证配置复杂度更高个人开发者不建议折腾这个。OpenClaw官方文档里明确支持的是第一种“企业内部自建应用”模式这也是最稳定、功能最全的接入方式。本文接下来的内容都基于这种方式展开。4.2 企业内部应用的完整配置流程登录企业微信管理后台地址是https://work.weixin.qq.com/wework_admin/frame。注意这个是企业微信网页版管理后台不是个人微信也不是企业微信客户端别走错门。在管理后台左侧菜单找到“应用管理”然后在“自建”区域点击“创建应用”。填上应用名称比如“AI助理”、应用Logo、可见范围建议先选一个小范围的测试部门创建完成之后你会得到两个关键参数AgentId应用的唯一标识在应用详情页能看到。Secret应用的密钥在应用详情页点击“查看”按钮获取这个值必须保密代码里不要明文写死。同时还必须拿到企业本身的CorpID在企业微信管理后台的“我的企业”页面底部能看到。这三个参数CorpID、AgentId、Secret是OpenClaw接入企业微信的身份凭证缺一不可。接下来要设置“企业可信IP”。在应用详情页找到“企业可信IP”配置项把你的服务器公网IP填进去。这一步很关键因为企业微信API会校验调用方的IP只有出现在可信IP列表里的服务器才能调用发消息的接口。如果没填或者填错后面发消息时会一直报invalid ip错误。最后是最关键的一步“接收消息服务器配置”。在应用详情页找到“接收消息”区域点击“设置API接收”填三个参数URL填你服务器上OpenClaw的Webhook回调地址格式类似https://你的域名:9000/clawid/wecom。如果你没有域名想用IP直连也可以填http://你的IP:9000/clawid/wecom但企业微信要求必须是公网可达的地址。Token自定义一串随机字符串比如myOpenClawToken2024。EncodingAESKey点击“随机获取”按钮生成也可以自己填43位随机字符。填好之后点击保存企业微信服务器会立即往你的URL发一条验证请求如果OpenClaw已经在运行并且回调路径正确验证会自动通过。这里我再提醒一句如果服务器在NAT后面没有公网IP就需要先用frp或者cpolar做内网穿透把9000端口映射出去。开发调试阶段用穿透没问题但生产环境还是建议用带公网IP的服务器穿透方案不稳定的话回调会断。4.3 消息回调与收发机制配置完回调URL之后需要把OpenClaw应用配置里对应的企业微信参数填上。在OpenClaw的config.main.json里找到企业微信相关的配置块填入上面拿到的CorpID、AgentId、Secret、Token、EncodingAESKey。这里解释一下企业微信消息回调的原理理解了它你后面排查问题会轻松得多。企业微信服务器扮演的是“中转站”角色员工A在企业微信里给机器人发了一条消息企业微信服务器收到后会对消息体做AES加密然后往你配置的URL发起一个POST请求。OpenClaw收到这个请求后用EncodingAESKey解密还原出真实消息内容再交给大模型处理。OpenClaw生成回复后调用企业微信的“发送应用消息”API带上你的Secret和AgentId把消息推送回去员工A就收到了回复。这个机制意味着你的服务器必须实时在线并且公网可达一旦端口不通或者进程挂了消息就会堆积在企业微信服务器端恢复后也不会自动补发设计上就是让AI主动调API主动推消息而不是做消息队列。这也就是为什么我反复强调要用pm2守护进程保证7x24在线的原因。4.4 群聊与私聊的权限控制企业微信机器人接入完成后会遇到一个非常现实的问题它在群里会不会乱回复默认情况下OpenClaw对私聊消息是全量响应的任何人私聊机器人都能得到回复。群聊则不同有两种触发机制一种是**机器人才响应另一种是设置命令前缀**比如!或/开头才响应。我强烈建议群聊模式设置为“机器人或命令前缀触发”避免群里大家都在聊天时机器人插嘴刷屏。OpenClaw还有一个辅助功能值得提一下在配置里可以设置“仅允许指定用户或部门使用”。企业微信返回的消息里会带上发送人的UserIDOpenClaw可以根据这个字段做白名单。比如你只希望技术部的同事能用AI助理其余部门的人发了消息直接忽略就在配置里加上对应的UserID或部门ID列表即可。5. 常见问题排查与避坑速查表5.1 安装阶段常见问题整个安装过程中我见过和亲身踩过的问题不少按出现频率排个序问题一npm install过程报ERR说缺python或者node-gyp。这个基本就是系统缺少编译工具链补齐依赖再重装就好sudo apt install -y build-essential python3 npm rebuild问题二启动时Chromium报错提示找不到libgbm.so.1。这个前面提过就是缺Puppeteer的系统依赖库。一次性装齐所有可能用到的库装完之后重启OpenClaw。问题三npm install下载速度慢到怀疑人生。国内服务器先把npm源切到npmmirror能快一个量级。另外还要注意OpenClaw下载Chromium的时候走的是Puppeteer的下载地址这个地址在npm install时会单独下载一个浏览器压缩包也很容易卡住。可以把Puppeteer的下载源也换成国内镜像export PUPPETEER_DOWNLOAD_BASE_URLhttps://npmmirror.com/mirrors/chromium-browser-snapshots问题四端口冲突9000端口被别的服务占了。用sudo netstat -tlnp | grep 9000检查端口占用如果有别的服务占着改OpenClaw配置里的端口号即可。5.2 企业微信接入阶段常见问题问题一保存回调URL时企业微信提示“验证失败”。先从三个维度排查第一你的URL是否真的公网可达可以在服务器上执行curl -I http://你的域名:9000确认第二Token和EncodingAESKey是否和config.main.json里的配置完全一致注意EncodingAESKey是43位别漏字符第三OpenClaw日志里有没有收到这次验证请求的记录如果压根没有请求进来那就是网络层的问题。问题二消息能收到但OpenClaw回复发不出去。先看日志里有没有invalid ip相关报错如果有就是企业可信IP没配好回管理后台把当前服务器的出口IP加进去。注意服务器最好用固定的公网IP如果IP是动态的频繁变更会让API调用时灵时不灵。问题三群里机器人它不理人。这个大概率是触发方式配置问题。OpenClaw默认在群聊里要求消息以命令前缀开头或者包含机器人的字段检查一下配置里的群聊触发条件并且确认机器人已经被添加到目标群里。注意自建应用机器人需要群主在企业微信群里主动添加不是所有群自动有的。问题四OpenClaw收到了消息但回复内容质量差或者胡乱回答。这个跟接入没关系是模型选择问题。默认的Clawnet API用的模型可能是通用型换成DeepSeek或者Kimi这种中文能力强的模型会好很多。在config.main.json里改一下模型配置重启服务即可。5.3 运行时稳定与安全建议OpenClaw这类AI Agent服务长期运行之后会有一些“慢性病”需要提前预防。内存泄漏与Swap占用Node.js服务和Chromium子进程跑久了内存会缓慢增长我建议在pm2配置里加一个内存超限自动重启的规则当进程内存超过1.5GB时自动重启。虽然会中断当前正在执行的任务但总比整个服务器卡死强。日志膨胀OpenClaw的日志会记录所有对话内容和任务执行细节时间长了会占大量磁盘空间。配置里可以设置日志轮转或者用logrotate定期清理。建议保留7-14天日志即可。敏感信息保护企业微信回调的Token、EncodingAESKey、API密钥以及对话内容本身都很敏感。千万不要把config.main.json直接提交到Git仓库或者公开博客里。用系统环境变量存储密钥配置文件里用${VARIABLE_NAME}引用是更安全的做法。防火墙与访问控制服务器防火墙只对外开放需要用到的端口比如企业微信回调的9000端口其他端口一律白名单模式。ClawID本地认证页面的4455端口千万不能暴露到公网否则任何人都可能绑定你的设备。如果必须远程访问认证页面用SSH隧道。6. 开机自启与长期稳定运行6.1 用pm2接管OpenClaw进程直接用npm start跑服务SSH断开或者服务器一重启OpenClaw就没了这显然不行。生产环境我推荐用pm2做进程守护npm install -g pm2 cd /opt/openclaw pm2 start npm --name openclaw -- start pm2 savepm2 save会把当前进程状态存下来。然后执行pm2 startup这个命令会在系统里生成一条开机自启的systemd任务执行完之后把提示里的那一长串命令复制到终端里跑一遍pm2就注册成了系统服务。以后服务器开机pm2会自动拉起OpenClaw。几个高频使用的pm2命令整理一下操作命令查看进程状态和日志pm2 status openclaw实时追踪日志pm2 logs openclaw --lines 100重启服务pm2 restart openclaw停止服务pm2 stop openclaw结合前面的内存超限保护可以给OpenClaw设置一个最大内存限制超出自动重启pm2 start npm --name openclaw -- start --max-memory-restart 1500M6.2 日志怎么查才高效排障第一步永远是看日志。OpenClaw的日志分为两块pm2捕获的标准输出/错误日志以及OpenClaw自己在data/logs目录下生成的应用日志。查询某个具体时间段内企业微信回调是否正常收到用grep过滤是最快的grep wecom /opt/openclaw/data/logs/*.log | tail -n 50如果是排查回调地址是否被访问看pm2日志里的请求记录pm2 logs openclaw --lines 200 | grep clawid/wecom日志里看到HTTP 200说明回调正常看到401或403则往密钥和签名方向排查。6.3 可选扩展接入本地Ollama模型把对话数据留在本地不少朋友对把企业内部对话数据发给第三方大模型API有顾虑所以我在这里介绍一下OpenClaw配合Ollama本地模型的用法。前提是服务器上已经装了Ollama并且拉取好了模型比如qwen2.5:7bollama pull qwen2.5:7b然后确认Ollama的API服务在监听localhost:11434Ollama默认就是。在OpenClaw的config.main.json里把模型配置改成{ model: { provider: ollama, baseUrl: http://localhost:11434/v1, model: qwen2.5:7b, apiKey: ollama } }注意Ollama的/v1端点也是OpenAI兼容的所以OpenClaw不需要额外插件就能对接。改完重启OpenClawpm2 restart openclaw本地模型的好处是数据不出内网、没有API费用代价是回复速度和效果明显不如云端大模型70亿参数级别的模型应对简单任务可以复杂推理容易露怯。所以我的建议是日常办公问答、信息查询这种任务用云端API涉及敏感数据或者纯粹内部知识库的场景切到本地模型灵活切换才是最优解。写在最后的一点个人体会整套部署流程走下来最大的感受是OpenClaw这个项目的组件划分很清晰安装过程虽然链条长但只要理解了它就是“主服务浏览器内核数据库IM通道”的组合每一步都不会觉得莫名其妙。我自己在实际使用中最顺手的组合是Ubuntu 22.04 Node 20 pm2守护 DeepSeek API跑推理 企业微信自建应用接收消息这套组合我跑了几个月稳定性足够高。最后再分享两个小技巧。第一个是我后来才发现的OpenClaw的技能Skills可以自定义扩展比如写一个“查天气”的技能、写一个“翻译文件”的技能把常用的Prompt工程封装到config.skills.json里机器人就从一个“聊天模型”真正变成一个“能干活儿的工具人”。第二个是建议新手第一天上手时别急着配企业微信先用网页端的ClawID聊天界面测试OpenClaw本身是否正常再接入企微这样能隔离变量排查问题省一半时间。等这些都跑通了你就可以开始琢磨怎么让这个数字员工帮你处理日报、盯监控、回邮件了那又是另一个很有意思的话题了。