OpenClaw 安装教程（Linux）

本次部署指南的核心目标非常明确：在 Linux 环境中，无论是云服务器还是本地物理机，我们都需要完整地完成 OpenClaw 智能体框架的安装与部署，并通过基础的健康检查与功能验证，确保整个系统能够成功启动并稳定运行。

一、环境要求

在开始动手安装之前，我们首先需要确认系统满足所有的基础运行环境要求。以下是部署 OpenClaw 所需的核心依赖清单：

Linux 操作系统：OpenClaw 支持绝大多数主流的 Linux 发行版。对于初学者或希望获得最佳兼容性的用户，建议选用 Ubuntu 22.04 LTS 或 CentOS 8 等长期支持版本。

Node.js 22.x：这是运行 OpenClaw 框架的必备 JavaScript 运行时环境，请务必确保版本号精准匹配。

npm 包管理器：它通常随 Node.js 一同安装，用于管理 OpenClaw 的项目依赖包。

管理员权限：在安装全局 npm 包或执行某些系统级操作时，需要具备 sudo 或 root 权限。

建议首先在终端中执行以下命令，快速验证 Node.js 与 npm 是否已正确安装：

node -v
npm -v

二、安装 Node.js 22（如未安装）

如果上述命令没有返回预期的版本信息，则说明需要先安装 Node.js 环境。我们强烈推荐使用 nvm（Node Version Manager） 工具进行安装和管理，它可以让你在不同项目间轻松切换 Node.js 版本。

请按照顺序，在终端中逐条执行下述安装指令：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.3/install.sh | bash
source ~/.bashrc
nvm install 22
nvm use 22
node -v
npm -v

执行完毕后，Node.js 22 运行环境即安装成功。最后两条命令用于再次确认安装的版本无误。

三、安装 OpenClaw

当基础环境准备就绪后，即可开始安装 OpenClaw 框架本身。我们通过 npm 进行全局安装，以便在系统的任何目录下都能直接调用 openclaw 命令行工具。

npm install -g openclaw

安装过程取决于你的网络速度，请耐心等待。安装完成后，切勿跳过验证步骤。执行以下两个简单命令以确认安装成功：

openclaw --version
openclaw help

第一个命令会打印出当前安装的 OpenClaw 具体版本号；第二个命令则会列出所有可用的子命令及其简要说明。看到这些信息，即表示 OpenClaw 主体安装“稳了”。

四、启动 Gateway 服务

OpenClaw 的核心功能由其 Gateway（网关）服务提供。只有成功启动此服务，OpenClaw 才能开始处理请求。首先，熟悉几个常用的服务管理命令：

openclaw gateway status  # 查看服务当前运行状态
openclaw gateway start   # 启动网关服务
openclaw gateway stop    # 停止网关服务
openclaw gateway restart # 重启网关服务

对于全新安装，我们直接启动服务即可：

openclaw gateway start

启动命令执行后，强烈建议立即检查服务状态，以确保其正在后台正常运行：

openclaw gateway status

五、基础配置

服务成功运行后，还需要进行关键的初始化配置，为其注入“灵魂”。运行配置向导命令，它将通过交互式问答引导你完成核心设置：

openclaw configure

你需要根据提示，依次配置 AI 模型供应商（如 OpenAI、Claude）、消息集成通道（如 Discord、Slack 机器人）、以及需要启用的工具插件等。这一步直接决定了 OpenClaw 将使用哪些 AI 能力、通过何种渠道与你交互。

重要提示：如果你计划启用网页搜索功能（web_search），此功能需要配置独立的搜索引擎 API 密钥（例如 Brave Search API Key）。若未在初始向导中配置，可随时通过以下命令单独进行设置：

openclaw configure --section web

六、健康检查

完成基础配置后，强烈推荐执行一次全面的系统“体检”。这有助于提前发现并解决潜在的环境配置、依赖缺失或网络连通性问题。执行诊断命令：

openclaw doctor --non-interactive

此命令将以非交互模式自动运行，检查包括 Node.js 环境、依赖包版本、必要的环境变量、网络连接性以及服务端口状态在内的多项指标，并生成详细的诊断报告。根据报告中的提示修复任何异常项，可以有效避免后续使用中的大多数常见故障。

七、升级与维护

为了获得最新的功能增强和安全补丁，定期升级 OpenClaw 至最新版本是良好的维护习惯。升级操作非常简单：

npm install -g openclaw@latest

升级完成后，为确保新版本服务稳定运行，建议遵循标准的维护流程：首先重启 Gateway 服务以加载新版本代码，随后再次执行健康检查以确认升级未引入新问题。

openclaw gateway restart
openclaw doctor --non-interactive

八、常见问题

在安装和初次配置过程中，你可能会遇到一些典型问题。以下是针对高频问题的快速排查指南。

1） openclaw：找不到命令

此错误通常意味着系统无法定位到全局安装的 npm 包的可执行文件路径。

解决方法：首先，执行 npm prefix -g 查看全局包安装路径，再执行 npm bin -g 查看全局可执行文件目录。然后，确保该目录（例如 /usr/local/bin 或 ~/.nvm/versions/node/v22.x/bin）已被添加到你的 shell 配置文件（如 ~/.bashrc, ~/.zshrc）的 PATH 环境变量中，并执行 source 命令使配置生效。

2) Gateway 启动失败

若服务无法启动，请按以下顺序系统化排查：

步骤一：查看状态与日志。执行 openclaw gateway status，观察输出的错误信息。

步骤二：尝试重启。执行 openclaw gateway restart，有时可以解决临时性的进程锁问题。

步骤三：深入诊断。如果问题依旧，请运行 openclaw doctor --non-interactive。该诊断工具通常能精准定位到缺失的依赖、错误的配置或端口冲突等具体原因。

3) 搜索工具报 missing_brave_api_key

当调用网页搜索工具出现此错误时，表明功能虽已启用，但未配置必需的 API 密钥。

解决方法：运行 openclaw configure --section web 命令，在对应的配置项中填入从 Brave Search 等供应商处获取的有效 API 密钥即可。

九、结语

遵循上述步骤，你应该已经成功在 Linux 服务器上完成了 OpenClaw AI 智能体框架的部署，并使其进入了可运行状态。

那么，在验证安装成功之后，接下来应该如何深入呢？我们提供两个关键的行动建议：

首先，深入进行场景化配置。根据你的实际应用需求，精细化配置消息通道（例如将其接入你的团队 Slack 或 Discord 工作区），这是发挥其协同作用的关键步骤。

其次，务必完成生产环境安全加固。在正式投入业务使用前，请全面审查安全设置：检查服务是否以最小必要权限运行、确保网关监听端口未被不必要地暴露在公网、并严格管理所有使用的 API 密钥及敏感配置项（建议使用环境变量或密钥管理服务）。安全无小事，这一环节至关重要。

祝你部署过程一切顺利，快速开启 OpenClaw 的智能体应用之旅！