OpenCode Claude Agent: Setup, Subscription Limits, and Policy

Use the OpenCode Claude Agent provider through your own local Claude Code installation. Install both tools, run claude auth login, then choose Claude Agent in /connect. Choose API-key access if your team needs a clearly documented third-party authentication route.

As of 2026-11-05, OpenCode provides a dedicated Claude Agent setup guide. The provider uses Claude Code’s active authentication, so selecting it does not automatically select subscription billing.

What does Claude Agent change?

Claude Agent gives you OpenCode’s interface and tool execution while Claude Code handles model communication. OpenCode calls your installed claude through Anthropic’s Claude Agent SDK.

The built-in provider arrived in OpenCode v2.2.3. Version v2.2.4 added guided setup in the desktop/app provider picker. You do not need a separate subscription plugin.

The provider design assigns file operations, shell commands, and permissions to OpenCode. Claude Code’s built-in tools are disabled.

OpenCode also runs compaction and subagents, as its current Claude Agent guide explains. The integration does not load your native Claude Code settings, hooks, MCP servers, skills, or memory.

Your OpenCode instructions and tools therefore determine how the project is handled. Review them before allowing edits or command execution. If your workflow depends on native Claude Code hooks or agent teams, continue using Claude Code until you have an equivalent workflow.

The main reason to try this provider is to keep OpenCode’s interface and model-switching workflow. Installing it does not reproduce the complete Claude Code experience.

Install and connect Claude Agent

Use OpenCode V2 and Claude Code on the same machine as the OpenCode server. This provider is unavailable in OpenCode remote workspaces.

The subscription path assumes an active individual Pro, Max, or Ultra plan.

Install the correct versions

Install OpenCode V2, with v2.2.3 as the feature minimum. Use v2.2.4 or later for the guided app setup.

These commands are for Bash on macOS, Linux, or WSL. They follow the OpenCode V2 installation instructions and Claude Code installation instructions:

curl -fsSL https://opencode.ai/v2/install | bash
curl -fsSL https://claude.ai/install.sh | bash

Open a new terminal, then check both versions:

opencode --version
claude --version

Claude Code must be 2.1.248 or later, as required by the provider’s version check. Update older native installations with claude update; use the relevant package manager for package-managed installations.

If you already use V1, read the V2 migration guide first. Both versions use the opencode command and shared configuration locations.

Installation does not supply model usage. See Claude Code installation, subscription, and API access if you have not selected an account route.

Sign in and check the account

Authenticate through Claude Code’s own sign-in flow. Select your Claude subscription account if you intend to use its allowance:

claude auth login
claude auth status --text

Confirm that the status identifies the intended account and authentication method. The CLI reference distinguishes this from claude auth login --console, which selects Console API billing.

Check for inherited credentials before a subscription trial. Anthropic documents that environment API keys can override subscription authentication. If an old key is unintentionally set in your personal shell, clear it:

unset ANTHROPIC_API_KEY
claude auth status --text

Also check unintended ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, and cloud-provider settings against Anthropic’s authentication precedence. A subscription login does not override every other credential.

Inspect providers.claude-agent.settings in your OpenCode configuration for apiKey, authToken, or baseURL. Model-level overrides also matter. The connection implementation applies these settings after the server’s environment.

Connect and verify a real request

Start a private OpenCode server for the first check:

opencode --standalone

Standalone mode uses a private server. This makes the current shell’s environment relevant, instead of relying on an already-running shared service. It does not remove configuration overrides.

Inside OpenCode, run /connect and select Claude Agent. Then run /models and choose one of the models reported by Claude Code. Provider model references can use aliases such as claude-agent/opus; do not assume they match direct API model IDs.

In the desktop/app interface, the guided setup offers installation, sign-in, connection checking, and recovery. A successful check continues to model selection. These app controls are separate from the terminal instructions above.

Use a repository containing README.md, then submit:

Read README.md and summarize the project in three sentences. Do not modify files or run shell commands.

Check that OpenCode shows a file-reading tool call and a relevant answer. This checks model access and the tool-return path. A populated model picker alone is insufficient: the connection probe does not send a model prompt.

Set OPENCODE_CLAUDE_PATH when discovery fails

Point the server at the actual Claude Code executable if its PATH does not find the intended installation. First confirm that command -v claude resolves the correct executable in your terminal.

For another standalone check:

export OPENCODE_CLAUDE_PATH="$(command -v claude)"
opencode --standalone

For the shared background service, use its managed environment:

opencode service set env OPENCODE_CLAUDE_PATH "$(command -v claude)"

Changing the service environment stops the running service. The next command that needs the local server starts it with the new value. Reconnect Claude Agent and repeat the small request. The server environment instructions explain why changing only a client terminal can be insufficient.

Which allowance does Claude Agent use?

Budget requests according to Claude Code’s active credential. With subscription authentication, treat Claude Agent requests as part of your existing Claude allowance.

