OpenCode + Claude: Claude Agent Subscription Login vs API Key Setup (2.2.3+)

OpenCode 2.2.3 adds a built-in Claude Agent provider. Install Claude Code 2.1.248+, run claude auth login, then pick Claude Agent in /connect to use your Claude Code login and models. The other route is the Anthropic provider with a baseURL and an API Key. This guide compares both routes, walks through each setup, shows how to move CLAUDE.md rules to AGENTS.md, lists common errors, and includes real output from the API Key route.

8 分钟阅读
OpenCode + Claude: Claude Agent Subscription Login vs API Key Setup (2.2.3+)

Short answer: since OpenCode 2.2.3, OpenCode ships a built-in provider called Claude Agent. Install Claude Code (2.1.248 or newer), run claude auth login in your terminal, then choose Claude Agent in OpenCode's /connect, and you get your Claude Code login and models inside OpenCode. The @opencode post announcing it ("you can now use your claude subscription in OpenCode") passed 620K views within a day.

It is not the only route. There have always been two ways to use Claude in OpenCode:

  • Subscription login: /connect → Claude Agent. Usage counts against your Claude account.
  • API Key: /connect → Anthropic, or set baseURL and a Key for the anthropic provider in opencode.json. Usage is metered per Key.

Below: how the two differ, how to set up each one, and why your CLAUDE.md seems to stop working after the switch.

Create an API Key and share it across OpenCode, Claude Code, Codex and Cursor →

The two routes side by side

Claude Agent (subscription login)Anthropic (API Key)
VersionsOpenCode 2.2.3+, Claude Code 2.1.248+ installed locallyAny OpenCode version
Sign-inclaude auth login in a terminalPaste an API Key (or read it from an env var)
Who sends requestsYour local claude program, via the official Claude Agent SDKOpenCode itself
Tools, permissions, historyAll on the OpenCode sideAll on the OpenCode side
CLAUDE.mdClaude Code's CLAUDE.md loading is turned off; rules come through AGENTS.mdOpenCode's own rule loading (AGENTS.md first)
Remote / hosted workspacesNot supported; claude must run on the same machineSupported
Temperature and other sampling optionsNot supportedSupported

Everything in this table comes from the provider's design doc claude-agent-provider.md and PR #58782 in the OpenCode repo.

Which one to pick:

  • You already have a Claude plan and only run OpenCode on your own computer: use Claude Agent.
  • You run OpenCode on servers, remote workspaces or CI, or you want OpenCode, Claude Code, Codex and Cursor to share one Key with one place to check usage records: use the API Key route.
  • You can set up both and switch in /models. Per the design doc, OpenCode's history is the source of truth: when you switch back to Claude Agent, everything it missed is sent to it as one message.

Route 1: Claude Agent subscription login (OpenCode 2.2.3+)

Step 1: check versions

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

Upgrade if needed:

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 must be 2.1.248 or newer. Per the design doc, OpenCode tells Claude Code to skip the context it normally adds each turn (nested CLAUDE.md files, skill lists, reminders), and that option only exists from 2.1.248.

Step 2: sign in to Claude Code in a terminal

bash
claude auth login
claude --version
opencode

Run claude auth login in a terminal, not /login inside Claude Code. The 2.2.4 release notes specifically replaced a misleading /login hint with claude auth login.

Per the design doc, OpenCode never reads Claude Code's saved login. /connect only records that you picked this login method, and your local claude sends the requests itself. Any login claude supports works: a subscription, an API key or a cloud account.

Step 3: run /connect in OpenCode and choose Claude Agent

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

Choose Claude Agent, not Anthropic. Anthropic is the API Key entry and only shows a box asking for a Key. From 2.2.4, choosing Claude Agent starts a guided setup: copy the claude auth login command, install Claude Code, verify the connection, then pick a model. In the desktop app you can also recover from Needs sign-in there.

If claude is not on your PATH, or you have several versions installed, point OpenCode at the right one:

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

What changes after the switch

Per the design doc:

  • Claude Code's built-in tools are off. Claude uses OpenCode's tools, and every tool call goes through OpenCode's permission prompts. There is one permission system.
  • Claude Code's own config is not read: settings in ~/.claude and the project's .claude folder, CLAUDE.md files, hooks, MCP servers and skills are all turned off; OpenCode uses its own versions. Auto compaction and auto memory are off too; OpenCode handles compaction.
  • The system prompt is Claude Code's own, plus OpenCode's instructions: AGENTS.md, skills, MCP instructions, the selected agent's prompt and so on.
  • Not supported: Claude plan /usage, cloud sessions and /teleport, /loop, auto mode, computer use and more. /usage in OpenCode shows OpenCode Console usage.
  • Each session keeps one long-running claude process. It exits after 5 idle minutes, and the next message resumes the saved Claude session.

The terms question

The replies under the announcement are full of people asking whether this breaks Anthropic's terms:

  • The official Claude Agent SDK overview says that unless previously approved, Anthropic does not allow third-party developers to offer claude.ai login or rate limits for their products, including agents built on the Claude Agent SDK, and points to API key authentication instead.
  • OpenCode's own design doc lists, under "Open Questions", whether they need to discuss this with Anthropic or get approval.
  • According to @grok, Anthropic has not publicly confirmed or approved this use; according to @schulzfel, it is built on the official Agent SDK; according to @jimmyyangrz, because it relies on the Claude login it is fine to tinker with but risky to build a workflow on.

As of publishing, Anthropic has not commented publicly on OpenCode's provider. For account-risk issues with subscription logins, see Why Claude accounts get banned and how to move Claude Code to an API Key.

