OpenCode Claude Agent: 설정, 구독 한도와 이용 조건

OpenCode의 Claude Agent 프로바이더는 직접 설치한 로컬 Claude Code를 통해 사용합니다. 두 도구를 설치하고 claude auth login을 실행한 뒤 /connect에서 Claude Agent를 선택합니다. 팀에서 외부 제품에 대한 인증 방법이 명확히 문서화된 경로를 원한다면 API 키를 선택합니다.

2026-11-05 기준으로 OpenCode는 별도의 Claude Agent 설정 가이드를 제공합니다. 이 프로바이더는 Claude Code에서 현재 활성화된 인증을 사용합니다. 따라서 이 프로바이더를 선택해도 자동으로 구독 이용량이 사용되는 것은 아닙니다.

Claude Agent를 사용하면 무엇이 달라집니까?

Claude Agent를 사용하면 OpenCode가 인터페이스와 도구 실행을 제공하고, Claude Code가 모델과의 통신을 처리합니다. OpenCode는 Anthropic의 Claude Agent SDK를 통해 설치된 claude를 호출합니다.

이 내장 프로바이더는 OpenCode v2.2.3에 추가됐습니다. v2.2.4에서는 앱의 프로바이더 선택 화면에 단계별 설정 기능을 추가했습니다. 구독 연결용 플러그인을 별도로 설치할 필요가 없습니다.

프로바이더 설계 문서에 따르면 파일 작업, 셸 명령 실행, 권한 처리는 OpenCode가 담당합니다. Claude Code에 내장된 도구는 비활성화됩니다.

현재 Claude Agent 가이드는 컨텍스트 압축과 서브에이전트 실행도 OpenCode가 담당한다고 설명합니다. 컨텍스트 압축은 누적된 대화 내용을 줄이는 처리입니다. 이 연동은 Claude Code 자체의 설정, 훅, MCP 서버, 스킬, 메모리를 불러오지 않습니다. 훅은 특정 이벤트가 발생할 때 실행되는 처리 코드입니다.

따라서 프로젝트를 다루는 방식은 OpenCode의 지침과 도구 설정을 따릅니다. 파일 수정이나 명령 실행을 허용하기 전에 이를 확인합니다. Claude Code 자체의 훅이나 에이전트 팀에 의존하는 작업이라면 동등한 작업 구성을 마련할 때까지 Claude Code를 계속 사용합니다.

이 프로바이더를 시도할 주된 이유는 OpenCode의 인터페이스와 모델 전환 방식을 유지하기 위해서입니다. 설치만으로 Claude Code의 모든 기능을 그대로 사용할 수 있는 것은 아닙니다.

Claude Agent 설치와 연결

OpenCode 서버가 실행되는 머신에 OpenCode V2와 Claude Code를 함께 설치합니다. 이 프로바이더는 OpenCode의 원격 작업 공간에서 사용할 수 없습니다.

구독으로 연결하려면 활성 상태의 개인용 Pro, Max 또는 Ultra 플랜이 필요합니다.

필요한 버전을 설치합니다

OpenCode V2를 설치합니다. 이 기능을 사용하려면 최소 v2.2.3이 필요합니다. 앱의 단계별 설정 기능은 v2.2.4 이상에서 사용합니다.

다음 명령은 macOS, Linux 또는 WSL의 Bash에서 실행합니다. OpenCode V2 설치 안내와 Claude Code 설치 안내에 따른 명령입니다.

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

새 터미널을 열고 두 프로그램의 버전을 확인합니다.

opencode --version
claude --version

Claude Code는 2.1.248 이상이어야 합니다. 프로바이더의 버전 검사에서 요구하는 최소 버전입니다. 이전 네이티브 설치본은 claude update로 업데이트합니다. 패키지 관리자로 설치했다면 해당 패키지 관리자를 사용합니다.

이미 V1을 사용한다면 먼저 V2 마이그레이션 가이드를 읽습니다. 두 버전은 opencode 명령을 사용하며 같은 설정 경로를 공유합니다.

