GEODE는 Anthropic, OpenAI(ChatGPT 구독 OAuth 레인 포함), OpenRouter, GLM 네 프로바이더 경로를 명시적으로 라우팅합니다. 이 페이지는 키와 설정이 어디에 저장되는지, 모델이 어떤 순서로 결정되는지, 막혔을 때 어떻게 디버깅하는지 다룹니다.
4개 명시적 프로바이더 경로
모델 id의 접두사가 프로바이더를 결정합니다. 라우팅 SoT는 배포 매니페스트 core/config/routing.toml이고,~/.geode/routing.toml이 섹션 단위로 덮어씁니다.
| 프로바이더 | 기본 모델 | 라우팅 규칙 | 인증 레인 |
|---|---|---|---|
| Anthropic | claude-opus-4-8 (보조 claude-sonnet-4-6, 저비용 claude-haiku-4-5-20251001) | claude- 접두사 | ANTHROPIC_API_KEY |
| OpenAI / Codex | gpt-5.5 | gpt-, o3-, o4- 접두사. 단 gpt-5.5, gpt-5.5-pro와 -codex 계열 접미사는 Codex OAuth 백엔드로만 라우팅. gpt-6-astra, gpt-5.6-sol/terra/luna, gpt-5.4 계열은 듀얼 레인 — 로그인 상태(API 키 ↔ 구독 OAuth)가 백엔드를 결정. Astra의 실제 접근은 OpenAI 계정별 rollout에 따름 | ChatGPT 구독 OAuth(~/.codex/auth.json) 또는 OPENAI_API_KEY |
| OpenRouter | openrouter/openrouter/free, openrouter/openrouter/auto 또는 정확한 catalogue id | openrouter/<publisher>/<model>. 외부 namespace 하나를 제거해 OpenRouter에 전달 | OPENROUTER_API_KEY. 크레딧 기반 PAYG이며 direct provider와 동치 폴백하지 않습니다. |
| GLM (ZhipuAI) | glm-5.2 (무료 티어 glm-4.7-flash) | glm- 접두사 | ZAI_API_KEY. Coding Plan과 PAYG 엔드포인트가 분리되어 있습니다. |
(프로바이더, 자격 소스) 조합마다 어댑터가 하나씩 등록됩니다 (core/llm/adapters/). geode adapters list로 현재 등록 상태, API transport, billing, 자격 환경을 확인할 수 있습니다.
OpenRouter는 OpenAI의 별칭이 아니라 별도 inference router입니다. /login add로 키를 등록하고 /model openrouter/anthropic/claude-sonnet-4처럼 정확한 참조를 선택합니다. 응답의 usage.cost가 예산·사용량 기록의 권위이고, 반환 모델·선택 provider·routing attempt는 bounded LLM-call event에 남습니다. free/auto는 동적 경로이므로 고정 모델 공식 평가에 사용하지 않습니다.
키와 설정이 사는 곳
역할이 파일별로 분리되어 있습니다. 키와 프로필은 로컬 비밀 파일, 동작은 config.toml에 둡니다.
| 파일 | 역할 |
|---|---|
~/.geode/.env | 시크릿 전용 평문 파일(0600). ANTHROPIC_API_KEY, OPENAI_API_KEY, OPENROUTER_API_KEY, ZAI_API_KEY. 전역 파일이 권위를 가지며 프로젝트 .env는 빠진 값만 채웁니다. |
~/.geode/auth.toml | Plan/Profile 메타데이터와 GEODE가 관리하는 자격증명 평문 파일(0600). 외부 CLI가 관리하는 자격증명은 복제하지 않습니다. |
~/.geode/config.toml | 전역 동작 설정. 모델 선택, effort, 로그인 소스가 여기 저장됩니다. |
.geode/config.toml | 프로젝트별 덮어쓰기. /model의 기본 저장 위치입니다. |
~/.geode/routing.toml | 라우팅 매니페스트 덮어쓰기. 폴백 체인 옵트인도 여기서 합니다. |
이 두 비밀 파일은 Git에서 제외되고 읽기·쓰기 때 소유자 전용 권한을 강제하지만 OS Keychain은 아닙니다. 같은 사용자 권한으로 실행되는 프로세스까지 격리하지는 못하므로 공유·비신뢰 호스트에서는 환경 주입 또는 전용 secret manager를 사용합니다. Google Workspace OAuth의 OS keyring 저장소는 이 LLM API-key 경로와 별개입니다.
모델, 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의 선택을 가리고 있으면 경고 한 줄을 먼저 띄웁니다. 전환 검증은 항상 실효 설정을 보여 주는 geode about을 기준으로 합니다.
폴백 정책: 기본은 비어 있음
routing.toml의 [model.fallbacks]는 기본 출하 상태가 전부 빈 목록입니다. 기본 모델이 실패하면 GEODE는 조용히 다른 모델로 바꾸지 않고 즉시 실패를 올립니다 (core/llm/errors.py의 fast-fail 단락). 사용자가/model로 직접 고르는 것이 의도된 복구 경로입니다. 폴백 체인이 필요하면 ~/.geode/routing.toml에서 옵트인합니다.
재시도 경계
llm_max_retries는 최초 호출을 포함한 모델별 총 시도 횟수입니다(기본 3). 메인 에이전트 루프, 보조 호출, scaffold-search mutator가 같은 설정을 사용하지만 각 논리 호출은 별도 예산을 가집니다. SDK 자체 재시도는 0으로 두어 두 계층의 횟수가 곱해지지 않게 합니다.
연결 실패, timeout, 408/409, 일시적 429, 5xx만 jitter backoff로 재시도합니다. retry-after-ms와 숫자/HTTP-date 형식의Retry-After를 존중하되 60초를 넘는 대기는 즉시 사용자에게 돌려줍니다. 인증·잘못된 요청·결제 소진과 이미 출력이 보인 stream 중단은 재호출하지 않습니다.
이 호출 예산은 도구 재실행 권한이 아닙니다. 로컬 부작용은 durable effect receipt로 완료 여부를 확인하고, MCP 재접속은 서버가readOnlyHint 또는 idempotentHint를 선언한 도구만 재호출합니다. scaffold-search의 --mc는 반복적/무효 후보의 의미적 재제안 횟수이며 네트워크 재시도가 아닙니다.
실패 모드
| 증상 | 원인 | 해법 |
|---|---|---|
| 모델을 바꿨는데 그대로 | 상위 레이어(보통 옛 .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와 gpt-5.4 계열은 API 키와 구독 양쪽에서 동작). /login openai로 로그인합니다. |
설정 레퍼런스
- 설정 기초. 레이어 모델 전체.
- config.toml 레퍼런스. 키 전수 목록.
- 인증과 OAuth. 프로파일과 회전.
- LLM 라우팅. 어댑터 레이어 내부.