企业官网建设流程全解析

1. OpenCode Agent 里 read 工具提示词异常到底长什么样

你在 OpenCode 里让 Agent 读一个文件，结果它要么反复读同一个路径、要么只读 30 行就停下来、要么把相对路径./config.json直接丢给 read 工具然后报错。这类现象表面看是模型「不听话」，实际上大概率是 read 工具提示词没有被正确加载，或者被你的自定义配置覆盖掉了。

read 工具在 OpenCode 里承担的角色很明确：读取文件或目录内容，返回带行号的文本，遇到图片或 PDF 则作为附件交给多模态模型。它的提示词文件位于packages/opencode/src/tool/read.txt，里面规定了几个硬性约束——filePath 必须是绝对路径、默认只返回前 2000 行、超过 2000 字符的行会被截断、翻页靠 offset 参数、大文件建议先用 Grep 定位、不确定路径先用 Glob 查找、多个文件要并行读取、避免每次只读几十行的挤牙膏行为。

当这些约束没有生效时，你会看到非常典型的异常：Agent 用./src/index.ts这种相对路径调用 read，工具直接返回路径不存在的错误；或者 Agent 读完前 2000 行后不知道用 offset 继续，而是重新从头读一遍；又或者它明明要读三个文件，却串行地一个一个读，每次只读 50 行，把一次任务拖成几十次工具调用。

这个场景适合谁？适合正在用 OpenCode 做本地代码库问答、文档检索、日志分析的开发者，尤其是那些已经接了自定义模型或自定义工具配置、发现 Agent 行为跟官方文档描述不一致的人。核心检索词就是 OpenCode read 工具提示词排查，你要做的是从提示词配置入手，确认工具描述是否被正确加载与执行。

我试过在同一个 OpenCode 实例里切换不同模型，read 工具的表现差异非常大。有的模型会老老实实传绝对路径，有的模型看到filePath这个参数名就默认可以传相对路径。这说明提示词本身没问题，问题出在提示词有没有被完整注入到模型的系统消息里，以及模型有没有正确理解这段描述。

排查思路分三层：第一层确认 read.txt 是否被正确加载，第二层确认你的自定义配置有没有覆盖或截断这段提示词，第三层确认模型实际收到的工具描述跟文件内容是否一致。下面按这个顺序展开，每一步都给可复制的配置片段和验证动作。

2. TaoToken 前置：把模型接入和工具提示词排查串起来

在排查 read 工具提示词之前，你需要一个稳定的模型接入点，否则你分不清是提示词没加载，还是模型本身对工具调用的支持有问题。TaoToken 在这里的作用是提供一个统一的 API 入口，让你可以快速切换不同模型来对比 read 工具的行为差异。

TaoToken 的官网是 https://taotoken.net/?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content= ，API 地址是 https://taotoken.net/api 。你需要在控制台创建一个 API Key，然后把它配置到 OpenCode 的模型设置里。控制台入口在 https://taotoken.net/console?utm_source=taotoken_aicg_blog_end&utm_content=console&utm_campaign=rewrite ，API Keys 管理页面在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 。

为什么排查 read 工具提示词要先搞定模型接入？因为 OpenCode 的工具调用依赖模型返回结构化的 tool call。如果模型接入不稳定，你看到的「read 工具不按提示词执行」可能只是模型返回了格式错误的 tool call，跟提示词本身无关。用一个稳定的接入点，你才能把变量控制住。

配置 OpenCode 使用 TaoToken 的方式，取决于你用的是哪种接入模式。如果你走的是 OpenAI 兼容接口，在 OpenCode 的配置文件里设置 baseURL 和 apiKey 即可。如果你用的是 Claude Code 风格的接入，需要参考对应的文档。接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite ，里面有不同客户端的配置示例。

