OpenClaw API 키 오류 해결: 인증·429·Gateway 문제 구분하기

OpenClaw에서 No API key found, 401, 429가 나오거나 봇이 응답하지 않으면 오류를 반환한 곳과 실제로 요청을 실행한 agent부터 확인하세요. 모델 제공업체가 인증을 거절했다면 그 연결에서 선택한 키·로그인을 복구합니다. Gateway가 접속을 거절했다면 클라이언트의 Gateway 인증과 기기 권한을 확인합니다. 두 곳의 비밀값은 서로 바꿔 쓸 수 없습니다.

우선 같은 요청의 재전송을 멈추고 오류 원문, 발생 시각, agent, 선택 모델, 실제 시도한 모델을 남깁니다. 이미 파일을 수정하거나 메시지를 보냈다면 결과를 확인하고, 아직 끝나지 않은 단계부터 이어가세요. 시간 초과는 “아무 일도 일어나지 않았다”는 증거가 아닙니다.

아래 안내는 2026년 10월 7일 확인한 OpenClaw 공식 문서에 근거합니다. 예제의 오류 분류와 시간 계산은 합성 데이터로 오프라인 확인했으며, 실제 계정 인증이나 유료 모델 호출로 복구를 시험한 결과는 아닙니다.

오류 원문에 따라 첫 조치를 선택하세요

HTTP 상태 코드만으로 키가 잘못됐다고 판단하면 엉뚱한 인증을 바꾸기 쉽습니다. 오류 본문, 응답을 보낸 서버, 직전 시도 순서를 함께 확인합니다.

Gateway의 /healthz가 정상이라고 모델 인증까지 정상인 것은 아닙니다. 모델 목록도 캐시나 명시적인 설정으로 보일 수 있으므로, 목록에 모델이 있다는 사실과 실제 모델 응답 성공을 구분합니다. Gateway 상태 확인, 모델 상태의 의미

API 키가 있는데도 없다고 나오면 실제 실행 환경을 확인하세요

키를 저장한 컴퓨터와 모델을 호출하는 컴퓨터가 같은지부터 확인합니다. 원격 Gateway나 Docker 컨테이너가 모델을 호출한다면 노트북 터미널의 키만 바꿔서는 그 프로세스가 바뀌지 않습니다.

실패한 agent ID를 아는 경우 다음은 해당 Gateway 호스트에서 사용하는 문서상 진단 명령입니다. AGENT_ID는 실제 설정된 ID로 바꾸세요. 이 글의 예제를 작성하면서 아래 명령을 실행하지는 않았습니다.

openclaw models status --agent AGENT_ID
openclaw models status --agent AGENT_ID --json --check
openclaw models auth list --agent AGENT_ID

models status는 설정된 기본 모델과 대체 경로를 봅니다. 대화에서 모델을 따로 선택했다면 그 대화의 /model status를 확인하고, /status에서 선택 모델과 실제 대체 실행 모델을 구분합니다. ACP 등 외부 실행 방식이 모델과 인증을 관리한다면 그 실행 방식의 상태도 따로 확인해야 합니다.

JSON에서는 auth.providers의 인증 공급원, auth.oauth의 저장된 프로필 상태, auth.modelRouteIssues의 경로 문제, auth.runtimeAuthRoutes의 실행 가능 상태를 함께 읽습니다. 저장된 프로필이 보이더라도 실행 프로그램이 없거나 비밀값 공급원이 실패하면 요청을 보낼 수 없습니다. indeterminate는 이 확인에서 결론을 내리지 못했다는 뜻이지 “키가 틀렸다”는 뜻이 아닙니다.

--check 종료 코드 0은 인식된 문제가 없다는 뜻이며 모델 호출 성공이 아닙니다. 1은 누락·만료·호환성·실행 불가·판단 불가 문제를 포함하고, 2는 1에 해당하는 문제 없이 만료가 임박한 경우입니다. 명령 실패 때는 상태 객체 대신 오류 객체가 반환될 수 있으므로 종료 코드와 내용을 함께 확인합니다. 이 명령도 대상 비밀값을 해석하거나 제공업체 소유 상태를 확인할 수 있어 완전히 독립된 오프라인 검사로 취급하면 안 됩니다. models CLI 공식 설명

