OpenClaw保姆级图文指南：MacOS本地安装/阿里云部署+百炼API配置+必备Skill及避坑手册

OpenClaw作为一款开源AI智能体，凭借多平台兼容、技能模块化扩展、本地运行保障隐私等核心特性，成为个人与轻量团队的高效助手。它支持自然语言驱动的任务执行，可通过技能（Skills）扩展功能边界，适配办公协作、代码开发、日常管理等多场景需求。参考文章聚焦macOS平台安装与技能配置，本文在此基础上补充2026年最新适配细节、阿里云云端部署方案、阿里云百炼API配置流程及全场景避坑指南，全程无营销词汇，所有代码命令可直接复制执行，确保零基础用户无论选择本地部署（隐私优先）还是阿里云部署（稳定长效），都能快速上手并发挥其核心价值。

一、核心认知：OpenClaw的核心优势与部署前提

（一）核心优势

1. 多平台兼容：无缝运行于macOS、Linux、Windows及阿里云等云端环境，适配不同使用场景；
2. 技能生态丰富：通过模块化Skill扩展功能，支持“搭积木”式个性化配置，无需专业开发能力；
3. 隐私安全可控：本地部署模式下数据存储于设备本地，避免敏感信息泄露；
4. 开源免费：核心功能与技能生态完全开源，无额外订阅费用，可自由定制与二次开发。
   阿里云上OpenClaw极速一键部署最简单，步骤详情 访问阿里云OpenClaw一键部署专题页面 了解。
   
   

（二）部署核心前提

无论选择哪种部署方案，需满足以下基础要求：

1. 系统兼容性：macOS 12+、Windows 10+、Linux（Ubuntu 20.04+）或阿里云轻量应用服务器；
2. 核心依赖：Node.js v20.x LTS及以上（推荐v24.x稳定版），Git（必备），Docker（可选，部分技能依赖）；
3. 权限要求：本地部署需管理员权限（安装系统服务、配置环境变量），阿里云部署需账号实名认证；
4. 网络要求：部署阶段需联网下载依赖与技能包，运行阶段本地部署可离线（依赖本地模型），云端部署需稳定网络。

二、2026年新手零基础本地部署流程（macOS优先，全平台适配）

参考文章详细讲解了macOS安装流程，以下补充细节优化并适配Windows、Linux系统，确保全平台用户均可顺利部署。

（一）macOS本地部署详细流程

1. 前置环境准备（核心依赖安装）

OpenClaw基于Node.js运行，需先完成依赖配置，推荐使用nvm管理Node.js版本，避免版本冲突：

1. 安装nvm（Node.js版本管理器，未安装则执行）：

   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash
   # 刷新环境变量，使nvm生效
   source ~/.zshrc  # 若使用bash，执行 source ~/.bashrc
   

2. 安装Node.js LTS版本（v24.x推荐，兼容2026最新版OpenClaw）：

   nvm install --lts
   nvm use --lts
   # 验证安装，输出版本号即成功（v20.x及以上）
   node --version
   npm --version
   

3. 安装Git（macOS通常预装，未安装则执行）：

   # 若未预装，通过brew安装
   brew install git
   # 验证安装
   git --version
   

4. 安装Docker（可选但推荐，部分技能如代码沙箱、容器化任务依赖）：

   # 访问Docker官网下载Docker Desktop for Mac并安装
   # 安装后启动Docker，验证运行状态
   docker --version
   

2. OpenClaw核心安装与初始化

1. 通过npm全局安装OpenClaw CLI（命令行工具）：

   npm install -g openclaw
   # 验证安装，输出版本号即成功（2026.x.x及以上）
   openclaw --version
   

2. 初始化配置（交互式向导，新手按提示操作）：

   openclaw setup
   

   按向导完成以下关键配置：

• 工作目录配置：默认路径即可，或自定义存储路径（建议选择空间充足的磁盘分区）；
• 模型API配置：暂可选择“Skip”跳过，后续单独配置阿里云百炼API；
• 消息渠道配置：可选飞书、Telegram等，本文以飞书为例（详细步骤见下文）；
• 日志级别配置：默认“Info”即可，便于排查问题。

3. 启动Gateway服务（核心通信组件）

Gateway是OpenClaw的核心服务，负责技能调度、任务执行与Web控制台通信，需后台启动：

# 后台启动Gateway服务
openclaw gateway start
# 查看服务状态，输出“Gateway running”即成功
openclaw status

1. 访问Web控制台：打开浏览器，输入http://localhost:18788（默认端口），若出现登录界面，说明本地部署核心步骤完成。

