구독 중인 AI를 내 앱에서 API로 부르려면, star-cliproxy 설치와 쓰기 전 조건

앱과 CLI 사이에 공통 주소를 하나 둔다

CLI는 터미널에서 명령으로 실행하는 프로그램이다. star-cliproxy의 기본 경로에서는 앱이 보낸 요청을 받은 프록시가 설치된 CLI를 하위 프로세스로 실행한다. 그 출력을 앱이 읽을 수 있는 응답 형식으로 바꿔 돌려준다. 저장소의 공급자 기본 코드에서 이 실행 부분을 확인할 수 있다. 요청마다 CLI를 실행하는 방식 말고도 SDK, app-server, channel-worker 같은 실행 모드가 코드에 따로 있다.

앱이 세 개이고 쓰는 AI도 세 종류라면 연결 코드가 여러 곳에 흩어진다. 프록시를 두면 모든 앱이 같은 주소에 요청하면서 모델 이름 자리에 별칭을 넣는다. 그 별칭이 어느 공급자의 어떤 실제 모델로 갈지는 대시보드의 모델 매핑이 정한다. 공급자를 바꿀 때 앱 설정은 그대로 두고 매핑만 고치면 된다. 라우터 코드는 별칭에 연결된 활성 매핑을 우선순위 값으로 정렬해 고른다. 한 매핑이 실패했을 때 다음 매핑으로 넘어가는 동작이 어디까지 되는지는 이번에 검증하지 않았다.

대시보드에는 요청 추이와 공급자별 연결 상태, 모델별 사용량이 모인다. 어떤 연결이 살아 있고 어디서 오류가 나는지를 여러 터미널을 오가지 않고 볼 수 있다. 화면의 성공률은 요청이 처리됐는지를 센 기록이다. 답변이 맞았는지를 뜻하는 숫자는 아니다.

직접 만든 앱에 글 정리 기능을 붙이는 경우가 대표적인 쓰임새다. 사용자 지정 공급자를 받는 옵시디언 플러그인에서 노트에 질문하거나 브라우저 확장에서 읽던 웹 내용을 정리하는 데도 연결할 수 있다. 어느 경우든 앱 쪽에서 접속 주소를 바꿀 수 있어야 한다.

자료: star-cliproxy 공개 저장소 · github.com · star-cliproxy 한국어 README · github.com

‘추가 과금 없이’가 맞는 범위

star-cliproxy가 요금을 없애 주지는 않는다. 앱의 요청이 이미 로그인한 CLI로 넘어가므로 그 CLI가 쓰는 구독의 포함 범위와 사용 한도 안에서 처리될 뿐이다. 어떤 작업이 구독에 포함되는지는 공급자와 실행 모드, 작업 종류에 따라 다르다. 구독과 별도로 과금되는 API가 있는지도 공급자마다 확인해야 한다.

여러 앱을 연결하면 같은 구독의 사용량을 그만큼 나눠 쓰게 된다. 평소 한도가 빠듯한 사람이라면 중요한 개발 작업에 남겨 둘 여유까지 계산해야 한다. 이번 시연에서 짧은 회의 메모 한 건을 보낸 요청은 Codex CLI의 사용량 기록상 입력 토큰이 14,716개였다. 그중 8,960개가 캐시 입력으로 잡혔다. 메모 자체의 길이보다 훨씬 큰 값이다. 이 토큰이 요금제의 한도에 어떻게 계산되는지는 확인하지 않았다.

유료 HTTP 서비스를 공급자로 등록했다면 그 서비스의 요금이 그대로 붙는다. 프록시가 내 컴퓨터에서 돈다고 추론까지 로컬에서 이뤄지는 것도 아니다. 클라우드 모델로 보낸 내용은 외부 서버에서 처리된다. 옵시디언 플러그인처럼 연결하는 앱에 유료 기능이 있다면 그 비용도 별개다.

공급자의 이용 조건은 사용자가 직접 확인할 몫이다. 이 글은 특정 요금제에서 무제한으로 쓸 수 있다거나 계정 제재 위험이 없다고 보장하지 않는다.

비슷한 도구는 푸는 문제가 다르다

