Auth and OAuth — GEODE Docs

GEODE는 프로바이더마다 두 종류의 자격을 받습니다. 구독 OAuth와 PAYG API 키입니다. 어느 쪽을 쓸지는CredentialSource 하나로 표현되고, 프로파일과 플랜은~/.geode/auth.toml에, API 키는~/.geode/.env에 저장됩니다.

자격 소스

단일 SoT는 core/config/credential_source.py의CredentialSource StrEnum입니다.

값	의미
`auto`	매니페스트 순서 해석. OAuth 우선, PAYG는 `fallback_to_payg`가 켜진 경우에만.
`api_key`	PAYG API 키.
`claude-cli`	claude CLI 구독을 통한 Anthropic OAuth.
`openai-codex`	Codex CLI를 통한 ChatGPT 구독 OAuth.
`oauth`	레거시 별칭. Settings 검증이 받아줍니다.
`none`	해당 프로바이더 비활성 센티널.

선택은 [llm] anthropic_credential_source /openai_credential_source(기본 auto)에 저장됩니다. /login source <provider> <type>은 toml에만 쓰므로 .env를 지워도 선택이 살아남습니다. (provider, source) 쌍마다 구체 어댑터가 하나씩 레지스트리에 등록됩니다(core/llm/adapters/의anthropic_payg, anthropic_oauth,claude_cli, openai_payg,codex_oauth, codex_cli,glm_coding_plan, glm_payg).

/login 대시보드

세션 안의 /login은 플랜과 자격을 한 화면에서 관리합니다(core/cli/commands/login.py). thin CLI에서 로컬로 실행되고, 끝나면 데몬에 인증 상태 리로드를 알립니다.

서브커맨드	동작
`/login openai`	ChatGPT 구독 OAuth 로그인. device-code 플로우는 `core/auth/oauth_login.py`이고, 결과는 `auth.toml`에 OAUTH_BORROWED 플랜 + 프로파일 쌍으로 저장됩니다.
`/login anthropic`	Claude 구독 OAuth. macOS 키체인의 `"Claude Code-credentials"` 항목을 읽습니다(routing.toml `[credentials.keychain]`, override는 `GEODE_ANTHROPIC_KEYCHAIN_SERVICE`).
`/login google`	Gmail, Calendar, Drive, Docs, Sheets, Tasks, Contacts용 Google Workspace OAuth. 사용자가 만든 Desktop 앱 클라이언트를 가져오며 LLM 프로바이더 자격과 분리됩니다.
`/login add`	자격 추가. 키 모양(`sk-ant-`, `sk-proj-`, GLM {id}.{secret})으로 프로바이더를 추정합니다.
`/login use` / `remove`	프로파일 선택과 제거.
`/login route`	프로바이더와 플랜 라우팅 확인.
`/login quota`	구독 쿼터 상태.
`/login source <provider> <type>`	자격 소스 영속화. config.toml `[llm]`에 기록.

Google Workspace

uv나 GitHub에서 설치한 사용자도 중앙 GEODE OAuth 앱 없이 자신의 Google Cloud Desktop 클라이언트로 연결할 수 있습니다. 권장 진입점은/login google입니다. 첫 연결에서는 client JSON 경로와 필요한 서비스 번들을 명시적으로 고릅니다. 자동화하려면 다음처럼 한 줄로 지정할 수 있습니다. Google Cloud 콘솔부터 시작하는 절차는 Google Workspace 연결 가이드에 있습니다.

/login google --client-json ~/Downloads/client_secret.json \
  --services gmail-send,calendar-read,workspace-files

/login google services
/login google status
/login google use user@example.com
/login google --new-account --services calendar-read
/login google --services calendar-read --replace-services
/login google logout user@example.com

인증은 시스템 브라우저, 임의의 127.0.0.1 포트, Authorization Code + PKCE S256 + state 검증을 씁니다. Google이 Desktop 앱의 incremental auth를 지원하지 않으므로 서비스를 더할 때는 대상 활성 계정의 기존 번들과 새 번들의 합집합으로 재동의합니다. 브라우저에서 다른 계정을 고르면 저장하지 않고 실패하며, 두 번째 계정은 --new-account로 연결합니다. 권한을 줄일 때는 유지할 전체 번들과 --replace-services를 함께 지정합니다.gmail-read는 Restricted scope라 기본 권장 묶음에 포함되지 않습니다. Drive·Docs·Sheets는 전체 Drive 대신 non-sensitive drive.file로 GEODE가 만들거나 파일별로 허용된 항목만 다룹니다.

