第二章：安装与配置

三种方式安装 OpenClaw，总有一种适合你。

本章概览

在这一章中，你将学习：

三种安装 OpenClaw 的方法（npm / Docker / 图形化管理工具）
如何使用 openclaw onboard 完成初始设置
如何选择和配置 LLM Provider
如何验证安装是否成功

选择适合你的方式

完全不懂命令行？ 直接跳到方法三：图形化管理工具
会用基本命令行？ 推荐方法一：npm 安装
熟悉 Docker？ 试试方法二：Docker 部署

2.1 安装前准备

系统要求

要求	最低配置	推荐配置
操作系统	Windows 10 / macOS 12 / Ubuntu 20.04	最新版本
内存	4 GB	8 GB+
磁盘空间	500 MB	2 GB+（含本地模型）
网络	需要（使用云端 LLM 时）	宽带连接
Node.js	v22+	v22 LTS

准备 API Key

在安装之前，建议你先准备好一个 LLM 的 API Key。以下是几个常见选择：

LLM Provider	获取方式	费用	推荐指数
Claude (Anthropic)	console.anthropic.com	按量付费	★★★★★
GPT (OpenAI)	platform.openai.com	按量付费	★★★★☆
DeepSeek	platform.deepseek.com	按量付费（便宜）	★★★★☆
Ollama (本地)	免费下载	完全免费	★★★☆☆

用哪个 LLM？

预算充足，追求最佳效果：选 Claude（Sonnet 或 Opus）
想省钱但效果也不错：选 DeepSeek
完全不想花钱：选 Ollama 本地模型
已经有 OpenAI 账号：直接用 GPT 也可以

2.2 方法一：npm 安装

这是最主流的安装方式，适合有一定命令行基础的用户。

第一步：确认 Node.js 版本

打开终端（Terminal / 命令行），输入：

bash

node --version

你应该看到类似 v22.x.x 的输出。OpenClaw 要求 Node.js ≥ 22。

没有 Node.js 或版本过低？

如果提示 "command not found" 或版本低于 v22，你需要升级 Node.js。

请前往 nodejs.org 下载 LTS 版本（长期支持版），按照提示安装即可。

安装完成后，重新打开终端再试一次。

第二步：全局安装 OpenClaw

bash

npm install -g openclaw@latest
# 或
pnpm add -g openclaw@latest

安装过程中你可能会看到类似的输出：

added 342 packages in 45s

第三步：验证安装

bash

openclaw --version

你应该看到版本号输出。

第四步：运行引导式设置

bash

openclaw onboard --install-daemon

--install-daemon 会把 Gateway 注册成系统服务（macOS 用 launchd，Linux 用 systemd user service），开机自动运行。

向导界面大致如下：

🐾 Welcome to OpenClaw!
   Let's get you set up. This will only take a few minutes.

? Choose your LLM Provider:
  ❯ Claude (Anthropic)
    GPT (OpenAI)
    DeepSeek
    Ollama (Local)
    Custom OpenAI-compatible endpoint

按照向导提示，依次完成以下设置：

选择 LLM Provider -- 选择你要使用的 AI 后端
输入 API Key -- 粘贴你的 API Key
选择默认模型 -- 比如 Claude Sonnet、GPT-4o 等
设置消息平台 -- 可以稍后配置，先跳过也行
完成！ -- 设置向导会生成配置文件

第五步：打开仪表盘

浏览器访问：

http://127.0.0.1:18789/

仪表盘是 OpenClaw 的浏览器控制界面，可以做聊天、配置、节点管理、查看会话等所有日常操作。

如果打不开，说明 Gateway 没在跑，手动启动：

bash

openclaw gateway --port 18789

第六步：发送第一条测试消息

bash

openclaw message send --target <目标账号> --message "Hello from OpenClaw"

目标账号收到消息 → 说明渠道、Gateway、CLI 全部打通。

万能排错命令

如果遇到任何问题，先运行：

bash

openclaw doctor

它会自动检查并修复常见问题。openclaw doctor 也是日常排错的万能命令。

