OAuth

OpenClaw은 OAuth를 지원하는 프로바이더(특히 OpenAI Codex (ChatGPT OAuth))를 위해 “구독 인증”을 제공합니다. Anthropic 구독의 경우 setup-token 방식을 사용합니다. Anthropic은 과거에 Claude Code 외부에서의 구독 사용을 제한한 적이 있으므로, 사용 여부는 본인의 판단에 맡기며 현재 Anthropic 정책을 직접 확인하시기 바랍니다. OpenAI Codex OAuth는 OpenClaw과 같은 외부 도구에서의 사용이 공식적으로 지원됩니다. 이 페이지에서는 다음을 설명합니다:

프로덕션 환경의 Anthropic에서는 구독 setup-token 인증보다 API 키 인증이 더 안전하고 권장되는 방식입니다.

OAuth 토큰 교환 작동 방식 (PKCE)
토큰이 저장되는 위치 (와 그 이유)
멀티 계정 처리 방법 (프로필 + 세션별 오버라이드)

OpenClaw은 자체 OAuth나 API 키 플로우를 포함하는 프로바이더 플러그인도 지원합니다. 다음 명령으로 실행할 수 있습니다:

openclaw models auth login --provider <id>

토큰 싱크 (존재 이유)

OAuth 프로바이더는 로그인/갱신 과정에서 새로운 리프레시 토큰을 발급하는 것이 일반적입니다. 일부 프로바이더(또는 OAuth 클라이언트)는 동일한 사용자/앱에 대해 새 토큰이 발급되면 기존 리프레시 토큰을 무효화할 수 있습니다.

실제 증상:

OpenClaw 과 Claude Code / Codex CLI를 통해 각각 로그인하면 → 나중에 둘 중 하나가 무작위로 “로그아웃”됨

이 문제를 줄이기 위해 OpenClaw은 auth-profiles.json을 토큰 싱크로 취급합니다:

런타임이 한 곳에서 자격 증명을 읽음
여러 프로필을 유지하고 결정적으로 라우팅 가능

저장소 (토큰 저장 위치)

시크릿은 에이전트별로 저장됩니다:

인증 프로필 (OAuth + API 키 + 선택적 값 수준 참조): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
레거시 호환 파일: ~/.openclaw/agents/<agentId>/agent/auth.json (정적 api_key 항목은 발견 시 제거됨)

레거시 가져오기 전용 파일 (여전히 지원되지만 주 저장소가 아님):

~/.openclaw/credentials/oauth.json (처음 사용 시 auth-profiles.json으로 가져옴)

위의 모든 경로는 $OPENCLAW_STATE_DIR (상태 디렉터리 오버라이드)도 지원합니다. 전체 참조: /gateway/configuration

정적 시크릿 참조 및 런타임 스냅샷 활성화 동작에 대해서는 시크릿 관리를 참고하세요.

Anthropic setup-token (구독 인증)

경고: Anthropic setup-token 지원은 기술적 호환성이며 정책적 보장이 아닙니다. Anthropic은 과거에 Claude Code 외부에서의 일부 구독 사용을 차단한 적이 있습니다. 구독 인증 사용 여부는 본인이 판단하고 Anthropic의 현재 약관을 확인하세요.

아무 컴퓨터에서 claude setup-token을 실행한 다음 OpenClaw에 붙여넣으세요:

openclaw models auth setup-token --provider anthropic

다른 곳에서 토큰을 생성한 경우 수동으로 붙여넣으세요:

openclaw models auth paste-token --provider anthropic

확인:

openclaw models status

OAuth 교환 (로그인 작동 방식)

OpenClaw의 대화형 로그인 플로우는 @mariozechner/pi-ai에 구현되어 있으며 위자드/명령어와 연결되어 있습니다.

Anthropic setup-token

플로우 구조:

claude setup-token 실행
OpenClaw에 토큰 붙여넣기
토큰 인증 프로필로 저장 (갱신 없음)

위자드 경로: openclaw onboard → 인증 선택 setup-token (Anthropic).

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth는 Codex CLI 외부(OpenClaw 워크플로우 포함)에서의 사용이 공식적으로 지원됩니다.

플로우 구조 (PKCE):

PKCE verifier/challenge + 랜덤 state 생성
https://auth.openai.com/oauth/authorize?... 열기
http://127.0.0.1:1455/auth/callback에서 콜백 캡처 시도
콜백 바인딩 불가(또는 원격/헤드리스)인 경우 리다이렉트 URL/코드 붙여넣기
https://auth.openai.com/oauth/token에서 교환
액세스 토큰에서 accountId 추출 후 { access, refresh, expires, accountId } 저장

위자드 경로: openclaw onboard → 인증 선택 openai-codex.

갱신 + 만료

프로필에는 expires 타임스탬프가 저장됩니다.

런타임 동작:

expires가 미래인 경우 → 저장된 액세스 토큰 사용
만료된 경우 → (파일 잠금 하에) 갱신하고 저장된 자격 증명 덮어쓰기

갱신 플로우는 자동이므로 일반적으로 수동으로 토큰을 관리할 필요가 없습니다.

멀티 계정 (프로필) + 라우팅

두 가지 패턴이 있습니다:

1) 권장: 별도 에이전트

“개인”과 “업무”가 절대 상호작용하지 않도록 하려면 격리된 에이전트(별도의 세션 + 자격 증명 + 워크스페이스)를 사용하세요:

openclaw agents add work
openclaw agents add personal

그런 다음 에이전트별로 인증을 구성하고(위자드) 대화를 올바른 에이전트로 라우팅합니다.

2) 고급: 하나의 에이전트에 여러 프로필

auth-profiles.json은 동일 프로바이더에 대해 여러 프로필 ID를 지원합니다.

어떤 프로필을 사용할지 선택:

전역적으로 설정 순서 지정 (auth.order)
세션별로 /model ...@<profileId> 사용

예시 (세션 오버라이드):

/model Opus@anthropic:work

존재하는 프로필 ID 확인 방법:

openclaw channels list --json (auth[] 표시)