OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

인증

OpenClaw는 모델 제공자에 대해 OAuth와 API 키를 지원합니다. 상시 실행되는 Gateway 호스트에서는 API 키가 가장 예측 가능한 옵션이며, 구독/OAuth 흐름도 제공자 계정 모델과 일치하는 경우 사용할 수 있습니다.

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

  1. 제공자 콘솔에서 API 키를 생성합니다.
  2. Gateway 호스트(openclaw gateway를 실행하는 머신)에 키를 설정합니다.
bash
export <PROVIDER>_API_KEY="..."openclaw models status
  1. Gateway가 systemd/launchd에서 실행되는 경우 데몬이 읽을 수 있도록 키를 ~/.openclaw/.env에 저장합니다.
bash
cat >> ~/.openclaw/.env <<'EOF'&lt;PROVIDER&gt;_API_KEY=...EOF
  1. Gateway 프로세스(또는 데몬)를 다시 시작한 후 다시 확인합니다.
bash
openclaw models statusopenclaw doctor

환경 변수를 직접 관리하고 싶지 않다면 openclaw onboard를 사용하여 데몬용 API 키를 저장할 수도 있습니다. 전체 환경 변수 로드 우선순위(env.shellEnv, ~/.openclaw/.env, systemd/launchd)는 환경 변수를 참조하세요.

Anthropic: Claude CLI 재사용

Anthropic 설정 토큰 인증은 계속 지원됩니다. Claude CLI 재사용(claude -p 방식의 사용)도 이 통합에서 공식적으로 허용됩니다. 호스트에서 Claude CLI 로그인을 사용할 수 있는 경우 로컬/데스크톱 사용에는 이 방법을 권장합니다. 장기간 실행되는 Gateway 호스트에서는 서버 측 결제를 명시적으로 제어할 수 있는 Anthropic API 키가 여전히 가장 예측 가능한 선택입니다.

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

bash
# Gateway 호스트에서 실행claude auth loginclaude auth status --textopenclaw models auth login --provider anthropic --method cli --set-default

이 과정은 두 단계로 이루어집니다. 먼저 호스트의 Claude Code를 Anthropic에 로그인한 다음, OpenClaw가 로컬 claude-cli 백엔드를 통해 Anthropic 모델 선택을 라우팅하고 이에 해당하는 OpenClaw 인증 프로필을 저장하도록 설정합니다.

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

수동 토큰 입력

모든 제공자에서 사용할 수 있으며 에이전트별 SQLite 인증 저장소에 기록하고 구성을 업데이트합니다.

bash
openclaw models auth paste-token --provider openrouter

OpenClaw는 각 에이전트의 openclaw-agent.sqlite에서 인증 프로필을 읽습니다. 엔드포인트 세부 정보(baseUrl, api, 모델 ID, 헤더, 시간 제한)는 인증 프로필이 아니라 openclaw.json 또는 models.json의 models.providers.<id> 아래에 있어야 합니다.

이전 설치에 auth-profiles.json, auth-state.json 또는 { "openrouter": { "apiKey": "..." } } 같은 평면 구조가 아직 남아 있다면 openclaw doctor --fix를 실행하여 SQLite로 가져오세요. doctor는 원본 JSON 파일 옆에 타임스탬프가 지정된 백업을 보관합니다.

Bedrock의 auth: "aws-sdk" 같은 외부 인증 경로는 자격 증명이 아닙니다. 이름이 지정된 Bedrock 경로의 경우 openclaw.json에서 auth.profiles.<id>.mode: "aws-sdk"를 설정하세요. 인증 프로필 저장소에 type: "aws-sdk"를 기록하면 안 됩니다. openclaw doctor --fix는 자격 증명 저장소의 레거시 AWS SDK 마커를 구성 메타데이터로 마이그레이션합니다.

SecretRef 기반 자격 증명

  • api_key 자격 증명은 keyRef: { source, provider, id }를 사용할 수 있습니다.
  • token 자격 증명은 tokenRef: { source, provider, id }를 사용할 수 있습니다.
  • OAuth 모드 프로필은 SecretRef 자격 증명을 거부합니다. auth.profiles.<id>.mode가 "oauth"이면 해당 프로필의 SecretRef 기반 keyRef/tokenRef가 거부됩니다.

모델 인증 상태 확인

bash
openclaw models statusopenclaw doctor

자동화에 적합한 검사로, 만료되었거나 누락된 경우 종료 코드 1, 곧 만료되는 경우 2를 반환합니다.

bash
openclaw models status --check

실시간 인증 검사(범위를 좁히려면 --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency 또는 --probe-max-tokens 추가):

bash
openclaw models status --probe

참고:

  • 검사 행은 인증 프로필, 환경 자격 증명 또는 models.json에서 가져올 수 있습니다.
  • auth.order.<provider>에서 저장된 프로필이 누락된 경우 검사는 해당 프로필을 시도하지 않고 excluded_by_auth_order를 보고합니다.
  • 인증이 존재하지만 OpenClaw가 해당 제공자에서 검사 가능한 모델을 확인할 수 없는 경우 검사는 status: no_model을 보고합니다.
  • 속도 제한 대기 시간은 모델 범위로 적용될 수 있습니다. 한 모델에서 대기 중인 프로필도 같은 제공자의 다른 모델에는 계속 사용될 수 있습니다.

