Fundamentals

OAuth

OpenClaw는 이를 제공하는 provider(특히 OpenAI Codex (ChatGPT OAuth))에 대해 OAuth를 통한 "구독 인증"을 지원합니다. Anthropic의 경우 실질적인 구분은 이제 다음과 같습니다.

Anthropic API 키: 일반 Anthropic API 과금
OpenClaw 내부의 Anthropic Claude CLI / 구독 인증: Anthropic 직원이 이 사용이 다시 허용된다고 알려주었습니다

OpenAI Codex OAuth는 OpenClaw 같은 외부 도구에서 사용하는 것이 명시적으로 지원됩니다. 이 페이지에서는 다음을 설명합니다.

프로덕션에서 Anthropic을 사용할 때는 API 키 인증이 더 안전한 권장 경로입니다.

OAuth 토큰 교환이 작동하는 방식(PKCE)
토큰이 저장되는 위치와 그 이유
여러 계정을 처리하는 방법(프로필 + 세션별 재정의)

OpenClaw는 자체 OAuth 또는 API 키 흐름을 제공하는 provider Plugin도 지원합니다. 다음으로 실행하세요.

bash

openclaw models auth login --provider <id>

토큰 싱크(존재 이유)

OAuth provider는 로그인/새로 고침 흐름 중에 새 refresh token을 발급하는 경우가 많습니다. 일부 provider(또는 OAuth 클라이언트)는 같은 사용자/앱에 대해 새 refresh token이 발급되면 이전 refresh token을 무효화할 수 있습니다.

실제 증상:

OpenClaw 및 Claude Code / Codex CLI로 로그인함 → 나중에 둘 중 하나가 임의로 "로그아웃"됨

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

런타임은 한 곳에서 자격 증명을 읽습니다
여러 프로필을 유지하고 결정론적으로 라우팅할 수 있습니다
외부 CLI 재사용은 provider별로 다릅니다. Codex CLI는 빈 openai-codex:default 프로필을 부트스트랩할 수 있지만, OpenClaw에 로컬 OAuth 프로필이 생기면 로컬 refresh token이 정본이 됩니다. 다른 통합은 계속 외부에서 관리되며 CLI 인증 저장소를 다시 읽을 수 있습니다
구성된 provider 집합을 이미 아는 상태 및 시작 경로는 외부 CLI 검색 범위를 해당 집합으로 제한하므로, 단일 provider 설정에서 관련 없는 CLI 로그인 저장소를 탐색하지 않습니다

저장소(토큰 위치)

비밀은 agent 인증 저장소에 저장됩니다.

인증 프로필(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

정적 secret 참조와 런타임 스냅샷 활성화 동작은 Secrets Management를 참조하세요.

보조 agent에 로컬 인증 프로필이 없으면 OpenClaw는 기본/메인 agent 저장소에서 read-through 상속을 사용합니다. 읽을 때 메인 agent의 auth-profiles.json을 복제하지 않습니다. OAuth refresh token은 특히 민감합니다. 일부 provider가 사용 후 refresh token을 순환하거나 무효화하기 때문에 일반 복사 흐름은 기본적으로 이를 건너뜁니다. 독립 계정이 필요한 agent에는 별도의 OAuth 로그인을 구성하세요.

Anthropic 레거시 토큰 호환성

OpenClaw는 Anthropic setup-token도 지원되는 토큰 인증 경로로 노출하지만, 이제는 사용 가능한 경우 Claude CLI 재사용 및 claude -p를 우선합니다.

Anthropic Claude CLI 마이그레이션

OpenClaw는 Anthropic Claude CLI 재사용을 다시 지원합니다. 호스트에 이미 로컬 Claude 로그인이 있으면 온보딩/구성에서 이를 직접 재사용할 수 있습니다.

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

OpenClaw의 대화형 로그인 흐름은 @earendil-works/pi-ai에 구현되어 있으며 마법사/명령에 연결되어 있습니다.

Anthropic setup-token

흐름 형태:

OpenClaw에서 Anthropic setup-token을 시작하거나 paste-token 사용
OpenClaw가 결과 Anthropic 자격 증명을 인증 프로필에 저장
모델 선택은 anthropic/...에 유지
기존 Anthropic 인증 프로필은 롤백/순서 제어를 위해 계속 사용 가능

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth는 OpenClaw 워크플로를 포함하여 Codex CLI 외부에서 사용하는 것이 명시적으로 지원됩니다.

흐름 형태(PKCE):

PKCE verifier/challenge + 무작위 state 생성
https://auth.openai.com/oauth/authorize?... 열기
http://127.0.0.1:1455/auth/callback에서 콜백 캡처 시도
콜백을 바인딩할 수 없거나 원격/headless 환경이면 리디렉션 URL/코드 붙여넣기
https://auth.openai.com/oauth/token에서 교환
access token에서 accountId를 추출하고 { access, refresh, expires, accountId } 저장

마법사 경로는 openclaw onboard → 인증 선택 openai-codex입니다.

새로 고침 + 만료

프로필은 expires 타임스탬프를 저장합니다.

런타임에서:

expires가 미래이면 → 저장된 access token 사용
만료되었으면 → 파일 잠금 아래에서 새로 고침하고 저장된 자격 증명 덮어쓰기
보조 agent가 상속된 메인 agent OAuth 프로필을 읽는 경우, 새로 고침은 refresh token을 보조 agent 저장소로 복사하는 대신 메인 agent 저장소에 다시 씁니다
예외: 일부 외부 CLI 자격 증명은 계속 외부에서 관리됩니다. OpenClaw는 복사된 refresh token을 소비하는 대신 해당 CLI 인증 저장소를 다시 읽습니다. Codex CLI 부트스트랩은 의도적으로 더 좁습니다. 빈 openai-codex:default 프로필을 시드한 다음, OpenClaw가 소유한 새로 고침이 로컬 프로필을 정본으로 유지합니다.

새로 고침 흐름은 자동입니다. 일반적으로 토큰을 수동으로 관리할 필요는 없습니다.

여러 계정(프로필) + 라우팅

두 가지 패턴:

1) 권장: 별도 agent

"personal"과 "work"가 절대 상호작용하지 않게 하려면 격리된 agent(별도 세션 + 자격 증명 + 워크스페이스)를 사용하세요.

bash

openclaw agents add workopenclaw agents add personal

그런 다음 agent별로 인증(마법사)을 구성하고 채팅을 올바른 agent로 라우팅하세요.

2) 고급: 하나의 agent에 여러 프로필

auth-profiles.json은 같은 provider에 대해 여러 프로필 ID를 지원합니다.

사용할 프로필을 선택하는 방법:

구성 순서(auth.order)를 통해 전역으로
/model ...@<profileId>를 통해 세션별로

예시(세션 재정의):

/model Opus@anthropic:work

어떤 프로필 ID가 있는지 확인하는 방법:

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