프로그램 설치와 모델 이용 요금은 별개입니다. 아직 사용할 계정 방식을 정하지 않았다면 Claude Code 설치, 구독, API 접근 방식을 확인합니다.

로그인하고 계정을 확인합니다

Claude Code 자체의 로그인 절차로 인증합니다. 구독에 포함된 이용량을 사용하려면 해당 구독 계정을 선택합니다.

claude auth login
claude auth status --text

상태 출력에 의도한 계정과 인증 방법이 표시되는지 확인합니다. CLI 참조 문서는 이 방법을 claude auth login --console과 구분합니다. claude auth login --console은 Console API 요금 청구를 선택합니다.

구독 사용을 시험하기 전에 환경에서 상속된 인증 정보를 확인합니다. Anthropic은 환경 변수의 API 키가 구독 인증보다 우선할 수 있다고 설명합니다. 개인 셸에 이전 키가 실수로 설정돼 있다면 해당 변수를 해제합니다.

unset ANTHROPIC_API_KEY
claude auth status --text

ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL, 클라우드 프로바이더 설정에도 의도하지 않은 값이 있는지 확인합니다. Anthropic의 인증 우선순위와 대조합니다. 구독 계정으로 로그인해도 다른 모든 인증 정보보다 우선하는 것은 아닙니다.

OpenCode 설정의 providers.claude-agent.settings에서 apiKey, authToken, baseURL을 확인합니다. 모델별로 값을 재정의한 경우도 함께 살펴봅니다. 연결 구현은 서버 환경 변수를 적용한 뒤 이 설정을 적용합니다.

연결한 뒤 실제 요청을 확인합니다

첫 검증에는 독립된 OpenCode 서버를 실행합니다.

opencode --standalone

standalone 모드는 독립된 서버를 사용합니다. 따라서 이미 실행 중인 공유 서비스에 의존하지 않고 현재 셸의 환경을 적용할 수 있습니다. 다만 설정 파일에 지정된 재정의 항목은 계속 적용됩니다.

OpenCode 안에서 /connect를 실행하고 Claude Agent를 선택합니다. 이어서 /models를 실행한 뒤 Claude Code가 제공한 모델 중 하나를 선택합니다. 프로바이더의 모델 참조는 claude-agent/opus 같은 별칭을 사용할 수 있습니다. 직접 API를 호출할 때의 모델 ID와 같다고 가정하지 않습니다.

앱 인터페이스의 단계별 설정은 설치, 로그인, 연결 확인, 오류 후 재시도를 안내합니다. 연결 확인에 성공하면 모델 선택으로 넘어갑니다. 이 앱의 조작 화면과 앞서 설명한 터미널 명령은 구분해야 합니다.

README.md가 있는 저장소에서 다음 요청을 보냅니다.

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

이 요청은 파일을 읽고 프로젝트를 세 문장으로 요약하되, 파일을 수정하거나 셸 명령을 실행하지 않도록 지시합니다. OpenCode에 파일 읽기 도구 호출과 내용에 맞는 답변이 표시되는지 확인합니다.

이렇게 모델 접근과 도구 결과가 돌아오는 과정을 함께 검증합니다. 모델 목록이 나타나는 것만으로는 충분하지 않습니다. 연결 검사는 모델에 프롬프트를 보내지 않기 때문입니다.

실행 파일을 찾지 못하면 OPENCODE_CLAUDE_PATH를 설정합니다

서버의 PATH가 원하는 설치본을 찾지 못하면 Claude Code 실행 파일의 실제 경로를 지정합니다. 먼저 터미널에서 command -v claude가 올바른 실행 파일 경로를 출력하는지 확인합니다.

독립된 서버로 다시 확인할 때는 다음 명령을 사용합니다.

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

공유 백그라운드 서비스에는 서비스가 관리하는 환경을 설정합니다.

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

서비스 환경을 변경하면 실행 중인 서비스가 중지됩니다. 이후 로컬 서버가 필요한 명령을 실행하면 새 값으로 서비스가 시작됩니다. Claude Agent를 다시 연결하고 짧은 요청을 반복합니다.

