English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Gateway

인증

OpenClaw는 모델 제공자에 대해 OAuth와 API 키를 지원합니다. 상시 실행되는 gateway 호스트의 경우 API 키가 보통 가장 예측 가능한 옵션입니다. Subscription/OAuth 흐름도 제공자 계정 모델과 맞는 경우 지원됩니다.

전체 OAuth 흐름과 저장소 레이아웃은 /concepts/oauth를 참조하세요. SecretRef 기반 인증(env/file/exec 제공자)은 Secrets Management를 참조하세요. models status --probe에서 사용하는 자격 증명 적격성/이유 코드 규칙은 Auth Credential Semantics를 참조하세요.

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

장기 실행 gateway를 운영하는 경우 선택한 제공자의 API 키로 시작하세요. 특히 Anthropic의 경우 API 키 인증이 여전히 가장 예측 가능한 서버 설정이지만, OpenClaw는 로컬 Claude CLI 로그인의 재사용도 지원합니다.

  1. 제공자 콘솔에서 API 키를 생성합니다.
  2. 이를 gateway 호스트(openclaw gateway를 실행하는 머신)에 둡니다.
export <PROVIDER>_API_KEY="..."
openclaw models status
  1. Gateway가 systemd/launchd 아래에서 실행되는 경우 데몬이 읽을 수 있도록 키를 ~/.openclaw/.env에 두는 것이 좋습니다.
cat >> ~/.openclaw/.env <<'EOF'
&lt;PROVIDER&gt;_API_KEY=...
EOF

그런 다음 데몬을 다시 시작하거나 Gateway 프로세스를 다시 시작하고 다시 확인합니다.

openclaw models status
openclaw doctor

env vars를 직접 관리하고 싶지 않다면 온보딩이 데몬 사용을 위해 API 키를 저장할 수 있습니다: openclaw onboard.

env 상속(env.shellEnv, ~/.openclaw/.env, systemd/launchd)에 대한 자세한 내용은 Help를 참조하세요.

Anthropic: Claude CLI 및 토큰 호환성

Anthropic setup-token 인증은 OpenClaw에서 지원되는 토큰 경로로 여전히 사용할 수 있습니다. 이후 Anthropic 직원은 OpenClaw 스타일 Claude CLI 사용이 다시 허용된다고 알려왔으므로, OpenClaw는 Anthropic이 새 정책을 게시하지 않는 한 이 통합에 대해 Claude CLI 재사용과 claude -p 사용을 승인된 것으로 처리합니다. 호스트에서 Claude CLI 재사용을 사용할 수 있다면, 이제 이 경로가 선호됩니다.

장기 실행 gateway 호스트의 경우 Anthropic API 키가 여전히 가장 예측 가능한 설정입니다. 같은 호스트의 기존 Claude 로그인을 재사용하려면 온보딩/구성에서 Anthropic Claude CLI 경로를 사용하세요.

Claude CLI 재사용을 위한 권장 호스트 설정:

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

이는 2단계 설정입니다.

  1. gateway 호스트에서 Claude Code 자체를 Anthropic에 로그인합니다.
  2. OpenClaw에 Anthropic 모델 선택을 로컬 claude-cli 백엔드로 전환하고 일치하는 OpenClaw 인증 프로필을 저장하라고 알립니다.

claude가 PATH에 없다면 먼저 Claude Code를 설치하거나 agents.defaults.cliBackends.claude-cli.command를 실제 바이너리 경로로 설정하세요.

수동 토큰 입력(모든 제공자; auth-profiles.json 작성 + 구성 업데이트):

openclaw models auth paste-token --provider openrouter

auth-profiles.json은 자격 증명만 저장합니다. 표준 형태는 다음과 같습니다.

{
  "version": 1,
  "profiles": {
    "openrouter:default": {
      "type": "api_key",
      "provider": "openrouter",
      "key": "OPENROUTER_API_KEY"
    }
  }
}

OpenClaw는 런타임에 표준 version + profiles 형태를 기대합니다. 이전 설치에 { "openrouter": { "apiKey": "..." } }와 같은 플랫 파일이 아직 있다면, openclaw doctor --fix를 실행하여 이를 openrouter:default API 키 프로필로 다시 작성하세요. doctor는 원본 옆에 .legacy-flat.*.bak 사본을 유지합니다. baseUrl, api, 모델 id, 헤더, 타임아웃 같은 endpoint 세부 정보는 auth-profiles.json이 아니라 openclaw.json 또는 models.json의 models.providers.<id> 아래에 속합니다.

