TL;DR
Claude의 Max 플랜과 Team 플랜에는 매월 추가 비용 없이 API 크레딧이 제공됩니다. 이 크레딧은 Claude Code에서는 사용할 수 없지만, OpenCode에 API 키를 등록하면 사용할 수 있습니다. 제 환경에서도 OpenCode를 사용하자 이 크레딧에서 차감되었습니다.
# 1. claude.ai의 Settings > Billing에서 Console 조직을 연결하고, Console에서 API 키를 생성합니다
# 2. 그 키를 OpenCode에 등록합니다(프롬프트에 붙여넣기)
opencode auth login anthropic --method key
...
- 매월 금액은 Max 5x가 $100이고, Max 20x가 $200입니다(Team은 시트별, 최대 $500). 매월 초기화되며 이월되지 않습니다. Pro는 대상에서 제외됩니다.
- 자동으로 추가되지 않습니다. claude.ai에서 Console 조직을 연결해야만 추가됩니다.
- OpenCode에는 Console의 API 키를 등록합니다. Pro/Max 계정으로 OpenCode에 로그인하는 것은 Anthropic이 허용하지 않습니다.
- 후반부는 Claude Code의 설정(
CLAUDE.md,
subagent, skill, MCP, hooks)을 OpenCode로 옮기는 방법과 주의사항입니다.
작동 확인: macOS 27.0.1, OpenCode v2.0.27, Claude Code 2.1.296. 공식 페이지 인용 및 실제 실행은 모두 2026-10-12 시점입니다.
서론
2026-10-11 밤, 해커톤 프로젝트를 마무리하며 Claude Code가 주간 한도에 도달했습니다. Console 계정으로 다시 로그인하자 이번에는 Credit balance is too low라는 메시지가 나타났습니다. 다음 날인 2026-10-12부터는 API 키로 OpenCode v2.0.27을 사용하게 되었습니다.
2026-10-07부터 Max와 Team 플랜에 월별 API 크레딧이 추가됩니다(Platform의 리포트 노트). 대화형 Claude Code에서는 사용할 수 없고, API를 통해서만 사용할 수 있습니다. 이 글은 OpenCode에 연결하는 절차와 Claude Code 설정을 V2로 이전할 때의 함정들에 대한 내용입니다.
OpenCode에 연결하는 절차
사용 가능한 범위
Help Center 및 Platform 문서의 내용을 표로 정리했습니다.
| 사용 방식 | 크레딧 |
|---|
| 대화형 Claude Code(단말・IDE・데스크톱・Web) | 대상 제외 |
연결된 조직의 API 키로 직접 실행하는 claude -p , Agent SDK | 대상 |
| Claude API, Console의 Playground | 대상 |
| Bedrock, Vertex AI, Foundry | 대상 제외 |
| OpenCode 등 제3자 클라이언트(Console의 API 키) | 기재 없음(실제로는 감소함) |
월별 금액은 Max 5x가 $100이고, Max 20x가 $200이며, Team은 시트별 풀(최대 $500)입니다. 매월 업데이트되어 이월이 없으며, Console 조직의 연결은 플랜당 1개만 가능하고, 나중에 스스로 변경할 수 없습니다(지원팀을 통해서만 가능).
Console 계정으로 Claude Code에 로그인해도 이 크레딧은 사용할 수 없습니다. 문서에는 조직이 이 크레딧만 가지고 있을 경우 Credit balance too low · Add funds: …가 표시된다고 나와 있습니다.
1. Console 조직을 연결하기
- claude.ai의 Settings > Billing을 열어봅니다(Team의 소유자는 Organization settings > Billing)
- API credits의 'Link organization'에서 조직을 선택하거나 새로 만듭니다 - Supplemental Credit Terms를 확인하고 연결합니다.
플랜 측은 Max라면 계약자(Contractor), Team이라면 소유자(Owner) 또는 기본 소유자(Primary Owner)가 필요하고, 콘솔 측은 소유자(Owner)/관리자(Admin)/청구(Billing) 중 하나의 역할이 필요합니다. 신규 계약은 7일이 지난 후에 신청할 수 있습니다. 대상임에도 'API credits'가 표시되지 않는 경우, 배포 과정 중에 있을 수 있습니다(Help Center는 며칠에 걸쳐 배포된다고 합니다). 링크하면 콘솔의 Settings > Billing에서 Promotional credits로 금액과 기한이 표시됩니다. 작업에 사용할 조직을 선택해 주세요.
2. API 키 만들기
콘솔의 Settings → API keys에서 Create key를 누르고, 이름과 유효 기간을 정하며, Linked account를 자신으로 설정합니다. sk-ant-로 시작하는 키는 생성 시에 한 번만 표시됩니다. 링크된 조직의 키는 워크스페이스가 달라도 같은 잔액에서 차감됩니다.
3. OpenCode에 등록하기
curl -fsSL https://opencode.ai/v2/install | bash # V1을 사용 중이라면 opencode upgrade --major
opencode auth login anthropic --method key
프롬프트에 키를 붙여넣습니다(대화형 터미널이 필요합니다). TUI의 경우 /connect에서 Anthropic을 선택합니다. 등록할 때마다 저장된 계정이 늘어나고, 가장 최신 것이 active가 됩니다. 이전에 다른 키를 사용했다면, opencode auth list로 확인하고, opencode auth switch anthropic <label>로 링크된 조직의 키로 전환해 주세요(Providers).
환경 변수로 전달하려면 OpenCode의 백그라운드 서버에만 설정할 수 있습니다(opencode service set env ANTHROPIC_API_KEY sk-ant-...). 저는 사용하지 않습니다.
4. 작동 여부 확인하기
$ opencode auth list
Anthropic Anthropic stored
$ opencode run --model anthropic/claude-haiku-5-5 "Reply with exactly one word: pong"
...
opencode auth list --format json을 사용하면 `
Claude Code의 설정을 OpenCode V2로 옮겨야 합니다.
- 기준으로 삼을 것은 OpenCode V2 문서(https://opencode.ai/v2/docs/)입니다. V1 방식(
permission, bash, task, mcp.<name>)은 사용하지 마세요.
- 참고할 것:
~/.claude/CLAUDE.md, ~/.claude/settings.json, ~/.claude/agents/, ~/.claude/skills/, 활성화된 플러그인(settings.json의 enabledPlugins. 내용은 ~/.claude/plugins/cache/ 아래), claude mcp list 결과
...
바로 수정하는 것이 불안하다면, 먼저 에이전트를 plan에 전환하여(Shift+Tab 또는 /agents) 계획만 세우게 하세요. plan 에이전트는 일반 파일을 편집하지 않습니다.
제 환경에서 Sonnet 5.5의 plan 에이전트에게 돌려보니, agent 10개의 수정, plugin의 skill 폴더, context7의 MCP, hook의 대체까지 포함된 계획이 나왔고, 옮길 수 없는 것(statusLine, 알림 또는 usage-guard의 hook)도 표로 제시되었습니다. 저 자신의 마이그레이션은 이 프롬프트를 만들기 전에 다음 절차에 따라 수동으로 진행했습니다. 옮긴 후에는 아래 각 항목과 비교하여 내용을 확인해 주세요.
대응되는 항목
V1 설정 예시를 복사하면 이름이 달라지는 부분이 있습니다. V2에서는 permission이 permissions로, bash가 shell로, task가 subagent로, MCP는 mcp.<name>이 아니라 mcp.servers.<name>입니다(Permissions, MCP servers).
| 항목 | Claude Code | OpenCode V2 |
|---|
| 지시서 (Instructions) | CLAUDE.md | AGENTS.md만 |
| subagent | ~/.claude/agents/*.md | ~/.config/opencode/agents/*.md (frontmatter가 다름) |
| skill | ~/.claude/skills, plugin | ~/.claude/skills는 자동, plugin 분은 skills에 나열 |
| MCP | plugin(저는 context7) | mcp.servers.<name> |
| hooks 및 권한 | settings.json의 hooks, permissions | |
| permissions. hook은 plugin | |
| 슬래시 명령어 (Slash command) | skill, commands/ | |
| commands/*.md ($ARGUMENTS는 여기서 전개) | |
CLAUDE.md는 읽히지 않습니다
V2가 읽는 것은 AGENTS.md뿐이며, CLAUDE.md에는 폴백(fallback)하지 않습니다(Instructions). 일회용 git 리포지토리에서 도구를 사용하지 않고 지시만으로 암호를 답하게 Haiku 5.5에 의존했을 때, CLAUDE.md의 암호는 돌아오지 않았고, AGENTS.md를 추가하자 돌아왔습니다.
# CLAUDE.md만(PINEAPPLE)
NONE
# AGENTS.md도 넣었을 때(MANGO)
...
설정의 instructions에 CLAUDE.md를 넣어봤지만, V2는 해당 항목을 받는 것만으로 읽지 않습니다(Config). 그래서 전역적인 AGENTS.md에 다음 한 줄을 추가했습니다. 읽는 것은 모델이므로, 따를지는 모델에게 달렸습니다.
- 대부분의 리포지토리는 Claude Code를 위해 설정되어 있었습니다. 만약 리포에
CLAUDE.md가 있고, AGENTS.md에서 달리 명시하지 않았다면, 작업하기 전에 해당 CLAUDE.md를 읽으세요: 이것이 프로젝트의 지침이며, 여기에 규칙이 적용됩니다.
리포지토리마다, Read CLAUDE.md in this repository before working.만 적힌 AGENTS.md를 배치하는 방법도 있습니다.
subagent는 frontmatter가 다릅니다
coder와 비교해 보세요.
---
name: coder
description: Use for coding tasks delegated to a subagent: ...
...
---
description: "Use for coding tasks delegated to a subagent: ..."
mode: subagent
...
name은 작성하지 않고 파일명이 ID가 됩니다 -
mode: subagent를 쓰지 않으면 primary가 됩니다(Agents) -
model은 provider/model#variant입니다. sonnet과 effort: max는 여기에 모입니다. model: inherit는 줄을 지우면 부모의 모델을 상속받습니다 -
question을 deny로 설정하는 것은 내장된 general과 동일한 설정입니다
그대로 복사해도 오류가 나지는 않습니다. ~/.claude/agents/에 있는 coder, reviewer, review-lead, Plan을 일회용 git 리포지토리의 .opencode/agents/로, 동명이의 글로벌 agent와 섞이지 않도록 cc-를 붙여 복사한 후, opencode debug agents에서 확인했습니다.
cc-coder primary (none)
cc-Plan primary (none)
cc-review-lead primary (none)
...
모두가 primary이고 모델은 비어 있습니다. name, model, effort는 반영되지 않았습니다. 게다가 cc-Plan에는 edit의 deny가 한 줄도 없고, disallowedTools로 읽기 전용으로 설정하려던 agent가 편집 가능한 상태가 됩니다. disallowedTools는 permissions의 deny로 다시 작성해야 합니다.
# Claude Code(Plan.md)
disallowedTools: Edit, Write, NotebookEdit, Agent, ExitPlanMode, Artifact
# OpenCode(planner.md)
permissions:
- action: edit
...
메인 세션의 effort는 루트의 model에는 쓸 수 없습니다. 루트의 model은 provider와 model만 유지하며, #variant는 남아있지 않기 때문입니다(Models). agents.build.model에 작성합니다.
"model": "anthropic/claude-opus-5-5",
"agents": {
"build": { "model": "anthropic/claude-opus-5-5#max" }
...
수동으로 옮긴 agent는 opencode debug agents에서 확인합니다.
| jq에 직접 연결하면 JSON이 중간에 잘립니다(직접 확인한 5번 모두). 따라서 파일을 거쳐야 합니다.
opencode debug agents > /tmp/agents.json
jq -r '.[] | select(.id | IN("build","coder","planner","review-lead")) | [.id, .mode, (.model | if . then "
(.providerID)/(.id)#(.variant // "")" else "(inherit)" end)] | @tsv' /tmp/agents.json | column -t -s$' '
build primary anthropic/claude-opus-5-5#max
coder subagent anthropic/claude-sonnet-5-5#max
planner subagent anthropic/claude-opus-5-5#max
...
skill은 plugin 개수만큼 추가합니다
~/.claude/skills
그리고 .claude/skills는 그대로 읽힙니다(Skills). 읽히지 않는 것은 plugin의 skill이며, plugin 캐시 내 skills 디렉토리를 설정의 skills에 추가합니다. 경로에 버전이 포함되므로, plugin이 업데이트되면 덮어쓰여집니다.
"skills": [
"~/.claude/plugins/cache/<marketplace>/<plugin>/<version>/skills",
"~/.claude/skills", // ID가 중복되면 뒤의 것이 우선합니다. 개인 skill은 plugin보다 뒤에 배치하세요.
...
skill의 ID는 경로로 결정되며, plugin 이름 공간이 붙지 않습니다(frontmatter의 name은 표시명입니다). 제 환경에서는 개인용 code-review와 mattpocock-skills plugin의 code-review가 충돌했습니다. 뒤의 것이 우선하기 때문에, plugin 쪽은 SKILL.md로의 심볼릭 링크만 둔 디렉토리에 별명을 붙여 남겨두었습니다.
SRC=~/.claude/plugins/cache/claude-plugins-official/mattpocock-skills/1.2.3/skills/engineering/code-review/SKILL.md
mkdir -p ~/.config/opencode/skills/mattpocock-code-review
ln -s "$SRC" ~/.config/opencode/skills/mattpocock-code-review/SKILL.md
~/.claude/skills나 plugin 캐시는 작업 디렉토리 외부에 있으므로, skill이 보조 파일을 읽을 수 있도록 external_directory를 허용합니다.
{ "action": "external_directory", "resource": "~/.claude/skills/*", "effect": "allow" },
{ "action": "external_directory", "resource": "~/.claude/plugins/cache/*", "effect": "allow" }
MCP는 servers 아래에 작성합니다
"mcp": {
"servers": {
"context7": { "type": "remote", "url": "https://mcp.context7.com/mcp", "oauth": false }
...
원격 MCP 서버는 기본적으로 OAuth를 사용합니다. context7은 계정 없이 사용할 수 있으므로, "oauth": false로 설정했습니다. opencode mcp list에서 ✓ context7 connected가 표시되면 연결된 것입니다. 툴 이름은 <server>_<tool>이며, Claude Code의 경우 mcp__plugin_context7_context7__...
과는 별개입니다. 기본 Code Mode에서는 도구가 execute를 통해 호출됩니다(codemode: false로 일반 도구로 노출할 수 있습니다).
hooks는 permissions와 plugin으로 분리합니다
Claude Code에는 subagent만이 git push나 배포를 실행하지 못하게 하는 PreToolUse의 hook(subagent-irreversible-guard.sh)이 있었습니다. 메인 세션은 예외입니다.
OpenCode V2에서는 이를 permissions로 대체했습니다. 규칙은 위에서부터 순서대로 평가되며, 가장 마지막에 일치하는 것이 승리합니다. 최상위 규칙은 모든 agent에게 적용되며, subagent는 부모의 권한을 상속받지 않고 자신의 권한만으로 작동(Permissions)하므로, 최상위에서 deny를 걸고 메인 build만 다시 열어줍니다.
{
"permissions": [
// 모든 agent(subagent 포함)에 적용되는 deny
...
- 기본값은 모두 허용입니다. V2의 agent는
*의 allow로 시작하며, ask가 되는 경우는 .env 읽기와 작업 디렉토리 외부만 해당합니다. 권한을 추가하는 것이 아니라, deny나 ask를 추가하는 설계가 됩니다 - 패턴은 커맨드 문자열의 전체에 맞춰야 합니다. *는 공백이나 따옴표를 포함하여 무엇이든 일치시키기 때문에, git * push*와 같은 광범위한 패턴은 git commit -m "fix push bug"까지 막습니다. 저는 git push*와 git -C * push처럼 좁게 작성했습니다 - 문서에서도 위험한 커맨드를 모두 포착하는 패턴보다 허용할 커맨드를 좁게 제한하는 것이 좋다고 합니다. 이 deny는 사고를 방지하는 울타리일 뿐, 샌드박스는 아닙니다.
편집 후나 종료 시에 작동하던 hook(PostToolUse, Stop)은 설정이 없어 plugin(~/.config/opencode/plugins/*.js)으로 재작성했습니다(Plugins). usage-guard의 hook은 API 키에 플랜의 5시간 단위 또는 주간 단위가 없기 때문에 이전하지 않았습니다.
슬래시 커맨드는 skill의 얇은 Wrapper로 만듭니다
skill은 skill 도구이거나, 프롬프트에 작성하는 @skill-id로 읽습니다. $ARGUMENTS를 전개(expand)하는 것은 명령어 쪽입니다(Commands). 제 delegate skill은 끝에 ARGUMENTS: $ARGUMENTS를 두어 인수를 받았습니다만, opencode run --format json으로 보면, skill 도구의 입력은 `{
Agent ツール, SendMessage
、isolation: worktree
은 OpenCode에 없습니다. Claude Code용으로 작성된 skill을 그대로 읽을 수 있도록 글로벌한 AGENTS.md에 변환표를 배치했습니다.
| Claude Code | OpenCode |
|---|
Agent 툴의 subagent_type: X | subagent 툴의 agent: X |
run_in_background: true | background: true |
SendMessage | 같은 sessionID를 전달하여 subagent를 호출 |
isolation: worktree | git worktree add를 직접 실행하고, 경로를 지시에 작성 |
fork | 없음 (자족적인 지시를 전달) |
git worktree add는 .gitignore된 파일을 가져오지 않습니다. Claude Code가 자동으로 하던 .worktreeinclude의 복사도 직접 해야 합니다.
검증 범위
- 크레딧 소모: OpenCode 사용 후 Promotional credits가 감소한 것을 Console의 Billing에서 확인했습니다. 제3자 클라이언트는 공식 페이지에 기재되어 있지 않으므로, 취급이 변경될 가능성이 있습니다 -
- 화면 문구: claude.ai와 Console의 조작은 공식 페이지의 기재를 따릅니다 -
- 권한 패턴:
git * push*가 커밋 메시지의 push까지 막는 것은 문서의 매치 규칙에서 알 수 있는 것이며, 본 기사에서는 실행하여 확인하지 않았습니다 -
- skill 별명 링크:
SKILL.md만 링크하고 있으므로, 보조 파일을 가진 skill에서 상대 경로가 해결되는지는 미확인입니다 -
- 슬래시 명령어:
$ARGUMENTS의 전개는 문서를 읽어본 것일 뿐입니다 (opencode run에서는 /이름이 전개되지 않았습니다) - macOS 외 데스크톱 앱, Team 플랜은 시도하지 않았습니다
요약
- ✅ 월별 API 크레딧은 Max 5x / Max 20x / Team에서만 가능하며, Console 조직을 연결하여 접속해야 합니다. 대화형 Claude Code에서는 사용할 수 없습니다.
- ✅ OpenCode에는 Console의 API 키를 등록합니다. Pro/Max 로그인은 사용하지 않습니다.
- ✅
ANTHROPIC_API_KEY는 ~/.zshrc에 작성하지 마세요. Claude Code가 읽어서 'Credit balance is too low' 메시지가 뜹니다.