这里要强调一点：TaoToken 是模型 API 接入服务，不是编辑器替代品，也不是让你绕过 OpenCode 的工具机制。它的价值在于让你能在一个地方管理多个模型的 Key，方便你在排查 read 工具提示词时快速切换模型做对照实验。

举个例子，你可以先用模型 A 跑一次 read 工具调用，记录它传的 filePath 是绝对路径还是相对路径；然后切到模型 B 跑同样的任务，对比行为差异。如果两个模型都出现同样的异常，那问题大概率在提示词加载环节；如果只有一个模型异常，那问题在模型对工具描述的理解上。这个对照实验的前提就是你有一个能快速切换模型的接入点。

TaoToken 的模型对话入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，你可以先用它验证某个模型是否支持工具调用，再决定要不要把它配到 OpenCode 里。Coding Plan 入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，适合长期做 Agent 开发的场景。

把模型接入搞定之后，你才有资格说「read 工具提示词有问题」。否则你排查半天，最后发现是 API Key 过期或者模型不支持 function calling，那就白忙活了。

3. 可复制配置：read 工具提示词片段与 OpenCode 设置

这一节给你可以直接复制粘贴的配置片段。先看 read 工具提示词的核心内容，这段描述决定了模型怎么调用 read 工具。你可以把它作为自定义工具描述写进 OpenCode 的配置里，也可以用来对照官方 read.txt 是否被正确加载。

{ "tool": { "read": { "description": "Read a file or directory. filePath MUST be an absolute path like /home/user/project/src/index.ts, NOT a relative path like ./index.ts. Returns the first 2000 lines by default. Use offset (1-indexed) to read further pages. For very large files, prefer Grep to locate content first. If unsure about the path, use Glob to find the file before reading. Multiple files should be read in parallel, not sequentially. Avoid reading only 30 lines at a time; read a larger window like 500 or 1000 lines when context is needed. Image and PDF files are returned as attachments for multimodal models.", "parameters": { "filePath": { "type": "string", "description": "Absolute path to the file or directory to read" }, "offset": { "type": "number", "description": "Line number to start reading from, 1-indexed" }, "limit": { "type": "number", "description": "Maximum number of lines to read" } } } } }

这段 JSON 的关键点在于 description 字段。它把 read 工具的约束全部写进去了：绝对路径、2000 行默认限制、offset 翻页、Grep 优先、Glob 定位、并行读取、避免小窗口、多媒体附件。如果你的 OpenCode 配置里 read 工具的 description 是空的或者被截断了，模型就不知道这些规则，行为自然异常。

如果你用的是 TOML 格式的配置文件，可以这样写：

[tool.read] description = """ Read a file or directory. filePath MUST be an absolute path. Returns the first 2000 lines by default. Use offset (1-indexed) to read further. For very large files, prefer Grep to locate content first. If unsure about the path, use Glob to find the file before reading. Multiple files should be read in parallel. Avoid reading only 30 lines at a time; read 500-1000 lines when context is needed. Image and PDF files are returned as attachments. """ [tool.read.parameters.filePath] type = "string" description = "Absolute path to the file or directory" [tool.read.parameters.offset] type = "number" description = "Line number to start reading from, 1-indexed" [tool.read.parameters.limit] type = "number" description = "Maximum number of lines to read"

如果你用的是 Claude Code 风格的 settings.json，配置结构会不一样，但核心还是把 read 工具的 description 写完整。Claude Code 的接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite ，里面有 settings.json 的完整示例。

配置写完之后，你需要确认 OpenCode 实际加载的是哪份提示词。OpenCode 的加载顺序通常是：内置 read.txt → 用户自定义配置 → 运行时覆盖。如果你在自定义配置里写了 read 工具描述，它会覆盖内置的 read.txt。这时候如果你写的描述不完整，模型就会丢失部分约束。

一个常见的坑是：你在自定义配置里只写了 filePath 参数，忘了写 offset 和 limit，结果模型不知道可以翻页，读大文件时反复从头读。另一个坑是 description 写得太短，比如只写「Read a file」，模型就不知道要传绝对路径。

