bizrouter CLI

쓰던 코딩 에이전트를 그대로 두고 명령 앞에 bizrouter만 붙이면 BizRouter로 연결됩니다. 로그인한 뒤에는 BizRouter 콘솔(API 키·정책·감사 로그·통계)도 명령으로, 또는 에이전트의 MCP 도구로 다룰 수 있습니다.

npm install -g bizrouter        # 또는: curl -fsSL https://bizrouter.ai/install.sh | bash
bizrouter login                 # 브라우저에서 코드를 확인하고 승인합니다 (한 번만)
bizrouter claude                # Claude Code
bizrouter codex                 # Codex CLI
bizrouter opencode              # OpenCode
bizrouter hermes                # Hermes

설치 없이 바로 써 볼 수도 있습니다: npx bizrouter claude

로그인이 해 주는 것

bizrouter login은 터미널에 8자리 코드를 보여주고 브라우저에서 BizRouter 콘솔을 엽니다. 콘솔에 로그인(비밀번호·Google·웍스AI·2차 인증 그대로)한 뒤 코드를 확인하고 「승인」하면

• 이 기기용 콘솔 세션(기본 30일. 조직이 미사용 자동 로그아웃을 정했다면 콘솔 API를 쓰지 않은 시간이 그 기준을 넘을 때 더 일찍 만료되며, 그러면 bizrouter login을 다시 실행하십시오)과
• 이 기기 이름의 API 키(모델 호출용)가 함께 발급되어 ~/.bizrouter/credentials.json에 권한 600으로 저장됩니다.

키만 붙여 넣던 방식도 그대로 됩니다: bizrouter login --with-key. CI·컨테이너에서는 BIZROUTER_API_KEY(모델 호출)·BIZROUTER_SESSION_TOKEN(콘솔) 환경 변수가 저장된 값보다 우선합니다. 세션은 콘솔 「계정 → 로그인된 기기」에서 언제든 종료할 수 있습니다.

코딩 에이전트 실행

| 도구 | 실행 시 하는 일 | 설정 파일 변경 | | --- | --- | --- | | Claude Code | ANTHROPIC_BASE_URL=https://api.bizrouter.ai/claude, 토큰, 빈 ANTHROPIC_API_KEY, 모델 선택창 자동 채움(이 키로 쓸 수 있는 채팅 모델 전체)을 넘기고, 사용자 settings.json의 다른 게이트웨이 설정이 이기지 못하도록 명령행 settings로 고정 | 없음 | | Codex CLI | -c 오버라이드로 BizRouter provider(Responses API)와 모델·추론 강도 지정 | 없음 | | OpenCode | OPENCODE_CONFIG_CONTENT로 이 키가 쓸 수 있는 모델 전체가 담긴 bizrouter provider를 주입 | 없음 | | Hermes | custom provider(CUSTOM_BASE_URL/CUSTOM_API_KEY)와 모델을 이번 실행에만 지정 | 없음 |

도구는 평소처럼 실행됩니다. 바뀌는 것은 그 실행에서 모델을 호출하는 주소와 인증뿐이어서, 화면과 사용법은 같고 과금·모델 정책·감사 로그는 BizRouter 콘솔에 남습니다. bizrouter 없이 실행하면 평소대로 동작합니다. 우리 옵션 뒤의 인자는 도구에 그대로 전달됩니다.

한 가지 예외가 있습니다. bizrouter claude로 나눈 대화는 bizrouter/deepseek-v4.1-flash[1m]처럼 BizRouter 전용 모델 ID를 기록하므로, 이어 갈 때도 bizrouter claude --resume(직전 대화는 --continue)을 써야 합니다. Claude Code는 종료할 때 claude --resume <id>를 안내하는데, bizrouter 없이 실행한 claude는 BizRouter 연결이 없어 그 모델 ID를 Anthropic에 보내고 첫 메시지에서 There's an issue with the selected model 오류가 납니다. 그래서 bizrouter claude는 대화형 세션이 끝나면 이 명령을 한 번 안내합니다. 대화에 기록된 모델은 CLI가 알 수 없으므로 모든 대화형 종료에서 안내하며, -p로 한 번 묻고 끝나는 실행과 --version·mcp 같은 하위 명령에서는 안내하지 않습니다.

