OpenCode 接入 Claude 两条路怎么选:Claude Agent 订阅登录 vs API Key 配置教程(2.2.3+)

OpenCode 2.2.3 新增内置 Claude Agent provider:装好 Claude Code 2.1.248+、执行 claude auth login,再在 /connect 里选 Claude Agent,就能用 Claude Code 的登录和模型。另一条路是 Anthropic provider 填 baseURL 和 API Key。本文对比两条路的区别,给出完整配置步骤、CLAUDE.md 迁到 AGENTS.md 的做法、常见报错,并附 API Key 路线的实测输出。

7 分钟阅读
OpenCode 接入 Claude 两条路怎么选:Claude Agent 订阅登录 vs API Key 配置教程(2.2.3+)

先说结论:从 OpenCode 2.2.3 起,OpenCode 内置了一个叫 Claude Agent 的 provider。装好 Claude Code(2.1.248 或更新),在终端执行 claude auth login,再到 OpenCode 里 /connect 选 Claude Agent,就能用你 Claude Code 的登录和模型。@opencode 官方 10 月 31 日 00:00(北京时间)发的帖子一句「you can now use your claude subscription in OpenCode」,一天内曝光超过 62 万。

但它不是唯一的路。OpenCode 里接 Claude 一直有两条:

  • 订阅登录:/connect → Claude Agent,额度跟着你的 Claude 账号走。
  • API Key:/connect → Anthropic,或在 opencode.json 里给 anthropic provider 填 baseURL 和 Key,按 Key 计量。

下面讲清两条路的区别、各自的配置步骤,以及切过去以后 CLAUDE.md 为什么「不生效」了。

创建 API Key,在 OpenCode、Claude Code、Codex、Cursor 里共用 →

两条路的区别一张表

对比项Claude Agent(订阅登录)Anthropic(API Key)
需要的版本OpenCode 2.2.3+,本机装 Claude Code 2.1.248+任意版本的 OpenCode
登录方式终端里 claude auth login填 API Key(可放环境变量)
谁发请求本机的 claude 程序,通过官方 Claude Agent SDKOpenCode 自己
工具、权限、历史都在 OpenCode 这边都在 OpenCode 这边
读不读 CLAUDE.mdClaude Code 的 CLAUDE.md 加载被关掉,规则走 AGENTS.mdOpenCode 自己的规则加载(AGENTS.md 优先)
远程 / 托管工作区不支持,必须在装了 claude 的同一台机器上支持
temperature 等采样参数不支持支持

表里的行为都来自 OpenCode 仓库里这个 provider 的设计文档 claude-agent-provider.md和 PR #58782。

怎么选:

  • 已经有 Claude 订阅、只在自己电脑上用 OpenCode,想直接用现有账号:走 Claude Agent。
  • 要在服务器、远程工作区、CI 里跑,或者想让 OpenCode、Claude Code、Codex、Cursor 共用一把 Key、统一看调用记录:走 API Key。
  • 两条路可以同时配好,在 /models 里切换。据设计文档,OpenCode 的历史是唯一来源,从 Claude Agent 切到别的模型再切回来,对方没看到的部分会被打包成一条消息补给它。

路线一:Claude Agent 订阅登录(OpenCode 2.2.3+)

第 1 步:确认版本

bash
opencode --version   # 2.2.3+
claude --version     # 2.1.248+

版本不够就升级:

bash
# OpenCode
opencode upgrade
# or: curl -fsSL https://opencode.ai/v2/install | bash
# or: npm i -g @opencode/cli@latest

# Claude Code
claude update
# or: curl -fsSL https://claude.ai/install.sh | bash

Claude Code 必须是 2.1.248 或更新。据设计文档,OpenCode 会让 Claude Code 跳过它每轮自动加的上下文(嵌套的 CLAUDE.md、技能列表、提醒等),这个能力从 2.1.248 开始才有。

第 2 步:在终端登录 Claude Code

bash
claude auth login
claude --version
opencode

注意是在终端里执行 claude auth login,不是在 Claude Code 里输入 /login。2.2.4 的更新说明专门把之前误导人的 /login 提示改成了 claude auth login。

据设计文档,OpenCode 不会读取 Claude Code 保存的登录信息,/connect 只是记录「你选了这种登录方式」,请求由本机的 claude 程序自己发。订阅、API Key、云厂商账号,claude 用哪种登录都可以。

第 3 步:在 OpenCode 里 /connect 选 Claude Agent

text
/connect
  → Claude Agent      (Claude Code login)
  → Anthropic         (API Key)
/models

选 Claude Agent,不要选 Anthropic。Anthropic 那一项是 API Key 入口,选了只会弹出一个输入 Key 的框。2.2.4 起选 Claude Agent 后会有引导:复制 claude auth login 命令、安装 Claude Code、检查连接,通过后再选模型;桌面版里显示 Needs sign-in 时也能从这里恢复。

claude 不在 PATH 里,或者你装了多个版本,可以用环境变量指定:

