1. 为什么要在 Windows 上折腾本地 AI Agent如果你最近在搜「Windows AI Agent 搭建」或者「OpenClaw 部署教程」大概率已经看过不少一键整合包的介绍。整合包确实把 Git、Node.js 这些依赖都打包好了解压双击就能跑对不想碰命令行的朋友很友好。但真正落地的时候卡人的往往不是安装本身而是装完之后怎么让 Agent 稳定调用大模型——尤其是 Key 怎么配、Base URL 填什么、config.toml 和 settings.json 里哪些字段不能动。我自己在 Win11 上把 OpenClaw 整合包从零跑通前后踩了七八个坑最典型的就是 Gateway 显示在线、但一发指令就报 401或者日志里出现local proxy failed。后来把模型通道统一换成 TaoToken 的 API 之后配置收敛成一套 Key 一个 Base URL排查成本直接降下来了。这篇就把完整流程拆开写从整合包解压、config.toml 骨架、settings.json 字段到 TaoToken 接入、验证请求、常见报错对照尽量做到你复制粘贴就能复现。先说清楚这套东西适合谁一是想在 Windows 本地跑自动化任务文件归类、表格处理、网页抓取的办公用户二是想拿 OpenClaw 当 Agent 宿主、自己接模型做实验的开发者三是被各种「一键包」装完却连不上模型卡住的人。核心检索词就三个——Windows、AI Agent、OpenClaw 部署全文围绕它们展开。需要提前说明的是OpenClaw 本身是本地智能体工具负责调度文件读写、键鼠模拟这些动作而模型推理这一层需要一个稳定的 API 通道。把这两层分开理解后面排查问题会清晰很多界面报错多半是 Agent 层请求失败多半是模型通道层。2. TaoToken 前置准备统一 Key 与 API 通道在动 config.toml 之前先把模型通道这层准备好否则后面配置填了也是白填。TaoToken 在这里扮演的角色就是给 OpenClaw 提供一个统一的 API 入口——你不用在配置文件里塞好几家厂商的 Key也不用为每个模型单独改 Base URL一个 Key 走天下。2.1 注册与获取 API Key打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。控制台地址是 https://taotoken.net/console 登录后左侧菜单找到 API Keys 页面https://taotoken.net/api-keys 。在这里创建一个新 Key复制出来先存到记事本里后面 config.toml 和 settings.json 都要用。创建 Key 的时候注意两点一是给它起个能认出来的名字比如openclaw-win方便以后多设备区分二是创建后只显示一次页面刷新就看不到了务必当场复制。如果手滑没复制直接删掉重建一个就行不折腾。2.2 确认 Base URL 与模型 IDTaoToken 的 API 基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置里就填这个。模型 ID 这块你可以在模型对话页面 https://taotoken.net/chat 里先试跑一下确认哪个模型响应正常再把它写进配置。常见的比如 claude 系列、gpt 系列都能在对话页里直接选。这里有个容易混的点Base URL 到底填https://taotoken.net/api还是带/v1的版本不同客户端要求不一样。OpenClaw 的 config.toml 里provider 的 base_url 字段一般填到/api这一层具体路径由客户端自己拼。如果你填了带/v1的反而可能拼成/api/v1/v1/...导致 404。这个后面在排错章节会再展开。2.3 为什么建议统一走一个通道我试过在配置里同时挂两三个 provider结果就是每次报错都要先判断是哪个通道的问题排查时间翻倍。统一成 TaoToken 一个通道之后401 就是 Key 问题超时就是网络或额度问题reading choices就是返回结构问题判断路径非常短。对本地 Agent 这种需要长期稳定运行的场景通道越少越省心。另外如果你后面要跑长期编码任务或者 Agent 工作流可以了解下 Coding Planhttps://taotoken.net/coding-plan 它更适合高频调用的场景。不过这篇聚焦部署和排查先把基础通道跑通再说。3. 可复制配置config.toml 与 settings.json 骨架这一节是全文的核心直接给可复制的配置片段。OpenClaw 整合包解压后配置目录一般在安装路径下的config文件夹里你会看到config.toml和settings.json两个文件。前者管模型 provider 和通道后者管客户端行为和 Gateway 参数。3.1 config.toml 骨架下面这份是我实测能跑通的骨架把api_key换成你自己的即可。注意 TOML 里字符串用双引号路径用正斜杠或双反斜杠都行但别用单反斜杠会被当转义符。# OpenClaw 模型通道配置 # 路径示例D:/OpenClaw/config/config.toml [gateway] host 127.0.0.1 port 18789 auto_start true [provider.taotoken] type openai_compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-3-5-sonnet timeout 120 max_retries 2 [agent] default_provider taotoken workspace D:/OpenClaw/workspace log_level info几个字段说明一下。type填openai_compatible是因为 TaoToken 的接口兼容 OpenAI 格式OpenClaw 能直接识别。base_url就填到/api不要自己加/v1。timeout给 120 秒本地 Agent 有时候要处理大文件太短会中途断。max_retries给 2偶发网络抖动可以自动重试。3.2 settings.json 骨架settings.json 管的是客户端侧的行为和 config.toml 分工不同。下面这份同样是可复制的{ gateway: { url: http://127.0.0.1:18789, healthCheckInterval: 30, reconnectDelay: 5 }, ui: { language: zh-CN, theme: light, showTokenStats: true }, agent: { provider: taotoken, model: claude-3-5-sonnet, maxTokens: 4096, temperature: 0.7 }, security: { allowFileWrite: true, allowShellExec: false, allowedPaths: [ D:/OpenClaw/workspace, D:/Downloads ] } }这里security.allowedPaths很关键它限制了 Agent 能读写哪些目录。默认只放开 workspace 和下载目录避免它乱动系统盘。allowShellExec建议先设 false等跑稳定了再按需打开。3.3 三件套对齐检查配置写完做一次三件套对齐Base URL 是https://taotoken.net/apiKey 是sk-开头那串Model ID 是你在对话页确认过的那个。这三样在 config.toml 和 settings.json 里必须一致任何一处写错都会导致请求失败。我见过最常见的就是 config.toml 里写了claude-3-5-sonnetsettings.json 里手滑写成claude-3.5-sonnet结果一直报模型不存在。4. 验证请求从 Gateway 在线到指令跑通配置填完不代表就能用得一步步验证。这一节给可执行的验证动作每步都有明确的成功标志。4.1 启动 Gateway 并确认端口双击 OpenClaw 启动程序等界面加载完。右上角状态栏应该显示「Gateway 在线」绿色标识。如果一直转圈显示「正在等待 Gateway 就绪」先等 1 到 3 分钟首次启动要初始化依赖。超过 3 分钟还不行就去检查端口。打开 PowerShell跑一句netstat -ano | findstr 18789如果能看到LISTENING状态说明 Gateway 端口正常。如果什么都没有说明 Gateway 没起来或者端口被别的程序占了。端口冲突的排查在下一节展开。4.2 用 curl 直接验证模型通道在动 Agent 之前先用 curl 单独验证 TaoToken 通道通不通这样能把「通道问题」和「Agent 问题」分开。PowerShell 里跑curl.exe -X POST https://taotoken.net/api/v1/chat/completions -H Authorization: Bearer sk-你的TaoToken密钥 -H Content-Type: application/json -d {\model\:\claude-3-5-sonnet\,\messages\:[{\role\:\user\,\content\:\ping\}]}注意这里 curl 的路径是/api/v1/chat/completions因为这是直接调 API需要完整路径而 config.toml 里填的是/api客户端会自己拼。这两个不要搞混。如果返回里有choices字段和正常内容说明通道没问题。如果返回 401就是 Key 错了返回 404就是路径拼错了返回超时就是网络或额度问题。4.3 下发第一条 Agent 指令通道验证通过后回到 OpenClaw 界面在底部输入框下发一条简单指令比如列出 D:/OpenClaw/workspace 目录下的所有文件回车发送。如果 Agent 正常返回文件列表说明整条链路——界面 → Gateway → TaoToken → 模型 → 返回——全部打通。这一步成功之后再试复杂指令比如「整理 D 盘下载文件夹里的图片按拍摄日期建立文件夹分类存放」。4.4 看日志确认请求细节右上角有「运行日志」入口点开能看到每次请求的详细记录。重点看三样请求的 Base URL 是不是https://taotoken.net/api用的 Model ID 是不是你配的那个返回状态码是不是 200。日志里如果出现local proxy failed说明本地代理层有问题通常是端口或防火墙拦截。5. 本篇常见错排查401、local proxy failed、reading choices这一节按真实报错来对照每条都给现象、原因、处理动作。这些是我在 Windows 上实际遇到过的不是凭空列的。5.1 401 Unauthorized现象界面提示请求失败日志里状态码 401。原因基本就三个Key 复制错了、Key 前后带了空格、Key 已经失效。处理动作重新去 https://taotoken.net/api-keys 复制一次粘贴到 config.toml 的api_key字段注意别把引号也复制进去。改完重启 Gateway。5.2 local proxy failed现象日志里出现local proxy failed或connection refused。原因通常是 Gateway 端口被占或者防火墙拦了本地回环。处理动作先netstat -ano | findstr 18789看端口如果被占改 config.toml 里的port为别的值比如 18790同时把 settings.json 里的gateway.url也改成对应端口。然后检查 Windows Defender 防火墙给 OpenClaw 主程序放行。5.3 reading choices 报错现象日志里出现error reading choices或invalid response format。原因是客户端期望 OpenAI 格式的返回但实际拿到的结构不对。常见于 Base URL 填错比如填了带/v1的导致路径重复拼接。处理动作确认 config.toml 里base_url是https://taotoken.net/api不带/v1确认type是openai_compatible。5.4 OAuth 相关报错现象提示 OAuth 失败或 token 过期。如果你用的是需要 OAuth 的客户端比如某些 Claude Code 场景要确认认证方式选的是 API Key 而不是 OAuth。处理动作在客户端设置里切换到 API Key 模式填入 TaoToken 的 Key。Claude Code 的接入文档可以参考 https://taotoken.net/doc 里面有各客户端的配置说明。5.5 端口冲突排查表报错现象可能原因处理动作Gateway 离线端口被占改 port 并同步 settings.jsonlocal proxy failed防火墙拦截放行主程序请求超时timeout 太短调到 120 秒模型不存在Model ID 拼错对齐三件套排查顺序建议先 curl 验证通道再看 Gateway 端口最后看配置文件字段。这个顺序能把问题范围快速缩小。6. 稳定运行后的接入与进阶把上面几步跑通之后OpenClaw 在 Windows 上基本就能稳定用了。日常维护其实很简单Key 快到期前去控制台换一个配置文件里改一行重启即可模型想换改 config.toml 和 settings.json 里的 Model ID两处保持一致。如果你后面要接 Claude Code 或者做更复杂的 Agent 工作流接入文档在 https://taotoken.net/doc 里面有各客户端的完整配置示例。需要长期跑编码任务的可以看 Coding Planhttps://taotoken.net/coding-plan 。想先试模型效果的模型对话页面 https://taotoken.net/chat 可以直接跑。最后留一个我踩过的坑整合包解压路径千万别带中文和空格D:/OpenClaw这种最稳。我一开始图省事解压到「D:/新建文件夹/OpenClaw」结果 Gateway 启动时读配置文件路径出错排查了半天才发现是路径里的中文。改成纯英文路径后一次就通了。这个细节在官方文档里不一定写但实际部署时特别容易中招。
1. 为什么要在 Windows 上折腾本地 AI Agent如果你最近在搜「Windows AI Agent 搭建」或者「OpenClaw 部署教程」大概率已经看过不少一键整合包的介绍。整合包确实把 Git、Node.js 这些依赖都打包好了解压双击就能跑对不想碰命令行的朋友很友好。但真正落地的时候卡人的往往不是安装本身而是装完之后怎么让 Agent 稳定调用大模型——尤其是 Key 怎么配、Base URL 填什么、config.toml 和 settings.json 里哪些字段不能动。我自己在 Win11 上把 OpenClaw 整合包从零跑通前后踩了七八个坑最典型的就是 Gateway 显示在线、但一发指令就报 401或者日志里出现local proxy failed。后来把模型通道统一换成 TaoToken 的 API 之后配置收敛成一套 Key 一个 Base URL排查成本直接降下来了。这篇就把完整流程拆开写从整合包解压、config.toml 骨架、settings.json 字段到 TaoToken 接入、验证请求、常见报错对照尽量做到你复制粘贴就能复现。先说清楚这套东西适合谁一是想在 Windows 本地跑自动化任务文件归类、表格处理、网页抓取的办公用户二是想拿 OpenClaw 当 Agent 宿主、自己接模型做实验的开发者三是被各种「一键包」装完却连不上模型卡住的人。核心检索词就三个——Windows、AI Agent、OpenClaw 部署全文围绕它们展开。需要提前说明的是OpenClaw 本身是本地智能体工具负责调度文件读写、键鼠模拟这些动作而模型推理这一层需要一个稳定的 API 通道。把这两层分开理解后面排查问题会清晰很多界面报错多半是 Agent 层请求失败多半是模型通道层。2. TaoToken 前置准备统一 Key 与 API 通道在动 config.toml 之前先把模型通道这层准备好否则后面配置填了也是白填。TaoToken 在这里扮演的角色就是给 OpenClaw 提供一个统一的 API 入口——你不用在配置文件里塞好几家厂商的 Key也不用为每个模型单独改 Base URL一个 Key 走天下。2.1 注册与获取 API Key打开官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册登录后进入控制台。控制台地址是 https://taotoken.net/console 登录后左侧菜单找到 API Keys 页面https://taotoken.net/api-keys 。在这里创建一个新 Key复制出来先存到记事本里后面 config.toml 和 settings.json 都要用。创建 Key 的时候注意两点一是给它起个能认出来的名字比如openclaw-win方便以后多设备区分二是创建后只显示一次页面刷新就看不到了务必当场复制。如果手滑没复制直接删掉重建一个就行不折腾。2.2 确认 Base URL 与模型 IDTaoToken 的 API 基础地址是 https://taotoken.net/api 注意这个地址不带任何查询参数配置里就填这个。模型 ID 这块你可以在模型对话页面 https://taotoken.net/chat 里先试跑一下确认哪个模型响应正常再把它写进配置。常见的比如 claude 系列、gpt 系列都能在对话页里直接选。这里有个容易混的点Base URL 到底填https://taotoken.net/api还是带/v1的版本不同客户端要求不一样。OpenClaw 的 config.toml 里provider 的 base_url 字段一般填到/api这一层具体路径由客户端自己拼。如果你填了带/v1的反而可能拼成/api/v1/v1/...导致 404。这个后面在排错章节会再展开。2.3 为什么建议统一走一个通道我试过在配置里同时挂两三个 provider结果就是每次报错都要先判断是哪个通道的问题排查时间翻倍。统一成 TaoToken 一个通道之后401 就是 Key 问题超时就是网络或额度问题reading choices就是返回结构问题判断路径非常短。对本地 Agent 这种需要长期稳定运行的场景通道越少越省心。另外如果你后面要跑长期编码任务或者 Agent 工作流可以了解下 Coding Planhttps://taotoken.net/coding-plan 它更适合高频调用的场景。不过这篇聚焦部署和排查先把基础通道跑通再说。3. 可复制配置config.toml 与 settings.json 骨架这一节是全文的核心直接给可复制的配置片段。OpenClaw 整合包解压后配置目录一般在安装路径下的config文件夹里你会看到config.toml和settings.json两个文件。前者管模型 provider 和通道后者管客户端行为和 Gateway 参数。3.1 config.toml 骨架下面这份是我实测能跑通的骨架把api_key换成你自己的即可。注意 TOML 里字符串用双引号路径用正斜杠或双反斜杠都行但别用单反斜杠会被当转义符。# OpenClaw 模型通道配置 # 路径示例D:/OpenClaw/config/config.toml [gateway] host 127.0.0.1 port 18789 auto_start true [provider.taotoken] type openai_compatible base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 model claude-3-5-sonnet timeout 120 max_retries 2 [agent] default_provider taotoken workspace D:/OpenClaw/workspace log_level info几个字段说明一下。type填openai_compatible是因为 TaoToken 的接口兼容 OpenAI 格式OpenClaw 能直接识别。base_url就填到/api不要自己加/v1。timeout给 120 秒本地 Agent 有时候要处理大文件太短会中途断。max_retries给 2偶发网络抖动可以自动重试。3.2 settings.json 骨架settings.json 管的是客户端侧的行为和 config.toml 分工不同。下面这份同样是可复制的{ gateway: { url: http://127.0.0.1:18789, healthCheckInterval: 30, reconnectDelay: 5 }, ui: { language: zh-CN, theme: light, showTokenStats: true }, agent: { provider: taotoken, model: claude-3-5-sonnet, maxTokens: 4096, temperature: 0.7 }, security: { allowFileWrite: true, allowShellExec: false, allowedPaths: [ D:/OpenClaw/workspace, D:/Downloads ] } }这里security.allowedPaths很关键它限制了 Agent 能读写哪些目录。默认只放开 workspace 和下载目录避免它乱动系统盘。allowShellExec建议先设 false等跑稳定了再按需打开。3.3 三件套对齐检查配置写完做一次三件套对齐Base URL 是https://taotoken.net/apiKey 是sk-开头那串Model ID 是你在对话页确认过的那个。这三样在 config.toml 和 settings.json 里必须一致任何一处写错都会导致请求失败。我见过最常见的就是 config.toml 里写了claude-3-5-sonnetsettings.json 里手滑写成claude-3.5-sonnet结果一直报模型不存在。4. 验证请求从 Gateway 在线到指令跑通配置填完不代表就能用得一步步验证。这一节给可执行的验证动作每步都有明确的成功标志。4.1 启动 Gateway 并确认端口双击 OpenClaw 启动程序等界面加载完。右上角状态栏应该显示「Gateway 在线」绿色标识。如果一直转圈显示「正在等待 Gateway 就绪」先等 1 到 3 分钟首次启动要初始化依赖。超过 3 分钟还不行就去检查端口。打开 PowerShell跑一句netstat -ano | findstr 18789如果能看到LISTENING状态说明 Gateway 端口正常。如果什么都没有说明 Gateway 没起来或者端口被别的程序占了。端口冲突的排查在下一节展开。4.2 用 curl 直接验证模型通道在动 Agent 之前先用 curl 单独验证 TaoToken 通道通不通这样能把「通道问题」和「Agent 问题」分开。PowerShell 里跑curl.exe -X POST https://taotoken.net/api/v1/chat/completions -H Authorization: Bearer sk-你的TaoToken密钥 -H Content-Type: application/json -d {\model\:\claude-3-5-sonnet\,\messages\:[{\role\:\user\,\content\:\ping\}]}注意这里 curl 的路径是/api/v1/chat/completions因为这是直接调 API需要完整路径而 config.toml 里填的是/api客户端会自己拼。这两个不要搞混。如果返回里有choices字段和正常内容说明通道没问题。如果返回 401就是 Key 错了返回 404就是路径拼错了返回超时就是网络或额度问题。4.3 下发第一条 Agent 指令通道验证通过后回到 OpenClaw 界面在底部输入框下发一条简单指令比如列出 D:/OpenClaw/workspace 目录下的所有文件回车发送。如果 Agent 正常返回文件列表说明整条链路——界面 → Gateway → TaoToken → 模型 → 返回——全部打通。这一步成功之后再试复杂指令比如「整理 D 盘下载文件夹里的图片按拍摄日期建立文件夹分类存放」。4.4 看日志确认请求细节右上角有「运行日志」入口点开能看到每次请求的详细记录。重点看三样请求的 Base URL 是不是https://taotoken.net/api用的 Model ID 是不是你配的那个返回状态码是不是 200。日志里如果出现local proxy failed说明本地代理层有问题通常是端口或防火墙拦截。5. 本篇常见错排查401、local proxy failed、reading choices这一节按真实报错来对照每条都给现象、原因、处理动作。这些是我在 Windows 上实际遇到过的不是凭空列的。5.1 401 Unauthorized现象界面提示请求失败日志里状态码 401。原因基本就三个Key 复制错了、Key 前后带了空格、Key 已经失效。处理动作重新去 https://taotoken.net/api-keys 复制一次粘贴到 config.toml 的api_key字段注意别把引号也复制进去。改完重启 Gateway。5.2 local proxy failed现象日志里出现local proxy failed或connection refused。原因通常是 Gateway 端口被占或者防火墙拦了本地回环。处理动作先netstat -ano | findstr 18789看端口如果被占改 config.toml 里的port为别的值比如 18790同时把 settings.json 里的gateway.url也改成对应端口。然后检查 Windows Defender 防火墙给 OpenClaw 主程序放行。5.3 reading choices 报错现象日志里出现error reading choices或invalid response format。原因是客户端期望 OpenAI 格式的返回但实际拿到的结构不对。常见于 Base URL 填错比如填了带/v1的导致路径重复拼接。处理动作确认 config.toml 里base_url是https://taotoken.net/api不带/v1确认type是openai_compatible。5.4 OAuth 相关报错现象提示 OAuth 失败或 token 过期。如果你用的是需要 OAuth 的客户端比如某些 Claude Code 场景要确认认证方式选的是 API Key 而不是 OAuth。处理动作在客户端设置里切换到 API Key 模式填入 TaoToken 的 Key。Claude Code 的接入文档可以参考 https://taotoken.net/doc 里面有各客户端的配置说明。5.5 端口冲突排查表报错现象可能原因处理动作Gateway 离线端口被占改 port 并同步 settings.jsonlocal proxy failed防火墙拦截放行主程序请求超时timeout 太短调到 120 秒模型不存在Model ID 拼错对齐三件套排查顺序建议先 curl 验证通道再看 Gateway 端口最后看配置文件字段。这个顺序能把问题范围快速缩小。6. 稳定运行后的接入与进阶把上面几步跑通之后OpenClaw 在 Windows 上基本就能稳定用了。日常维护其实很简单Key 快到期前去控制台换一个配置文件里改一行重启即可模型想换改 config.toml 和 settings.json 里的 Model ID两处保持一致。如果你后面要接 Claude Code 或者做更复杂的 Agent 工作流接入文档在 https://taotoken.net/doc 里面有各客户端的完整配置示例。需要长期跑编码任务的可以看 Coding Planhttps://taotoken.net/coding-plan 。想先试模型效果的模型对话页面 https://taotoken.net/chat 可以直接跑。最后留一个我踩过的坑整合包解压路径千万别带中文和空格D:/OpenClaw这种最稳。我一开始图省事解压到「D:/新建文件夹/OpenClaw」结果 Gateway 启动时读配置文件路径出错排查了半天才发现是路径里的中文。改成纯英文路径后一次就通了。这个细节在官方文档里不一定写但实际部署时特别容易中招。