다른 agent는 되는데 하나만 실패하는 경우

현재 인증 저장소는 공유 SQLite와 agent별 SQLite를 사용합니다. 공유 저장소는 ~/.openclaw/state/openclaw.sqlite, agent별 저장소는 ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite입니다. 로컬 프로필이 없으면 공유 인증을 읽을 수 있으므로 새 agent마다 비밀값을 복사할 필요는 없습니다. 같은 프로필 ID의 로컬 덮어쓰기, agent별 인증 순서, 다른 상태 디렉터리 때문에 선택 결과가 달라질 수 있습니다. 인증 저장과 공유 방식

먼저 실패한 agent의 프로필과 순서를 정상 agent와 비교합니다. SQLite를 직접 고치거나 과거의 auth-profiles.json에 키를 덧붙이지 마세요. 과거 파일은 검증된 마이그레이션 대상이지 현재 인증 저장소와 같은 역할이 아닙니다. 오래된 JSON으로 사용 가능한 새 저장소를 덮어쓰는 복구도 피해야 합니다.

확인 결과에 맞춰 인증을 복구합니다

실제로 필요한 API 키가 없다면 해당 제공업체와 agent를 지정해 보호된 대화형 입력을 사용합니다. 아래는 Anthropic API 키 방식의 문서 예시이며 다른 제공업체에는 그 제공업체 ID를 사용합니다.

openclaw models auth paste-api-key --provider anthropic --agent AGENT_ID

이 동작은 활성 프로필을 갱신하거나 새 프로필을 만들 수 있습니다. 기존 연결을 바꿀지, --profile-id로 별도 프로필을 지정할지 먼저 정합니다. paste-token은 토큰 자료를 입력하는 명령이므로 API 키 입력과 혼동하지 마세요. OpenAI API 키와 ChatGPT/Codex 로그인은 현재 openai 제공업체 아래의 서로 다른 인증 방식입니다. 인증 입력 명령과 적용 범위

네이티브 Claude CLI 방식이라면 Gateway와 같은 호스트·사용자·PATH·CLAUDE_CONFIG_DIR에서 CLI 로그인과 실행 가능 여부를 확인합니다. CLI 로그인을 준비하는 일과 OpenClaw에서 CLI 실행 방식을 선택하는 일은 별개입니다. OpenClaw는 Claude의 네이티브 로그인 토큰을 읽거나 저장·갱신·전달하지 않습니다. 지원되는 관리형 setup-token 역시 별도 방식입니다. 임의로 추출한 OAuth 토큰을 복사하거나 모델 이름만 보고 구독 청구를 단정하지 마세요. 제공업체 인증 방식

더 구체적인 invalid bearer token과 인증 헤더 누락 진단은 OpenClaw 401 인증 오류 안내에서 이어갈 수 있습니다.

Gateway·기기·채널 인증은 모델 API 키와 따로 고칩니다

Gateway HTTP OpenResponses 요청에서는 Gateway에 접속하는 인증을 사용합니다. 공유 토큰·비밀번호 모드의 Authorization: Bearer에 넣는 값은 모델 제공업체 키가 아닙니다. trusted-proxy 모드에는 별도의 신원 규칙이 적용됩니다. 공유 비밀값 HTTP 모드는 전체 운영자 권한을 부여하므로 단순한 읽기 전용 토큰으로 생각해서도 안 됩니다. 한국어 OpenResponses 인증 설명

OpenResponses HTTP 엔드포인트는 기본적으로 꺼져 있습니다. 비활성화된 엔드포인트의 404를 모델 키 오류로 고치거나, 모델 목록의 200을 상위 제공업체 인증 성공으로 해석하지 않습니다. 엔드포인트 활성화는 같은 포트에 호환 API도 노출하므로 401만 없애려고 인증을 끄거나 포트를 넓게 공개하는 방식은 적절하지 않습니다.