Claude Code는 컨텍스트 창 크기를 모델 ID의 [1m] 마커로만 판단합니다(모델 목록의 context_length는 무시). 그래서 bizrouter claude는 모델을 지정하지 않으면 이 키가 쓸 수 있는 1M 컨텍스트 Claude 모델(Sonnet 우선)을 ANTHROPIC_MODEL=<모델>[1m]으로 넘기고, 직접 지정한 1M 모델에도 마커를 붙입니다. bizrouter claude --model bizrouter/deepseek-v4.1-flash처럼 원래 카탈로그 ID만 입력하면 됩니다. [1m]은 Claude Code가 1M 창을 계산하도록 하는 호환 표기이지 별도 모델이나 속도 모드가 아닙니다. 게이트웨이는 이 표기를 제거하고 원래 모델 ID로 호출합니다. 200k 모델에는 붙이지 않습니다. 1M 입력은 표준 단가로 과금됩니다.

Claude 외 1M 모델은 실제 입력 한도가 1M보다 작을 수 있습니다(예: GPT-6.1 Sol은 922,000 토큰). Claude Code는 모르는 모델을 스스로 정한 임계값에서 압축하지 않고 제공사의 컨텍스트 초과 오류를 기다리므로, bizrouter claude는 이런 모델마다 실제 입력 한도(최대 1M)를 Claude Code의 modelSettings.<모델>.autoCompactWindow로 실행 설정에 함께 넘깁니다. 세션은 그 한도보다 약 33,000 토큰 앞에서 자동 압축합니다. 세션 안에서 /model로 바꾼 모델에도 적용됩니다.

bizrouter claude --model anthropic/claude-opus-5 -p "실패하는 테스트 고쳐줘"
bizrouter claude --model bizrouter/glm-5.3     # GPT·Gemini·GLM·Kimi 등 이 키가 쓸 수 있는 모든 채팅 모델
bizrouter codex --model openai/gpt-5.5 --reasoning-effort high exec "README 요약해줘"
bizrouter opencode --model google/gemini-3.5-pro
bizrouter claude --dry-run          # 실행 대신 넘겨줄 환경 변수와 명령을 보여줍니다

콘솔 세션이 있으면 Claude Code·Codex·OpenCode에 이 CLI가 MCP 서버 bizrouter 로 함께 연결됩니다. 에이전트는 bizrouter_api(콘솔 API 호출)·bizrouter_openapi(API 탐색)·bizrouter_docs(문서)·bizrouter_models·bizrouter_whoami·bizrouter_search(Search) 도구로 API 키를 만들고, 정책을 바꾸고, 사용량을 읽고, 실제 데이터를 찾아 답합니다. 데이터를 바꾸는 호출은 사용자 확인 뒤 confirm: true를 받아야만 실행됩니다. --no-mcp로 끕니다.

Search — 실제 데이터를 찾아 답하기

bizrouter search는 BizRouter Search(POST /v1/search)를 호출합니다. 모델이 질문에 맞는 출처(법령·국회, 기업 공시·재무, 부동산 실거래, 국가통계·금리, 교통, 논문·임상, 웹 검색·뉴스, 날씨, 지도, 미국 주식 등 50종 이상)를 골라 조회한 뒤 출처와 함께 답합니다. 조회는 무료이고 모델 토큰만 과금됩니다.

bizrouter search "근로기준법 60조 연차 휴가 조문"
bizrouter search "한국은행 기준금리 최근 결정" --model openai/gpt-5.5
bizrouter search "삼성전자 2024년 매출" --json | jq '.bizrouter_search.sources'
echo "인천공항 오늘 출발 지연 편" | bizrouter search --no-stream

bizrouter opencode --search                     # OpenCode 세션 전체에 Search 를 켬 (<모델>:search)
bizrouter hermes --search --model openai/gpt-5.5

답은 stdout, 출처·조회 횟수·라운드·모델·비용 한 줄은 stderr로 나옵니다. 로그인한 뒤 실행한 Claude Code·Codex·OpenCode 안에서는 MCP 도구 bizrouter_search로 같은 일을 합니다. Claude Code(Messages API)·Codex(Responses API)는 :search 접미사를 쓸 수 없으므로 이 도구가 두 에이전트에서 Search를 쓰는 길입니다.