비교 대상으로 삼은 도구는 셋이다. 이름이 비슷한 CLIProxyAPI와 여러 모델 API를 하나로 묶는 LiteLLM, 옵시디언 안에 AI 에이전트를 넣는 Claudian이다. 2026년 9월 14일 각 저장소의 README와 일부 코드를 특정 커밋에 고정해 읽었다. 속도나 성공률, 계정 제재율을 나란히 재는 실험은 하지 않았다.

CLIProxyAPI는 README 기준으로 OAuth 로그인과 여러 계정의 라운드로빈 라우팅, API 형식 변환을 다루며 관리 앱도 제공한다. 확인한 Codex 실행 코드는 인증 정보와 기본 URL을 이용해 서버에 HTTP 요청을 직접 보냈다. star-cliproxy의 기본 CLI 경로는 설치된 CLI 프로그램을 실행해 그 출력을 받는다. 인증과 실행을 어느 쪽이 맡는지가 다르다. 코드 경로 하나를 확인했을 뿐이라 CLIProxyAPI의 모든 경로가 같다고 일반화할 수는 없다. 실행 구조가 다르다고 해서 공급자 정책상 어느 쪽이 더 안전하다는 뜻이 되지도 않는다.

LiteLLM은 SDK와 게이트웨이로 여러 모델 API를 공통 형식으로 부르게 하고 가상 키와 비용 추적, 관리 UI, 부하 분산을 제공한다. 팀이나 서비스 단위로 API 연결과 예산을 관리하려는 쪽에 가깝다. Claudian은 옵시디언 안에서 Claude Code나 Codex 같은 하네스로 노트를 편집하고 검색하며 bash를 실행하는 플러그인이다. 옵시디언 안의 작업만 필요하다면 공통 프록시 없이 이런 직접 통합을 쓰는 편이 더 간단할 수 있다.

자료: CLIProxyAPI README, 커밋 7fa443d · github.com · CLIProxyAPI의 Codex 실행 코드 · github.com · LiteLLM README, 커밋 30f33a9 · github.com · Claudian README, 커밋 2c07ee6 · github.com

설치는 Git, Node.js, 로그인된 CLI 하나에서 시작한다

준비물은 소스 코드를 받을 Git과 프로젝트를 실행할 Node.js 20 이상, 이미 로그인해 둔 AI CLI 하나다. 연결할 CLI 쪽에 더 높은 요구사항이 있을 수 있으니 개별 도구의 설치 조건도 함께 본다. 공급자 로그인은 각 CLI의 공식 절차로 마친다.

Codex나 Claude Code 같은 코딩 에이전트에게 설치를 맡기는 방법이 가장 손이 덜 간다. 저장소 주소를 건네며 현재 README와 설정 예제를 읽고 설치하라고 요청한다. 이때 조건을 몇 가지 붙여 두는 편이 안전하다. 기존 설치나 실행 중인 인스턴스가 있는지 확인해 덮어쓰거나 중복 실행하지 않게 한다. 관리자 토큰과 프록시 접근 키는 새로 만들어 .env 파일에만 두고 화면에 출력하거나 커밋하지 않게 한다. 공식 로그인은 사용자가 직접 하도록 안내받는다. 공급자 하나와 모델 별칭 하나를 등록해 Playground에서 첫 응답까지 확인한 뒤 API 주소와 대시보드 주소, 앱에 넣을 설정 항목을 알려 달라고 하면 된다.

.env의 두 키는 관리자 토큰과 프록시 접근 키다. 관리자 토큰은 관리 기능에 쓰고 프록시 접근 키는 앱이 프록시에 요청할 때 쓴다. 예제에 들어 있는 기본 문자열은 반드시 새 값으로 바꾼다. 테크독해가 정리한 예시는 Node.js의 crypto 모듈로 관리자 토큰에 32바이트, 프록시 키에는 sk-proxy- 뒤에 24바이트 무작위 값을 16진수로 붙인다. 파일은 이미 있으면 실패하도록 쓰고 권한은 소유자만 읽고 쓰는 600으로 둔다. 만든 키는 콘솔에 표시하지 않는다.