선택적 운영 스크립트(systemd/Termux): 인증 모니터링 스크립트.

API 키 교체(Gateway)

일부 제공자는 호출이 제공자 속도 제한에 걸리면 구성된 대체 키로 요청을 다시 시도합니다.

제공자별 키 우선순위:

  1. OPENCLAW_LIVE_&lt;PROVIDER&gt;_KEY(단일 재정의, 하나의 키로 고정)
  2. &lt;PROVIDER&gt;_API_KEYS(쉼표/공백/세미콜론으로 구분된 목록)
  3. &lt;PROVIDER&gt;_API_KEY
  4. &lt;PROVIDER&gt;_API_KEY_*(이 접두사가 있는 모든 환경 변수)

Google 제공자(google, google-vertex)는 추가로 GOOGLE_API_KEY를 대체 값으로 사용합니다. 결합된 목록은 사용 전에 중복을 제거합니다.

OpenClaw는 오류 메시지가 rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted 또는 too many requests와 일치하는 경우에만 다음 키로 교체합니다. 다른 오류에는 대체 키를 사용하여 다시 시도하지 않습니다. 모든 키가 실패하면 마지막 시도에서 발생한 최종 오류가 반환됩니다.

저장된 인증을 제거해도 제공자의 키는 폐기되지 않습니다. 제공자 측에서 무효화해야 하는 경우 제공자 대시보드에서 키를 교체하거나 폐기하세요.

Gateway 실행 중 제공자 인증 제거

Gateway 제어 영역을 통해 제공자 인증을 제거하면 OpenClaw는 해당 제공자의 저장된 인증 프로필을 삭제하고, 선택된 모델 제공자가 제거된 제공자와 일치하는 활성 채팅/에이전트 실행을 중단합니다. 중단된 실행은 stopReason: "auth-revoked"와 함께 일반적인 취소/수명 주기 이벤트를 내보내므로 연결된 클라이언트는 자격 증명이 제거되어 실행이 중지되었음을 표시할 수 있습니다.

사용할 자격 증명 제어

OpenAI 및 레거시 openai-codex ID

OpenAI API 키 프로필과 ChatGPT/Codex OAuth 프로필은 모두 표준 제공자 ID openai를 사용합니다. 새 구성에는 openai:* 프로필 ID와 auth.order.openai를 사용하세요.

이전 구성, 인증 프로필 ID 또는 auth.order.openai-codex에서 openai-codex가 보이면 레거시 마이그레이션 입력으로 취급하세요. 새 openai-codex 프로필을 만들면 안 됩니다. 다음을 실행하세요.

bash
openclaw doctor --fixopenclaw models auth list --provider openai

doctor는 레거시 openai-codex:* 프로필 ID와 auth.order.openai-codex 항목을 표준 openai 경로로 다시 작성합니다. OpenAI 전용 모델/런타임 라우팅은 OpenAI를 참조하세요.

로그인 중(CLI)

bash
openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

--profile-id를 사용하면 동일한 제공자의 여러 OAuth 로그인을 하나의 에이전트 내에서 분리하여 유지할 수 있습니다.

--force는 선택한 에이전트 디렉터리에서 해당 제공자의 저장된 인증 프로필을 삭제한 다음 동일한 인증 흐름을 다시 실행합니다. 저장된 프로필이 멈췄거나 만료되었거나 잘못된 계정에 연결된 경우 사용하세요. 제공자의 자격 증명을 폐기하지는 않습니다.

bash
openclaw models auth login --provider anthropic --force

세션별(채팅 명령)

  • /model <alias-or-id>@<profileId>는 현재 세션에 특정 제공자 자격 증명을 고정합니다(프로필 ID 예: anthropic:default, anthropic:work).
  • /model(또는 /model list)은 간략한 선택기를 표시하며, /model status는 전체 보기(후보 + 다음 인증 프로필, 구성된 경우 제공자 엔드포인트 세부 정보 포함)를 표시합니다.

이미 실행 중인 채팅의 인증 순서 또는 프로필 고정을 변경한 경우 /new 또는 /reset을 전송하여 새 세션을 시작하세요. 기존 세션은 재설정할 때까지 현재 모델/프로필 선택을 유지합니다.

에이전트별(CLI 재정의)

인증 순서 재정의는 해당 에이전트의 SQLite 인증 상태에 저장됩니다.

bash
openclaw models auth order get --provider anthropicopenclaw models auth order set --provider anthropic anthropic:defaultopenclaw models auth order clear --provider anthropic

특정 에이전트를 대상으로 하려면 --agent <id>를 사용하고, 구성된 기본 에이전트를 사용하려면 생략하세요. openclaw models status --probe는 누락된 저장 프로필을 조용히 건너뛰지 않고 excluded_by_auth_order로 표시합니다.

문제 해결

"자격 증명을 찾을 수 없음"

Gateway 호스트에 Anthropic API 키를 구성하거나 Anthropic 설정 토큰 경로를 설정한 후 다시 확인하세요.

bash
openclaw models status

토큰 만료 예정/만료됨

openclaw models status를 실행하여 만료 예정인 프로필을 확인하세요. Anthropic 토큰 프로필이 누락되었거나 만료된 경우 설정 토큰을 통해 갱신하거나 Anthropic API 키로 마이그레이션하세요.

관련 항목

Was this useful?
On this page

On this page