공유 비밀값만으로 Control UI의 기기 신원을 대신할 수는 없습니다. WebSocket 1008도 정책 위반을 뜻하는 범위 안에서 세부 원인을 읽어야 하며 모델 API 키 불량의 고유 코드가 아닙니다. 기기 승인과 권한 복구는 해당 소유자가 수행합니다. 접속 오류별 공식 안내

Gateway OpenResponses의 401은 접속 인증, 403은 운영자 권한, 인증 실패 횟수 제한의 429는 Gateway 입구를 확인합니다. 이 429는 모델 제공업체의 분당 호출 제한과 다릅니다. Retry-After를 지키고 접속 인증을 고쳐야 하며 IP나 Origin을 바꿔 제한을 피하지 않습니다. SSE 연결 뒤 response.failed가 올 수 있으므로 연결 성공만으로 답변 성공을 판단하지 마세요. 요구된 클라이언트 도구 결과가 반환되지 않아 발생한 502 역시 모델 제공업체 전체 장애로 단정할 수 없습니다. HTTP 오류와 스트리밍 설명

Telegram·Discord 등 채널 로그인이나 전송 단계의 실패라면 해당 봇·채널 인증과 메시지 결과를 확인합니다. 모델 답변이 만들어졌지만 전송만 실패했다면 답변을 다시 생성하기보다 전송된 기록을 먼저 확인해야 합니다.

429와 쿨다운에서는 대기 이유부터 읽습니다

제공업체가 일시적인 속도 제한을 반환하면 추가 작업과 동시 요청을 줄이고 지정한 최소 시간 이상 기다립니다. Retry-After는 음이 아닌 정수 초 또는 HTTP 날짜를 사용할 수 있습니다. OpenClaw 문서에 설명된 RetryAfterMs는 밀리초입니다. 날짜 계산에는 기준 시각이 필요하고, 확인할 수 없는 값은 임의의 짧은 대기로 바꾸지 않습니다. HTTP Retry-After 정의

현재 내장 모델 재시도 정책은 모델 429에서 첫 호출을 포함해 최대 10회 시도합니다. 다른 일시 오류에는 최대 8회 재시도와 90초 연속 장애 창이 적용됩니다. 완전한 모델 응답이 창을 해제하며 부분 출력이나 도구 활동만으로는 해제되지 않습니다. 일반 backoff 상한이 30초여도 제공업체의 더 긴 최소 대기 시간이 우선하고, 취소·실행 기한은 복구를 끝냅니다. 내장 세션의 retry.provider.maxRetries를 일반 openclaw.json 설정으로 넣어서는 안 됩니다. 현재 재시도 정책

all in cooldown이면 저장된 이유와 해제 시각을 확인합니다. 보통의 30초·1분·5분 대기와 청구·영구 인증 실패에 대한 초기 10분 차단은 OpenClaw 내부 상태이며 제공업체의 보편적인 초기화 시간은 아닙니다. 재시작하거나 충전했다고 저장된 차단이 바로 해제되는 것도 아닙니다. 모델별 쿨다운과 프로필 전체의 청구 차단은 적용 범위가 다릅니다. 프로필 선택과 쿨다운

명시적인 사용량 소진이면 해당 창이 회복될 때까지 보류하거나 이미 승인된 적합한 대체 연결을 선택합니다. 인증·청구·거부를 일시 오류로 묶어 무한 재시도하지 않습니다. 청구 문제가 401·403으로, 일시적인 사용 창 문제가 402로 나타날 수 있으므로 본문과 제공업체의 분류를 함께 봅니다.

대체 경로는 작업에 필요한 도구·데이터 처리·비용 조건을 충족해야 합니다. 명시적으로 선택한 대화 모델은 엄격하게 유지될 수 있고, 대체 모델이 한 턴에 실행됐다고 다음 턴의 선택이 영구 변경되는 것은 아닙니다. 키 회전과 프로필·모델 대체도 서로 다릅니다. 같은 계정의 여러 키가 공유하는 한도는 키 수만큼 늘어나지 않습니다. 상세 대기 판단은 OpenClaw 429와 쿨다운 복구 안내를 참고하세요.

