跳到主要内容
极客日志极客日志面向AI+效率的开发者社区
首页博客我的书AI学习GitHub 精选镜像AI 生图工具UI配色美学关于
搜索内容 / 工具 / 仓库 / 镜像...⌘K搜索
注册
博客列表
编程语言Node.jsAI

OpenClaw 本地部署实战:从零搭建首个 AI 助理

OpenClaw 是一款开源 AI 代理工具,支持本地化部署与大模型对接。其核心组件、硬件要求及阿里云百炼 API 配置流程,通过一键安装脚本快速搭建环境,演示技能调用实战,并梳理命令找不到、端口占用等常见问题的解决方案,帮助开发者构建隐私可控的自动化助手。

人间失格发布于 2026/4/10更新于 2026/9/1058 浏览
OpenClaw 本地部署实战:从零搭建首个 AI 助理

OpenClaw 本地部署实战:从零搭建首个 AI 助理

2026 年,AI 技术的落地形态正从纯对话向任务执行转变。OpenClaw 作为开源 AI 代理领域的代表工具,核心差异在于'连接'与'执行'——它不是简单的问答机器人,而是能深度整合本地环境、第三方工具、网络服务的数字员工。

对开发者而言,搭建个人版 OpenClaw有三个核心价值:

  1. 隐私可控:所有交互和任务执行都在本地完成,无需上传数据至第三方平台;
  2. 功能自定义:通过 ClawHub 的社区技能,可自由扩展 AI 助理的能力(如管理本地文件、调用企业 API);
  3. 低成本试用:旧电脑或低配云服务器均可运行,且阿里云百炼等平台提供免费 API 额度。

本文将带你从零基础开始,完成本地部署并验证核心功能。

一、核心认知:先搞懂这 4 个关键概念

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

1. OpenClaw(原 Clawdbot/Moltbot)

它是整个 AI 助理的'大脑 + 调度中心',负责接收自然语言指令、解析意图、调度对应的技能。注意:OpenClaw 本身不包含大模型推理能力,必须对接外部大模型的 API(如阿里云百炼、OpenAI)才能理解你的指令。

2. Gateway(网关)

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

  • 负责管理 Web 控制台、聊天窗口等前端界面的连接;
  • 监控所有 Skills 的运行状态;
  • 处理大模型 API 的请求与响应。 只要 Gateway 停止运行,你的 AI 助理就会离线。

3. Skills(技能)

Skills 是 OpenClaw 的'手脚',也是它能完成实际任务的核心。每个 Skill 都是一个模块化的功能插件:

  • agent-browser:无头浏览器技能,支持自动访问网页、抓取数据;
  • file-manager:文件管理技能,支持新建/删除/编辑本地文件;
  • email-sender:邮件技能,支持自动发送邮件。 没有安装 Skills 的 OpenClaw,即便对接了大模型,也只能和你'聊天',无法完成实际操作。

4. ClawHub

这是官方维护的'技能市场',截至 2026 年已有 5700+ 个社区贡献的 Skills 可供一键安装。你可以把它理解成手机的'应用商店',通过简单命令即可安装所需技能。

二、准备工作:工欲善其事,必先利其器

1. 硬件与系统要求

OpenClaw 的设计理念是轻量化部署,对硬件几乎没有门槛:

硬件/系统最低要求推荐要求备注
CPU1 核1 核及以上低配 CPU 仅影响技能执行速度
内存1GB2GB 及以上低于 1GB 会导致 Gateway 启动失败
磁盘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 最稳定的方式。

2. 核心凭证:大模型 API-Key

OpenClaw 需要对接外部大模型才能工作,API-Key 是连接大模型的'钥匙'。以下是适合新手的 API 获取方式:

阿里云百炼 API-Key(国内用户首选)
  1. 注册阿里云账号并完成实名认证;
  2. 进入'百炼大模型控制台';
  3. 点击左侧'密钥管理',创建密钥并复制生成的 API-Key(注意:密钥仅显示一次,需妥善保存);
  4. 新用户福利:实名认证后可领取免费额度(qwen-turbo 模型约 100 万 tokens),足够新手测试使用。
备选方案:OpenAI API-Key

若你有 OpenAI 账号,可在官网创建 API-Key,但需注意需科学上网且无免费额度。接口格式与阿里云百炼兼容,配置时仅需修改 Base URL 即可。

3. 环境预检

部署前需检查网络连通性和端口状态,避免后续部署失败。打开终端执行以下命令:

# 测试阿里云百炼接口连通性(国内用户)
ping dashscope.aliyuncs.com -c4

# 测试 OpenClaw 官方服务器连通性
ping openclaw.ai -c4

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

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

# macOS/Linux/WSL2 系统
lsof -i:18789

# Windows CMD(WSL2 外)
netstat -ano | findstr :18789

若输出为空,说明端口未被占用;若输出有进程信息,需先停止该进程或修改 OpenClaw 的端口配置。