bash
export OPENCODE_CLAUDE_PATH="$HOME/.local/bin/claude"
opencode

切过去以后有哪些变化

据设计文档:

  • Claude Code 自带的工具关掉了,Claude 用的是 OpenCode 的工具。每次工具调用都走 OpenCode 的权限确认,只有一套权限系统。
  • Claude Code 的配置都不读:~/.claude 和项目里 .claude 目录下的设置、CLAUDE.md、hooks、MCP 服务器、skills 都关掉,OpenCode 用自己的那一套。自动压缩、自动记忆也关掉,由 OpenCode 接管。
  • 系统提示词用 Claude Code 自己的,再加上 OpenCode 的说明:AGENTS.md、skills、MCP 说明、当前 agent 的提示词等。
  • 不支持的功能:Claude 套餐的 /usage、云端会话和 /teleport、/loop、auto mode、computer use 等。OpenCode 里的 /usage 显示的是 OpenCode Console 的用量。
  • 每个会话一个常驻的 claude 进程,空闲 5 分钟后退出,下一条消息会接上之前的 Claude 会话。

条款上的争议

这条路在回复区争议很大,很多人问会不会违反 Anthropic 条款:

  • Claude Agent SDK 官方文档概览页写明:除非事先获得批准,Anthropic 不允许第三方开发者在自己的产品里提供 claude.ai 登录或套餐额度,包括基于 Claude Agent SDK 构建的 agent,并建议改用 API Key 认证。
  • OpenCode 的设计文档在「Open Questions」里也写了一条:是否需要和 Anthropic 沟通或取得批准。
  • 据 @grok 的回复,Anthropic 尚未公开确认或批准这种用法;据 @schulzfel,这是用官方 Agent SDK 实现的;据 @jimmyyangrz,这条路依赖 Claude 登录,适合尝鲜,拿来搭长期工作流有风险。

截至本文发布,Anthropic 没有就 OpenCode 这个 provider 公开表态。订阅账号本身的风控问题,可以先看《Claude 账号为什么被封:Claude Code 改用 API Key 的做法》。

路线二:Anthropic provider + API Key

这条路不依赖 Claude Code,OpenCode 直接发请求。用本站 Key 的配置如下。

第 1 步:把 Key 放进环境变量

bash
export AICODEWITH_API_KEY="你的 API Key"

第 2 步:在 opencode.json 里填 baseURL

项目根目录的 opencode.json,或全局的 ~/.config/opencode/opencode.json:

json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "anthropic": {
      "options": {
        "baseURL": "https://api.aicodewith.ai/v1",
        "apiKey": "{env:AICODEWITH_API_KEY}"
      }
    }
  },
  "model": "anthropic/claude-sonnet-5-5"
}

几个要点:

  • OpenCode 的 baseURL 要带 /v1:https://api.aicodewith.ai/v1。这一点和 Claude Code 不一样,Claude Code 的 ANTHROPIC_BASE_URL 是 https://api.aicodewith.ai,不带 /v1。
  • apiKey 用 {env:AICODEWITH_API_KEY} 从环境变量读,Key 不会写进项目文件,也就不会被 git 提交。
  • 也可以不写 apiKey,改用 /connect → Anthropic 在弹出的框里粘贴 Key。
  • 用 /models 看能选的 Claude 模型,model 写成 anthropic/模型 ID。

多个客户端共用一个账号时 Key 和地址怎么分开管理,见《Codex、OpenCode、WorkBuddy 多工具配置不串线》;Claude Code 这边的配置见《Claude Code 第三方 API 接入教程》。

实测:OpenCode 2.2.5 用本站 Key 修一个小 bug

我们在一台 Linux 机器上装了 OpenCode 2.2.5,按上面的配置走 API Key 路线,让它修一个 slugify 函数,项目里放了一份 AGENTS.md,要求改完 .py 文件后跑测试:

python
# slug.py
def slugify(title):
    return title.lower().replace(" ", "-")

# test_slug.py
def test_basic(self):  self.assertEqual(slugify("Hello World"), "hello-world")
def test_punct(self):  self.assertEqual(slugify("OpenCode + Claude: Setup!"), "opencode-claude-setup")
def test_spaces(self): self.assertEqual(slugify("  a   b  "), "a-b")

命令:

bash
opencode run -m anthropic/claude-sonnet-5-5 \
  "Fix slugify in slug.py so all tests in test_slug.py pass. Follow AGENTS.md. Reply with one short summary line."

从回车到返回用时约 11 秒。OpenCode 读了两个文件、改写 slug.py、按 AGENTS.md 的要求跑了测试,3 个测试全部通过。真实输出:

text
> build · claude-sonnet-5-5
→ Read slug.py
→ Read test_slug.py
← Write slug.py
Wrote file successfully: slug.py
$ python3 -m unittest 2>&1 | tail -5
...
Ran 3 tests in 0.000s
OK
I rewrote `slugify` in `slug.py` to turn each run of non-alphanumeric characters into one hyphen and strip hyphens from both ends, and `python3 -m unittest` now passes all 3 tests.

