Goose를 커스텀 OpenAI 호환 엔드포인트에서 실행하기.

빠른 답: openai 프로바이더는 유지하고, 호스트만 오버라이드.

Goose는 문서화된 커스텀 엔드포인트 경로를 제공합니다: GOOSE_PROVIDER는 openai로 그대로 두고, 그 프로바이더가 가리키는 곳만 오버라이드하면 됩니다. OPENAI_HOST가 기본 api.openai.com 호스트를 대체하고, OPENAI_API_KEY가 인증하며, GOOSE_MODEL이 정확한 id로 모델을 선택합니다. 요청 경로는 별개입니다: OPENAI_BASE_PATH는 기본값이 v1/chat/completions이며 보통 변경할 필요가 없습니다. 이 형태는 조심해서 봐야 합니다. 이 부류의 대부분의 도구와 정반대이기 때문입니다: OPENAI_HOST는 /v1 접미사 없이 호스트만 있는 https://api.apisrouter.com을 받습니다. /v1/chat/completions 부분은 OPENAI_BASE_PATH에 있습니다. 호스트에 /v1을 덧붙이면 경로가 중복되어, 게이트웨이가 고장 난 것처럼 보이는 404가 발생합니다.

export GOOSE_PROVIDER=openai
export OPENAI_HOST=https://api.apisrouter.com   # bare host, no /v1
export OPENAI_API_KEY=sk-APIsRouter-...
export GOOSE_MODEL=claude-sonnet-4-6

goose session

Goose가 프로바이더와 통신하는 방법.

Goose(GitHub의 block, 약 5.1만 스타)는 Block의 자율 엔지니어링 에이전트로, 작업을 계획하고, 파일을 수정하고, 셸 명령을 실행하고, MCP 기반 확장을 구동합니다. 이 모든 것은 하나의 모델 대화 위에 놓여 있습니다: 루프의 모든 단계가 툴 정의가 첨부된 /v1/chat/completions 요청이므로, 프로바이더 설정이 전체 에이전트가 실행되는 위치를 결정합니다. 설정은 계층화되어 있습니다. 대화형 경로는 goose configure이며, openai 프로바이더의 경우 API 키와 선택적인 커스텀 호스트를 물어본 다음, GOOSE_PROVIDER와 GOOSE_MODEL 같은 비밀이 아닌 설정을 ~/.config/goose/config.yaml에 씁니다. 데스크톱 앱도 같은 프로바이더 설정을 자체 UI로 노출합니다. 시크릿은 별도로 처리됩니다: 키는 시스템 키체인으로 가거나 환경 변수에서 가져오며, config.yaml에 직접 붙여넣은 키는 읽히지 않고 무시됩니다. 환경 변수는 파일보다 우선하며, 이 덕분에 위의 env 경로가 노트북 셸에서 CI 러너에 이르기까지 어디서나 작동합니다. Goose는 GOOSE_MODEL을 그대로 문자열로 전달하므로, id는 OPENAI_HOST 뒤의 엔드포인트가 제공하는 어떤 것이든 될 수 있습니다: 오늘은 Claude id, 내일은 Kimi나 Qwen id — 변수 하나 차이입니다.

선언적 경로: 커스텀 프로바이더 파일.

환경 변수 오버라이드 외에도, 현재 Goose 문서는 선언적 커스텀 프로바이더도 설명합니다: ~/.config/goose/custom_providers/(Windows에서는 플랫폼별 설정 디렉터리)에 넣는 JSON 파일로, 내장 프로바이더와 나란히 이름이 붙은 프로바이더를 등록합니다. 이 파일은 엔진(chat-completions 엔드포인트라면 openai), 키를 담을 환경 변수, 엔드포인트 URL, 프로바이더가 제공하는 모델을 선언합니다. 여기서는 URL 관례에 주의하세요. 다시 뒤집히기 때문입니다: OPENAI_HOST와 달리, 커스텀 프로바이더의 base_url은 경로까지 포함한 전체 요청 URL입니다: https://api.apisrouter.com/v1/chat/completions. 각 models 항목은 context_limit을 가지고 있어 Goose가 채워 넣을 수 있는 윈도우를 알 수 있게 해줍니다. 선언적 파일은 게이트웨이가 openai 슬롯을 차지하는 대신, Goose의 프로바이더 목록에 자체 키 변수를 가진 독립된 이름의 프로바이더로 나타나기를 원할 때 더 적합합니다. 환경 변수 오버라이드는 CI와 빠른 전환에 더 적합합니다. 둘 다 같은 엔드포인트로 이어지므로, 하나만 골라 쓰고 겹쳐 쓰지 마세요.

