OpenClaw 本地部署指南：从零搭建 AI 助理

摘要

本文聚焦开源 AI 代理工具 OpenClaw 的本地部署与实操，从核心概念拆解入手，先厘清 OpenClaw、Gateway、Skills、ClawHub 的关联，再明确硬件系统要求与大模型 API-Key 准备要点，通过官方一键安装脚本完成本地部署，并配置阿里云百炼 API 实现大模型对接。以虚拟实战案例，详细演示 Skills 调用流程，同时梳理部署中'命令找不到''API-Key 配置失败'等高频问题的解决方法。

关键词

OpenClaw、AI 助理、本地部署、Skills、Gateway、阿里云百炼、API-Key、开源 AI 代理、WSL2、ClawHub

一、开篇：为什么要自己搭一个 AI 助理？

2026 年，AI 技术的落地形态正从'纯对话式交互'向'任务执行式交互'转变，OpenClaw 作为开源 AI 代理领域的代表工具，正是这一趋势的典型产物。相较于 ChatGPT 网页版、文心一言等纯在线对话工具，OpenClaw 的核心差异在于'连接'与'执行'——它不是简单的'问答机器人'，而是能深度整合本地环境、第三方工具、网络服务的'数字员工'。

举个简单的例子：你想整理某技术论坛的热门内容，用传统 AI 工具只能得到'你可以手动打开网页、复制内容、整理表格'的建议；而 OpenClaw 能直接调用浏览器技能，自动访问网页、抓取指定板块数据、结构化整理成表格，全程无需你手动操作。

对普通用户而言，搭建个人版 OpenClaw 有三个核心价值：

隐私可控：所有交互和任务执行都在本地（或你自己的服务器）完成，无需将个人需求、文件数据上传至第三方平台；
功能自定义：通过 ClawHub 的 5700+ 社区技能，可自由扩展 AI 助理的能力（如管理本地文件、调用企业 API、自动化办公）；
低成本试用：对硬件要求极低，旧电脑、低配云服务器均可运行，且阿里云百炼等平台对新用户提供免费 API 额度，零成本即可上手。

本文将帮你解决以下核心问题，让你从'零基础'到'能用 OpenClaw 完成实际任务'：

OpenClaw 到底是什么？（厘清与 Clawdbot、Moltbot 的关系）；
我的电脑能否满足部署要求？（Windows/macOS/Linux 环境适配）；
如何一步步完成本地部署？（命令行实操 + 界面配置双教程）；
部署完成后如何验证功能？（虚拟实战：AI 助理自动查网页、整理数据）。

二、核心认知：先搞懂这 4 个关键概念，避免踩坑

很多新手在部署 OpenClaw 时踩坑，本质是没搞懂核心组件的关系。花 3 分钟理解以下 4 个概念，能帮你避开 80% 的部署问题。

2.1 OpenClaw（原 Clawdbot/Moltbot）

OpenClaw 的前身是 Clawdbot 和 Moltbot，2025 年完成品牌整合后统一命名为 OpenClaw，它是整个 AI 助理的'大脑 + 调度中心'——负责接收你的自然语言指令、解析意图、调度对应的技能、协调各组件完成任务。

核心注意点：OpenClaw 本身不包含大模型推理能力，它就像一个'空架子'，必须对接外部大模型的 API（如阿里云百炼、OpenAI）才能理解你的指令。这也是为什么部署时'配置 API-Key'是必不可少的步骤。

2.2 Gateway（网关）

Gateway 是 OpenClaw 的后台核心进程，也是你部署后需要长期运行的服务。你可以把它理解成'AI 助理的后台管家'：

负责管理 Web 控制台、聊天窗口等前端界面的连接；
监控所有 Skills 的运行状态；
处理大模型 API 的请求与响应；
维护 OpenClaw 的基础配置。

只要 Gateway 停止运行，你的 AI 助理就会'离线'，无法响应任何指令。

2.3 Skills（技能）

Skills 是 OpenClaw 的'手脚'，也是它能完成实际任务的核心。每个 Skill 都是一个模块化的功能插件，对应一类具体操作：

agent-browser：无头浏览器技能，支持自动访问网页、抓取数据、模拟点击；
file-manager：文件管理技能，支持新建/删除/编辑本地文件；
email-sender：邮件技能，支持自动发送邮件；
api-caller：API 调用技能，支持对接第三方接口。

没有安装 Skills 的 OpenClaw，即便对接了大模型，也只能和你'聊天'，无法完成任何实际操作。