三、实战部署:5 分钟安装 OpenClaw(本地版)

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

1. 执行一键安装命令

在终端中输入以下命令(适用于 macOS/Linux/WSL2):

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

脚本执行后会自动完成检测系统类型、安装 Node.js(≥22.0.0 版本)、安装 OpenClaw 核心程序、配置环境变量及启动 Gateway 服务。

当脚本执行到 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.

2. 配置 API-Key(让 AI 变聪明)

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

方法一:Web UI 配置(推荐新手)
  1. 打开浏览器,访问 http://localhost:18789(若端口修改过,需替换为对应端口);
  2. 首次进入会显示引导页面,点击"Go to Settings"进入配置页;
  3. 点击左侧"Model Providers",点击"Add Provider";
  4. 按以下参数配置阿里云百炼(关键参数需准确):
    • Name: bailian
    • API Type: openai-completions
    • API Key: 你的阿里云百炼 API-Key
    • Base URL: https://dashscope.aliyuncs.com/compatible-mode/v1
  5. 点击"Save"保存,然后点击左侧"Models",点击"Add Model",将 qwen-turbo 设为默认。
方法二:命令行配置(适合远程服务器)

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

# 配置阿里云百炼 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

3. 验证安装

配置完成后,需验证 OpenClaw 是否正常运行:

# 查看 OpenClaw 版本
openclaw version

# 查看 Gateway 服务状态
openclaw status

# 运行健康检查
openclaw doctor

若所有检查项均为 ✅,说明安装和配置完全正常。

四、虚拟实战:让 AI 助理动起来(技能初探)

现在你的 OpenClaw 已经有了'大脑'和基础'手脚',我们通过一个虚拟实战案例,演示如何让它完成实际任务。

1. 实战背景

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

2. 实操步骤

步骤 1:查看可用技能

打开 OpenClaw Web 控制台,在聊天输入框中输入:

展示当前可用的 Skills

确认列表中包含 agent-browser 技能。若未显示,执行 openclaw skills reload 刷新技能列表。

步骤 2:下达任务指令

在聊天输入框中输入清晰、具体的指令:

用 agent-browser 技能访问开源中国首页(oschina.net),抓取页面中'热门项目'板块的所有项目,提取每个项目的名称、简介、今日 Star 数,整理成 Markdown 表格形式返回。
步骤 3:观察执行过程

输入指令后,OpenClaw 会显示执行进度:

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

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

步骤 4:查看执行结果

任务执行成功后,你会看到类似以下的结构化数据返回。注:以上数据为页面实时抓取结果,若页面结构更新,可能导致抓取字段不全。

五、新手避坑指南

根据高频问题,整理以下常见坑及解决方案:

1. 执行 openclaw 命令提示'command not found'

原因:Node.js 未成功安装或未加入系统 PATH 环境变量。 解决:

# 检查 Node.js 是否安装
node -v

# 若未安装,重新安装 Node.js
curl -fsSL https://deb.nodesource.com/setup_22.x | bash -
apt-get install -y nodejs

# 重载环境变量
source ~/.bashrc

# 验证 openclaw 命令
openclaw version

2. API-Key 配置成功,但模型返回'Invalid API Key'

原因:API-Key 包含多余空格、账号未实名认证或 Base URL 配置错误。 解决:

  1. 重新复制 API-Key,确保无多余字符;
  2. 登录阿里云百炼控制台,检查 API-Key 状态;
  3. 核对 Base URL:必须是 https://dashscope.aliyuncs.com/compatible-mode/v1。

3. 18789 端口无法访问,浏览器显示'无法连接'

原因:Gateway 服务未启动或端口被占用。 解决:

# 确认 Gateway 已启动
openclaw status

# 若未启动,启动服务
openclaw start

# 若端口被占用,修改 OpenClaw 端口配置
nano ~/.openclaw/openclaw.json
# 找到"server": {"port": 18789},修改为 18790
openclaw restart

4. 技能调用无响应,提示'Skill not found'

原因:技能未安装或名称输入错误。 解决:

# 查看已安装技能
openclaw skills list

# 若未找到 agent-browser,手动安装
openclaw skills install agent-browser

# 刷新技能列表
openclaw skills reload

5. Windows 原生系统部署后,Gateway 启动失败

原因:Windows 原生系统对 Node.js 的子进程管理存在兼容性问题。 解决:彻底卸载 Windows 原生部署的 OpenClaw,安装 WSL2 并在其中重新执行一键安装脚本。

安全提醒:OpenClaw 的 Skills 可访问本地文件、网络资源,使用时请注意权限控制,不要在生产环境中部署未验证的第三方 Skills,定期修改 API-Key。

六、总结

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

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

相较于在线 AI 工具,OpenClaw 的优势在于隐私可控、功能可扩展。下一篇文章将聚焦'云部署',带你实现 OpenClaw 的 7×24 小时在线,并打通钉钉/飞书,让 AI 助理随时随地响应你的指令。

