在 OpenCode 里用 Claude 订阅:来龙去脉与源码实现

By 陈成 · Published October 31, 2026

OpenCode 怎么接入 Claude 订阅,源码如何实现,合规上稳不稳?

调研时间 2026-10-31。源码基于 OpenCode v2.2.5,commit 4878a0e30f。

结论

OpenCode 这次没有恢复 3 月被下架的 OAuth 方案,而是换了一条路。

合规上有一个没闭合的口子。“Anthropic 同意了”目前只有 OpenCode 一方的说法,我没找到 Anthropic 的公开确认。详见合规一节。

怎么用

# 需要 Claude Code 2.1.248 或更高版本
claude auth login
# 然后在 OpenCode 里
/connect   # 选 Claude Agent
/models

CLI 也可以用 auth login claude-agent。claude 不在 PATH 时,用 OPENCODE_CLAUDE_PATH 指定路径。见 v2 文档源文件。

时间线

timeline
    title OpenCode 与 Claude 订阅
    2025-06 : OpenCode 加入 Claude OAuth 登录
    2026-01 : 有人复现 Anthropic 拦截含 opencode 字样的系统提示 : 文档加上不受官方支持的警告
    2026-02 : Anthropic 条款写明订阅 OAuth 不能用于第三方工具和 Agent SDK
    2026-03 : OpenCode 收到法务要求,删除内置插件
    2026-06 : Anthropic 暂停 SDK 用量改走单独额度的计划
    2026-10 : v2.2.3 发布 Claude Agent provider
日期(UTC) 事件 来源
2025-06-05 加入 Claude OAuth。OpenCode 自己走 PKCE,把 token 写进本地 anthropic.json 35b03e4cb3
2026-01-15 Ryan Vogel 称 Anthropic 拦截了含 “opencode” 字样的次级系统提示,属个人复现 推文
2026-01-20 文档加订阅警告 7f50b27996
2026-02-18 条款明确后,Numman Ali 总结为 OpenClaw、Pi、OpenCode、Agent SDK 都不被授权 推文
2026-02-19 出现名为 “anthropic legal requests” 的提交,r/ClaudeAI 当成下架消息讨论(331 分)。这个提交只在侧分支上,当时没进主干 973715f3da、Reddit
2026-03-15 Matt Pocock 公开问 Anthropic,能否在本地开发里用订阅 token 跑 Agent SDK。这条在你的书签里 推文
2026-03-19 主干合入同名提交,删掉 opencode-anthropic-auth@0.0.13、anthropic-20250930.txt 提示词和 claude-code-20250219 beta 头 1ac1a0287c
2026-03-19 Dax:“they sent lawyers”,1.3.0 不再自动加载插件 推文
2026-06-15 Anthropic 暂停已宣布的 SDK 用量调整,SDK、claude -p、第三方应用仍走订阅额度 支持文章
2026-10-30 03:20 Dax 预告 “what if you could use your claude subscription in opencode” 推文
2026-10-30 06:48 PR #58782 合入,增 6866 行 PR
2026-10-30 09:55 v2.2.3 发布 Release
2026-10-30 16:00 官方账号宣布,35 万多次浏览 推文

新旧方案对比

旧方案(2025-06 到 2026-03) 新方案(v2.2.3 起)
谁发 API 请求 OpenCode 本机 claude 进程
登录 OpenCode 发起 OAuth 用户在终端跑 claude auth login
token OpenCode 保存和刷新 OpenCode 拿不到
请求身份 带 Claude Code 专用的 beta 头 就是 Claude Code 发的
系统提示 专门维护的 Anthropic 提示词文件 Claude Code 官方预设,末尾追加内容
新增依赖 无 claude 二进制,版本 2.1.248 起

社区插件还在沿用旧路子。ex-machina/opencode-anthropic-auth(561 star)的代码会上报 Claude Code 的 user-agent 和版本号,README 自己也警告可能封号。这条路仍属条款禁止的范围。另一个插件 openchamber/opencode-claude 早就走 Agent SDK,现在已归档,并建议用户换内置 provider。

源码实现

代码在 packages/core/src/plugin/provider/claude-agent/,共 2360 行。设计说明见 specs/v2/claude-agent-provider.md,这份 spec 写得很细,想深入可以直接读。

