OpenClaw 安装部署指南npm、Docker 与源码三种模式详解在生产环境部署 AI Agent 网关选择合适的交付模式远比单纯的能跑起来更重要。本文从资源隔离性、运维复杂度、安全边界三个维度深度解析 OpenClaw 的三种官方部署方案。一、环境要求与前置检查在正式部署前需要确认目标机器满足以下基线配置。OpenClaw 采用 Node.js 运行时架构网关进程本身轻量但沙箱执行环境与向量内存操作对资源有特定要求。1.1 基础硬件配置部署场景CPU内存存储网络开发测试4核2GB最低4GB建议20GB SSD出站 443 端口开放生产单节点6核8GB~16GB100GB NVMe稳定公网/IP白名单高可用集群8核32GB持久化卷PVC内网 10Gbps关键提示若启用浏览器自动化Playwright或本地模型推理Ollama/Llama.cpp内存需求需额外增加 4GB~8GB 缓冲。1.2 软件依赖清单Node.js版本 22.x LTS强制要求V8 引擎特性依赖包管理器npm 10 或 pnpm 8容器运行时Docker 方案Docker Engine 24 或 Docker Desktop 4.25可选组件FFmpeg语音处理、Chromium浏览器自动化执行前置检查命令# 验证 Node 版本node-v# 需输出 v22.x.x# 验证 ulimitDocker 方案需关注ulimit-n# 建议 65535避免高并发句柄耗尽二、部署方案选型决策树OpenClaw 提供三种官方支持的部署路径分别对应不同的运维哲学--------------------------------------------------- | OpenClaw 部署选型决策 | --------------------------------------------------- | ------------------------------ | | 追求极简快速 需要长期运维 | | 一键脚本安装 Docker 部署 (install.sh) (Compose) | | ------------ ---------------------- | | | | 本地开发 快速验证 全容器化模式 HostSandbox 混合模式 (npm) (npm) (推荐生产) (进阶隔离)选型建议个人开发者/本地调试npm 全局安装热重载友好调试信息完整中小团队生产环境Docker Compose 全容器化一次构建多环境一致金融/医疗等高敏感场景Host Gateway Sandbox 容器混合模式实现网关与执行环境的强隔离三、方案一一键脚本安装极速体验官方提供的自动化脚本适用于绝大多数 Linux 发行版Ubuntu 22.04/Debian 12/RHEL 9封装了 Node 环境检测、依赖安装与初始化引导。3.1 执行流程拆解脚本执行逻辑并非简单的下载-解压而是包含环境探测与自适应修复curl-fsSLhttps://openclaw.ai/install.sh|bash脚本内部执行阶段---------------- | 阶段1: 环境探测 | | - 检查 Node 版本 | | - 检测包管理器 | | - 验证权限 | --------------- | v --------------- | 阶段2: 依赖安装 | | - 若缺 Node 22 | | 自动调用 n 或 | | nvm 安装 | --------------- | v --------------- | 阶段3: 二进制安装 | | - npm install | | - 生成 CLI 包装器| --------------- | v --------------- | 阶段4: 初始化引导 | | - 提示 onboard | | - 创建 systemd | | 服务可选 | ----------------3.2 安装后验证# 检查 CLI 可用性openclaw--version# 查看网关守护进程状态若启用systemctl status openclaw-gateway版本升级策略OpenClaw 采用语义化版本Semver但注意 0.x 版本期间可能存在破坏性变更。生产环境建议锁定 minor 版本# 安全升级仅 patch 版本npmupdate-gopenclaw# 大版本迁移需查阅 Migration Guidenpminstall-gopenclaw0.4.04.2 进程保活配置npm 模式默认前台运行生产环境需配合进程管理器PM2 方案推荐npminstall-gpm2 pm2 startopenclaw gateway--nameopenclaw-gw pm2 startup pm2 saveSystemd 方案手动创建服务单元文件 /etc/systemd/system/openclaw.service指定 User 与 WorkingDirectory避免 root 运行风险。五、方案三Docker Compose 部署生产级Docker 方案是生产环境的首选核心优势在于环境一致性与安全沙箱的原生支持。官方提供两种 Compose 配置模式对应不同的隔离级别。5.1 架构模式对比模式 A全容器化Full Containerization所有组件Gateway、CLI、Sandbox运行于容器网络内部。-------------------------------------------------- | Docker Host | | --------------------------------------------- | | | Docker Network: openclaw | | | | ---------------- ------------------ | | | | | openclaw-cli | | openclaw-gateway | | | | | | (配置管理) | | (核心网关) | | | | | ---------------- ------------------ | | | | | | | | | | v v | | | | ---------------------------------------- | | | | | Sandbox 容器代码执行隔离 | | | | | | - 无网络访问可选 | | | | | | - 只读文件系统除 /tmp | | | | | ---------------------------------------- | | | --------------------------------------------- | --------------------------------------------------适用场景公有云 VPS、团队共享开发机、CI/CD 流水线。模式 BHost Gateway Sandbox 容器混合隔离网关进程直接运行于宿主机或主容器仅将危险操作代码执行、浏览器自动化放入临时沙箱容器。-------------------------------------------------- | Docker Host | | | | ------------------ ------------------ | | | openclaw-gateway | | Sandbox Pool | | | | (Host Network) |----| ------------ | | | | PID 1 (宿主机) | | | Sandbox #1 | | | | ------------------ | ------------ | | | | | ------------ | | | v | | Sandbox #2 | | | | ------------------ | ------------ | | | | Control UI | ------------------ | | | (Port 18789) | | | ------------------ | --------------------------------------------------架构优势性能网关直接绑定宿主机端口避免 NAT 转发延迟安全敏感操作如 rm -rf /被限制在一次性容器中退出即焚毁5.2 部署实操步骤官方提供自动化设置脚本 docker-setup.sh建议先 clone 仓库再执行便于后续调优gitclone https://github.com/openclaw/openclaw.gitcdopenclaw# 执行自动化构建与配置./docker-setup.sh脚本执行关键动作构建本地镜像基于 node:22-bookworm创建数据卷映射~/.openclaw配置/记忆与 ~/openclaw/workspace工作区触发交互式初始化向导onboard生成 docker-compose.yml 与可选的 docker-compose.extra.yml持久化挂载手动 Compose 启动若需自定义version:3.8services:openclaw-gateway:build:.ports:-18789:18789volumes:-~/.openclaw:/home/node/.openclaw-~/openclaw/workspace:/home/node/workspaceenvironment:-NODE_ENVproduction-SANDBOX_ENABLEDtruerestart:unless-stopped启动命令# 初始化仅需一次dockercompose run--rmopenclaw-cli onboard# 后台启动网关dockercompose up-dopenclaw-gateway# 查看实时日志dockercompose logs-fgateway5.3 权限与持久化注意事项官方镜像以非 root 用户 nodeUID 1000运行若宿主机挂载目录权限不符会导致配置写入失败# Linux 宿主机需调整目录归属sudochown-R1000:1000 ~/.openclaw ~/openclaw/workspace# 或设置 ACL若多用户共享setfacl-R-mu:1000:rwx ~/.openclaw六、初始化向导与配置生成无论采用哪种部署方式首次运行都需执行 openclaw onboard这是一个交互式配置流程生成核心配置文件 ~/.openclaw/config.json。6.1 向导流程解析------------------- | openclaw onboard | ------------------ | v ------------------ | 1. 选择 AI 提供商 | | - OpenAI | | - Anthropic | | - OpenRouter | | - 本地模型 | ------------------ | v ------------------ | 2. 配置 API 密钥 | | (加密存储) | ------------------ | v ------------------ | 3. 设置网关凭证 | | - Admin Token | | - 端口 (18789) | ------------------ | v ------------------ | 4. 选择通信通道 | | - Telegram | | - WhatsApp | | - Discord | | - Webhook | ------------------ | v ------------------ | 5. 生成配置文件 | | 与系统服务 | -------------------6.2 关键配置项说明模型路由配置config.json 节选{models:{default:gpt-4,providers:[{name:openai,apiKey:${OPENAI_API_KEY},baseURL:https://api.openai.com/v1},{name:local-llama,apiKey:sk-no-key,baseURL:http://host.docker.internal:11434/v1}]},gateway:{port:18789,sandbox:{enabled:true,image:openclaw/sandbox:latest}}}环境变量覆盖生产环境建议通过 .env 或 Docker Secrets 注入敏感信息避免硬编码于 JSON 文件。七、生产环境加固建议从架构安全角度部署完成后建议实施以下加固措施7.1 网络层安全防火墙仅开放 18789 端口或自定义端口限制源 IP 白名单SSH 隧道管理后台建议通过本地端口转发访问避免直接暴露公网bash复制ssh -N -L 18789:127.0.0.1:18789 user7.2 运行时安全非特权用户确保 OpenClaw 进程以非 root 运行Docker 模式已默认实现沙箱限制启用 SANDBOX_ENABLEDtrue禁止 Agent 直接访问宿主机文件系统命令白名单在 config.json 中配置 allowed_commands 与 denied_commands限制危险 Shell 操作7.3 监控与备份状态备份~/.openclaw 目录包含 Agent 记忆与配置建议每日增量备份至对象存储日志聚合Docker 模式可配置日志驱动至 Loki 或 ELK 栈便于审计 Agent 行为八、故障排查速查表现象可能原因排查命令onboard卡住API Key 验证失败curl -I https://api.openai.com检查出站网络Docker 启动后 1008 错误远程访问配置未启用检查config.json中allowInsecureAuth仅内网可临时开启权限被拒绝 (EACCES)UID 1000 无权访问挂载卷ls -n ~/.openclaw确认归属内存溢出 (OOM)Sandbox 未限制内存Docker 中设置deploy.resources.limits.memory端口冲突18789 被占用netstat -tulnpgrep 18789九、总结OpenClaw 的三级部署体系覆盖了从个人极客到企业级生产的全场景一键脚本降低了体验门槛适合快速验证概念npm 模式提供了开发灵活性适合需要深度定制的场景Docker Compose 则是生产环境的稳健之选特别是 HostSandbox 混合模式在性能与隔离性之间取得了最佳平衡本文章基于openclaw官方文档。仅供学习参考请勿用于商业用途。