설정레퍼런스

인증과 OAuth

자격 소스, /login OAuth 프로파일, Codex 토큰 감지, API 키가 사는 곳을 다룹니다.

이 문서의 목차

자격 소스
/login 대시보드
Google Workspace
ChatGPT 자격 가져오기
PAYG 키
실패 모드
다음

GEODE는 구독 경로와 PAYG API 키를 받습니다. 어느 쪽을 쓸지는 CredentialSource 하나로 표현됩니다. GEODE에서 등록한 구독 자격과 API 키, 플랜은 ~/.geode/auth.toml에 저장됩니다. 외부 환경 변수와 기존 .env 키는 별도 입력으로 계속 읽습니다.

자격 소스

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

값	의미
`auto`	매니페스트 순서 해석. OAuth 우선, PAYG는 `fallback_to_payg`가 켜진 경우에만.
`api_key`	PAYG API 키.
`claude-cli`	퇴역한 Anthropic 입력. migration 오류만 내며 실행되지 않습니다.
`openai-codex`	프로세스 내부 `codex-oauth` 어댑터를 통한 ChatGPT 구독 OAuth.
`oauth`	OpenAI는 Codex OAuth 별칭, Anthropic은 퇴역 오류 입력.
`none`	해당 프로바이더 비활성 센티널.

Anthropic과 OpenRouter의 내장 경로는 api_key뿐입니다. 과거 claude-cli/oauth 값은 migration 안내를 위해 읽지만 binary나 네트워크 호출 전에 중단됩니다.

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

세션 안의 /login은 플랜과 자격을 한 화면에서 관리합니다(core/cli/commands/login.py). 키 입력과 브라우저 로그인(add, set-key, openai, anthropic, google)과 source는 thin CLI에서 실행합니다. 키는 저장한 뒤 데몬에 리로드를 알립니다. 조회와 plan·프로파일 변경은 실행 중인 상태를 가진 데몬이 처리합니다. 저장하지 못한 변경은 성공으로 표시하지 않습니다.

/login add, /login anthropic, 온보딩과 레거시 /key는 같은 인증 저장 함수를 사용하며.env나 전역 설정에 키를 복사하지 않습니다. 저장 실패는 기존 자격을 유지하고, 별도 프로세스의 리로드 실패는 따로 표시합니다. 모델 도구 manage_login은 비밀값 없는 조회·선택만 받습니다. 기본 키 등록은 터미널의 숨김 입력으로 진행하며, 기존 /key …와 /login set-key <plan> <key> 명시 입력도 호환됩니다. 폐기된set_api_key와 manage_auth 도구는 제거했습니다.

서브커맨드	동작
`/login openai`	ChatGPT 구독 OAuth 로그인. device-code 플로우는 `core/auth/oauth_login.py`이고, 결과는 `auth.toml`에 OAUTH_BORROWED 플랜 + 프로파일 쌍으로 저장됩니다.
`/login anthropic`	숨김 입력으로 Anthropic PAYG 키를 등록합니다. 세션 소스 선택은 바꾸지 않습니다.
`/login google`	Gmail, Calendar, Drive, Docs, Sheets, Tasks, Contacts용 Google Workspace OAuth. 사용자가 만든 Desktop 앱 클라이언트를 가져오며 LLM 프로바이더 자격과 분리됩니다.
`/login add`	ChatGPT 구독 로그인 또는 프로바이더 API 키(Anthropic, OpenAI, OpenRouter, GLM)를 한 메뉴에서 고릅니다. API 키는 선택한 프로바이더에 대해 한 번만 입력하며, 초기 설정도 같은 입력·저장 경로를 사용합니다. 다른 프로바이더를 추가할 때는 다시 실행합니다.
`/login use` / `remove`	프로파일 선택과 제거.
`/login route`	프로바이더와 플랜 라우팅 확인.
`/login quota`	플랜에 선언된 호출 한도. GEODE는 사용량을 세지 않으므로 현재 사용량은 프로바이더 계정에서 확인합니다.
`/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는 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에 있습니다.

ChatGPT 자격 가져오기

기본 경로는 /login openai가 발급해 ~/.geode/auth.toml에 저장한 자격입니다. 기존 ~/.codex/auth.json도 읽을 수 있지만 이는 자격 가져오기일 뿐이며 GEODE는 Codex CLI를 추론에 실행하지 않습니다.

PAYG 키

대화형 등록은 권한 0600의 auth.toml에 저장합니다./login set-key <plan-id>는 기존 플랜의 키를 숨김 입력으로 바꿉니다. 자동화나 외부 비밀 관리 도구에서 공급하는 환경 변수도 지원합니다. 기존 환경 파일을 자동으로 삭제하거나 옮기지는 않습니다.

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

GLM은 PAYG API 키 경로를 지원합니다. 2026-09-24 Coding Plan 정책은 공식 지원 도구로 사용을 제한하며 GEODE 사용 자격은 확인되지 않았습니다. 기존 구독 프로필은 보존하되 실행을 차단하고, PAYG로 자동 전환하지 않습니다.

실패 모드

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

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

GEODE 저장소의 문서 사이트에서 옮겨 온 문서입니다. 원문 커밋 de077a4 · GitHub에서 원문 보기

자격 소스

/login 대시보드

Google Workspace

ChatGPT 자격 가져오기

PAYG 키

실패 모드

다음