Authentication

기준일: 2026-07-26
공식 기준: Authentication

Authentication 문서는 OpenClaw 공식 문서(gateway/authentication)를 한국어로 정리한 가이드입니다. Model authentication: OAuth, API keys, Claude CLI reuse, and Anthropic setup-token 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치된 CLI 버전과 공식 원문을 확인하세요.

핵심 요약

Model authentication: OAuth, API keys, Claude CLI reuse, and Anthropic setup-token

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

문서 구성

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

• Recommended setup: API key (any provider)
• Anthropic: Claude CLI reuse
• Run on the gateway host
• Manual token entry
• SecretRef-backed credentials
• Checking model auth status
• API key rotation (gateway)
• Removing provider auth while the gateway is running
• Controlling which credential is used
• OpenAI and legacy openai-codex ids
• During login (CLI)
• Per-session (chat command)
• Per-agent (CLI override)
• 트러블슈팅
• "No credentials found"
• Token expiring/expired
• 관련 문서

상세 내용

본문

This page covers model provider authentication (API keys, OAuth, Claude CLI reuse, Anthropic setup-token). For gateway connection authentication (token, password, trusted-proxy), see Configuration and Trusted Proxy Auth.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Full OAuth flow and storage layout: /concepts/oauth
• SecretRef-based auth (env/file/exec providers): Secrets Management
• Credential eligibility/reason codes used by models status --probe: Auth Credential Semantics

Recommended setup: API key (any provider)

1. Create an API key in your provider console. 2. Put it on the gateway host (the machine running openclaw gateway):

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw models status

cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF

openclaw models status
openclaw doctor

Anthropic: Claude CLI reuse

Anthropic setup-token auth remains a supported path. Claude CLI reuse (claude -p-style usage) is also sanctioned for this integration; when a Claude CLI login is available on the host, that's the preferred path for local/desktop use. For long-lived gateway hosts, an Anthropic API key is still the most predictable choice, with explicit server-side billing control.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Run on the gateway host

claude auth login claude auth status --text openclaw models auth login --provider anthropic --method cli --set-default ```

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Manual token entry

Works for any provider; writes the per-agent SQLite auth store and updates config:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw models auth paste-token --provider openrouter

SecretRef-backed credentials

주요 항목:

• api_key credentials can use keyRef: { source, provider, id }
• token credentials can use tokenRef: { source, provider, id }
• OAuth-mode profiles reject SecretRef credentials: if auth.profiles.<id>.mode is "oauth", a SecretRef-backed keyRef/tokenRef for that profile is rejected.

Checking model auth status

Automation-friendly check, exit 1 when expired/missing, 2 when expiring:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• Probe rows can come from auth profiles, env credentials, or models.json.
• If auth.order.<provider> omits a stored profile, probe reports excluded_by_auth_order for that profile instead of trying it.
• If auth exists but OpenClaw can't resolve a probeable model for that provider, probe reports status: no_model.
• Rate-limit cooldowns can be model-scoped: a profile cooling down for one model can still serve a sibling model on the same provider.

openclaw models status
openclaw doctor

openclaw models status --check

openclaw models status --probe

API key rotation (gateway)

Some providers retry a request with an alternate configured key when a call hits a provider rate limit.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Removing provider auth while the gateway is running

When you remove provider auth through the gateway control plane, OpenClaw deletes the saved auth profiles for that provider and aborts active chat/agent runs whose selected model provider matches the removed one. Aborted runs emit the normal cancellation/lifecycle events with stopReason: "auth-revoked", so connected clients can show the run stopped because credentials were removed.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

Controlling which credential is used

이 섹션의 세부 항목은 공식 문서 Controlling which credential is used를 참고하세요.

OpenAI and legacy openai-codex ids

OpenAI API-key profiles and ChatGPT/Codex OAuth profiles both use the canonical provider id openai. Use openai:* profile ids and auth.order.openai for new config.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw doctor --fix
openclaw models auth list --provider openai

During login (CLI)

--profile-id keeps multiple OAuth logins for the same provider separate inside one agent.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw models auth login --provider openai --profile-id openai:ritsuko
openclaw models auth login --provider openai --profile-id openai:lain

openclaw models auth login --provider anthropic --force

Per-session (chat command)

If you change auth order or profile pinning for a chat that's already running, send /new or /reset to start a fresh session — existing sessions keep their current model/profile selection until reset.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

주요 항목:

• /model <alias-or-id>@<profileId> pins a specific provider credential for the current session (example profile ids: anthropic:default, anthropic:work).
• /model (or /model list) shows a compact picker; /model status shows the full view (candidates + next auth profile, plus provider endpoint details when configured).

Per-agent (CLI override)

Auth order overrides are stored in that agent's SQLite auth state:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

트러블슈팅

이 섹션의 세부 항목은 공식 문서 트러블슈팅를 참고하세요.

"No credentials found"

Configure an Anthropic API key on the gateway host, or set up the Anthropic setup-token path, then re-check:

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

openclaw models status

Token expiring/expired

Run openclaw models status to see which profile is expiring. If an Anthropic token profile is missing or expired, refresh it via setup-token or migrate to an Anthropic API key.

위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문과 --help를 확인하세요.

관련 문서

주요 항목:

• Secrets management
• Remote access
• Auth storage

실습 체크리스트

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

자주 쓰는 명령·설정 예시

openclaw models status

cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF

openclaw models status
openclaw doctor

# Run on the gateway host
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

openclaw models auth paste-token --provider openrouter

openclaw models status
openclaw doctor

관련 링크

• 공식 원문: gateway/authentication
• OpenClaw 문서 홈

이 가이드는 공식 문서를 한국어 학습용으로 재구성한 것입니다. 옵션 기본값·플래그 이름은 설치 버전에 따라 달라질 수 있습니다.