OpenCode 플러그인이 공식 CLI로 Claude Code를 실행한다

OpenCode용 @khalilgharbaoui/opencode-claude-code-plugin은 Anthropic의 Claude 모델을 HTTP API로 직접 호출하지 않고, 공식 Claude Code CLI인 claude를 하위 프로세스로 실행한다. 기존 CLI 로그인(Claude 구독, API 키, Bedrock 또는 Vertex)을 이용하며, OpenCode 1.x와 2.x를 모두 지원한다.

플러그인은 토큰을 읽거나 저장하거나 재사용하지 않는다. 제작자는 Anthropic이 2026년 2월 구독 인증을 제3자 Claude 사용에 재사용하는 방식을 허용하지 않았다고 설명하며, 이 플러그인은 그런 방식으로 동작할 수 없다고 밝힌다. Anthropic의 법률 안내는 수정하지 않은 공식 클라이언트에서 로그인하는 것을 허용하지만, 플러그인을 승인하거나 보증한 것은 아니라고 명시한다.

도구 실행 주체도 나뉜다. 기본 설정에서 Bash, Edit, Write, WebFetch, Task 호출은 Claude가 프로세스 내 MCP 도구를 부르고 OpenCode가 자체 권한 확인과 감사 로그 아래 실행하는 프록시 방식이다. 반면 Read, Grep, Glob, WebSearch는 Claude Code에서 실행한다. OpenCode의 MCP 서버를 Claude 쪽에 연결하고 OpenCode 스킬을 Claude의 Skill 도구에서 쓰도록 준비할 수도 있다. 도구별 실행 주체를 선택하는 방법은 도구 프록시 안내에 있다.

설치와 사용 조건

먼저 Claude Code CLI를 설치하고 로그인해야 한다. 플러그인은 기존 claude 실행 파일을 사용하며 CLI를 함께 설치하지 않는다. 로그인 상태는 claude auth status로 확인하고, 로그인하지 않았다면 claude auth login을 실행한다. 버전 확인 명령은 claude --version이다. 원문에는 예시로 2.1.284 (Claude Code)가 제시돼 있다.

OpenCode의 전역 설정에 플러그인 패키지 이름을 추가한다. 패키지를 직접 npm install하지 않아도 되며, OpenCode가 플러그인을 찾아 캐시한다.

{ "plugin": ["@khalilgharbaoui/opencode-claude-code-plugin"] }

이 설정은 ~/.config/opencode/opencode.json에 넣으며 OpenCode 1.x와 2.x에서 사용할 수 있다. OpenCode 2의 기본 키는 plugins다. OpenCode 2에서는 opencode plugin add @khalilgharbaoui/opencode-claude-code-plugin 명령으로 설정 항목을 추가하고 패키지를 설치할 수도 있다.

플러그인은 프로세스가 시작될 때 한 번 로드되므로 OpenCode를 완전히 종료한 뒤 다시 실행해야 한다. 모델 선택기에는 Claude Code 제공자가 나타난다. OpenCode 1.x에서는 제공자 ID인 claude-code로 표시된다. 모델 ID 형식은 claude-code/<model>이며, 터미널에서 확인할 때는 opencode run -m claude-code/claude-haiku-5-5 "reply with ok"를 사용한다. 목록에는 Claude Sonnet 5.5 (2×), Claude Opus 5 (5×) 같은 항목이 있으며, 괄호의 값은 Haiku 대비 각 모델의 목록 가격 비율이다.

모델 선택기에 플러그인이 보이지 않으면 증상별 문제 해결 안내를 참고할 수 있다. 어느 세션에서든 /claude-code-doctor를 실행하면 모델 호출 없이 플러그인이 파악한 상태를 출력한다.

계정·비용·권한

플러그인은 CLI가 로그인한 계정과 과금 방식을 따른다. 구독 계정에서 헤드리스 claude --print를 사용하면 해당 요금제의 일반 사용량 한도에서 차감되고, API 키를 사용하면 사용량에 따라 과금된다. 플러그인은 세션마다 CLI의 apiKeySource를 확인하며, ANTHROPIC_API_KEY 환경 변수가 의도치 않게 과금 경로를 바꿀 수 있으면 경고한다. 자세한 내용은 과금 안내와 어떤 로그인에 과금되는지에 관한 문제 해결 문서에 있다.

여러 Claude Code 계정을 설정하면 "accounts": ["personal", "work"]와 같이 지정한 계정마다 제공자가 하나씩 생긴다. 작업 도중 사용량 한도에 도달하면 안내에 계정, 한도 갱신 시간대와 시각, 선택할 수 있는 다른 계정이 표시된다. 하위 에이전트 설정에서는 forceModel, reasoningEffort, cacheTtl을 지정할 수 있고 호출자의 계정을 이어받는다. task_batch는 여러 하위 에이전트를 동시에 실행한다. 관련 문서는 계정 설정과 하위 에이전트 안내다.

