GEODE v1.0.0부터 uv나 GitHub로 설치한 사용자도 중앙 GEODE OAuth 앱 없이 자신의 Google Cloud 프로젝트로 Gmail, Calendar, Drive, Docs, Sheets, Tasks, Contacts를 연결할 수 있습니다. 권장 진입점은 대화형 GEODE 화면의 /login google입니다.
이 가이드는 개인용 Desktop OAuth 클라이언트를 만드는 최소 경로를 설명합니다. Google Workspace 조직에서 운영하거나 다른 사용자에게 공개할 앱이라면 조직 관리자 정책과 Google의 검증 요구사항도 함께 적용됩니다.
시작 전에
- GEODE v1.0.0 이상과 대화형 로컬 터미널
- Google 계정과 직접 관리할 Google Cloud 프로젝트
- macOS Keychain, Windows Credential Locker, Linux Secret Service 중 하나
안전한 OS 키링을 사용할 수 없으면 GEODE는 로그인을 거부합니다. refresh token이나 client secret을 평문 파일로 대신 저장하지 않습니다.
1. 필요한 API 활성화
Google Cloud 콘솔의 APIs & Services → Library에서 사용할 서비스에 해당하는 API만 활성화합니다. Google의 공식 API 활성화 가이드도 같은 순서를 안내합니다.
| GEODE 기능 | 활성화할 API |
|---|---|
| Gmail 읽기·전송 | Gmail API |
| Calendar 일정 조회·생성·스케줄러 동기화 | Google Calendar API |
| Drive·Docs·Sheets | Google Drive API, Google Docs API, Google Sheets API |
| Tasks | Google Tasks API |
| Contacts | People API |
2. 동의 화면 구성
Google Auth platform의 Branding, Audience, Data Access를 채웁니다. 처음 시험할 때는 Audience를 External의 Testing으로 두고 자신의 계정을 test user로 추가하는 것이 가장 빠릅니다. 자세한 필드는 OAuth 동의 화면 구성을 따릅니다.
- Internal: Workspace 조직 내부 사용자 전용. 조직 관리자 정책을 따릅니다.
- External · Testing: 첫 시험에 적합합니다. test user가 필요하고, 기본 프로필 범위를 넘는 승인의 refresh token은 7일 뒤 만료될 수 있습니다.
- External · In production: 지속 사용 또는 배포용입니다. 개인적으로 아는 100명 미만만 쓰는 앱은 검증 예외 대상이 될 수 있지만, 미검증 경고와 사용자 상한·정책은 그대로 적용됩니다.
정확한 수명 조건은 Google의 OAuth 앱 게시 상태 도움말, 개인용 예외 조건은 앱 검증 요구사항을 기준으로 확인하십시오.
Gmail 읽기의 gmail.readonly는 Restricted scope입니다. 여러 사람에게 배포하거나 조직 데이터에 접근하면 Google의 앱 검증, 제한 범위 검토, 보안 평가 요건을 별도로 확인하십시오. 개인용 BYO 클라이언트라는 사실이 Google API 정책을 없애지는 않습니다.
3. Desktop 앱 자격 만들기
- Google Auth platform의 Clients로 이동합니다.
- Create client를 누르고 Application type을 Desktop app으로 고릅니다.
- 생성 후 JSON을 내려받아 로컬의 안전한 경로에 둡니다.
Web application 자격이나 OOB 복사·붙여넣기 흐름은 사용하지 않습니다. GEODE는 Google의 Desktop 앱 OAuth 지침에 맞춰 시스템 브라우저, 임의의 127.0.0.1 포트, PKCE S256, state 검증을 사용합니다. 자격 생성 화면의 세부 순서는 Google Workspace 자격 만들기를 참고하십시오.
4. GEODE에서 연결
셸 명령이 아니라 geode 대화형 화면 안에서 실행합니다. 인자 없는 명령은 JSON 경로와 서비스 선택을 차례로 묻습니다.
geode > /login google # 또는 한 번에 한 줄로 지정 > /login google --client-json ~/Downloads/client_secret.json --services gmail-send,calendar-read,workspace-files
recommended 선택은 gmail-send,calendar-read,workspace-files입니다. Gmail 읽기처럼 더 강한 권한은 필요할 때만 별도로 추가하십시오.
| 번들 | 권한과 도구 표면 | 분류 |
|---|---|---|
gmail-send | 메일함을 읽지 않고 메일 전송 | Sensitive |
gmail-read | Gmail 검색·읽기 | Restricted |
calendar-read | 계정 소유 캘린더의 일정 읽기 | Sensitive |
calendar-write | 일정 조회·생성과 GEODE 스케줄러 동기화. v1.0.0에는 임의 일정 수정·삭제 도구가 없음 | Sensitive |
workspace-files | GEODE가 만든 Drive·Docs·Sheets 파일. v1.0.0에는 기존 파일용 Google Picker가 없음 | Non-sensitive |
tasks-read | Google Tasks 읽기 | Sensitive |
tasks-write | Google Tasks 읽기·변경 | Sensitive |
contacts-read | People API로 Contacts 읽기 | Sensitive |
workspace-files는 전체 Drive 범위가 아니라 drive.file을 사용합니다. v1.0.0의 지원 경로는 GEODE가 만든 파일입니다. 이 scope 자체는 Picker로 사용자가 연 파일도 다룰 수 있지만, GEODE v1.0.0은 기존 파일을 고르는 Google Picker를 제공하지 않습니다.
5. 상태 확인과 계정 관리
/login google services /login google status /login google use user@example.com /login google --new-account --services calendar-read /login google --services calendar-write,tasks-write --replace-services /login google logout user@example.com
기존 계정에 번들을 추가하면 설치형 앱의 제약 때문에 기존 번들과 새 번들의 합집합으로 다시 동의합니다. 권한을 줄이려면 남길 전체 번들을--replace-services와 함께 지정합니다. 브라우저에서 다른 Google 계정을 선택하면 GEODE는 저장하지 않고 중단합니다. 두 번째 계정은 --new-account로 시작하십시오.
정보가 저장되는 위치
| 층 | 저장 정보 | 저장하지 않는 정보 |
|---|---|---|
OS keyring · geode.google.oauth | client secret, refresh token, 계정 이메일, 표시 이름 | 메일·일정·파일·태스크·연락처 내용 |
~/.geode/google/accounts.json | schema version, 단조 증가 revision, 활성 account id, client/project id, 번들, 실제 승인 scope, secret_ref, 상태·시각 | 토큰, client secret, 이메일, 표시 이름, Workspace 내용 |
Process memory | 짧은 수명의 access token과 expiry | 데몬 auth reload와 logout 뒤에는 유지하지 않음 |
Durable session/tool stores · SQLite | 도구 이름을 담은 _personal_data_omitted 표식. 바깥 호출 행은 call id를 유지 | Workspace 도구의 원문 입력·결과 |
메타데이터 레지스트리는 0700 디렉터리 안의 0600 파일이며, 프로세스 락과 .accounts.lock을 잡고 atomic replace합니다. 손상되거나 모르는 schema_version은 자동 초기화하지 않고 닫힌 채로 실패합니다. 사용자가 대화창에 직접 쓴 내용과 모델이 일반 대화문으로 작성한 요약은 GEODE의 통상 세션 보존 정책을 따릅니다. 영속 tool/session 저장소에는 원문 입력·결과가 복사되지 않습니다. 별도의 회전형 런타임 로그는 Workspace 결과 payload를 의도적으로 복사하지 않지만, 제한된 Google API 오류 진단은 남을 수 있으므로 일반 운영 로그 보존 정책으로 관리하십시오. 전체 JSON 스키마와 동시성 계약은 Google Workspace OAuth 설계 기록에 있습니다.
매 호출 동의 경계
Workspace 읽기 결과는 선택한 LLM 프로바이더로 전달될 수 있습니다. 그래서 GEODE는 개인 데이터가 포함된 읽기와 변경 작업 모두에 대해 도구 호출 직전에 affirmative consent를 다시 받습니다. 이 승인은 always-allow로 캐시할 수 없고, headless·서브에이전트에서는 닫힌 채로 거부되며 HITL 0이나 권한 건너뛰기로 우회할 수 없습니다.
자주 만나는 문제
| 증상 | 해법 |
|---|---|
| access_denied 또는 앱 접근 불가 | External Testing이라면 로그인 계정을 test user에 추가하고 Audience를 확인합니다. |
| 약 7일마다 다시 로그인해야 함 | External Testing 토큰 수명입니다. 개인 장기 사용이면 정책을 검토한 뒤 In production 전환을 고려합니다. |
| API가 비활성이라는 403 | 오류에 나온 Gmail, Calendar, Drive, Docs, Sheets, Tasks, People API를 같은 Cloud 프로젝트에서 활성화합니다. |
| 필요한 번들이 없다는 안내 | /login google --services <bundle>로 기존 번들에 추가합니다. |
| 다른 계정이라는 오류 | 현재 계정으로 다시 동의하거나 --new-account를 사용합니다. |
| secure keyring이 없다는 오류 | 운영체제 자격 저장소를 활성화합니다. 평문 fallback은 지원하지 않습니다. |
Hermes는 어떻게 풀었나
Hermes Agent도 사용자 소유 Desktop 클라이언트를 선택하지만, 배포 단위는 런타임 명령이 아니라 bundled google-workspaceSkill과 Python 스크립트입니다. 검사한 구현은 고정 localhost 실패 redirect URL을 사용자가 다시 붙여넣는 분리형 흐름과 ~/.hermes 아래 client/token JSON을 사용합니다. 쓰기 전 확인은 Skill 절차가 담당합니다.
GEODE는 그 아이디어에서 BYO client, 서비스 중심 설정, PKCE/state, revoke를 채택하되 trust boundary를 바꿨습니다. 로컬 thin CLI가 임의 loopback callback을 직접 받고, 장기 secret은 OS keyring에 두며, 멀티 계정과 활성 계정을 스키마로 관리하고, 개인 데이터와 mutation 승인은 executor가 매 호출 강제합니다. 비교 근거는 Hermes Google Workspace Skill과 setup.py입니다.
다음
- 인증과 OAuth 레퍼런스. 명령과 저장소 계약을 빠르게 찾습니다.
- Google Workspace API 사용자 데이터 정책. Agentic 기능에 적용되는 공식 정책입니다.
- Gmail API scope. Sensitive와 Restricted 분류를 확인합니다.