[4편] CliProxyAPI 완벽 가이드 - CLI AI 모델을 표준 API로 통합하기

1편 OpenCode와 OpenCode Zen 완벽 가이드
2편 Oh-My-OpenCode로 나만의 워크플로우 구축하기
3편 Custom Agents 가이드

[4편] OpenCode Proxy와 모델 관리

1. CliProxyAPI란?

GitHub에서 강력한 CLI 기반 AI 모델들(Claude Code, OpenAI Codex, Gemini CLI 등)을 OpenAI/Gemini/Claude 호환 API로 노출하여 기존의 수많은 AI 도구와 연결해 주는 프록시 서버입니다.

CLI-Proxy-Api Github Link

왜 필요한가?

Claude Code, Codex 등 최신 모델들은 CLI 환경에서만 강력한 기능을 제공
기존 OpenAI SDK나 GUI 도구들과는 직접 호환되지 않는 불편함 존재
CliProxyAPI가 중간에서 프로토콜을 변환하여 표준 API 규격으로 제공
Antigravity와 gemini cli, openai, claude 모두에 결제했다면, 내가 원하는 모든 모델들을 돌아가며 편하게 사용할 수 있다. 특히 그 계정들이 여러개라면 더욱 빛을 발한다.

지원 모델:

Claude Code (Anthropic CLI)
OpenAI Codex
Gemini CLI
Qwen Code
iFlow
Antigravity
*Custom API

2. 설치 및 실행

2.1 Docker로 실행 (권장)

가장 빠르고 깔끔한 실행 방식입니다.

docker run -d \
  --name cliproxyapi \
  -p 8317:8317 \
  -v $(pwd)/config.yaml:/app/config.yaml \
  ghcr.io/router-for-me/cliproxyapi:latest

2.2 바이너리로 실행

빌드된 바이너리를 직접 다운로드하여 실행할 수 있습니다.

# 다운로드 (Linux/macOS)
curl -L https://github.com/router-for-me/CLIProxyAPI/releases/latest/download/cliproxyapi-linux-amd64 -o cliproxyapi
chmod +x cliproxyapi

# 실행
./cliproxyapi --config config.yaml

2.3 소스에서 빌드

Go 환경이 구축되어 있다면 소스에서 직접 빌드할 수 있습니다.

git clone https://github.com/router-for-me/CLIProxyAPI.git
cd CLIProxyAPI
go build -o cliproxyapi ./cmd/server
./cliproxyapi --config config.yaml

2.4 brew로 빌드

brew install cliproxyapi
//혹은
brew install cliproxyapi --fetch-HEAD

2.4.1 HEAD로 설치시 업그레이드 방법

brew upgrade cliproxyapi --fetch-HEAD

2.5 재시작

brew services restart cliproxyapi

3. config.yaml 완전 가이드

3.1 기본 설정

서버의 네트워크 인터페이스와 클라이언트 인증을 위한 키를 설정합니다.

# Server configuration
host: "0.0.0.0"
port: 8317

# API keys for client authentication
api-keys:
  - "your-api-key-1"
  - "your-api-key-2"

# Logging
log-level: "info"

3.2 웹에서 수정

웹에서 수정할 때 유의해야 할 사항은, API키 메뉴에서 설정하면 오류가 나타나기 때문에 Config Management 페이지에서 수정해야 한다는 점이다.

4. API 엔드포인트 가이드

4.1 OpenAI 호환 엔드포인트

엔드포인트	메서드	설명
`/v1/chat/completions`	POST	채팅 완성 (GPT 모델 호환)
`/v1/completions`	POST	텍스트 완성
`/v1/models`	GET	사용 가능 모델 목록 조회
`/v1/responses`	POST	OpenAI Responses API 지원
`/v1/responses/compact`	POST	압축된 응답 형태 제공

4.2 Claude 호환 엔드포인트

엔드포인트	메서드	설명
`/v1/messages`	POST	Anthropic Claude Messages API 규격
`/v1/messages/count_tokens`	POST	입력 텍스트의 토큰 수 계산

4.3 Gemini 호환 엔드포인트

엔드포인트	메서드	설명
`/v1beta/models`	GET	Gemini 지원 모델 목록 조회
`/v1beta/models/*action`	POST/GET	Gemini 고유 액션 수행

4.4 직접 API 호출 테스트

서버가 정상 작동하는지 curl로 확인할 수 있습니다.

# 모델 목록 조회
curl http://localhost:8317/v1/models \
  -H "Authorization: Bearer your-api-key-1"

# 채팅 완성 요청
curl http://localhost:8317/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-api-key-1" \
  -d '{
    "model": "claude-code",
    "messages": [
      {"role": "user", "content": "Hello, world!"}
    ]
  }'

5. OpenCode와 연결하기

5.1 환경 변수 설정

OpenCode가 프록시 서버를 인식하도록 엔드포인트를 지정합니다.

# ~/.zshrc 또는 ~/.bashrc에 추가
export LOCAL_ENDPOINT="http://localhost:8317/v1"

