설정 기초

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에 적는 것은 여전히 유효한 운영 방법입니다.

확장 신뢰 정책

번들된 GEODE 기능은 1급 코드로 분류됩니다. 그 밖의 파일시스템 훅, 패키지 LLM 어댑터, 프로젝트·개인 스킬, MCP 서버는 기존 매니페스트를 발견한 뒤 ~/.geode/extension-policy.json의 승인을 먼저 확인합니다. 정책이 없거나 해당 ID가 없으면 실행 코드는 로드되지 않습니다.

{
  "version": 1,
  "extensions": {
    "hook:failure-metrics": {
      "enabled": true,
      "trusted": true,
      "execution": "trusted",
      "capabilities": ["events"]
    },
    "llm-adapter:acme-payg": {
      "enabled": true,
      "trusted": true,
      "execution": "trusted"
    },
    "skill:project-review": {
      "enabled": true,
      "trusted": true,
      "execution": "trusted",
      "capabilities": ["shell"]
    },
    "mcp:filesystem": {
      "enabled": true,
      "trusted": false,
      "execution": "brokered",
      "capabilities": ["stdio"]
    }
  }
}

trusted는 신뢰한 Python 코드를 같은 프로세스에서 실행하는 API 경계이지 샌드박스가 아닙니다. brokeredMCP는 지원되는 OS 샌드박스가 있을 때만 정확한 환경과 격리된 임시 디렉터리로 시작하며, 샌드박스를 만들 수 없으면DEGRADED 상태로 남고 실행되지 않습니다. 다른 정책을 쓰려면 GEODE_EXTENSION_POLICY_OVERRIDE에 정책 파일 경로를 지정합니다. override는 strict하므로 파일 누락이나 잘못된 JSON이면 시작이 실패합니다. 결정은 시작 snapshot으로 고정되고 runtime health의 extensions에서 확인됩니다.

해석 사다리

모든 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이 소비되는 곳입니다.