설정 기초

GEODE 설정의 규칙은 한 줄입니다. 자격 증명은 auth.toml(GEODE가 관리)이나 .env(직접 넣는 환경 변수)에, 동작은 config.toml에 둡니다. 같은 키가 여러 층에 있으면 더 가까운 층이 이기고, 어느 층이 이겼는지는geode config explain이 보여줍니다.

파일과 역할

시크릿 전용 .env는 도구가 지키는 계약입니다./model은 더 이상 GEODE_MODEL을.env에 쓰지 않고 config.toml에만 기록합니다. 과거 릴리스가 남긴 .env의 모델 줄은 피커가 toml을 쓴 직후 자동으로 지우고 알림을 출력합니다 (core/config/env_io.py의 remove_env). env 전용 키는 core/config/__init__.py의 _TOML_ENV_ONLY_FIELDS에 있는 API 키 필드뿐이고, 나머지 필드는 모두 config.toml 키가 있습니다. 예를 들어 게이트웨이는 ~/.geode/config.toml의 [gateway] enabled = true로 켜고, GEODE_GATEWAY_ENABLED export는 세션 한정 override로 남습니다.

확장 신뢰 정책

번들된 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에서 확인됩니다.

프로젝트 신뢰

저장소는 .geode/config.toml, .env,.claude/mcp_servers.json을 함께 담아 올 수 있습니다. GEODE는 폴더를 신뢰하기 전까지 권한을 넓히는 프로젝트 설정을 적용하지 않습니다. 프로젝트 .env, 프로젝트 MCP 서버와 게이트웨이 설정, 샌드박스·computer use·웹훅·알림·저장 경로 같은 키가 여기에 해당합니다. 모델 선택처럼 권한과 무관한 키와[policy.org] denied_tools 같은 제한은 바로 적용됩니다.

geode config trust              # 현재 폴더 신뢰
geode config trust --list       # 신뢰한 폴더 목록
geode config trust PATH --revoke

신뢰 기록은 Codex처럼 전역 ~/.geode/config.toml의[projects."경로"] 표에만 남고 프로젝트의 config.toml은 참조하지 않으므로, 저장소가 스스로를 신뢰할 수 없습니다.hitl.dangerously_skip_permissions와computer_use.helper_path는 신뢰한 폴더에서도 프로젝트 설정으로 읽지 않습니다. 무시된 항목은 경고 로그와geode config explain에 표시됩니다.

해석 사다리

모든 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의 경로를 바꿉니다. 메인 설정 로더,geode config explain, /model의 전역 읽기·저장·확인 화면은 같은 경로 해석 함수를 사용합니다. MCP 서버 로딩, 게이트웨이 읽기·변경 감시, seed 역할·투표자 설정도 이 전역 경로를 따릅니다. 프로젝트 범위로 저장하면 .geode/config.toml에 기록되며, 프로젝트 toml은 전역 설정 위에 그대로 얹힙니다.geode-eval config migrate-petri-toml의 미리보기와--yes 저장도 같은 전역 경로를 사용합니다.

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을 새 설정 후보로 읽고 검증한 뒤 기존 싱글톤을 갱신합니다. 필드 검증이나 준비, 라우팅 갱신이 실패하면 예외를 전달하고 기존 Settings 값을 유지합니다. 파일을 수정한 다음 다시 리로드하면 같은 객체 참조에 새 값이 적용됩니다. 리로드는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, 신뢰한 폴더라면 프로젝트 .env에서도 읽힙니다. 승격 우선순위는 수동 export > 전역 .env> 프로젝트 .env이고 (전역이 권위, 프로젝트는 전역에 없는 키만 채움), 파일은 이미 존재하는 프로세스 env를 덮지 않으며 빈 값도 덮지 않습니다.

실패 모드

다음

• config.toml 레퍼런스. 전체 키 목록입니다.
• 인증과 OAuth. 자격 증명 저장과 로그인을 다룹니다.
• LLM 라우팅. routing.toml이 소비되는 곳입니다.