서버 환경 설정 안내는 클라이언트 터미널에서만 변수를 바꾸면 충분하지 않을 수 있는 이유를 설명합니다.

Claude Agent는 어느 이용량을 사용합니까?

요청 예산은 Claude Code의 활성 인증 정보를 기준으로 잡습니다. 구독으로 인증했다면 Claude Agent 요청도 기존 Claude 구독의 이용량에 포함해 계산합니다.

OpenCode는 이 연결 방식의 이용량이 구독에서 처리된다고 설명합니다. Anthropic은 Claude와 Claude Code가 플랜의 이용 한도를 공유한다고 확인합니다. 두 설명을 함께 보면 인터페이스를 바꿔도 별도의 이용량이 생기지 않는다는 결론이 나옵니다.

다음 세 가지를 구분합니다.

Claude Code 인증 방식	이용 요금이 처리되는 계정과 기준
Claude 구독	플랜에 포함된 이용량과 한도, 활성화한 추가 유료 사용 크레딧의 적용을 받습니다
Anthropic API 계정 또는 지원되는 클라우드 계정	해당 계정의 API 요금과 한도를 적용합니다
사용자 지정 게이트웨이	게이트웨이 계정의 요금 규칙을 적용합니다

예상 비용이 비어 있다고 무료 이용이라고 판단하지 않습니다. 프로바이더의 비용 처리 로직은 사용자 지정 기본 URL을 쓸 때도 예상 비용을 표시하지 않습니다.

소비한 이용량과 한도가 초기화되는 시각은 Claude Settings > Usage에서 확인합니다. Claude Code 자체의 /usage 화면은 OpenCode 안에서 사용할 수 없습니다. 추가 유료 사용 크레딧도 확인합니다. 이 기능을 활성화하면 포함된 한도를 소진한 뒤 별도 요금이 발생할 수 있습니다.

계정 방식을 선택하려면 Claude 구독과 API 요금 청구 비교를 참고합니다.

이용 조건에서 확인할 수 있는 범위는 무엇입니까?

허용 여부는 특정 구현과 운영 방식의 범위에서 판단해야 합니다. 공식 SDK를 사용한다는 이유만으로 모든 외부 앱이 구독 인증 정보를 사용할 권한을 얻는 것은 아닙니다.

다음 세 문서는 서로 다른 상황을 설명합니다.

공식 자료	설명하는 내용	이 설정에서의 판단 기준
OpenCode의 이전 프로바이더 문서	Anthropic이 Pro/Max 구독 플러그인을 금지한다고 경고하며, OpenCode는 1.3.0부터 이를 기본 제공하지 않는다고 설명합니다.	과거 플러그인에 대한 경고이며, 새 V2 프로바이더의 구현을 설명한 문구는 아닙니다.
Anthropic Agent SDK 개요	외부 개발자가 제품에서 Claude 계정 로그인이나 해당 계정의 요청 한도를 제공하려면 사전 승인이 필요합니다.	SDK 호출만으로 허용받았다고 판단할 수 없습니다.
Claude Code 법률 및 규정 준수 안내	제3자의 인증 정보 중개를 제한하지만, 사용자가 자신의 구독으로 수정되지 않은 Claude Code 실행 파일에 로그인하는 것은 허용합니다.	기본 로그인 절차를 유지합니다. 이 예외를 인증 정보의 공동 사용이나 새 상용 서비스에 그대로 확대해서 해석하지 않습니다.

이 구현에 관한 별도의 발언도 있습니다. 2026-10-30에 PR 작성자 Tarquinen은 Anthropic의 허락을 받았다고 밝혔으며, 이 연동이 약관을 준수한다고 설명했습니다. 이 발언의 주체는 OpenCode 기여자입니다. 승인 범위를 규정한 Anthropic 발행 문서는 아닙니다.

