OpenClaw 安装指南【详细保姆级教程，含常见问题解决方案】

1. 为什么 Windows 用户装 OpenClaw 总在第一步卡住OpenClaw 是一个跑在本地、能接管终端与文件系统的 AI 助手运行时你可以把它理解成一个「住在你电脑里的自动化管家」它通过 WebSocket 暴露一个网关端口浏览器或客户端连上去之后就能让模型帮你读写文件、执行命令、跑脚本。它适合谁适合想在 Windows 上做本地 AI Agent 实验、又不想把代码丢到云端的开发者也适合刚接触命令行、想找一个能跟做的部署项目练手的小白。问题在于OpenClaw 的原生运行环境是 Linux 系的官方安装脚本、systemd 服务、npm 全局路径这些设定全是按 Linux 习惯写的。Windows 直接跑会遇到一堆路径分隔符、权限、端口转发的问题。所以社区里最稳的方案是Windows 装 WSL2在 WSL2 里跑一个 Ubuntu再在 Ubuntu 里装 Node.js 22 和 OpenClaw。这套组合的好处是你既保留了 Windows 的图形界面和浏览器又拿到了一个几乎原生的 Linux 环境。我试过在纯 Windows 的 PowerShell 里硬装结果卡在openclaw: command not found和端口监听失败上折腾两小时没通。换成 WSL2 Ubuntu 之后从零到服务启动大概 25 分钟。这篇就按这个路线走把每一步的命令、配置片段、以及 401、local proxy failed 这类典型报错都拆开讲。你跟着敲遇到报错直接跳到第 5 节对照。需要提前说明的是OpenClaw 本身只是一个运行时框架它要调用模型能力就得配置一个兼容 OpenAI 协议的模型服务地址和 Token。这一步很多人会忽略导致服务起来了但请求一直 401。后面第 3 节我会给一份可直接复制的配置片段把 Base URL、Key、Model ID 三件套写清楚。2. WSL2 与 Ubuntu 环境准备从启用虚拟化到首次登录这一节的目标是让你在 Windows 上拥有一个能用的 Ubuntu 终端。整个过程分四步启用 WSL 功能、设置默认版本、安装 Ubuntu、初始化用户。每一步都有对应的 PowerShell 或终端命令照抄即可。2.1 启用 WSL 与虚拟机平台功能以管理员身份打开 Windows PowerShell。注意是「管理员身份」普通权限执行 dism 会报错。依次执行下面两条命令dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart第一条启用 Linux 子系统第二条启用虚拟机平台。两条都返回「操作成功完成」后重启计算机。重启是必须的不重启后面wsl --set-default-version 2会提示功能未启用。重启后再次以管理员身份打开 PowerShell设置 WSL 默认版本为 2wsl --set-default-version 2如果提示「WSL 2 需要更新其内核组件」去微软官方文档下载 WSL2 内核更新包安装即可装完再执行一次上面的命令。2.2 安装 Ubuntu 发行版推荐用命令行一键安装最省事wsl --install -d Ubuntu这条命令会自动下载并安装最新的 Ubuntu。如果你想要指定版本比如 22.04 LTS可以先用wsl --list --online看可用列表再wsl --install -d Ubuntu-22.04。安装完成后重启终端Ubuntu 会自动启动并进入初始化。备选方案是打开 Microsoft Store 搜索 Ubuntu 22.04 LTS 或 24.04 LTS点「获取」安装。两种方式效果一样命令行更快。2.3 初始化 Ubuntu 用户首次启动 Ubuntu 会要求设置用户名和密码。用户名建议用小写字母不要带特殊字符比如user或dev。如果输入了Invalid username错误说明你用了大写或符号换一个符合 Linux 命名规范的即可。密码输入时不会显示任何字符这是正常的输完回车再确认一次。这个密码后面sudo提权要用务必记住。忘了的话可以在 PowerShell 里wsl --user root进去重置但麻烦不如一开始记牢。初始化完成后你会看到类似userDESKTOP-XXXX:~$的提示符说明 Ubuntu 已经就绪。先更新一下系统包避免后面装 Node.js 时依赖冲突sudo apt update sudo apt upgrade -y这一步可能要几分钟取决于网络。如果 apt 源慢可以换成国内镜像源但这不是必须的先跑通再说。2.4 确认 WSL2 网络与端口转发基础WSL2 默认会把 Linux 里的监听端口映射到 Windows 的 localhost所以你在 Windows 浏览器里访问http://127.0.0.1:18789是能通的。但有一个坑如果你在 WSL2 里服务监听的是0.0.0.0Windows 侧访问127.0.0.1通常没问题如果监听的是::1或特定网卡可能连不上。OpenClaw 默认监听ws://127.0.0.1:18789这个地址在 WSL2 内部和 Windows 侧都能访问所以不用额外配端口转发。验证 WSL2 版本可以用wsl -l -v输出里VERSION列应该是2。如果是1执行wsl --set-version Ubuntu 2转换。WSL1 不支持完整的网络栈和 systemdOpenClaw 跑不起来。到这里环境准备就完成了。你手上应该有一个能正常sudo的 Ubuntu 终端网络能通WSL2 版本正确。下一节开始装 Node.js 和 OpenClaw 本体。3. Node.js 22 与 OpenClaw 安装配置可复制的 settings 片段这一节是全文技术密度最高的部分。OpenClaw 要求 Node.js v22 及以上低于这个版本会在安装脚本阶段报引擎不兼容。我们先把 Node.js 装好再跑 OpenClaw 安装脚本最后处理 PATH 和 Token 配置。3.1 安装 Node.js 22在 Ubuntu 终端里执行curl -fsSL https://deb.nodesource.com/setup_22.x | sudo -E bash - sudo apt install -y nodejs第一条命令把 NodeSource 的 22.x 仓库加到 apt 源里第二条安装。装完验证node -v npm -vnode -v应该输出v22.x.x或更高。如果输出的是v18或v20说明系统里已有旧版本需要先卸载再装或者用 nvm 切换。用 nvm 的话curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash source ~/.bashrc nvm install 22 nvm use 22 nvm alias default 22nvm 的好处是版本切换干净不会和 apt 装的 Node 打架。如果你已经用 apt 装了旧版建议sudo apt remove nodejs清掉再用 nvm。3.2 运行 OpenClaw 安装脚本curl -fsSL https://openclaw.ai/install.sh | bash脚本会自动下载 OpenClaw 并配置。过程中如果出现 npm 的 deprecated 警告可以忽略不影响功能。安装完成后如果提示openclaw: command not found说明 npm 全局 bin 目录不在 PATH 里执行下面的修复echo export PATH/home/你的用户名/.npm-global/bin:$PATH ~/.bashrc source ~/.bashrc把「你的用户名」替换成实际用户名比如user。然后openclaw --version应该能输出版本号。3.3 配置向导与 Token 设置运行配置向导openclaw onboard向导会依次问Welcome 输入 yesMode 选 advanced 或 quickstartModel Provider 这一步很关键如果你要接第三方兼容 OpenAI 协议的服务选 Skip 或对应选项后面手动配Channels 选 skip for nowSkills 按提示装依赖Hooks 选 skip for nowSystemd 服务在 WSL 里不支持直接跳过。Token 配置有两种方式。向导里如果问Generate and configure a gateway token now?选 Yes 会自动生成。如果选了 No手动设置openclaw config set gateway.auth.token $(openssl rand -hex 16)注意旧版本用的是gateway.token新版已废弃必须用gateway.auth.token否则配置不生效。接下来是模型服务配置。OpenClaw 通过 OpenAI 兼容协议调用模型你需要准备三件套Base URL、API Key、Model ID。配置文件在~/.openclaw/openclaw.json可以直接编辑也可以用openclaw config set逐项设置。一份可复制的配置片段如下{ gateway: { auth: { token: 你的网关Token } }, agents: { defaults: { model: claude-sonnet-4-20250514, baseUrl: https://taotoken.net/api, apiKey: 你的APIKey } } }这里baseUrl填https://taotoken.net/apiapiKey填你在 TaoToken 控制台创建的 Keymodel填你要用的模型 ID。三件套缺一不可少任何一个都会在请求阶段报 401 或 model not found。设置默认模型也可以用命令openclaw config set agents.defaults.model claude-sonnet-4-20250514 openclaw config set agents.defaults.baseUrl https://taotoken.net/api openclaw config set agents.defaults.apiKey 你的APIKey配置完成后查看 Token 是否写入成功cat ~/.openclaw/openclaw.json如果openclaw config get gateway.auth.token返回__OPENCLAW_REDACTED__这是安全机制在隐藏敏感值直接看 JSON 文件里的token字段即可。3.4 启动服务与访问openclaw gateway run看到listening on ws://127.0.0.1:18789就说明服务起来了。如果报Port 18789 is already in use先openclaw gateway stop再重启。在 Windows 浏览器访问http://127.0.0.1:18789/?token你的网关Token注意端口是 18789不是 18791。Token 要拼在 URL 的token参数里否则会返回 Unauthorized。4. 验证请求与成功结果从 401 到正常对话的完整链路服务起来不等于能用。这一节我们做一次完整的验证请求确认从网关到模型服务的链路是通的。很多人卡在「服务启动了但一发消息就报错」问题基本出在模型配置或 Token 传递上。4.1 用 curl 验证网关连通性先在 Ubuntu 终端里确认网关在监听curl -s http://127.0.0.1:18789/health如果返回{status:ok}或类似健康检查响应说明网关进程正常。如果连接被拒绝检查openclaw gateway run是否还在前台运行或者用openclaw gateway status看状态。4.2 验证模型服务三件套网关通了之后真正决定能不能对话的是模型服务配置。你可以先用 curl 直接测模型服务地址确认 Base URL 和 Key 有效curl -s https://taotoken.net/api/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer 你的APIKey \ -d { model: claude-sonnet-4-20250514, messages: [{role: user, content: ping}], max_tokens: 10 }如果返回包含choices字段的 JSON说明 Key 和 Base URL 都对。如果返回 401说明 Key 无效或没带上如果返回 model not found说明 Model ID 写错了。这一步能把问题范围缩小到「模型服务」还是「OpenClaw 配置」。4.3 在 Web 界面发起首次对话浏览器打开带 token 的地址后界面会加载出对话窗口。输入一句「你好帮我列出当前目录文件」如果 OpenClaw 返回了文件列表说明整条链路——浏览器 → 网关 → 模型服务 → 工具执行——全部打通。成功的结果长这样界面上先显示你的消息然后模型返回一段文本如果触发了工具调用还会显示执行的命令和输出。这时候你可以试着让它读一个文件、跑一个ls确认 Agent 能力正常。4.4 验证 Token 配置是否生效如果对话返回 Unauthorized先检查 URL 里的 token 是否和配置文件里的一致。可以这样对比grep token ~/.openclaw/openclaw.json把输出的值和浏览器 URL 里的token对比不一致就改 URL。另外注意如果你在配置向导里选了自动生成 Token但后来手动改了配置文件需要重启网关服务才会生效openclaw gateway stop openclaw gateway run验证通过后你就有了一套可用的 OpenClaw 环境。接下来把常见报错整理成对照表遇到问题直接查。5. 常见报错排查401、local proxy failed 与 OAuth 对照这一节按报错信息分类每条给出原因和修复动作。你遇到哪个就查哪个不用从头读。5.1 401 Unauthorized最常见。三种可能网关 Token 没传、模型 API Key 无效、Key 和 Base URL 不匹配。先确认浏览器 URL 带了?tokenxxx且 xxx 和~/.openclaw/openclaw.json里的gateway.auth.token一致。再确认模型服务的apiKey字段填的是有效 Key没有多余空格。最后确认baseUrl和 Key 是同一家服务的比如 Base URL 填https://taotoken.net/apiKey 就必须是 TaoToken 控制台创建的不能混用别家的。修复后重启网关openclaw gateway stop openclaw gateway run5.2 local proxy failed这个报错通常出现在 WSL2 网络模式切换或 Windows 侧有网络策略拦截时。表现是 OpenClaw 尝试连接模型服务地址失败日志里出现local proxy failed或connection refused。先在 Ubuntu 里测网络curl -I https://taotoken.net/api如果 curl 也失败说明 WSL2 的出网有问题。可以尝试重启 WSLwsl --shutdown然后重新打开 Ubuntu 终端。如果还是不行检查 Windows 的防火墙是否拦截了 WSL 的虚拟网卡把 WSL 相关规则放行。另一个原因是 OpenClaw 配置里写了本地代理地址但代理没启动。检查openclaw.json里有没有proxy字段如果有且指向127.0.0.1:xxxx确认那个端口有服务在跑或者直接删掉 proxy 字段走直连。5.3 reading choices 报错日志里出现reading choices或cannot read property choices of undefined说明模型服务返回的 JSON 结构不符合 OpenAI 协议OpenClaw 解析不到choices字段。原因通常是 Base URL 写错了。比如把https://taotoken.net/api写成了https://taotoken.net/api/v1导致请求路径变成/v1/v1/chat/completions服务返回 404 或错误页自然没有 choices。正确写法是 Base URL 只到/apiOpenClaw 内部会拼/v1/chat/completions。修复openclaw config set agents.defaults.baseUrl https://taotoken.net/api然后重启网关再试。5.4 OAuth 相关报错如果你在配置里启用了需要 OAuth 的模型服务但没完成授权流程会报OAuth token expired或invalid_grant。OpenClaw 本身不强制 OAuth如果你用的是 API Key 方式检查配置里有没有残留的oauth字段删掉即可。如果确实需要 OAuth按服务商文档重新走一遍授权把拿到的 token 写入配置。但大多数场景下API Key 方式更简单建议优先用 Key。5.5 其他高频问题速查Invalid usernameUbuntu 初始化时用户名不合规用小写字母重来。command not found: openclawPATH 没配执行source ~/.bashrc或手动加.npm-global/bin。gateway.token is ignored用了旧配置项改成gateway.auth.token。Port 18789 is already in use服务已在跑先openclaw gateway stop。Systemd service failedWSL 不支持 systemd配置向导里跳过即可不影响网关运行。6. 把 OpenClaw 接上模型服务Token 获取与长期使用建议环境跑通之后真正决定体验的是模型服务是否稳定、Token 是否够用。OpenClaw 本身不绑定任何模型厂商它只认 OpenAI 兼容协议所以你可以自由选择后端。如果你还没有可用的 API Key可以去 TaoToken 控制台创建一个。地址是 https://taotoken.net/api-keys 创建后复制 Key填到openclaw.json的apiKey字段。Base URL 固定用https://taotoken.net/apiModel ID 按你需要的模型填比如claude-sonnet-4-20250514或gpt-4o。三件套配好重启网关就能用。想先验证模型对话效果可以打开 https://taotoken.net/model-chat 直接试一句确认 Key 有效再写进配置省得来回排查。如果你打算长期跑编码类 Agent 任务比如让 OpenClaw 帮你改代码、跑测试建议看一下 Coding Plan地址是 https://taotoken.net/coding-plan 按用量规划比单次调用更划算。接入文档在 https://taotoken.net/doc 里面有完整的协议说明和示例。日常使用中建议把openclaw gateway run放到后台跑或者用nohup挂起避免关终端就断服务。WSL2 的 Ubuntu 终端关掉后进程会终止可以用tmux或screen保持会话。另外定期备份~/.openclaw/openclaw.json里面存了 Token 和模型配置重装时直接恢复能省很多事。最后提醒一句Token 和 API Key 都是敏感信息不要提交到 Git 仓库也不要在截图里暴露。配置文件权限设成600chmod 600 ~/.openclaw/openclaw.json这样只有当前用户能读多一层保护。