flowchart LR
    subgraph OC[OpenCode 进程]
        Loop[Agent 循环 权限 历史 压缩]
        LM[ClaudeAgentLanguageModel]
        Sessions[ClaudeSessions 进程与同步]
        MCP[进程内 MCP server]
        Pending[PendingTools 挂起的 Promise]
    end
    subgraph CC[本机 claude 进程]
        SDK[Agent SDK 控制通道]
        Core[Claude Code 请求逻辑]
        Cred[Claude Code 自己的登录信息]
    end
    API[Anthropic API]
    Loop --> LM --> Sessions --> SDK --> Core
    Cred --> Core
    Core --> API
    Core -- 调用工具 --> MCP --> Pending
    Loop -- 工具结果 --> Pending

1. 接入点:伪装成一个普通模型

OpenCode 的 agent 循环只认 AI SDK 的 LanguageModelV3。ClaudeAgentLanguageModel 实现这个接口,只支持 doStream。convert-claude-stream.ts 把 SDK 消息转成 AI SDK 的 stream part,所以上层看不出差别。

index.ts#L24-L28 在不能启动本地进程的环境里直接跳过,比如远程 workspace 和托管版。

2. 登录:OpenCode 只记一个选择

integration.ts#L15-L28 注册的登录方式类型是 external,注释写明插件看不到 token。

判断是否登录靠启动探测。probe.ts 起一个 query,不发 prompt,读 initializationResult() 里的账号、版本和模型列表,再用 tokenSource 和 apiKeySource 判断(L111-L113)。模型列表也来自这里,OpenCode 不写死。

3. 启动参数:把 Claude Code 掏空

这是最值得看的 100 行,query-options.ts:

// query-options.ts#L56-L70
return {
  pathToClaudeCodeExecutable: input.executable,
  env: { ...input.io.env(), ...input.connection, ...ISOLATION_ENV },
  settingSources: [],                 // 不读 ~/.claude 和项目 .claude
  settings: { disableAllHooks: true },
  thinking: { type: "adaptive", display: "summarized" },
  strictMcpConfig: true,
  skills: [],
  tools: [],                          // 关掉所有内置工具
  permissionMode: "dontAsk",
  allowedTools: ["mcp__opencode__*"], // 只放行 OpenCode 的工具
  verbatimPrompts: true,              // 不注入每轮上下文,也不解析 /command
}

ISOLATION_ENV(L11-L26)关掉 CLAUDE.md、auto memory、自动压缩、away summary、tool search 和 advisor。tool search 必须关,因为 OpenCode 的工具全是 MCP 工具,开着会被全部隐藏。

它还清掉 3 个 shell 变量。其中 CLAUDE_CODE_SIMPLE 会跳过 OAuth,MCP_TOOL_TIMEOUT 会让长时间的权限弹窗和子 agent 超时失败。

verbatimPrompts 决定了最低版本。旧版 claude 会默默忽略这个选项,可能把用户文本当命令解析,所以 probe.ts#L21-L22 卡在 2.1.248。

4. 工具桥:一个挂起的 Promise

SDK 的消息流是单向的。OpenCode 能看到工具调用,却无法把结果推回正在运行的回合,所以必须让 Claude Code 去调一个“真实存在”的工具,并在那里等。

sequenceDiagram
    participant O as OpenCode 循环
    participant S as ClaudeSessions
    participant C as claude 进程
    participant M as MCP handler
    O->>S: doStream 发送 prompt
    S->>C: session.begin
    C-->>S: 流式返回 tool_use
    S-->>O: finish 原因为 tool-calls
    Note over O,S: 这一步结束,claude 回合没有结束
    C->>S: PreToolUse hook 带 tool_use_id
    C->>M: tools/call 不带 id
    Note over M: 取 hook 存下的 id,挂起 Promise
    O->>O: 走权限检查,执行工具
    O->>S: 下一次 doStream,prompt 里含工具结果
    S->>M: pending.resolve
    M-->>C: 返回工具结果
    C->>S: PostToolUse hook 换入 PDF 和图片
    C-->>S: 继续流式输出

对应代码:

这里有一个代价。ID 只存在一个槽位里(pending.ts 的 next),工具必须串行执行,所以 server.ts#L21-L22 把所有工具标成非只读。走这个 provider 时,Claude 的并行读文件也会变成一个接一个。