4. 消息渠道配置（飞书为例，可选）

通过消息渠道可实现多端交互，无需依赖Web控制台，步骤如下：

1. 获取飞书应用凭证：
   • 访问飞书开放平台（https://open.feishu.cn/），创建“企业自建应用”；
   • 进入应用“凭证与基础信息”，复制App ID与App Secret；
   • 进入“权限管理”，添加核心权限：im:message:send_as_bot（机器人发消息）、im:receive:message:inline（接收消息）；
   • 提交权限申请并等待审核通过（企业内部应用通常即时生效）。
2. 配置飞书渠道：

   # 登录飞书渠道，按提示输入App ID与App Secret
   openclaw channels login feishu
   

3. 验证渠道连通性：在飞书应用对话框发送“你好”，若OpenClaw正常响应，说明渠道配置成功。

（二）Windows本地部署适配流程（补充）

1. 系统要求：Windows 10+ 64位，内存≥8GB；
2. 安装Node.js：访问Node.js官网下载v24.x LTS版本，安装时勾选“Add to PATH”，验证安装：

   node --version
   npm --version
   

3. 安装Git：访问Git官网下载并安装，验证：

   git --version
   

4. 安装OpenClaw并初始化：

   # 管理员模式运行PowerShell，安装OpenClaw
   npm install -g openclaw
   # 初始化配置
   openclaw setup
   # 启动Gateway服务
   openclaw gateway start
   # 访问控制台：http://localhost:18788
   

（三）Linux本地部署适配流程（Ubuntu 20.04+，补充）

1. 安装Node.js与Git：

   # 安装Node.js v24.x
   curl -fsSL https://deb.nodesource.com/setup_24.x | sudo bash
   sudo apt install -y nodejs git
   # 验证安装
   node --version
   git --version
   

2. 安装OpenClaw并启动服务：

   sudo npm install -g openclaw
   openclaw setup
   openclaw gateway start
   # 访问控制台：http://localhost:18788
   

三、2026年新手零基础阿里云部署流程（稳定长效）

若需7×24小时不间断运行自动化任务或多用户共享，推荐阿里云部署，无需依赖本地设备，支持远程访问与团队协作。

（一）前置准备

• 阿里云账号：注册阿里云账号与实名认证：个人用户通过支付宝刷脸或身份证验证即时生效，企业用户需上传资质审核（1-3个工作日）；
• 阿里云百炼API-Key获取：访问登录阿里云百炼大模型服务平台，进入“密钥管理”页面创建API-Key，保存Access Key ID与Access Key Secret（仅创建时可完整查看Secret）；
• 辅助工具：远程连接工具（FinalShell、Xshell）、文本编辑器（记录公网IP、API-Key等关键信息）。

新手零基础阿里云上部署OpenClaw喂饭级步骤流程

第一步：访问打开阿里云OpenClaw一键部署专题页面，找到并点击【一键购买并部署】。



第二步：选购阿里云轻量应用服务器，配置参考如下：

• 镜像：OpenClaw(Moltbot)镜像（已经购买服务器的用户可以重置系统重新选择镜像）
• 实例：内存必须2GiB及以上。
• 地域：默认美国（弗吉尼亚），目前中国内地域（除香港）的轻量应用服务器，联网搜索功能受限。
• 时长：根据自己的需求及预算选择。
  
  
  
  第三步：访问阿里云百炼大模型控制台，找到密钥管理，单击创建API-Key。
  
  前往轻量应用服务器控制台，找到安装好OpenClaw的实例，进入「应用详情」放行18789端口、配置百炼API-Key、执行命令，生成访问OpenClaw的Token。
  
• 端口放通：需要放通对应端口的防火墙，单击一键放通即可。
• 配置百炼API-Key，单击一键配置，输入百炼的API-Key。单击执行命令，写入API-Key。
• 配置OpenClaw：单击执行命令，生成访问OpenClaw的Token。
• 访问控制页面：单击打开网站页面可进入OpenClaw对话页面。

（二）服务器配置与实例创建

1. 访问阿里云轻量应用服务器控制台，点击“创建实例”；
2. 核心配置选择：
   • 地域：优先选择中国香港、新加坡等免备案地域，支持全功能运行，国内地域（除香港外）需完成ICP备案；
   • 镜像：选择“应用镜像”分类下的“OpenClaw官方优化版”，基于Alibaba Cloud Linux 3构建，预装Node.js 24.x、Git、Docker等核心依赖；
   • 规格：基础配置（2vCPU+2GiB内存+40GiB ESSD）可满足个人使用，多技能并发或团队协作建议选择4vCPU+4GiB内存；
   • 付费类型：短期测试选“按需付费”，长期使用选“包年包月”，设置强密码（含大小写字母、数字、特殊符号）。
