결론부터: OpenCode 2.2.3부터 OpenCode에 Claude Agent라는 provider가 기본으로 들어갔습니다. Claude Code(2.1.248 이상)를 설치하고 터미널에서 claude auth login을 실행한 뒤, OpenCode의 /connect에서 Claude Agent를 고르면 Claude Code 로그인과 모델을 OpenCode에서 쓸 수 있습니다. 이를 알린 @opencode 게시물("you can now use your claude subscription in OpenCode")은 하루 만에 조회 62만 회를 넘겼습니다.
하지만 방법이 이것 하나는 아닙니다. OpenCode에서 Claude를 쓰는 길은 원래 두 가지입니다.
- 구독 로그인:
/connect→ Claude Agent. 사용량은 Claude 계정 쪽에서 차감됩니다. - API Key:
/connect→ Anthropic, 또는opencode.json에서anthropicprovider에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 SDK 경유 | OpenCode 자체 |
| 도구, 권한, 기록 | 모두 OpenCode 쪽 | 모두 OpenCode 쪽 |
| CLAUDE.md | Claude Code의 CLAUDE.md 로딩은 꺼짐. 규칙은 AGENTS.md로 전달 | OpenCode 자체 규칙 로딩 (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로 다시 돌아오면 그동안 못 본 부분이 메시지 하나로 묶여 전달됩니다.
방법 1: Claude Agent 구독 로그인 (OpenCode 2.2.3+)
1단계: 버전 확인
opencode --version # 2.2.3+
claude --version # 2.1.248+
부족하면 업데이트:
# 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 로그인
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
/connect
→ Claude Agent (Claude Code login)
→ Anthropic (API Key)
/models
Anthropic이 아니라 Claude Agent를 고릅니다. Anthropic은 API Key 입구라서 Key 입력창만 뜹니다. 2.2.4부터는 Claude Agent를 고르면 안내가 시작됩니다. claude auth login 명령 복사, Claude Code 설치, 연결 확인을 거쳐 모델 선택으로 넘어갑니다. 데스크톱 앱에서 Needs sign-in이 떴을 때도 여기서 복구할 수 있습니다.
claude가 PATH에 없거나 여러 버전이 깔려 있으면 환경 변수로 지정합니다.
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 설명, 선택한 에이전트의 프롬프트 등)가 더해집니다.
- 지원하지 않는 기능: 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로 만든 에이전트도 포함된다고 적혀 있고, 대신 API key 인증을 쓰라고 안내합니다.
- OpenCode 설계 문서도 "Open Questions"에 Anthropic과 논의하거나 승인을 받아야 하는지를 적어 두었습니다.
- @grok에 따르면 Anthropic은 이 사용 방식을 공개적으로 확인하거나 승인하지 않았습니다. @schulzfel에 따르면 공식 Agent SDK로 구현됐습니다. @jimmyyangrz에 따르면 Claude 로그인에 의존하므로 써 보기에는 괜찮지만 워크플로의 기반으로 삼기에는 위험합니다.
이 글 게시 시점까지 Anthropic은 OpenCode의 이 provider에 대해 공개 입장을 내지 않았습니다. 구독 계정의 위험은 「Claude 계정이 정지되는 이유와 Claude Code를 API Key로 옮기는 방법」을 참고하세요.
방법 2: Anthropic provider + API Key
이 방법은 Claude Code가 필요 없고 OpenCode가 직접 요청을 보냅니다. AICodeWith Key로 설정하면 다음과 같습니다.
1단계: Key를 환경 변수에 넣기
export AICODEWITH_API_KEY="YOUR_API_KEY"
2단계: opencode.json에 baseURL 쓰기
프로젝트 루트의 opencode.json 또는 전역 ~/.config/opencode/opencode.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은/v1없는https://api.aicodewith.ai입니다. 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가 AICodeWith Key로 작은 버그 고치기
Linux 머신에 OpenCode 2.2.5를 설치하고 위 설정으로 slugify 함수를 고치게 했습니다. 프로젝트에는 .py 파일을 바꾸면 테스트를 돌리라는 AGENTS.md를 두었습니다.
# 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")
명령:
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."
Enter부터 종료까지 약 11초. OpenCode는 두 파일을 읽고 slug.py를 다시 쓴 뒤 AGENTS.md 지시대로 테스트를 돌렸고 3개 모두 통과했습니다. 실제 출력:
> 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.
고친 코드:
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 구독 계정이 없어서, 방법 1의 단계는 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가 같은 파일을 읽습니다.
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로 설정했을 때 돌아온 응답:
Error: 不支持的请求路径,请检查 API 地址是否正确
https://api.aicodewith.ai/v1로 바꾸면 됩니다.
「请在请求中提供有效的 API Key」(유효한 API Key 없음)
{env:AICODEWITH_API_KEY}가 빈 값입니다. 다른 터미널에서 export했거나 변수 이름을 잘못 쓴 경우가 대부분입니다. 변수를 비운 뒤 나온 오류:
Error: 请在请求中提供有效的 API Key。
CLAUDE.md를 고쳐도 반영되지 않는다
프로젝트에 이미 AGENTS.md가 있으면 OpenCode는 그것만 쓰고, Claude Agent에서는 Claude Code의 CLAUDE.md 로딩도 꺼져 있습니다. 앞 절처럼 규칙을 AGENTS.md로 옮기세요.
플랜 한도에 걸렸다
설계 문서에 따르면 Claude Code가 스스로 재시도하고 OpenCode는 이 provider에서 재시도하지 않으므로, 한도 오류는 한 번만 표시됩니다. 초기화를 기다리거나 /models에서 API Key 방식으로 바꿔 계속하세요.



