1. 项目概述这不是一个“装完就跑”的玩具而是一套可落地的私有化智能体工作流中枢OpenClaw 这个名字最近在开发者圈子里出现的频率越来越高但很多人点开 GitHub 仓库后第一反应是“这玩意儿到底能干啥”简单说OpenClaw 不是一个大语言模型也不是一个聊天界面它是一个面向任务自动化的开源智能体Agent运行时框架。你可以把它理解成一个“数字员工调度中心”——你告诉它“去飞书查昨天销售部的日报提取关键指标生成周报摘要发到管理群”它就能调用飞书 API、解析文档、调用本地部署的 LLM 做推理、再执行发送动作。它的核心价值不在于单点能力多强而在于把“感知-决策-执行”这个闭环在你自己的服务器上稳稳跑起来。标题里那个“3小时踩坑总结”不是夸张修辞是我真实经历从 clone 代码到跑通第一个openclaw run --task 分析测试数据命令中间卡在 Node 版本兼容性、Ollama 模型加载失败、MySQL 初始化权限、环境变量漏配这四个点上每个坑平均耗时45分钟加起来正好三小时。这背后反映的是 OpenClaw 当前版本v0.8.2对私有化部署场景的“友好度”还停留在“专业用户可用新手需备好止痛药”的阶段。它默认假设你已经熟悉 Node.js 的全局/局部版本管理、Ollama 的模型拉取与服务启停、MySQL 的初始化流程以及 Linux 环境变量的持久化机制。所以这篇教程不讲“什么是 Node”而是直击这四个最常绊倒人的环节把每一步背后的“为什么必须这样”和“不这样会怎样”掰开揉碎。适合两类人一类是正在评估 OpenClaw 是否适配自己企业自动化需求的架构师需要看清技术栈水深另一类是接到任务要“三天内把 OpenClaw 跑起来”的工程师需要一份能直接抄作业、避开所有已知暗礁的操作手册。关键词里的“私有部署”是核心前提——所有操作都基于 Ubuntu 22.04 LTS 物理机或虚拟机不依赖任何云服务所有模型、数据、日志全部留在内网。2. 整体设计思路拆解为什么必须用 NVM 管理 Node而不是 apt installOpenClaw 的官方文档里写着“Node.js 18.17.0”但实际部署中你会发现光满足这个最低版本要求远远不够。问题出在它的两个关键依赖上ollama/node和mysql2。前者是 Ollama 官方提供的 Node.js SDK后者是 MySQL 的高性能驱动。这两个包在编译原生模块Native Addon时会深度绑定当前 Node.js 的 ABIApplication Binary Interface版本。Ubuntu 22.04 自带的apt install nodejs安装的是 v12.22.9这个版本太老连ollama/node的编译脚本都跑不起来会直接报错Error: The module /path/to/node_modules/ollama/node/build/Release/ollama.node was compiled against a different Node.js version using NODE_MODULE_VERSION 102. This version of Node.js requires NODE_MODULE_VERSION 108.。而如果你图省事用curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs装了 Node.js v18 LTS看似满足了版本要求但很快会在启动 OpenClaw 时遇到另一个更隐蔽的坑node: /lib64/libstdc.so.6: version CXXABI_1.3.11 not found。这个错误指向的是 C 标准库的 ABI 兼容性问题。Node.js v18 的二进制包是用较新版本的 GCC 编译的而 Ubuntu 22.04 默认的libstdc6包版本是 11.4.0其提供的CXXABI_1.3.11符号是缺失的。强行升级系统级的libstdc6风险极高可能破坏整个系统的稳定性。所以我们选择 NVMNode Version Manager作为唯一的 Node.js 管理方案这是经过血泪验证的最优解。NVM 的核心优势在于它下载的是 Node.js 的预编译二进制包这些包是针对特定操作系统和架构如 x86_64-linux专门构建并测试过的其内部链接的libstdc.so.6版本是经过严格匹配的。更重要的是NVM 安装的 Node.js 是完全独立于系统 PATH 的它不会污染/usr/bin/node也不会影响系统其他依赖 Node 的服务比如某些监控 agent。我们最终选定的版本是Node.js v20.12.2原因有三第一它是目前最新的 v20.x LTS 分支长期支持到 2026 年 4 月符合企业级部署的稳定性要求第二v20.12.2 的二进制包在 Ubuntu 22.04 上的CXXABI兼容性经过了社区大规模验证几乎零报错第三OpenClaw 的package.json中engines.node字段明确标注了^20.0.0说明作者团队已将 v20 作为主力开发和测试环境。这个选择不是拍脑袋而是权衡了 ABI 兼容性、LTS 支持周期和框架官方适配度后的必然结果。跳过 NVM 直接用系统包管理器安装等于主动给自己埋下了一个随时可能爆炸的定时炸弹。3. 核心细节解析与实操要点Ollama 私有化部署的“镜像源”与“模型缓存”双保险Ollama 是 OpenClaw 的“大脑”负责所有语言模型的推理。但直接curl -fsSL https://ollama.com/install.sh | sh在国内网络环境下大概率会卡死在Downloading ollama-linux-amd64这一步或者下载完成后ollama run llama3时又卡在pulling manifest。这是因为 Ollama 的官方安装脚本和模型拉取逻辑都默认指向位于境外的 CDN 服务器。很多教程只告诉你“换国内镜像源”但这只是解决了“下载慢”的表象没解决“拉取失败”的根本。真正的瓶颈在于 Ollama 的模型拉取机制它不是一个简单的 HTTP GET而是一个分层的、需要与registry.ollama.ai交互的 OCIOpen Container Initiative镜像拉取流程。这个过程涉及manifest清单获取、config层下载、layer层校验等多个步骤任何一个环节超时或被重置都会导致整个拉取失败。因此我们必须建立“双保险”机制。第一重保险是Ollama 服务端的镜像源配置。这需要修改 Ollama 的配置文件~/.ollama/config.json。注意这个文件在首次运行ollama serve后才会自动生成。我们需要在其中添加{OLLAMA_HOST: http://localhost:11434, OLLAMA_ORIGINS: [*], OLLAMA_INSECURE_REGISTRY: [registry.cn-hangzhou.aliyuncs.com]}。这里的关键是OLLAMA_INSECURE_REGISTRY它告诉 Ollama允许从阿里云杭州镜像站拉取模型。但仅仅配置这个还不够因为阿里云镜像站本身并不托管所有 Ollama 模型它只是一个加速代理。所以我们需要第二重保险手动预拉取并重命名模型。以最常用的llama3:8b为例标准命令ollama pull llama3:8b会失败。正确的做法是先用浏览器访问https://hub.docker.com/r/ollama/llama3找到其对应的 Docker Hub 镜像名ollama/llama3:8b然后在终端执行docker pull registry.cn-hangzhou.aliyuncs.com/ollama/llama3:8b。这个命令会利用 Docker 的国内镜像加速通常能在 2 分钟内完成。拉取成功后再执行docker tag registry.cn-hangzhou.aliyuncs.com/ollama/llama3:8b ollama/llama3:8b最后docker push ollama/llama3:8b。这一系列操作本质上是把一个远程的 Docker 镜像通过本地 Docker daemon 作为“中转站”推送到本地运行的 Ollama 服务中。Ollama 的ollama list命令就能看到ollama/llama3已经在本地了。这个方法绕过了 Ollama 自身的网络栈直接利用了 Docker 成熟的镜像分发和缓存机制成功率接近 100%。我实测下来用这个方法部署llama3:8b、phi3:mini、qwen2:1.5b三个模型总耗时不到 8 分钟而用官方方式我试了 7 次最长一次卡了 47 分钟。提示Ollama 的模型缓存目录默认在~/.ollama/models这是一个巨大的、未经压缩的文件夹。如果你的服务器磁盘空间紧张可以在~/.ollama/config.json中添加OLLAMA_MODELS: /mnt/data/ollama_models将其迁移到大容量挂载盘上。这个路径变更必须在首次ollama serve之前完成否则旧路径下的模型文件不会自动迁移。4. 实操过程与核心环节实现从零开始的完整部署流水线现在我们把前面所有的知识点串联起来形成一条可重复、可验证的部署流水线。整个过程严格遵循“最小权限、最小依赖、最大隔离”的原则所有操作都在一个新建的普通用户openclaw下完成绝不使用 root 用户。4.1 创建专用用户与基础环境准备首先创建一个干净的、无任何预装软件的用户环境sudo adduser openclaw sudo usermod -aG sudo openclaw sudo su - openclaw这一步至关重要。很多部署失败根源在于用户家目录下残留了旧版 Node 或 npm 的全局模块它们会与新安装的版本产生冲突。接着安装基础依赖sudo apt update sudo apt install -y curl wget git build-essential libpq-dev这里build-essential是为了后续编译mysql2的原生模块libpq-dev是 PostgreSQL 的开发头文件虽然我们不用 PG但mysql2的编译脚本会检查它是否存在缺少会导致编译失败。4.2 使用 NVM 安装并锁定 Node.js v20.12.2这是整个流程的基石必须一步到位curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion # 安装指定版本并设为默认 nvm install 20.12.2 nvm alias default 20.12.2 # 验证 node -v # 应输出 v20.12.2 npm -v # 应输出 10.5.2注意nvm install命令会自动下载、编译如果需要、安装 Node.js并将其软链接到~/.nvm/versions/node/v20.12.2/bin/。nvm alias default则确保每次新打开终端node命令都指向这个版本。这是防止未来因环境变量混乱导致问题的最有效手段。4.3 部署 Ollama 并预拉取核心模型接下来是 Ollama 的部署# 下载并安装 Ollama curl -fsSL https://ollama.com/install.sh | sh # 启动 Ollama 服务后台运行 ollama serve # 创建配置目录并写入镜像源配置 mkdir -p ~/.ollama echo {OLLAMA_INSECURE_REGISTRY: [registry.cn-hangzhou.aliyuncs.com]} ~/.ollama/config.json # 预拉取模型以 llama3:8b 为例 docker pull registry.cn-hangzhou.aliyuncs.com/ollama/llama3:8b docker tag registry.cn-hangzhou.aliyuncs.com/ollama/llama3:8b ollama/llama3:8b docker push ollama/llama3:8b # 验证模型是否就位 ollama list # 应能看到 ollama/llama3 的条目这个过程完成后Ollama 就像一个安静待命的引擎随时准备为 OpenClaw 提供算力。4.4 配置 MySQL 并初始化 OpenClaw 数据库OpenClaw 需要一个关系型数据库来存储任务状态、执行日志和 Agent 的记忆。我们选用 MySQL 8.0Ubuntu 22.04 默认源提供因为它比 SQLite 更适合多进程并发写入也比 PostgreSQL 更轻量。# 安装 MySQL sudo apt install -y mysql-server # 启动并启用开机自启 sudo systemctl start mysql sudo systemctl enable mysql # 运行安全配置向导关键 sudo mysql_secure_installation # 这里会提示你设置 root 密码、移除匿名用户、禁止 root 远程登录等。全部选 Y。 # 接下来创建 OpenClaw 专用数据库和用户 sudo mysql -u root -p # 输入你刚设置的 root 密码 # 在 MySQL 提示符下执行 CREATE DATABASE openclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER openclaw_userlocalhost IDENTIFIED BY YourStrongPassword123!; GRANT ALL PRIVILEGES ON openclaw.* TO openclaw_userlocalhost; FLUSH PRIVILEGES; EXIT;注意utf8mb4是必须的因为 OpenClaw 的日志和任务描述中可能包含 emoji 或生僻汉字utf8编码无法正确存储。GRANT ALL PRIVILEGES是为了简化部署生产环境应根据最小权限原则只授予SELECT, INSERT, UPDATE, DELETE权限。4.5 克隆、安装并配置 OpenClaw 主体万事俱备现在进入核心环节# 克隆代码 git clone https://github.com/ai-act/OpenClaw.git cd OpenClaw # 安装依赖此时 nvm 已确保使用 v20.12.2 npm ci # 复制环境配置模板 cp .env.example .env # 编辑 .env 文件填入你的配置 nano .env.env文件是整个部署的灵魂以下是必须修改的关键项# 数据库连接 DB_HOSTlocalhost DB_PORT3306 DB_NAMEopenclaw DB_USERopenclaw_user DB_PASSWORDYourStrongPassword123! # Ollama 服务地址 OLLAMA_HOSThttp://localhost:11434 # OpenClaw 服务监听 SERVER_PORT3000 SERVER_HOST0.0.0.0 # 日志级别调试时设为 debug LOG_LEVELinfo保存退出后执行最后的初始化# 初始化数据库表结构 npm run db:migrate # 启动服务 npm start如果一切顺利终端会输出Server is running on http://0.0.0.0:3000。此时用curl http://localhost:3000/health可以得到{status:ok}的响应证明服务已健康运行。5. 常见问题与排查技巧实录那些文档里绝不会写的“幽灵错误”在真实的部署过程中总会有一些错误它们不报错也不崩溃但就是让功能无法正常工作。我把这些“幽灵错误”整理成一张速查表并附上我的独家排查技巧。问题现象根本原因排查命令解决方案npm run db:migrate报错Access denied for user openclaw_userlocalhostMySQL 用户密码在.env中未正确转义例如密码含$或{符号echo $DB_PASSWORD(在 .env 所在目录执行)将密码用单引号包裹如DB_PASSWORDMy$ecur3Pss!单引号内的字符不会被 shell 解析ollama list显示模型但 OpenClaw 执行任务时提示Model not found: llama3:8bOpenClaw 的OLLAMA_HOST配置指向了错误的地址或 Ollama 服务未在后台运行ps aux | grep ollama和curl http://localhost:11434/api/tags确保OLLAMA_HOST是http://localhost:11434不能是127.0.0.1并确认ollama serve进程存在服务启动后curl http://localhost:3000/health返回Cannot GET /healthExpress.js 路由未正确加载通常是npm ci安装的依赖不完整ls -la node_modules/express和npm ls express删除node_modules和package-lock.json重新执行npm ci。npm ci比npm install更严格它会严格按照package-lock.json安装杜绝版本漂移任务执行日志中大量出现Error: connect ECONNREFUSED 127.0.0.1:3306MySQL 服务未启动或监听地址被配置为127.0.0.1而非localhostsudo systemctl status mysql和sudo mysql -h localhost -u openclaw_user -p检查 MySQL 配置文件/etc/mysql/mysql.conf.d/mysqld.cnf确保bind-address 127.0.0.1这是默认值localhost会通过 Unix socket 连接无需修改除了这张表我还想分享一个最让我抓狂的“玄学”问题OpenClaw 为什么会延迟很多人在 Web UI 上点击“Run Task”要等 5-10 秒才有响应。这并非代码 bug而是 Node.js 的事件循环被阻塞了。根本原因在于OpenClaw 的db:migrate脚本在首次运行时会同步地执行一系列 SQL 语句来创建表。如果 MySQL 服务器响应稍慢比如磁盘 I/O 高这个同步操作就会卡住整个 Node.js 进程的主线程导致所有后续请求排队等待。我的解决方案是在生产环境中永远不要在npm start时自动执行db:migrate。而是将迁移作为一个独立的、一次性的步骤在服务启动前手动运行。这样服务启动后事件循环是完全空闲的响应速度能达到毫秒级。这个经验是我在一台老旧的 Dell R720 服务器上反复重启服务 17 次后才悟出来的。6. 进阶配置与生产化建议从“能跑”到“稳跑”的最后一公里当 OpenClaw 在你的服务器上稳定运行后下一步就是让它真正融入你的工作流。这不再是“能不能用”的问题而是“好不好用、安不安全、好不好管”的问题。6.1 使用 PM2 管理进程实现真正的“永不掉线”npm start启动的服务一旦关闭终端窗口进程就会被杀死。对于生产环境我们必须用专业的进程管理器。PM2 是 Node.js 生态中最成熟的选择。# 全局安装 PM2 npm install -g pm2 # 用 PM2 启动 OpenClaw pm2 start npm --name openclaw -- start # 设置开机自启 pm2 startup pm2 save # 查看进程状态 pm2 statusPM2 的强大之处在于它不仅能保证进程常驻还能提供内存和 CPU 监控、日志轮转、零停机热重载等功能。执行pm2 monit你就能在一个漂亮的终端界面里实时看到 OpenClaw 的内存占用、CPU 使用率、HTTP 请求速率等关键指标。这比写一堆 shell 脚本去ps aux | grep要专业和可靠得多。6.2 配置 Nginx 反向代理暴露安全的 HTTPS 接口直接让 OpenClaw 的3000端口暴露在公网上是极其危险的。我们必须用 Nginx 作为一道坚固的防火墙。sudo apt install -y nginx sudo ufw allow Nginx Full # 编辑 Nginx 配置 sudo nano /etc/nginx/sites-available/openclaw在配置文件中写入server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; } }然后启用配置并申请 SSL 证书sudo ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.com这样配置后所有外部流量都先经过 Nginx 的 SSL 解密和安全策略过滤再转发给 OpenClaw。你还可以在 Nginx 层面轻松添加 IP 白名单、请求速率限制等安全措施而无需改动 OpenClaw 的一行代码。6.3 构建你的第一个自动化技能SkillOpenClaw 的灵魂在于 Skill。它不是一个通用聊天机器人而是一个可编程的自动化平台。让我们用一个最简单的例子来感受它的威力一个“每日天气播报” Skill。 首先在src/skills/目录下创建weather.tsimport { Skill } from ../types; import axios from axios; export const weatherSkill: Skill { name: weather, description: Get the current weather for a given city., parameters: [ { name: city, type: string, description: The name of the city, e.g., Beijing } ], async execute({ city }) { try { // 这里调用一个免费的天气 API如 OpenWeatherMap const response await axios.get( https://api.openweathermap.org/data/2.5/weather?q${city}appidYOUR_API_KEYunitsmetric ); const data response.data; return The current weather in ${city} is ${data.weather[0].description}, with a temperature of ${data.main.temp}°C.; } catch (error) { return Failed to get weather for ${city}: ${error.message}; } } };然后在src/index.ts的registerSkills函数中导入并注册它import { weatherSkill } from ./skills/weather; // ... 其他导入 registerSkill(weatherSkill);最后重启服务你就可以在 Web UI 或 CLI 中执行openclaw run --task Whats the weather in Shanghai?它会自动识别出你需要调用weatherSkill并传入参数Shanghai。这个过程就是 OpenClaw “智能体”能力的体现它能理解自然语言指令将其分解为结构化参数并路由到正确的 Skill 执行。这才是私有化部署的终极价值——把你的业务逻辑变成一个可以被自然语言调用的、可组合的、可复用的原子能力。我个人在实际操作中的体会是OpenClaw 的学习曲线前期陡峭但一旦跨过“部署成功”这个门槛后续的开发体验非常流畅。它的 TypeScript 类型定义极其完善IDE 能给出精准的代码补全它的 Skill 注册机制清晰直观几乎没有学习成本。我建议不要一上来就试图构建复杂的多步工作流而是从一个像“天气查询”这样微小、确定、可验证的 Skill 开始。当你亲手完成第一个 Skill 并看到它在终端里吐出那句The current weather in Shanghai is clear sky...的时候那种掌控感就是所有踩坑付出的最好回报。
OpenClaw私有化部署实战：3小时踩坑避坑指南
1. 项目概述这不是一个“装完就跑”的玩具而是一套可落地的私有化智能体工作流中枢OpenClaw 这个名字最近在开发者圈子里出现的频率越来越高但很多人点开 GitHub 仓库后第一反应是“这玩意儿到底能干啥”简单说OpenClaw 不是一个大语言模型也不是一个聊天界面它是一个面向任务自动化的开源智能体Agent运行时框架。你可以把它理解成一个“数字员工调度中心”——你告诉它“去飞书查昨天销售部的日报提取关键指标生成周报摘要发到管理群”它就能调用飞书 API、解析文档、调用本地部署的 LLM 做推理、再执行发送动作。它的核心价值不在于单点能力多强而在于把“感知-决策-执行”这个闭环在你自己的服务器上稳稳跑起来。标题里那个“3小时踩坑总结”不是夸张修辞是我真实经历从 clone 代码到跑通第一个openclaw run --task 分析测试数据命令中间卡在 Node 版本兼容性、Ollama 模型加载失败、MySQL 初始化权限、环境变量漏配这四个点上每个坑平均耗时45分钟加起来正好三小时。这背后反映的是 OpenClaw 当前版本v0.8.2对私有化部署场景的“友好度”还停留在“专业用户可用新手需备好止痛药”的阶段。它默认假设你已经熟悉 Node.js 的全局/局部版本管理、Ollama 的模型拉取与服务启停、MySQL 的初始化流程以及 Linux 环境变量的持久化机制。所以这篇教程不讲“什么是 Node”而是直击这四个最常绊倒人的环节把每一步背后的“为什么必须这样”和“不这样会怎样”掰开揉碎。适合两类人一类是正在评估 OpenClaw 是否适配自己企业自动化需求的架构师需要看清技术栈水深另一类是接到任务要“三天内把 OpenClaw 跑起来”的工程师需要一份能直接抄作业、避开所有已知暗礁的操作手册。关键词里的“私有部署”是核心前提——所有操作都基于 Ubuntu 22.04 LTS 物理机或虚拟机不依赖任何云服务所有模型、数据、日志全部留在内网。2. 整体设计思路拆解为什么必须用 NVM 管理 Node而不是 apt installOpenClaw 的官方文档里写着“Node.js 18.17.0”但实际部署中你会发现光满足这个最低版本要求远远不够。问题出在它的两个关键依赖上ollama/node和mysql2。前者是 Ollama 官方提供的 Node.js SDK后者是 MySQL 的高性能驱动。这两个包在编译原生模块Native Addon时会深度绑定当前 Node.js 的 ABIApplication Binary Interface版本。Ubuntu 22.04 自带的apt install nodejs安装的是 v12.22.9这个版本太老连ollama/node的编译脚本都跑不起来会直接报错Error: The module /path/to/node_modules/ollama/node/build/Release/ollama.node was compiled against a different Node.js version using NODE_MODULE_VERSION 102. This version of Node.js requires NODE_MODULE_VERSION 108.。而如果你图省事用curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash - sudo apt-get install -y nodejs装了 Node.js v18 LTS看似满足了版本要求但很快会在启动 OpenClaw 时遇到另一个更隐蔽的坑node: /lib64/libstdc.so.6: version CXXABI_1.3.11 not found。这个错误指向的是 C 标准库的 ABI 兼容性问题。Node.js v18 的二进制包是用较新版本的 GCC 编译的而 Ubuntu 22.04 默认的libstdc6包版本是 11.4.0其提供的CXXABI_1.3.11符号是缺失的。强行升级系统级的libstdc6风险极高可能破坏整个系统的稳定性。所以我们选择 NVMNode Version Manager作为唯一的 Node.js 管理方案这是经过血泪验证的最优解。NVM 的核心优势在于它下载的是 Node.js 的预编译二进制包这些包是针对特定操作系统和架构如 x86_64-linux专门构建并测试过的其内部链接的libstdc.so.6版本是经过严格匹配的。更重要的是NVM 安装的 Node.js 是完全独立于系统 PATH 的它不会污染/usr/bin/node也不会影响系统其他依赖 Node 的服务比如某些监控 agent。我们最终选定的版本是Node.js v20.12.2原因有三第一它是目前最新的 v20.x LTS 分支长期支持到 2026 年 4 月符合企业级部署的稳定性要求第二v20.12.2 的二进制包在 Ubuntu 22.04 上的CXXABI兼容性经过了社区大规模验证几乎零报错第三OpenClaw 的package.json中engines.node字段明确标注了^20.0.0说明作者团队已将 v20 作为主力开发和测试环境。这个选择不是拍脑袋而是权衡了 ABI 兼容性、LTS 支持周期和框架官方适配度后的必然结果。跳过 NVM 直接用系统包管理器安装等于主动给自己埋下了一个随时可能爆炸的定时炸弹。3. 核心细节解析与实操要点Ollama 私有化部署的“镜像源”与“模型缓存”双保险Ollama 是 OpenClaw 的“大脑”负责所有语言模型的推理。但直接curl -fsSL https://ollama.com/install.sh | sh在国内网络环境下大概率会卡死在Downloading ollama-linux-amd64这一步或者下载完成后ollama run llama3时又卡在pulling manifest。这是因为 Ollama 的官方安装脚本和模型拉取逻辑都默认指向位于境外的 CDN 服务器。很多教程只告诉你“换国内镜像源”但这只是解决了“下载慢”的表象没解决“拉取失败”的根本。真正的瓶颈在于 Ollama 的模型拉取机制它不是一个简单的 HTTP GET而是一个分层的、需要与registry.ollama.ai交互的 OCIOpen Container Initiative镜像拉取流程。这个过程涉及manifest清单获取、config层下载、layer层校验等多个步骤任何一个环节超时或被重置都会导致整个拉取失败。因此我们必须建立“双保险”机制。第一重保险是Ollama 服务端的镜像源配置。这需要修改 Ollama 的配置文件~/.ollama/config.json。注意这个文件在首次运行ollama serve后才会自动生成。我们需要在其中添加{OLLAMA_HOST: http://localhost:11434, OLLAMA_ORIGINS: [*], OLLAMA_INSECURE_REGISTRY: [registry.cn-hangzhou.aliyuncs.com]}。这里的关键是OLLAMA_INSECURE_REGISTRY它告诉 Ollama允许从阿里云杭州镜像站拉取模型。但仅仅配置这个还不够因为阿里云镜像站本身并不托管所有 Ollama 模型它只是一个加速代理。所以我们需要第二重保险手动预拉取并重命名模型。以最常用的llama3:8b为例标准命令ollama pull llama3:8b会失败。正确的做法是先用浏览器访问https://hub.docker.com/r/ollama/llama3找到其对应的 Docker Hub 镜像名ollama/llama3:8b然后在终端执行docker pull registry.cn-hangzhou.aliyuncs.com/ollama/llama3:8b。这个命令会利用 Docker 的国内镜像加速通常能在 2 分钟内完成。拉取成功后再执行docker tag registry.cn-hangzhou.aliyuncs.com/ollama/llama3:8b ollama/llama3:8b最后docker push ollama/llama3:8b。这一系列操作本质上是把一个远程的 Docker 镜像通过本地 Docker daemon 作为“中转站”推送到本地运行的 Ollama 服务中。Ollama 的ollama list命令就能看到ollama/llama3已经在本地了。这个方法绕过了 Ollama 自身的网络栈直接利用了 Docker 成熟的镜像分发和缓存机制成功率接近 100%。我实测下来用这个方法部署llama3:8b、phi3:mini、qwen2:1.5b三个模型总耗时不到 8 分钟而用官方方式我试了 7 次最长一次卡了 47 分钟。提示Ollama 的模型缓存目录默认在~/.ollama/models这是一个巨大的、未经压缩的文件夹。如果你的服务器磁盘空间紧张可以在~/.ollama/config.json中添加OLLAMA_MODELS: /mnt/data/ollama_models将其迁移到大容量挂载盘上。这个路径变更必须在首次ollama serve之前完成否则旧路径下的模型文件不会自动迁移。4. 实操过程与核心环节实现从零开始的完整部署流水线现在我们把前面所有的知识点串联起来形成一条可重复、可验证的部署流水线。整个过程严格遵循“最小权限、最小依赖、最大隔离”的原则所有操作都在一个新建的普通用户openclaw下完成绝不使用 root 用户。4.1 创建专用用户与基础环境准备首先创建一个干净的、无任何预装软件的用户环境sudo adduser openclaw sudo usermod -aG sudo openclaw sudo su - openclaw这一步至关重要。很多部署失败根源在于用户家目录下残留了旧版 Node 或 npm 的全局模块它们会与新安装的版本产生冲突。接着安装基础依赖sudo apt update sudo apt install -y curl wget git build-essential libpq-dev这里build-essential是为了后续编译mysql2的原生模块libpq-dev是 PostgreSQL 的开发头文件虽然我们不用 PG但mysql2的编译脚本会检查它是否存在缺少会导致编译失败。4.2 使用 NVM 安装并锁定 Node.js v20.12.2这是整个流程的基石必须一步到位curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash # 重新加载 shell 配置 export NVM_DIR$HOME/.nvm [ -s $NVM_DIR/nvm.sh ] \. $NVM_DIR/nvm.sh [ -s $NVM_DIR/bash_completion ] \. $NVM_DIR/bash_completion # 安装指定版本并设为默认 nvm install 20.12.2 nvm alias default 20.12.2 # 验证 node -v # 应输出 v20.12.2 npm -v # 应输出 10.5.2注意nvm install命令会自动下载、编译如果需要、安装 Node.js并将其软链接到~/.nvm/versions/node/v20.12.2/bin/。nvm alias default则确保每次新打开终端node命令都指向这个版本。这是防止未来因环境变量混乱导致问题的最有效手段。4.3 部署 Ollama 并预拉取核心模型接下来是 Ollama 的部署# 下载并安装 Ollama curl -fsSL https://ollama.com/install.sh | sh # 启动 Ollama 服务后台运行 ollama serve # 创建配置目录并写入镜像源配置 mkdir -p ~/.ollama echo {OLLAMA_INSECURE_REGISTRY: [registry.cn-hangzhou.aliyuncs.com]} ~/.ollama/config.json # 预拉取模型以 llama3:8b 为例 docker pull registry.cn-hangzhou.aliyuncs.com/ollama/llama3:8b docker tag registry.cn-hangzhou.aliyuncs.com/ollama/llama3:8b ollama/llama3:8b docker push ollama/llama3:8b # 验证模型是否就位 ollama list # 应能看到 ollama/llama3 的条目这个过程完成后Ollama 就像一个安静待命的引擎随时准备为 OpenClaw 提供算力。4.4 配置 MySQL 并初始化 OpenClaw 数据库OpenClaw 需要一个关系型数据库来存储任务状态、执行日志和 Agent 的记忆。我们选用 MySQL 8.0Ubuntu 22.04 默认源提供因为它比 SQLite 更适合多进程并发写入也比 PostgreSQL 更轻量。# 安装 MySQL sudo apt install -y mysql-server # 启动并启用开机自启 sudo systemctl start mysql sudo systemctl enable mysql # 运行安全配置向导关键 sudo mysql_secure_installation # 这里会提示你设置 root 密码、移除匿名用户、禁止 root 远程登录等。全部选 Y。 # 接下来创建 OpenClaw 专用数据库和用户 sudo mysql -u root -p # 输入你刚设置的 root 密码 # 在 MySQL 提示符下执行 CREATE DATABASE openclaw DEFAULT CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; CREATE USER openclaw_userlocalhost IDENTIFIED BY YourStrongPassword123!; GRANT ALL PRIVILEGES ON openclaw.* TO openclaw_userlocalhost; FLUSH PRIVILEGES; EXIT;注意utf8mb4是必须的因为 OpenClaw 的日志和任务描述中可能包含 emoji 或生僻汉字utf8编码无法正确存储。GRANT ALL PRIVILEGES是为了简化部署生产环境应根据最小权限原则只授予SELECT, INSERT, UPDATE, DELETE权限。4.5 克隆、安装并配置 OpenClaw 主体万事俱备现在进入核心环节# 克隆代码 git clone https://github.com/ai-act/OpenClaw.git cd OpenClaw # 安装依赖此时 nvm 已确保使用 v20.12.2 npm ci # 复制环境配置模板 cp .env.example .env # 编辑 .env 文件填入你的配置 nano .env.env文件是整个部署的灵魂以下是必须修改的关键项# 数据库连接 DB_HOSTlocalhost DB_PORT3306 DB_NAMEopenclaw DB_USERopenclaw_user DB_PASSWORDYourStrongPassword123! # Ollama 服务地址 OLLAMA_HOSThttp://localhost:11434 # OpenClaw 服务监听 SERVER_PORT3000 SERVER_HOST0.0.0.0 # 日志级别调试时设为 debug LOG_LEVELinfo保存退出后执行最后的初始化# 初始化数据库表结构 npm run db:migrate # 启动服务 npm start如果一切顺利终端会输出Server is running on http://0.0.0.0:3000。此时用curl http://localhost:3000/health可以得到{status:ok}的响应证明服务已健康运行。5. 常见问题与排查技巧实录那些文档里绝不会写的“幽灵错误”在真实的部署过程中总会有一些错误它们不报错也不崩溃但就是让功能无法正常工作。我把这些“幽灵错误”整理成一张速查表并附上我的独家排查技巧。问题现象根本原因排查命令解决方案npm run db:migrate报错Access denied for user openclaw_userlocalhostMySQL 用户密码在.env中未正确转义例如密码含$或{符号echo $DB_PASSWORD(在 .env 所在目录执行)将密码用单引号包裹如DB_PASSWORDMy$ecur3Pss!单引号内的字符不会被 shell 解析ollama list显示模型但 OpenClaw 执行任务时提示Model not found: llama3:8bOpenClaw 的OLLAMA_HOST配置指向了错误的地址或 Ollama 服务未在后台运行ps aux | grep ollama和curl http://localhost:11434/api/tags确保OLLAMA_HOST是http://localhost:11434不能是127.0.0.1并确认ollama serve进程存在服务启动后curl http://localhost:3000/health返回Cannot GET /healthExpress.js 路由未正确加载通常是npm ci安装的依赖不完整ls -la node_modules/express和npm ls express删除node_modules和package-lock.json重新执行npm ci。npm ci比npm install更严格它会严格按照package-lock.json安装杜绝版本漂移任务执行日志中大量出现Error: connect ECONNREFUSED 127.0.0.1:3306MySQL 服务未启动或监听地址被配置为127.0.0.1而非localhostsudo systemctl status mysql和sudo mysql -h localhost -u openclaw_user -p检查 MySQL 配置文件/etc/mysql/mysql.conf.d/mysqld.cnf确保bind-address 127.0.0.1这是默认值localhost会通过 Unix socket 连接无需修改除了这张表我还想分享一个最让我抓狂的“玄学”问题OpenClaw 为什么会延迟很多人在 Web UI 上点击“Run Task”要等 5-10 秒才有响应。这并非代码 bug而是 Node.js 的事件循环被阻塞了。根本原因在于OpenClaw 的db:migrate脚本在首次运行时会同步地执行一系列 SQL 语句来创建表。如果 MySQL 服务器响应稍慢比如磁盘 I/O 高这个同步操作就会卡住整个 Node.js 进程的主线程导致所有后续请求排队等待。我的解决方案是在生产环境中永远不要在npm start时自动执行db:migrate。而是将迁移作为一个独立的、一次性的步骤在服务启动前手动运行。这样服务启动后事件循环是完全空闲的响应速度能达到毫秒级。这个经验是我在一台老旧的 Dell R720 服务器上反复重启服务 17 次后才悟出来的。6. 进阶配置与生产化建议从“能跑”到“稳跑”的最后一公里当 OpenClaw 在你的服务器上稳定运行后下一步就是让它真正融入你的工作流。这不再是“能不能用”的问题而是“好不好用、安不安全、好不好管”的问题。6.1 使用 PM2 管理进程实现真正的“永不掉线”npm start启动的服务一旦关闭终端窗口进程就会被杀死。对于生产环境我们必须用专业的进程管理器。PM2 是 Node.js 生态中最成熟的选择。# 全局安装 PM2 npm install -g pm2 # 用 PM2 启动 OpenClaw pm2 start npm --name openclaw -- start # 设置开机自启 pm2 startup pm2 save # 查看进程状态 pm2 statusPM2 的强大之处在于它不仅能保证进程常驻还能提供内存和 CPU 监控、日志轮转、零停机热重载等功能。执行pm2 monit你就能在一个漂亮的终端界面里实时看到 OpenClaw 的内存占用、CPU 使用率、HTTP 请求速率等关键指标。这比写一堆 shell 脚本去ps aux | grep要专业和可靠得多。6.2 配置 Nginx 反向代理暴露安全的 HTTPS 接口直接让 OpenClaw 的3000端口暴露在公网上是极其危险的。我们必须用 Nginx 作为一道坚固的防火墙。sudo apt install -y nginx sudo ufw allow Nginx Full # 编辑 Nginx 配置 sudo nano /etc/nginx/sites-available/openclaw在配置文件中写入server { listen 80; server_name your-domain.com; return 301 https://$server_name$request_uri; } server { listen 443 ssl http2; server_name your-domain.com; ssl_certificate /etc/letsencrypt/live/your-domain.com/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/your-domain.com/privkey.pem; location / { proxy_pass http://127.0.0.1:3000; proxy_http_version 1.1; proxy_set_header Upgrade $http_upgrade; proxy_set_header Connection upgrade; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; proxy_cache_bypass $http_upgrade; } }然后启用配置并申请 SSL 证书sudo ln -sf /etc/nginx/sites-available/openclaw /etc/nginx/sites-enabled/ sudo nginx -t sudo systemctl reload nginx sudo apt install -y certbot python3-certbot-nginx sudo certbot --nginx -d your-domain.com这样配置后所有外部流量都先经过 Nginx 的 SSL 解密和安全策略过滤再转发给 OpenClaw。你还可以在 Nginx 层面轻松添加 IP 白名单、请求速率限制等安全措施而无需改动 OpenClaw 的一行代码。6.3 构建你的第一个自动化技能SkillOpenClaw 的灵魂在于 Skill。它不是一个通用聊天机器人而是一个可编程的自动化平台。让我们用一个最简单的例子来感受它的威力一个“每日天气播报” Skill。 首先在src/skills/目录下创建weather.tsimport { Skill } from ../types; import axios from axios; export const weatherSkill: Skill { name: weather, description: Get the current weather for a given city., parameters: [ { name: city, type: string, description: The name of the city, e.g., Beijing } ], async execute({ city }) { try { // 这里调用一个免费的天气 API如 OpenWeatherMap const response await axios.get( https://api.openweathermap.org/data/2.5/weather?q${city}appidYOUR_API_KEYunitsmetric ); const data response.data; return The current weather in ${city} is ${data.weather[0].description}, with a temperature of ${data.main.temp}°C.; } catch (error) { return Failed to get weather for ${city}: ${error.message}; } } };然后在src/index.ts的registerSkills函数中导入并注册它import { weatherSkill } from ./skills/weather; // ... 其他导入 registerSkill(weatherSkill);最后重启服务你就可以在 Web UI 或 CLI 中执行openclaw run --task Whats the weather in Shanghai?它会自动识别出你需要调用weatherSkill并传入参数Shanghai。这个过程就是 OpenClaw “智能体”能力的体现它能理解自然语言指令将其分解为结构化参数并路由到正确的 Skill 执行。这才是私有化部署的终极价值——把你的业务逻辑变成一个可以被自然语言调用的、可组合的、可复用的原子能力。我个人在实际操作中的体会是OpenClaw 的学习曲线前期陡峭但一旦跨过“部署成功”这个门槛后续的开发体验非常流畅。它的 TypeScript 类型定义极其完善IDE 能给出精准的代码补全它的 Skill 注册机制清晰直观几乎没有学习成本。我建议不要一上来就试图构建复杂的多步工作流而是从一个像“天气查询”这样微小、确定、可验证的 Skill 开始。当你亲手完成第一个 Skill 并看到它在终端里吐出那句The current weather in Shanghai is clear sky...的时候那种掌控感就是所有踩坑付出的最好回报。
