Goose + JoinGonka Gateway: 키링을 통한 제공자 및 키 관리

1단계: Goose 설치하기.프로젝트 문서에 있는 CLI 공식 설치 방법:

# macOS and Linux: the script puts the binary in ~/.local/bin
curl -fsSL https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh | CONFIGURE=false bash

# macOS, Homebrew
brew install block-goose-cli

CONFIGURE=false 변수는 스크립트가 설치 직후 실행하는 goose configure 마법사를 비활성화합니다: 프로바이더는 설치 프로그램이 설정합니다. ~/.local/bin 디렉터리가 PATH에 없으면 스크립트가 그렇게 알려줍니다. Windows용으로는 같은 저장소에 download_cli.ps1 스크립트가 있고, 데스크톱 앱은 문서 페이지에서 다운로드할 수 있습니다. 데스크톱 앱과 CLI는 같은 설정을 읽으므로 아래 내용은 둘 다에 적용됩니다. 확인은 goose --version입니다.

2단계: 키 발급받기.gate.joingonka.ai/register에서 가입하고 주소를 확인한 뒤, 'API 키' 섹션에서 jg- 접두사가 붙은 키를 생성하세요. 하나의 키와 하나의 잔액이 네트워크의 모든 모델에 적용됩니다.

3단계: 설치 프로그램 실행하기.

npx @joingonka/setup --tool goose

설치 프로그램이 키를 물어봅니다(셸 기록에 남지 않도록 명령줄 인수로는 전달되지 않습니다). 그리고 다음을 수행합니다:

• 게이트웨이 주소와 네트워크의 세 가지 모델(실제 컨텍스트 윈도우 포함)이 담긴 프로바이더 파일 custom_providers/custom_joingonka.json을 권한 600으로 생성합니다. custom_joingonka와 CUSTOM_JOINGONKA_API_KEY라는 이름은 Goose가 'JoinGonka'라는 이름에서 자동으로 도출하는 것과 동일하므로, 마법사에서 입력한 키가 올바른 위치에 저장됩니다;
• JoinGonka를 기본 프로바이더로, 모델은 DeepSeek V4 Flash로 설정합니다. 단, 프로바이더가 아직 선택되지 않았거나 저희 것이 선택되어 있고 모델이 비어 있거나 네트워크에서 사라진 경우에만 해당합니다. 다른 선택은 건드리지 않고, 시험해볼 명령을 출력합니다: goose session --provider custom_joingonka --model …;
• Goose의 시크릿 저장소가 확실히 파일 기반일 때만 키를 secrets.yaml에 저장합니다. 그렇지 않으면 한 단계가 남았다고 바로 알려줍니다. 자세한 내용은 키 관련 섹션에 있습니다;
• 변경된 파일의 백업을 만들고, 마지막으로 게이트웨이에 라이브 요청을 보내 키, 주소, 모델을 즉시 검증합니다.

설치 프로그램은 Goose 본체와 같은 방식으로 설정 디렉터리를 찾습니다: Linux와 macOS에서는 ~/.config/goose, Windows에서는 %APPDATA%\Block\goose\config, GOOSE_PATH_ROOT가 설정된 경우 <root>/config. 다른 모델은 --model 플래그로 지정하며, 축약형 deepseek, glm, minimax를 사용할 수 있습니다. 명시적으로 지정된 모델은 항상 기록됩니다. 무질문 모드에서는 환경 변수에서 키를 가져옵니다:

JOINGONKA_API_KEY=jg-your-key npx @joingonka/setup --tool goose --model glm --non-interactive

설치 프로그램이 수행하는 모든 작업은 수동으로 수행할 수 있습니다. 제공자(provider)는 별도의 JSON 파일인 ~/.config/goose/custom_providers/custom_joingonka.json으로 정의되며, 파일 이름은 name 필드와 일치해야 합니다:

{
  "name": "custom_joingonka",
  "engine": "openai",
  "display_name": "JoinGonka",
  "description": "JoinGonka Gateway — Gonka AI inference (OpenAI-compatible)",
  "api_key_env": "CUSTOM_JOINGONKA_API_KEY",
  "base_url": "https://gate.joingonka.ai/v1/chat/completions",
  "models": [
    { "name": "deepseek-ai/DeepSeek-V4-Flash-0731", "context_limit": 380000 },
    { "name": "zai-org/GLM-5.3-Flash", "context_limit": 390000 },
    { "name": "MiniMaxAI/MiniMax-M2.7", "context_limit": 200000 }
  ],
  "supports_streaming": true,
  "requires_auth": true
}

Goose의 모델 항목에는 별도의 응답 상한선 설정이 없습니다. 이러한 모델의 경우 요청 시 제한 값을 전달하지 않으며(요청 로그를 통해 확인됨), 스트리밍 모드에서는 게이트웨이가 모델의 상한선에 따라 응답을 제한합니다(DeepSeek V4 Flash는 32,768 토큰, GLM-5.3 Flash 및 MiniMax M2.7은 8,192 토큰). 이를 위해 전역 변수 GOOSE_MAX_TOKENS를 설정할 필요는 없습니다. 이는 모든 제공자에게 즉시 일괄 적용되기 때문입니다.