后台运行

如果你没有加 --install-daemon，可以让 OpenClaw 在后台持续运行：

bash

openclaw gateway --port 18789

这样即使关闭终端窗口，OpenClaw 也会继续运行。

2.3 方法二：Docker 部署

Docker 部署适合以下情况：

你熟悉 Docker
你想要更干净的隔离环境
你计划部署到服务器上

第一步：确认 Docker 环境

bash

docker --version

如果没有安装 Docker，请前往 docker.com 下载 Docker Desktop。

第二步：拉取镜像

bash

docker pull openclaw/openclaw:latest

第三步：创建配置目录

bash

mkdir -p ~/.openclaw

第四步：运行容器

bash

docker run -d \
  --name openclaw \
  --restart unless-stopped \
  -v ~/.openclaw:/root/.openclaw \
  -p 18789:18789 \
  openclaw/openclaw:latest

参数	说明
`-d`	后台运行（detached mode）
`--name openclaw`	给容器起名叫 "openclaw"
`--restart unless-stopped`	自动重启（除非手动停止）
`-v ~/.openclaw:/root/.openclaw`	挂载配置目录，数据持久化
`-p 18789:18789`	端口映射，仪表盘访问

第五步：运行设置向导

bash

docker exec -it openclaw openclaw onboard

后续步骤和 npm 安装一样，按照向导提示操作即可。

常用 Docker 命令

bash

# 查看运行状态
docker ps | grep openclaw

# 查看日志
docker logs openclaw

# 实时查看日志
docker logs -f openclaw

# 停止
docker stop openclaw

# 重新启动
docker start openclaw

# 更新到最新版本
docker pull openclaw/openclaw:latest
docker stop openclaw && docker rm openclaw
# 然后重新执行 docker run 命令

Docker 网络注意事项

如果你使用 Docker 部署，并且需要接收 Webhook（比如 WhatsApp Business API 的回调），你需要确保：

容器的 18789 端口已经映射到主机
你的主机网络可以从外部访问（或使用 ngrok 等隧道工具）

2.4 方法三：GUI 配置工具

最适合非技术用户

openclaw 配置方式十分不友好， github 上也有很多 Openclaw 的 GUI 配置工具。

以OneClaw为例

OneClaw 是一个独立的桌面应用程序，它把 OpenClaw 包装成了一个可以直接双击打开的应用。你不需要：

~~安装 Node.js~~
~~使用 npm 命令~~
~~打开终端~~
~~编辑配置文件~~

一切都通过图形界面完成。

安装步骤

macOS 用户：

前往 github.com/oneclaw/oneclaw/releases
下载最新的 .dmg 文件
打开 .dmg 文件
将 OneClaw 拖到 Applications 文件夹
双击打开 OneClaw

Windows 用户：

前往 github.com/oneclaw/oneclaw/releases
下载最新的 .exe 安装包
运行安装包，按照提示完成安装
从开始菜单或桌面快捷方式打开 OneClaw

Linux 用户：

前往 github.com/oneclaw/oneclaw/releases
下载 .AppImage 或 .deb 包
安装并运行

macOS 上提示"无法验证开发者"？

由于 OneClaw 是开源项目，没有 Apple 的开发者签名。首次打开时：

右键点击应用图标
选择"打开"
在弹出的对话框中点击"打开"

或者去 系统偏好设置 → 安全性与隐私 → 通用，点击"仍然打开"。

关于 OneClaw 的详细使用，我们会在第六章中深入讲解。

2.5 配置 LLM Provider

无论你使用哪种安装方式，都需要配置 LLM Provider。以下是各个 Provider 的详细配置说明。

Claude (Anthropic)

json