직접 설치한다면 아래 다섯 단계를 거친다. 서버가 뜨면 기본 주소는 API가 http://localhost:8300, 관리 화면이 http://localhost:5300이다. 포트를 바꿨다면 실제 설정에 맞는 주소로 접속한다.

• git clone https://github.com/starhunt/star-cliproxy.git 로 저장소를 받은 뒤 star-cliproxy 폴더로 이동한다.
• npm install 로 의존성을 설치하고 npm run build 로 빌드한다.
• config.example.yaml 을 config.yaml 로 복사한다. 사용할 CLI의 실행 경로와 활성화 여부를 확인하고 쓰지 않는 공급자는 필요에 맞게 끈다.
• 저장소 폴더에 .env 파일을 새로 만들고 ADMIN_TOKEN 과 PROXY_API_KEY 두 값을 넣는다. 프록시 접근 키는 sk-proxy- 로 시작하게 만든다.
• npm run dev:all 로 API 서버와 대시보드를 함께 띄운다. README의 방식처럼 두 터미널에서 npm run dev 와 npm run dev:dashboard 를 따로 실행해도 된다.

새 폴더에서 다시 설치해 보니

2026년 9월 14일 공개 저장소의 커밋 796b648을 임시 폴더에 새로 복제해 같은 순서를 밟았다. 복제와 npm install, npm run build가 모두 오류 없이 끝났다. 운영 중인 인스턴스와 포트가 겹치지 않게 API를 18326번, 대시보드를 15326번으로 띄웠다. 상태 확인 요청과 대시보드는 각각 HTTP 200을 돌려줬고 인증을 붙인 모델 목록 요청에도 응답이 왔다. 확인을 마친 뒤 두 서비스는 종료했다.

포트를 바꾸다 걸린 부분이 있었다. package.json의 dev:dashboard 스크립트에 --port 5300이 들어 있어서 환경 변수로 포트를 바꿔도 이 값이 우선했다. 대시보드 포트를 바꾸려면 npm run dev --workspace=packages/dashboard -- --port 15326처럼 Vite 인수를 직접 넘겨야 한다. Vite가 IPv6 localhost에 바인딩돼 있어서 127.0.0.1 대신 실행 화면에 표시된 localhost 주소로 접속해 확인했다.

npm install 단계에서 npm은 의존성 취약점 20건을 보고했다. 낮음 3건, 중간 8건, 높음 9건이다. 이번 확인에서는 이 경고의 세부 내용을 분석하지 않았다.

공급자 하나, 별칭 하나, 첫 응답

대시보드의 Providers 화면에서 사용할 CLI가 켜져 있는지 본다. Codex 항목을 펼치면 CLI 경로와 기본 모델, 최대 동시 처리 수, 타임아웃, 실행 모드가 나온다. 기본 제공 공급자는 실행 중에 활성화 여부와 기본 모델, 동시 실행 수, 타임아웃, 실행 모드 옵션만 바꿀 수 있다. CLI 경로처럼 화면에서 잠긴 항목은 설정 파일에서 맞춘다. 그 전에 터미널에서 해당 CLI 자체가 정상 응답하는지 확인해 두는 편이 좋다.

Model Mappings 화면에서는 앱이 부를 별칭과 요청을 보낼 공급자, 공급자가 알아듣는 실제 모델 이름을 따로 입력한다. 이번에는 별칭 my-ai를 Codex 공급자의 gpt-5.6-luna 모델에 연결했다. my-ai는 설명용으로 붙인 이름이라 기본으로 등록돼 있지 않다. 실제 모델 이름은 연결한 CLI가 지원하는 목록을 보고 넣는다.

Playground에서는 등록한 별칭을 고른 뒤 공개해도 되는 짧은 입력을 보낸다. 시연에는 미리 써 둔 가상의 회의 메모를 넣었다. 다음 주 월요일 베타 테스트를 시작하고 민수는 금요일까지 설치 안내를, 지연은 토요일까지 오류 제보 양식을 맡으며 가격은 아직 정하지 않았다는 내용이다. 외부 검색이나 파일, 도구를 쓰지 말라는 조건을 붙였더니 결정 사항과 담당자별 할 일로 나뉜 답이 돌아왔다. Playground에서 응답이 오면 공급자와 모델 연결은 확인된 셈이다. 실제 앱은 그다음에 붙여야 문제가 생긴 구간을 좁히기 쉽다.