2.4 ClawHub

ClawHub 是 OpenClaw 官方维护的'技能市场'，截至 2026 年 2 月，已有 5700+ 个社区贡献的 Skills 可供一键安装。你可以把它理解成手机的'应用商店'，通过简单的命令即可安装所需技能，无需自己开发代码。

三、准备工作：工欲善其事，必先利其器

3.1 硬件与系统要求

OpenClaw 的设计理念是'轻量化部署'，对硬件几乎没有门槛，官方推荐配置如下（亲测验证）：

硬件/系统	最低要求	推荐要求	备注
CPU	1 核	1 核及以上	无性能瓶颈，低配 CPU 仅影响技能执行速度
内存	1GB	2GB 及以上	低于 1GB 会导致 Gateway 启动失败，2GB 以上可流畅运行多技能
磁盘	10GB 剩余空间	20GB 剩余空间	需存储 Node.js、技能文件、日志等
系统	Linux（Ubuntu 18.04+）、macOS 10.15+、Windows 10/11（WSL2）	Linux（Ubuntu 20.04+）、macOS 12+、Windows 11（WSL2）	Windows 原生支持不稳定，易出现端口占用、技能调用失败问题

💡 新手特别建议：如果你是 Windows 原生系统用户，强烈建议安装 WSL2（Windows Subsystem for Linux 2），这是目前 Windows 环境下运行 OpenClaw 最稳定的方式。WSL2 的安装步骤可参考微软官方文档：https://learn.microsoft.com/zh-cn/windows/wsl/install（验证可访问），全程 5 分钟即可完成。如果你不想折腾本地环境，也可选择阿里云轻量应用服务器（OpenClaw 官方镜像），一键部署无需手动配置，后续系列文章会详细讲解。

3.2 核心凭证：大模型 API-Key（必备）

如前文所述，OpenClaw 需要对接外部大模型才能工作，API-Key 是连接大模型的'钥匙'。以下是适合新手的 API 获取方式（优先推荐国内平台）：

3.2.1 阿里云百炼 API-Key（国内用户首选）

步骤如下（亲测 2026 年 2 月有效）：

注册阿里云账号并完成实名认证：https://www.aliyun.com/（验证可访问）；
进入'百炼大模型控制台'：https://dashscope.console.aliyun.com/（验证可访问）；
点击左侧'密钥管理'，点击'创建密钥'，复制生成的'API-Key'（注意：密钥仅显示一次，需妥善保存）；
新用户福利：实名认证后可领取免费额度（qwen-turbo 模型约 100 万 tokens），足够新手测试使用。

3.2.2 备选方案：OpenAI API-Key

若你有 OpenAI 账号，可在 https://platform.openai.com/api-keys 创建 API-Key，但需注意：

需科学上网才能调用；
无免费额度，需绑定支付方式；
接口格式与阿里云百炼兼容，配置时仅需修改 Base URL 即可。

3.3 工具准备

工具类型	推荐工具	下载地址（验证可访问）	用途
终端工具	Windows Terminal	https://aka.ms/terminal	Windows 系统下的终端，支持 WSL2、CMD 等多环境
终端工具	macOS/Linux 终端	系统内置	直接执行命令行操作
SSH 工具（可选）	FinalShell	远程连接服务器时使用
浏览器	Chrome/Firefox	官方官网	访问 OpenClaw Web 控制台

3.4 环境预检

部署前需检查网络连通性和端口状态，避免后续部署失败。打开终端（Windows Terminal/WSL2/ macOS 终端），执行以下命令：

3.4.1 测试网络连通性

# 测试阿里云百炼接口连通性（国内用户）
ping dashscope.aliyuncs.com -c4
# 测试 OpenClaw 官方服务器连通性
ping openclaw.ai -c4

执行结果示例（正常情况）：

PING dashscope.aliyuncs.com (120.25.108.199) 56(84) bytes of data.
64 bytes from 120.25.108.199 (120.25.108.199): icmp_seq=1 ttl=56 time=18.2 ms
64 bytes from 120.25.108.199 (120.25.108.199): icmp_seq=2 ttl=56 time=17.8 ms
64 bytes from 120.25.108.199 (120.25.108.199): icmp_seq=3 ttl=56 time=18.5 ms
64 bytes from 120.25.108.199 (120.25.108.199): icmp_seq=4 ttl=56 time=17.9 ms
--- dashscope.aliyuncs.com ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3004ms
rtt min/avg//mdev = /// ms