Bedrock auth: "aws-sdk" 같은 외부 인증 경로도 자격 증명이 아닙니다. 이름 있는 Bedrock 경로를 원한다면 openclaw.json에 auth.profiles.<id>.mode: "aws-sdk"를 넣으세요. auth-profiles.json에 type: "aws-sdk"를 쓰지 마세요. openclaw doctor --fix는 레거시 AWS SDK 마커를 자격 증명 저장소에서 구성 메타데이터로 이동합니다.

정적 자격 증명에는 인증 프로필 참조도 지원됩니다.

  • api_key 자격 증명은 keyRef: { source, provider, id }를 사용할 수 있습니다
  • token 자격 증명은 tokenRef: { source, provider, id }를 사용할 수 있습니다
  • OAuth 모드 프로필은 SecretRef 자격 증명을 지원하지 않습니다. auth.profiles.<id>.mode가 "oauth"로 설정되어 있으면 해당 프로필에 대한 SecretRef 기반 keyRef/tokenRef 입력은 거부됩니다.

자동화 친화적 확인(만료/누락 시 exit 1, 곧 만료 시 2):

openclaw models status --check

실시간 인증 probes:

openclaw models status --probe

참고:

  • Probe 행은 인증 프로필, env 자격 증명 또는 models.json에서 올 수 있습니다.
  • 명시적 auth.order.<provider>가 저장된 프로필을 생략하면, probe는 해당 프로필을 시도하는 대신 excluded_by_auth_order를 보고합니다.
  • 인증은 있지만 OpenClaw가 해당 제공자에 대해 probe 가능한 모델 후보를 확인할 수 없으면 probe는 status: no_model을 보고합니다.
  • Rate-limit cooldowns는 모델 범위일 수 있습니다. 한 모델에 대해 cooling down 중인 프로필도 같은 제공자의 sibling 모델에는 여전히 사용할 수 있습니다.

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

Anthropic 참고

Anthropic claude-cli 백엔드는 다시 지원됩니다.

  • Anthropic 직원은 이 OpenClaw 통합 경로가 다시 허용된다고 알려왔습니다.
  • 따라서 OpenClaw는 Anthropic이 새 정책을 게시하지 않는 한 Anthropic 기반 실행에 대해 Claude CLI 재사용과 claude -p 사용을 승인된 것으로 처리합니다.
  • Anthropic API 키는 장기 실행 gateway 호스트와 명시적인 서버 측 billing control에 가장 예측 가능한 선택지로 남아 있습니다.

모델 인증 상태 확인

openclaw models status
openclaw doctor

API 키 순환 동작(gateway)

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

  • 우선순위:
    • OPENCLAW_LIVE_&lt;PROVIDER&gt;_KEY(단일 override)
    • &lt;PROVIDER&gt;_API_KEYS
    • &lt;PROVIDER&gt;_API_KEY
    • &lt;PROVIDER&gt;_API_KEY_*
  • Google 제공자는 추가 fallback으로 GOOGLE_API_KEY도 포함합니다.
  • 같은 키 목록은 사용 전에 중복 제거됩니다.
  • OpenClaw는 rate-limit 오류에 대해서만 다음 키로 재시도합니다(예: 429, rate_limit, quota, resource exhausted, Too many concurrent requests, ThrottlingException, concurrency limit reached 또는 workers_ai ... quota limit exceeded).
  • Non-rate-limit 오류는 대체 키로 재시도하지 않습니다.
  • 모든 키가 실패하면 마지막 시도의 최종 오류가 반환됩니다.

사용할 자격 증명 제어

세션별(채팅 명령)

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

간단한 picker에는 /model(또는 /model list)을 사용하고, 전체 보기에는 /model status를 사용하세요(후보 + 다음 인증 프로필, 구성된 경우 제공자 endpoint 세부 정보 포함).

에이전트별(CLI override)

에이전트에 명시적 인증 프로필 순서 override를 설정합니다(해당 에이전트의 auth-state.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>를 사용하고, 구성된 기본 에이전트를 사용하려면 생략하세요. 순서 문제를 디버그할 때 openclaw models status --probe는 생략된 저장 프로필을 조용히 건너뛰는 대신 excluded_by_auth_order로 표시합니다. cooldown 문제를 디버그할 때는 rate-limit cooldowns가 전체 제공자 프로필이 아니라 하나의 모델 id에 연결될 수 있음을 기억하세요.

문제 해결

"No credentials found"

Anthropic 프로필이 없으면 gateway 호스트에 Anthropic API 키를 구성하거나 Anthropic setup-token 경로를 설정한 다음 다시 확인하세요.

openclaw models status

토큰 만료 예정/만료됨

어떤 프로필이 만료 예정인지 확인하려면 openclaw models status를 실행하세요. Anthropic 토큰 프로필이 없거나 만료된 경우 setup-token을 통해 해당 설정을 새로 고치거나 Anthropic API 키로 마이그레이션하세요.

관련