zen-proxy: 모든 AI 코딩 에이전트에서 OpenCode Zen의 무료 모델 사용

시작하기

설치

curl -fsSL https://raw.githubusercontent.com/12errh/zen-proxy/main/install.sh | bash

irm https://raw.githubusercontent.com/12errh/zen-proxy/main/install.ps1 | iex

_{이것이 전체 설치 과정입니다 — 계정, API 키, npm install가 필요 없습니다. 이제 아래에서 사용할 에이전트를 선택하세요.}

Claude Code

zen-claude

_{Linux, macOS 및 Windows에서 동일하게 작동합니다.}

프록시가 이미 실행 중이 아니라면 시작하고, 모든 라이브 무료 Zen 모델을 Claude Code의 /model 선택기에 로드하며, Claude Code를 실행한 후 종료할 때 프록시를 다시 중지합니다. 기존 Claude Code 설정은 건드리지 않습니다.

모든 OpenAI와 호환되는 에이전트

_{Cline, Roo Code, Continue, Aider, mimo, opencode 포크 — baseURL 설정을 가진 모든 것}

curl -s http://127.0.0.1:8787/health
# {"ok":true,"upstream":"https://opencode.ai/inference/v1"}

zen-proxy     # http://127.0.0.1:8787 — 대시보드는 / 에서 접근 가능

중지할 때까지 계속 작동하므로, 에이전트를 한 번만 프록시에 연결하고 계속 사용할 수 있습니다. zen-claude가 이 작업을 대신 처리해주고 정리도 해줍니다.

제공되는 기능 (What you get)

프록시가 필요한 이유 (Why a proxy is needed)

OpenCode의 무료 모델은 OpenCode CLI 자체에만 제공됩니다. 다른 모든 사용자는 다음 오류를 받게 됩니다:

403 FreeTierError: OpenCode's free tier can only be used from within OpenCode

zen-proxy는 이 게이트웨이 앞에 위치하여 사용자 에이전트를 실제 세션으로 식별합니다.

OpenAI 형태의 라우트는 이름 매핑이 없으므로 다르게 처리됩니다. 즉, 도구가 전혀 없는 요청—요약이나 제목 생성 같은 에이전트 자체 내부 호출—은 OpenCode 고유의 도구 명세(tool manifest)를 받아 게이트를 통과합니다. 이는 opencode가 모든 호출에서 보내는 방식과 정확히 같습니다. 이 게이트웨이는 tool_choice: "none"을 존중하지 않으며, 일반적인 요약 프롬프트에 실제 read 호출로 응답하기 때문에, OpenAI 형태의 라우트 모두에서 모든 도구 호출은 대신 응답에서 제거됩니다.

• 이것은 익명의 무료 티어에 의존합니다. IP당 할당량, 공유 풀이며 때때로 포화 상태가 될 수 있습니다. 안정성이 필요하면 키를 가져오세요.
• 단순 curl로는 403 에러가 발생합니다. 게이트웨이는 진정한 에이전트 트래픽에만 응답합니다. 위에 언급된 모든 에이전트는 이 방식을 따르지만, 수동으로 만든 채팅 클라이언트는 그렇지 않습니다.
• "agent-only"로 표시된 모델이 고장 난 것은 아닙니다. 게이트웨이는 합성적인 상태 확인(health probes)을 거부하므로, 프록시는 실제 요청으로부터 진정한 상태를 학습합니다—ok (실제 트래픽)입니다. 모델은 일시적인 차단으로 인해 절대 누락되지 않습니다.
• 모델의 존재는 프로빙이 아닌 카탈로그에서 옵니다. 은퇴한 모델과 건강한 모델 모두 동일하게 거부되므로, 어떤 프로브도 이 둘을 구별할 수 없습니다.
• 폴백(Fallbacks)은 zen_served_by 및 x-zen-served-by / x-zen-fallback 헤더를 통해 자신을 알립니다.
• agent-tools.json은 OpenCode의 도구를 캡처한 것입니다. 만약 OpenCode가 도구 스키마를 변경하면, /v1/messages 브릿지가 게이트웨이를 만족시키지 못할 수 있습니다. 모든 OpenCode 요청에서 다시 캡처하세요.

설정 (Configuration)

첫 실행 시 생성되며, 대시보드에서 실시간으로 재로드하고 편집 가능한 zen-proxy.json 파일입니다. 환경 변수가 시작 시 우선합니다.

⚠️ [IMG:N] 형식 토큰은 이미지 placeholder 입니다. 번역하지 말고 원래 위치에 그대로 유지하세요.

Anonymous public access shares a per-IP quota that is sometimes saturated. Set defaultZenKey, or send x-zen-key per request, for steadier service.

http://127.0.0.1:8787/ — 상위(upstream) 상태 및 가동 시간, 실시간 요청 피드, 원클릭 모델 테스트, 즉시 설정 편집, 그리고 로그 테일링 기능.

install.sh 스크립트를 사용하면 systemd 유닛을 설치할 수 있으며, 또는 다음 명령어를 사용할 수 있습니다:

sudo systemctl enable --now zen-proxy

두 런처 모두 환경 변수(env vars)를 내보내기(export) 하는 대신 --settings 플래그를 전달합니다. Claude Code는 ~/.claude/settings.json에서 환경 변수를 읽으며, 이 값이 셸의 설정보다 우선합니다. 따라서 해당 파일이 이미 ANTHROPIC_BASE_URL을 설정하고 있다면 export 명령어는 조용히 무시됩니다. 기존 구성은 그대로 유지되며, 일반적인 claude 명령어도 이를 사용합니다.

claude --settings ./claude/zen-proxy.settings.json

생성된 피커(picker)는 bin/make-settings.mjs에서 가져오며, 이 스크립트는 프록시로부터 실시간 모델 목록을 읽습니다 (fallback으로 models.json 사용). 각 행은 behavesAs를 설정하여 Claude Code가 생소한 모델 ID도 적절하게 처리하면서 해당 정확한 ID를 상위(upstream)로 전송하도록 합니다.

만약 zen-claude가 'command not found'라고 한다면, 먼저 ls -l ~/.local/bin/zen-claude를 확인하세요. 심볼릭 링크(symlink)가 없다면 설치 프로그램을 다시 실행해야 합니다. 이 명령이 존재한다면, 이는 오래된 PATH 설정일 뿐입니다:

export PATH="$HOME/.local/bin:$PATH"                          # 현재 터미널에서만 적용
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc      # 영구적으로 적용