Configuration basics

왜 이 페이지를 먼저 읽나

GEODE는 코드를 고치지 않고 동작을 바꿀 수 있어야 합니다. 모델, 예산, 메신저 바인딩 같은 값은 설정에서 옵니다. 그래서 키 하나하나를 외우기 전에, 설정이 어디에 살고 어떤 순서로 합쳐지는지부터 잡아야 합니다. 전체 키 목록은 config.toml 레퍼런스에 있습니다. 이 페이지는 그 레퍼런스를 읽기 위한 지도입니다.

설정이 사는 곳

GEODE는 네 곳에서 설정을 읽습니다. 같은 키가 여러 곳에 있으면, 더 가까운 곳이 이깁니다.

CLI 인자. 한 번의 실행에만 적용됩니다.
환경 변수와 .env. 모든 변수는 GEODE_ 접두사를 씁니다. 예를 들어 GEODE_MODEL이 model 키를 덮습니다. .env 파일은 현재 디렉터리의 .env와 ~/.geode/.env 두 곳에서 읽습니다.
프로젝트 TOML. .geode/config.toml. 워크스페이스마다 다른 설정을 둘 때 씁니다.
전역 TOML. ~/.geode/config.toml. 모든 프로젝트에 공통으로 적용할 기본값입니다.

어느 파일도 필수가 아닙니다. 넷 다 없으면 GEODE는 코드 안의 기본값으로 동작합니다.

해석 순서

우선순위는 높은 것부터 낮은 것까지 다음과 같습니다.

CLI 인자
  > 환경 변수 / .env (GEODE_*)
    > 프로젝트 .geode/config.toml
      > 전역 ~/.geode/config.toml
        > 코드 기본값

읽는 방식이 두 갈래라는 점이 중요합니다. 환경 변수와 .env는 설정 객체를 만들 때 곧바로 로드됩니다. TOML 값은 그 뒤에 얹히되,환경 변수로 이미 정해진 키는 건너뜁니다. 그래서 환경 변수가 항상 TOML보다 셉니다. 환경 변수로 모델을 고정해 두면 config.toml의 모델 값은 무시됩니다.

TOML에서 코드가 모르는 키는 조용히 무시됩니다. 매핑된 키만 적용되므로, 오타가 난 키는 효과 없이 지나갑니다. 레퍼런스에 적힌 이름을 그대로 쓰세요.

로드 시점

설정은 싱글턴입니다. 처음 누군가 설정을 요청할 때 한 번 만들어지고, 그 뒤로는 같은 객체가 재사용됩니다. 무거운 의존성을 미루기 위해 이렇게 지연 로드합니다. 디스크가 바뀌면 reload_settings_from_disk()가.env와 config.toml을 다시 읽어 살아 있는 싱글턴을 제자리에서 갱신합니다. geode serve 데몬이 세션 경계에서 이 경로를 타기 때문에, CLI에서 모델을 바꿔도 데몬이 디스크와 다시 맞춰집니다.

config.toml 첫 모양

값은 영역별 테이블로 묶입니다. 바꾸고 싶은 줄의 주석만 풀면 됩니다.

[llm]
primary_model = "claude-opus-4-7"
secondary_model = "gpt-5.4"

[pipeline]
confidence_threshold = 0.7
max_iterations = 5

[gateway]
time_budget_s = 300

[[gateway.bindings.rules]]
channel = "slack"
channel_id = "C12345"
auto_respond = true

[[gateway.bindings.rules]]는 메신저 채널 하나를 세션으로 라우팅하는 규칙입니다. channel_id가 비면 그 규칙은 안전을 위해 건너뜁니다. 빈 id는 모든 채널을 받는 위험한 catch-all이 되기 때문입니다. 바인딩을 더 다루려면 바인딩 설정 가이드를 보세요.

다음으로