OAuth와 구독 인증 설정하기

개발 도구를 사용하다 보면 여러 기기나 터미널에서 동시에 로그인 세션을 유지하는 게 생각보다 까다롭다는 걸 느끼실 거예요. 한쪽에서 로그인하면 다른 쪽 세션이 갑자기 끊겨서 다시 인증해야 하는 상황은 개발 흐름을 방해하곤 하죠. OpenClaw는 이런 번거로움을 줄이기 위해 인증 정보를 체계적으로 관리할 수 있는 구조를 가지고 있어요.

필요한 것

• OpenAI Codex (ChatGPT OAuth) 또는 Anthropic 구독 계정
• OpenClaw CLI가 설치된 환경

빠른 시작

가장 빠르게 인증을 시작하는 방법은 전용 Plugin을 사용하는 거예요. 아래 명령어를 실행해 보세요.

openclaw models auth login --provider <id>

Anthropic (Claude Pro/Max) 설정하기

Anthropic 구독 사용자는 setup-token 방식을 사용해요.

1. 아무 장비에서나 claude setup-token을 실행하고 생성된 토큰을 복사하세요.
2. OpenClaw에 아래 명령어로 붙여넣으세요.

   openclaw models auth setup-token --provider anthropic

   만약 이미 토큰을 가지고 있다면 직접 입력할 수도 있어요.

   openclaw models auth paste-token --provider anthropic

OpenAI Codex (ChatGPT OAuth) 설정하기

OpenAI는 PKCE 방식의 OAuth 흐름을 사용해요.

1. openclaw onboard 명령어를 실행하고 인증 옵션에서 openai-codex를 선택하세요.
2. 브라우저가 열리면 로그인을 진행하고, 자동으로 콜백이 처리되지 않는 환경이라면 리다이렉트 URL이나 코드를 직접 붙여넣으세요.

Storage: 인증 정보 저장 위치

OpenClaw는 인증 정보를 Agent 단위로 격리해서 저장해요. 모든 경로는 $OPENCLAW_STATE_DIR 환경 변수로 변경할 수 있어요.

• 현재 사용되는 저장소:
  • 프로필 정보: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • 런타임 캐시: ~/.openclaw/agents/<agentId>/agent/auth.json (자동 관리되므로 직접 수정하지 마세요)
• Legacy 저장소:
  • ~/.openclaw/credentials/oauth.json (처음 실행 시 auth-profiles.json으로 마이그레이션돼요)

Multiple Accounts 관리하기

여러 계정을 사용해야 한다면 두 가지 방법을 추천해요.

1. Agent 분리 (권장): ‘work’와 ‘personal’처럼 Agent를 완전히 나누면 워크스페이스와 인증 정보가 섞이지 않아요.

   openclaw agents add work
   openclaw agents add personal

2. 프로필 ID 사용: 하나의 Agent 안에서 여러 프로필을 두고 슬래시 명령어로 전환할 수 있어요.
   • 예: /model Opus@anthropic:work

문제 해결

다른 도구와 함께 사용할 때 로그아웃되는 현상

OpenClaw와 Claude Code 또는 Codex CLI를 동시에 쓰면 한쪽이 로그아웃될 수 있어요. 이는 OAuth 제공자가 새 Refresh Token을 발급하면서 기존 토큰을 무효화하기 때문이에요.

• 해결책: OpenClaw는 auth-profiles.json을 token sink로 사용해서 토큰을 한 곳에서 읽고 쓰도록 관리해요. 인증이 자꾸 풀린다면 해당 파일에 프로필이 올바르게 등록되어 있는지 확인해 보세요.

토큰 만료 문제

OpenClaw는 expires 타임스탬프를 확인해서 토큰이 만료되었다면 자동으로 갱신(Refresh)을 시도해요. 파일 잠금(File lock) 기능을 사용하므로 여러 프로세스가 동시에 토큰을 갱신하려고 해도 안전해요.

추가적인 도움이 필요하신가요? AI Setup Assistant에게 물어보세요!

다음 단계

• /concepts/model-failover: 모델 장애 조치 및 로테이션 규칙 알아보기
• /tools/slash-commands: 채팅 중 사용할 수 있는 슬래시 명령어 확인하기