GEODE는 Anthropic, OpenAI(ChatGPT 구독 OAuth 레인 포함), GLM 세 프로바이더로 라우팅합니다. 이 페이지는 키와 설정이 어디에 저장되는지, 모델이 어떤 순서로 결정되는지, 막혔을 때 어떻게 디버깅하는지 다룹니다.
3-프로바이더 라우팅
모델 id의 접두사가 프로바이더를 결정합니다. 라우팅 SoT는 배포 매니페스트 core/config/routing.toml이고,~/.geode/routing.toml이 섹션 단위로 덮어씁니다.
| 프로바이더 | 기본 모델 | 라우팅 규칙 | 인증 레인 |
|---|---|---|---|
| Anthropic | claude-opus-4-8 (보조 claude-sonnet-4-6, 저비용 claude-haiku-4-5-20251001) | claude- 접두사 | 구독 OAuth(claude CLI keychain) 또는 ANTHROPIC_API_KEY |
| OpenAI / Codex | gpt-5.5 | gpt-, o3-, o4- 접두사. 단 gpt-5.5, gpt-5.5-pro와 -codex 계열 접미사는 Codex OAuth 백엔드로만 라우팅. gpt-5.6-sol/terra/luna는 듀얼 레인 — 로그인 상태(API 키 ↔ 구독 OAuth)가 백엔드를 결정 | ChatGPT 구독 OAuth(~/.codex/auth.json) 또는 OPENAI_API_KEY |
| GLM (ZhipuAI) | glm-5.2 (무료 티어 glm-4.7-flash) | glm- 접두사 | ZAI_API_KEY. Coding Plan과 PAYG 엔드포인트가 분리되어 있습니다. |
(프로바이더, 자격 소스) 조합마다 어댑터가 하나씩 등록됩니다 (core/llm/adapters/). geode adapters list로 현재 등록 상태와 자격 환경을 확인할 수 있습니다.
키와 설정이 사는 곳
역할이 파일별로 분리되어 있습니다. 키는 .env, 동작은 config.toml입니다.
| 파일 | 역할 |
|---|---|
~/.geode/.env | 시크릿 전용. ANTHROPIC_API_KEY, OPENAI_API_KEY, ZAI_API_KEY. 프로젝트 .env가 있으면 그쪽이 이깁니다. |
~/.geode/config.toml | 전역 동작 설정. 모델 선택, effort, 로그인 소스가 여기 저장됩니다. |
.geode/config.toml | 프로젝트별 덮어쓰기. /model의 기본 저장 위치입니다. |
~/.geode/routing.toml | 라우팅 매니페스트 덮어쓰기. 폴백 체인 옵트인도 여기서 합니다. |
모델, effort, 로그인 소스를 .env에 적는 방식은 폐기되었습니다. 예전 버전이 남긴 .env의 모델 줄은 /model이 toml에 쓰면서 자동으로 지우고 "removed stale ... from .env" 안내를 출력합니다.
모델 결정 순서
위가 아래를 가립니다. 첫 번째로 값이 설정된 레이어가 이깁니다.
1. CLI 인자 2. env 레이어 (os.environ + project .env + global .env) 3. 프로젝트 .geode/config.toml 4. 전역 ~/.geode/config.toml 5. 라우팅 기본값 (core/config/routing.toml)
데몬은 시작할 때 모델 계열 env 키를 의도적으로 버리므로 (BEHAVIOR_ENV_KEYS, core/config/env_io.py), 세션마다 toml의 선택이 항상 이깁니다. 셸에서 직접 export한GEODE_MODEL은 그 세션 한정의 파워유저 오버라이드입니다.
디버깅 플로우: geode config explain
"설정을 바꿨는데 안 먹힌다"의 표준 진단은geode config explain model입니다. 레이어별 후보 값과 파일 경로를 표로 보여주고, 이기는 레이어 하나에 WINNER, 가려진 레이어에 masked를 표시합니다.
geode config explain model # 어느 레이어가 이기는지 geode about # 실효(EFFECTIVE) 모델 + 프로바이더
geode about은 실제로 적용 중인 값을 보여주는 화면입니다. env 레이어가 toml의 선택을 가리고 있으면 경고 한 줄을 먼저 띄웁니다. 전환 검증은 config 파일 내용이 아니라 항상 geode about 기준으로 합니다.
폴백 정책: 기본은 비어 있음
routing.toml의 [model.fallbacks]는 기본 출하 상태가 전부 빈 목록입니다. 기본 모델이 실패하면 GEODE는 조용히 다른 모델로 바꾸지 않고 즉시 실패를 올립니다 (core/llm/errors.py의 fast-fail 단락). 사용자가/model로 직접 고르는 것이 의도된 복구 경로입니다. 폴백 체인이 필요하면 ~/.geode/routing.toml에서 옵트인합니다.
실패 모드
| 증상 | 원인 | 해법 |
|---|---|---|
| 모델을 바꿨는데 그대로 | 상위 레이어(보통 옛 .env 줄 또는 셸 export)가 가림 | geode config explain model로 WINNER 레이어를 찾아 그 줄을 고치거나 지웁니다. |
| 데몬만 옛 모델로 응답 | 데몬 환경에 모델 env가 박제됨 | 데몬은 시작 시 모델 계열 env 키를 버리는 것이 기본입니다. pkill -f "geode serve" 후 재시작합니다. 데몬 모델을 env로 일부러 고정하려면 GEODE_SERVE_KEEP_MODEL_ENV=1이 탈출구입니다. |
| GLM 구독인데 미터링 과금 | Coding Plan 키가 PAYG 엔드포인트로 나감 | Coding Plan 엔드포인트(api.z.ai/api/coding/paas/v4)와 PAYG(api.z.ai/api/paas/v4)는 다릅니다. 어느 쪽으로 나가는지 확인합니다. |
gpt-5.5가 API 키로 안 됨 | codex 전용 모델 | gpt-5.5와 gpt-5.5-pro는 ChatGPT 구독 OAuth 레인으로만 라우팅됩니다(gpt-5.6 계열은 API 키로도 동작). /login openai로 로그인합니다. |
설정 레퍼런스
- 설정 기초. 레이어 모델 전체.
- config.toml 레퍼런스. 키 전수 목록.
- 인증과 OAuth. 프로파일과 회전.
- LLM 라우팅. 어댑터 레이어 내부.