OpenClaw开发环境搭建指南：Windows/Mac/Linux教程

本文是一份面向开发者的跨平台实战指南，手把手教你如何在 Windows、macOS 和 Linux 系统上零基础搭建 OpenClaw 本地开发环境——从验证 Node.js v18+ 运行时、执行平台专属一键安装脚本，到启动服务、配置 Moonshot AI（Kimi K2.5）作为首选中文大模型提供方，并完成运行时、网关、AI 接口三层连通性校验，全程覆盖常见坑点（如权限不足、网络限制、版本冲突），助你快速打通本地智能体开发全链路，即刻开启可调试、可扩展的 AI 应用构建之旅。

如果您希望在本地设备上完整搭建 OpenClaw 开发环境，但面临系统差异、依赖冲突或权限报错等问题，则可能是由于 Node.js 版本不兼容、终端权限不足或网络策略限制所致。以下是覆盖 Windows、macOS 和 Linux 三大平台的全路径部署操作步骤：

一、验证并安装 Node.js 运行时

OpenClaw 依赖 Node.js v18 或更高版本的 LTS 稳定版作为底层运行环境，未安装或版本过低将导致后续命令执行失败。需先确认当前环境是否满足最低要求，并按需安装或升级。

1、打开终端（Windows：PowerShell 管理员模式；macOS/Linux：默认终端）。

2、输入命令 node --version 检查已安装版本，若返回错误或显示低于 v18.0.0，则需重新安装。

3、访问 https://nodejs.org 下载并运行官方 LTS 安装包，全程点击「Next」使用默认配置即可完成路径注册与 npm 集成。

4、再次执行 node --version 与 npm --version，确认二者均成功输出有效版本号。

二、选择并执行平台适配安装方式

根据操作系统类型，采用对应安装脚本可自动处理依赖检测、权限配置及环境变量写入，避免手动干预引发的路径异常或权限拒绝问题。

1、Windows 用户（PowerShell 管理员模式）：
执行命令 iwr -useb https://openclaw.ai/install.ps1 | iex；若国内访问缓慢，改用镜像地址 iwr -useb https://open-claw.org.cn/install-cn.ps1 | iex。

2、macOS / Linux 用户（终端）：
执行命令 curl -fsSL https://openclaw.ai/install.sh | bash；如提示权限拒绝，前置添加 sudo 并输入密码继续。

3、通用验证步骤：
安装完成后，在任意终端窗口中输入 openclaw --version，应返回类似 2026.3.2 的版本标识。

三、启动服务并访问控制台

安装成功后需启动 OpenClaw 主进程，其内置 Web 控制台用于模型配置、技能管理与调试监控，必须确保网关服务处于监听状态才能正常访问。

1、在终端中输入命令 openclaw start 启动核心服务。

2、等待终端输出包含 Listening: 127.0.0.1:18791 的日志行，表明 Dashboard 已就绪。

3、打开本地浏览器，访问地址 http://localhost:18791，加载成功即进入图形化设置界面。

四、配置首个 AI 模型提供方

OpenClaw 默认不绑定任何大模型，需手动添加至少一个 AI Provider 才能启用意图理解与任务执行能力。中国用户推荐优先配置 Moonshot AI（Kimi K2.5），因其对中文语义支持更优且无需科学上网。

1、登录 https://platform.moonshot.cn/console，完成账号注册并登录。

2、点击左侧菜单栏「API Key 管理」→「创建 API Key」，复制生成的密钥字符串（以 sk-xxx 开头）。

3、回到 OpenClaw Dashboard 页面，进入 Settings → AI Providers → Add Provider。

4、选择 Moonshot AI 类型，填入刚复制的 API Key，并指定接入点为 https://api.moonshot.cn/v1。

5、点击 Save 后，页面应显示该 Provider 状态为 Active，表示模型通道已连通。

五、运行基础连通性校验

为确保各模块协同工作正常，需依次验证运行时、网关、AI 接口三层通信链路是否畅通，任一环节失败都将影响后续技能调用与自动化执行。

1、在终端中执行 openclaw gateway status，确认输出中包含 Listening: 127.0.0.1:18789。

2、执行 openclaw debug test-ai，等待返回结果中出现 Provider responded successfully 字样。

3、执行 Test-NetConnection -ComputerName 127.0.0.1 -Port 18789（仅 Windows），确认 TcpTestSucceeded: True。

今天带大家了解了的相关知识，希望对你有所帮助；关于科技周边的技术知识我们会一点点深入介绍，欢迎大家关注golang学习网公众号，一起学习编程~