Moment

OpenClaw 安装部署完整教程

OpenClaw 安装部署完整教程（2026）

OpenClaw 是一个自托管的个人 AI 助手框架，支持多模型、多渠道（WhatsApp / Telegram / Discord / Web），可以将你常用的 AI 能力整合到一个统一的智能助手中。

本文基于官方文档和 macOS arm64 实际部署经验编写，适用于 macOS / Linux 环境。

目录

  1. 系统要求
  2. 安装方式一：npm 全局安装（推荐新手）
  3. 安装方式二：从源码安装（开发者）
  4. 首次配置向导
  5. 启动 Gateway
  6. 安装 macOS App（可选）
  7. 连接消息渠道
  8. Docker 部署（Linux 服务器）
  9. 常用管理命令
  10. 常见问题排查

一、系统要求

项目 要求
Node.js 推荐 Node 24（最低 Node 22.14+）
npm / pnpm npm 10+ 或 pnpm 9+
macOS 13+（app 模式）
Linux 任何主流发行版（systemd / Docker）
架构 x86_64 和 arm64 均支持

1.1 安装 Node.js（如未安装）

macOS（使用 Homebrew）：

brew install node@24

Linux（使用 nvm）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install 24

验证安装：

node --version   # 应输出 v24.x.x
npm --version    # 应输出 10.x+

二、安装方式一：npm 全局安装（推荐新手）

最简单的方式，适合快速上手：

npm install -g openclaw

安装完成后，运行初始化向导：

openclaw setup

三、安装方式二：从源码安装（开发者）

如果你需要修改源码或使用最新未发布功能：

3.1 克隆仓库

git clone https://github.com/openclaw/openclaw.git
cd openclaw

3.2 安装依赖

pnpm install
pnpm build

3.3 运行初始化

pnpm openclaw setup

四、首次配置向导

运行 openclaw setup 后，会进入交互式配置向导，引导你完成：

  1. 选择 AI 模型提供商 — 支持 OpenAI、Anthropic、Google、OpenRouter 等
  2. 配置 API Key — 输入你的模型 API 密钥
  3. 选择工作区路径 — 默认 ~/.openclaw/workspace
  4. 初始化工作区文件 — 自动创建 AGENTS.md、SOUL.md 等核心文件

4.1 配置文件说明

安装完成后，你的配置和数据分布如下：

路径 说明
~/.openclaw/openclaw.json 主配置文件
~/.openclaw/workspace/ 工作区（技能、记忆、提示词）
~/.openclaw/credentials/ 各渠道的认证凭据
~/.openclaw/agents/<agentId>/sessions/ 会话数据

💡 最佳实践： 将 ~/.openclaw/workspace 初始化为 Git 私有仓库，方便版本管理和备份。

cd ~/.openclaw/workspace
git init
git add .
git commit -m "Initial workspace setup"

五、启动 Gateway

Gateway 是 OpenClaw 的核心服务，负责处理消息路由、模型调用和会话管理。

5.1 npm 全局安装方式

openclaw gateway start

检查状态：

openclaw gateway status
openclaw health          # 健康检查

5.2 源码安装方式（开发模式）

# 启动热更新模式，源码改动自动重载
pnpm gateway:watch

或者直接运行：

node openclaw.mjs gateway --port 18789 --verbose

默认 WebSocket 监听地址为 ws://127.0.0.1:18789。

六、安装 macOS App（可选）

macOS 用户强烈推荐安装桌面应用，提供菜单栏集成和图形化管理。

6.1 从官网下载

访问 openclaw.ai 下载最新的 OpenClaw.app。

6.2 连接本地 Gateway

  1. 启动 OpenClaw.app
  2. 完成权限设置（macOS TCC 弹窗）
  3. 设置连接模式为 Local
  4. App 会自动连接到本地运行的 Gateway

验证方式：App 状态栏应显示 “Using existing gateway…”。

七、连接消息渠道

OpenClaw 支持多种消息平台作为交互界面。

7.1 Web Chat（默认已启用）

安装完成后，Web 聊天界面默认可用，通过浏览器访问即可。

7.2 连接 Telegram

openclaw channels login telegram

按提示输入你的 Telegram Bot Token（向 @BotFather 获取）。

7.3 连接 WhatsApp

openclaw channels login whatsapp

扫描弹出的二维码完成配对。

7.4 连接 Discord

在配置文件中添加 Discord Bot Token：

{
  "channels": {
    "discord": {
      "token": "YOUR_DISCORD_BOT_TOKEN"
    }
  }
}

八、Docker 部署（Linux 服务器）

适合在 VPS 或云服务器上长期运行。

8.1 拉取镜像

docker pull openclaw/openclaw:latest

8.2 运行容器

docker run -d \
  --name openclaw \
  -p 18789:18789 \
  -v ~/.openclaw:/root/.openclaw \
  -e OPENAI_API_KEY=your_key_here \
  openclaw/openclaw:latest

8.3 使用 docker-compose（推荐）

# docker-compose.yml
version: "3.8"
services:
  openclaw:
    image: openclaw/openclaw:latest
    container_name: openclaw
    restart: always
    ports:
      - "18789:18789"
    volumes:
      - ./data:/root/.openclaw
    environment:
      - OPENAI_API_KEY=${OPENAI_API_KEY}

docker compose up -d

8.4 Linux systemd 用户服务

如果使用原生安装（非 Docker），启用 linger 确保退出登录后 Gateway 继续运行：

sudo loginctl enable-linger $USER

对于多用戶服务器，建议配置 system 级别的服务。

九、常用管理命令

命令 说明
openclaw setup 初始化 / 重新配置
openclaw gateway start 启动 Gateway
openclaw gateway stop 停止 Gateway
openclaw gateway restart 重启 Gateway
openclaw gateway status 查看 Gateway 状态
openclaw health 健康检查
openclaw channels login 连接新消息渠道
openclaw --version 查看版本
openclaw help 查看所有命令

十、常见问题排查

Q1: Gateway 启动失败 / 端口被占用

# 检查端口占用
lsof -i :18789    # macOS
ss -tlnp | grep 18789   # Linux

# 使用自定义端口
openclaw gateway start --port 19999

Q2: 模型返回 401 / 403 错误

检查 API Key 是否正确配置：

# 查看配置
cat ~/.openclaw/openclaw.json | grep -i key

Q3: macOS 安装后命令找不到

确保 npm 全局 bin 目录在 PATH 中：

# bash / zsh
export PATH=$(npm prefix -g)/bin:$PATH

# 添加到 ~/.zshrc
echo 'export PATH=$(npm prefix -g)/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

Q4: Linux 退出登录后 Gateway 停止

启用 systemd linger：

sudo loginctl enable-linger $USER

Q5: 如何更新 OpenClaw？

npm 安装：

npm update -g openclaw

源码安装：

git pull
pnpm install   # 如果 lockfile 有变化
pnpm build

注意：你的个性化配置在 ~/.openclaw/ 下，更新不会覆盖。

结语

OpenClaw 将强大的 AI 助手能力带到你自己的设备上，数据完全可控，渠道灵活扩展。按照本教程安装配置后，你可以通过 Web、Telegram、WhatsApp 等多种方式与你的 AI 助手交互。

site logo

Moment

© 2026 Moment