고급5분 소요openclawconceptsoauth

OAuth

OAuth 문서는 OpenClaw 공식 문서(concepts/oauth)를 한국어로 정리한 가이드입니다. OAuth in OpenClaw: token exchange, storage, and multi-account patterns 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

OAuth in OpenClaw: token exchange, storage, and multi-account patterns

한국어 가이드 범위: concepts/oauth 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

The token sink (why it exists)
Storage (where tokens live)
Anthropic Claude CLI reuse
OAuth exchange (how login works)
Anthropic setup-token
OpenAI Codex (ChatGPT OAuth)
Refresh + expiry
Multiple accounts (profiles) + routing
1) Preferred: separate agents
2) Advanced: multiple profiles in one agent
관련 문서

상세 내용

본문

OpenClaw supports OAuth ("subscription auth") for providers that offer it, notably OpenAI Codex (ChatGPT OAuth) and Anthropic Claude CLI reuse. For Anthropic, the practical split is:

주요 항목:

Anthropic API key: normal Anthropic API billing.
Anthropic Claude CLI / subscription auth inside OpenClaw: Anthropic staff
how the OAuth token exchange works (PKCE)
where tokens are stored (and why)
how to handle multiple accounts (profiles + per-session overrides)

openclaw models auth login --provider <id>

The token sink (why it exists)

OAuth providers commonly mint a new refresh token on every login/refresh. Some providers invalidate the previous refresh token when a new one is issued for the same user/app. Practical symptom: log in via OpenClaw and via Claude Code / Codex CLI, and one of them randomly gets logged out later.

주요 항목:

the runtime reads credentials from one place per agent
multiple profiles can coexist and route deterministically
external CLI reuse is provider-specific: once OpenClaw owns a local OAuth
status/startup paths scope external CLI discovery to the provider set

Storage (where tokens live)

Secrets live per agent, keyed by the logical name auth-profiles.json (the underlying store is the agent's SQLite database; the JSON name is kept for compatibility and tooling display):

주요 항목:

Auth profiles (OAuth + API keys + optional value-level refs):
Legacy compatibility file: ~/.openclaw/agents/<agentId>/agent/auth.json
~/.openclaw/credentials/oauth.json (imported into the auth profile store on first use)

Anthropic Claude CLI reuse

OpenClaw supports Anthropic Claude CLI reuse and claude -p as a sanctioned auth path. If you already have a local Claude login on the host, onboarding/configure can reuse it directly. Anthropic setup-token remains available as a supported token-auth path, but OpenClaw prefers Claude CLI reuse when it is available.

OpenClaw's interactive login flows are implemented in openclaw/plugin-sdk/llm.ts and wired into the wizards/commands.

Anthropic setup-token

create the token by running claude setup-token on any machine with Claude Code, then start Anthropic setup-token or paste-token from OpenClaw 2. OpenClaw stores the resulting Anthropic credential in an auth profile 3. model selection stays on anthropic/... 4. existing Anthropic auth profiles remain available for rollback/order control

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including OpenClaw workflows.

openclaw models auth login --provider openai

Refresh + expiry

Profiles store an expires timestamp. At runtime:

주요 항목:

if expires is in the future, use the stored access token
if expired, refresh (under a file lock) and overwrite the stored credentials
if a secondary agent reads an inherited main-agent OAuth profile, the
externally managed CLI credentials (Claude CLI, narrow Codex CLI bootstrap;

Multiple accounts (profiles) + routing

Two patterns:

1) Preferred: separate agents

If you want "personal" and "work" to never interact, use isolated agents (separate sessions + credentials + workspace):

openclaw agents add work
openclaw agents add personal

2) Advanced: multiple profiles in one agent

The auth profile store supports multiple profile IDs for the same provider. Pick which one is used:

주요 항목:

globally via config ordering (auth.order)
per-session via /model ...@<profileId>
/model Opus@anthropic:work
Model failover (rotation + cooldown rules)
Slash commands (command surface)

openclaw models auth list --provider <id>

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/oauth
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw models auth login --provider <id>

openclaw models auth login --provider openai

openclaw agents add work
openclaw agents add personal

openclaw models auth list --provider <id>

OAuth

핵심 요약

OAuth in OpenClaw: token exchange, storage, and multi-account patterns

한국어 가이드 범위: concepts/oauth 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

The token sink (why it exists)
Storage (where tokens live)
Anthropic Claude CLI reuse
OAuth exchange (how login works)
Anthropic setup-token
OpenAI Codex (ChatGPT OAuth)
Refresh + expiry
Multiple accounts (profiles) + routing
1) Preferred: separate agents
2) Advanced: multiple profiles in one agent
관련 문서

상세 내용

본문

OpenClaw supports OAuth ("subscription auth") for providers that offer it, notably OpenAI Codex (ChatGPT OAuth) and Anthropic Claude CLI reuse. For Anthropic, the practical split is:

