1. 为什么第一次装 openclaw 总卡在环境这一步openclaw 是一个跑在本地的 AI Agent 网关它把模型调用、频道接入飞书、Telegram 等、技能插件统一收在一份配置文件里管理。你可以在 Windows 上把它当成一个常驻后台的小服务前台用 PowerShell 敲命令后台由 gateway 负责转发请求。适合谁适合想在自己电脑上跑一个可控 Agent、又不想把 Key 散落在各个脚本里的开发者。但它的安装链路比普通 npm 包长Node.js 提供运行时Git 负责拉取依赖PowerShell 负责执行安装脚本最后 gateway 才是真正干活的进程。这四环里任何一环出问题你看到的报错都不一样而新手最容易把它们混在一起以为是openclaw 装不上。我这次在 Windows 11 上从零装了一遍踩的坑集中在三处装完 Node.js 没重开终端导致命令找不到、PowerShell 默认禁止脚本执行、以及非管理员权限下 gateway 计划任务注册失败。下面按真实顺序复盘每一步都给可复制的命令和预期输出你照着走能少绕两小时。先明确一个概念openclaw gateway 是常驻进程gateway run是前台跑关终端就停调试用它gateway start是注册成后台服务关终端还在。很多人第一次用start失败就是因为权限或环境变量没配对。理解这点后面的排错会顺很多。环境准备阶段的核心检索词就是 Node.js、Git、PowerShell 三件套缺一个安装脚本都会中途报错。下面从检查开始。2. 环境检查与 Node.js、Git 安装的完整命令2.1 先查三件套版本别急着装打开 PowerShell普通权限即可逐条执行node -v npm -v git --version预期输出类似v22.14.0、10.9.2、git version 2.47.1.windows.1。如果node报无法将项识别为 cmdlet说明没装或没进 PATHgit报错不影响主流程但安装脚本自动下载 Git 会很慢建议手动装。Node.js 去官网下载 Windows Installer.msi一路下一步即可。装完必须关掉所有已打开的 PowerShell 和 CMD 窗口再重开否则系统读不到新的 PATH你会一直看到node找不到——这是最高频的假故障。Git 用 winget 装最省事winget install --id Git.Git -e --source winget装完同样重开终端验证git --version。2.2 放开 PowerShell 脚本执行权限Windows 默认策略是 Restricted安装脚本install.ps1会被直接拦下报因为在此系统上禁止运行脚本。执行Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser提示确认时输入Y。RemoteSigned的含义是本地脚本可跑从网络下载的脚本需签名。这是官方推荐的最小放开不要图省事设成Unrestricted。2.3 用管理员身份跑安装脚本这一步是关键。以管理员身份打开 PowerShell否则后面 gateway 注册计划任务会失败。然后执行powershell -c irm https://openclaw.ai/install.ps1 | iex安装过程 3 到 10 分钟不等取决于网络。如果长时间没动静按回车刷新进度直到出现Clawdbot installed successfully。安装向导里会连续问你几个配置项第一次装建议这样选配置项选择I understand this is powerful and inherently risky. Continue?YesOnboarding modeQuickStartModel/auth providerSkip for nowFilter models by providerAll providersDefault model默认Select channel (QuickStart)Skip for nowConfigure skills now?NoEnable hooks?空格选中 Skip for now 后回车How do you want to hatch your bot?Hatch in TUI模型和频道都先跳过等 gateway 跑起来再配避免一次填太多出错难定位。3. 把 endpoint 改到 TaoToken 统一 Key 通道的配置写法openclaw 的模型配置集中在配置文件的models.providers段。默认它连的是各家官方地址你要做的是把baseUrl换成 TaoToken 的统一入口apiKey换成你在 TaoToken 申请的 Keyapi字段保持openai-completions协议不变。TaoToken 的 API 地址是https://taotoken.net/apiKey 在控制台创建https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentconsole配置文件位置在用户目录下的.openclaw文件夹。Windows 下路径类似C:\Users\你的用户名\.openclaw\config.json。这里有个大坑Windows 默认不显示文件扩展名你可能改的是config.json.txt却以为改的是config.json怎么改都不生效。先在资源管理器查看里勾上文件扩展名。可复制的配置片段如下把你的TaoTokenKey替换成真实 Key{ models: { mode: merge, providers: { taotoken: { baseUrl: https://taotoken.net/api, apiKey: 你的TaoTokenKey, api: openai-completions, models: [ { id: claude-sonnet-4-5, name: Claude Sonnet 4.5, reasoning: true, input: [text, image], contextWindow: 200000, maxTokens: 8192 } ] } } }, agents: { defaults: { model: { primary: taotoken/claude-sonnet-4-5 }, models: { taotoken/claude-sonnet-4-5: {} } } } }三件套对照记牢Base URL填https://taotoken.net/apiKey填 TaoToken 控制台生成的Model ID填taotoken/claude-sonnet-4-5provider 名斜杠模型 id。三者任一写错请求都会失败。如果你更习惯用环境变量管理 Key可以在配置里写${TAOTOKEN_API_KEY}然后在启动 gateway 前设置$env:TAOTOKEN_API_KEY 你的TaoTokenKey注意用gateway start后台启动时终端里设的环境变量不会带进后台进程这也是很多人配了 Key 却不生效的原因。要么写死在配置文件要么用gateway run前台跑。4. 启动 gateway 并验证模型请求成功4.1 前台启动看日志调试阶段强烈建议用前台模式报错直接打在屏幕上openclaw gateway run看到监听18789端口、无红色报错说明网关起来了。另开一个 PowerShell 窗口查状态openclaw gateway status openclaw status4.2 发一条真实请求验证用openclaw models list确认taotoken/claude-sonnet-4-5在列表里然后触发一次对话。最直接的方式是进 TUI 或通过频道发消息。如果只想快速验证通道可以在 TUI 里发一句你好报一下你的模型名。成功时你会看到流式返回的文本且openclaw logs --follow里出现200状态码、token 计数正常。失败时日志会给出具体原因下一节对照排查。4.3 后台常驻与日常运维命令验证通过后切后台openclaw gateway start常用命令备一份openclaw gateway stop # 停止 openclaw gateway restart # 重启 openclaw gateway status # 状态 openclaw update # 更新 openclaw doctor # 体检 openclaw logs --follow # 跟踪日志 openclaw onboard # 重跑配置向导 openclaw models status # 模型状态 openclaw channels add # 添加频道 openclaw skills list # 技能列表 openclaw security audit # 安全扫描openclaw dashboard我不建议日常用它只是把带 token 的网页打开并没有真正启动服务容易误判。5. 真实报错对照401、local proxy failed、reading choices报错一401 Unauthorized。日志里出现401加invalid api key八成是 Key 写错或复制时带了空格。回 TaoToken 控制台重新生成一个粘贴时注意别把换行带进去。也可能是baseUrl写成了https://taotoken.net/api/多一个斜杠或漏了/api。报错二local proxy failed / connection refused。这类是网络层问题常见于gateway start后台模式下环境变量没生效。解决思路改用gateway run前台跑确认能通后再排查后台。另外检查gateway.bind是否为loopback端口18789有没有被占用netstat -ano | findstr 18789报错三reading choices of undefined。这是响应体结构和预期不符通常因为api字段填错。openclaw 走 OpenAI 兼容协议时必须写openai-completions写成别的会导致解析失败。同时确认模型id和agents.defaults.model.primary里的 provider 前缀一致。报错四OAuth 相关。如果你在向导里选了 OAuth 类 provider 又中途跳过配置里会残留半截认证信息。执行openclaw onboard重跑向导或手动清掉auth.profiles里对应条目。报错五gateway.cmd 启动不了 / 找不到计划任务。根因是非管理员权限安装。用管理员 PowerShell 重跑安装脚本或手动注册服务。排错时统一先看日志openclaw logs --follow日志里的状态码和错误字段是最准的线索比猜快得多。6. 后续接入与统一 Key 通道的长期用法gateway 跑通后模型调用就统一走 TaoToken 这一条通道了。你新增频道比如飞书或技能时不用再为每个 provider 单独配 Key改一处models.providers即可。飞书频道配置示例{ channels: { feishu: { enabled: true, appId: 你的飞书appId, appSecret: 你的飞书appSecret, requireMention: true, groupPolicy: open } } }如果你打算长期跑 Agent、频繁调试模型用 Coding Plan 会比按量更省心https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding-plan想先在网页里试模型效果、确认通道没问题用模型对话页最快https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentchatKey 管理和新建入口在控制台https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentapi-keys配置字段和协议细节查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc最后提醒一句改完配置文件记得openclaw gateway restart否则跑的还是旧配置。Windows 下改文件前先确认扩展名可见这个坑我踩过一次改了半小时没生效最后发现改的是.txt。