같은 입력을 스트리밍으로 보냈을 때는 운영 인스턴스의 Playground가 답을 추론 본문 영역에 띄웠고 끝부분이 잘려 보였다. Debug에 남은 CLI 원본 출력에는 전체 답이 있었다. 제품 쪽 표시 문제이며 이번 작업에서는 고치지 않았다.

등록과 응답 확인은 운영자가 평소 쓰는 인스턴스에서 했다. 이 인스턴스에는 공개 저장소에 아직 커밋되지 않은 로컬 수정이 일부 있다. 시연용으로 만든 별칭은 확인 후 지웠다.

앱에는 주소, 프록시 키, 별칭 세 값을 넣는다

OpenAI 호환 공급자나 사용자 지정 주소를 지원하는 앱이라면 접속 주소와 프록시 접근 키, 등록한 모델 별칭을 맞추면 된다. 관리자 토큰은 앱에 넣지 않는다. 모든 앱이 주소 변경을 허용하지는 않으니 쓰려는 앱의 설정 화면부터 확인한다.

Python 프로그램에서는 OpenAI의 Python SDK를 그대로 쓸 수 있다. 프로젝트 환경에 pip install openai로 SDK를 설치하고 클라이언트를 만들 때 base_url을 http://localhost:8300/v1로 지정한다. api_key에는 환경 변수 CLIPROXY_API_KEY에 넣어 둔 프록시 접근 키를 쓴다. chat.completions.create의 model 자리에 my-ai를 넣으면 메시지를 보내고 답을 받는 방식은 평소와 같다. 같은 별칭으로 Python SDK에서 한 문장 요약을 요청했더니 약 4.9초 뒤 답이 왔다. 한 번 실행한 기록이다.

다른 기기에서 앱을 실행한다면 그 기기에서 localhost는 그 기기 자신을 가리킨다. 프록시가 돌아가는 장비의 주소와 접근 설정이 따로 필요하다.

옵시디언 Copilot 플러그인은 2026년 9월 14일 공식 문서 기준으로 Settings의 Copilot 항목에서 BYOK, Add a provider, Add a custom provider 순서로 들어간다. Base URL과 프록시 키, 모델 ID인 my-ai를 넣고 Test와 Save를 누른다. 처음에는 Quick Chat에서 이 모델을 골라 현재 노트에 질문해 보는 편이 낫다. 문서에 따르면 새 BYOK 모델은 Quick Chat과 호환되는 opencode 경로에 연결되며 Claude나 Codex 에이전트 모델 목록과는 따로 관리된다. 전체 노트 검색까지 하려면 임베딩과 색인을 추가로 구성해야 할 수 있다. 플러그인의 유료 기능은 별개다.

브라우저에서는 옵시디언 Web Clipper의 Interpreter처럼 사용자 지정 공급자를 받는 확장을 쓸 수 있다. 어떤 확장은 /v1까지만 받고 어떤 확장은 /v1/chat/completions까지 전체 요청 주소를 요구하므로 둘을 구분해 넣는다.

Copilot과 Web Clipper 연결은 공식 설정 문서를 근거로 한 안내다. 이번에 실제 앱에서 끝까지 연결해 보지는 않았다. 앱 버전에 따라 모델 목록을 가져오는 방식이나 설정 위치가 달라질 수 있다.

자료: Obsidian Copilot LLM 공급자 설정 · docs.obsidiancopilot.com · Obsidian Web Clipper Interpreter · obsidian.md

답이 이상할 때 Debug 화면에서 보는 것

Debug 화면은 앱이 실제로 보낸 요청 메시지와 CLI의 원본 표준 출력·표준 오류, 파싱을 거친 최종 결과를 요청 단위로 보여 준다. HTTP 공급자라면 HTTP 요청과 응답 데이터가 남는다. 실행된 명령을 복사하는 기능도 있다. 네트워크 패킷을 엿보는 기능은 아니다. 프록시가 처리한 내용을 기록해 두는 방식이다.