400·통신·Docker·설정 오류는 해당 단계에서 복구하세요

400이면 오류 본문과 입력 크기를 나눠 봅니다

Gateway가 요청 본문 오류를 반환했다면 거절된 필드나 형식을 먼저 고칩니다. context length exceeded라면 완료한 작업을 보존하고, 실패한 실제 모델과 입력 크기를 확인합니다. 필요한 내용을 남겨 압축하거나 큰 도구 출력과 요청을 나눕니다. 로컬 모델에서는 표시된 최대치보다 현재 인스턴스에 로드된 컨텍스트 창이 중요합니다. 키를 바꿔도 같은 입력 초과는 남습니다. 컨텍스트 초과·압축 실패 후 이어가기

TLS와 연결 오류면 인증 요청이 도달했는지 확인합니다

인증서 체인 오류나 연결 거절은 제공업체가 키를 평가하기 전에 발생할 수 있습니다. 실패한 프로세스의 실제 주소, DNS·프록시 경로, 인증서 신뢰 설정을 확인하고 관리자가 승인한 올바른 인증서 체인을 사용합니다. NODE_TLS_REJECT_UNAUTHORIZED=0으로 검증을 끄는 방식은 API 키 해결책이 아닙니다.

Node의 NODE_EXTRA_CA_CERTS는 프로세스 시작 때 신뢰할 PEM 인증서를 추가합니다. 실행 중 process.env만 바꿔도 다시 읽히지 않으며, TLS 클라이언트가 명시적인 ca를 사용하면 기본·추가 루트가 사용되지 않습니다. setuid나 파일 capabilities 조건에도 제약이 있습니다. 이 설명은 Node 문서의 동작 범위이며 설치된 OpenClaw·Node 버전 확인 결과는 아닙니다. Node 인증서 옵션

Docker에서만 실패하면 컨테이너의 환경을 확인합니다

현재 공식 환경 규칙은 이미 프로세스에 있는 값을 일반적으로 덮어쓰지 않습니다. 작업 폴더 .env도 제공업체 인증과 보호된 제어값을 넣는 일반 공급원으로 사용할 수 없습니다. 전역 상태 디렉터리 .env, 설정의 보충 환경값, 서비스가 관리하는 값은 각 우선순위를 확인해야 합니다. 필요한 변수의 존재와 공급원만 확인하고 원문 키나 전체 환경 출력을 지원 문의에 붙이지 마세요. 환경 변수 규칙

Docker Compose의 환경값을 바꿨다면 단순 restart는 새 환경을 적용하지 않습니다. 현재 공식 절차에 맞게 Gateway 컨테이너를 다시 생성해야 합니다. 진행 중인 작업과 보존 볼륨을 확인한 유지보수 시점에 수행하고, 상태 볼륨을 삭제하는 방식으로 키 문제를 해결하지 않습니다. Docker 환경 변경

SecretRef와 설정 오류면 공급원·구조를 먼저 고칩니다

활성 SecretRef는 지원 경로에서 일반 텍스트보다 우선하며, SQLite 인증 프로필이 설정의 참조를 가릴 수도 있습니다. 명시한 참조의 공급원 실패는 잘못된 API 키와 다릅니다. 사용할 수 없게 설정된 제공업체를 선택했을 때 다른 환경값이나 저장 프로필로 몰래 우회하지 않으므로, 그 공급원을 복구하고 승인된 반영 절차를 따릅니다. 읽기 전용 상태가 준비된 스냅샷을 보여 주더라도 실제 전송의 인증 조건은 여전히 엄격할 수 있습니다. 비밀값 운영과 활성화