콘솔 관리 명령

모두 --json을 지원하고, 데이터를 바꾸는 명령은 터미널에서 확인을 묻거나 --yes를 요구합니다.

bizrouter api --list [검색어]                      # 콘솔 API 전체 목록 (라이브 OpenAPI 기준)
bizrouter api --schema PATCH /organizations/settings   # 필드 확인
bizrouter api /statistics/ -q start_date=2026-09-01    # 아무 콘솔 API 호출
bizrouter api POST /api-keys -d '{"name":"ci"}' --yes

bizrouter keys list|create|update|delete           # API 키 (한도·기간·허용 모델·허용 IP)
bizrouter usage [--from --to] [--by model|key|day] # 사용 금액·요청 수
bizrouter billing                                  # 크레딧·월별 청구
bizrouter org show|members|settings [k=v]          # 조직·구성원·감사 로그 저장 등 조직 설정
bizrouter audit list|show <id>|stats               # 요청 감사 로그
bizrouter routing policy|presets|profiles|logs     # 스마트 라우팅
bizrouter security show|set|access                 # 보안 필터·콘솔 접근 통제
bizrouter docs [주제]                              # 에이전트 매뉴얼(AGENT_MANUAL.md)·개발 문서
bizrouter mcp                                      # MCP 서버(stdio)로 직접 실행

