1. Windows 上跑 OpenClaw 到底卡在哪环境检查与依赖安装的完整思路OpenClaw 是一个能在本地操控电脑、读写文件、模拟键鼠的自动化智能体框架适合想在 Windows 上做本地 AI Agent 实验的开发者。它本身不绑定某一家模型而是通过统一的 API 通道去调用大模型所以安装过程分两段先把本地运行环境搭起来再把模型接入通道配好。很多人第一次装的时候以为双击一个 exe 就完事结果卡在 Gateway 离线、依赖缺失、路径带中文这些坑上来回折腾一下午。我先把结论放前面OpenClaw 在 Windows 上跑不起来九成问题出在三个地方——运行路径含中文或空格、Python/Node.js/Git 依赖版本不对、模型接入的 Base URL 和 Key 没配对。这篇就按「环境准备 → 依赖安装 → 配置验证 → 接入 TaoToken → 排障」的顺序走一遍命令都可以直接复制到 PowerShell 里执行。先说清楚它适合谁如果你是想在 Windows 本地跑一个能操作文件系统、能调浏览器、能执行多步任务的 Agent并且希望模型调用走一个统一入口而不是每个模型单独配一遍那 OpenClaw 这套结构是合适的。它不适合只想聊天问答的场景那种直接开网页对话就行没必要上本地框架。环境检查这一步别跳过。打开 PowerShell建议用管理员身份后面装依赖会用到先确认系统版本和架构# 查看系统版本与架构 [System.Environment]::OSVersion.Version $env:PROCESSOR_ARCHITECTURE # 确认是 64 位 Windows 10/11 Get-ComputerInfo | Select-Object WindowsProductName, OsArchitecture, OsHardwareAbstractionLayer输出里OsArchitecture应该是64-bit。如果是 32 位系统后面的 Node.js 和 Python 安装包都要换但 OpenClaw 当前主流程基本按 64 位走32 位建议直接换机器或装虚拟机。接着检查磁盘空间和安装路径。OpenClaw 本体不大但模型缓存、技能扩展、日志会持续占空间建议目标盘预留 5GB 以上。路径必须是纯英文不能有中文、空格、、这类字符。推荐D:\OpenClaw或E:\AI\OpenClaw别用D:\软件\OpenClaw这种。# 查看各盘可用空间 Get-PSDrive -PSProvider FileSystem | Select-Object Name, {nFreeGB;e{[math]::Round($_.Free/1GB,2)}} # 创建纯英文安装目录 New-Item -ItemType Directory -Path D:\OpenClaw -Force然后检查依赖。OpenClaw 运行需要 Git、Node.js建议 18 LTS 及以上、Python3.10 及以上。先看系统里有没有git --version node --version npm --version python --version如果某条命令报「无法将...识别为 cmdlet」说明没装或没进 PATH。这里有个常见坑Windows 自带一个python的别名会跳到 Microsoft Store执行python --version可能弹出商店页面而不是版本号。遇到这种情况去「设置 → 应用 → 高级应用设置 → 应用执行别名」里把python.exe和python3.exe两个别名关掉再重新装官方 Python。依赖安装我建议用 winget比手动下安装包省事# 用 winget 安装依赖管理员 PowerShell winget install --id Git.Git -e --source winget winget install --id OpenJS.NodeJS.LTS -e --source winget winget install --id Python.Python.3.11 -e --source winget装完关掉当前 PowerShell 再重开让 PATH 生效然后重新验证四个版本命令。Node.js 装完记得确认 npm 也能用因为 OpenClaw 的部分工具链走 npm 拉取。到这一步环境准备就算完成了。别急着启动先把依赖版本记下来后面排障时对照用。我实测下来Node.js 低于 18 会出现依赖解析失败Python 低于 3.10 会在某些技能模块导入时报语法错误这两个版本线是硬要求。2. TaoToken 前置准备统一 Key 与 API 通道怎么配OpenClaw 本身不带模型它需要一个能调用的模型服务。TaoToken 在这里的角色是统一入口你拿一个 Key配一个 Base URL就能在 OpenClaw 里切换不同模型不用每个模型单独申请、单独配地址。对本地 Agent 来说这点很关键因为 Agent 跑多步任务时会频繁调模型入口统一了换模型只改一个 Model ID 就行。先注册并拿到 Key。打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。创建时给它起个能认出来的名字比如openclaw-local方便后面在多个项目里区分。Key 拿到后先别急着往 OpenClaw 里塞先在本地验证一下这个 Key 能不能通。这一步能省掉后面大量「到底是 Key 错还是 OpenClaw 配错」的扯皮。用 PowerShell 发一个最小请求# 把 $env:TAOTOKEN_KEY 换成你自己的 Key $env:TAOTOKEN_KEY sk-你的Key $headers { Authorization Bearer $env:TAOTOKEN_KEY Content-Type application/json } $body { model claude-3-5-sonnet-20241022 messages ({ role user; content 只回复两个字通了 }) max_tokens 16 } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri https://taotoken.net/api/v1/chat/completions -Method Post -Headers $headers -Body $body如果返回里choices[0].message.content有内容说明 Key 和通道都正常。如果报 401先检查 Key 有没有复制全、有没有多余空格如果报模型不存在换一个 Model ID 再试。模型列表和可用 ID 可以在模型对话页确认https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。这里要强调 Base URL 的写法。TaoToken 的 API 根地址是https://taotoken.net/api注意这个地址不带 UTM 参数配置里就写这个。OpenClaw 里通常要求填到/v1这一层也就是https://taotoken.net/api/v1具体看它配置项怎么定义。填错层级是高频错误表现为 404 或「local proxy failed」。关于 Key 的存放别硬编码在代码里。OpenClaw 支持.env文件把 Key 写进去然后确保.env不被提交到 Git。如果你用 Git 管理配置目录先把.env加进.gitignore# 在 OpenClaw 配置目录下 Add-Content -Path .gitignore -Value .env Add-Content -Path .gitignore -Value *.logTaoToken 的 Coding Plan 适合长期跑 Agent 的场景因为 Agent 多步任务消耗 token 比单轮对话大得多包月或套餐形式更划算具体在 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 看。如果你只是先跑通环境用按量计费就够。还有一点OpenClaw 第一次启动会做依赖初始化和 Gateway 就绪检查这个过程需要网络。确保网络通畅别在这时候挂系统级代理否则 Gateway 可能连不上本地端口。TaoToken 的调用是标准的 HTTPS 请求不需要额外网络配置。3. 可复制配置OpenClaw 的 settings 与 .env 片段这一节给可直接复制的配置。OpenClaw 的配置分两块一块是.env放 Key 和 Base URL 这类敏感信息一块是settings.json或等价的 TOML放模型、Gateway 端口、工具开关这些。不同版本文件名可能略有差异以你解压后目录里的实际文件为准但字段结构基本一致。先建.env。在 OpenClaw 安装目录下创建或编辑.env# OpenClaw 环境变量 TAOTOKEN_API_KEYsk-你的Key TAOTOKEN_BASE_URLhttps://taotoken.net/api/v1 OPENCLAW_GATEWAY_PORT18789 OPENCLAW_LOG_LEVELinfo注意TAOTOKEN_BASE_URL写到/v1这是 OpenAI 兼容接口的惯例层级。如果你的 OpenClaw 版本要求根地址就改成https://taotoken.net/api但大多数情况填到/v1。然后是settings.json。这个文件控制模型选择和 Agent 行为{ gateway: { host: 127.0.0.1, port: 18789, autoStart: true }, model: { provider: openai-compatible, baseUrl: https://taotoken.net/api/v1, apiKeyEnv: TAOTOKEN_API_KEY, modelId: claude-3-5-sonnet-20241022, maxTokens: 4096, temperature: 0.3 }, tools: { fileSystem: true, browser: true, keyboardMouse: true }, workspace: D:\\OpenClaw\\workspace }几个字段说明一下。provider填openai-compatible因为 TaoToken 走的是 OpenAI 兼容协议。apiKeyEnv指向.env里的变量名这样 Key 不落盘到 JSON。modelId换成你想用的模型比如gpt-4o、claude-3-5-sonnet-20241022等具体可用 ID 在模型对话页查。workspace是 Agent 操作文件的根目录必须是纯英文路径且和安装目录分开避免 Agent 误操作程序文件。如果你更习惯 TOML 格式等价写法是这样[gateway] host 127.0.0.1 port 18789 auto_start true [model] provider openai-compatible base_url https://taotoken.net/api/v1 api_key_env TAOTOKEN_API_KEY model_id claude-3-5-sonnet-20241022 max_tokens 4096 temperature 0.3 [tools] file_system true browser true keyboard_mouse true配置写完先做一次语法校验。JSON 可以用 PowerShell 自带的解析器验Get-Content D:\OpenClaw\settings.json -Raw | ConvertFrom-Json | Out-Null if ($?) { Write-Host JSON 语法 OK }TOML 的话用 Python 验python -c import tomllib; tomllib.load(open(rD:\OpenClaw\settings.toml,rb)); print(TOML 语法 OK)配置里最容易错的是路径转义。JSON 里 Windows 路径的反斜杠要写成\\比如D:\\OpenClaw\\workspace。写成单反斜杠D:\OpenClaw会导致解析失败或路径被当成转义字符。这是新手高频坑我见过好几次因为这一个字符 Gateway 起不来。还有port别和系统里已占用的端口冲突。18789 是 OpenClaw 常用默认值如果被占换一个比如 18790。检查端口占用Get-NetTCPConnection -LocalPort 18789 -ErrorAction SilentlyContinue有输出说明被占换端口。配置改完保存下一步启动验证。4. 启动与验证从 Gateway 就绪到第一次成功请求配置就绪后启动 OpenClaw。如果你用的是一键启动包双击启动程序如果是命令行方式在安装目录执行cd D:\OpenClaw # 根据实际入口文件调整常见为 main.py 或 npm start python main.py # 或 npm start启动后终端会打印日志重点看这几行依赖检查通过、Gateway 监听在127.0.0.1:18789、模型 provider 初始化成功。第一次启动因为要初始化服务等 1 到 3 分钟是正常的别以为卡死了就关窗口。验证 Gateway 是否在线另开一个 PowerShell 窗口# 检查 Gateway 端口是否在监听 Test-NetConnection -ComputerName 127.0.0.1 -Port 18789 # 直接请求健康检查接口 Invoke-RestMethod -Uri http://127.0.0.1:18789/health -Method GetTcpTestSucceeded为True健康接口返回status: ok之类说明 Gateway 起来了。如果端口不通回看上一节的端口占用和配置路径。接着验证模型接入。OpenClaw 一般有个测试命令或界面按钮命令行方式可以发一个最小任务# 通过 OpenClaw 的 CLI 发一条测试指令具体子命令以 --help 为准 python main.py --task 在 workspace 下创建 test.txt内容写 hello openclaw如果 Agent 正常执行并在D:\OpenClaw\workspace下生成了test.txt说明整条链路通了OpenClaw 解析任务 → 调 TaoToken 的模型 → 模型返回工具调用 → OpenClaw 执行文件操作。这是最有说服力的验证比单纯看 Gateway 在线更实在。也可以直接测模型通道绕过 Agent 逻辑$headers { Authorization Bearer $env:TAOTOKEN_API_KEY Content-Type application/json } $body { model claude-3-5-sonnet-20241022 messages ({ role user; content 返回 JSON{ok:true} }) } | ConvertTo-Json -Depth 5 Invoke-RestMethod -Uri https://taotoken.net/api/v1/chat/completions -Method Post -Headers $headers -Body $body返回正常说明 Key、Base URL、模型 ID 三者都对。这一步和 OpenClaw 无关纯粹验证 TaoToken 通道排障时能快速定位问题在哪一层。成功跑通后你可以在 OpenClaw 界面里看到对话窗口、Gateway 状态、可用 token 额度这些信息。试着发一条自然语言指令比如「列出 D 盘根目录下的文件夹按名称排序」看它能不能正确调用文件系统工具。指令越具体执行越准这是 Agent 类工具的通用规律。验证阶段还要留意日志。OpenClaw 的日志一般在安装目录的logs文件夹或者终端直接输出。日志里如果出现reading choices相关报错通常是模型返回结构不符合预期多半是 Base URL 层级或模型 ID 写错。如果出现local proxy failed检查是不是系统代理干扰了本地回环地址把127.0.0.1和localhost加进代理例外。跑通之后建议把这次成功的配置备份一份包括.env、settings.json和依赖版本号。后面升级或换机器时直接对照能省很多时间。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节按真实报错来。我把 OpenClaw 接入过程中最常见的几类错误和对应处理列出来每条都给出定位方法和修复动作。401 Unauthorized。这是 Key 问题。先确认.env里TAOTOKEN_API_KEY没有多余空格和换行PowerShell 里读出来看看长度(Get-Content D:\OpenClaw\.env | Select-String TAOTOKEN_API_KEY).Line.Length正常 Key 长度在几十个字符。如果长度明显不对说明复制时截断了。另外确认请求头是Bearer加 Key中间一个空格别写成Bearer:。如果 Key 本身没问题去控制台看这个 Key 有没有被禁用或额度耗尽。local proxy failed。这个报错通常和网络代理有关。OpenClaw 的 Gateway 走本地回环如果系统级代理把127.0.0.1也代理了就会失败。检查代理设置netsh winhttp show proxy Get-ItemProperty -Path HKCU:\Software\Microsoft\Windows\CurrentVersion\Internet Settings | Select-Object ProxyEnable, ProxyServer如果ProxyEnable是 1把127.0.0.1;localhost加进例外列表或者临时关掉系统代理再启动 OpenClaw。注意这里说的是系统代理配置不是让你去用什么网络工具纯粹是本地回环地址别被代理拦截。reading choices 报错。完整报错一般是cannot read property choices of undefined或类似。这说明模型返回的 JSON 里没有choices字段OpenClaw 解析失败。原因通常是 Base URL 写错层级比如写成了https://taotoken.net/api而实际要/v1或者模型 ID 不存在导致返回错误结构。先用第 4 节的直接请求验证通道确认返回里有choices再回来看 OpenClaw 配置。OAuth 相关报错。如果你在配置里看到 OAuth 字样说明某个 provider 走了 OAuth 流程而不是 API Key。OpenClaw 接 TaoToken 用的是 API Key 模式不需要 OAuth。检查settings.json里provider是不是误设成了需要 OAuth 的类型改成openai-compatible。如果用的是 Claude Code 这类工具它的 OAuth 和 API Key 是两套流程别混用接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。Gateway 一直离线。按顺序查安装路径是否纯英文、端口是否被占、.env是否被正确加载、杀毒软件是否拦截了进程。Windows Defender 的实时防护有时会拦 OpenClaw 的文件操作可以在「Windows 安全中心 → 病毒和威胁防护 → 排除项」里把安装目录加进去而不是整个关掉防护。依赖版本冲突。如果启动时报ModuleNotFoundError或Cannot find module说明依赖没装全或版本不对。重新跑一遍依赖安装并确认 Node.js 和 Python 版本node --version # 应 18 python --version # 应 3.10 pip list | Select-String openai|requests|httpx缺包就补pip install -r requirements.txt npm install排障的核心思路是分层定位先确认 TaoToken 通道本身通不通直接请求 API再确认 Gateway 起没起健康检查最后确认 OpenClaw 配置对不对settings 和 .env。三层里哪层报错就修哪层别一上来就重装。6. 接入后的下一步模型切换、Coding Plan 与文档入口环境跑通、模型接入验证成功后日常使用就是切模型和跑任务。OpenClaw 里换模型只改settings.json的modelIdBase URL 和 Key 不动这就是统一通道的好处。比如从claude-3-5-sonnet-20241022换成gpt-4o改一个字段重启 Gateway 即可。可用模型 ID 在模型对话页查https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。如果你打算长期跑 Agent 任务比如让 OpenClaw 定时整理文件、批量处理文档token 消耗会比单轮对话大不少。这种情况看 Coding Plan 更合适https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。按量计费适合先试水跑通流程后再决定要不要转套餐。Key 管理在控制台https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 可以创建多个 Key 给不同项目用方便追踪消耗。API Key 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。接入细节和字段说明看文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 。文档里有完整的接口列表和参数说明遇到配置字段不确定时优先查这里比在群里问快。最后给几个实用建议。第一把.env和settings.json纳入版本管理时.env一定要排除Key 泄露比配置丢失麻烦得多。第二OpenClaw 的 workspace 目录定期清理Agent 跑任务会生成不少中间文件。第三升级 OpenClaw 前先备份配置新版本字段可能有变化对照文档迁移。第四如果同时用 Claude Code 或其他编码工具它们的配置目录是分开的别把 Key 混着放各自用各自的.env。跑通这一套之后你在 Windows 上就有了一个能调多模型的本地 Agent 环境。后面想加技能、接聊天渠道、做自动化流程都是在这个基础上扩展。先把环境这关过了剩下的就是调指令和试任务。