【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 编译工具链用于编译原生依赖。二、系统基础环境配置无论采用哪种安装方式,首先都需要更新系统软件包列表并安装基础依赖。这是避免后续安装过程中出现依赖缺失错误的关键步骤。打开终端,执行以下命令:sudoaptupdatesudoaptupgrade-ysudoaptinstall-ycurlwgetgitpython3 build-essential libssl-dev ufw这些命令的作用各不相同:curl 和 wget 用于下载安装脚本和依赖包;git 用于后续可能的源码操作;python3 是一些原生模块编译时需要的依赖;build-essential 包含了 gcc、g 等编译工具;libssl-dev 提供 SSL/TLS 支持;ufw 是防火墙工具,用于后续的安全配置。安装过程可能需要几分钟时间,请耐心等待完成。更新完成后,建议配置防火墙规则。OpenClaw 默认监听 18789 端口,如果需要从外部访问,需要开放这个端口。但出于安全考虑,默认建议只允许本地访问:sudoufw allow22/tcp# 保留 SSH 访问sudoufwenable# 不开放 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 版本:nvminstall22nvm use22nvm 会自动下载并安装 Node.js 22 的最新稳定版本。安装完成后,验证版本:node-v# 应该输出 v22.x.xnpm-v# 应该输出对应的 npm 版本为了让 Node.js 22 在每次登录后自动加载,需要将其设置为默认版本:nvmaliasdefault22如果不愿意使用 nvm,也可以直接从 NodeSource 源安装 Node.js。NodeSource 提供了最新的 Node.js 版本,安装命令如下:curl-fsSLhttps://deb.nodesource.com/setup_22.x|sudo-Ebash-sudoaptinstall-ynodejs这种方式安装的 Node.js 会添加到系统路径中,所有用户都可以使用,但升级和管理不如 nvm 灵活。四、OpenClaw 安装与部署OpenClaw 提供了一键安装脚本,能够自动处理大部分安装过程。但考虑到网络环境,建议先了解安装脚本的执行流程,以便在网络失败时能够手动处理。标准的一键安装命令是:curl-fsSLhttps://openclaw.ai/install.sh|bash这个脚本会自动检测操作系统类型,安装必要的依赖,包括 Homebrew(在 macOS 上)或直接使用 apt(在 Ubuntu 上),然后安装 Node.js 和 pnpm,最后安装 OpenClaw 本身。由于网络原因,一键安装脚本可能会失败。在这种情况下,可以采用手动安装方式。首先全局安装 pnpm:npminstall-gpnpmpnpmsetup执行 pnpm setup 后,需要关闭终端并重新打开,或者执行 source ~/.bashrc 刷新环境变量。然后安装 OpenClaw:npminstall-gopenclaw如果遇到权限问题,可以配置 npm 的全局安装路径:mkdir~/.npm-globalnpmconfigsetprefix~/.npm-globalechoexport PATH~/.npm-global/bin:$PATH~/.bashrcsource~/.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 服务:sudosystemctl status openclaw# 查看状态sudosystemctl start openclaw# 启动服务sudosystemctl stop openclaw# 停止服务sudosystemctl restart openclaw# 重启服务六、安全加固配置OpenClaw 作为能够操作系统的 AI Agent,安全配置至关重要。完成基本安装后,建议进行以下安全加固措施。首先是开启 Token 认证。默认情况下,OpenClaw 可能没有启用认证,这是不安全的。执行以下命令设置强密码:openclaw configsetgateway.auth.token$(openssl rand-hex32)这会生成一个 64 位的随机十六进制字符串作为认证 Token。后续连接 OpenClaw 时,需要在 WebSocket 握手时提供这个 Token。将 Token 保存在安全的地方,不要泄露。如果需要从 Web UI 连接,可以在仪表板的设置面板中输入 Token。Token 会被加密存储在配置文件中。注意密码不会被持久化,每次重启 Web UI 都需要重新输入密码。其次是关闭公网监听。默认情况下,OpenClaw 只监听 localhost:18789,外部无法访问。如果之前配置了公网监听,需要关闭:openclaw configsetgateway.bindHost127.0.0.1openclaw configsetgateway.port18789这样配置后,只有本机可以访问 OpenClaw。如果确实需要从外部访问,建议配置反向代理,例如使用 Nginx 作为前端,通过 SSL 加密连接,并且在反向代理层添加额外的认证。第三是运行安全审计。OpenClaw 提供了内置的安全审计工具,可以检查配置中的安全问题和潜在风险:openclaw security audit这个命令会检查多个安全项,包括是否启用认证、是否有公网监听、文件权限是否正确等。对于每个检查项,会给出通过、警告或严重等级别,以及相应的修复建议。应该根据审计结果逐项修复,直到没有严重问题。最后是定期更新。OpenClaw 项目活跃,版本更新频繁,经常包含安全修复和性能改进。建议定期检查并升级到最新版本:npmupdate-gopenclaw升级前建议先查看更新日志,了解新版本的变更内容,确认兼容性后再升级。七、验证与测试完成安装和配置后,需要验证 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,可以使用淘宝镜像:npmconfigsetregistry https://registry.npmmirror.com对于 pnpm,也可以配置镜像:pnpmconfigsetregistry 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 上的安装与部署