요구사항
- Python 3.12 이상
uv패키지 매니저 (설치 안내)- 프로바이더 자격 1개 이상. ChatGPT Plus 구독(OAuth), Anthropic 구독(OAuth) 또는 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이 실효값입니다. |
geode serve가 거부 | gateway 비활성 | ~/.geode/.env에 GEODE_GATEWAY_ENABLED=true를 추가합니다. 대화만 하려면 serve를 직접 띄울 필요가 없습니다. |
| 응답이 비거나 끊김 | 자격 만료 또는 무효 | geode doctor로 키와 OAuth 상태를 점검하고 /login으로 갱신합니다. |
| 배너 모델과 실제 응답 모델이 다름 | 오래된 데몬이 살아 있음 | pkill -f "geode serve" 후 다시 geode를 실행합니다. |
복구 절차
망가진 상태에서 알려진 상태로 돌아오는 순서입니다.
geode doctor. 파이썬, PATH, 자격, 데몬을 한 번에 점검합니다.geode about. 실제로 어떤 모델과 경로가 잡혀 있는지 확인합니다.geode config explain model. 설정이 어디서 가려지는지 봅니다.pkill -f "geode serve"후 재진입. 데몬을 새로 띄웁니다.geode setup -r. 그래도 안 되면 설정을 처음부터 다시 합니다.
업데이트와 삭제
geode update # uv: 최신 patch; 소스: pull + rebuild geode update --latest # uv: minor/major 업데이트를 명시적으로 허용 geode uninstall # 런타임 데이터 + CLI 제거
선택: Google Workspace 연결
Gmail, Calendar, Drive, Docs, Sheets, Tasks, Contacts를 쓰려면 직접 만든 Google Desktop OAuth 클라이언트를 연결합니다. 대화형 화면에서 /login google을 실행하면 client JSON과 최소 권한 번들을 차례로 고를 수 있습니다.
geode > /login google
Cloud 프로젝트, API 활성화, 7일 Testing 만료, 저장 스키마까지는 Google Workspace 연결 가이드를 따르십시오.
다음 단계
- Google Workspace 연결. 사용자 소유 OAuth로 Gmail과 Calendar 등을 붙입니다.
- 경로 선택. 구독, API 키, 무료 경로 중 무엇이 맞는지 고릅니다.
- 두 개의 루프. GEODE의 핵심 멘탈 모델입니다.
- 데몬으로 실행. 메신저와 스케줄을 붙이는 길입니다.