플러그인은 Haiku 4.5부터 Opus 5.5까지, Fable과 Mythos, low부터 max까지의 추론 노력 설정, 빠른 모드를 지원한다고 설명한다. 각 모델에는 (N×) 목록 가격 표시가 붙는다. 계정에서 특정 모델을 사용할 수 없는 경우를 위한 대체 모델 연결도 제공한다. 모델 전체 목록은 모델 문서에서 확인할 수 있다.

"permissionPreset": "read-only"를 지정하면 CLI, 프록시, 권한 계층에 읽기 전용 설정을 적용한다. /btw는 진행 중인 프로세스에 관한 별도 질문에 사용하고, /claude-code-doctor는 상태 보고서를 제공한다. Doctor의 bundle 형식은 허용 목록에 따라 정보를 가려 공개 이슈에 붙여 넣을 수 있게 한다고 제작자는 설명한다. 각 기능의 문서는 /btw, Doctor, 권한 설정에 있다.

플러그인에는 설정 옵션과 환경 변수, 모델 ID, 문제 해결 규칙을 안내하는 claude-code-plugin 스킬이 포함된다. 이 스킬은 Claude Code를 실행할 때마다 준비되며, 테스트가 코드와 내용이 맞는지 확인하도록 구성했다고 제작자는 밝힌다.

비교와 제약

OpenCode의 기본 anthropic 제공자는 OpenCode 인증 저장소에 플랫폼 API 키를 사용한다. 이 플러그인은 공식 claude CLI의 로그인 정보를 이용하고 토큰을 가져오지 않는다. 구독 인증을 공식 클라이언트 밖에서 재사용하는 프록시·토큰 재사용 플러그인과는 인증 방식이 다르다. 이 플러그인은 대화마다 claude 하위 프로세스를 실행하며 동시 실행 수는 16개로 제한된다. Claude Code가 OpenCode 모르게 자체 컨텍스트를 압축할 수도 있다.

OpenCode 2.2.3 이상에서 Claude 로그인 계정 하나만 사용하는 경우에는 OpenCode에 내장된 Claude Agent 제공자도 대안이다. 이 기능 역시 사용자의 claude를 실행하지만 모든 도구를 OpenCode에서 실행하고 ~/.claude 설정은 사용하지 않는다. 제작자는 플러그인이 OpenCode 1.x 지원, 여러 계정, 기존 Claude Code 설정, 빠른 모드, /btw, 사이드바 기능을 추가로 제공한다고 안내한다. 자세한 항목은 전체 비교 문서와 내장 Claude Agent 제공자 비교에 있다.

제작자는 테스트 파일 12개가 가짜 claude를 이용해 실제 턴을 진행하며 스트림 파서, 프록시 중개기, 두 감시 기능, 중단, 재실행, 계정 전환, 모델 대체 연결을 종단 간 점검한다고 설명한다. AGENTS.md의 각 규칙에는 측정에 사용한 검사, 버전, 수치가 기록돼 있고 근거는 에이전트 기록에 있다고 한다. 런타임 의존성은 두 개다. 사이트는 릴리스 뒤와 수치가 바뀌는 푸시마다, 그리고 6시간마다 갱신된다고 안내한다.

문서는 소개, 시작하기, OpenCode 2, 설정 옵션, 환경 변수, MCP, 스킬, 기록 설정, 백그라운드 하위 에이전트, 턴별 통계, 컨텍스트 압축과 사고 과정, 대화형 전송, 다른 플러그인과의 호환성, 장기 문제 해결 사례, 알려진 제한 사항, 턴 처리 방식, 프록시 호출 종료 방식, 임시 파일과 보안, 측정 방식, 테스트, 개발, 릴리스에서 볼 수 있다. 문서 사이트의 내용은 GitHub에서 렌더링되는 docs/ 디렉터리에도 있다.

저장소는 칼릴 가르바우이(Khalil Gharbaoui)가 만들고 관리한다. 플러그인은 포크에서 가져온 작업을 원 저자 표기를 보존해 반영하거나 커밋에 저자를 밝히고 다시 구현한다고 설명한다. 기여자와 기능별 공로는 크레딧 문서에서 확인할 수 있다. 라이선스는 MIT이며, 첫 버전은 에밀리앙(Émilien, @unixfox)이 작성했고 이후에는 칼릴 가르바우이와 크레딧에 기재된 사람들이 작업했다. 라이선스 파일과 기여 규칙이 담긴 AGENTS.md를 참고할 수 있다.