모델 & 자격 증명

Gajae-Code(gjc)는 모든 구체적인 프로바이더 모델을 그대로 보관한 다음, 그 위에 정규(canonical) 레이어를 만듭니다. 덕분에 정확한 provider/model을 고정하거나, 여러 프로바이더에 걸쳐 합쳐지는 정규 id를 선택할 수 있습니다. 이 모든 것은 하나의 파일 — ~/.gjc/agent/models.yml — 과 인증 해석, 런타임 탐지로 동작합니다.

이 페이지는 실용 레퍼런스입니다. 전체 스키마를 붙여넣지는 않고, 파일의 형태, 프리셋, 역할, 동등성, 탐지, 인증 순서를 다룹니다.

설정 파일 위치

기본 설정 경로는 다음과 같습니다.

~/.gjc/agent/models.yml

레거시 동작도 여전히 남아 있습니다.

• models.yml이 없고 같은 위치에 models.json이 있으면 models.yml로 마이그레이션됩니다.
• 명시적인 .json / .jsonc 경로는 프로그래밍 방식으로 전달할 때 계속 지원됩니다.

models.yml이 스키마/검증 검사를 통과하지 못하면, 레지스트리는 내장 모델로 계속 동작합니다. 오류는 UI에 노출됩니다.

models.yml 형태

크게 보면 models.yml에는 최상위 섹션이 세 개 — providers, equivalence, modelBindings — 있습니다.

providers:
  <provider-id>:
    # 프로바이더 레벨 설정 (baseUrl, api, auth, models, ...)
equivalence:
  overrides:
    <provider-id>/<model-id>: <canonical-model-id>
  exclude:
    - <provider-id>/<model-id>
modelBindings:
  modelRoles:
    default: <provider/model-id 또는 canonical-id>[:thinkingLevel]
  agentModelOverrides:
    executor: <provider/model-id>

provider-id는 선택과 인증 조회 전반에 쓰이는 정규 프로바이더 키입니다. equivalence는 선택 사항입니다. 구체 모델 위에서 정규 그룹핑을 구성합니다.

models.yml은 엄격(strict) 합니다. 알 수 없는 provider/model 키는 프로바이더 디스패치 전에 검증에서 실패합니다. 무시될 거라고 기대하지 말고, 오래된 키는 제거하세요.

프로바이더 레벨 필드

전체 커스텀 프로바이더는 전송(transport)과 모델 목록을 선언합니다.

providers:
  my-provider:
    baseUrl: https://api.example.com/v1
    apiKey: MY_PROVIDER_API_KEY
    api: openai-completions
    auth: apiKey
    headers:
      X-Team: platform
    disableStrictTools: false  # `strict`를 거부하는 Anthropic 호환 엔드포인트면 true
    models:
      - id: some-model-id
        name: Some Model
        reasoning: false
        input: [text]
        contextWindow: 128000
        maxTokens: 16384

허용되는 provider/model api 값:

openai-completions, openai-responses, openai-codex-responses, azure-openai-responses, bedrock-converse-stream, anthropic-messages, google-generative-ai, google-vertex, google-gemini-cli, ollama-chat, cursor-agent.

허용되는 auth 값: apiKey(기본값), none, oauth. models.yml 커스텀 모델의 경우 oauth는 스키마상 허용되지만 apiKey 요구를 면제하지는 않습니다.

검증 규칙

• 전체 커스텀 프로바이더(models 비어 있지 않음): baseUrl, auth: none이 아니면 apiKey, 그리고 프로바이더 레벨 또는 각 모델의 api가 필요합니다.
• 오버라이드 전용 프로바이더(models 없음/비어 있음): baseUrl, headers, compat, requestTransform, disableStrictTools, modelOverrides, discovery 중 하나 이상을 정의해야 합니다.
• 모델 검사: id는 필수, contextWindow와 maxTokens는 지정 시 양수여야 합니다.

프로바이더 프리셋

흔한 MiniMax, GLM/zAI 설정의 경우 프리셋을 쓰는 게 좋습니다. OpenAI 호환 API, 베이스 URL, 환경 변수, 모델 id, 호환성 플래그가 한 번에 작성되기 때문입니다.

CLI에서:

gjc setup provider --preset minimax
gjc setup provider --preset minimax-cn
gjc setup provider --preset glm

TUI 안에서도 동일한 프리셋을 쓸 수 있습니다.

/provider add --preset minimax
/provider add --preset glm
/provider add zai

프리셋은 문서화된 환경 변수 이름(MINIMAX_CODE_API_KEY, MINIMAX_CODE_CN_API_KEY, ZAI_API_KEY)을 참조하는 models.yml 항목만 작성합니다. 실제 자격 증명을 저장하거나 검증하지 않습니다. GLM 별칭(glm, zai, z-ai)은 glm-proxy라는 이름의 OpenAI 호환 커스텀 프로바이더를 작성합니다. 1급(first-class) zai 프로바이더를 대체하지 않습니다.

