【OpenClaw 全面解析：从零到精通】第 004 篇：OpenClaw 在 Linux/Ubuntu 上的安装与部署实战
系列说明：本系列共计 20 余篇，全面介绍 OpenClaw 开源 AI 智能体框架。本文为系列第 004 篇，聚焦于 OpenClaw 在 Linux/Ubuntu 上的安装与部署实战。建议先阅读 第 003 篇：OpenClaw 技术依赖与生态栈详解。
摘要
本文详细介绍在 Ubuntu 22.04/24.04 系统上安装和部署 OpenClaw 的完整流程,涵盖系统环境准备、Node.js 安装、OpenClaw 部署、配置向导、安全加固以及常见问题排查,帮助开发者从零开始搭建自己的 OpenClaw AI 助手系统。
一、环境准备与系统要求
在开始安装 OpenClaw 之前,需要确保服务器满足最低硬件和软件要求。OpenClaw 对硬件的要求相对友好,但为了保证流畅运行,建议配置如下:CPU 至少 4 核心以保证 Agent 能够并发处理多个任务;内存建议 8GB 以上,4GB 是最低可用配置,但可能会在处理复杂任务时出现卡顿;存储空间至少需要 10GB 可用空间,用于存储模型缓存、Skills 插件和日志文件。此外,还需要稳定的网络连接,以及 sudo 管理员权限用于执行安装操作。
软件方面,OpenClaw 要求操作系统为 Ubuntu 22.04 或 24.04,其他基于 Debian 的发行版理论上也可以运行,但本文以 Ubuntu 为例进行说明。Node.js 版本必须不低于 22.0.0,这是硬性要求,低于此版本将无法正常工作。此外还需要 git 用于克隆代码仓库,以及 build-essential 编译工具链用于编译原生依赖。
二、系统基础环境配置
无论采用哪种安装方式,首先都需要更新系统软件包列表并安装基础依赖。这是避免后续安装过程中出现"依赖缺失"错误的关键步骤。打开终端,执行以下命令:
sudoapt update &&sudoapt upgrade -ysudoaptinstall-ycurlwgetgit python3 build-essential libssl-dev ufw 这些命令的作用各不相同:curl 和 wget 用于下载安装脚本和依赖包;git 用于后续可能的源码操作;python3 是一些原生模块编译时需要的依赖;build-essential 包含了 gcc、g++ 等编译工具;libssl-dev 提供 SSL/TLS 支持;ufw 是防火墙工具,用于后续的安全配置。安装过程可能需要几分钟时间,请耐心等待完成。
更新完成后,建议配置防火墙规则。OpenClaw 默认监听 18789 端口,如果需要从外部访问,需要开放这个端口。但出于安全考虑,默认建议只允许本地访问:
sudo ufw allow 22/tcp # 保留 SSH 访问sudo ufw enable# 不开放 18789 端口,保持默认的仅本地访问这样配置后,只有通过 SSH 登录到服务器的用户才能访问 OpenClaw,减少了被攻击的风险。如果确实需要远程访问,建议配置反向代理或 VPN,而不是直接开放端口。
三、Node.js 运行时安装
Node.js 是 OpenClaw 的核心依赖,安装方式有多种。推荐使用 nvm(Node Version Manager)进行安装,因为它能够方便地管理多个 Node.js 版本,避免版本冲突问题。首先安装 nvm,官方脚本托管在 GitHub 上,但由于网络原因,国内用户可能无法直接访问。可以使用 Gitee 镜像:
curl -o- https://gitee.com/RubyMetric/nvm-cn/raw/main/install.sh |bashsource ~/.bashrc 安装完成后,验证 nvm 是否正常工作:
nvm --version接下来安装 Node.js 22 版本:
nvm install22 nvm use 22nvm 会自动下载并安装 Node.js 22 的最新稳定版本。安装完成后,验证版本:
node-v# 应该输出 v22.x.xnpm-v# 应该输出对应的 npm 版本为了让 Node.js 22 在每次登录后自动加载,需要将其设置为默认版本:
nvm alias default 22如果不愿意使用 nvm,也可以直接从 NodeSource 源安装 Node.js。NodeSource 提供了最新的 Node.js 版本,安装命令如下:
curl-fsSL https://deb.nodesource.com/setup_22.x |sudo-Ebash - sudoaptinstall-y nodejs 这种方式安装的 Node.js 会添加到系统路径中,所有用户都可以使用,但升级和管理不如 nvm 灵活。
四、OpenClaw 安装与部署
OpenClaw 提供了一键安装脚本,能够自动处理大部分安装过程。但考虑到网络环境,建议先了解安装脚本的执行流程,以便在网络失败时能够手动处理。
标准的一键安装命令是:
curl-fsSL https://openclaw.ai/install.sh |bash这个脚本会自动检测操作系统类型,安装必要的依赖,包括 Homebrew(在 macOS 上)或直接使用 apt(在 Ubuntu 上),然后安装 Node.js 和 pnpm,最后安装 OpenClaw 本身。
由于网络原因,一键安装脚本可能会失败。在这种情况下,可以采用手动安装方式。首先全局安装 pnpm:
npminstall-gpnpmpnpm setup 执行 pnpm setup 后,需要关闭终端并重新打开,或者执行 source ~/.bashrc 刷新环境变量。然后安装 OpenClaw:
npminstall-g openclaw 如果遇到权限问题,可以配置 npm 的全局安装路径:
mkdir ~/.npm-global npm config set prefix '~/.npm-global'echo'export PATH=~/.npm-global/bin:$PATH'>> ~/.bashrc source ~/.bashrc 这样可以避免使用 sudo 安装全局包,更符合 Node.js 社区的最佳实践。
安装完成后,验证 OpenClaw 是否正常安装:
openclaw --version应该输出 OpenClaw 的版本号,例如 2026.3.x。如果命令无法识别,可能是环境变量没有正确加载,需要检查 PATH 配置。
五、初始化配置
安装完成后,需要运行配置向导进行初始化设置:
openclaw onboard --install-daemon 这个命令会启动交互式配置向导,引导用户完成一系列设置。首先是是否使用之前的配置信息,如果是首次安装,选择 Reset 重置配置。然后选择 QuickStart 快速配置模式。
接下来是模型配置,这是最关键的一步。OpenClaw 支持多种大模型提供商,包括 Anthropic、OpenAI、DeepSeek、国产模型等。选择模型时需要特别注意上下文窗口大小,OpenClaw 默认要求最小 16000 Token,否则后续运行时会报错。如果选择 Custom Provider 自定义提供商,需要提供 base URL、API Key 和模型名称。
配置完成后,向导会提示是否安装 Skills。Skills 是 OpenClaw 的技能插件,提供了文件操作、邮件处理、代码生成等功能。建议至少安装基础 Skills,否则 OpenClaw 的功能会受到很大限制。可以根据需要选择安装哪些 Skills,安装过程会自动下载和配置。
最后,向导会询问是否安装守护进程。守护进程会在系统启动时自动启动 OpenClaw,确保服务持续运行。对于服务器部署,建议选择安装。安装守护进程后,可以通过以下命令管理 OpenClaw 服务:
sudo systemctl status openclaw # 查看状态sudo systemctl start openclaw # 启动服务sudo systemctl stop openclaw # 停止服务sudo systemctl restart openclaw # 重启服务六、安全加固配置
OpenClaw 作为能够操作系统的 AI Agent,安全配置至关重要。完成基本安装后,建议进行以下安全加固措施。
首先是开启 Token 认证。默认情况下,OpenClaw 可能没有启用认证,这是不安全的。执行以下命令设置强密码:
openclaw config set gateway.auth.token "$(openssl rand -hex32)"这会生成一个 64 位的随机十六进制字符串作为认证 Token。后续连接 OpenClaw 时,需要在 WebSocket 握手时提供这个 Token。将 Token 保存在安全的地方,不要泄露。
如果需要从 Web UI 连接,可以在仪表板的设置面板中输入 Token。Token 会被加密存储在配置文件中。注意密码不会被持久化,每次重启 Web UI 都需要重新输入密码。
其次是关闭公网监听。默认情况下,OpenClaw 只监听 localhost:18789,外部无法访问。如果之前配置了公网监听,需要关闭:
openclaw config set gateway.bindHost "127.0.0.1" openclaw config set gateway.port 18789这样配置后,只有本机可以访问 OpenClaw。如果确实需要从外部访问,建议配置反向代理,例如使用 Nginx 作为前端,通过 SSL 加密连接,并且在反向代理层添加额外的认证。
第三是运行安全审计。OpenClaw 提供了内置的安全审计工具,可以检查配置中的安全问题和潜在风险:
openclaw security audit 这个命令会检查多个安全项,包括是否启用认证、是否有公网监听、文件权限是否正确等。对于每个检查项,会给出通过、警告或严重等级别,以及相应的修复建议。应该根据审计结果逐项修复,直到没有严重问题。
最后是定期更新。OpenClaw 项目活跃,版本更新频繁,经常包含安全修复和性能改进。建议定期检查并升级到最新版本:
npm update -g openclaw 升级前建议先查看更新日志,了解新版本的变更内容,确认兼容性后再升级。
七、验证与测试
完成安装和配置后,需要验证 OpenClaw 是否正常工作。首先检查 OpenClaw 服务状态:
openclaw doctor 这个命令会运行全面的健康检查,包括版本、认证、网络连接、依赖项等多个方面,确保所有组件都正常工作。如果有任何问题,会给出详细的错误信息和修复建议。
然后测试 Gateway 连接。OpenClaw 提供了 TUI(终端用户界面)用于测试和交互:
openclaw tui 这会启动一个基于文本的交互界面,可以通过它发送指令给 Agent,查看执行结果。尝试发送一个简单的测试指令,例如"列出当前目录的文件",验证 Agent 是否能够正常响应。
如果配置了 Web UI,可以在浏览器中访问 http://localhost:18789,查看控制面板。首次访问需要输入之前配置的 Token。通过 Web UI 可以更直观地管理 OpenClaw,查看日志、配置 Skills、管理设备等。
最后测试 Agent 的实际功能。尝试一个稍微复杂的任务,例如"查找并整理昨天的下载文件",观察 Agent 是否能够理解意图、制定计划、执行操作、给出结果。这个过程能够全面测试 OpenClaw 的各项功能是否正常。
八、常见问题排查
在安装和部署过程中,可能会遇到各种问题。这里列出一些常见问题及其解决方案。
Node.js 版本不匹配是最常见的问题之一。如果提示 Node.js 版本过低,需要按照前面的步骤安装 Node.js 22 或更高版本。可以使用 nvm list 查看已安装的 Node.js 版本,nvm use 22 切换到正确版本。
网络连接问题也是常见问题。安装脚本或 Skills 下载可能因为网络原因失败。解决方案包括配置国内镜像源、使用代理,或者手动下载后复制到服务器。对于 npm,可以使用淘宝镜像:
npm config set registry https://registry.npmmirror.com 对于 pnpm,也可以配置镜像:
pnpm config set registry https://registry.npmmirror.com 权限问题也经常出现。如果遇到 EACCES 错误,说明没有权限写入某个目录。可以按照前面的方法配置 npm 全局路径,或者使用 sudo(不推荐)。更好的做法是检查目录权限并修复。
WebSocket 连接失败通常是因为防火墙或认证问题。首先检查 OpenClaw 服务是否正常运行,端口是否监听,然后检查 Token 是否正确。如果使用外部访问,检查网络连通性和端口转发配置。
Agent 执行错误可能是因为模型配置不正确或权限不足。检查 API Key 是否有效,模型名称是否正确,上下文窗口是否满足要求。检查 Agent 是否有权限访问相关文件和执行相关命令。
九、生产部署建议
对于生产环境部署,还有几点建议。首先是使用配置管理工具管理 OpenClaw 配置,确保环境的一致性。可以使用 Ansible、Puppet 等工具自动化部署过程。
其次是监控和日志。OpenClaw 的日志文件存储在 ~/.openclaw/logs 目录,建议配置日志轮转,避免日志文件过大。可以集成到现有的监控系统中,实时监控 OpenClaw 的运行状态。
第三是备份和恢复。OpenClaw 的配置和状态都存储在 ~/.openclaw 目录,定期备份这个目录可以防止数据丢失。可以使用定时任务定期打包备份,并存储到远程位置。
第四是高可用部署。对于关键任务,可以考虑部署多个 OpenClaw 实例,通过负载均衡分发请求。需要注意多实例间的状态同步问题。
结语
在 Linux/Ubuntu 上部署 OpenClaw 是一个相对简单的过程,但要实现稳定可靠的生产部署,需要仔细规划各个步骤。从环境准备、依赖安装、配置初始化到安全加固,每个环节都不可忽视。本文提供的流程和建议能够帮助开发者快速搭建自己的 OpenClaw 系统,并确保其安全稳定运行。在下一篇文章中,我们将探讨 OpenClaw 在 macOS 上的安装与部署,为不同平台的用户提供指导。
上一篇：[第 003 篇] OpenClaw 技术依赖与生态栈详解
下一篇：[第 005 篇] OpenClaw 在 macOS 上的安装与部署