验证配置是否生效的方法很简单：在 OpenCode 里发一个明确需要读文件的请求，比如「读取 /etc/hostname 的内容」，然后看 Agent 返回的 tool call 里 filePath 是不是绝对路径。如果它传的是hostname或者./hostname，说明提示词里的绝对路径约束没有生效。

你还可以在 OpenCode 的日志里搜索 read 工具的调用记录，确认模型收到的 tool description 跟你配置的是否一致。如果日志里显示的 description 是旧版本或者被截断的版本，说明配置没有热加载，需要重启 OpenCode 或者重新加载配置。

4. 验证请求：确认 read 工具描述被正确加载与执行

配置写好了，接下来要验证。验证分两步：第一步确认提示词被加载，第二步确认模型按提示词执行。

先看第一步。在 OpenCode 的安装目录下找到 read.txt 的实际路径，通常在packages/opencode/src/tool/read.txt。用 read 工具自己读这个文件，或者用命令行查看：

cat packages/opencode/src/tool/read.txt | head -50

对比你自定义配置里的 description，看内容是否一致。如果 OpenCode 支持热加载，修改配置后不需要重启；如果不支持，重启后再验证。

第二步，发一个测试请求，观察 Agent 的 tool call。你可以用这样的提示词：

请读取 /home/user/project/package.json 文件的前 100 行，并告诉我 dependencies 里有哪些包。

预期行为：Agent 调用 read 工具，filePath 传/home/user/project/package.json（绝对路径），limit 传 100 或者不传（默认 2000），然后返回带行号的内容。

如果 Agent 传的是package.json或者./package.json，说明绝对路径约束没生效。如果 Agent 读了整个文件而不是前 100 行，说明 limit 参数没被正确理解。如果 Agent 返回的内容没有行号，说明 read 工具的返回格式被改动了。

再测一个翻页场景：

请读取 /var/log/syslog 的第 2001 行到第 2500 行。

预期行为：Agent 调用 read 工具，filePath 传绝对路径，offset 传 2001，limit 传 500。如果 Agent 不知道用 offset，而是重新从头读，说明翻页机制没生效。

再测一个并行读取场景：

请同时读取 /etc/hostname、/etc/hosts、/etc/resolv.conf 三个文件的内容。

预期行为：Agent 在一次响应里发出三个 read tool call，而不是串行地读完一个再读下一个。如果它是串行的，说明并行读取的提示没有生效。

再测一个多媒体场景：

请读取 /home/user/screenshot.png 这个图片文件。

预期行为：read 工具返回文件附件，而不是尝试把二进制当文本解析。如果 Agent 返回一堆乱码，说明多媒体处理的提示没生效。

验证过程中，你可以用 TaoToken 的模型对话入口 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite 先单独测试模型是否支持工具调用。如果模型在对话入口里就不能正确返回 tool call，那配到 OpenCode 里也不会有好结果。

实测下来，read 工具提示词生效的关键在于三点：description 完整、参数定义清晰、模型支持 function calling。缺任何一个，你都会看到「工具描述与实际调用行为不一致」的现象。

5. 本篇常见错排查：401、local proxy failed、reading choices、OAuth

排查 read 工具提示词时，你会遇到一些看起来像提示词问题、实际是接入或认证问题的报错。这一节对照真实报错逐个拆解。

401 Unauthorized：这是最常见的。你在 OpenCode 里配置了 TaoToken 的 API Key，但 Key 无效或过期。表现是 Agent 根本不调用 read 工具，直接返回认证错误。排查方法：去 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite 确认 Key 状态，重新生成一个再试。注意 Base URL 要写 https://taotoken.net/api ，不要多加路径。

