설정 기초

GEODE 설정의 규칙은 한 줄입니다. 시크릿은 .env에, 동작은 config.toml에 둡니다. 같은 키가 여러 층에 있으면 더 가까운 층이 이기고, 어느 층이 이겼는지는geode config explain이 보여줍니다.

파일과 역할

시크릿 전용 .env는 도구가 지키는 계약입니다./model은 더 이상 GEODE_MODEL을.env에 쓰지 않고 config.toml에만 기록합니다. 과거 릴리스가 남긴 .env의 모델 줄은 피커가 toml을 쓴 직후 자동으로 지우고 알림을 출력합니다 (core/config/env_io.py의 remove_env). toml 매핑이 없는 env 전용 키 (GEODE_GATEWAY_ENABLED 등)를 손으로.env에 적는 것은 여전히 유효한 운영 방법입니다.

해석 사다리

모든 Settings 필드는 같은 사다리를 탑니다. 위가 이깁니다 (core/config/explain.py의 LAYERS).

1. os.environ            셸 export. 세션 한정 수동 override
2. 전역 .env             ~/.geode/.env (시크릿 권위)
3. 프로젝트 .env          cwd의 .env (전역에 없는 키만 채움)
4. 프로젝트 config.toml   .geode/config.toml
5. 전역 config.toml      ~/.geode/config.toml
6. 코드 기본값

시크릿(.env)과 동작(config.toml)은 전역과 프로젝트의 우선 방향이 반대입니다. .env는 전역이 위(권위), config.toml은 프로젝트가 위(프로젝트 튜닝). 같은 키가 양쪽에 동시에 들어가지 않으므로(시크릿 전용, 동작 전용 분리, C-2) 사다리는 하나로 충분합니다. v0.99.216 이전에는.env도 프로젝트가 위였는데, 빈 프로젝트.env가 전역 실키를 가리는 함정이 있어 전역 권위로 뒤집었습니다 (Hermes 정렬).

모델 해석으로 좁히면 같은 사다리가 이렇게 읽힙니다. CLI 인자 > env 층(os.environ + .env 파일들) > 프로젝트 toml > 전역 toml > routing 기본값. env 층이 toml 전부를 이기므로, 잊힌.env 줄 하나가 이후의 모든 toml 편집을 가립니다. 이 구조의 대표 함정입니다.

GEODE_CONFIG_TOML env 변수는 전역config.toml의 경로를 바꿉니다. C-4부터 메인 설정 로더(core/config/__init__.py)와 self-improving 로더(core/config/self_improving.py)가 같은 경로를 읽습니다. 프로젝트 toml은 그 위에 그대로 얹힙니다.

geode config explain

"설정을 바꿨는데 실효값이 안 움직인다"의 표준 진단 플로우입니다. 키마다 층별 후보 표를 출력하고, 정확히 하나의 층을 WINNER로, 그 아래 설정된 층을masked로 표시합니다. 파일 경로까지 같이 나오므로 어느 줄을 고치거나 지워야 하는지 바로 보입니다.

geode config explain model     # 키 생략 시 model
geode about                    # 실효 모델 + 마스크 경고 한 줄

검증은 항상 실효값으로 합니다. geode about이 보여주는 모델이 실제로 호출되는 모델이고, env 층이 toml 선택을 가리고 있으면 같은 화면에 경고가 뜹니다. config.toml 내용을 읽는 것으로 검증을 끝내면 안 됩니다.

리로드 시맨틱

세션 경계에서 reload_settings_from_disk()가.env, GEODE_* env, config.toml을 살아 있는 싱글톤에 다시 읽어 들입니다. 필드 복사가 실패하면 해당 필드명을 적은 경고를 남기므로 반쯤 적용된 리로드가 조용히 지나가지 않습니다. 리로드는reload_routing_constants()도 호출해 routing 매니페스트 캐시를 비우고 core.config의 라우팅 상수를 다시 묶습니다. 한계도 명시합니다. 모듈 로드 시점에 값을 복사해 간 importer는 부트 시점 복사본을 계속 들고 있으므로, 그 경로까지 갱신하려면 프로세스를 재시작해야 합니다.

데몬과 모델 env 키

serve 데몬은 시작할 때 상속받은 환경에서 동작(모델 선택) 계열 env 키를 떨어뜨리고, .env 승격에서도 건너뜁니다 (core/cli/bootstrap.py의load_daemon_env). 데몬 환경에 승격된 모델 키가 모든 /model 전환보다 오래 살아남던 문제의 수정입니다. 대상 키 목록은 core/config/env_io.py의BEHAVIOR_ENV_KEYS입니다.

GEODE_MODEL  GEODE_ACT_MODEL  GEODE_JUDGE_MODEL
GEODE_COGNITIVE_REFLECTION_MODEL  GEODE_LEARNING_EXTRACT_MODEL
GEODE_AGENTIC_EFFORT
GEODE_ANTHROPIC_CREDENTIAL_SOURCE  GEODE_OPENAI_CREDENTIAL_SOURCE

데몬의 모델을 env로 일부러 고정하고 싶다면GEODE_SERVE_KEEP_MODEL_ENV=1을 켭니다. C-4부터 이 플래그는 프로세스 env뿐 아니라 양쪽 .env파일에서도 읽힙니다. 승격 우선순위는 수동 export > 전역 .env> 프로젝트 .env이고 (전역이 권위, 프로젝트는 전역에 없는 키만 채움), 파일은 이미 존재하는 프로세스 env를 덮지 않으며 빈 값도 덮지 않습니다.

실패 모드

다음

• config.toml 레퍼런스. 전체 키 목록입니다.
• 인증과 OAuth. 시크릿 층에 무엇이 들어가는지 다룹니다.
• LLM 라우팅. routing.toml이 소비되는 곳입니다.