{
  "llm": {
    "provider": "anthropic",
    "api_key": "sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

获取 API Key 的步骤：

访问 console.anthropic.com
注册或登录
进入 API Keys 页面
点击 "Create Key"
复制生成的 Key（以 sk-ant- 开头）

API Key 安全

API Key 就像密码一样重要，请注意：

不要把 API Key 分享给别人
不要把它提交到 GitHub 等公开仓库
如果泄露了，立即在 Console 中删除并重新生成

订阅认证（免 API Key）

OpenClaw 还支持 OAuth 订阅认证，不想到处贴 API Key 可以用这个方式：

Anthropic：直接用 Claude Pro / Max / Team 账号登录
OpenAI：用 ChatGPT / Codex 订阅登录

在 openclaw onboard 向导中选择对应的选项即可。

其他 Provider

json

// GPT (OpenAI)
{
  "llm": {
    "provider": "openai",
    "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

// DeepSeek（性价比高）
{
  "llm": {
    "provider": "deepseek",
    "api_key": "sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

// Ollama（本地模型，完全免费）
{
  "llm": {
    "provider": "ollama",
    "base_url": "http://localhost:11434"
  }
}

性价比之选

DeepSeek 的 API 价格非常亲民，大约是 Claude/GPT 的 1/10 到 1/5。如果你只是想体验 OpenClaw 的功能，DeepSeek 是一个很好的起点。

Ollama 本地模型

Ollama 让你可以在本地运行 LLM，完全免费且无需网络。

第一步：安装 Ollama

bash

# macOS / Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows：从 ollama.com 下载安装包

第二步：下载模型

bash

ollama pull llama3.1           # Meta 的 Llama 3.1（8B，推荐）
ollama pull qwen2.5           # 阿里的通义千问（中文表现好）
ollama pull mistral            # Mistral 7B（轻量级）

第三步：配置 OpenClaw

json

{
  "llm": {
    "provider": "ollama",
    "base_url": "http://localhost:11434",
    "model": "llama3.1"
  }
}

本地模型的优缺点

优点：

完全免费
完全离线，隐私最大化
没有 API 调用限制

缺点：

需要较好的硬件（至少 8GB 内存，推荐有独立显卡）
模型能力通常不如 Claude/GPT 的最新版本
首次下载模型需要时间（几 GB 大小）

2.6 配置文件详解

安装完成后，OpenClaw 的配置文件位于 ~/.openclaw/openclaw.json。

配置文件的三个作用域

作用域	位置	作用范围
默认行为	什么都不配也能用	OpenClaw 用内置 Pi 以 RPC 模式运行，按发送者区分会话
用户配置	`~/.openclaw/openclaw.json`	当前用户所有项目
项目配置	`.openclaw.json`（项目目录）	仅当前项目

最小化加固配置示例

生产环境强烈建议至少配白名单：

json

{
  "channels": {
    "feishu": {
      "allowFrom": ["+8613800138000"],
      "groups": {
        "*": { "requireMention": true }
      }
    }
  },
  "messages": {
    "groupChat": {
      "mentionPatterns": ["@openclaw"]
    }
  }
}

字段	作用	建议
`channels.<渠道>.allowFrom`	白名单——只接受这些账号的消息	必配，避免陌生人触发智能体烧 token
`channels.<渠道>.groups."*".requireMention`	所有群组默认要 @ 才回复	建议 `true`
`messages.groupChat.mentionPatterns`	自定义触发词	起一个团队认得的名字

完整配置示例

json

{
  "channels": {
    "telegram": {
      "allowFrom": ["87654321"]
    }
  },
  "llm": {
    "provider": "anthropic",
    "api_key": "sk-ant-api03-xxxxx"
  }
}

不需要手动编辑

如果你使用 openclaw onboard 完成设置，大部分配置项都会自动生成。你只在需要调整的时候才需要手动编辑配置文件。

2.7 多实例部署

需要跑多个互不干扰的 Gateway（比如开发和生产分开、或多个账号）：

bash

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

要点：

OPENCLAW_CONFIG_PATH：独立配置文件
OPENCLAW_STATE_DIR：独立状态目录（保存会话、凭据等）
--port：换端口避免冲突

2.8 安全要点

默认绑回环：Gateway 默认只监听 127.0.0.1，不要随便改成公网
远程访问：优先用 Tailscale 或 SSH 隧道，不要直接暴露端口
非回环必须带 token：openclaw gateway --bind tailnet --token xxx
白名单：allowFrom 一定要配
群组默认 requireMention：避免机器人在群里被刷屏触发

2.9 常用命令速查

bash

# 引导式初始化（包含开机自启）
openclaw onboard --install-daemon

# 手动启动 Gateway
openclaw gateway --port 18789

# 配对/登录渠道
openclaw channels login

# 发送测试消息
openclaw message send --target <目标> --message "Hello"

# 万能排错
openclaw doctor

2.10 常见问题排查

现象	排查方向
仪表盘打不开	Gateway 没启动 → `openclaw gateway --port 18789`
渠道配对失败	重试 `openclaw channels login`，注意网络
切换安装方式后异常	`openclaw doctor`
群里 @ 了机器人不回复	检查 `/activation` 设置和 `mentionPatterns`
想限制谁能用	配 `allowFrom` 白名单
远程访问连不上	是否带 token，是否绑定到正确的网卡

万能命令：openclaw doctor。

本章小结

在这一章中，我们学习了：

三种安装方式：npm（最主流）、Docker（适合服务器部署）、OneClaw（适合非技术用户）
设置向导：openclaw onboard 帮你完成初始配置
LLM Provider 选择：Claude（最强）、GPT、DeepSeek（便宜）、Ollama（免费本地）、订阅认证（免 API Key）
配置文件：~/.openclaw/openclaw.json 是核心配置文件
常用命令：openclaw onboard、openclaw gateway、openclaw channels login、openclaw doctor
安全加固：白名单、requireMention、多实例隔离

下一步

安装完成后，让我们来了解 OpenClaw 的核心架构 -- 第三章：Gateway 架构。

第二章：安装与配置 ​

本章概览 ​

2.1 安装前准备 ​

系统要求 ​

准备 API Key ​

2.2 方法一：npm 安装 ​

第一步：确认 Node.js 版本 ​

第二步：全局安装 OpenClaw ​

第三步：验证安装 ​

第四步：运行引导式设置 ​

第五步：打开仪表盘 ​

第六步：发送第一条测试消息 ​

万能排错命令 ​

2.3 方法二：Docker 部署 ​

第一步：确认 Docker 环境 ​

第二步：拉取镜像 ​

第三步：创建配置目录 ​

第四步：运行容器 ​

第五步：运行设置向导 ​

常用 Docker 命令 ​

2.4 方法三：GUI 配置工具 ​

以OneClaw为例 ​

安装步骤 ​

2.5 配置 LLM Provider ​

Claude (Anthropic) ​

订阅认证（免 API Key） ​

其他 Provider ​

Ollama 本地模型 ​

2.6 配置文件详解 ​

配置文件的三个作用域 ​

最小化加固配置示例 ​

完整配置示例 ​

2.7 多实例部署 ​

2.8 安全要点 ​

2.9 常用命令速查 ​

2.10 常见问题排查 ​

本章小结 ​

第二章：安装与配置

本章概览

2.1 安装前准备

系统要求

准备 API Key

2.2 方法一：npm 安装

第一步：确认 Node.js 版本

第二步：全局安装 OpenClaw

第三步：验证安装

第四步：运行引导式设置

第五步：打开仪表盘

第六步：发送第一条测试消息

万能排错命令

2.3 方法二：Docker 部署

第一步：确认 Docker 环境

第二步：拉取镜像

第三步：创建配置目录

第四步：运行容器

第五步：运行设置向导

常用 Docker 命令

2.4 方法三：GUI 配置工具

以OneClaw为例

安装步骤

2.5 配置 LLM Provider

Claude (Anthropic)

订阅认证（免 API Key）

其他 Provider

Ollama 本地模型

2.6 配置文件详解

配置文件的三个作用域

最小化加固配置示例

完整配置示例

2.7 多实例部署

2.8 安全要点

2.9 常用命令速查

2.10 常见问题排查

本章小结