在 OpenCode 里用 Claude 订阅:来龙去脉与源码实现
By 陈成 · Published October 31, 2026
OpenCode 怎么接入 Claude 订阅,源码如何实现,合规上稳不稳?
调研时间 2026-10-31。源码基于 OpenCode v2.2.5,commit 4878a0e30f。
结论
OpenCode 这次没有恢复 3 月被下架的 OAuth 方案,而是换了一条路。
- 它用 Anthropic 官方的 Claude Agent SDK 启动用户本机的
claude,模型请求全部由 Claude Code 自己发。 - 登录在终端里用
claude auth login完成。我 grep 了整个 provider 目录,没有fetch,也没有读 credentials 或 keychain 的代码,和 spec 里“从不读取登录信息”的说法一致。 - Claude Code 的内置工具全部关掉。OpenCode 把自己的工具做成 MCP server 塞给它,模型一调工具,MCP handler 就挂起等待,由 OpenCode 跑完工具再把结果送回去。这个挂起的 Promise 是整个实现的核心。
- 所以它的实际形态是“OpenCode 的外壳和工具,Claude Code 的系统提示和模型通道”。一句话概括:壳是 OpenCode,账单还是 Claude Code。
合规上有一个没闭合的口子。“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: 继续流式输出
对应代码:
tools/server.ts#L27-L31:handler 不干活,直接return pending.call(name)。tools/pending.ts#L39-L48:等待call.result.promise。tools/hooks.ts:MCP handler 收不到tool_use_id,只能靠 PreToolUse hook 提前存一下。claude/session.ts#L121-L129:看到message_stop且有工具调用,就返回"tools",结束 OpenCode 这一步。claude/sessions.ts#L278-L286:下一轮 resolve 挂起的调用,再继续读流。
这里有一个代价。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. 进程和计费
- 每个聊天一个
claude进程,空闲 5 分钟退出(IDLE_MS),下次用resume接上。 - 等工具期间不算空闲(L338),否则权限弹窗等久了会被记成用户取消。
- 系统提示、工具列表、连接配置或输出上限一变,进程就重启(L72)。模型和 effort 可以在运行中切换。
- 订阅登录显示费用 $0(
provider.ts#L116-L122)。这只代表 OpenCode 不按 token 算钱,plan 额度照扣。 - SDK 是可选 peer dependency,首次使用才加载。
8. 和原生 Claude Code 的差别
下面这些在 OpenCode 里用不了,来自 spec 和文档:
/usage和额度提示,OpenCode 的/usage显示的是 Console 用量- auto mode、agent teams、
/loop、云端 session - auto memory,以及
/simplify这类内置 skill ~/.claude的所有配置,包括 CLAUDE.md、hooks、MCP 和 skills,需要在 OpenCode 里另配一遍
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 决定。
合规到底稳不稳
支持的证据:
- Anthropic 法律页现在写明,条款不阻止 “an end user from signing in to the unmodified Claude Code binary with their own Claude subscription”。
- 2 月到 3 月版本里 “including the Agent SDK ... is not permitted” 这句(见 Matt Pocock 的引用),现在的页面上已经没有了。我没查到改动日期。
- 支持文章说,登录 Claude plan 后,SDK、
claude -p和第三方应用的用量都走订阅额度。 - PR 作者 Tarquinen 在 PR 里说 “We got permission from Anthropic and everything here is fully tos compliant”。Daniel Smolsky 也在 X 上说了同样的话。
需要留意的地方:
- 同一份法律页也写着,开发者的产品“包括使用 Agent SDK 的”应当用 API key,并且 Anthropic 不允许第三方开发者在自己的应用里提供 Claude.ai 登录。SDK 概览则写 “Unless previously approved”。OpenCode 的合规性依赖两点:登录发生在官方二进制里,以及确实拿到了这个 “previously approved”。
- 我没找到 Anthropic 的公开确认。X 上搜
from:ClaudeDevs opencode和from:bcherny opencode都没结果,不过 X 搜索本身不算可靠。maria 公开要求官方确认,这条有 380 赞。 - 这个仓库里的 spec 还留着 “Do we need to discuss anything here with anthropic or any kind of approval?” 这个未决问题。可能只是忘了删,但它和“已获批准”放在一起不太好看。
- spec 还写着,有传闻说
claude -p和 SDK 用户的额度消耗得比原生 Claude Code 快,并注明“未验证”。Phanes 也提了同样的疑问。 - 法律页还写着,订阅额度按“ordinary, individual usage”设计,并保留不事先通知就采取措施的权利。r/ClaudeCode 3 月有人自述只跑几次
-p就被封,一面之词,也没有下文。 - v1 文档还写着 “Anthropic explicitly prohibits this”。这句话针对的是旧插件,但确实让不少人困惑。
Grok 的回复别当证据。同一天它既说“Anthropic 明确禁止”(例),又说“完全合法”(例),前者还是发布前回答的。
我的判断:技术路径是条款允许范围里最稳的一种,比任何 OAuth 插件都安全。但主力账号要不要现在切过去,我会再等一下,等 Anthropic 给出明确说法,或者等社区跑一段时间看有没有封号报告。先拿非主力账号试更稳妥。
社区反应
X 和 Reddit 上最集中的问题就三个:会不会封号、走的是 SDK 还是 OAuth、为什么不直接用 Claude Code。
- 封号担忧最多。r/ClaudeCode 的帖子(52 分,40 条评论)里有人直接说 “Def getting banned lol”,也有人反驳说 Hermes 早就这样做了。
- r/opencode 的帖子(66 分)有人嫌证据只是“推文截图的推文”。高赞评论指向 PR 那条回复,同时认为只有 OpenCode 单方说法仍然可疑。
- 没立刻用上的人也不少,有人反馈更新后只看到 API key 输入框。同一天的提交 8505041881 补了连接前的引导,但这条反馈发在该提交之后,具体原因我没查。
- 对价值的质疑也有。Dickson 问相比 Claude Code 的优势在哪,Pierre Bruno 说“就是 OpenCode 里的 Claude Code”。正面的理由是 Ernest 说的,选哪个工具成了个人偏好,不再是账单问题。
- 也有人问能不能照做其他厂商。PR 作者回复说 agy 暂无计划,但如果能力够且 Google 允许就可以加。
书签里的相关内容
书签搜索是严格的关键词匹配,“claude subscription”“opencode claude max”都是 0 条。你没有收藏这次发布本身。相关的只有这些:
- Matt Pocock:能否用订阅 token 跑 Agent SDK,2026-03,最贴题
- Pi Changelog v0.83.0,
pi auth print-bearer-token可以把凭证导出给外部客户端 - OpenCode 2.0 发布,这次的 provider 就建在 v2 的 core 和插件体系上
- Josh Rosen:Pi Durable vs OpenCode 架构对比
- Manoj:Code mode that survives a crash,和上面对比文章同一作者
- Vercel durable-harness,同样把 Claude Code 和 OpenCode 当可替换的运行层
这次调研的局限
- 没有实际运行 OpenCode,也没有测额度消耗。源码分析基于阅读。
- provider 主流程我读了,
tools/result.ts、sync/fingerprint.ts、sync/checkpoints.ts、usage.ts只看了部分或靠 spec 理解。 - 2 月那个侧分支提交为何当时没合入,我没查到原因。
- 帖子数据是 2026-10-31 上午的快照,这件事发布才一天,后续可能有变化。