주요 항목:

Anthropic API key: normal Anthropic API billing.
Anthropic Claude CLI / subscription auth inside OpenClaw: Anthropic staff
how the OAuth token exchange works (PKCE)
where tokens are stored (and why)
how to handle multiple accounts (profiles + per-session overrides)

openclaw models auth login --provider <id>

The token sink (why it exists)

주요 항목:

the runtime reads credentials from one place per agent
multiple profiles can coexist and route deterministically
external CLI reuse is provider-specific: once OpenClaw owns a local OAuth
status/startup paths scope external CLI discovery to the provider set

Storage (where tokens live)

Secrets live per agent, keyed by the logical name auth-profiles.json (the underlying store is the agent's SQLite database; the JSON name is kept for compatibility and tooling display):

주요 항목:

Auth profiles (OAuth + API keys + optional value-level refs):
Legacy compatibility file: ~/.openclaw/agents/<agentId>/agent/auth.json
~/.openclaw/credentials/oauth.json (imported into the auth profile store on first use)

Anthropic Claude CLI reuse

OpenClaw's interactive login flows are implemented in openclaw/plugin-sdk/llm.ts and wired into the wizards/commands.

Anthropic setup-token

create the token by running claude setup-token on any machine with Claude Code, then start Anthropic setup-token or paste-token from OpenClaw 2. OpenClaw stores the resulting Anthropic credential in an auth profile 3. model selection stays on anthropic/... 4. existing Anthropic auth profiles remain available for rollback/order control

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including OpenClaw workflows.

openclaw models auth login --provider openai

Refresh + expiry

Profiles store an expires timestamp. At runtime:

주요 항목:

if expires is in the future, use the stored access token
if expired, refresh (under a file lock) and overwrite the stored credentials
if a secondary agent reads an inherited main-agent OAuth profile, the
externally managed CLI credentials (Claude CLI, narrow Codex CLI bootstrap;

Multiple accounts (profiles) + routing

Two patterns:

1) Preferred: separate agents

If you want "personal" and "work" to never interact, use isolated agents (separate sessions + credentials + workspace):

openclaw agents add work
openclaw agents add personal

2) Advanced: multiple profiles in one agent

The auth profile store supports multiple profile IDs for the same provider. Pick which one is used:

주요 항목:

globally via config ordering (auth.order)
per-session via /model ...@<profileId>
/model Opus@anthropic:work
Model failover (rotation + cooldown rules)
Slash commands (command surface)

openclaw models auth list --provider <id>

실습 체크리스트

공식 문서와 로컬 버전을 대조합니다: https://docs.openclaw.ai/concepts/oauth
관련 CLI는 openclaw --help 및 하위 명령 --help로 옵션을 확인합니다.
설정 변경 시 openclaw config / openclaw doctor로 유효성을 검사합니다.
Gateway·채널·플러그인 변경 후에는 필요 시 Gateway를 재시작합니다.

자주 쓰는 명령·설정 예시

openclaw models auth login --provider <id>

openclaw models auth login --provider openai

openclaw agents add work
openclaw agents add personal

openclaw models auth list --provider <id>

OAuth

핵심 요약

문서 구성

상세 내용

본문

The token sink (why it exists)

Storage (where tokens live)

Anthropic Claude CLI reuse

Anthropic setup-token

OpenAI Codex (ChatGPT OAuth)

Refresh + expiry

Multiple accounts (profiles) + routing

1) Preferred: separate agents

2) Advanced: multiple profiles in one agent

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

OAuth

핵심 요약

문서 구성

상세 내용

본문

The token sink (why it exists)

Storage (where tokens live)

Anthropic Claude CLI reuse

Anthropic setup-token

OpenAI Codex (ChatGPT OAuth)

Refresh + expiry

Multiple accounts (profiles) + routing

1) Preferred: separate agents

2) Advanced: multiple profiles in one agent

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

OAuth

핵심 요약

문서 구성

상세 내용

본문

The token sink (why it exists)

Storage (where tokens live)

Anthropic Claude CLI reuse

OAuth exchange (how login works)

Anthropic setup-token

OpenAI Codex (ChatGPT OAuth)

Refresh + expiry

Multiple accounts (profiles) + routing

1) Preferred: separate agents

2) Advanced: multiple profiles in one agent

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

OAuth

핵심 요약

문서 구성

상세 내용

본문

The token sink (why it exists)

Storage (where tokens live)

Anthropic Claude CLI reuse

OAuth exchange (how login works)

Anthropic setup-token

OpenAI Codex (ChatGPT OAuth)

Refresh + expiry

Multiple accounts (profiles) + routing

1) Preferred: separate agents

2) Advanced: multiple profiles in one agent

관련 문서

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드