若出现'100% packet loss'，说明网络不通，需检查网络设置或防火墙。

3.4.2 检查端口是否被占用

OpenClaw 默认使用 18789 端口作为 Web 控制台端口，需确保该端口未被占用：

# macOS/Linux/WSL2 系统
lsof -i:18789
# Windows CMD（WSL2 外）
netstat -ano | findstr :18789

执行结果说明：

若输出为空，说明端口未被占用（正常）；
若输出有进程信息，说明端口被占用，需先停止该进程（如 kill -9 进程 ID），或后续修改 OpenClaw 的端口配置。

四、实战部署：5 分钟安装 OpenClaw（本地版）

OpenClaw 官方提供了一键安装脚本，这是新手最易上手的方式，无需手动安装依赖、配置环境变量。

4.1 执行一键安装命令

在终端中输入以下命令（适用于 macOS/Linux/WSL2）：

curl -fsSL https://openclaw.ai/install.sh | bash

注：该链接为 OpenClaw 官方 2026 年 2 月最新安装地址，发文前已验证可访问；若后续失效，可访问 OpenClaw 官方文档（https://openclaw.ai/docs）获取最新脚本地址。

4.1.1 安装过程说明

脚本执行后会自动完成以下操作（全程约 2-3 分钟，取决于网络速度）：

检测系统类型（Linux/macOS/WSL2）；
安装 Node.js（≥22.0.0 版本，OpenClaw 2026 版的最低要求）；
安装 OpenClaw 核心程序，并配置环境变量；
启动 Gateway 服务，并提示是否打开 Web UI。

安装过程关键交互：当脚本执行到 How do you want to hatch your bot? 时，输入 1（选择'Open the Web UI'），回车后脚本会自动打开默认浏览器访问 OpenClaw 控制台。

安装成功提示：终端最后会输出类似以下内容，说明安装完成：

✅ OpenClaw installed successfully!
📌 Gateway is running (pid: 12345)
🌐 Web UI is available at: http://localhost:18789
🔧 To configure API-Key, visit the Settings page in Web UI.

4.2 配置 API-Key（让 AI 变聪明）

安装完成后，Gateway 已启动，但此时 OpenClaw 还没有'大脑'，需配置 API-Key 对接大模型。以下提供两种配置方式，新手优先选择 Web UI 配置。

4.2.1 方法一：Web UI 配置（推荐新手）

打开浏览器，访问 http://localhost:18789（若端口修改过，需替换为对应端口）；
首次进入会显示引导页面，点击'Go to Settings'进入配置页；
点击左侧'Model Providers'，点击'Add Provider'；
点击'Save'保存，然后点击左侧'Models'，点击'Add Model'；
点击'Save'，并点击'Set as Default'将该模型设为默认。

配置模型信息：

参数名	取值	说明
ID	qwen-turbo	阿里云通义千问轻量版，性价比高
Provider	bailian	选择上一步创建的 Provider

按以下参数配置阿里云百炼（关键参数需准确）：

参数名	取值	说明
Name	bailian	自定义名称，便于识别
API Type	openai-completions	阿里云百炼兼容 OpenAI 接口格式
API Key	你的阿里云百炼 API-Key	需完整复制，不含多余空格
Base URL	https://dashscope.aliyuncs.com/compatible-mode/v1	百炼 OpenAI 兼容接口地址

4.2.2 方法二：命令行配置（适合远程服务器）

若你部署在无图形界面的远程服务器，可通过命令行配置：

# 配置阿里云百炼 Provider
openclaw config set models.providers.bailian.apiKey "你的 API-Key"
openclaw config set models.providers.bailian.baseUrl "https://dashscope.aliyuncs.com/compatible-mode/v1"
openclaw config set models.providers.bailian.type "openai-completions"
# 配置默认模型
openclaw config set models.default "bailian/qwen-turbo"
# 重启 Gateway 使配置生效
openclaw restart

执行结果示例：

✅ Config updated successfully!
🔄 Restarting Gateway...
✅ Gateway restarted successfully (pid: 67890)

4.3 验证安装

配置完成后，需验证 OpenClaw 是否正常运行，执行以下命令：

# 查看 OpenClaw 版本
openclaw version
# 查看 Gateway 服务状态
openclaw status
# 运行健康检查
openclaw doctor

4.3.1 正常执行结果

# openclaw version 输出
OpenClaw v2026.02.01 (stable)
Node.js v22.1.0
OS: Linux x64 (Ubuntu 22.04)