설정 문제는 openclaw config file로 활성 파일을 확인하고 해당 버전의 스키마·config validate 결과로 구조를 좁힙니다. 검증은 SecretRef 호환성과 실행 경로 신뢰 조건 등을 확인하지만 공급원이 반환할 비밀값이나 제공업체의 인증 수락을 증명하지 않습니다. JSON 문법 통과도 현재 설치된 스키마 통과와 다릅니다. Doctor 수리나 마이그레이션은 구체적인 발견 사항과 백업을 근거로 진행하며 모든 401의 첫 조치로 강제 설치·프로필 삭제를 사용하지 않습니다. 플러그인 실행 불가, 읽기 전용 저장소, 응답하지 않도록 설정된 메시지 정책도 별도 원인입니다. config 진단과 검증 범위

새 제공업체나 로컬 서버를 연결하는 작업이 필요하다면 OpenClaw 모델 설정 안내에서 연결 방식과 실제 동작 확인을 진행할 수 있습니다.

운영 복구는 남은 일과 재시도 예산을 정한 뒤 진행합니다

내장 실행이 재시도하는 동안 애플리케이션이 전체 턴을 다시 호출하면 시도 횟수가 곱해질 수 있습니다. 먼저 현재 실행이 끝났는지 확인하고, 오류를 반환한 시도와 완료한 도구 결과를 남깁니다. 허용된 복구에는 횟수·전체 기한·최소 대기·중복 실행 가능 여부가 모두 필요합니다.

예를 들어 파일 수정은 완료됐고 모델의 다음 응답만 실패했다면 파일 쓰기를 다시 수행하지 않습니다. 메시지 전송 후 응답이 끊겼다면 발송 여부를 확인할 때까지 전송을 보류합니다. 같은 요청 ID를 붙였다고 제공업체가 중복 방지를 지원하는 것은 아니며 POST는 자동으로 멱등하지 않습니다. HTTP 재시도와 멱등성

다음은 전송 기능이 없는 오프라인 복구 판단 예제입니다. Python 3.10 이상에서 파일 하나로 실행할 수 있으며 OpenClaw 설정이나 공식 재시도 구현을 대체하지 않습니다. 입력 kind는 오류 코드에서 자동 추측하지 않고 응답을 보낸 곳과 오류 본문을 확인해 붙이는 예제용 분류입니다. replay_safe는 중복 실행이 안전하다고 확인된 경우에만 참으로 두고, backup_allowed는 작업·모델 선택·권한·비용 조건을 충족하는 승인된 대체 경로가 있을 때만 참으로 둡니다.

from dataclasses import dataclass, replace
from datetime import datetime, timezone
from email.utils import parsedate_to_datetime
from math import isfinite

@dataclass(frozen=True)
class Failure:
    kind: str
    replay_safe: bool = False
    outcome_unknown: bool = False
    retry_after: str | None = None
    retry_after_ms: int | None = None
    backup_allowed: bool = False

def minimum_wait(f: Failure, now: datetime) -> float | None:
    values = []
    if f.retry_after_ms is not None:
        if type(f.retry_after_ms) is not int or f.retry_after_ms < 0:
            return None
        values.append(f.retry_after_ms / 1000)
    if f.retry_after is not None:
        raw = f.retry_after.strip()
        if raw.isascii() and raw.isdigit():
            values.append(int(raw))
        else:
            try:
                date = parsedate_to_datetime(raw)
                if date.tzinfo is None:
                    return None
                values.append(max(0.0, (date - now).total_seconds()))
            except (ValueError, TypeError, OverflowError):
                return None
    return max(values, default=0.0)

