【OpenClaw从入门到精通】：环境搭建全攻略——Windows/macOS/Linux三平台部署指南（2026实测）

1. 先搞清楚 OpenClaw 到底装了什么OpenClaw 是一个跑在本地的 AI 助手运行时你可以把它理解成一个「常驻后台的调度中枢」它对外暴露一个 Gateway 端口默认 18789对内管理多个 agent、渠道和技能。你平时用命令行、Web 控制台或者消息渠道跟它对话真正干活的是它背后调用的模型服务。它适合谁三类人最合适一是想在自己电脑上跑一个私有 AI 助手的开发者二是需要把 AI 能力接进现有脚本、定时任务的自动化玩家三是想研究 agent 编排、渠道接入的技术同学。如果你只是想随便聊两句用网页版就够了不必折腾本地部署。环境搭建之所以是第一步是因为 OpenClaw 对运行时版本、系统权限、网络端口都比较敏感。Node.js 版本低一个小版本openclaw命令可能直接报ERR_REQUIRE_ESM端口被占用Gateway 起不来API Key 没配好对话一直转圈。这篇就把 Windows、macOS、Linux 三平台的安装命令、依赖清单、config.toml骨架一次讲清并且用 TaoToken 统一 Key 和 API 通道完成接入最后跑一次真实启动加报错排查。先给一张三平台依赖对照表方便你对照自己的系统项目WindowsmacOSLinux推荐运行方式WSL2 Ubuntu原生原生Node.js 版本 22.0.0 22.0.0 22.0.0包管理器winget / nvm-windowsHomebrewapt / yum内存建议16GB16GB8GB 起磁盘可用15GB10GB10GB服务管理NSSMlaunchdsystemd注意Node.js 22 是硬门槛别用 18 或 20 凑合OpenClaw 的部分依赖用了较新的 ESM 特性低版本会在启动阶段就挂掉。2. 用 TaoToken 统一 Key 与 API 通道OpenClaw 本身不生产模型能力它需要连一个兼容 Anthropic 协议的 API 端点。这里我用 TaoToken 来做统一通道好处是一个 Key 走通所有模型调用不用在多个平台之间来回切换配置config.toml里只维护一份base_url和api_key就行。TaoToken 官网入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentopenclaw_setupAPI 端点固定为https://taotoken.net/api 这个地址不加 UTM 参数直接写进配置。你需要先去控制台创建一个 API Key然后把它填进 OpenClaw 的配置里。Key 的创建入口在控制台的 API Keys 页面拿到形如sk-xxxx的字符串后先存好后面三平台的配置都会用到它。提示不要把 Key 直接写进会提交到 Git 的文件里。推荐用环境变量注入或者放在~/.openclaw/config.toml这种本地配置文件中并确保该目录不被版本控制。如果你后面要长期跑编码类任务或者 Agent 编排可以关注 Coding Plan 方案它更适合高频调用场景只是验证模型连通性的话用模型对话页面手动测一次就够了。3. 三平台可复制配置3.1 WindowsWSL2 方案推荐以管理员身份打开 PowerShell先装 WSL2 和 Ubuntuwsl --install -d Ubuntu重启后从开始菜单进入 Ubuntu更新系统并装基础工具sudo apt update sudo apt upgrade -y sudo apt install -y curl git wget build-essential装 Node.js 22curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs node --version装 OpenClaw CLInpm install -g openclawlatest openclaw --version如果你确实不能用 WSL2原生 Windows 用 winget 装 Node 也行winget install OpenJS.NodeJS.LTS npm install -g openclawlatest3.2 macOSHomebrew 原生安装先装 Xcode 命令行工具和 Homebrew已装可跳过xcode-select --install brew install node node --versionApple Silicon 机器建议确认走的是 arm64 原生版本arch -arm64 npm install -g openclawlatest openclaw --version3.3 LinuxUbuntu / Debian 与 CentOSUbuntu / Debian 系sudo apt update sudo apt install -y curl git build-essential curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt-get install -y nodejs npm install -g openclawlatestCentOS / RHEL 系sudo yum install -y epel-release curl -fsSL https://rpm.nodesource.com/setup_22.x | sudo bash - sudo yum install -y nodejs npm install -g openclawlatest3.4 config.toml 骨架三平台通用OpenClaw 的配置文件默认在~/.openclaw/config.toml。下面这份骨架把 Gateway、模型通道、agent 默认参数都写好了你只需要替换api_key[gateway] port 18789 host 127.0.0.1 max_connections 100 timeout_ms 30000 [provider] name taotoken base_url https://taotoken.net/api api_key sk-你的Key model claude-sonnet-4-20250514 [agents.defaults] max_memory 4GB timeout_ms 30000Windows 原生环境下路径是C:\Users\你的用户名\.openclaw\config.tomlWSL2 里则跟 Linux 一致。改完配置后建议用openclaw config validate检查一遍语法避免 TOML 写错导致启动失败。4. 启动验证与成功结果配置写好后先做一次健康检查openclaw status openclaw health然后启动 Gatewayopenclaw gateway --port 18789 --verbose看到类似下面的输出就说明起来了[gateway] listening on 127.0.0.1:18789 [provider] taotoken connected, modelclaude-sonnet-4-20250514 [health] all checks passed浏览器打开http://127.0.0.1:18789/能看到 Web 控制台随便发一条消息如果模型正常返回内容说明 Key 和 API 通道都通了。这一步是整个环境搭建的验收动作过了这关后面接渠道、写技能才有意义。Linux 上如果要用 systemd 常驻可以建一个服务文件[Unit] DescriptionOpenClaw Gateway Afternetwork.target [Service] Typesimple EnvironmentTAOTOKEN_API_KEYsk-你的Key ExecStart/usr/bin/openclaw gateway --port 18789 Restarton-failure RestartSec10 [Install] WantedBymulti-user.target保存到/etc/systemd/system/openclaw.service后执行sudo systemctl daemon-reload sudo systemctl enable --now openclaw。5. 本篇常见报错排查报错一ERR_REQUIRE_ESM或Cannot find module基本是 Node.js 版本不对。用node --version确认是 22 以上Windows 上可以用 nvm-windows 切换nvm install 22 nvm use 22。报错二EADDRINUSE: address already in use :18789端口被占了。Linux/macOS 用lsof -i :18789找到进程再 killWindows 用netstat -ano | findstr :18789查 PID然后taskkill /PID PID /F。或者干脆在config.toml里换个端口。报错三对话一直转圈或返回 401Key 没配对或者base_url写错了。检查config.toml里base_url是不是https://taotoken.net/apiapi_key有没有多余空格。改完记得重启 Gateway。报错四macOS 上launchctl服务起不来先launchctl list | grep openclaw看状态再launchctl unload后重新load。日志在/tmp/openclaw.err里面通常有具体原因。报错五Linux 上 npm 全局安装权限不足别用 sudo 硬装配置用户级前缀更干净mkdir ~/.npm-global npm config set prefix ~/.npm-global echo export PATH~/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc报错六WSL2 里 localhost 访问不到WSL2 的网络是隔离的Windows 侧访问要用 WSL 的 IP或者直接在 WSL 内部用curl http://127.0.0.1:18789验证。新版 WSL2 支持 localhost 转发如果不行就wsl --update升级一下。6. 接下来怎么走环境跑通之后下一步通常是接渠道和写技能。如果你要长期跑编码任务或 Agent 编排建议直接上 Coding Plan省得每次手动配 Key只是偶尔验证模型效果用模型对话页面手动测就行。API 相关的细节和接入文档都在文档页遇到配置问题优先翻那里。我自己的习惯是每换一台机器先把config.toml骨架复制过去改 Key跑openclaw health三步确认环境没问题再动别的。这套流程在三平台上都验证过最省时间。