본문으로 이동
GEODE
문서
GitHub
문서 탐색빠른 시작
시작하기튜토리얼

빠른 시작

GEODE를 설치하고 설정 마법사를 돌린 뒤 첫 대화까지 갑니다. 성공 기준과 복구 절차를 함께 안내합니다.

요구사항

  • Python 3.12 이상
  • uv 패키지 매니저 (설치 안내)
  • 프로바이더 자격 1개 이상. ChatGPT Plus 구독(OAuth) 또는 Anthropic·OpenAI·GLM API 키 중 하나면 충분합니다.

1. 설치

PyPI 배포명은 geode-agent, 설치되는 명령은geode와 geode-mcp 두 개입니다.

uv tool install geode-agent
geode version

소스 체크아웃으로 개발하려면 이렇게 설치합니다.

git clone https://github.com/mangowhoiscloud/geode.git
cd geode
uv sync
uv tool install -e . --force

2. 설정 마법사

geode setup이 자격을 잡아줍니다. ChatGPT 구독 OAuth(~/.codex/auth.json)가 있으면 API 키를 묻기 전에 먼저 감지합니다. 시크릿은 ~/.geode/.env에, 모델 선택 같은 동작 설정은 ~/.geode/config.toml에 저장됩니다. .env에 모델을 적는 방식은 더 이상 쓰지 않습니다.

geode setup        # 처음 설정
geode setup -r     # 처음부터 다시

3. 첫 대화

geode를 실행하면 serve 데몬이 자동으로 켜지고 thin CLI가 IPC로 붙습니다. 자유 텍스트는 이 대화형 화면 안에서 입력합니다. 셸에서 geode "요청" 형태의 원샷은 지원하지 않습니다.

geode

> 오늘 AI 리서치 트렌드를 요약해줘
> /model        # 모델 확인과 전환
> /status       # 데몬, MCP, 키 상태
> /quit

성공 기준

  • 배너에 버전과 모델이 표시되고 dim한 "session cli-… · connected" 라인이 보입니다.
  • 자유 텍스트에 에이전트가 도구를 호출하며 답합니다.
  • geode about의 EFFECTIVE 모델이 의도한 모델과 일치합니다.

자주 만나는 실패와 해법

증상원인해법
모델을 바꿨는데 그대로상위 레이어가 가리는 중geode config explain model로 어느 레이어가 이기는지 확인합니다. geode about이 실효값입니다.
외부 채널 메시지가 들어오지 않음gateway 비활성로컬 대화는 그대로 동작합니다. 외부 채널도 쓰려면 GEODE_GATEWAY_ENABLED=true를 설정합니다.
응답이 비거나 끊김자격 만료 또는 무효geode doctor로 키와 OAuth 상태를 점검하고 /login으로 갱신합니다.
배너 모델과 실제 응답 모델이 다름오래된 데몬이 살아 있음pkill -f "geode serve" 후 다시 geode를 실행합니다.

복구 절차

망가진 상태에서 알려진 상태로 돌아오는 순서입니다.

  1. geode doctor. 파이썬, PATH, 자격, 데몬을 한 번에 점검합니다.
  2. geode about. 실제로 어떤 모델과 경로가 잡혀 있는지 확인합니다.
  3. geode config explain model. 설정이 어디서 가려지는지 봅니다.
  4. pkill -f "geode serve" 후 재진입. 데몬을 새로 띄웁니다.
  5. geode setup -r. 그래도 안 되면 설정을 처음부터 다시 합니다.

업데이트와 삭제

geode update                  # uv: 최신 patch; 소스: pull + rebuild
geode update --latest         # uv: minor/major 업데이트를 명시적으로 허용

공개 v1.0.27에는 아래의 새 삭제 보호가 아직 포함되지 않았습니다. 이 버전의 uv 설치는 원래 패키지 매니저로 CLI만 제거하고, 런타임·프로젝트 데이터는 남겨두세요.

uv tool uninstall geode-agent # CLI만 제거; 런타임·프로젝트 데이터 보존

소스 체크아웃 전용 — Unreleased. 아래 절차와 보존 보장은 PR #3295를 포함한 소스 설치에 적용됩니다. main 반영과 PyPI 릴리스는 별개이므로, 버전 문자열만으로 이 보호의 포함 여부를 판단하지 마세요.

geode uninstall --dry-run     # 삭제 대상과 설치 소유권 확인
geode uninstall               # 확인된 런타임 데이터 + uv CLI 제거

삭제 범위는 GEODE_HOME(기본 ~/.geode)과 설치 소유권이 확인된 uv 도구입니다. 프로젝트의 .geode/, 소스, 가상환경과 빌드 캐시는 보존합니다. --keep-config는 런타임의 .env, config.toml, auth.toml을,--keep-data는 vault·identity·user_profile을 원래 위치에 남깁니다. 다른 설치 방식이나 사용자 지정 uv 설치는 자동 삭제가 거부될 수 있으므로 원래 패키지 매니저를 사용합니다. 중간 단계가 실패하면 명령은 실패로 종료하며, 이미 삭제된 데이터가 자동 복구되지는 않습니다.

다음 단계