def decide(f: Failure, *, attempts: int, max_attempts: int,
           remaining_s: float, now: datetime) -> tuple[str, float]:
    if (attempts < 1 or max_attempts < 1 or
            not isfinite(remaining_s) or remaining_s <= 0):
        return ("STOP_BUDGET", 0.0)
    if f.outcome_unknown:
        return ("VERIFY_OUTCOME", 0.0)
    repairs = {
        "provider_auth": "FIX_PROVIDER_AUTH",
        "gateway_auth": "FIX_GATEWAY_AUTH",
        "gateway_auth_limit": "FIX_GATEWAY_AND_WAIT",
        "context": "SAVE_AND_REDUCE_INPUT",
        "config": "FIX_CONFIG",
        "tls": "FIX_TRUST_OR_TRANSPORT",
        "refusal": "STOP_REFUSAL",
        "cancelled": "STOP_CANCELLED",
    }
    if f.kind in repairs:
        return (repairs[f.kind], 0.0)
    if f.kind not in {"provider_rate", "transient", "usage_exhausted"}:
        return ("INSPECT_ERROR", 0.0)
    if not f.replay_safe:
        return ("VERIFY_REPLAY_SAFETY", 0.0)
    if attempts >= max_attempts:
        return ("STOP_ATTEMPTS", 0.0)
    if f.kind == "usage_exhausted":
        return ("APPROVED_BACKUP" if f.backup_allowed else "DEFER_USAGE", 0.0)
    floor = minimum_wait(f, now)
    if floor is None:
        return ("CHECK_WAIT_HEADER", 0.0)
    # 고정된 작은 여유값은 오프라인 예제용이며 실제 jitter 정책이 아닙니다.
    delay = max(floor, min(30.0, 2.0 ** min(attempts - 1, 5)) + 0.25)
    # 다음 응답을 확인할 여유 1초도 예제의 보수적인 가정입니다.
    if delay + 1.0 >= remaining_s:
        return ("APPROVED_BACKUP" if f.backup_allowed else "DEFER_WAIT", 0.0)
    return ("WAIT_THEN_RECHECK", delay)

if __name__ == "__main__":
    clock = datetime(2026, 10, 7, 0, 0, 0, tzinfo=timezone.utc)
    base = Failure("provider_rate", replay_safe=True, retry_after="120")
    args = dict(attempts=1, max_attempts=3, remaining_s=20, now=clock)
    assert decide(base, **args) == ("DEFER_WAIT", 0.0)
    assert decide(replace(base, backup_allowed=True), **args)[0] == "APPROVED_BACKUP"
    assert decide(replace(base, outcome_unknown=True), **args)[0] == "VERIFY_OUTCOME"
    assert decide(replace(base, replay_safe=False), **args)[0] == "VERIFY_REPLAY_SAFETY"
    assert decide(replace(base, kind="provider_auth"), **args)[0] == "FIX_PROVIDER_AUTH"
    assert decide(replace(base, kind="gateway_auth_limit"), **args)[0] == "FIX_GATEWAY_AND_WAIT"
    assert decide(base, **{**args, "attempts": 3}) == ("STOP_ATTEMPTS", 0.0)
    date_case = replace(base, retry_after="Wed, 07 Oct 2026 00:00:05 GMT")
    assert decide(date_case, **args) == ("WAIT_THEN_RECHECK", 5.0)
    ms_case = replace(base, retry_after="1", retry_after_ms=2500)
    assert decide(ms_case, **args) == ("WAIT_THEN_RECHECK", 2.5)
    assert decide(replace(base, retry_after="1.5"), **args)[0] == "CHECK_WAIT_HEADER"
    assert decide(replace(base, kind="usage_exhausted"), **args)[0] == "DEFER_USAGE"
    assert decide(base, **{**args, "remaining_s": 0})[0] == "STOP_BUDGET"
    print("offline recovery decisions: OK")

이 예제는 긴 대기 시간을 짧게 잘라 재전송하지 않고, 마지막 시도 뒤에는 대기하지 않습니다. WAIT_THEN_RECHECK도 즉시 전송하라는 명령이 아닙니다. 대기 후 취소 여부·남은 기한·현재 쿨다운을 다시 확인하고, 실제 실행기의 제한된 재시도 정책 안에서 다음 시도를 결정해야 합니다. FIX_GATEWAY_AND_WAIT 역시 인증을 고친 뒤 Gateway의 대기 안내를 따르는 분기입니다.

같은 사건의 진단 메모는 다음처럼 비밀값 없이 남길 수 있습니다. 아래 JSON은 기록 예시이며 openclaw.json에 넣는 설정이 아닙니다. 모델과 프로필은 가상의 식별자입니다.