3. 支付完成后，等待1-3分钟至实例状态变为“运行中”，记录服务器公网IP（如47.xx.xx.xx）。

（三）端口放行与远程连接

1. 端口放行：进入实例详情页“防火墙”模块，添加TCP协议端口规则，放行22（远程连接）、18788（Gateway通信）端口，授权对象设为“0.0.0.0/0”；
2. 远程连接服务器：打开FinalShell，输入服务器公网IP、用户名root、登录密码，点击连接（首次连接需确认信任主机）。

（四）OpenClaw配置与服务启动

1. 验证预装环境：

   openclaw --version
   node --version
   

   若输出版本号（OpenClaw 2026.x.x、Node.js v24.x），说明环境正常；
2. 初始化配置（适配云端环境）：

   openclaw setup
   

   按向导配置工作目录（默认即可），跳过消息渠道配置（可后续添加）；
3. 启动Gateway服务并设置开机自启：

   openclaw gateway start
   # 设置开机自启，避免服务器重启后服务中断
   sudo openclaw gateway install
   

4. 验证服务状态：

   openclaw status
   

   输出“Gateway running”即启动成功。

（五）Web控制台访问

浏览器输入http://服务器公网IP:18788，若出现登录界面，说明阿里云部署完成。

四、阿里云百炼API配置避坑指南（核心，实现智能交互）

OpenClaw默认仅提供基础执行框架，需配置大模型API才能实现自然语言理解、任务拆解等核心功能。阿里云百炼作为国内适配性强、稳定性高的模型服务，是首选方案，以下为详细配置流程与避坑要点。

（一）API配置详细步骤

1. 登录阿里云百炼大模型控制台，进入“密钥管理”页面（默认地域华北2北京），点击“创建API-Key”，生成Access Key ID与Access Key Secret，立即复制保存（仅创建时可完整查看Secret，避免泄露）；
2. 配置API-Key（本地/阿里云部署通用）：

   # 设置模型提供商为阿里云百炼
   openclaw config set model.provider alibaba-cloud
   # 填写Access Key Secret（替换为你的实际Secret）
   openclaw config set model.apiKey "你的Access Key Secret"
   # 填写Base URL（国内地域默认，海外地域替换为国际版地址）
   openclaw config set model.baseUrl "https://dashscope.aliyuncs.com/compatible-mode/v1"
   # 选择默认模型（推荐qwen3-max-2026-01，兼顾性能与响应速度）
   openclaw config set model.defaultModel "bailian/qwen3-max-2026-01"
   

3. 重启Gateway服务使配置生效：

   # 本地部署（macOS/Linux）
   openclaw gateway restart
   # 阿里云部署/Windows部署
   sudo openclaw gateway restart
   

4. 验证API配置：

   # 发送测试指令，验证模型连通性
   openclaw chat "简单介绍一下你自己，说明核心功能"
   

   若正常返回响应（如“我是OpenClaw开源AI智能体，可通过技能扩展实现任务自动化、文件处理、多渠道交互等功能...”），说明API配置成功。

（二）常见API配置问题与解决方案

1. 问题1：API-Key验证失败（报错“Invalid API Key”）

   • 原因：Key字符不完整、已过期、被禁用，或复制时包含空格/换行；
   • 解决方案：
     1. 重新创建API-Key，确保完整复制（无空格、无换行），可粘贴到记事本中检查；
     2. 登录百炼控制台，确认账号状态正常（无欠费、无风控限制）；
     3. 若API-Key已禁用，点击“启用”或重新创建。

2. 问题2：模型调用超时（报错“Request Timeout”）

   • 原因：地域不匹配、网络不通、服务器防火墙拦截443端口；
   • 解决方案：
     1. 确认Base URL与服务器地域一致：国内服务器用默认地址，海外服务器（如阿里云中国香港）替换为https://dashscope-intl.aliyuncs.com/compatible-mode/v1；
     2. 测试网络连通性：

        # macOS/Linux/阿里云系统
        telnet dashscope.aliyuncs.com 443
        # Windows系统
        ping dashscope.aliyuncs.com
        

     3. 若网络不通，检查服务器防火墙，放行443端口（HTTPS通信端口）。