5. 系统提示:保留 Claude Code 的预设

system-prompt.ts#L9-L23 用 preset: "claude_code",追加一段运行环境说明,再加 agent 角色和 AGENTS.md、skills 等内容。它会明说自己跑在 OpenCode 里,不做身份伪装。

这也带来一个限制:OpenCode 内置的 agent 提示词不生效,自定义 agent 的提示词是追加在 Claude Code 预设后面的。标题生成例外,会整个替换成 OpenCode 的提示(utility)。

6. 两份历史的同步

OpenCode 数据库是准,但 Claude 只能续自己写过的 session,所以每次请求前要比对。sync/decide.ts 按消息组的 hash 判断走哪条路:

flowchart TD
    A[新请求] --> B{有保存的 Claude 历史吗}
    B -- 没有 --> F[fresh 新建 session 发全部历史]
    B -- 有 --> C{第一组 hash 对得上吗}
    C -- 对不上 --> F
    C -- 对得上 --> D{已存历史全部匹配吗}
    D -- 否,编辑或撤销过 --> E[changed 在最后匹配点 fork]
    D -- 是 --> G{漏掉的内容里有非用户消息吗}
    G -- 有,中间切过模型 --> H[catch-up 用 conversation-checkpoint 补发]
    G -- 没有 --> I[continue 直接续]

切到其他模型再切回来时,漏掉的部分包进 <conversation-checkpoint>(catch-up.ts)作为一条用户消息发送。fork 用 SDK 的 forkSession,fork.ts 还会逐条比对内容,确认前缀没被改过。

压缩和总结也走 fork,保留聊天的工具和提示来复用 prompt cache。spec 记录了一次测试,新写入缓存的 token 从 8577 降到 32。

7. 进程和计费

8. 和原生 Claude Code 的差别

下面这些在 OpenCode 里用不了,来自 spec 和文档:

Ryan Winchester 问到不同项目用不同 CLAUDE_CONFIG_DIR 的情况。从代码看,io.env() 会透传 shell 环境变量,理论上能生效,但我没实测。

和 Pi 的做法对比

Manoj Mahalingam 的 Two Harnesses Walk into a Claude Subscription 是我看到最好的外部分析,他读了两边的源码,并把引用固定到了具体 commit。

OpenCode Claude Agent pi-claude-code
接入方式 公开的 Agent SDK claude -p 的 stream-json,加本地 relay
上游请求 Claude Code 发,不改动 relay 拦截、抓取,有时改写
工具调用 MCP handler 挂起等结果 MCP 立即拒绝,Pi 从 relay 抓原始响应
工具调用后 同一 session 继续 换新 worker,重放历史
系统提示 Claude Code 预设加追加内容 Pi 的提示替换基础提示
登录 订阅、API key、云厂商、网关 只支持订阅,发现冲突配置就拒绝启动
超额保护 无专门处理 检测到 isUsingOverage 就让回合失败

他的建议是交互式编码先选 OpenCode,需要跨模型统一提示和记录格式的应用选 Pi。文章结论也很直白:两边都比他预想的复杂得多。他没有实测速度和额度消耗。

我的看法是,Pi 的 relay 能看到带认证的请求头,也依赖 Claude Code 的请求格式,条款风险和维护成本都比 OpenCode 高。OpenCode 这边的代价是 Claude 的行为更接近 Claude Code,不完全由 OpenCode 决定。

合规到底稳不稳

支持的证据:

需要留意的地方:

Grok 的回复别当证据。同一天它既说“Anthropic 明确禁止”(例),又说“完全合法”(例),前者还是发布前回答的。

我的判断:技术路径是条款允许范围里最稳的一种,比任何 OAuth 插件都安全。但主力账号要不要现在切过去,我会再等一下,等 Anthropic 给出明确说法,或者等社区跑一段时间看有没有封号报告。先拿非主力账号试更稳妥。

社区反应

X 和 Reddit 上最集中的问题就三个:会不会封号、走的是 SDK 还是 OAuth、为什么不直接用 Claude Code。

书签里的相关内容

书签搜索是严格的关键词匹配,“claude subscription”“opencode claude max”都是 0 条。你没有收藏这次发布本身。相关的只有这些:

这次调研的局限

Read this report as Markdown · Cite it (BibTeX)