1. 为什么 Windows 上跑 OpenClaw 总在第一步卡住OpenClaw 是一个开源桌面自动化智能体能在 Windows 10/11 上模拟键鼠、控制浏览器、批量处理本地文件把重复性办公操作交给模型去规划执行。它适合不想写脚本的办公人群也适合想快速验证 Agent 落地效果的开发者。但我在几台不同配置的 Windows 机器上装下来发现失败点高度集中不是软件本身难装而是环境准备、解压方式、安装路径、模型接入这四件事里总有一件没做对。最常见的现象是双击启动程序后界面一闪而过或者卡在「正在等待 Gateway 就绪」不动再或者任务能下发但模型一直返回 401。前两个属于本地环境问题最后一个几乎都是 API Key 和 Base URL 没配对。这篇就把从零安装到跑通首个桌面任务、再到接入 TaoToken 统一 Key 的完整链路拆开讲配置片段可以直接复制。先明确一个前提OpenClaw 的模型调用走的是 OpenAI 兼容协议所以任何提供兼容接口的服务都能接。TaoToken 的价值在于把多家模型的 Key 收敛成一个Base URL 固定换模型只改 Model ID不用在多个平台之间来回注册和切换。对桌面自动化这种需要反复试不同模型的任务来说省事很多。下面按「环境准备 → 解压安装 → 配置模型 → 验证请求 → 排错」的顺序走每一步都给出可复制的命令或配置。2. 环境准备与 OpenClaw 安装路径规范2.1 关闭安全软件的实时拦截OpenClaw 运行时要调用系统底层读写权限、模拟键鼠、控制浏览器这些行为在安全软件眼里和恶意程序高度相似。实测下来360、腾讯电脑管家、火绒的实时防护都可能直接隔离核心文件Windows Defender 的「实时保护」也会拦。安装前把这些的实时防护临时关掉装完跑通后再按需加白名单。不是让你永久关闭防护而是安装和首次启动阶段先放行。加白名单的位置一般在安全软件的「信任区」或「排除项」里把整个Openclaw-win文件夹加进去即可。2.2 解压工具的选择Windows 自带的解压功能处理这种带多层目录和可执行文件的压缩包时容易丢文件或权限异常。用 WinRAR 或 7-Zip右键选择「解压到当前文件夹」等 1 到 2 分钟。解压完应该得到一个Openclaw-win文件夹里面有一个红色龙虾图标的启动程序看到它就说明解压完整。2.3 安装路径的硬性规则这是报错最密集的地方。路径必须满足纯英文、无空格、无特殊符号、非 C 盘。合规示例D:\OpenClaw E:\AI\OpenClaw F:\OpenClaw_v29禁止示例D:\工具\OpenClaw 含中文 D:\Open Claw 含空格 D:\OpenClaw2026 含特殊符号 C:\OpenClaw 系统盘长期占用影响流畅度路径里只要出现中文或空格安装阶段大概率弹「路径非法」并中断。改路径后重新点「开始安装」即可不用重新解压。2.4 首次启动的 Gateway 初始化部署完成后程序会自动打开主界面第一次启动时 Gateway 网关要初始化页面显示「正在等待 Gateway 就绪...」。这是正常加载等 1 到 3 分钟。初始化完成后右上角状态栏会显示「Gateway 在线」后续启动就快了。中途别关窗口否则文件残缺得重新解压。3. 用 TaoToken 统一 Key 接入模型可复制配置OpenClaw 的模型配置集中在解压目录下的.env文件里部署程序会自动生成一份。你要做的是把里面的 Base URL、API Key、Model ID 三项改成 TaoToken 的。3.1 获取 Key 和确认 Base URL先去 TaoToken 控制台创建一个 API Key。地址是https://taotoken.net/api-keys登录后在「API Keys」页面点新建复制生成的 Key形如sk-开头的一串。这个 Key 只显示一次存好。Base URL 固定为https://taotoken.net/api注意这里不带任何路径后缀OpenClaw 会自动拼接/v1/chat/completions。如果你手上有别的工具要求填完整路径那是在那个工具的字段里加不是改这里。3.2 编辑 .env 配置文件用记事本或 VS Code 打开Openclaw-win目录下的.env找到模型相关字段改成下面这样# TaoToken 统一接入配置 OPENAI_API_KEYsk-你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_MODELclaude-sonnet-4-20250514 # 网关端口默认即可被占用时改这里 GATEWAY_PORT18789 # 本地数据目录保持默认 DATA_DIR./data三个关键字段说明字段填什么说明OPENAI_API_KEYTaoToken 的 Key控制台复制sk- 开头OPENAI_BASE_URLhttps://taotoken.net/api固定不加 /v1OPENAI_MODEL模型 ID换模型只改这一行Model ID 要填 TaoToken 支持的完整名称。比如想用 Claude 系列就填claude-sonnet-4-20250514想用别的就换成对应 ID。具体可用列表在 TaoToken 的模型对话页面能看到https://taotoken.net/models里选一个复制过来即可。3.3 保存后重启网关改完.env必须重启网关才生效。点主界面右上角的重启按钮或者直接关掉程序重新运行启动程序。重启后右上角状态栏重新显示「Gateway 在线」说明配置已加载。如果你用的是 Claude Code 这类需要单独配置的工具配置逻辑一样都是 Base URL 加 Key 加 Model ID 三件套。TaoToken 的接入文档https://taotoken.net/doc里有各工具的对照写法照着填就行。4. 验证请求跑通第一个桌面自动化任务配置对不对发一条任务就知道。别一上来就让它整理整个 D 盘先用小范围任务验证链路。4.1 最小验证指令在底部输入框粘贴这条在桌面新建一个文件夹叫 OpenClaw测试然后在里面创建一个 txt 文件写入当前时间按 Enter 发送。如果模型接入正常你会看到中间对话窗口逐步输出执行步骤创建文件夹、创建文件、写入内容。整个过程是模型规划加本地执行你能看到每一步的反馈。4.2 用 curl 单独验证 API 通道如果任务没反应先排除是不是模型通道的问题。打开 PowerShell用这条命令直接打 TaoToken 的接口curl https://taotoken.net/api/v1/chat/completions ^ -H Content-Type: application/json ^ -H Authorization: Bearer sk-你的TaoToken密钥 ^ -d {\model\:\claude-sonnet-4-20250514\,\messages\:[{\role\:\user\,\content\:\回复ok\}]}返回里如果有choices字段和内容说明 Key 和 Base URL 都没问题问题在 OpenClaw 本地。如果返回 401就是 Key 错了或没生效返回 404多半是 Base URL 多写了/v1。4.3 成功后的状态确认任务跑通后主界面右上角会显示剩余 Tokens 额度左侧导航栏能看到这次对话的历史记录。这时候可以试更复杂的指令比如整理 D 盘下载文件夹按图片、文档、压缩包、安装包分类归档删除空目录指令描述越具体执行精准度越高。模糊的「帮我整理文件」容易让模型反复确认反而慢。5. 常见报错逐条排查5.1 401 Unauthorized报错长这样Error: 401 Unauthorized - invalid api key原因就三个Key 复制时带了空格、Key 已失效、.env里字段名写错。检查OPENAI_API_KEY后面有没有多余空格Key 是不是从控制台完整复制的。改完重启网关。如果还报 401去 TaoToken 控制台确认这个 Key 还在有效期内。5.2 local proxy failed / connection refusedError: local proxy failed: dial tcp 127.0.0.1:18789: connect: connection refused这是网关没起来或端口被占用。先看主界面右上角是不是「Gateway 离线」。如果是点重启按钮。如果重启后还是离线检查GATEWAY_PORT设的端口有没有被别的程序占用。用这条命令查netstat -ano | findstr 18789有输出说明被占用把.env里的GATEWAY_PORT改成 18790 或其他空闲端口重启即可。5.3 reading choices 报错Error: reading choices: unexpected end of JSON input这个通常是模型返回了空响应或非 JSON 内容。两种可能Model ID 填错了TaoToken 那边找不到这个模型或者请求被中途截断。先确认 Model ID 拼写和 TaoToken 模型列表里的一致再确认网络稳定。改完 Model ID 重启网关重试。5.4 OAuth 相关报错Error: oauth token exchange failed如果你在 OpenClaw 里配了需要 OAuth 的渠道但没走完授权流程会报这个。桌面自动化场景一般用 API Key 就够了不需要 OAuth。检查.env里是不是混入了 OAuth 相关字段删掉或注释掉只保留 API Key 方式。5.5 路径非法导致安装中断安装失败路径包含非法字符回到 2.3 节的规则把安装路径改成纯英文无空格。改完不用重新解压直接重新点「开始安装」。5.6 安全软件隔离核心文件现象是启动程序双击没反应或者启动后立刻退出。去安全软件的隔离区看有没有Openclaw-win里的文件被拦。有的话恢复并加白名单然后重新解压一次压缩包覆盖再启动。6. 长期使用与模型切换建议跑通之后日常用起来最影响体验的是模型选择。桌面自动化任务对模型的规划能力要求不低简单任务用轻量模型就够复杂多步任务换强一点的模型。因为走的是 TaoToken 统一 Key切换成本就是改.env里OPENAI_MODEL那一行重启网关其他都不用动。如果你打算长期跑自动化任务、或者要接多个 Agent 场景可以看下 TaoToken 的 Coding Planhttps://taotoken.net/coding-plan按用量规划比单次调用更划算。只是想先验证模型效果的直接去模型对话页面https://taotoken.net/chat试几条指令确认模型能力再落到 OpenClaw 里。最后提醒一句OpenClaw 的自动化能力很强但别一上来就让它操作生产环境的数据库或重要文件。先在测试目录里跑通流程确认指令理解准确了再逐步放开权限。我踩过的坑基本都在这篇里了按步骤走能省不少时间。
1. 为什么 Windows 上跑 OpenClaw 总在第一步卡住OpenClaw 是一个开源桌面自动化智能体能在 Windows 10/11 上模拟键鼠、控制浏览器、批量处理本地文件把重复性办公操作交给模型去规划执行。它适合不想写脚本的办公人群也适合想快速验证 Agent 落地效果的开发者。但我在几台不同配置的 Windows 机器上装下来发现失败点高度集中不是软件本身难装而是环境准备、解压方式、安装路径、模型接入这四件事里总有一件没做对。最常见的现象是双击启动程序后界面一闪而过或者卡在「正在等待 Gateway 就绪」不动再或者任务能下发但模型一直返回 401。前两个属于本地环境问题最后一个几乎都是 API Key 和 Base URL 没配对。这篇就把从零安装到跑通首个桌面任务、再到接入 TaoToken 统一 Key 的完整链路拆开讲配置片段可以直接复制。先明确一个前提OpenClaw 的模型调用走的是 OpenAI 兼容协议所以任何提供兼容接口的服务都能接。TaoToken 的价值在于把多家模型的 Key 收敛成一个Base URL 固定换模型只改 Model ID不用在多个平台之间来回注册和切换。对桌面自动化这种需要反复试不同模型的任务来说省事很多。下面按「环境准备 → 解压安装 → 配置模型 → 验证请求 → 排错」的顺序走每一步都给出可复制的命令或配置。2. 环境准备与 OpenClaw 安装路径规范2.1 关闭安全软件的实时拦截OpenClaw 运行时要调用系统底层读写权限、模拟键鼠、控制浏览器这些行为在安全软件眼里和恶意程序高度相似。实测下来360、腾讯电脑管家、火绒的实时防护都可能直接隔离核心文件Windows Defender 的「实时保护」也会拦。安装前把这些的实时防护临时关掉装完跑通后再按需加白名单。不是让你永久关闭防护而是安装和首次启动阶段先放行。加白名单的位置一般在安全软件的「信任区」或「排除项」里把整个Openclaw-win文件夹加进去即可。2.2 解压工具的选择Windows 自带的解压功能处理这种带多层目录和可执行文件的压缩包时容易丢文件或权限异常。用 WinRAR 或 7-Zip右键选择「解压到当前文件夹」等 1 到 2 分钟。解压完应该得到一个Openclaw-win文件夹里面有一个红色龙虾图标的启动程序看到它就说明解压完整。2.3 安装路径的硬性规则这是报错最密集的地方。路径必须满足纯英文、无空格、无特殊符号、非 C 盘。合规示例D:\OpenClaw E:\AI\OpenClaw F:\OpenClaw_v29禁止示例D:\工具\OpenClaw 含中文 D:\Open Claw 含空格 D:\OpenClaw2026 含特殊符号 C:\OpenClaw 系统盘长期占用影响流畅度路径里只要出现中文或空格安装阶段大概率弹「路径非法」并中断。改路径后重新点「开始安装」即可不用重新解压。2.4 首次启动的 Gateway 初始化部署完成后程序会自动打开主界面第一次启动时 Gateway 网关要初始化页面显示「正在等待 Gateway 就绪...」。这是正常加载等 1 到 3 分钟。初始化完成后右上角状态栏会显示「Gateway 在线」后续启动就快了。中途别关窗口否则文件残缺得重新解压。3. 用 TaoToken 统一 Key 接入模型可复制配置OpenClaw 的模型配置集中在解压目录下的.env文件里部署程序会自动生成一份。你要做的是把里面的 Base URL、API Key、Model ID 三项改成 TaoToken 的。3.1 获取 Key 和确认 Base URL先去 TaoToken 控制台创建一个 API Key。地址是https://taotoken.net/api-keys登录后在「API Keys」页面点新建复制生成的 Key形如sk-开头的一串。这个 Key 只显示一次存好。Base URL 固定为https://taotoken.net/api注意这里不带任何路径后缀OpenClaw 会自动拼接/v1/chat/completions。如果你手上有别的工具要求填完整路径那是在那个工具的字段里加不是改这里。3.2 编辑 .env 配置文件用记事本或 VS Code 打开Openclaw-win目录下的.env找到模型相关字段改成下面这样# TaoToken 统一接入配置 OPENAI_API_KEYsk-你的TaoToken密钥 OPENAI_BASE_URLhttps://taotoken.net/api OPENAI_MODELclaude-sonnet-4-20250514 # 网关端口默认即可被占用时改这里 GATEWAY_PORT18789 # 本地数据目录保持默认 DATA_DIR./data三个关键字段说明字段填什么说明OPENAI_API_KEYTaoToken 的 Key控制台复制sk- 开头OPENAI_BASE_URLhttps://taotoken.net/api固定不加 /v1OPENAI_MODEL模型 ID换模型只改这一行Model ID 要填 TaoToken 支持的完整名称。比如想用 Claude 系列就填claude-sonnet-4-20250514想用别的就换成对应 ID。具体可用列表在 TaoToken 的模型对话页面能看到https://taotoken.net/models里选一个复制过来即可。3.3 保存后重启网关改完.env必须重启网关才生效。点主界面右上角的重启按钮或者直接关掉程序重新运行启动程序。重启后右上角状态栏重新显示「Gateway 在线」说明配置已加载。如果你用的是 Claude Code 这类需要单独配置的工具配置逻辑一样都是 Base URL 加 Key 加 Model ID 三件套。TaoToken 的接入文档https://taotoken.net/doc里有各工具的对照写法照着填就行。4. 验证请求跑通第一个桌面自动化任务配置对不对发一条任务就知道。别一上来就让它整理整个 D 盘先用小范围任务验证链路。4.1 最小验证指令在底部输入框粘贴这条在桌面新建一个文件夹叫 OpenClaw测试然后在里面创建一个 txt 文件写入当前时间按 Enter 发送。如果模型接入正常你会看到中间对话窗口逐步输出执行步骤创建文件夹、创建文件、写入内容。整个过程是模型规划加本地执行你能看到每一步的反馈。4.2 用 curl 单独验证 API 通道如果任务没反应先排除是不是模型通道的问题。打开 PowerShell用这条命令直接打 TaoToken 的接口curl https://taotoken.net/api/v1/chat/completions ^ -H Content-Type: application/json ^ -H Authorization: Bearer sk-你的TaoToken密钥 ^ -d {\model\:\claude-sonnet-4-20250514\,\messages\:[{\role\:\user\,\content\:\回复ok\}]}返回里如果有choices字段和内容说明 Key 和 Base URL 都没问题问题在 OpenClaw 本地。如果返回 401就是 Key 错了或没生效返回 404多半是 Base URL 多写了/v1。4.3 成功后的状态确认任务跑通后主界面右上角会显示剩余 Tokens 额度左侧导航栏能看到这次对话的历史记录。这时候可以试更复杂的指令比如整理 D 盘下载文件夹按图片、文档、压缩包、安装包分类归档删除空目录指令描述越具体执行精准度越高。模糊的「帮我整理文件」容易让模型反复确认反而慢。5. 常见报错逐条排查5.1 401 Unauthorized报错长这样Error: 401 Unauthorized - invalid api key原因就三个Key 复制时带了空格、Key 已失效、.env里字段名写错。检查OPENAI_API_KEY后面有没有多余空格Key 是不是从控制台完整复制的。改完重启网关。如果还报 401去 TaoToken 控制台确认这个 Key 还在有效期内。5.2 local proxy failed / connection refusedError: local proxy failed: dial tcp 127.0.0.1:18789: connect: connection refused这是网关没起来或端口被占用。先看主界面右上角是不是「Gateway 离线」。如果是点重启按钮。如果重启后还是离线检查GATEWAY_PORT设的端口有没有被别的程序占用。用这条命令查netstat -ano | findstr 18789有输出说明被占用把.env里的GATEWAY_PORT改成 18790 或其他空闲端口重启即可。5.3 reading choices 报错Error: reading choices: unexpected end of JSON input这个通常是模型返回了空响应或非 JSON 内容。两种可能Model ID 填错了TaoToken 那边找不到这个模型或者请求被中途截断。先确认 Model ID 拼写和 TaoToken 模型列表里的一致再确认网络稳定。改完 Model ID 重启网关重试。5.4 OAuth 相关报错Error: oauth token exchange failed如果你在 OpenClaw 里配了需要 OAuth 的渠道但没走完授权流程会报这个。桌面自动化场景一般用 API Key 就够了不需要 OAuth。检查.env里是不是混入了 OAuth 相关字段删掉或注释掉只保留 API Key 方式。5.5 路径非法导致安装中断安装失败路径包含非法字符回到 2.3 节的规则把安装路径改成纯英文无空格。改完不用重新解压直接重新点「开始安装」。5.6 安全软件隔离核心文件现象是启动程序双击没反应或者启动后立刻退出。去安全软件的隔离区看有没有Openclaw-win里的文件被拦。有的话恢复并加白名单然后重新解压一次压缩包覆盖再启动。6. 长期使用与模型切换建议跑通之后日常用起来最影响体验的是模型选择。桌面自动化任务对模型的规划能力要求不低简单任务用轻量模型就够复杂多步任务换强一点的模型。因为走的是 TaoToken 统一 Key切换成本就是改.env里OPENAI_MODEL那一行重启网关其他都不用动。如果你打算长期跑自动化任务、或者要接多个 Agent 场景可以看下 TaoToken 的 Coding Planhttps://taotoken.net/coding-plan按用量规划比单次调用更划算。只是想先验证模型效果的直接去模型对话页面https://taotoken.net/chat试几条指令确认模型能力再落到 OpenClaw 里。最后提醒一句OpenClaw 的自动化能力很强但别一上来就让它操作生产环境的数据库或重要文件。先在测试目录里跑通流程确认指令理解准确了再逐步放开权限。我踩过的坑基本都在这篇里了按步骤走能省不少时间。