改完的代码:

python
import re


def slugify(title):
    # Collapse every run of non-alphanumeric characters into a single hyphen
    return re.sub(r"[^a-z0-9]+", "-", title.lower()).strip("-")

订阅登录这条路我们没有可用的 Claude 订阅账号,上面路线一的步骤按 OpenCode 的发布说明和设计文档整理。

创建 API Key,照着上面的 opencode.json 跑一遍 →

CLAUDE.md 迁到 AGENTS.md

走 Claude Agent 时,Claude Code 自己的 CLAUDE.md 加载被关掉了,项目规则要靠 OpenCode 传过去。OpenCode 的规则加载顺序是(见 OpenCode Rules 文档):

  • 项目里同时有 AGENTS.md 和 CLAUDE.md 时,只用 AGENTS.md。
  • 没有 AGENTS.md 时,才把 CLAUDE.md 当兜底。
  • 全局的 ~/.config/opencode/AGENTS.md 优先于 ~/.claude/CLAUDE.md。

最省事的做法:把规则搬到 AGENTS.md,CLAUDE.md 只留一行引用,这样 OpenCode、Claude Code、Codex 读到的是同一份:

bash
git mv CLAUDE.md AGENTS.md
printf '@AGENTS.md\n' > CLAUDE.md
git add AGENTS.md CLAUDE.md

Claude Code 会通过 @AGENTS.md 把内容导进来。更完整的共用写法见《Claude Code 和 Codex 共用 AGENTS.md》。

常见报错

/connect 里只看到输入 API Key 的框

你选的是 Anthropic。那是 API Key 入口。要用订阅登录,退回去选 Claude Agent。列表里没有 Claude Agent,说明 OpenCode 版本低于 2.2.3,执行 opencode upgrade。

Claude Agent 连不上或提示要登录

按顺序查:claude --version 是否 2.1.248+;是否在终端里执行过 claude auth login;claude 是否在 PATH 里,不在就设置 OPENCODE_CLAUDE_PATH。在远程工作区或托管版 OpenCode 里这个 provider 不可用。

不支持的请求路径

API Key 路线下 baseURL 少了 /v1。我们把地址故意写成 https://api.aicodewith.ai 时,返回的就是:

text
Error: 不支持的请求路径,请检查 API 地址是否正确

改成 https://api.aicodewith.ai/v1 即可。

请在请求中提供有效的 API Key

{env:AICODEWITH_API_KEY} 读到的是空值,通常是在另一个终端里 export 的,或者变量名拼错。我们把变量清空后跑出来的报错:

text
Error: 请在请求中提供有效的 API Key。

改了 CLAUDE.md 没效果

项目里已经有 AGENTS.md 时,OpenCode 只用 AGENTS.md;走 Claude Agent 时 Claude Code 的 CLAUDE.md 加载也被关掉了。按上一节把规则搬到 AGENTS.md。

到了套餐上限

据设计文档,Claude Code 会自己重试,OpenCode 不再重试,达到套餐上限的错误只显示一次。等额度恢复,或者在 /models 里切到 API Key 那条路继续。

参考来源

相关文章

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是什么、怎么用?Vercel + shadcn 给 Agent 的行为库,在 Claude Code / Codex / Cursor 里安装与实测(0.1.0-beta.1)

UI SDK 是 Vercel 在 2026 年 11 月 12 日发布的、给 Agent 用的行为(behaviors)库,版本 0.1.0-beta.1。行为写在与框架无关的 @ui-sdk/core 里,再由 React、Vue、Svelte、Solid 和 Web Components 适配器渲染。本文按官方文档整理它是什么、怎么安装、怎么给 Claude Code / Codex / Cursor 装 skill,并记录我们在测试机上的真实命令、耗时和输出。

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是什么、怎么装?让 Claude Code / Codex 在本地测 AWS 应用(1.0.322 实测)

AWS Emulator 是 AWS 官方 2026 年 11 月 12 日(北京时间)正式发布的本地 AWS 模拟器,没有额外服务费、源码开放,不需要 AWS 账号,覆盖 200 多个服务。本文在 Debian 13 上实测 1.0.322:安装命令、AWS CLI 指向本地 endpoint 建 S3 桶和 DynamoDB 表、常见报错,以及让 Claude Code、Codex、Cursor 对着模拟器写代码跑测试的接法。

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是什么、怎么装?接入 Claude Code 和 Codex、配置第三方 API Key 与常见报错(0.1.9 实测)

T3 Code 是 pingdotgg 开源的编码 Agent 控制台,本身不带模型,调用你机器上已装好的 Claude Code、Codex、Cursor 等 CLI。本文在 Linux 上实测 T3 Code 0.1.9:讲清安装命令,Claude Code 和 Codex 先各自接上 AICodeWith API Key、再由 T3 Code 调用的配置方法,用 t3 thread 命令行跑通两端的过程,以及我们实际遇到的报错和解法。