{
  "agent": "report-worker",
  "selectedModel": "example/model-a",
  "attemptedModel": "example/model-a",
  "issuer": "provider",
  "kind": "provider_rate",
  "retryAfterSeconds": 120,
  "remainingSeconds": 20,
  "outcome": "known_failure_before_tool_execution",
  "completed": ["local draft saved"],
  "pending": ["generate final response"],
  "decision": "defer; do not repeat completed file write"
}

20초만 남았는데 최소 120초를 기다려야 하므로 이번 실행에서는 보류하는 예입니다. JSON 문법과 예제 계산을 확인해도 실제 키, 모델 호출, 청구와 파일 저장 성공은 별도로 확인해야 합니다.

고친 뒤에는 실패했던 같은 연결에서 성공을 확인하세요

수정한 인증이 적용됐는지 확인하려면 같은 Gateway·사용자·agent·대화의 모델 선택·실행 방식에서 짧고 부작용 없는 요청을 보냅니다. 실제 시도한 모델과 프로필이 의도한 것인지, 답변이 끝까지 완료됐는지 확인합니다. 기본 모델의 상태만 정상이거나 다른 제공업체의 모델 목록이 조회되는 것으로 기존 실패를 해결했다고 판단하지 않습니다.

Gateway 접속 복구의 성공은 요청한 역할·권한으로 연결되는 것입니다. 모델 복구는 그 연결에서 모델 응답이 완료되는 것까지, 도구·채널 복구는 해당 작업의 결과가 실제로 확인되는 것까지 봅니다. 권한이 좁은 RPC 확인이나 WebSocket 인증 handshake가 전체 관리·쓰기 권한을 증명하는 것도 아닙니다.

models status --probe는 실제 모델 요청이므로 토큰 비용이나 제한을 발생시킬 수 있습니다. 공식 문서는 공유 상태 디렉터리의 독점 사용과 적절한 유지보수 시점의 Gateway 정지를 요구합니다. 시간 초과나 중단 뒤에도 이미 수락된 작업과 정리가 끝났는지 확인해야 합니다. 제공업체·프로필·시간·동시성·토큰 범위를 정하고 명시적으로 허용된 경우에만 사용하세요. 기본값이 전체 청구 상한을 보장하지는 않습니다. probe의 조건과 범위

자주 묻는 질문

새 API 키를 만들면 모든 401과 429가 해결되나요?

아닙니다. Gateway 토큰·기기 권한·채널 인증은 모델 키와 다르고, 공유 사용량 제한은 키를 늘려도 그대로일 수 있습니다. 실패한 서버와 선택된 인증 공급원을 먼저 확인하세요. 인증 구분, 실패 복구와 한도

키를 입력했는데 모델 목록이 보이지 않으면 키가 잘못된 건가요?

그렇게 단정할 수 없습니다. 사용자 지정 baseUrl에서는 암시적인 카탈로그가 제공되지 않을 수 있으며, 명시적으로 설정한 모델은 별도로 남을 수 있습니다. 목록의 존재·부재보다 실제 연결의 모델 ID와 인증·실행 상태를 확인하고 같은 경로의 짧은 응답으로 판단합니다. 모델 목록과 상태 설명

설정 파일을 바꿨는데 왜 서비스만 계속 실패하나요?

서비스가 다른 사용자·활성 파일·상태 디렉터리·환경값을 사용할 수 있습니다. 기존 프로세스 환경과 활성 SecretRef의 우선순위도 확인하세요. Docker 환경 변경은 단순 재시작으로 반영되지 않습니다. 실제 실행 프로세스의 공급원을 맞춘 뒤 해당 환경의 승인된 반영 절차를 따릅니다. 환경 변수, Docker 환경 변경

타임아웃 뒤 같은 작업을 보내도 되나요?

먼저 기존 결과를 확인해야 합니다. 응답을 받지 못해도 파일 변경·전송·청구가 이미 발생했을 수 있습니다. 결과가 불명확하면 재전송을 보류하고 완료한 일과 남은 일을 나눕니다. 반복이 안전하다고 확인된 단계만 제한된 예산 안에서 재개하세요. HTTP의 안전한 재시도 조건