# openclaw status 输出
Gateway is running (pid: 67890)
Web UI: http://localhost:18789
Skills loaded: 5 (agent-browser, file-manager, etc.)

# openclaw doctor 输出
✅ Network connectivity: OK
✅ Gateway service: Running
✅ Model provider config: Valid
✅ Default model: bailian/qwen-turbo (available)
✅ Port 18789: Not blocked
✅ Disk space: Sufficient (25GB free)

若所有检查项均为 ✅，说明安装和配置完全正常；若出现 ❌，需根据提示排查问题（详见本文第六节避坑指南）。

五、第一项虚拟实战：让 AI 助理动起来（技能初探）

现在你的 OpenClaw 已经有了'大脑'（大模型）和基础'手脚'（默认安装的 agent-browser 技能），我们通过一个虚拟实战案例，演示如何让它完成实际任务。

5.1 实战背景（虚拟案例）

你是一名科技爱好者，需要每日跟踪开源中国（oschina.net）的热门项目，但手动浏览、整理耗时较多。希望通过 OpenClaw 的 agent-browser 技能，自动访问开源中国首页，抓取'热门项目'板块的名称、简介、今日 Star 数，并整理成表格。

5.2 OpenClaw 执行任务的核心流程

在开始操作前，先了解 OpenClaw 执行技能类任务的完整流程（流程图如下）：

用户输入自然语言指令
Gateway 接收指令
调用大模型解析意图
是否需要调用 Skills？
- 是 -> Gateway 匹配对应 Skills（如 agent-browser）
  - Skills 执行具体操作（访问网页、抓取数据）
  - Skills 返回结构化数据给 Gateway
  - 大模型整理数据为易读格式
  - Gateway 返回结果给用户
- 否 -> 大模型直接返回回答

5.3 实操步骤

5.3.1 步骤 1：查看可用技能

打开 OpenClaw Web 控制台（http://localhost:18789），在聊天输入框中输入：

展示当前可用的 Skills

执行结果示例：

OpenClaw：当前已加载以下 Skills（共 5 个）： agent-browser（v2026.02）：无头浏览器技能，支持网页访问、数据抓取； file-manager（v2026.02）：本地文件管理技能； text-processor（v2026.02）：文本处理技能（格式化、翻译）； system-info（v2026.02）：系统信息查询技能； help-center（v2026.02）：帮助中心技能。

确认列表中包含 agent-browser 技能（2026 版默认内置），若未显示，执行 openclaw skills reload 刷新技能列表。

5.3.2 步骤 2：下达任务指令

在聊天输入框中输入清晰、具体的指令（指令越具体，执行结果越准确）：

用 agent-browser 技能访问开源中国首页（oschina.net），抓取页面中'热门项目'板块的所有项目，提取每个项目的名称、简介、今日 Star 数，整理成 Markdown 表格形式返回。

5.3.3 步骤 3：观察执行过程

输入指令后，OpenClaw 会显示执行进度：

OpenClaw：正在解析你的指令… OpenClaw：已匹配到技能：agent-browser OpenClaw：agent-browser 技能正在启动无头浏览器… OpenClaw：正在访问 oschina.net… OpenClaw：正在抓取'热门项目'板块数据… OpenClaw：正在整理数据…

整个过程约 10-15 秒（取决于网络速度）。

5.3.4 步骤 4：查看执行结果

虚拟执行结果示例（基于 agent-browser 技能官方演示逻辑构建）：

OpenClaw：任务执行成功！以下是开源中国首页'热门项目'板块的最新数据（抓取时间：2026-02-21 15:30）：

注：以上数据为页面实时抓取结果，若页面结构更新，可能导致抓取字段不全。

5.4 关键说明

本案例为虚拟构建，实际执行结果取决于开源中国页面结构、网络状态、技能版本；
若执行失败，常见原因：
- 网页结构更新，agent-browser 技能的抓取规则未适配；
- 网络无法访问 oschina.net；
- agent-browser 技能未正确加载。
可通过 openclaw logs gateway 查看执行日志，定位具体问题。

六、新手避坑指南（基于真实高频问题）

根据 OpenClaw 官方 GitHub Issues、阿里云开发者社区的高频问题，整理以下 5 个新手最易踩的坑及解决方案：

6.1 坑 1：执行 openclaw 命令提示'command not found'

原因

Node.js 未成功安装；
OpenClaw 未加入系统 PATH 环境变量；
安装脚本执行后未重启终端。

解决方案

