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, @{n='FreeGB';e={[math]::Round($_.Free/1GB,2)}} # 创建纯英文安装目录 New-Item -ItemType Directory -Path "D:\OpenClaw" -Force

然后检查依赖。OpenClaw 运行需要 Git、Node.js（建议 18 LTS 及以上）、Python（3.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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，注册后在控制台创建 API Key。控制台地址是 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，Key 管理页在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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 "*.log"

TaoToken 的 Coding Plan 适合长期跑 Agent 的场景，因为 Agent 多步任务消耗 token 比单轮对话大得多，包月或套餐形式更划算，具体在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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_KEY=sk-你的Key TAOTOKEN_BASE_URL=https://taotoken.net/api/v1 OPENCLAW_GATEWAY_PORT=18789 OPENCLAW_LOG_LEVEL=info

注意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(r'D:\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 Get

TcpTestSucceeded为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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_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的modelId，Base URL 和 Key 不动，这就是统一通道的好处。比如从claude-3-5-sonnet-20241022换成gpt-4o，改一个字段重启 Gateway 即可。可用模型 ID 在模型对话页查：https://taotoken.net/models?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

如果你打算长期跑 Agent 任务，比如让 OpenClaw 定时整理文件、批量处理文档，token 消耗会比单轮对话大不少。这种情况看 Coding Plan 更合适：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。按量计费适合先试水，跑通流程后再决定要不要转套餐。

Key 管理在控制台：https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，可以创建多个 Key 给不同项目用，方便追踪消耗。API Key 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。

接入细节和字段说明看文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= 。文档里有完整的接口列表和参数说明，遇到配置字段不确定时优先查这里，比在群里问快。

最后给几个实用建议。第一，把.env和settings.json纳入版本管理时，.env一定要排除，Key 泄露比配置丢失麻烦得多。第二，OpenClaw 的 workspace 目录定期清理，Agent 跑任务会生成不少中间文件。第三，升级 OpenClaw 前先备份配置，新版本字段可能有变化，对照文档迁移。第四，如果同时用 Claude Code 或其他编码工具，它们的配置目录是分开的，别把 Key 混着放，各自用各自的.env。

跑通这一套之后，你在 Windows 上就有了一个能调多模型的本地 Agent 环境。后面想加技能、接聊天渠道、做自动化流程，都是在这个基础上扩展。先把环境这关过了，剩下的就是调指令和试任务。