第二章：安装与配置

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

本章概览

在这一章中，你将学习：

三种安装 OpenClaw 的方法（npm / Docker / OneClaw 桌面版）
如何使用 openclaw onboard 完成初始设置
如何选择和配置 LLM Provider
如何验证安装是否成功

选择适合你的方式

完全不懂命令行？ 直接跳到方法三：OneClaw 桌面版
会用基本命令行？ 推荐方法一：npm 安装
熟悉 Docker？ 试试方法二：Docker 部署

2.1 安装前准备

系统要求

要求	最低配置	推荐配置
操作系统	Windows 10 / macOS 12 / Ubuntu 20.04	最新版本
内存	4 GB	8 GB+
磁盘空间	500 MB	2 GB+（含本地模型）
网络	需要（使用云端 LLM 时）	宽带连接
Node.js	v18+（方法一需要）	v20 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

你应该看到类似 v20.11.0 的输出。如果版本低于 v18，需要先升级 Node.js。

没有 Node.js？

如果提示 "command not found" 或 "不是内部命令"，说明你还没有安装 Node.js。

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

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

第二步：全局安装 OpenClaw

bash

npm install -g openclaw@latest

这个命令会：

从 npm 仓库下载 OpenClaw 最新版本
将它安装为全局命令行工具
安装过程通常需要 1-3 分钟

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

added 342 packages in 45s

12 packages are looking for funding
  run `npm fund` for details

权限问题？

如果在 macOS 或 Linux 上遇到权限错误，可以用 sudo：

bash

sudo npm install -g openclaw@latest

在 Windows 上，请以管理员身份运行命令提示符或 PowerShell。

第三步：验证安装

bash

openclaw --version

你应该看到版本号输出，比如：

openclaw v1.x.x

第四步：运行设置向导

bash

openclaw onboard

这是 OpenClaw 的交互式设置向导，它会引导你完成初始配置。

向导界面大致如下：

🐾 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 等
设置消息平台 -- 可以稍后配置，先跳过也行
完成！ -- 设置向导会生成配置文件

🐾 OpenClaw is ready!

Your config has been saved to ~/.openclaw/config.yaml

Quick start:
  openclaw start          # Start the assistant
  openclaw gateway add    # Add a messaging platform
  openclaw skills list    # Browse available skills

Happy clawing! 🐾

第五步：启动 OpenClaw

bash

openclaw start

如果一切正常，你会看到：

🐾 OpenClaw is running!

Agent: Claude Sonnet
Gateway: No platforms connected yet
Status: Waiting for messages...

Tip: Run 'openclaw gateway add' to connect a messaging platform

后台运行

如果你想让 OpenClaw 在后台持续运行（推荐），可以使用 Daemon 模式：

bash

openclaw start --daemon

这样即使关闭终端窗口，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 3000:3000 \
  openclaw/openclaw:latest

参数解释：

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

第五步：运行设置向导

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 的回调），你需要确保：

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

2.4 方法三：OneClaw 桌面版

最适合非技术用户

如果你不想碰命令行，OneClaw 就是为你准备的。它是 OpenClaw 的桌面应用包装版，提供图形化界面。

什么是 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 的首次设置

打开 OneClaw 后，你会看到一个简洁的设置界面：

┌─────────────────────────────────────┐
│          Welcome to OneClaw         │
│                                     │
│  Step 1: Choose LLM Provider        │
│  ┌─────────────────────────────┐    │
│  │ ○ Claude (Anthropic)        │    │
│  │ ○ GPT (OpenAI)              │    │
│  │ ○ DeepSeek                  │    │
│  │ ○ Ollama (Local)            │    │
│  └─────────────────────────────┘    │
│                                     │
│  Step 2: Enter API Key              │
│  ┌─────────────────────────────┐    │
│  │ sk-ant-xxxxxxxxxxxxxxxxxxxx │    │
│  └─────────────────────────────┘    │
│                                     │
│  [Next →]                           │
└─────────────────────────────────────┘

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

2.5 配置 LLM Provider

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

Claude (Anthropic)

yaml

# ~/.openclaw/config.yaml
llm:
  provider: anthropic
  api_key: sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxx
  model: claude-sonnet-4-20250514
  max_tokens: 4096

获取 API Key 的步骤：

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

API Key 安全

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

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

可选模型：

模型	适用场景	成本
`claude-sonnet-4-20250514`	日常使用（推荐）	中等
`claude-opus-4-20250514`	复杂任务	较高
`claude-haiku-3-20250307`	简单任务、省钱	低

GPT (OpenAI)

yaml

# ~/.openclaw/config.yaml
llm:
  provider: openai
  api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  model: gpt-4o
  max_tokens: 4096

获取 API Key 的步骤：

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

DeepSeek

yaml

# ~/.openclaw/config.yaml
llm:
  provider: deepseek
  api_key: sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
  model: deepseek-chat
  max_tokens: 4096

性价比之选

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

yaml

# ~/.openclaw/config.yaml
llm:
  provider: ollama
  base_url: http://localhost:11434
  model: llama3.1
  max_tokens: 4096

本地模型的优缺点

优点：

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

缺点：

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

2.6 配置文件详解

安装完成后，OpenClaw 的配置文件位于 ~/.openclaw/config.yaml。以下是一个完整的配置示例：

yaml

# ~/.openclaw/config.yaml

# LLM 配置
llm:
  provider: anthropic           # anthropic / openai / deepseek / ollama
  api_key: sk-ant-api03-xxxxx   # 你的 API Key
  model: claude-sonnet-4-20250514 # 使用的模型
  max_tokens: 4096              # 最大输出 token 数
  temperature: 0.7              # 回复的创造性（0-1，越高越有创意）