개인용으로 사용할 때는 수정되지 않은 Claude Code 설치본에서 자신의 계정으로 로그인합니다. 세션 토큰을 다른 플러그인으로 내보내지 않습니다. 회사에 도입하거나 제품에 통합한다면 해당 운영 방식을 포괄하는 확인을 받거나 문서화된 API 키 경로를 사용합니다.

인증을 거쳐 요청이 정상 처리됐다는 사실만으로 모든 배포 방식의 계약상 허용 여부까지 확정되지는 않습니다.

실제로 발생한 오류에 맞춰 해결합니다

관찰한 증상에 해당하는 원인을 확인한 뒤 짧은 파일 읽기 요청을 다시 실행합니다.

증상	확인할 사항과 다음 조치
`Claude Code is not installed`	OpenCode 서버의 머신에 설치하거나 그 서버의 `OPENCODE_CLAUDE_PATH`를 설정합니다. 다시 연결합니다.
`Claude Code is not logged in`	같은 머신에서 같은 사용자로 `claude auth login`을 실행합니다. 상태를 확인하고 다시 연결합니다.
오류에 `2.1.248 or later is required`가 표시됩니다	Claude Code를 업데이트하고 실행 파일 버전을 확인한 뒤 다시 시도합니다.
연결됐지만 모델이 없거나 응답이 오지 않습니다	서버의 실행 파일과 로그인 상태를 확인합니다. 다시 연결합니다. 모델 검색 성공만으로 실제 요청의 동작이 확인되지는 않습니다.

문서화된 연결 오류는 설치되지 않은 경우와 로그인하지 않은 경우를 설명합니다. 요청이 플랜 한도에 도달했다면 계정의 사용량 페이지를 확인합니다. 다시 연결해도 이용 한도가 보충되지는 않습니다.

API 키는 언제 선택해야 합니까?

요금을 분리하거나 로컬 Claude Code가 없는 서버를 사용하려면 API 키를 선택합니다. 외부 제품에 대해 문서화된 인증 방법이 필요할 때도 같은 선택이 적합합니다. API의 예산과 한도는 Claude 구독과 별도로 관리합니다.

Anthropic API에 직접 연결합니다

Claude Console에서 자신의 키를 만듭니다. OpenCode의 /connect에서 Anthropic을 선택한 뒤 API 키 인증을 사용합니다.

같은 작업을 수행하는 V2 인증 명령은 키를 대화형으로 입력받습니다.

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

응답이 OK인지 확인하고 의도한 API 계정에 사용량이 기록됐는지 확인합니다. 계정이나 모델을 잘못 선택했다면 /connect 또는 /models에서 수정한 뒤 다시 요청합니다.

OpenAI 호환 API로 연결합니다

2026-11-05 기준으로 BetterToken에도 claude-sonnet-5-5와 claude-opus-5-5가 등록돼 있습니다. 문서화된 OpenCode 연동은 OpenAI 호환 API와 자신의 BetterToken 키를 사용합니다. 이 API 접근에는 별도의 이용 요금이 청구됩니다.

워크스페이스에서 키를 만듭니다. 새로운 V2 기본 형식으로 설정하려면 기존 설정을 유지하면서 다음 프로바이더를 프로젝트의 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"
        }
      }
    }
  }
}

이 예제는 OpenCode의 V2 기본 사용자 지정 프로바이더 형식을 따릅니다. providers, package, settings를 사용합니다. 이 프로바이더 항목 안에 V1 필드 이름을 섞지 않습니다.

키가 화면에 표시되지 않도록 입력한 뒤 같은 Bash 터미널에서 확인 요청을 실행합니다.

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

정상적으로 연결됐다면 OK가 포함된 응답을 기대할 수 있습니다. 이어서 워크스페이스의 요청과 청구 내역을 확인합니다. OpenCode에 BetterToken 계정을 이미 저장했다면 활성 계정도 확인합니다. 저장된 계정은 환경 변수를 통한 연결보다 우선합니다.

큰 작업을 시작하기 전에 현재 가격을 확인합니다. 이 API 경로에는 Claude 구독이 포함되지 않습니다. 다른 구독 로그인 연동에 대한 허가를 제공하는 것도 아닙니다.