모델 역할과 thinking 레벨

모델 역할을 쓰면 어디서나 id를 하드코딩하는 대신 모델을 작업에 묶을 수 있습니다. 지원되는 역할:

default, smol, slow, vision, plan, designer, commit, task

역할 값은 modelRoles(설정 / modelBindings) 아래에 둡니다. 각 역할 값은 다음 중 하나입니다.

• provider/modelId — 구체적인 프로바이더 변형을 고정, 또는
• gpt-5.3-openai-code 같은 정규 id — 프로바이더 합치기를 허용.

각 역할 값에는 thinking 선택자 접미사를 붙일 수 있습니다.

:off | :minimal | :low | :medium | :high | :xhigh

예: default: layofflabs/gpt-5.5:high. 한 역할이 다른 역할을 가리키면 대상 모델은 정상적으로 상속됩니다. 참조하는 역할에 붙은 명시적 접미사는 그 역할 한정 사용에서 우선합니다.

관련 설정:

enabledModels와 disabledProviders 항목은 경로 접두사로 스코프를 지정할 수 있습니다(path, paths, pathPrefix, pathPrefixes 사용). 특정 프로젝트 디렉터리마다 홈 디렉터리와 다른 모델 집합을 고정할 수 있습니다.

정규 동등성

레지스트리는 모든 구체 프로바이더 모델을 보관한 뒤 그 위에 정규 레이어를 만듭니다. 정규 id는 공식 업스트림 id만 사용합니다 — 예: anthropic-model-opus-4-6, anthropic-model-haiku-4-5, gpt-5.3-openai-code.

equivalence 블록으로 그룹핑을 설정합니다.

equivalence:
  overrides:
    zenmux/openai-code: gpt-5.3-openai-code
    p-openai-code/openai-code: gpt-5.3-openai-code
  exclude:
    - demo/openai-code-preview

정규 그룹핑 빌드 순서:

휴리스틱은 의도적으로 좁습니다. 번들 매치나 명시적 오버라이드 없이는 모호한 패밀리/버전을 절대 합치지 않습니다.

여러 구체 변형이 같은 정규 id를 공유하면, 해석은 가용성 + 인증, 그다음 modelProviderOrder, 그다음 기존 레지스트리 순서를 사용합니다. 비활성/미인증 프로바이더는 건너뜁니다. 세션 상태와 트랜스크립트는 항상 실제로 턴을 실행한 구체 provider/model을 기록합니다.

/model과 --list-models에서는 프로바이더 탭/행 옆에 정규 뷰가 함께 나타납니다. 정규 항목을 선택하면 정규 선택자가 저장되고, 프로바이더 행을 선택하면 명시적 provider/modelId가 저장됩니다.

런타임 탐지

명시적으로 설정하지 않으면, Gajae-Code는 로컬 런타임을 위한 암묵적이고 키 없는(keyless) 탐지 가능 프로바이더를 추가합니다.

셋 모두 auth: none처럼 동작합니다. 탐지는 런타임의 모델 엔드포인트를 호출합니다. 로컬 기본값으로 모델 항목을 합성합니다. 직접 탐지를 설정할 수도 있습니다.

providers:
  ollama:
    baseUrl: http://127.0.0.1:11434
    api: openai-responses
    auth: none
    discovery:
      type: ollama

discovery.type은 ollama, llama.cpp, lm-studio를 허용합니다. 프로바이더 레벨 api가 필요합니다.

인증과 API 키 해석 순서

프로바이더의 키를 요청할 때, 실제 순서는 다음과 같습니다.

models.yml의 apiKey 값은 먼저 환경 변수 이름으로 취급됩니다. 해당 env 변수가 없으면 리터럴 문자열을 토큰으로 사용합니다. authHeader: true이고 프로바이더 apiKey가 설정되면, 모델에 Authorization: Bearer <resolved-key> 헤더가 주입됩니다. auth: none으로 표시된 프로바이더는 자격 증명 없이 사용 가능한 것으로 취급됩니다.

모델은 레지스트리(getAll())에 존재할 수 있습니다. 인증이 해석되어야(getAvailable()) 선택 가능해집니다.

브로커 모드

GJC_AUTH_BROKER_URL(또는 auth.broker.url)이 설정되면, 로컬 SQLite 자격 증명 저장소가 원격 브로커 저장소로 대체됩니다. 저장된 API 키·OAuth 자격 증명은 refresh 토큰이 가려진 브로커 제공 스냅샷에서 제공됩니다. 토큰 만료 시 로컬이 아니라 브로커에서 갱신을 트리거합니다.

관련 페이지

모든 *_API_KEY, *_TOKEN, 클라우드 자격 증명은 비밀로 취급하세요 — 절대 로그에 남기거나 커밋하지 마세요.