5.2 opencode.jsonc 설정

apiKey는 프록시 설정 파일(config.yaml)에 등록한 키 중 하나를 사용합니다.

"provider": {
    "cliproxyapi": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "CLIProxyAPI",
      "options": {
        "baseURL": "http://127.0.0.1:8317/v1",
        "apiKey": "key"
      },

      "models": {
        "gpt-5.2": {
          "name": "GPT-5.2 (OpenAI)",
          "limit": { "context": 272000, "output": 128000 },
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          "variants": {
            "none":   { "reasoningEffort": "none",   "reasoningSummary": "auto",     "textVerbosity": "medium" },
            "low":    { "reasoningEffort": "low",    "reasoningSummary": "auto",     "textVerbosity": "medium" },
            "medium": { "reasoningEffort": "medium", "reasoningSummary": "auto",     "textVerbosity": "medium" },
            "high":   { "reasoningEffort": "high",   "reasoningSummary": "detailed", "textVerbosity": "medium" },
            "xhigh":  { "reasoningEffort": "xhigh",  "reasoningSummary": "detailed", "textVerbosity": "medium" }
          }
        },
        "gpt-5.2-codex": {
          "name": "GPT-5.2 Codex (OpenAI)",
          "limit": { "context": 272000, "output": 128000 },
          "modalities": { "input": ["text", "image"], "output": ["text"] },
          "variants": {
            "low":    { "reasoningEffort": "low",    "reasoningSummary": "auto",     "textVerbosity": "medium" },
            "medium": { "reasoningEffort": "medium", "reasoningSummary": "auto",     "textVerbosity": "medium" },
            "high":   { "reasoningEffort": "high",   "reasoningSummary": "detailed", "textVerbosity": "medium" },
            "xhigh":  { "reasoningEffort": "xhigh",  "reasoningSummary": "detailed", "textVerbosity": "medium" }
          }
        },
    ...

5.3 연결 테스트

환경 변수와 함께 OpenCode를 실행하여 정상 연결 여부를 확인합니다.

# OpenCode 실행
LOCAL_ENDPOINT=http://localhost:8317/v1 opencode

6. 멀티 계정 로드 밸런싱

여러 계정을 등록하면 프록시가 자동으로 요청을 분산 처리합니다.

클로드 계정을 클로드 외부에서 사용하는 것은 명백한 약관 위반이다. 개인의 철저한 책임이 요구된다. ( 예전 사진 )

레이트 리밋 회피: 여러 계정의 쿼터(Quota)를 활용하여 한계를 극복합니다.
가용성 향상: 특정 계정의 문제가 생겨도 서비스가 중단되지 않습니다.
비용 효율성: 무료 티어 계정들을 묶어서 활용할 수 있습니다.

7. OAuth 로그인

프록시 서버가 작동하려면 먼저 로컬 장치에서 각 제공자의 CLI 인증이 완료되어 있어야 합니다.

8. 트러블슈팅

8.1 연결 실패

서버가 살아있는지, 포트가 열려있는지 확인하세요.

# 서버 상태 확인
curl http://localhost:8317/health

# 로그 확인
docker logs cliproxyapi

8.2 인증 오류

api-keys 배열에 클라이언트가 사용하는 키가 포함되어 있는지 확인하세요.
HTTP 헤더에 Authorization: Bearer <Key> 형식이 정확한지 확인하세요.

8.3 모델 없음 오류

config.yaml에서 해당 모델 공급자가 enabled: true인지 확인하세요.
로컬 CLI에서 실제 로그인이 유효한지 테스트하세요.

9. 고급 설정

9.1 HTTPS 설정

보안이 필요한 환경에서 인증서를 적용할 수 있다고 나와있지만 저는 테스트해보지 못했습니다.

tls:
  enabled: true
  cert-file: "/path/to/cert.pem"
  key-file: "/path/to/key.pem"

9.2 프록시 뒤에서 실행

기업 환경 등 아웃바운드 프록시가 필요한 경우 설정할 수 있다고 되어있지만 저는 테스트해보지 못했습니다.

proxy:
  http: "http://proxy.company.com:8080"
  https: "http://proxy.company.com:8080"

9.3 로깅 설정

10. 실전 시뮬레이션

$ docker run -d -p 8317:8317 -v ./config.yaml:/app/config.yaml ghcr.io/router-for-me/cliproxyapi:latest
a1b2c3d4e5f6...

$ curl http://localhost:8317/v1/models -H "Authorization: Bearer opencode-key-12345"
{
  "object": "list",
  "data": [
    {"id": "claude-code", "object": "model", "owned_by": "anthropic"},
    {"id": "openai-codex", "object": "model", "owned_by": "openai"},
    {"id": "gemini-cli", "object": "model", "owned_by": "google"}
  ]
}

$ LOCAL_ENDPOINT=http://localhost:8317/v1 opencode

OpenCode v0.5.0
Connected to CliProxyAPI at localhost:8317
Available models: claude-code, openai-codex, gemini-cli

> 안녕하세요!
Claude Code: 안녕하세요! 무엇을 도와드릴까요?

11. 결론

CliProxyAPI는 CLI 기반 AI 모델들을 표준 OpenAI API로 통합하여 AI 인프라의 유연성을 극대화해 주는 도구입니다. 복잡한 CLI 명령어를 직접 다루지 않아도 웹에서 설정된 값으로 기존에 쓰던 도구 그대로 최신 모델의 성능을 누릴 수 있습니다.

통합: 여러 제공자의 CLI 모델을 하나의 엔드포인트로 관리
호환성: 수많은 기존 오픈소스 AI 도구들과의 즉각적인 연결
확장성: 멀티 계정 로드 밸런싱을 통한 안정적 운영

12. TL;DR

CliProxyAPI는 Claude Code, Codex, Gemini CLI를 OpenAI 호환 API로 변환해 주는 프록시입니다.
GitHub 저장소: github.com/router-for-me/CLIProxyAPI
기본 포트는 8317이며, config.yaml을 통해 인증 키를 설정합니다.
OpenCode와 연결 시 LOCAL_ENDPOINT 환경 변수를 프록시 주소로 설정하면 즉시 사용 가능합니다.
멀티 계정을 등록하면 자동으로 부하가 분산되어 레이트 리밋을 피할 수 있습니다.

13. 참고 링크

CliProxyAPI GitHub: https://github.com/router-for-me/CLIProxyAPI
OpenCode 공식 문서: https://github.com/opencode-ai/opencode
Claude Code 안내: https://docs.anthropic.com/claude/docs/claude-code
OpenAI Codex 가이드: https://platform.openai.com/docs/guides/code

'AI' 카테고리의 다른 글

OpenClaw 상세 설치 가이드 - 초보자용 (0)	2026.02.06
2026년 2월 신규모델 Claude Opus 4.6 & GPT-5.3 Codex (1)	2026.02.06
Reverse-SynthID 완벽 분석 - 구글의 워터마크를 뚫어보자 (0)	2026.02.06
[3편] OpenCode + Custom Agents 가이드 - 커스텀 에이전트와 멀티 에이전트 오케스트레이션 (1)	2026.02.05
[2편] OpenCode 심화 가이드 - Oh-My-OpenCode로 나만의 워크플로우 구축하기 (0)	2026.02.05

Isaac Note

[4편] CliProxyAPI 완벽 가이드 - CLI AI 모델을 표준 API로 통합하기

[4편] OpenCode Proxy와 모델 관리

1. CliProxyAPI란?

2. 설치 및 실행

2.1 Docker로 실행 (권장)

2.2 바이너리로 실행

2.3 소스에서 빌드

2.4 brew로 빌드

2.4.1 HEAD로 설치시 업그레이드 방법

2.5 재시작

3. config.yaml 완전 가이드

3.1 기본 설정

3.2 웹에서 수정

4. API 엔드포인트 가이드

4.1 OpenAI 호환 엔드포인트

4.2 Claude 호환 엔드포인트

4.3 Gemini 호환 엔드포인트

4.4 직접 API 호출 테스트

5. OpenCode와 연결하기

5.1 환경 변수 설정

5.2 opencode.jsonc 설정

5.3 연결 테스트

6. 멀티 계정 로드 밸런싱

7. OAuth 로그인

8. 트러블슈팅

8.1 연결 실패

8.2 인증 오류

8.3 모델 없음 오류

9. 고급 설정

9.1 HTTPS 설정

9.2 프록시 뒤에서 실행

9.3 로깅 설정

10. 실전 시뮬레이션

11. 결론

12. TL;DR

13. 참고 링크

'AI' 카테고리의 다른 글

티스토리툴바

[4편] CliProxyAPI 완벽 가이드 - CLI AI 모델을 표준 API로 통합하기

[4편] OpenCode Proxy와 모델 관리

1. CliProxyAPI란?

2. 설치 및 실행

2.1 Docker로 실행 (권장)

2.2 바이너리로 실행

2.3 소스에서 빌드

2.4 brew로 빌드

2.4.1 HEAD로 설치시 업그레이드 방법

2.5 재시작

3. config.yaml 완전 가이드

3.1 기본 설정

3.2 웹에서 수정

4. API 엔드포인트 가이드

4.1 OpenAI 호환 엔드포인트

4.2 Claude 호환 엔드포인트

4.3 Gemini 호환 엔드포인트

4.4 직접 API 호출 테스트

5. OpenCode와 연결하기

5.1 환경 변수 설정

5.2 opencode.jsonc 설정

5.3 연결 테스트

6. 멀티 계정 로드 밸런싱

7. OAuth 로그인

8. 트러블슈팅

8.1 연결 실패

8.2 인증 오류

8.3 모델 없음 오류

9. 고급 설정

9.1 HTTPS 설정

9.2 프록시 뒤에서 실행

9.3 로깅 설정

10. 실전 시뮬레이션

11. 결론

12. TL;DR

13. 참고 링크

'AI' 카테고리의 다른 글

관련글

티스토리툴바