opencode-claude-auth是一个 OpenCode 插件：它直接复用你已有的Claude Code 凭证（OAuth 令牌），让你在 OpenCode 中免费使用 Claude 系列模型，无需单独登录、无需购买 API key。本文带你从零完成安装与配置。

什么是 opencode-claude-auth？

简单说，它解决的是一个很实际的痛点：

如果你已经订阅了 Claude Pro / Max 并在使用 Claude Code，装好这个插件后，OpenCode 会自动读取你本机的 Claude Code 凭证完成认证——整个过程你只需要"运行 OpenCode"这一件事。

工作原理：它是怎么"偷来"凭证的？

别担心，凭证始终只留在你的本机。插件的工作方式可以概括为四步：

1. 拦截请求：插件向 OpenCode 注册一个自定义 auth provider，拦截所有发往 Anthropic API 的请求；
2. 读取凭证：从 macOS 钥匙串（Keychain）读取Claude Code-credentials条目，其他平台则回退读取~/.claude/.credentials.json凭证文件；
3. 自动刷新：令牌快过期时，直接调用 Anthropic 的 OAuth 端点刷新——不消耗任何 LLM token，失败时回退到claudeCLI；
4. 后台同步：每 5 分钟将凭证同步到 OpenCode 的auth.json作为兜底，令牌剩余 1 小时到期前会主动刷新一次。

核心逻辑位于 src/index.ts（请求拦截与刷新）和 src/credentials.ts（凭证读取与缓存），想深入了解可配合 src/keychain.ts（Keychain 读取）一起看。

安装前准备：确认两个前提条件

开始安装前，请确认以下两项都已就绪：

• ✅Claude Code 已安装并完成过认证：在终端运行一次claude并登录，凭证就会存入 Keychain（macOS）或~/.claude/.credentials.json（Linux / Windows）；
• ✅OpenCode 已安装：运行opencode --version能输出版本号即可。

💡 平台兼容性：macOS 体验最佳（走 Keychain），Linux 和 Windows 通过凭证文件回退，同样可用。

一键安装步骤：只需一行配置

方式 A：让 AI 帮你装（最省事）

把下面这句话粘贴给任意 LLM agent（Claude Code、OpenCode、Cursor 等），它会自动完成全部配置：

Install the opencode-claude-auth plugin and configure it by following: https://raw.githubusercontent.com/griffinmartin/opencode-claude-auth/main/installation.md

方式 B：手动配置（只需 30 秒）

打开 OpenCode 配置文件~/.config/opencode/opencode.json，添加一行插件声明：

{ "plugin": ["opencode-claude-auth@latest"] }

两个要点：

• @latest标签保证每次启动时都拉取最新版本，无需手动npm install——OpenCode 会用 Bun 自动安装 npm 插件；
• 配置完成后直接运行 OpenCode，插件会自动接管认证，无需任何额外操作。

详细的分步安装说明（含验证与升级方法）见 installation.md，完整项目介绍见 README.md。

支持哪些模型？

当前版本支持14 个 Claude 模型，覆盖 Opus、Sonnet、Haiku、Fable 全系列：

各模型对应的 beta 标志与请求头策略定义在 src/model-config.ts，可通过pnpm run test:models用你自己的账号实测验证（最近一次的 14 个模型冒烟测试结果全部通过，见 test-results/model-smoke-test.json）。

此外，1M 超长上下文已被原生支持，插件不再发送旧的 beta 头。如果你的套餐不含长上下文计费，超出标准窗口后会提示 "Extra usage is required for long context requests"。

多账号切换（macOS 用户福音）

在 macOS 上登录了多个 Claude Code 账号？插件会自动从 Keychain 检测所有账号，并按订阅等级（Claude Pro、Claude Max 等）自动标注。

切换方法：

opencode auth login

在列表中选择"Switch Claude Code account"，挑一个账号即可。你的选择会跨会话持久化；如果只有一个账号，切换菜单会自动隐藏。

常见问题排查

遇到报错别慌，对照下面这张表基本都能解决：

如果认证错误难以复现，可以开启诊断日志：

export CLAUDE_AUTH_DEBUG=1

日志会写入~/.local/share/opencode/claude-auth-debug.log，所有密钥（token、API key）都会被自动脱敏，文件可以直接贴到 issue 里。排查完记得unset CLAUDE_AUTH_DEBUG。

进阶：常用环境变量

Anthropic 若调整了接口细节，你不用干等插件发版——大部分参数都可以通过环境变量即时覆盖：

例如临时指定 CLI 版本：export ANTHROPIC_CLI_VERSION=2.2.0。

另外，如果你已经在跑CLIProxyAPI，它本身就能用 OAuth 登录 Claude 账号并暴露本地 API，此时不需要也不建议再叠加本插件（两者二选一即可），直接让 OpenCode 内置的 Anthropic provider 指向代理地址就行。

⚠️ 风险与合规提醒

有一点必须坦诚说明：Anthropic 的服务条款要求 Claude Pro/Max 订阅令牌仅用于官方客户端。本插件属于社区 workaround，如果 Anthropic 调整其 OAuth 基础设施，插件可能随时失效。请自行评估后使用，并遵守你所在平台的合规要求。

结语

回顾一下 opencode-claude-auth 带给你的核心价值：

• 🆓省钱：不购买 API key，复用已付费的 Claude Code 订阅；
• ⚡省事：一行配置完成安装，令牌自动读取、自动刷新、自动同步；
• 🔄多账号：macOS 下自动检测 Keychain 中的所有 Claude Code 账号，一条命令切换；
• 🧰可观测：脱敏诊断日志 + 丰富的环境变量覆盖，出问题好排查。

安装完成后，运行 OpenCode 即可直接开聊——你的 Claude 订阅，现在同时驱动两个工具了。版本演进历史可查阅 CHANGELOG.md，构建与脚本定义见 Makefile。