如何用 headroom wrap opencode 一条命令把 OpenCode 流量接入 Headroom 代理

如何用 headroom wrap opencode 一条命令把 OpenCode 流量接入 Headroom 代理

【免费下载链接】headroom Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server. 项目地址: https://gitcode.com/GitHub_Trending/head/headroom

如果你已经在用 OpenCode，希望它发出的每次 LLM 请求都先经过 Headroom 压缩再转发给上游模型，那么 headroom wrap opencode 就是官方提供的接入方式：一条命令启动（或复用）Headroom 代理、改写 OpenCode 配置、注册 MCP 工具，并以生成的配置拉起 OpenCode。整个过程无需手动编辑 OpenCode 配置文件。

准备条件

wrap 命令由 Headroom 的 Python 包提供，OpenCode 本身也需要已经安装：

1. 安装 headroom CLI。Headroom 要求 Python 3.10+，推荐用 uv 装一个独立环境（安装文档）：

uv tool install --python 3.13 "headroom-ai[all]"
headroom --version

2. 确认 opencode 可执行文件在 PATH 中。wrap 在任何配置改动之前都会先做这个检查，找不到时会直接报错退出：

Error: 'opencode' not found in PATH.
Install OpenCode: https://opencode.ai

3. 配置上游模型 API key。代理默认 --backend anthropic，对应环境变量见安装文档：ANTHROPIC_API_KEY（代理到 Anthropic 时使用）、OPENAI_API_KEY（代理到 OpenAI 时使用）。你打算用哪家上游模型，就配置对应的 key。

执行 wrap：一条命令接入

headroom wrap opencode

这条命令完成后，OpenCode 就以 Headroom 生成的配置启动了。它实际做了这些事（官方集成文档）：

生成的 headroom provider 通过代理暴露这些模型，默认模型是 headroom/claude-sonnet-4-6，可在 opencode.json 或生成的 OPENCODE_CONFIG_CONTENT 中修改：

常用选项

按需追加参数，完整列表见集成文档：

headroom wrap opencode \
  --port 8787 \
  --no-mcp \
  --no-serena \
  --code-graph \
  --no-proxy \
  --learn \
  --memory \
  --backend anthropic \
  --anyllm-provider ... \
  --region ... \
  -- <opencode args>

• --port 8787：指定代理端口，用于避免端口冲突；
• --no-mcp / --no-serena：跳过对应 MCP 注册；
• --no-proxy：不启动代理（例如代理已在别处运行时）；
• --backend anyllm --anyllm-provider groq：切换后端，示例来自命令帮助文本；
• -- 之后的参数原样透传给 OpenCode，例如 headroom wrap opencode -- "fix the bug"。

验证流量确实走了代理

1. 看 wrap 的输出：命令会打印它设置的环境变量，其中关键是 OPENCODE_CONFIG_CONTENT（文档示例为 OPENCODE_CONFIG_CONTENT={provider: headroom}）。确认它包含 provider.headroom 块，说明 OpenCode 会按这个配置路由。
2. 打开节省看板：代理运行时提供实时节省看板（安装文档）：

headroom dashboard            # 打开 http://localhost:8787/dashboard

如果你在自定义端口运行代理，直接访问 http://localhost:<端口>/dashboard。在 OpenCode 中发起一次对话后，看板上出现请求记录即说明流量经过了代理。 3. 检查配置文件：wrap 会在改动前生成 opencode.json.headroom-backup，opencode.json 中应出现指向 http://127.0.0.1:<port>/v1 的 headroom provider。

结束时用 unwrap 还原

headroom unwrap opencode

unwrap 的行为（集成文档）：

• 若存在 wrap 前备份 opencode.json.headroom-backup，原文件按字节恢复，备份删除；
• 若无备份但配置里还有 Headroom 管理的标记块，则只移除该块、保留其余内容；若文件只有 Headroom 写入的内容，则删除整个文件，让 OpenCode 回退到默认配置；
• 同时从 OpenCode 中注销 Headroom MCP server（及 Headroom 安装的 Serena MCP）；
• 停止本地 Headroom 代理（加 --no-stop-proxy 可保留代理）。

如果之后还想让 Headroom 长期接管 OpenCode 而不是每次 wrap，可以用持久化安装（可选分支）：

headroom install apply --preset persistent-service --scope provider --providers manual --target opencode

该命令把 Headroom provider 直接写入 ~/.config/opencode/opencode.json，并让代理常驻 8787 端口。注意 OpenCode 要直接改写 provider 配置必须用 --scope provider，默认 user scope 只写 shell 环境配置。

常见问题排查

以下判断和解决方法均来自集成文档的 Troubleshooting 一节：

OpenCode 没有走 headroom provider。 检查 OPENCODE_CONFIG_CONTENT 是否已设置且包含 provider.headroom 块；wrap 命令会打印它设置的所有环境变量，对照即可。

代理端口冲突。 用 --port 指定一个具体端口，或者不指定让代理自动选择可用端口（选择到其他端口时，wrap 会把 provider 配置和 MCP 配置同步更新到实际端口）。

原生插件连不上 Headroom。 如果你用的是 headroom-opencode 包的 HeadroomPlugin（进程内拦截，与 wrap 是两条独立路径），把 HEADROOM_PROXY_URL 设置为正在运行的代理地址，例如 http://127.0.0.1:8787。

unwrap 后 provider 仍然存在。 再跑一次 headroom unwrap opencode；仍不生效时从 ~/.config/opencode/opencode.json.headroom-backup 手动恢复。

两条路径怎么选：想让 CLI 统一管理代理、配置注入、MCP 注册、备份和卸载，用 headroom wrap opencode；想让 OpenCode 在进程内直接拦截 provider 流量，用原生插件。不要在同一次接入里混用两者。

【免费下载链接】headroom Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server. 项目地址: https://gitcode.com/GitHub_Trending/head/headroom