★ FEATURED ARTICLE 1. OpenCode Agent 的 bash 工具提示词到底在解决什么问题如果你正在用 OpenCode 这类终端里的编码 Agent大概率遇到过这种场景让它帮你跑个构建它上来就是cd /Users/you/project npm run build结果目录里带空格直接炸了或者它用cat读一个几千行的日志把上下文窗口塞满后面几轮对话全在胡言乱语。这些都不是模型笨而是 bash 工具提示词没设计好。bash 工具提示词说白了就是你在 OpenCode Agent 配置里写给模型看的一段系统级说明告诉它「这个 bash 工具怎么调、什么能干什么不能干、优先用什么替代」。它和普通对话提示词最大的区别是它直接约束工具调用的参数结构和执行边界。写得好Agent 执行 shell 命令又稳又省 token写得烂轻则命令报错重则误删文件。这篇面向的是需要让 Agent 安全高效执行 shell 命令的开发者尤其是已经在用 OpenCode、Cline、Claude Code 这类工具想让 bash 调用行为可预期的人。我会给出可直接复制的提示词模板、OpenCode 的配置文件片段以及通过 TaoToken 统一 Key/API 通道接入后的验证步骤。核心检索词就三个OpenCode bash 工具提示词、Agent 专用工具、shell 命令安全执行。先说清楚一个前提OpenCode 的 bash 工具本身有一套底层框架它在调用系统 API 时会自己切换工作目录所以提示词里要明确禁止模型自己拼cd xxx command。原因有四条我在实际调优时反复验证过第一规避逻辑陷阱。模型拼cd a cd b cmd只要中间一个目录不存在整条链就断了而且它自己往往意识不到失败发生在哪一步。第二防命令注入。路径里带特殊字符空格、;、$()时模型自由拼接极容易触发注入漏洞。你让它处理一个用户上传的、名字叫my file; rm -rf ~.txt的文件它要是不加引号直接拼后果自己脑补。第三强制规范化。明确让框架填工作目录系统日志里每条命令的 cwd 都清清楚楚出问题排查快得多。第四方便调试。日志里能看到「这条命令是在哪个目录跑的」而不是靠模型自己复述。理解了这四点你写提示词时就有了主心骨所有涉及目录切换、路径拼接的地方都要用「禁止 替代方案」的句式写死。再补一个容易被忽略的点输出量控制。OpenCode 的 bash 工具在输出超过${maxLines}或${maxBytes}时不会把全部内容塞进对话而是自动存到临时文件只给模型看前面一小段。所以提示词里要明确告诉模型不要用head、tail、sed -n去截断输出完整内容框架会保存需要时用 read 工具配合 offset/limit 读或者用 grep 搜。这一点如果没写模型会习惯性地加| head -50反而让框架的临时文件机制白费。2. TaoToken 前置统一 Key 与 API 通道怎么准备在写提示词之前得先把模型通道打通。OpenCode 支持自定义 OpenAI 兼容的 Base URL所以你可以把请求指向 TaoToken 的统一入口用一个 Key 管理多个模型省得每个模型配一套环境变量。TaoToken 在这里扮演的角色是「统一 Key/API 通道」你注册后拿到一个 API Key所有模型调用都走同一个 Base URL切换模型只改 Model ID不用重新配鉴权。对 OpenCode 这种需要频繁切换模型做对比测试的场景特别省事。准备工作分三步。第一步拿 Key。访问 https://taotoken.net/api-keys 创建你的 API Key复制保存好后面配置里要用。注意这个 Key 只在创建时完整显示一次丢了就重新建。第二步确认 Base URL。OpenCode 走 OpenAI 兼容协议Base URL 填https://taotoken.net/api注意这里不加任何 UTM 参数就是纯 API 地址。模型对话相关的调试可以在 https://taotoken.net/models 里先试确认模型能正常响应再往 OpenCode 里配。第三步选模型。OpenCode 里 bash 工具提示词的效果和模型能力关系很大。实测下来Claude 系列在工具调用参数结构上更稳GPT 系列在长命令拼接上偶尔会偷懒。你可以先用一个模型跑通再换另一个对比。如果你打算长期跑编码 AgentCoding Plan 的额度模型更适合高频调用地址是 https://taotoken.net/coding-plan。这里要提醒一句TaoToken 是 API 通道不是编辑器替代品。OpenCode 负责本地文件读写和命令执行TaoToken 负责把模型请求转发出去两者职责分开别混为一谈。配置 OpenCode 时环境变量建议这样设Linux/Macexport OPENAI_API_KEYsk-你的TaoTokenKey export OPENAI_BASE_URLhttps://taotoken.net/apiWindows PowerShell$env:OPENAI_API_KEYsk-你的TaoTokenKey $env:OPENAI_BASE_URLhttps://taotoken.net/api设完可以用一条 curl 验证通道是否通curl https://taotoken.net/api/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY返回模型列表就说明 Key 和 Base URL 都对。如果返回 401先检查 Key 有没有多余空格如果返回连接错误检查 Base URL 是不是写成了带路径的完整地址。通道打通后OpenCode 里所有模型请求都会经过 TaoToken你在提示词里写的 bash 工具约束才会真正作用到模型输出上。这一步没做好后面提示词调优都是空中楼阁。3. 可复制的 bash 工具提示词模板与 OpenCode 配置片段这一节是重点直接给可复制的内容。先给提示词模板再给 OpenCode 的配置文件片段路径和字段名保持和实际一致。提示词模板我按「工具说明 参数约束 专用工具优先 输出处理」四块组织你可以整段贴进 OpenCode 的 system prompt 或工具描述里## bash 工具使用规范 你有一个 bash 工具用于执行 shell 命令。调用时必须遵守以下规则 ### 参数约束 - command必填要执行的命令不能为空。 - timeout可选最长运行时间单位毫秒默认 1200002 分钟。超时会被强制终止。 - description建议用 5~10 个单词描述这条命令做什么例如 Install project dependencies方便日志排查。 ### 目录与路径 - 禁止使用 cd xxx command 形式。工作目录由框架在调用系统 API 时切换你只需给出命令本身。 - 路径中包含空格时必须用双引号包裹例如 ls my folder。 - 创建文件或文件夹前先用 ls 检查父级目录是否存在不要直接执行创建命令。 ### 专用工具优先 除非用户明确要求使用某个 bash 命令或确实没有专用工具能完成否则优先使用以下 OpenCode 内置工具 - 找文件用 Glob不要用 find / ls - 搜内容用 Grep不要用 grep / rg - 读文件用 Read不要用 cat / head / tail - 改文件用 Edit不要用 sed / awk - 写文件用 Write不要用 echo / cat EOF - 输出文本直接输出不要用 echo / printf ### 输出处理 - 不要用 head、tail 或其他命令限制输出行数。 - 输出超过 maxLines 或 maxBytes 时框架会自动保存完整内容到临时文件并展示前面一小段。 - 需要查看完整内容时用 Read 工具配合 offset/limit 参数或用 Grep 搜索。这段模板的关键在于「禁止 替代」成对出现。只写「禁止 cd」模型可能换个写法绕过去配上「工作目录由框架切换」它才知道正确做法。接下来是 OpenCode 的配置文件片段。OpenCode 的配置一般放在项目根目录或用户配置目录字段名以实际版本为准下面给的是通用结构{ model: claude-sonnet-4-20250514, provider: { openai: { baseURL: https://taotoken.net/api, apiKey: env:OPENAI_API_KEY } }, tools: { bash: { enabled: true, timeout: 120000, maxLines: 500, maxBytes: 51200, prompt: 见上方 bash 工具使用规范全文 } } }如果你用的是 TOML 格式的配置部分 OpenCode 版本支持等价写法model claude-sonnet-4-20250514 [provider.openai] baseURL https://taotoken.net/api apiKey env:OPENAI_API_KEY [tools.bash] enabled true timeout 120000 maxLines 500 maxBytes 51200这里三个字段必须成对出现缺一不可Base URL 填https://taotoken.net/apiKey 走环境变量OPENAI_API_KEYModel ID 填你实际要用的模型名。这就是所谓的「三件套」任何一处写错工具调用都会失败。maxLines和maxBytes建议不要设太大。设成 500 行 / 50KB 左右既能保证模型看到足够上下文又不会把窗口撑爆。设太大等于没设设太小模型频繁读临时文件也费 token。配置改完记得重启 OpenCode让它重新加载。有些版本支持热重载但保险起见还是重启。4. 验证请求与成功结果从一次真实 bash 调用看行为是否符合预期配置写完不算完得验证模型真的按提示词执行。我一般用三个测试用例覆盖目录、路径、专用工具三个维度。测试一目录切换。给模型一个任务「在项目根目录列出所有 TypeScript 文件」。如果提示词生效它应该调用 Glob 而不是cd xxx find . -name *.ts。观察 OpenCode 的日志看它实际调用的工具名和参数。测试二带空格路径。造一个目录test folder让模型「读取 test folder 下的 config.json」。正确行为是用 Read 工具路径参数带引号或框架自动处理错误行为是拼cat test folder/config.json然后报错。测试三长输出。跑一个会输出几千行的命令比如npm install --verbose。正确行为是模型不加| head框架自动截断并提示临时文件路径错误行为是模型自己加| tail -20。验证时可以直接在 OpenCode 里发指令然后看它的工具调用记录。下面是一个成功调用的日志片段示意[tool] Glob pattern: **/*.ts path: . [tool] Read filePath: test folder/config.json offset: 0 limit: 100 [tool] bash command: npm run build description: Build project timeout: 120000 result: Build succeeded in 8.3s看到 Glob、Read 被优先调用bash 只在真正需要时出现且 command 里没有cd说明提示词生效了。再验证一下 TaoToken 通道。在 OpenCode 里发一条需要模型推理的指令比如「解释这个项目的构建流程」然后看请求是否正常返回。如果返回内容完整、没有中断说明 Base URL 和 Key 都对。你也可以在 TaoToken 的模型对话页面 https://taotoken.net/models 里用同样的 prompt 对比输出确认模型行为一致。成功结果有三个标志一是工具调用参数结构正确没有多余字段二是 bash 命令里没有cd和路径拼接三是长输出场景下模型没有自己截断。三条都满足说明你的提示词和配置都到位了。如果模型偶尔还是会拼cd别急着改提示词先看是不是模型能力问题。换个模型再测如果换了就好那就是模型对工具描述的理解差异不是提示词写错。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth调优过程中踩的坑基本集中在四类报错逐个说。401 Unauthorized。最常见九成是 Key 问题。检查三处环境变量OPENAI_API_KEY有没有设、值有没有多余空格或换行、Key 有没有过期。用前面那条 curl 命令单独测curl 通了说明 Key 没问题那就是 OpenCode 读取环境变量的方式不对。有些版本要求 Key 写在配置文件里而不是环境变量看你的版本。local proxy failed。这个报错通常出现在 Base URL 写错或网络不通时。先确认 Base URL 是https://taotoken.net/api不要多加/v1或结尾斜杠。然后确认本机能不能访问这个地址用 curl 测。如果 curl 通但 OpenCode 报这个错检查 OpenCode 有没有配置自己的代理设置把代理关掉再试。reading choices 相关报错。一般是响应结构不符合 OpenAI 兼容格式或者模型返回了空 choices。先确认 Model ID 写对了模型名错会导致返回异常结构。再确认 TaoToken 通道返回的是标准 OpenAI 格式。如果换了模型就好说明是特定模型的问题。OAuth 相关报错。OpenCode 某些版本支持 OAuth 登录如果你同时配了 OAuth 和 API Key可能冲突。解决办法是二选一要么用 API Key 走 TaoToken要么用 OAuth别混用。用 API Key 时把 OAuth 相关配置注释掉。排查顺序建议先 curl 测通道再测 OpenCode 单模型再测工具调用。一层层排除别一上来就改提示词。另外提醒一个隐蔽的坑maxLines设成 0 或负数有些版本会当成「不限制」结果长输出直接把上下文撑爆。设成正整数500 左右比较稳。还有一个提示词里写了「禁止 cd」但模型在 description 字段里写了「cd to project and build」这不影响执行只是描述文字不用管。真正要看的是 command 字段。6. 语义一致的 CTA把通道和工具链固定下来提示词调好之后建议把配置固化到项目里别每次手动设环境变量。可以把 Base URL 和 Model ID 写进 OpenCode 的项目配置Key 继续走环境变量这样团队协作时别人 clone 下来只要设自己的 Key 就能跑。如果你还在对比不同模型对 bash 工具提示词的遵循度可以先用模型对话页面快速试https://taotoken.net/models同一个 prompt 换模型跑看哪个工具调用最规范。确定模型后再往 OpenCode 里配。长期跑编码 Agent 的话Coding Plan 的额度更适合高频工具调用场景地址 https://taotoken.net/coding-plan比按次调用省心。接入文档在 https://taotoken.net/doc里面有 OpenAI 兼容协议的完整字段说明配 OpenCode 时对着看不会错。最后给一个实用技巧把 bash 工具提示词单独存成一个文件比如prompts/bash-tool.md在 OpenCode 配置里用文件引用而不是内联字符串。这样改提示词不用动配置文件版本管理也清楚。我试过把提示词拆成「通用规范」和「项目特定规则」两个文件项目规则里写这个项目特有的构建命令、测试命令通用规范保持不变维护起来轻松很多。配置和提示词都固定下来后你的 OpenCode Agent 执行 shell 命令的行为就基本可预期了该用专用工具的地方不会去调 bash该调 bash 的地方不会乱拼 cd长输出不会撑爆上下文。剩下的就是根据实际项目微调 maxLines 和 timeout 这两个数值找到适合你工作流的平衡点。
阅读完成 · 觉得有帮助？