문제가 난 모델에 상세 캡처를 켜고 공개해도 되는 입력으로 같은 요청을 다시 보낸다. 요청 메시지와 원본 출력, 파싱된 결과를 차례로 대조하면 앱이 문맥을 빠뜨렸는지, CLI가 오류를 냈는지, 결과를 변환하다 어긋났는지 가를 수 있다. 인증값이 가려진 상태로 복사한 명령은 그대로 실행되지 않을 수 있다. 기록에는 입력 내용이 남는다. 다른 사람과 공유하기 전에 비밀정보가 섞이지 않았는지 확인해야 한다.

첫 요청이 실패했다면 구간을 나눠 본다. Playground부터 실패할 때는 CLI 로그인과 모델 이름, 실행 경로를 살핀다. Playground는 되는데 앱만 실패한다면 주소 끝부분과 키, 별칭, 클라이언트 타임아웃, 브라우저 권한이나 CORS가 확인 대상이다. 답은 오는데 내용이 이상할 때는 실제로 전송된 문맥과 원본 출력을 대조한다.

목록에 없는 CLI와 로컬 모델 서버

기본 공급자 목록에 없는 CLI는 커스텀 CLI로 등록한다. 실행 파일 경로와 명령 인자 템플릿, 입력을 넘기는 방식, 출력에서 답을 읽는 규칙을 맞춘다. 표준 입력으로 질문을 받는지, JSON 출력의 어느 항목에 답이 담기는지 같은 정보다. 목록 밖의 CLI라고 해서 모든 출력 형식이 자동으로 지원되지는 않는다.

설정만으로 맞출 수 없는 변환이나 특수 기능은 코드 플러그인으로 구현한다. 본체 코드를 고치지 않고 공급자를 추가할 수 있도록 플러그인 인터페이스가 따로 마련돼 있다.

Ollama나 vLLM처럼 모델 서버를 이미 운영하고 있다면 HTTP 공급자로 등록하는 길도 있다. 서버의 Base URL과 모델, 인증, 대화나 임베딩 같은 엔드포인트 종류를 설정한 뒤 별칭에 연결한다. 쓸 수 있는 기능은 그 서버가 제공하는 범위까지다. 이번 확인에서 커스텀 CLI와 HTTP 공급자는 등록 화면을 살펴보는 데 그쳤다. 새 서버를 붙여 끝까지 시험하지는 않았다.

API 형식이 호환된다고 모든 기능이 같아지지는 않는다. 앱이 도구 호출을 쓰려면 Tool Bridge 공급자 지원 여부와 클라이언트 쪽 실행 구성을 확인해야 한다. 운영 화면의 설명에 따르면 Tool Bridge는 OpenAI 호환 클라이언트의 도구를 지원 CLI의 구조화 출력으로 바꿔 주고, 실제 도구 실행은 요청한 클라이언트가 맡는다.

맞는 사람과 덜 맞는 사람

이 도구를 고를 이유는 세 가지로 모인다. 이미 쓰는 CLI를 여러 앱에 연결할 수 있다. 모델 교체를 한곳에서 관리한다. 실패한 요청의 입력과 출력을 추적할 수 있다. AI를 쓰는 곳이 많은 사람일수록 반복하던 연결 설정이 줄어든다.

대가도 있다. 프록시를 늘 켜 두고 관리해야 하고, 연결한 CLI의 로그인 상태와 버전이 바뀌면 프록시 동작도 영향을 받는다. 여러 앱이 같은 구독 사용량을 나눠 쓴다는 점도 앞에서 적은 그대로다.

자기 계정으로 여러 개인 프로젝트와 호환 앱을 연결하려는 사람에게 맞는 구조다. 팀 전체의 API 예산을 관리해야 한다면 LiteLLM이, 옵시디언 안에서만 에이전트를 쓰려면 Claudian이 더 맞을 수 있다. 처음부터 모든 기능을 설정할 필요는 없다. 공급자 하나와 모델 별칭 하나를 등록하고 Playground에서 응답을 확인한 다음 실제로 쓸 앱 하나를 붙여 보면 된다. Debug와 다른 공급자는 그 뒤에 넓혀도 된다.