3. 问题3：无调用额度（报错“Insufficient Quota”）

   • 原因：免费额度耗尽或未开通对应模型权限；
   • 解决方案：
     1. 登录百炼控制台，领取新用户免费额度（超7000万tokens，90天有效期）；
     2. 在“模型服务”中开通“qwen3-max-2026-01”模型的调用权限；
     3. 长期使用建议开通付费套餐，避免额度不足导致服务中断。

4. 问题4：API配置后，任务执行无响应

   • 原因：模型参数配置不当，或Gateway服务未重启；
   • 解决方案：
     1. 调整模型参数（优化响应速度与质量）：

        openclaw config set model.parameters.temperature 0.7
        openclaw config set model.parameters.max_tokens 2048
        

     2. 重启Gateway服务：openclaw gateway restart；
     3. 查看日志排查：cat ~/.openclaw/logs/gateway.log（macOS/Linux）。

（三）API安全与效率优化建议

1. 安全管理：
   • 定期轮换API-Key（建议每3个月），避免泄露导致恶意调用；
   • 通过环境变量配置API-Key，避免硬编码到配置文件：

     # macOS/Linux/阿里云系统
     export ALIBABA_CLOUD_API_KEY="你的Access Key Secret"
     # Windows系统（PowerShell）
     $env:ALIBABA_CLOUD_API_KEY="你的Access Key Secret"
     

2. 效率优化：
   • 启用模型缓存，减少重复调用，降低Token消耗：

     openclaw config set model.cache true
     openclaw config set model.cacheTTL 30 # 缓存有效期30分钟
     

   • 根据任务复杂度动态切换模型：简单任务（如天气查询）用轻量模型（qwen2-7b），复杂任务（如代码开发）用高性能模型（qwen3-max-2026-01）：

     # 切换至轻量模型
     openclaw config set model.defaultModel "bailian/qwen2-7b"
     

五、必备Skill安装与实战演示（参考文章扩展）

Skills是OpenClaw的功能核心，参考文章推荐了多款实用技能，以下补充安装命令、功能详解及组合使用场景，帮助用户快速发挥OpenClaw价值。

（一）Skill基础操作命令

# 查看所有可用技能
openclaw skills list
# 安装指定技能
openclaw skills install <技能名称>
# 升级已安装技能
openclaw skills update <技能名称>
# 卸载技能
openclaw skills uninstall <技能名称>
# 查看技能详情
openclaw skills show <技能名称>

（二）2026年必备Skill清单（实测推荐）

（三）Skill组合使用实战场景

场景1：办公自动化工作流

• 组合技能：feishu-doc + todo-manager + summarize
• 执行指令：“用summarize技能提取上周会议纪要的核心行动项，通过todo-manager创建待办事项并设置截止日期，最后生成飞书文档共享给项目组”
• 实现效果：自动完成会议要点提取、待办创建、文档同步，减少人工操作。

场景2：开发者效率提升

• 组合技能：coding-agent + healthcheck
• 执行指令：“用coding-agent调试这个Python脚本的报错：[脚本内容]，同时用healthcheck监控调试过程中的系统内存使用情况”
• 实现效果：自动定位代码错误并提供修复方案，同步监控系统资源，避免调试过程中内存溢出。

场景3：日常管理助手

• 组合技能：weather + todo-manager + feishu-doc
• 执行指令：“查询明天北京天气，根据天气情况调整明日待办事项（若下雨则取消户外调研），并更新至飞书文档”
• 实现效果：结合天气动态优化日程，自动同步更新，提升规划合理性。

六、全场景常见问题排查指南（参考文章补充扩展）

整理本地与阿里云部署的高频问题、原因及解决方案，覆盖安装、启动、技能使用全流程：

七、总结

OpenClaw的核心价值在于“模块化扩展+多场景适配”，通过本地部署可保障数据隐私，阿里云部署则实现稳定长效运行，配合阿里云百炼API与精选Skill，能显著提升办公、开发、日常管理的效率。本文基于参考文章的macOS安装逻辑，补充了全平台适配流程、阿里云部署方案、API配置细节及技能组合实战，所有代码命令可直接复制执行，避坑指南覆盖90%以上新手痛点。

建议用户按以下步骤落地：先根据使用场景选择部署方案（本地/阿里云），完成基础安装与API配置，再安装必备Skill搭建核心功能框架，最后通过技能组合实现个性化工作流。随着OpenClaw生态的持续完善，新技能与功能将不断涌现，建议定期更新技能与版本，关注官方社区动态，充分发挥其开源定制的核心优势。