Route 2: Anthropic provider + API Key

This route does not need Claude Code; OpenCode sends the requests directly. Here is the setup with an AICodeWith Key.

Step 1: put the Key in an environment variable

bash
export AICODEWITH_API_KEY="YOUR_API_KEY"

Step 2: set baseURL in opencode.json

Use opencode.json in the project root, or the global ~/.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"
}

Notes:

  • OpenCode's baseURL includes /v1: https://api.aicodewith.ai/v1. Claude Code is different: its ANTHROPIC_BASE_URL is https://api.aicodewith.ai without /v1.
  • apiKey reads {env:AICODEWITH_API_KEY} from the environment, so the Key never lands in project files or git.
  • You can also leave apiKey out and paste the Key via /connect → Anthropic.
  • Use /models to list the Claude models you can pick, and write model as anthropic/<model id>.

For keeping Keys and endpoints separate when several clients share one account, see Codex, OpenCode and WorkBuddy multi-tool setup. For the Claude Code side, see Claude Code third-party API setup.

Test run: OpenCode 2.2.5 fixes a small bug with an AICodeWith Key

We installed OpenCode 2.2.5 on a Linux machine, used the config above, and asked it to fix a slugify function. The project had an AGENTS.md that says to run the tests after changing any .py file:

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")

Command:

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."

It finished in about 11 seconds from Enter to exit. OpenCode read both files, rewrote slug.py, ran the tests as AGENTS.md asked, and all 3 tests passed. Real output:

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.

The fixed code:

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("-")

We don't have a Claude subscription account to test with, so the Route 1 steps above follow OpenCode's release notes and design doc.

Create an API Key and run the opencode.json above yourself →

Moving CLAUDE.md to AGENTS.md

With Claude Agent, Claude Code's own CLAUDE.md loading is off, so project rules have to come through OpenCode. OpenCode's rule order (see the OpenCode Rules docs):

  • If a project has both AGENTS.md and CLAUDE.md, only AGENTS.md is used.
  • CLAUDE.md is only a fallback when there is no AGENTS.md.
  • The global ~/.config/opencode/AGENTS.md wins over ~/.claude/CLAUDE.md.

The simplest fix: move the rules into AGENTS.md and leave a one-line import in CLAUDE.md, so OpenCode, Claude Code and Codex all read the same file:

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

Claude Code pulls the content in through @AGENTS.md. For a fuller shared setup, see Sharing AGENTS.md between Claude Code and Codex.

Common errors

/connect only shows an API Key input box

You picked Anthropic, which is the API Key entry. For subscription login, go back and pick Claude Agent. If Claude Agent isn't in the list, OpenCode is older than 2.2.3: run opencode upgrade.

Claude Agent won't connect or asks you to sign in

Check in order: claude --version is 2.1.248+; you ran claude auth login in a terminal; claude is on your PATH (if not, set OPENCODE_CLAUDE_PATH). The provider is not available in remote workspaces or hosted OpenCode.

"不支持的请求路径" (unsupported request path)

On the API Key route, baseURL is missing /v1. When we deliberately set it to https://api.aicodewith.ai, this is what came back:

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

Change it to https://api.aicodewith.ai/v1.

"请在请求中提供有效的 API Key" (no valid API Key)

{env:AICODEWITH_API_KEY} resolved to an empty value, usually because you exported it in a different terminal or misspelled the name. The error we got after clearing the variable:

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

Editing CLAUDE.md has no effect

When the project already has AGENTS.md, OpenCode only uses AGENTS.md, and with Claude Agent, Claude Code's CLAUDE.md loading is off as well. Move the rules to AGENTS.md as shown above.

Hitting the plan limit

Per the design doc, Claude Code retries on its own and OpenCode does not retry for this provider, so a plan-limit error shows once. Wait for your allowance to reset, or switch to the API Key route in /models.

Sources

相关文章

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

What is the UI SDK, and how do you use it? Vercel and shadcn's behavior library for agents, installed and tested in Claude Code / Codex / Cursor (0.1.0-beta.1)

The UI SDK is Vercel's behavior library for agents, released on 12 November 2026 as 0.1.0-beta.1. Behaviors live in the framework-free @ui-sdk/core package and are rendered by adapters for React, Vue, Svelte, Solid, and Web Components. This guide follows the official docs on what it is, how to install it, and how to add the skill for Claude Code, Codex, and Cursor, and it records the commands, timings, and output from our test machine.

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

What Is AWS Emulator and How Do You Install It? Test AWS Apps Locally with Claude Code and Codex (Tested on 1.0.322)

AWS Emulator is AWS's official local emulator of its service APIs, generally available since November 11, 2026 (US time). It has no additional service fee, its source is open, it needs no AWS account, and it covers more than 200 services. We tested version 1.0.322 on Debian 13. This guide covers the install commands, pointing the AWS CLI at the local endpoint to create an S3 bucket and a DynamoDB table, the errors we hit, and how to let Claude Code, Codex and Cursor write and test code against the emulator.

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

What Is T3 Code and How Do You Install It? Connect Claude Code and Codex, Use a Third-Party API Key, Fix Common Errors (Tested on 0.1.9)

T3 Code is pingdotgg's open-source control surface for coding agents. It ships no model of its own; it drives the Claude Code, Codex, Cursor and other CLIs already on your machine. We tested T3 Code 0.1.9 on Linux. This guide covers the install commands, how to point Claude Code and Codex at an AICodeWith API Key so T3 Code can drive them, a full run of both agents with the t3 thread command, and the errors we hit along the way with their fixes.