# Gateway 配置（后续章节详解）
gateway:
  port: 3000                    # Gateway 监听端口
  platforms: []                 # 连接的平台列表（后续配置）

# Agent 配置
agent:
  name: "My Assistant"          # 助手的名字
  language: "zh-CN"             # 默认语言
  system_prompt: |              # 系统提示词（可自定义）
    你是一个友好的 AI 助手，请用中文回复。

# 记忆配置
memory:
  enabled: true                 # 是否启用持久化记忆
  max_entries: 1000             # 最大记忆条目数

# 日志配置
logging:
  level: info                   # debug / info / warn / error
  file: ~/.openclaw/logs/openclaw.log

不需要手动编辑

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

2.7 常用命令速查

安装完成后，以下是你最常用的 OpenClaw 命令：

bash

# 基础命令
openclaw start            # 启动 OpenClaw
openclaw start --daemon   # 后台模式启动
openclaw stop             # 停止运行
openclaw status           # 查看运行状态
openclaw restart          # 重新启动

# 设置与配置
openclaw onboard          # 运行设置向导
openclaw config edit      # 编辑配置文件
openclaw config show      # 显示当前配置

# Gateway 管理
openclaw gateway add      # 添加消息平台
openclaw gateway list     # 查看已连接的平台
openclaw gateway remove   # 移除平台

# Skills 管理
openclaw skills list      # 查看已安装的技能
openclaw skills install   # 安装新技能
openclaw skills search    # 搜索可用技能

# 其他
openclaw logs             # 查看日志
openclaw update           # 更新到最新版本
openclaw --help           # 查看帮助

2.8 验证安装

让我们来验证一切是否正常工作。

快速测试

bash

# 启动 OpenClaw
openclaw start

# 在另一个终端窗口中，发送一条测试消息
openclaw chat "你好，请介绍一下你自己"

如果一切正常，你应该会收到 AI 的回复。

常见问题排查

问题：openclaw 命令找不到

原因： npm 全局安装的路径不在系统 PATH 中

解决方法：

bash

# 查看 npm 全局安装路径
npm config get prefix

# 确保该路径在你的 PATH 环境变量中
# macOS/Linux: 编辑 ~/.bashrc 或 ~/.zshrc
# Windows: 通过系统设置添加环境变量

问题：API Key 无效

原因： Key 输入有误，或者账户余额不足

解决方法：

检查 ~/.openclaw/config.yaml 中的 api_key 字段
确保 Key 是完整复制的，没有多余的空格
登录对应的 API 平台，检查账户余额和 Key 状态

问题：端口 3000 被占用

原因： 其他程序正在使用 3000 端口

解决方法：

bash

# 查看端口占用
lsof -i :3000    # macOS/Linux
netstat -ano | findstr :3000   # Windows

# 或者修改 OpenClaw 的端口
# 编辑 ~/.openclaw/config.yaml
gateway:
  port: 3001    # 改为其他端口

问题：Ollama 连接失败

原因： Ollama 服务没有启动

解决方法：

bash

# 确保 Ollama 正在运行
ollama serve

# 测试 Ollama 是否响应
curl http://localhost:11434/api/tags

本章小结

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

三种安装方式：npm（最主流）、Docker（适合服务器部署）、OneClaw（适合非技术用户）
设置向导：openclaw onboard 帮你完成初始配置
LLM Provider 选择：Claude（最强）、GPT、DeepSeek（便宜）、Ollama（免费本地）
配置文件：~/.openclaw/config.yaml 是核心配置文件
常用命令：start、stop、status、gateway、skills 等

下一步

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

第二章：安装与配置 ​

本章概览 ​

2.1 安装前准备 ​

系统要求 ​

准备 API Key ​

2.2 方法一：npm 安装 ​

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

第二步：全局安装 OpenClaw ​

第三步：验证安装 ​

第四步：运行设置向导 ​

第五步：启动 OpenClaw ​

2.3 方法二：Docker 部署 ​

第一步：确认 Docker 环境 ​

第二步：拉取镜像 ​

第三步：创建配置目录 ​

第四步：运行容器 ​

第五步：运行设置向导 ​

常用 Docker 命令 ​

2.4 方法三：OneClaw 桌面版 ​

什么是 OneClaw？ ​

安装步骤 ​

OneClaw 的首次设置 ​

2.5 配置 LLM Provider ​

Claude (Anthropic) ​

GPT (OpenAI) ​

DeepSeek ​

Ollama (本地模型) ​

2.6 配置文件详解 ​

2.7 常用命令速查 ​

2.8 验证安装 ​

快速测试 ​

常见问题排查 ​

本章小结 ​

第二章：安装与配置

本章概览

2.1 安装前准备

系统要求

准备 API Key

2.2 方法一：npm 安装

第一步：确认 Node.js 版本

第二步：全局安装 OpenClaw

第三步：验证安装

第四步：运行设置向导

第五步：启动 OpenClaw

2.3 方法二：Docker 部署

第一步：确认 Docker 环境

第二步：拉取镜像

第三步：创建配置目录

第四步：运行容器

第五步：运行设置向导

常用 Docker 命令

2.4 方法三：OneClaw 桌面版

什么是 OneClaw？

安装步骤

OneClaw 的首次设置

2.5 配置 LLM Provider

Claude (Anthropic)

GPT (OpenAI)

DeepSeek

Ollama (本地模型)

2.6 配置文件详解

2.7 常用命令速查

2.8 验证安装

快速测试

常见问题排查

本章小结