인증

OpenClaw는 모델 제공자 인증을 위해 OAuth와 API 키를 지원합니다. 항시 가동 게이트웨이 호스트의 경우, API 키가 가장 안정적인 선택입니다. 구독/OAuth 흐름도 제공자 계정 모델과 일치하는 경우 지원됩니다.

전체 OAuth 흐름과 저장소 구조는 /concepts/oauth를 참조하세요. SecretRef 기반 인증(env/file/exec 제공자)에 대해서는 시크릿 관리를 참조하세요. models status --probe에서 사용하는 자격 증명 적격성/사유 코드 규칙은 인증 자격 증명 시맨틱스를 참조하세요.

권장 설정 (API 키, 모든 제공자)

장기 운영 게이트웨이를 실행하는 경우, 선택한 제공자의 API 키부터 시작하세요. 특히 Anthropic의 경우, API 키 인증이 안전한 방법이며 구독 setup-token 인증보다 권장됩니다.

제공자 콘솔에서 API 키를 생성합니다.
게이트웨이 호스트 (openclaw gateway를 실행하는 머신)에 키를 설정합니다.

export <PROVIDER>_API_KEY="..."
openclaw models status

게이트웨이가 systemd/launchd에서 실행되는 경우, 데몬이 읽을 수 있도록 ~/.openclaw/.env에 키를 저장하는 것이 좋습니다:

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

그런 다음 데몬을 재시작하거나 게이트웨이 프로세스를 재시작하고 다시 확인합니다:

openclaw models status
openclaw doctor

환경 변수를 직접 관리하고 싶지 않다면, 온보딩 마법사가 데몬용 API 키를 저장할 수 있습니다: openclaw onboard.

환경 상속(env.shellEnv, ~/.openclaw/.env, systemd/launchd)에 대한 자세한 내용은 도움말을 참조하세요.

Anthropic: setup-token (구독 인증)

Claude 구독을 사용하는 경우, setup-token 흐름이 지원됩니다. 게이트웨이 호스트에서 실행하세요:

claude setup-token

그런 다음 OpenClaw에 붙여넣습니다:

openclaw models auth setup-token --provider anthropic

토큰이 다른 머신에서 생성된 경우, 수동으로 붙여넣습니다:

openclaw models auth paste-token --provider anthropic

다음과 같은 Anthropic 오류가 표시되는 경우:

This credential is only authorized for use with Claude Code and cannot be used for other API requests.

…대신 Anthropic API 키를 사용하세요.

경고: Anthropic setup-token 지원은 기술적 호환성만을 위한 것입니다. Anthropic은 과거에 Claude Code 외부에서의 일부 구독 사용을 차단한 적이 있습니다. 정책 위험이 수용 가능하다고 판단한 경우에만 사용하고, Anthropic의 현재 약관을 직접 확인하세요.

수동 토큰 입력 (모든 제공자; auth-profiles.json에 기록하고 설정을 업데이트):

openclaw models auth paste-token --provider anthropic
openclaw models auth paste-token --provider openrouter

정적 자격 증명에 대한 인증 프로필 참조도 지원됩니다:

api_key 자격 증명은 keyRef: { source, provider, id }를 사용할 수 있습니다
token 자격 증명은 tokenRef: { source, provider, id }를 사용할 수 있습니다

자동화 친화적 검사 (만료/누락 시 종료 코드 1, 만료 임박 시 2):

openclaw models status --check

선택적 운영 스크립트(systemd/Termux)는 여기에 문서화되어 있습니다: /automation/auth-monitoring

claude setup-token은 대화형 TTY가 필요합니다.

모델 인증 상태 확인

openclaw models status
openclaw doctor

API 키 로테이션 동작 (게이트웨이)

일부 제공자는 API 호출이 제공자 속도 제한에 도달했을 때 대체 키로 요청을 재시도하는 기능을 지원합니다.

우선순위 순서:
- OPENCLAW_LIVE_<PROVIDER>_KEY (단일 오버라이드)
- <PROVIDER>_API_KEYS
- <PROVIDER>_API_KEY
- <PROVIDER>_API_KEY_*
Google 제공자는 추가 폴백으로 GOOGLE_API_KEY도 포함합니다.
동일한 키 목록은 사용 전에 중복이 제거됩니다.
OpenClaw는 속도 제한 오류에 대해서만 다음 키로 재시도합니다 (예: 429, rate_limit, quota, resource exhausted).
속도 제한이 아닌 오류는 대체 키로 재시도되지 않습니다.
모든 키가 실패하면, 마지막 시도의 최종 오류가 반환됩니다.

사용할 자격 증명 제어

세션별 (chat 명령어)

/model <alias-or-id>@<profileId>를 사용하여 현재 세션에 특정 제공자 자격 증명을 고정합니다 (프로필 ID 예시: anthropic:default, anthropic:work).

/model (또는 /model list)로 간단한 선택기를, /model status로 전체 보기 (후보 + 다음 인증 프로필, 그리고 설정된 경우 제공자 엔드포인트 세부 정보)를 사용하세요.

에이전트별 (CLI 오버라이드)

에이전트에 대해 명시적 인증 프로필 순서 오버라이드를 설정합니다 (해당 에이전트의 auth-profiles.json에 저장됨):

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

--agent <id>를 사용하여 특정 에이전트를 지정합니다. 생략하면 설정된 기본 에이전트를 사용합니다.

문제 해결

”No credentials found”

Anthropic 토큰 프로필이 없는 경우, 게이트웨이 호스트에서 claude setup-token을 실행한 다음 다시 확인합니다:

openclaw models status

토큰 만료 임박/만료됨

openclaw models status를 실행하여 어떤 프로필이 만료 임박인지 확인합니다. 프로필이 없는 경우, claude setup-token을 다시 실행하고 토큰을 다시 붙여넣습니다.

요구 사항

Anthropic 구독 계정 (claude setup-token용)
Claude Code CLI 설치 (claude 명령어 사용 가능)