【Agent】【OpenCode】bash 工具提示词（HEREDOC）配置 TaoToken 统一 Key 通道

1. OpenCode Agent 的 bash 工具提示词为什么绕不开 HEREDOC如果你正在用 OpenCode 这类本地 Agent 跑自动化任务大概率遇到过这种场景让 Agent 帮你整理一次 PR 描述结果它把多行 Markdown 塞进gh pr create --body的时候换行全丢了引号被 shell 吃掉最后 PR 正文变成一坨。这不是模型笨而是 bash 工具提示词里没把 HEREDOC 讲清楚。OpenCode 的 bash 工具本质上是给 Agent 一个受控的 shell 执行入口。它允许模型调用git、gh、ls这类命令但必须通过提示词约束边界哪些命令能跑、哪些不能跑、多行文本怎么传。HEREDOCHere Document就是解决多行文本传递的关键语法。它的作用可以理解成一个“原样包裹”从EOF开始到EOF结束中间所有换行、引号、$符号都保持原样shell 不做变量替换和转义解析。我试过在 Agent 里直接拼--body 第一行\n第二行短文本还行一旦超过三行转义反斜杠就开始打架。换成 HEREDOC 之后PR 描述、commit message、issue 评论这类长文本基本一次过。这篇就围绕 OpenCode 的 bash 工具提示词配置结合 TaoToken 统一 Key 通道把config.toml和settings.json的可复制骨架给出来再演示一次gh命令的 HEREDOC 调用与验证。适合谁看正在本地跑 OpenCode Agent、想让 Agent 安全执行 bash 命令、又不想在多个模型供应商之间反复换 Key 的开发者。核心检索词就三个OpenCode bash 工具提示词、HEREDOC 用法、TaoToken 统一 Key 通道。2. 前置准备TaoToken 统一 Key 通道与 OpenCode 的关系OpenCode 本身是一个 Agent 运行框架它需要调用大模型来完成推理和工具调用决策。默认情况下你可能会在配置里填某个供应商的 base_url 和 api_key。问题是当你同时用 Claude、GPT、Gemini 做不同任务时Key 管理会变得很碎。TaoToken 在这里的角色是一个统一的 API 通道。你只需要在 TaoToken 控制台创建一个 API Key然后把 OpenCode 的模型请求指向 TaoToken 的 API 地址就能用同一个 Key 访问多个模型。官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 注意 API 地址后面不加 UTM 参数。具体操作路径先到 TaoToken 控制台创建 API Key地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite如果你需要看模型列表和对话测试用模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite如果你打算长期跑编码 Agent建议了解 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewriteAPI Key 管理页在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite接入文档参考 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite拿到 Key 之后OpenCode 的配置分两块一块是模型通道配置config.toml一块是 Agent 工具权限配置settings.json。下面直接给可复制骨架。注意不要把 API Key 硬编码到会提交到 Git 的文件里。建议用环境变量注入配置文件里只写变量引用。3. 可复制配置config.toml 与 settings.json 骨架3.1 config.toml 模型通道配置OpenCode 的config.toml一般放在项目根目录或用户配置目录。下面这份骨架把模型请求指向 TaoToken 的 API 地址Key 从环境变量读取。# config.toml # OpenCode 模型通道配置统一走 TaoToken API [provider] name taotoken base_url https://taotoken.net/api api_key_env TAOTOKEN_API_KEY [model] # 按你实际需要的模型名填写TaoToken 控制台可查 default claude-sonnet-4-20250514 fallback gpt-4o [agent] # Agent 运行参数 max_tokens 8192 temperature 0.2 timeout_seconds 120 [tools.bash] enabled true # 允许的命令白名单按需增删 allow [git, gh, ls, cat, grep, find, echo] # 禁止交互式命令 deny_flags [-i, --interactive]环境变量这样设置export TAOTOKEN_API_KEY你的_TaoToken_API_Key如果你用的是 Windows PowerShell$env:TAOTOKEN_API_KEY你的_TaoToken_API_Key3.2 settings.json 工具提示词与权限配置settings.json负责约束 Agent 的行为边界包括 bash 工具提示词、HEREDOC 要求、PR 创建流程等。下面这份骨架可以直接改。{ agent: { name: opencode-bash-agent, system_prompt_file: ./prompts/bash_tool.md }, tools: { bash: { enabled: true, require_heredoc_for_multiline: true, forbidden_tools: [TodoWrite, Task], forbidden_commands: [git push --force, rm -rf, curl | sh], require_confirmation: [git push, gh pr create] }, git: { allow_direct_git: false, prefer_gh_for_github: true } }, pr: { require_heredoc_body: true, collect_all_commits_since_fork: true, parallel_info_gathering: true, return_pr_url_to_user: true } }3.3 bash 工具提示词文件prompts/bash_tool.md是给模型看的提示词重点写清楚 HEREDOC 的使用规则。下面这段可以直接用。# Bash 工具使用规则 你只能执行白名单内的命令git、gh、ls、cat、grep、find、echo。 ## 多行文本必须使用 HEREDOC 当需要传递多行文本如 PR 描述、commit message、issue 评论时 必须使用 HEREDOC 格式禁止用 \n 拼接。 正确写法 gh pr create --title 标题 --body $(cat EOF ## Summary - 修复了 xxx - 新增了 yyy ## Test - 本地跑通单元测试 EOF ) 错误写法 gh pr create --body ## Summary\n- 修复了 xxx\n- 新增了 yyy ## GitHub 操作规则 1. 与 GitHub 相关的操作优先用 gh 命令不要直接用 git 操作远端。 2. 创建 PR 前必须分析从主分支分叉以来的所有提交不能只看最新一次。 3. 条件允许时并行收集信息提升效率。 4. 创建 PR 后把生成的 PR URL 返回给用户。 5. 禁止使用 TodoWrite 或 Task 等内部工具。 6. 禁止交互式命令带 -i 选项。 7. 没有改动不要硬提交。这份提示词的核心就是把 HEREDOC 从“可选技巧”变成“强制规则”。模型在生成 bash 调用时会优先按提示词里的正确写法来。4. 验证请求一次 gh 命令的 HEREDOC 调用与结果确认配置写完之后必须验证 Agent 是否真的按 HEREDOC 格式执行。下面用一个最小可复现的gh命令来测。4.1 准备一个测试仓库mkdir -p /tmp/opencode-heredoc-test cd /tmp/opencode-heredoc-test git init git checkout -b feature/heredoc-demo echo # demo README.md git add README.md git commit -m init demo4.2 用 HEREDOC 创建 PR 描述文件先不直接调gh pr create而是用 HEREDOC 生成一个 body 文件确认内容原样保留。cat EOF /tmp/pr_body.md ## Summary - 新增 README 初始化文件 - 验证 HEREDOC 多行传递 ## Changes - README.md: 添加标题 ## Test - 本地 git status 干净 EOF查看结果cat /tmp/pr_body.md预期输出就是上面那段 Markdown换行、##、-全部保留没有被 shell 解析。4.3 模拟 Agent 调用 gh 命令如果你有真实的 GitHub 仓库和gh登录态可以这样调gh pr create \ --title feat: HEREDOC demo \ --body $(cat EOF ## Summary - 新增 README 初始化文件 - 验证 HEREDOC 多行传递 ## Test - 本地 git status 干净 EOF )执行成功后会返回一个 PR URL类似https://github.com/yourname/yourrepo/pull/14.4 验证 Agent 是否遵守提示词在 OpenCode 里发一条指令帮我基于当前分支创建一个 PR描述里包含 Summary 和 Test 两部分。观察 Agent 生成的 bash 调用。如果配置生效你应该看到它使用EOF而不是\n拼接。如果它还是用\n说明require_heredoc_for_multiline没生效或者提示词文件没被加载。提示可以在 OpenCode 的日志里搜索heredoc关键字确认提示词是否注入成功。5. 本篇常见错排查5.1 HEREDOC 结束标记不生效最常见的原因是结束标记EOF前面有空格或 Tab。HEREDOC 要求结束标记必须顶格写前后不能有空格。错误cat EOF file.txt content EOF正确cat EOF file.txt content EOF5.2 变量被意外替换如果你用EOF而不是EOF里面的$变量会被 shell 替换。PR 描述里如果有$符号就会出问题。所以提示词里强制用单引号包裹EOF。5.3 Agent 仍然调用 TodoWrite 或 Task检查settings.json里的forbidden_tools是否包含这两个。有些 OpenCode 版本的工具名大小写敏感确认写的是TodoWrite和Task不是小写。5.4 gh 命令报权限错误先确认gh auth status是登录状态。如果没登录跑gh auth login按提示走。注意不要用交互式命令让 Agent 去跑登录操作手动完成。5.5 TaoToken API 返回 401检查环境变量TAOTOKEN_API_KEY是否真的注入到了 OpenCode 进程。可以在启动 OpenCode 前echo $TAOTOKEN_API_KEY确认。如果用的是 systemd 或 Docker环境变量可能没传进去。5.6 模型名写错导致 404TaoToken 的模型名以控制台展示为准。如果你填了不存在的模型名API 会返回 404 或 model not found。到模型对话页面确认可用模型名再回填到config.toml。5.7 PR 描述只包含最新一次提交这是提示词里collect_all_commits_since_fork没强调到位。在prompts/bash_tool.md里明确写必须用git log main..HEAD --oneline收集分叉以来的所有提交不能只看git log -1。6. 接入与排障后的下一步配置和验证跑通之后日常使用中最容易出问题的还是 Key 管理和模型切换。如果你在多个项目里用 OpenCode建议统一走 TaoToken 的 API Key避免每个项目配一套供应商凭证。API Key 管理入口在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 遇到 401 或模型名报错先翻这两处。如果你主要是验证模型输出是否符合预期可以用模型对话页面快速测一条 HEREDOC 相关的 prompt地址是 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。长期跑编码 Agent 的话Coding Plan 页面 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 有更详细的配额和模型说明。最后留一个实操建议把prompts/bash_tool.md纳入版本管理每次 Agent 行为异常时先 diff 这个文件再查settings.json。大部分 HEREDOC 相关的问题都是提示词里少写了一句“必须用单引号 EOF”。