{
  "name": "apisrouter",
  "display_name": "APIsRouter",
  "engine": "openai",
  "api_key_env": "APISROUTER_API_KEY",
  "base_url": "https://api.apisrouter.com/v1/chat/completions",
  "models": [
    { "name": "claude-sonnet-4-6", "context_limit": 200000 },
    { "name": "claude-opus-4-7",   "context_limit": 200000 },
    { "name": "kimi-k2.7-code",    "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

자율 에이전트를 위한 모델 선택.

실용적인 작업 흐름은 작업 세트를 고정해 두고 GOOSE_MODEL을 두세 후보에 걸쳐 몇 세션씩 돌려보는 것입니다. 모든 후보가 같은 키를 통해 라우팅되므로, 키별 사용량 뷰가 여러분 쪽에서 별도로 장부를 정리할 필요 없이 각 실험의 비용을 알려줍니다.

• Goose는 사람 개입 없이 계획, 수정, 실행, 출력 읽기, 반복을 이어갑니다. 순수한 유창함보다 툴 호출의 신뢰성이 더 중요하며, 이것이 사람들이 메인 루프에서 claude-sonnet-4-6과 claude-opus-4-7로 수렴하는 이유입니다.
• kimi-k2.7-code 같은 코딩 특화 id는 리팩터링 위주 세션에서 테스트해볼 가치가 있습니다. 게이트웨이를 통하면 그 테스트는 프로바이더 마이그레이션이 아니라 GOOSE_MODEL 값 하나만 바꾸면 됩니다.
• 긴 세션은 컨텍스트를 누적시킵니다. 선언적 경로에서 context_limit으로 정직하게 선언한 진짜 200k 윈도우를 가진 모델은 요약하기 전까지 더 많은 세션 기록을 유지할 수 있게 해줍니다.
• 스크립트 또는 CI 용도라면, 중간급 id(gpt-5.4, qwen3.7-max)가 범위가 잘 정해진 작업에서 프론티어 지출의 일부만으로도 충분한 경우가 많습니다. 상위 등급을 기본값으로 삼기 전에 여러분의 실제 작업으로 측정해 보세요.

사용한 만큼 지불 · 공식 요금보다 저렴

Selected models are priced below official list prices. Exact input, output, cache, and per-request prices are shown for each model.

Goose 특유의 실패 패턴.

OPENAI_HOST에 /v1을 덧붙임. 호스트 변수는 호스트만 받습니다. 경로는 이미 기본값이 v1/chat/completions인 OPENAI_BASE_PATH에 있습니다. 호스트를 https://api.apisrouter.com/v1로 설정하면 /v1/v1/... 요청과 404가 발생합니다. 다른 모든 도구가 /v1 접미사를 원하기 때문에 정확히 이 지점에서 가장 흔한 실수가 나옵니다. 커스텀 프로바이더 파일의 전체 URL 관례. 선언적 base_url은 /v1/chat/completions까지 포함한 완전한 요청 URL로, OPENAI_HOST와 정반대 관례입니다. 커스텀 프로바이더 파일에 호스트만 복사해 넣으면, OPENAI_HOST에 전체 URL을 복사해 넣는 것만큼이나 확실하게 망가집니다. config.yaml의 키는 인증되지 않습니다. Goose는 시크릿을 키체인이나 환경 변수에서 읽으며, config.yaml에 넣은 키 값은 무시합니다. 파일을 수정한 뒤에도 401이 계속된다면 이것이 이유입니다. 변수를 export하거나, goose configure를 다시 실행해 프롬프트가 뜰 때 키를 입력하세요. 데스크톱 세션은 셸 export를 보지 못합니다. 데스크톱 앱은 터미널 프로필로부터 아무것도 상속받지 않습니다. 데스크톱 설정 UI를 통해 프로바이더를 설정하거나, 변수가 설정된 셸에서 실행하세요. 설정 소스가 겹치는 경우. 환경 변수가 파일보다 우선하므로, 오래된 OPENAI_HOST export가 방금 config.yaml에 설정한 값을 덮어쓸 수 있습니다. 라우팅이 이상해 보이면, 어느 레이어를 탓하기 전에 Goose를 실행하는 그 셸에서 관련 변수를 출력해 확인하세요.

어떤 사람들이 게이트웨이를 통해 Goose를 쓰는가.

• Goose를 일상적으로 쓰며, 벤더마다 자격 증명 세트를 두는 대신 Claude, GPT, Kimi, Qwen을 키 하나 뒤에서 사용하고 싶은 엔지니어.
• Goose를 CI나 예약 작업에 넣는 팀. env만으로 되는 경로는 러너에 정확히 두 개의 라우팅 변수와 시크릿 하나만 있으면 되므로, 주입하기도 쉽고 교체하기도 쉽습니다.
• 실제 작업에서 에이전트 모델을 비교하는 개발자. 각 후보는 같은 엔드포인트에 대한 GOOSE_MODEL 값 하나면 되며, 키별 사용량으로 자동으로 비용이 매겨집니다.
• 여러 벤더 대시보드를 대조하는 대신, 에이전트 지출을 키별·모델별로 하나의 청구 화면에서 보고 싶은 플랫폼 팀.
• 특정 벤더의 결제 수단에 접근할 수 없는 개발자. 카드 없이 충전만으로 접근할 수 있어 프로바이더별 가입 의존성이 사라집니다.

엔드포인트 검증 및 첫 세션 디버깅.

세션을 시작하기 전에 게이트웨이가 GOOSE_MODEL의 id를 제공하는지 확인하세요. /v1/models 목록이 버전 접미사까지 포함한 정답 표기입니다. 첫 세션의 실패는 일관된 패턴을 보입니다. 404는 호스트와 경로가 잘못 조합됐다는 뜻이며, 거의 항상 OPENAI_HOST에 있는 /v1 때문입니다. 401은 키가 Goose가 찾는 곳에 없다는 뜻입니다: 실행한 셸에서 export되지 않았거나, 키체인에 없거나, config.yaml 안에 쓸모없이 놓여 있는 경우입니다. 게이트웨이에서 나오는 model-not-found 오류는 GOOSE_MODEL의 id 오타입니다. 세션은 시작되지만 툴 호출이 이상하게 동작한다면, 실제로 툴 사용을 지원하는 모델을 쓰고 있는지 확인하세요. 위 표의 id들은 모두 지원합니다. 루프가 실행되면, APIsRouter 콘솔이 요청별 모델, 토큰 수, 지출을 보여줍니다. 자율 에이전트는 이것이 가장 중요한 작업 유형입니다: 세션이 길고 툴 호출 턴이 많으므로, 사용량 뷰가 Goose로 보낸 오후 한 나절이 실제로 얼마나 들었는지 확인하는 방법입니다.

curl -s https://api.apisrouter.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY" | head -50

자주 묻는 질문