注:文中部分实战案例为演示功能构建,非真实已实施项目。实际效果请以你的测试为准。

目录

  1. OpenClaw 本地部署实战:从零搭建首个 AI 助理
  2. 一、核心认知:先搞懂这 4 个关键概念
  3. 1. OpenClaw(原 Clawdbot/Moltbot)
  4. 2. Gateway(网关)
  5. 3. Skills(技能)
  6. 4. ClawHub
  7. 二、准备工作:工欲善其事,必先利其器
  8. 1. 硬件与系统要求
  9. 2. 核心凭证:大模型 API-Key
  10. 阿里云百炼 API-Key(国内用户首选)
  11. 备选方案:OpenAI API-Key
  12. 3. 环境预检
  13. 测试阿里云百炼接口连通性(国内用户)
  14. 测试 OpenClaw 官方服务器连通性
  15. macOS/Linux/WSL2 系统
  16. Windows CMD(WSL2 外)
  17. 三、实战部署:5 分钟安装 OpenClaw(本地版)
  18. 1. 执行一键安装命令
  19. 2. 配置 API-Key(让 AI 变聪明)
  20. 方法一:Web UI 配置(推荐新手)
  21. 方法二:命令行配置(适合远程服务器)
  22. 配置阿里云百炼 Provider
  23. 配置默认模型
  24. 重启 Gateway 使配置生效
  25. 3. 验证安装
  26. 查看 OpenClaw 版本
  27. 查看 Gateway 服务状态
  28. 运行健康检查
  29. 四、虚拟实战:让 AI 助理动起来(技能初探)
  30. 1. 实战背景
  31. 2. 实操步骤
  32. 步骤 1:查看可用技能
  33. 步骤 2:下达任务指令
  34. 步骤 3:观察执行过程
  35. 步骤 4:查看执行结果
  36. 五、新手避坑指南
  37. 1. 执行 openclaw 命令提示“command not found”
  38. 检查 Node.js 是否安装
  39. 若未安装,重新安装 Node.js
  40. 重载环境变量
  41. 验证 openclaw 命令
  42. 2. API-Key 配置成功,但模型返回“Invalid API Key”
  43. 3. 18789 端口无法访问,浏览器显示“无法连接”
  44. 确认 Gateway 已启动
  45. 若未启动,启动服务
  46. 若端口被占用,修改 OpenClaw 端口配置
  47. 找到"server": {"port": 18789},修改为 18790
  48. 4. 技能调用无响应,提示“Skill not found”
  49. 查看已安装技能
  50. 若未找到 agent-browser,手动安装
  51. 刷新技能列表
  52. 5. Windows 原生系统部署后,Gateway 启动失败
  53. 六、总结

更多推荐文章

查看全部
  • 6 款免费学术论文降低 AI 检测率工具实测
  • 本地项目首次推送至 Git 远程仓库指南
  • GitHub Copilot 上下文工程实战指南与 7 个核心技巧
  • Stable Diffusion WebUI 本地安装与配置教程
  • 滑动窗口算法实战:最大连续 1 与最小操作数
  • 字符串模拟题精选:思维与实现解析
  • MySQL 事务核心概念与隔离级别实战
  • 使用 CopilotKit 快速集成前端 AI 助手实战指南
  • 从一句话到一张图:看懂 Stable Diffusion 的“潜空间扩散”生成流程(配图详解)
  • Rust 与 WebAssembly 深度实战:浏览器与 Node.js 高性能应用
  • 2026 年 3 月全球 AI 前沿动态:模型、智能体与产业融合
  • OpenClaw 配置飞书机器人完整指南
  • 自然语言处理技术与应用实践
  • 实战指南:Stable Diffusion 模型部署问题排查与性能调优
  • GitHub Copilot 学生认证申请流程与注意事项
  • MCP 实战:利用 Figma 设计稿自动生成前端代码
  • DeepSeek 中冷启动数据与多阶段训练的作用
  • 一卡通核心交易平台国产数据库实践:架构、迁移与高可用
  • Android 面试核心知识点汇总:32 个模块技术问答解析
  • 生成式 AI 对企业的影响、应用场景及实现路径解析

相关免费在线工具

  • RSA密钥对生成器

    生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online

  • Mermaid 预览与可视化编辑

    基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online

  • 随机西班牙地址生成器

    随机生成西班牙地址(支持马德里、加泰罗尼亚、安达卢西亚、瓦伦西亚筛选),支持数量快捷选择、显示全部与下载。 在线工具,随机西班牙地址生成器在线工具,online

  • Base64 字符串编码/解码

    将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online

  • Base64 文件转换器

    将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online

  • Markdown转HTML

    将 Markdown(GFM)转为 HTML 片段,浏览器内 marked 解析;与 HTML转Markdown 互为补充。 在线工具,Markdown转HTML在线工具,online