Goose는 제공자 파일을 엄격한 JSON 파서로 읽으므로, 주석이나 마지막 쉼표가 있으면 제공자가 목록에서 사라집니다. 마법사(goose configure → Custom Providers)를 통해 생성할 수도 있지만, 마법사는 컨텍스트 창 크기를 묻지 않으므로 직접 입력해야 합니다.

기본 제공자와 모델은 ~/.config/goose/config.yaml에 저장됩니다. Goose는 다음과 같이 기록합니다:

active_provider: custom_joingonka
providers:
  custom_joingonka:
    enabled: true
    model: deepseek-ai/DeepSeek-V4-Flash-0731
    configured: true

파일 루트에 평면 키인 GOOSE_PROVIDER 및 GOOSE_MODEL을 사용하는 이전 방식도 작동합니다. Goose는 설정을 처음 저장할 때(예: goose configure 사용 후) 이를 읽어 새로운 형식으로 자동 변환합니다. 설치 프로그램은 빈 파일에 이 평면 키를 쓰는데, 이는 모든 버전에서 인식됩니다. 환경 변수는 파일보다 우선하며, 쉘에서 설정된 경우 config.yaml의 선택 사항은 적용되지 않으며 설치 프로그램이 이에 대해 경고합니다.

Goose의 프로바이더 파일에는 시크릿 이름 CUSTOM_JOINGONKA_API_KEY만 있습니다. 값은 다음 순서로 검색됩니다: 같은 이름의 환경 변수, 그다음 시스템 시크릿 저장소(keyring, macOS에서는 Keychain), 그다음 설정 파일 옆의 secrets.yaml입니다. 시크릿이 파일에 기록되는 것은 Goose의 저장소가 파일 기반일 때이며, 거기서는 평문 그대로, 권한 600으로 저장됩니다. 그리고 config.yaml에서는 Goose가 키를 전혀 검색하지 않습니다(문서).

저장소가 파일 기반이 되는 경우는 keyring이 비활성화되어 있을 때 — 임의의 값을 가진 환경 변수 GOOSE_DISABLE_KEYRING, 또는 config.yaml의 GOOSE_DISABLE_KEYRING: true 줄 — 이거나 사용할 수 없을 때입니다: 그래픽 세션이 없는 서버, 컨테이너, CI 등이 그렇습니다. 후자의 경우 Goose는 로그에 "Keyring unavailable. Using file storage for secrets."라고 기록하고 스스로 파일로 전환합니다 — 바로 우리가 컨테이너에서 본 그대로입니다. 설치 프로그램은 keyring에 쓸 수 없고, 당신을 대신해 비활성화하지도 않습니다. 그러면 Goose가 이미 저장된 시크릿을 보지 못하게 되기 때문입니다. 여기서 다음 시나리오가 나옵니다:

남은 단계. goose configure를 실행하고 마법사의 질문에 답하세요 — 우리 실행에서는 이렇게 보였습니다:

• What would you like to configure? → Configure Providers;
• Which model provider should we use? → JoinGonka(우리 환경에서는 맨 앞에 있었습니다);
• Would you like to set CUSTOM_JOINGONKA_API_KEY? (optional) → Yes, 이어서 Enter value for CUSTOM_JOINGONKA_API_KEY에서 키를 붙여넣으세요 — 문자 대신 사각형이 나타납니다. 키는 즉시 저장됩니다;
• Would you like to configure advanced settings? → No;
• Select a model — 목록은 Goose가 게이트웨이에서 가져옵니다: MiniMaxAI/MiniMax-M2.7, deepseek-ai/DeepSeek-V4-Flash-0731, zai-org/GLM-5.3-Flash. 커서는 첫 줄에 있습니다 — 설치 프로그램이 선택한 모델을 유지하려면 화살표로 DeepSeek V4 Flash를 선택하세요. 테스트 요청 후 마법사는 "Configuration saved successfully"라는 줄로 끝납니다.

Goose Desktop에서는 경로가 이렇습니다: Settings → Models → Configure providers → JoinGonka → 키 → Submit. 키를 직접 붙여넣기 싫다면 변수에 넣고 같은 셸에서 마법사를 실행하세요: Goose가 "CUSTOM_JOINGONKA_API_KEY is set via environment variable"라고 표시하고 값을 저장할지 제안합니다:

read -s CUSTOM_JOINGONKA_API_KEY && export CUSTOM_JOINGONKA_API_KEY
goose configure

또는 저장 없이 한 번만 키를 전달할 수도 있습니다: CUSTOM_JOINGONKA_API_KEY=jg-your-key goose session, PowerShell에서는 $env:CUSTOM_JOINGONKA_API_KEY = "jg-your-key"; goose session. 환경 변수는 저장된 값보다 우선하지만 셸을 닫을 때까지만 유효합니다.

먼저 Goose가 실제로 어떤 설정을 인식하고 있는지 확인하세요:

goose info -v

「goose Configuration」블록에 GOOSE_PROVIDER: custom_joingonka와 모델 식별자가 포함된 GOOSE_MODEL 줄이 있어야 합니다. 그런 다음 대화형 세션 없이 단일 실행을 해보세요. 빈 디렉터리에 명백한 버그가 있는 파일을 넣고 찾아달라고 요청하세요.

goose run --no-session -t "Read calc.py and tell me in one sentence whether it has a bug."

--no-session 플래그는 실행을 기록에 저장하지 않습니다. 헤더에 ● new session · custom_joingonka deepseek-ai/DeepSeek-V4-Flash-0731 같은 줄이 나타나고, 이어서 도구 호출——cat calc.py 명령이 있는 ▸ shell——그리고 발견된 버그에 대한 답변이 표시됩니다. 한 번의 실행에 다른 모델을 지정하려면 --model을 사용하세요: zai-org/GLM-5.3-Flash 또는 MiniMaxAI/MiniMax-M2.7. 2026년 9월 23일 우리의 실행에서는 네트워크의 세 모델 모두 「요청 → 도구 → 결과 → 답변」 주기를 통과했습니다. Goose CLI는 기본적으로 모델의 추론을 숨깁니다——터미널로 출력하는 경우 GOOSE_CLI_SHOW_THINKING=1 변수로 표시할 수 있습니다. 게이트웨이 측에서는 요청이 관리 화면에서 보입니다: 「사용량」 섹션, 「모델별」 및 「키별」 분석입니다.

문제가 발생하면 진단은 보통 메시지에서 바로 읽을 수 있습니다:

에이전트는 일반 채팅과는 다르게 토큰을 소비합니다. Goose의 표준 구성에서도 18개의 내장 도구에 대한 설명이 모델에 전달되므로, 이번 실행에서는 질문 전부터 약 4,600개의 입력 토큰이 소비되었습니다. 「파일을 읽고 오류를 찾는」 작업에는 2~3단계와 10,000~15,000 토큰이 소요되었으며 거의 대부분이 입력 토큰입니다. 또한 Goose는 세션 이름을 생성하기 위해 자동으로 짧은 요청을 한 번 더 수행합니다. 불필요한 확장 기능은 goose configure → Toggle Extensions에서 끌 수 있으며, 이것이 입력 토큰을 줄이는 가장 간단한 방법입니다.

JoinGonka Gateway를 통하면 토큰 비용은 입력 $0.0069(백만 토큰당), 출력 $0.021(백만 토큰당)입니다. 이 가격은 네트워크 내 모든 모델에 동일하게 적용되며 이 페이지에서는 실시간 소스에서 가져옵니다.

우측 열의 예측치는 2026년 9월 가격 기준입니다. 비교를 위해 Goose에서 모델 비용을 지불하는 방식은 다음과 같습니다:

정확한 사용량과 잔액은 대시보드의 「사용량(Usage)」 및 「빌링(Billing)」 섹션에서 확인하세요. 왜 DeepSeek V4 Flash가 기본 설정되어 있는지(네트워크 내에서 가장 큰 답변 용량을 갖기 때문)에 대한 상세 내용은 모델 개요를 참조하세요.

확인 모드. 기본적으로 Goose는 auto 모드로 작동합니다 — 완전히 자율적으로, 아무것도 묻지 않고 파일을 편집 및 삭제하고, 명령을 실행하고, 확장 기능을 사용합니다. 자신의 프로젝트에서는 편리하지만, 다른 사람의 코드에서는 모드를 엄격하게 하는 것이 좋습니다:

# inside a session
/mode smart_approve

# permanently, as a line in config.yaml
GOOSE_MODE: smart_approve

이것은 Goose 자체의 기능이며 모델 프로바이더에 의존하지 않습니다.

모델 변경. 세션 내에서는 — ID를 동반한 /model 명령, 예를 들어 /model zai-org/GLM-5.3-Flash； 한 번의 실행에서는 — goose run과 goose session의 --model 플래그； 영구적으로는 — goose configure 또는 config.yaml의 model 행입니다. 프로바이더는 그대로 유지됩니다. 추론하는 GLM-5.3 Flash는 복잡한 로직에 적합하지만 응답 상한은 8192 토큰이며 그 일부는 추론에 사용됩니다 — 자세한 내용은 모델 리뷰를 참조하세요.

무인 실행. goose run은 스크립트와 CI에 적합합니다: -q 플래그는 출력에 모델 응답만 남기고, --output-format json은 파싱용 결과를 반환합니다. --max-turns(에이전트가 사람의 개입 없이 수행하는 턴 수)와 --max-tool-repetitions(동일한 인수로 같은 도구를 연속 호출할 수 있는 횟수) 제한이 루프를 방지합니다.

프라이버시. Goose의 익명 사용 통계는 기본적으로 비활성화되어 있습니다(GOOSE_TELEMETRY_ENABLED). 게이트웨이는 프롬프트와 응답 내용을 저장하지 않습니다 — 통계에는 소비 집계만 남습니다.