TOOLS.md 里把 rg.exe 的完整路径写得明明白白OpenClaw 跑搜索时还是回一句找不到可执行文件——这种排障最别扭的地方在于你没法判断是路径写错了还是模型压根没读到这段提示。这次的顺序是先把模型通道换成 TaoToken 的统一入口打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建 Key再把 OpenClaw 的 Base URL 指向 https://taotoken.net/api最后回头按原文 4.1 节的写法逐条核对 rg 那几行。通道和写法分开验证才不会两个变量一起动、最后不知道是谁修好的。1. TOOLS.md 写了 rg.exe 全路径OpenClaw 还是甩一句“找不到”1.1 先看清报错到底在说什么OpenClaw 里让模型做一次代码检索失败信息一般分两类。第一类是操作系统层面的“rg 不是内部或外部命令”“系统找不到指定的路径”这类说明命令真的执行了只是可执行文件没被定位到。第二类是模型层面的它压根没去调用搜索工具而是凭记忆给你一段猜测的目录结构然后告诉你“我找不到相关文件”。这两类报错的修法完全不同前者要动 TOOLS.md 里的路径后者要查模型有没有稳定读到你的上下文。很多人第一次遇到会把两类混在一起看于是拼命改 TOOLS.md改到第三版还是失败。判断方法是看会话里有没有实际的工具调用记录。如果工具被调用了、参数里还带着你写的那条路径却仍然失败问题在路径字符串本身如果整轮对话里没有任何工具调用问题在通道或者技能注入那一侧。1.2 TOOLS.md 管的是“怎么用”不是“能不能用”原文在 system-prompt.ts:690 那行澄清很关键TOOLS.md does not control tool availability; it is user guidance for how to use external tools。也就是说这份文件被塞进系统提示的位置是 Tooling 章节的使用说明区模型在拿到工具列表之前就先被告知——别指望用 TOOLS.md 打开或关闭某个工具。理解这一点之后排障方向就清晰了TOOLS.md 写错最坏的结果是模型用错参数或者调用一个不存在的路径但不会出现“因为没写 TOOLS.md 所以工具消失”。反过来如果工具列表里根本没有 rg-search 相关的技能你在 TOOLS.md 里写十条路径也没用。配置要分层技能层负责把工具挂上去TOOLS.md 层负责告诉模型这个工具在你机器上的具体样子。2. 判断是路径没写对还是模型没读到这段提示2.1 三种根因一次只动一个变量把可能性收敛成三种一是 TOOLS.md 里的路径字符串有问题比如少写了盘符、用了正斜杠、路径带空格却没处理二是文件写对了但注入环节没生效比如放错了工作区目录、或者被 12,000 字符上限截断三是模型请求这条链路本身不稳定模型时好时坏读没读到上下文全看运气。原文在加载阶段已经把规则说清楚了DEFAULT_TOOLS_FILENAME 就是 TOOLS.md在 CONTEXT_FILE_ORDER 里排第五位order50紧跟在 user.md 后面。它和 agents.md、soul.md 走同一个 loadWorkspaceBootstrapFiles() 入口子 agent 和 cron 任务里也在 MINIMAL_BOOTSTRAP_ALLOWLIST 白名单内。这意味着只要你放在正确的工作区根目录它一定会被加载。2.2 先让模型复述你写进去的内容不用猜直接验。在 OpenClaw 里发一句“把 TOOLS.md 中关于 ripgrep 的那一节原文贴出来不要总结。” 模型如果能把路径和版本号一字不差地念出来说明注入链路是通的问题就落在路径字符串或者调用方式上。如果它开始编、开始说“根据我的理解”那说明这段内容没进上下文先去查文件位置和注入预算。同时在本地开一个终端自己跑一遍这一步必须由你在自己机器上执行不要写成让模型去连你的环境Get-Command rg -ErrorAction SilentlyContinue | Select-Object Source C:\Users\cosmoslife\scoop\apps\ripgrep\current\rg.exe --version第一条命令告诉你 PATH 里到底有没有 rg第二条直接按完整路径调用验证这个 exe 真实存在且能跑。两条的结果贴回对话模型就能基于事实判断而不是基于猜测。这个“本地执行、结果回贴”的循环是后面所有配置的前提。3. 把 OpenClaw 的模型通道换成 TaoToken先排除链路抖动3.1 创建 Key 与确认要填的模型 ID先把凭据准备好。打开 TaoToken 注册登录在控制台里创建一把 API Key复制下来存好后面配置里统一用 YOUR_API_KEY 代替。同一个页面能看到模型广场模型 ID 以那里当时列出来的为准不要凭记忆写一个带日期后缀的名字写错了会直接 404。这一步的意义不只是“找个通道”。当模型调用时断时续你根本分不清是注入失败还是请求超时。先让底层通道稳定再谈 TOOLS.md 的细节变量才收得住。3.2 OpenClaw 配置文件里把 Base URL 指过去OpenClaw 的供应商配置写在它自己的配置文件里路径以你本机版本为准通常在用户目录下的 .openclaw 里。要改的核心只有三个字段Base URL、Key、模型 ID。注意 Base URL 填的是 https://taotoken.net/api末尾不要加 /v1也不要在这条地址上附加任何查询参数——落地页和接口地址是两回事前者是给人点的后者是给工具读的。{ providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: YOUR_API_KEY } }, agent: { provider: taotoken, model: YOUR_MODEL_ID }, workspace: { extraBootstrapFiles: [TOOLS.md] } }字段名以你本地版本的 OpenClaw 为准不同版本可能把 provider 写成 providers 下的一个数组也可能用 providerId 这种键名对照默认配置改即可。workspace 那一节对应的是原文 1.5 提到的 bootstrapExtraFiles 能力当你的 TOOLS.md 不在默认工作区而在某个项目目录里就靠这里额外挂进来。4. 按原文 4.1 节的写法重写 rg 那几行4.1 完整路径、转义、空格三个坑原文说得很直白rg 这类需要完整路径的工具写 TOOLS.md 时要把 Executable 那一行写全因为 PATH 未刷新。实际操作里翻车最多的三个点盘符和反斜杠。Windows 路径要么全用双反斜杠转义要么整段用反引号包起来别一半正斜杠一半反斜杠。路径里的空格。Program Files 这种目录不带引号模型拼出来的命令行会在空格处断开。只写目录不写文件名。写 C:...\ripgrep\current 是不够的必须指到 rg.exe。原文提到单文件上限 12,000 字符截断策略是头 70% 加标记再加尾 20%。如果你的 TOOLS.md 塞了太多无关内容工具路径那几行恰好在尾部被裁掉表现就是“我明明写了它却说没有”。路径段放在文件靠前的位置更安全。4.2 一份可以直接抄的 TOOLS.md 片段结构照原文 4.3 的建议走每个工具 2 到 5 行控制在 1,000 到 4,000 字符# TOOLS.md - Local Notes ## 工具路径 ### ripgrep (rg-search skill) - Executable: C:\Users\cosmoslife\scoop\apps\ripgrep\current\rg.exe - Version: 15.1.0 - Note: PATH 未刷新调用时必须使用完整路径路径含空格要加引号 - Fallback: PowerShell Select-String ## 存储规范 ### Screenshots - Storage: .openclaw\media - Naming: screenshot_YYYYMMDD_HHmmss.png ### Projects - Storage: projects/ ## 已知限制 ### PowerShell Set-Content - 会破坏 UTF-8 编码写文件改用 py -3.10注意这里只写“怎么用”和环境事实不写“哪些工具可用”也不写使用教程——教程属于 Skill 的 SKILL.md通用规则属于 AGENTS.md用户偏好属于 USER.md历史记录属于 MEMORY.md。边界划清楚模型才不会在几份文件之间互相干扰。5. 再跑一次 rg 相关操作看问题有没有消失5.1 先验证模型调用这条链路配置保存后重启 OpenClaw发一条最简单的消息确认模型能回。如果不回先在 TaoToken 模型对话 里用同一把 Key 和同一个模型 ID 发一条测试消息。那边通了说明 Key 和模型 ID 没问题问题在 OpenClaw 配置的字段名或者缩进上。这一步别省。很多人跳过验证直接去改 TOOLS.md结果改完还是失败其实是通道就没通白白折腾半小时。5.2 再让模型带着完整路径跑一次搜索通道确认无误后发一条带明确指令的消息“按 TOOLS.md 里 ripgrep 的 Executable 路径在 projects/ 目录下搜索包含 TODO 的文件只列文件名。” 观察会话里的工具调用参数看它拼出来的命令是不是完整的 exe 路径。如果模型仍然调用失败把它的工具调用参数、你本地 Get-Command 的输出、rg.exe --version 的输出三条贴在一起再问一轮。信息给全模型定位问题的准确率会明显上升。这里依旧是你在本地执行、把结果贴回对话不存在让模型直接连你机器执行这件事。6. 换完通道还报错按这个顺序继续查6.1 401、404 和多出来的 /v1配置里最常见的三个错症状各不相同现象常见原因处理401 UnauthorizedKey 复制时带了空格或填了别的项目的 Key回控制台重新生成一把整段粘贴404 Not Found模型 ID 写错或 Base URL 被加了 /v1模型 ID 以模型广场当时列表为准Base URL 保持 https://taotoken.net/api走了一半超时单次上下文太长TOOLS.md 过大把 TOOLS.md 压到 4,000 字符以内路径段前置第二行那条特别容易踩。工具配置里 Base URL 和浏览器里打开的页面地址是两套东西浏览器里那份要带查询参数填进配置文件的那份必须干干净净。6.2 TOOLS.md 没被重新注入改完文件后没有重启 OpenClaw会话里还是老上下文这是另一批“改了没用”的来源。另外如果你在子 agent 或定时任务里操作确认它走的是同一份工作区配置——原文 1.3 已经把 TOOLS.md 列进 MINIMAL_BOOTSTRAP_ALLOWLIST理论上任何模式都会注入但工作区路径指错了就是另一回事。改完文件重启再发一条要求复述的指令三步做完再判断。还有一种隐蔽情况项目目录下另有一份同名 TOOLS.md通过 extraBootstrapFiles 挂进来两份内容冲突。检查加载顺序只保留一份权威版本。7. 跑通之后把这次调用对一下账配置生效、rg 搜索正常返回文件列表之后回 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 控制台看一眼这次的调用记录和用量确认请求确实走上了这条通道而不是你以为配了、实际还在打别的地址。顺手把 TOOLS.md 在版本库里提一版下次换机器直接拉下来不用重写。如果这台机器以后要长期跑 OpenClaw 和各种技能可以顺手看看 Coding Plan 的套餐是否够用需要另建一把 Key 分给别的工具时在 控制台 API Keys 里创建不要几台机器共用一把。这次的整套顺序记住一句话就够了通道不稳先修通道通道稳了再抠 TOOLS.md 里那一行路径两个变量永远不要同时动。
TOOLS.md 里把 rg.exe 的完整路径写得明明白白OpenClaw 跑搜索时还是回一句找不到可执行文件——这种排障最别扭的地方在于你没法判断是路径写错了还是模型压根没读到这段提示。这次的顺序是先把模型通道换成 TaoToken 的统一入口打开 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 创建 Key再把 OpenClaw 的 Base URL 指向 https://taotoken.net/api最后回头按原文 4.1 节的写法逐条核对 rg 那几行。通道和写法分开验证才不会两个变量一起动、最后不知道是谁修好的。1. TOOLS.md 写了 rg.exe 全路径OpenClaw 还是甩一句“找不到”1.1 先看清报错到底在说什么OpenClaw 里让模型做一次代码检索失败信息一般分两类。第一类是操作系统层面的“rg 不是内部或外部命令”“系统找不到指定的路径”这类说明命令真的执行了只是可执行文件没被定位到。第二类是模型层面的它压根没去调用搜索工具而是凭记忆给你一段猜测的目录结构然后告诉你“我找不到相关文件”。这两类报错的修法完全不同前者要动 TOOLS.md 里的路径后者要查模型有没有稳定读到你的上下文。很多人第一次遇到会把两类混在一起看于是拼命改 TOOLS.md改到第三版还是失败。判断方法是看会话里有没有实际的工具调用记录。如果工具被调用了、参数里还带着你写的那条路径却仍然失败问题在路径字符串本身如果整轮对话里没有任何工具调用问题在通道或者技能注入那一侧。1.2 TOOLS.md 管的是“怎么用”不是“能不能用”原文在 system-prompt.ts:690 那行澄清很关键TOOLS.md does not control tool availability; it is user guidance for how to use external tools。也就是说这份文件被塞进系统提示的位置是 Tooling 章节的使用说明区模型在拿到工具列表之前就先被告知——别指望用 TOOLS.md 打开或关闭某个工具。理解这一点之后排障方向就清晰了TOOLS.md 写错最坏的结果是模型用错参数或者调用一个不存在的路径但不会出现“因为没写 TOOLS.md 所以工具消失”。反过来如果工具列表里根本没有 rg-search 相关的技能你在 TOOLS.md 里写十条路径也没用。配置要分层技能层负责把工具挂上去TOOLS.md 层负责告诉模型这个工具在你机器上的具体样子。2. 判断是路径没写对还是模型没读到这段提示2.1 三种根因一次只动一个变量把可能性收敛成三种一是 TOOLS.md 里的路径字符串有问题比如少写了盘符、用了正斜杠、路径带空格却没处理二是文件写对了但注入环节没生效比如放错了工作区目录、或者被 12,000 字符上限截断三是模型请求这条链路本身不稳定模型时好时坏读没读到上下文全看运气。原文在加载阶段已经把规则说清楚了DEFAULT_TOOLS_FILENAME 就是 TOOLS.md在 CONTEXT_FILE_ORDER 里排第五位order50紧跟在 user.md 后面。它和 agents.md、soul.md 走同一个 loadWorkspaceBootstrapFiles() 入口子 agent 和 cron 任务里也在 MINIMAL_BOOTSTRAP_ALLOWLIST 白名单内。这意味着只要你放在正确的工作区根目录它一定会被加载。2.2 先让模型复述你写进去的内容不用猜直接验。在 OpenClaw 里发一句“把 TOOLS.md 中关于 ripgrep 的那一节原文贴出来不要总结。” 模型如果能把路径和版本号一字不差地念出来说明注入链路是通的问题就落在路径字符串或者调用方式上。如果它开始编、开始说“根据我的理解”那说明这段内容没进上下文先去查文件位置和注入预算。同时在本地开一个终端自己跑一遍这一步必须由你在自己机器上执行不要写成让模型去连你的环境Get-Command rg -ErrorAction SilentlyContinue | Select-Object Source C:\Users\cosmoslife\scoop\apps\ripgrep\current\rg.exe --version第一条命令告诉你 PATH 里到底有没有 rg第二条直接按完整路径调用验证这个 exe 真实存在且能跑。两条的结果贴回对话模型就能基于事实判断而不是基于猜测。这个“本地执行、结果回贴”的循环是后面所有配置的前提。3. 把 OpenClaw 的模型通道换成 TaoToken先排除链路抖动3.1 创建 Key 与确认要填的模型 ID先把凭据准备好。打开 TaoToken 注册登录在控制台里创建一把 API Key复制下来存好后面配置里统一用 YOUR_API_KEY 代替。同一个页面能看到模型广场模型 ID 以那里当时列出来的为准不要凭记忆写一个带日期后缀的名字写错了会直接 404。这一步的意义不只是“找个通道”。当模型调用时断时续你根本分不清是注入失败还是请求超时。先让底层通道稳定再谈 TOOLS.md 的细节变量才收得住。3.2 OpenClaw 配置文件里把 Base URL 指过去OpenClaw 的供应商配置写在它自己的配置文件里路径以你本机版本为准通常在用户目录下的 .openclaw 里。要改的核心只有三个字段Base URL、Key、模型 ID。注意 Base URL 填的是 https://taotoken.net/api末尾不要加 /v1也不要在这条地址上附加任何查询参数——落地页和接口地址是两回事前者是给人点的后者是给工具读的。{ providers: { taotoken: { type: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: YOUR_API_KEY } }, agent: { provider: taotoken, model: YOUR_MODEL_ID }, workspace: { extraBootstrapFiles: [TOOLS.md] } }字段名以你本地版本的 OpenClaw 为准不同版本可能把 provider 写成 providers 下的一个数组也可能用 providerId 这种键名对照默认配置改即可。workspace 那一节对应的是原文 1.5 提到的 bootstrapExtraFiles 能力当你的 TOOLS.md 不在默认工作区而在某个项目目录里就靠这里额外挂进来。4. 按原文 4.1 节的写法重写 rg 那几行4.1 完整路径、转义、空格三个坑原文说得很直白rg 这类需要完整路径的工具写 TOOLS.md 时要把 Executable 那一行写全因为 PATH 未刷新。实际操作里翻车最多的三个点盘符和反斜杠。Windows 路径要么全用双反斜杠转义要么整段用反引号包起来别一半正斜杠一半反斜杠。路径里的空格。Program Files 这种目录不带引号模型拼出来的命令行会在空格处断开。只写目录不写文件名。写 C:...\ripgrep\current 是不够的必须指到 rg.exe。原文提到单文件上限 12,000 字符截断策略是头 70% 加标记再加尾 20%。如果你的 TOOLS.md 塞了太多无关内容工具路径那几行恰好在尾部被裁掉表现就是“我明明写了它却说没有”。路径段放在文件靠前的位置更安全。4.2 一份可以直接抄的 TOOLS.md 片段结构照原文 4.3 的建议走每个工具 2 到 5 行控制在 1,000 到 4,000 字符# TOOLS.md - Local Notes ## 工具路径 ### ripgrep (rg-search skill) - Executable: C:\Users\cosmoslife\scoop\apps\ripgrep\current\rg.exe - Version: 15.1.0 - Note: PATH 未刷新调用时必须使用完整路径路径含空格要加引号 - Fallback: PowerShell Select-String ## 存储规范 ### Screenshots - Storage: .openclaw\media - Naming: screenshot_YYYYMMDD_HHmmss.png ### Projects - Storage: projects/ ## 已知限制 ### PowerShell Set-Content - 会破坏 UTF-8 编码写文件改用 py -3.10注意这里只写“怎么用”和环境事实不写“哪些工具可用”也不写使用教程——教程属于 Skill 的 SKILL.md通用规则属于 AGENTS.md用户偏好属于 USER.md历史记录属于 MEMORY.md。边界划清楚模型才不会在几份文件之间互相干扰。5. 再跑一次 rg 相关操作看问题有没有消失5.1 先验证模型调用这条链路配置保存后重启 OpenClaw发一条最简单的消息确认模型能回。如果不回先在 TaoToken 模型对话 里用同一把 Key 和同一个模型 ID 发一条测试消息。那边通了说明 Key 和模型 ID 没问题问题在 OpenClaw 配置的字段名或者缩进上。这一步别省。很多人跳过验证直接去改 TOOLS.md结果改完还是失败其实是通道就没通白白折腾半小时。5.2 再让模型带着完整路径跑一次搜索通道确认无误后发一条带明确指令的消息“按 TOOLS.md 里 ripgrep 的 Executable 路径在 projects/ 目录下搜索包含 TODO 的文件只列文件名。” 观察会话里的工具调用参数看它拼出来的命令是不是完整的 exe 路径。如果模型仍然调用失败把它的工具调用参数、你本地 Get-Command 的输出、rg.exe --version 的输出三条贴在一起再问一轮。信息给全模型定位问题的准确率会明显上升。这里依旧是你在本地执行、把结果贴回对话不存在让模型直接连你机器执行这件事。6. 换完通道还报错按这个顺序继续查6.1 401、404 和多出来的 /v1配置里最常见的三个错症状各不相同现象常见原因处理401 UnauthorizedKey 复制时带了空格或填了别的项目的 Key回控制台重新生成一把整段粘贴404 Not Found模型 ID 写错或 Base URL 被加了 /v1模型 ID 以模型广场当时列表为准Base URL 保持 https://taotoken.net/api走了一半超时单次上下文太长TOOLS.md 过大把 TOOLS.md 压到 4,000 字符以内路径段前置第二行那条特别容易踩。工具配置里 Base URL 和浏览器里打开的页面地址是两套东西浏览器里那份要带查询参数填进配置文件的那份必须干干净净。6.2 TOOLS.md 没被重新注入改完文件后没有重启 OpenClaw会话里还是老上下文这是另一批“改了没用”的来源。另外如果你在子 agent 或定时任务里操作确认它走的是同一份工作区配置——原文 1.3 已经把 TOOLS.md 列进 MINIMAL_BOOTSTRAP_ALLOWLIST理论上任何模式都会注入但工作区路径指错了就是另一回事。改完文件重启再发一条要求复述的指令三步做完再判断。还有一种隐蔽情况项目目录下另有一份同名 TOOLS.md通过 extraBootstrapFiles 挂进来两份内容冲突。检查加载顺序只保留一份权威版本。7. 跑通之后把这次调用对一下账配置生效、rg 搜索正常返回文件列表之后回 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_end 控制台看一眼这次的调用记录和用量确认请求确实走上了这条通道而不是你以为配了、实际还在打别的地址。顺手把 TOOLS.md 在版本库里提一版下次换机器直接拉下来不用重写。如果这台机器以后要长期跑 OpenClaw 和各种技能可以顺手看看 Coding Plan 的套餐是否够用需要另建一把 Key 分给别的工具时在 控制台 API Keys 里创建不要几台机器共用一把。这次的整套顺序记住一句话就够了通道不稳先修通道通道稳了再抠 TOOLS.md 里那一行路径两个变量永远不要同时动。