OpenCode documents subscription coverage for this route. Anthropic confirms that Claude and Claude Code share plan usage limits. Together, these rules mean switching the interface does not create a second allowance.

Keep three cases separate:

Claude Code authentication	What pays for usage
Claude subscription	The plan’s included allowance, subject to its limits and any enabled paid usage credits
Anthropic API account or supported cloud account	That account’s API billing and limits
Custom gateway	The gateway account’s billing rules

Do not use an empty cost estimate as proof of free usage. The provider’s cost logic also omits estimates for custom base URLs.

Check Claude Settings > Usage for consumption and reset times. Claude Code’s native /usage view is not available inside OpenCode. Also review paid usage credits: enabling them can produce additional charges after included limits.

For the broader account decision, compare Claude subscriptions and API billing.

What do the policy statements establish?

Treat permission as specific to the implementation and arrangement. Using the official SDK alone does not grant every third-party application access to subscription credentials.

The three documents address different situations:

Official source	What it says	What follows for this setup
OpenCode’s legacy providers page	It warns that Anthropic prohibits Pro/Max subscription plugins and says OpenCode stopped bundling them in 1.3.0.	This historical plugin warning does not describe the new V2 provider’s implementation.
Anthropic Agent SDK overview	Third-party developers need prior approval to offer Claude account login or rate limits in their products.	Calling the SDK is not sufficient evidence of permission.
Claude Code legal and compliance	It restricts third-party credential intermediation while allowing users to sign into an unmodified Claude Code binary with their own subscriptions.	Preserve the native sign-in flow; do not generalize this exception to credential pooling or a new commercial service.

There is also an implementation-specific statement. On 2026-10-30, PR author Tarquinen said Anthropic had granted permission and described the integration as compliant. Attribute that statement to the OpenCode contributor. It is not an Anthropic-issued document defining the approval’s scope.

For personal use, keep your own login inside the unmodified Claude Code installation. Do not export session tokens into another plugin. For a company rollout or product integration, obtain confirmation covering that arrangement, or use the documented API-key route.

Successful authentication establishes that a request works. It does not settle contractual coverage for every deployment.

Fix the failure you actually see

Match the symptom to its cause, then repeat the small file-reading request.

Symptom	Check and next action
Claude Code is not installed	Install it on the OpenCode server’s machine, or set that server’s OPENCODE_CLAUDE_PATH. Reconnect.
Claude Code is not logged in	Run claude auth login on that machine under the same user. Check status, then reconnect.
The error says 2.1.248 or later is required	Update Claude Code and confirm the executable version before retrying.
Connected, but no models or no working response	Check the server’s executable and login. Reconnect; model discovery alone does not prove inference works.

The documented connection errors cover the missing-installation and missing-login branches. If a request instead reaches a plan limit, inspect the account’s usage page. Reconnecting does not replenish its allowance.

When should you use an API key?

Choose API-key access when you need separate billing, a server without local Claude Code, or the documented authentication route for a third-party product. Keep its budget and limits separate from the Claude subscription.

Direct Anthropic API access

Create your own key in Claude Console. In OpenCode, select Anthropic through /connect and use API-key authentication.

The equivalent V2 authentication command prompts for the secret interactively:

opencode auth login anthropic --method key
opencode run --standalone --model anthropic/claude-sonnet-5-5 "Reply with only: OK"

Look for an OK response and confirm usage against the intended API account. If the selected account or model is wrong, correct it through /connect or /models before retrying.

An OpenAI-compatible API route

BetterToken also lists claude-sonnet-5-5 and claude-opus-5-5 as of 2026-11-05. Its documented OpenCode integration uses an OpenAI-compatible API and your own BetterToken key. This is separately billed API access.

Create a key in your workspace. For a new native V2 configuration, merge this provider into your project’s opencode.jsonc:

{
  "$schema": "https://opencode.ai/config.json",
  "providers": {
    "bettertoken": {
      "name": "BetterToken",
      "env": ["BETTERTOKEN_API_KEY"],
      "package": "@opencode/ai/providers/openai-compatible",
      "settings": {
        "baseURL": "https://www.bettertoken.ai/v1"
      },
      "models": {
        "claude-sonnet-5-5": {
          "name": "Claude Sonnet 5.5"
        }
      }
    }
  }
}

This follows OpenCode’s native V2 custom-provider format. It uses providers, package, and settings; do not mix V1 field names inside this provider entry.

Collect the key without displaying it, then run the check in the same Bash terminal:

read -rs BETTERTOKEN_API_KEY && export BETTERTOKEN_API_KEY
opencode run --standalone --model bettertoken/claude-sonnet-5-5 "Reply with only: OK"

Expect a normal response containing OK, then check the request and charge in the workspace. If you already saved a BetterToken account in OpenCode, check its active account: saved accounts take precedence over environment connections.

Review current prices before a larger job. This API route does not include a Claude subscription or authorize unrelated subscription-login integrations.