# 1. 检查 Node.js 是否安装
node -v
# 若输出 v22.x.x，说明安装成功；若提示 command not found，重新安装 Node.js：
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs

# 2. 重载环境变量（Linux/macOS/WSL2）
source ~/.bashrc
# 若使用 zsh，执行 source ~/.zshrc

# 3. 验证 openclaw 命令
openclaw version

6.2 坑 2：API-Key 配置成功，但模型返回'Invalid API Key'

原因

API-Key 复制时包含多余空格/换行；
阿里云账号未实名认证，或 API-Key 已过期；
Base URL 配置错误（如少写'compatible-mode'）。

解决方案

重新复制 API-Key，确保无多余字符；
登录阿里云百炼控制台，检查 API-Key 状态（是否禁用/过期）；
核对 Base URL：阿里云百炼的 OpenAI 兼容地址必须是 https://dashscope.aliyuncs.com/compatible-mode/v1；

测试 API-Key 有效性（通过 curl 命令）：

curl https://dashscope.aliyuncs.com/compatible-mode/v1/chat/completions \
-H"Content-Type: application/json" \
-H"Authorization: Bearer 你的 API-Key" \
-d'{ "model": "qwen-turbo", "messages": [{"role": "user", "content": "你好"}] }'

若返回包含'choices'的 JSON 数据，说明 API-Key 有效；若返回'Invalid API Key'，需重新创建 API-Key。

6.3 坑 3：18789 端口无法访问，浏览器显示'无法连接'

原因

Gateway 服务未启动；
系统防火墙/安全组拦截了 18789 端口；
端口被其他进程占用。

解决方案

# 1. 确认 Gateway 已启动
openclaw status
# 若显示'Gateway is not running'，启动服务：
openclaw start

# 2. 开放防火墙端口（Linux）
ufw allow 18789/tcp
ufw reload

# 3. 若端口被占用，修改 OpenClaw 端口配置
# 编辑配置文件
nano ~/.openclaw/openclaw.json
# 找到"server": {"port": 18789}，修改为 18790（或其他未占用端口）
# 保存后重启 Gateway
openclaw restart
# 访问新地址：http://localhost:18790

6.4 坑 4：技能调用无响应，提示'Skill not found'

原因

技能未安装，或技能列表未刷新；
技能名称输入错误（如写成 agent_browser 而非 agent-browser）；
权限不足，无法加载技能文件。

解决方案

# 1. 查看已安装技能
openclaw skills list
# 2. 若未找到 agent-browser，手动安装
openclaw skills install agent-browser
# 3. 刷新技能列表
openclaw skills reload
# 4. 检查技能权限
chmod -R 755 ~/.openclaw/skills

6.5 坑 5：Windows 原生系统部署后，Gateway 启动失败

原因

Windows 原生系统对 Node.js 的子进程管理、文件路径处理存在兼容性问题。

解决方案

彻底卸载 Windows 原生部署的 OpenClaw；
安装 WSL2（参考微软官方文档）；
在 WSL2 中重新执行一键安装脚本（亲测 Windows 11 + WSL2 Ubuntu 22.04 无兼容性问题）。

6.6 安全提醒

OpenClaw 的 Skills 可访问本地文件、网络资源，使用时需注意：

首次使用时，避免授予 Skills 过高权限（如禁止 file-manager 技能访问系统盘）；
不要在生产环境中部署未验证的第三方 Skills；
定期修改 API-Key，避免密钥泄露。

七、总结

本文从新手视角出发，完成了 OpenClaw 本地部署的全流程讲解，核心要点如下：

OpenClaw 是轻量化开源 AI 代理工具，核心由 Gateway（后台服务）、Skills（功能插件）、外部大模型 API 组成，本身无推理能力；
本地部署的核心步骤为：环境预检→一键安装→配置 API-Key→验证服务，Windows 用户优先使用 WSL2 环境；
Skills 是 OpenClaw 的核心价值所在，通过 agent-browser 等技能可实现'自然语言驱动的实际任务执行'；
部署中常见问题（命令找不到、API-Key 失效、端口无法访问）均可通过日志排查、参数核对解决。

相较于在线 AI 工具，OpenClaw 的优势在于隐私可控、功能可扩展，即便你是零基础新手，也可通过本文的步骤快速搭建属于自己的本地 AI 助理。下一篇文章将聚焦'云部署'，带你实现 OpenClaw 的 7×24 小时在线，并打通钉钉/飞书，让 AI 助理随时随地响应你的指令。

OpenClaw 本地部署指南：从零搭建 AI 助理