OpenCode 使用 GitHub Copilot 计费机制分析与优化方案

发布时间：2026 年 1 月 21 日

什么是 Subagent？

OpenCode 有一个强大的功能：子任务代理 (Subagent)

当你让 AI 完成复杂任务时，它可以自动创建子任务：

• 主任务（你发起）：分析项目结构
• 创建子任务 1：重构模块 A (@general) ← Subagent
• 创建子任务 2：重构模块 B (@general) ← Subagent
• 创建子任务 3：更新文档 (@general) ← Subagent

修复原理：添加 x-initiator: agent 标记

官方的修复非常巧妙，采用了 GitHub Copilot 认可的标准机制：

// 检查是否是 subagent session（有父任务）
if(session.parentID){
  // 添加特殊 header，标记为 AI 自动发起
  headers["x-initiator"]="agent"
}

这与 VS Code 的机制一致：

• VS Code：在 API 层面使用 requestInitiator 参数标识请求来源
• OpenCode：在 HTTP 请求中添加 x-initiator: agent header
• 两者都是 GitHub Copilot 官方支持的标记方式

修复效果：

• 主任务（用户发起）：正常计费
• 主任务的循环（修复前）：每次循环都计费
• 主任务的循环（修复后）：仍然计费（因为没有 parentID）
• 子任务（有 parentID）：全部不计费
• 子任务中的所有 LLM 调用：不计费

注意：修复主要针对 Subagent 功能，主任务的循环仍会计费！

成本对比

修复前：

• 主任务：1 次计费
• 子任务 1: 5 次 LLM 调用 → 计费 5 次
• 子任务 2: 3 次 LLM 调用 → 计费 3 次
• 子任务 3: 2 次 LLM 调用 → 计费 2 次
• 总计：11 次计费

修复后：

• 主任务：1 次计费
• 子任务 1: 5 次 LLM 调用 → 不计费
• 子任务 2: 3 次 LLM 调用 → 不计费
• 子任务 3: 2 次 LLM 调用 → 不计费
• 总计：1 次计费（节省 90%！）

解决方案

立即升级到 v1.1.31+

# 检查当前版本
opencode --version
# 升级到最新版本
npm update opencode-ai@latest
# 或
brew upgrade opencode

充分利用 Subagent 功能

升级后，可以放心使用 @general 等 subagent：

# 推荐：让 AI 自动拆分子任务
opencode run "重构整个项目，使用 @general 分析最佳实践"
# 效果：
# - 主任务分析需求（计费 1 次）
# - 创建多个 subagent 子任务（不计费）
# - 所有子任务的工作（不计费）

关键原则：尽量让 AI 自己创建子任务，而不是在主任务中做所有事情。

方法 1：使用 @ 语法手动委托

# ❌ 避免：在主任务中执行多步骤操作
你：帮我重构 src 目录下的所有文件
# ✅ 推荐：让 AI 创建 subagent 处理
你：帮我重构 src 目录，使用 @general 分析并逐个文件处理

内置 Subagent：

• @general：通用多步骤任务（推荐用于复杂重构）
• @explore：代码探索和分析（只读，不会修改代码）

方法 2：让 AI 自动判断并委托

# 添加提示词，引导 AI 使用 subagent
你：帮我重构这个项目。如果任务复杂，请使用 @general 创建子任务

OpenCode 会自动识别：

• 如果任务需要多个步骤
• AI 会自动调用 task 工具创建 subagent

方法 3：通过配置强制使用 Subagent

// opencode.json
{
  "command": {
    "refactor": {
      "template": "重构 {input}，使用最佳实践",
      "subtask": true, // 强制作为子任务执行
      "agent": "general"
    }
  }
}

使用方式：

opencode /refactor src/utils/ # 自动创建 subagent，不计费

方法 4：创建自定义 Subagent

支持两种配置格式：

格式 1：JSON 配置 (推荐用于简单配置)

// opencode.json
{
  "agent": {
    "reviewer": {
      "mode": "subagent",
      "model": "anthropic/claude-sonnet-4-20250514",
      "description": "专门用于代码审查的子代理",
      "prompt": "你是一个专业的代码审查专家...",
      "steps": 50 // 子代理内部最多 50 步（不计费）
    }
  }
}

格式 2：Markdown 配置 (推荐用于复杂 prompt)

<!-- .opencode/agent/reviewer.md -->
---
mode: subagent
model: anthropic/claude-sonnet-4-20250514
description: 专门用于代码审查的子代理
steps: 50
---
你是一个专业的代码审查专家。审查代码时：
1. 检查潜在的 bug
2. 提出性能优化建议
3. 评估代码可读性

使用方式：

你：使用 @reviewer 审查这个文件 # 自动作为 subagent 执行，不计费

关键字段说明：steps vs maxSteps

重要：OpenCode 配置中：

• ✅ steps：正确字段（OpenCode v1.1+ 推荐）
• ❌ maxSteps：已弃用字段（仅为向后兼容保留）

// ✅ 正确写法
{
  "agent": {
    "build": {
      "steps": 10 // 限制最多 10 个循环步骤
    }
  }
}
// ⚠️ 旧写法（仍可用，但不推荐）
{
  "agent": {
    "build": {
      "maxSteps": 10 // 会自动转换为 steps
    }
  }
}

注意：如果同时配置了 steps 和 maxSteps，OpenCode 会优先使用 steps 值。

调整主任务配置（辅助策略）

如果确实需要在主任务中操作，可以通过配置减少循环次数：

// opencode.json
{
  "agent": {
    "build": {
      "steps": 10 // 限制最多 10 轮循环
    }
  },
  "permission": {
    "read": "allow", // 读取文件自动允许
    "glob": "allow", // 搜索文件自动允许
    "edit": "ask", // 修改文件需确认（重要！）
    "bash": "ask", // 执行命令需确认
    "task": "allow" // 自动允许创建 subagent（推荐！）
  }
}

关键配置说明：

• maxSteps: 防止无限循环
• edit: "ask": 可以在关键步骤拒绝，提前结束循环
• task: "allow": 非常重要，允许 AI 自动创建 subagent

总结与建议

关键要点

1. 理解架构差异是关键
   • VS Code：流式连接，1 次对话 = 1 次计费
   • OpenCode：循环架构，每次循环 = 1 次计费
   • Subagent 是 OpenCode 的成本优化利器
2. v1.1.31 带来的变化
   • Subagent 功能完全免费（有 parentID 的 session），充分利用时成本节省高达 90%
   • 主任务的循环仍然计费（这是架构特性）
3. Provider 选择建议
   • GitHub Copilot（按次）：适合复杂长任务，会消耗大量 token 的任务。
   • 其他按 Token 计费的：适合短任务，token 消耗可控的任务。

附：计费说明

1. GitHub Copilot 计费规则

2. 其他提供商（按 Token 计费）

对于 OpenAI、Anthropic 等按 Token 计费的提供商：

示例：Tool Calls 占 88.9% 的请求

假设总共 10,000 tokens：

结论：工具调用越多，成本越高！

3. 成本对比总结

同样的任务（含 3 个子任务）：

参考资料

• OpenCode GitHub 仓库
• v1.1.31 Release Notes
• GitHub Copilot 计费文档