저장소	내용
OS keyring `geode.google.oauth`	refresh token, client secret, 계정 이메일과 표시 이름. 안전한 백엔드가 없으면 로그인은 실패하며 평문 fallback은 없습니다.
`~/.geode/google/accounts.json`	schema version, 단조 증가 revision, 활성 account id, client/project id, 서비스 번들, 실제 granted scopes, 상태와 시각만. 프로세스 간 `.accounts.lock` 뒤 atomic write, 디렉터리 0700·파일 0600.
프로세스 메모리	짧은 수명의 access token과 expiry. 데몬 auth reload와 logout 때 폐기.
세션 영속 저장소	Workspace 도구의 원문 입력·결과는 JSON·SQLite·도구 로그에서 도구 이름을 담은 `_personal_data_omitted` 표식으로 치환하고, 바깥 호출 행만 call id를 유지합니다. 영속 telemetry에는 API 오류 상세를 복사하지 않고, 개인 도구가 포함된 batch는 별도 reflection provider 호출을 건너뜁니다. 별도의 회전형 런타임 로그에는 제한된 Google API 오류 진단이 남을 수 있습니다. 사용자가 직접 쓴 대화문과 모델이 대화문으로 작성한 요약은 일반 세션 보존 정책을 따릅니다.

Workspace 읽기 결과는 선택한 LLM 프로바이더로 전달될 수 있으므로 매 도구 호출 직전에 개인 데이터 disclosure와 affirmative consent가 뜹니다. 이 승인은 always-allow할 수 없고 headless·서브에이전트에서는 닫힌 채로 거부됩니다. Gmail 전송과 Drive/Docs/Sheets/Tasks/Calendar 변경도 같은 비캐시형 매 호출 승인을 거쳐 HITL 0·권한 건너뛰기로 우회할 수 없습니다. 자세한 스키마와 Hermes 비교는 설계 기록docs/architecture/google-workspace-oauth.md에 있습니다.

Codex 토큰 감지

ChatGPT Plus 구독 OAuth는 Codex CLI의 토큰 저장소~/.codex/auth.json을 읽습니다 (core/auth/codex_cli_oauth.py). 토큰 수명은 Codex CLI가 책임집니다. GEODE는 복사본을 영속화하지 않고 읽기만 하며, JWT exp로 만료를 판별합니다.geode setup도 API 키를 묻기 전에 이 파일을 먼저 감지합니다.

PAYG 키

API 키는 시크릿이므로 ~/.geode/.env 층에 삽니다. 온보딩과 /login의 키 기록이 이 계약을 따릅니다 (core/config/env_io.py의 upsert_env).

# ~/.geode/.env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-proj-...
ZAI_API_KEY={id}.{secret}

GLM은 엔드포인트가 둘입니다. Coding Plan(구독 과금)과 PAYG(종량 과금)이고, Coding Plan 키를 PAYG 경로에 쓰면 구독 쿼터를 조용히 우회해 종량 과금됩니다.

실패 모드

증상	원인	해법
응답이 비거나 401	토큰 만료 또는 키 무효	`geode doctor`로 자격 상태를 보고 `/login`으로 갱신합니다. Codex 쪽은 `codex login`을 다시 실행합니다.
소스를 바꿨는데 그대로	구버전의 `GEODE_*_CREDENTIAL_SOURCE` env 줄이 마스크	`geode config explain anthropic_credential_source`로 WINNER 층을 확인하고 그 줄을 지웁니다.
서브프로세스에서 `AdapterNotFoundError`	어댑터 레지스트리는 프로세스 단위인데 부트스트랩 누락	워커가 `core.llm.adapters.registry.bootstrap_builtins()`를 호출하는지 확인합니다.
구독이 있는데 PAYG로 과금	`auto`가 OAuth를 못 찾고 키로 해석	`/login route`와 `/login quota`로 플랜 상태를 확인하고, 필요하면 소스를 `claude-cli`/`openai-codex`로 고정합니다.

Google Workspace 연결. Cloud 프로젝트와 Desktop OAuth client 설정.
OAuth 토큰 회전. 갱신과 쿨다운의 런타임 동작.
프로바이더 설정. 처음 자격을 붙이는 절차.
설정 기초. 시크릿 층과 해석 사다리.