에이전트에게 맡길 때는 bizrouter docs가 출력하는 매뉴얼을 먼저 읽히면 됩니다. 사람용 개발 문서(https://bizrouter.ai/docs)는 같은 소스에서 만든 https://bizrouter.ai/llms-full.txt로도 제공됩니다.

그 밖의 명령

bizrouter models [검색어]        # 이 키로 쓸 수 있는 모델·컨텍스트·원화 단가
bizrouter search "질문"          # Search 호출 (--model, --max-tokens, --json, --no-stream)
bizrouter doctor                 # 키·세션·연결·설치·충돌 점검
bizrouter setup claude|codex|opencode   # 도구 설정 파일에 BizRouter를 영구 등록 (백업 생성)
bizrouter setup codex --app      # Codex 데스크톱 앱(Windows·macOS)용: 키를 config.toml에 저장하고 모델 목록 파일을 만듦
bizrouter setup codex --undo     # setup codex가 쓴 것만 지움 (키·모델 목록 파일 포함, 나머지 설정은 그대로)
bizrouter setup claude-desktop   # Claude 데스크톱 앱(타사 추론 모드)에 BizRouter 게이트웨이 등록 (--undo, --3p-only, --dry-run)
bizrouter auth / logout / env / update

Codex 데스크톱 앱

Dock이나 시작 메뉴에서 여는 앱은 셸의 환경 변수를 받지 못하므로, 환경 변수에서 키를 읽는 bizrouter setup codex만으로는 앱이 「Missing environment variable」로 실패합니다. 앱에서도 쓰려면 bizrouter setup codex --app을 실행하십시오.

• API 키를 config.toml의 BizRouter provider에 experimental_bearer_token으로 저장합니다(파일은 0600). 백업(config.toml.bak-<시각>)에서는 키를 가립니다.
• 이 키로 쓸 수 있는 채팅 모델 목록을 Codex 형식으로 config.toml 옆 bizrouter-models.json에 저장하고 model_catalog_json으로 가리킵니다. Codex는 인라인 키일 때 커스텀 provider의 모델을 네트워크로 찾지 않아, 이 파일이 없으면 앱의 모델 선택창에 Codex 기본 목록이 나옵니다. 새 모델이 추가되면 명령을 다시 실행해 갱신하십시오.
• 직접 지정한 model_catalog_json이 있으면 건드리지 않습니다.
• 터미널의 bizrouter codex는 -c로 env_key를 넘기고 Codex는 env_key를 인라인 키보다 먼저 쓰므로, 파일의 키가 낡아도 영향이 없습니다. bizrouter doctor가 파일의 키와 지금 키가 다른지 알려 줍니다.
• --undo는 API 키나 네트워크 없이 동작하며, setup codex가 쓴 provider 블록·기본 provider/모델 지정·모델 목록 파일만 지웁니다.

Claude 데스크톱 앱

Claude 앱에는 Anthropic 로그인 없이 외부 게이트웨이를 쓰는 「타사 추론」 모드가 있고, 앱의 설정 창(개발자 → 타사 추론 설정…)이 주소와 키를 입력받습니다. bizrouter setup claude-desktop은 그 창이 저장하는 것과 같은 파일을 대신 씁니다.

• <앱 3P 폴더>/configLibrary/_meta.json(appliedId·entries)과 <uuid>.json(inferenceProvider: gateway, inferenceGatewayBaseUrl: https://api.bizrouter.ai/claude, inferenceGatewayApiKey, inferenceGatewayAuthScheme: bearer). 폴더는 macOS ~/Library/Application Support/Claude-3p, Windows %LOCALAPPDATA%\Claude-3p(Store 설치본은 Packages\…Claude…\LocalCache\Local\Claude-3p가 있으면 그쪽), Linux ~/.config/Claude-3p.
• 주소에 /v1을 붙이지 않습니다. 앱이 /v1/models·/v1/messages를 직접 붙입니다.
• 이름이 BizRouter인 항목 하나만 만들고 갱신하며, 앱에 이미 있는 다른 설정은 그대로 둡니다. _meta.json은 쓰기 전에 백업합니다. _meta.json을 읽을 수 없거나 구조가 다르면 아무것도 쓰지 않습니다.
• 키는 먼저 평문으로 들어가고, 앱이 처음 시작할 때 OS 보안 저장소로 옮기고(__sealed__: 값으로 바뀜) 파일의 평문을 지웁니다(macOS에서 확인).
• --3p-only는 deploymentMode: "3p"도 써서 Claude 계정 로그인 선택지를 숨깁니다. --undo는 BizRouter 항목과 파일을 지우고 적용 항목을 이전 설정으로 돌립니다.
• 이 파일 형식은 앱의 내부 형식이라(공식 문서는 설정 창과 MDM만 설명) 앱 업데이트로 바뀔 수 있습니다. 구조가 달라지면 명령이 쓰지 않고 멈추고, bizrouter doctor가 앱에 저장된 BizRouter 주소가 맞는지 확인합니다. 앱은 실행 중에 이 파일을 다시 읽지 않으므로 명령 뒤 앱을 완전히 종료했다가 여세요.

알아둘 것

• Claude Code에서도 이 키가 쓸 수 있는 채팅 모델 전체를 씁니다. /model 선택창에는 Claude 모델은 그대로, 나머지는 claude-code/ 접두를 붙여(예: claude-code/bizrouter/glm-5.3[1m]) 나타나고, --model이나 /model에는 접두 없는 카탈로그 ID를 그대로 써도 됩니다. Claude 외 모델로 갈 때 게이트웨이가 Claude Code가 항상 보내는 Anthropic 전용 힌트(cache_control, thinking, context_management, 이전 턴 thinking 블록)를 떼어 내며, 뗀 cache_control 개수는 응답 헤더 x-bizrouter-cache-control-dropped로 알립니다. 1M 컨텍스트 모델에는 [1m]을 붙여 Claude Code가 200k로 잘못 계산하지 않게 합니다.
• 콘솔 세션은 로그인한 사용자의 권한(owner/member)을 그대로 따릅니다. 구성원(member)은 자기 API 키와 사용량만 다룰 수 있습니다.
• API 키(sk-br-v1-…)의 권한은 예전과 같습니다. 모델 호출만 되고, 콘솔 관리는 브라우저에서 승인한 사람의 콘솔 세션으로만 됩니다. 범위는 그 사람이 웹 콘솔에서 할 수 있는 일과 같습니다.
• 콘솔의 「사용량 조회 API」 키는 별개의 읽기 전용 키입니다. CLI는 쓰지도 바꾸지도 않습니다.
• credentials.json의 세션 토큰은 최대 30일짜리 콘솔 로그인입니다. 공유하거나 저장소에 넣지 말고, 의심스러우면 콘솔 「계정 → 로그인된 기기」에서 종료하십시오.
• 요구 사항: Node.js 18 이상. 각 코딩 에이전트는 따로 설치돼 있어야 합니다.

문서: https://bizrouter.ai/docs/cli