OpenClaw 本地部署与 AI 助理搭建实战指南

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

2.4 ClawHub

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

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

3.1 硬件与系统要求

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

💡 新手特别建议：
如果你是 Windows 原生系统用户，强烈建议安装 WSL2（Windows Subsystem for Linux 2），这是目前 Windows 环境下运行 OpenClaw 最稳定的方式。WSL2 的安装步骤可参考微软官方文档，全程 5 分钟即可完成。
如果你不想折腾本地环境，也可选择阿里云轻量应用服务器（OpenClaw 官方镜像），一键部署无需手动配置。

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

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

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

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

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

3.2.2 备选方案：OpenAI API-Key

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

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

3.3 工具准备

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: icmp_seq=1 ttl=56 time=18.2 ms
64 bytes from 120.25.108.199: icmp_seq=2 ttl=56 time=17.8 ms
--- dashscope.aliyuncs.com ping statistics ---
4 packets transmitted, 4 received, 0% packet loss, time 3004ms
rtt min/avg/max/mdev = 17.821/18.132/18.503/0.265 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 分钟，取决于网络速度）：

1. 检测系统类型（Linux/macOS/WSL2）；
2. 安装 Node.js（≥22.0.0 版本，OpenClaw 2026 版的最低要求）；
3. 安装 OpenClaw 核心程序，并配置环境变量；
4. 启动 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 配置（推荐新手）

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

配置模型信息：

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

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 执行技能类任务的完整流程：

1. 用户输入自然语言指令；
2. Gateway 接收指令；
3. 调用大模型解析意图；
4. 判断是否需要调用 Skills？
   • 否：大模型直接返回回答；
   • 是：Gateway 匹配对应 Skills（如 agent-browser）；
5. Skills 执行具体操作（访问网页、抓取数据）；
6. Skills 返回结构化数据给 Gateway；
7. 大模型整理数据为易读格式；
8. 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 关键说明

1. 本案例为虚拟构建，实际执行结果取决于开源中国页面结构、网络状态、技能版本；
2. 若执行失败，常见原因：
   • 网页结构更新，agent-browser 技能的抓取规则未适配；
   • 网络无法访问 oschina.net；
   • agent-browser 技能未正确加载。
3. 可通过 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）。

解决方案

1. 重新复制 API-Key，确保无多余字符；
2. 登录阿里云百炼控制台，检查 API-Key 状态（是否禁用/过期）；
3. 核对 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 可访问本地文件、网络资源，使用时需注意：

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

七、总结

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

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

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

再次声明：本文所有命令和操作步骤均基于公开技术文档撰写。实战案例为演示功能构建，非真实已实施项目。文中提及的技能调用结果基于官方演示逻辑模拟，实际效果请以你的测试为准。部署前建议查阅 OpenClaw 官方文档（https://openclaw.ai/docs）获取最新信息。