local proxy failed：这个报错通常出现在你本地有代理设置，但代理没有正常工作时。OpenCode 尝试通过本地代理访问 API，代理拒绝连接。排查方法：检查环境变量HTTP_PROXY和HTTPS_PROXY，如果不需要代理就清空它们。注意，这里说的是本地网络配置问题，不是让你去搞什么网络工具，只是把不必要的代理设置去掉。

reading choices 相关报错：这个报错说明模型返回的响应格式不符合 OpenAI 兼容规范，OpenCode 在解析choices字段时失败。常见原因是模型不支持 function calling，或者你用的模型 ID 写错了。排查方法：确认 Model ID 跟 TaoToken 文档里列出的名称一致，不要自己拼写。如果模型本身不支持工具调用，换一个支持的模型。

OAuth 相关报错：如果你用的是 Claude Code 风格的接入，可能会遇到 OAuth token 过期的问题。表现是 read 工具调用被拒绝，提示需要重新认证。排查方法：参考 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=claude_code&utm_campaign=rewrite 里的 OAuth 配置说明，重新走一遍认证流程。

read 工具返回空内容：Agent 调用了 read 工具，filePath 也传了绝对路径，但返回内容是空的。可能原因：文件确实为空、文件权限不足、或者 offset 传了一个超过文件行数的值。排查方法：先用命令行cat确认文件有内容，再检查 OpenCode 进程有没有读该文件的权限。

read 工具反复读同一个文件：Agent 读完一次后，又用同样的参数读第二次。这通常是提示词里没有说清楚「读完后应该基于内容回答，而不是重复读取」。你可以在自定义 description 里加一句「After reading, use the content to answer; do not re-read the same file unless the user asks」。

read 工具只读 30 行：Agent 每次只读很小的一段，导致一个 2000 行的文件要读几十次。这是提示词里「避免挤牙膏式读取」的约束没生效。检查你的 description 里有没有写「read 500-1000 lines when context is needed」。

read 工具不传 offset：Agent 读完前 2000 行后，不知道用 offset 继续，而是重新从头读。检查 description 里有没有写「Use offset (1-indexed) to read further pages」。

read 工具传相对路径：Agent 传./src/index.ts而不是绝对路径。检查 description 里有没有写「filePath MUST be an absolute path」。

如果你在配置里同时用了 CC Switch、Cline MCP 或 Codex auth.json，需要确保三件套齐全：Base URL 写 https://taotoken.net/api ，API Key 写你在控制台生成的 Key，Model ID 写模型名称。缺任何一个都会导致 read 工具调用失败。

排查顺序建议：先看报错类型，401 和 OAuth 是认证问题，local proxy failed 是网络配置问题，reading choices 是模型兼容性问题，read 工具行为异常才是提示词问题。不要把所有问题都归到提示词上。

6. 语义一致 CTA：继续用 TaoToken 验证你的 read 工具配置

read 工具提示词的排查，本质上是确认三件事：提示词被正确加载、模型正确理解工具描述、工具调用结果符合预期。这三件事都依赖一个稳定的模型接入点。

如果你还在用不稳定的接入方式，建议先把 TaoToken 的 API Key 配好。API Keys 管理在 https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_content=api-keys&utm_campaign=rewrite ，接入文档在 https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_content=doc&utm_campaign=rewrite 。配好之后，你可以快速切换模型，对比 read 工具在不同模型下的行为差异。

如果你要长期做 Agent 开发，Coding Plan 入口在 https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_content=coding_plan&utm_campaign=rewrite ，适合需要频繁调用工具的场景。如果你只是想先验证某个模型是否支持 read 工具调用，模型对话入口在 https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_content=model_chat&utm_campaign=rewrite ，可以快速测试。

最后给一个实用技巧：把 read 工具的 description 单独存一份，每次修改 OpenCode 配置后，用diff对比实际加载的版本和你的版本。如果发现不一致，说明配置没有生效，需要检查加载顺序或重启 OpenCode。这个习惯能帮你省下大量排查时间。