OpenClaw 401 인증 오류 해결: invalid bearer token과 인증 헤더 누락 구분하기

OpenClaw에서 401 인증 오류가 나면 어떤 서버가 어떤 인증을 거절했는지 먼저 확인하세요. 대시보드가 연결되지 않으면서 AUTH_TOKEN_MISSING이 나오는 경우는 Gateway 접속 문제이고, 대화 중 provider returned HTTP 401이 나오는 경우는 모델 제공업체 또는 선택한 실행 방식의 인증 문제입니다. Gateway 토큰을 바꿔도 모델 제공업체의 API 키는 갱신되지 않습니다.

invalid bearer token이면 현재 선택된 토큰이나 로그인을 확인하고, missing authentication header이면 해당 요청이 인증 정보를 읽어 전달하는 과정을 확인합니다. 한 agent만 실패한다면 그 agent의 모델, 로컬 프로필, 인증 우선순위를 점검하세요. 현재 OpenClaw는 공유 인증 정보를 읽을 수 있으므로 새 agent마다 별도 키를 복사해야 한다는 설명은 맞지 않습니다.

아래 명령과 저장 방식은 2026년 10월 4일 확인한 공식 문서를 기준으로 합니다. 실제 사용자 계정으로 인증하거나 유료 모델 요청을 실행한 결과는 아닙니다.

오류가 발생한 위치부터 확인하세요

먼저 오류 원문, 발생 시각, OpenClaw 버전, 실패한 agent와 모델 이름을 남깁니다. 키 값과 토큰은 기록하거나 공개하지 마세요. Gateway가 실행되는 컴퓨터에서 다음 상태를 확인합니다.

openclaw --version
openclaw gateway status
openclaw doctor

Authentication failed (provider returned HTTP 401). Your provider token may have expired라는 안내가 떠도 만료가 확정된 것은 아닙니다. 현재 선택된 계정, 폐기된 키, 다른 인증 정보의 우선 선택 등도 확인해야 합니다. 단순 재시도로 같은 오류가 반복되면 실패한 대상을 확인한 뒤 해당 인증만 수정합니다.

대시보드가 연결되지 않으면 Gateway 토큰을 확인하세요

Gateway 토큰은 OpenClaw 클라이언트가 Gateway에 접속할 때 쓰는 비밀값입니다. Anthropic이나 OpenRouter의 모델 API 키와는 용도가 다릅니다.

현재 공식 접속 오류 안내는 실패한 connect 응답의 error.details.code에 따라 조치를 나눕니다.

• AUTH_TOKEN_MISSING: 클라이언트가 필요한 공유 토큰을 보내지 않았습니다. Gateway 호스트의 대화형 터미널에서 openclaw gateway auth-token --show를 실행하고, 표시된 값을 접속하려는 클라이언트에 입력합니다. 이 출력은 개인 터미널 안에서만 다루세요.
• AUTH_TOKEN_MISMATCH: 공유 토큰이 일치하지 않습니다. 연결한 Gateway 주소가 맞는지와 클라이언트의 토큰 설정을 확인합니다. canRetryWithDeviceToken=true가 있으면 신뢰할 수 있는 기기 토큰으로 한 번 재시도할 수 있습니다. 계속 실패하면 공식 안내의 토큰 불일치 복구 절차를 따릅니다.
• AUTH_DEVICE_TOKEN_MISMATCH: 저장된 기기 토큰이 오래되었거나 폐기되었습니다. 기기 토큰을 다시 승인하거나 교체해야 합니다.
• AUTH_SCOPE_MISMATCH: 기기 토큰 자체는 인식되지만 요청한 역할·권한이 승인 범위를 벗어납니다. 필요한 권한을 검토하고 다시 페어링하거나 승인합니다. 공유 토큰 교체로 해결할 문제가 아닙니다.
• PAIRING_REQUIRED: 기기 승인이 필요합니다. openclaw devices list에서 요청을 확인한 뒤, 요청한 접근 권한이 맞을 때 openclaw devices approve <requestId>를 실행합니다. <requestId>는 실제 대기 중인 요청 ID로 바꿉니다.

인증을 끄는 것을 401 해결책으로 삼지 마세요. 성공 판단은 올바른 Gateway에 클라이언트가 연결되고 해당 접속 오류가 사라지는 것입니다. 이것만으로 모델 API 인증까지 정상임을 증명하지는 않습니다.

모델 제공업체가 401을 반환하면 선택된 agent와 대화를 확인하세요

모델 호출 문제라면 전체 설정을 다시 만들기 전에 실패한 agent를 지정해 확인합니다. 아래 <agentId>는 실제 설정된 agent ID로 바꾸세요.

openclaw models status --agent <agentId>
openclaw models auth list --agent <agentId>
openclaw models status --agent <agentId> --json --check

models status는 그 agent에 설정된 기본 모델, 대체 모델, 인증 및 실행 환경을 보여 줍니다. 현재 대화에서 따로 선택한 모델이나 계정은 확인하지 않습니다. 실패한 대화 안에서는 /model status를 실행해 실제 선택을 확인해야 합니다. 공식 models CLI 설명에 따르면 --check의 종료 코드 0도 모델 요청 성공을 보장하지 않습니다.

확인 결과는 다음처럼 읽습니다.

API 키를 셸에서 설정했는데 서비스만 실패한다면 실행 사용자와 환경도 확인하세요. macOS의 launchd나 Linux의 systemd로 실행한 Gateway는 터미널의 환경 변수를 그대로 받지 않을 수 있습니다. 공식 인증 문서는 Gateway 호스트에 키를 구성하고, 데몬에서는 ~/.openclaw/.env를 사용하는 방법을 안내합니다. 원격 서버가 모델을 호출한다면 노트북에만 키를 저장해서는 서버 설정이 바뀌지 않습니다.

invalid bearer token: API 인증과 Claude CLI 로그인을 나눠 복구하세요

invalid bearer token은 응답을 보낸 서버가 Bearer 인증을 받아들이지 못했다는 단서입니다. 이 문구 하나로 Claude 구독, setup-token, API 키 중 어느 방식인지 단정할 수는 없습니다. 먼저 /model status와 agent 상태에서 제공업체, 실행 방식, 선택된 계정을 확인합니다.

API 키를 사용하는 경우

선택된 제공업체의 키가 맞는지, 폐기·교체된 키가 남아 있지 않은지, 그 키가 현재 접속 주소에서 사용할 수 있는지 확인합니다. 중계 서비스를 선택했다면 그 서비스의 키와 주소가 한 쌍이어야 합니다. Gateway 토큰을 모델 API 키 입력란에 넣으면 안 됩니다.

새 키를 입력할 필요가 있다면 현재 CLI의 대화형 입력을 사용할 수 있습니다. 아래는 Anthropic API 키를 사용하는 해당 agent를 갱신하는 문서 예시입니다.

openclaw models auth paste-api-key --provider anthropic --agent <agentId>
openclaw models status --agent <agentId>

명령이 요청하는 보호된 입력에 키를 넣습니다. 다른 제공업체라면 anthropic을 실제 제공업체 ID로 바꾸며, 현재 연결을 덮어쓸지 별도 프로필을 만들지 먼저 정하세요. paste-api-key는 저장된 활성 키를 갱신할 수 있고 --profile-id로 특정 프로필을 지정할 수 있습니다. 명령의 저장·적용 범위를 확인하고, Gateway 반영 실패가 보고되면 해당 복구 안내에 따라 재시작합니다.

Claude CLI로 실행하는 경우

오류에 Please run /login · API Error: 401 Invalid bearer token이 함께 보인다면 Claude CLI가 반환한 메시지인지 확인하세요. Claude CLI 방식은 Gateway 호스트에 설치된 Claude Code 실행 파일을 사용합니다. Gateway와 같은 컴퓨터, 같은 운영체제 사용자, 같은 환경에서 다음 순서로 확인합니다.

claude auth status --text
claude auth login
openclaw gateway restart

먼저 상태를 보고 로그인이 필요할 때 claude auth login을 실행합니다. CLAUDE_CONFIG_DIR를 따로 설정했다면 서비스가 사용하는 로그인 디렉터리도 맞아야 합니다. CLI 실행 파일을 서비스의 PATH에서 찾을 수 있는지도 확인하세요.

현재 Anthropic 안내에 따르면 네이티브 Claude CLI 로그인과 토큰 갱신은 Claude Code가 관리합니다. OpenClaw는 그 네이티브 로그인 토큰을 읽거나 저장·갱신하지 않습니다. Claude의 OAuth 토큰을 OpenClaw 데이터베이스로 복사하는 방식으로 고치지 마세요.

OpenClaw에 저장한 setup-token을 사용하는 경우

setup-token은 별도 인증 방식입니다. 공식 OAuth 문서에는 지원 경로로 남아 있으므로 모든 토큰 인증이 제거되었다고 볼 수는 없습니다. 기존 토큰이 만료되거나 폐기되었다면 해당 방식으로 다시 인증할 수 있습니다.

openclaw models auth login --provider anthropic --method setup-token --agent <agentId>

이 절차는 대화형 터미널이 필요합니다. 다만 현재 Anthropic 문서는 갑자기 무효화된 토큰과 신규 설정에 대해 API 키 사용을 권합니다. 네이티브 CLI 로그인, OpenClaw에 저장한 setup-token, API 키를 같은 것으로 취급하지 마세요. 특히 --force는 기존 프로필을 먼저 삭제하므로 원인을 확인하기 전 일괄 재인증에 붙이지 않는 편이 좋습니다.

한 agent만 실패한다면 공유 인증을 덮어쓰는 로컬 프로필을 확인하세요

현재 기본 저장 위치는 다음과 같습니다. OPENCLAW_STATE_DIR를 설정했다면 실제 경로는 그 상태 디렉터리를 따릅니다.

공식 저장 방식은 공유 저장소를 필요할 때 읽고, 같은 ID의 agent 로컬 프로필이 있으면 로컬 값을 우선 사용하는 구조입니다. 로컬 프로필이 없으면 공유 인증 정보를 읽으며, 공유 값을 agent 데이터베이스에 복제하지 않습니다. 따라서 정상 공유 프로필이 있어도 실패한 agent에 오래된 같은 ID의 프로필이 남아 있으면 선택 결과가 달라질 수 있습니다.

정상 agent와 실패한 agent에서 models status --agent ... 및 models auth list --agent ...를 각각 확인하세요. 같은 모델·제공업체를 사용하는지, 프로필 ID가 같은지, 사용 불가 이유가 있는지 비교합니다. 특정 제공업체의 로컬 우선순위는 다음 명령으로 확인할 수 있습니다.

openclaw models auth order get --provider anthropic --agent <agentId>

로컬 인증 순서와 설정의 auth.order.<provider> 때문에 사용할 프로필이 제외될 수도 있습니다. 잘못된 계정 선택이면 정확한 프로필을 갱신하거나 선택을 수정하고, 독립 계정이 필요한 agent라면 별도 로그인을 구성합니다. 데이터베이스 행을 수동으로 바꾸거나 정상 agent의 OAuth refresh token을 복사하지 마세요. 일부 제공업체는 갱신 시 이전 토큰을 무효화합니다.

Claude CLI의 네이티브 로그인은 이 공유 저장소 밖에서 관리됩니다. 공유 API 프로필이 있다는 사실이 같은 서비스 사용자에게 Claude CLI 로그인이 있다는 뜻은 아닙니다.

업데이트 뒤 401이 시작됐다면 인증 이전 상태를 점검하세요

현재 런타임은 이전 auth-profiles.json, auth-state.json, agent별 auth.json의 비밀값을 직접 사용하지 않습니다. 지원되는 이전 파일은 SQLite로 가져오기 위한 입력입니다. 파일 안에 키가 남아 있다고 현재 요청에서 그 키를 쓰는 것은 아닙니다.

먼저 버전과 openclaw doctor 결과를 확인하고, 변경 전 설정과 상태 디렉터리의 백업을 보존하세요. AUTH_PROFILE_MIGRATION_REQUIRED가 보고되거나 업데이트 후 남은 인증 정보의 정리가 필요하다면 문서가 안내하는 복구를 적용합니다.

openclaw doctor --fix
openclaw gateway restart
openclaw models status --agent <agentId>

doctor --fix는 상태를 변경합니다. 공식 OAuth 저장 설명에 따르면 확인된 이전 값을 가져오고 원본 파일을 시각이 붙은 아카이브로 보존합니다. 이미 사용 가능한 저장된 인증이 있으면 이전 파일로 덮어쓰지 않습니다. 업데이트 문제 해결 안내는 재인증 후에도 남은 agent별 오래된 OAuth 복사본을 정리하는 경우도 설명합니다.

예외는 오래된 credentials/oauth.json입니다. 이 파일의 가져오기 기능은 현재 제거되어 있으며, 공식 문서는 해당 파일이 남아 있는 경우 2026.9.5를 거쳐 가져온 뒤 최신 버전으로 업그레이드하도록 안내합니다. 모든 설치에 이 중간 버전이 필요한 것은 아닙니다. 파일명과 doctor 진단을 확인한 뒤 적용하세요.

구버전으로 무조건 되돌리는 것도 피해야 합니다. 현재 상태가 이미 이전되었다면 과거 릴리스가 읽지 못할 수 있습니다. 의도적으로 되돌릴 때는 공식 롤백 안내에 따라 호환성을 확인하거나 해당 릴리스와 맞는 검증된 백업을 복원합니다. meta.lastTouchedVersion을 지워 보호 장치를 우회하지 마세요.

missing authentication header가 계속되면 키 교체를 멈추고 요청 경로를 조사하세요

이 오류는 응답한 서버가 필요한 인증 헤더를 받지 못했다는 뜻입니다. 원인은 키 입력 누락뿐 아니라 잘못된 인증 선택, 제공업체 설정, 중계 과정의 헤더 제거, 특정 버전의 요청 처리 문제일 수 있습니다. 오류만 보고 어느 하나를 확정할 수는 없습니다.

1. 실패한 대화의 모델·실행 방식과 models status --agent <agentId>가 보여 주는 설정을 맞춰 봅니다.
2. models.providers.<id>의 제공업체 ID, baseUrl, api, 모델 ID가 의도한 연결과 일치하는지 확인합니다. 연결 주소와 프로토콜은 인증 프로필이 아닌 모델 제공업체 설정에 속합니다.
3. Gateway 서비스가 그 인증 정보를 실제로 읽을 수 있는지 확인합니다. 셸에서 보이는 환경 변수, 로컬 프로필, 공유 프로필 중 무엇을 선택했는지 구분합니다.
4. 계속 실패하면 버전, agent ID, 모델 ID, 연결 주소와 오류 원문을 모아 요청을 만드는 플러그인 또는 중계 설정을 조사합니다. 공유하는 자료에서는 비밀값과 인증 헤더를 제거합니다.

OpenRouter에서 유효한 키가 있어도 이 오류가 났다는 과거 신고가 있습니다. 이슈 #51056은 Linux의 2026.3.13, 이슈 #97934는 macOS의 2026.6.10을 다룹니다. 두 번째 신고자는 2026.6.1로 되돌리자 동작했다고 보고했습니다. 이는 특정 환경의 과거 보고이며, 현재 버전 전체의 결함이나 현재 사용자에게 적합한 롤백을 증명하지 않습니다. 키 확인을 반복해도 같은 오류가 남는다면 버전과 요청 처리 경로를 함께 봐야 한다는 근거로 사용하세요.

복구 후에는 같은 대화에서 짧은 요청으로 확인하세요

저장 완료, 모델 목록 표시, --check 종료 코드 0은 실제 응답 성공과 다릅니다. 복구한 뒤에는 원래 실패한 agent, 모델, 실행 방식, 계정을 유지한 상태에서 짧은 요청 하나를 보내세요. 모델의 정상 응답이 나오고 해당 요청의 로그에 같은 인증 오류가 없어야 그 경로의 복구를 확인할 수 있습니다. 실제 요청에는 토큰 사용이나 요금이 발생할 수 있습니다. 장시간 작업을 재개하기 전에 짧게 확인하는 이유입니다.

CLI의 models status --probe로 검사할 수도 있지만 실행 전제가 있습니다. 현재 probe 설명에 따르면 직접 probe는 임시 내부 세션을 만들고 상태 디렉터리를 독점해야 합니다. 실행 중인 Gateway를 먼저 중지해야 하며, 검사 결과가 출력된 뒤에도 작업과 정리가 끝날 때까지 기다려야 합니다.

아래는 Anthropic의 한 agent로 범위를 제한하는 문서 예시입니다. 사용할 프로필을 지정하려면 --probe-profile <profileId>를 추가합니다.

openclaw gateway stop
openclaw models status --agent <agentId> --probe --probe-provider anthropic --probe-concurrency 1 --probe-max-tokens 8

probe는 실제 모델 요청이며 비용과 속도 제한에 영향을 줄 수 있습니다. --probe-max-tokens도 최선의 제한일 뿐입니다. 다른 프로세스가 같은 상태 디렉터리를 사용하지 않도록 하고, 명령의 작업과 정리가 완료된 뒤 openclaw gateway start로 다시 시작하세요. 타임아웃이나 중단만으로 정리가 끝났다고 판단하면 안 됩니다. 정리 실패가 보고되면 해결한 뒤 Gateway를 재개합니다. 운영 중인 Gateway를 유지해야 한다면 대화에서 짧은 요청으로 확인하는 방법을 선택하세요.

결과가 401에서 429, rate_limit, billing 등으로 바뀌었다면 새 오류의 원인을 따로 확인합니다. 인증 오류가 사라졌다고 전체 호출이 성공한 것은 아니며, 대기 상태와 잘못된 키를 혼동해 토큰을 계속 교체하지 마세요.

복구한 인증 방식을 계속 사용할지 결정하세요

장기간 켜 두는 서버에서는 API 키가 관리와 청구를 설명하기 쉽습니다. 공식 Gateway 인증 안내는 항상 실행하는 호스트에 API 키를 가장 예측 가능한 선택으로 안내합니다. 직접 관리하는 개인 컴퓨터에서 이미 Claude Code를 사용한다면 Claude CLI 방식도 선택할 수 있지만, 서비스 사용자와 CLI 로그인이 맞아야 합니다.

이 그림은 인증 방식의 차이를 설명하는 기존 자료입니다. 실제 설정에서는 위 표와 현재 문서의 조건을 적용하세요. 특히 Claude CLI를 선택했다는 사실만으로 구독 요금이 적용된다고 단정할 수 없습니다. Anthropic 제공업체 문서는 실행 방식뿐 아니라 선택된 계정도 확인하도록 안내합니다. CLI에서 명시적으로 API 키 계정을 사용하면 API 청구가 적용됩니다. 모델 이름만으로 인증이나 청구 방식을 판단하지 마세요.

자주 묻는 질문

OpenClaw 401이면 API 키를 새로 만들면 되나요?

먼저 실패한 인증을 확인해야 합니다. Gateway 접속 오류라면 Gateway 토큰 또는 기기 승인을, 모델 제공업체의 401이라면 선택된 제공업체 키·토큰 또는 CLI 로그인을 점검합니다. missing authentication header가 반복되면 키 교체보다 인증 정보 선택과 요청 경로를 확인해야 합니다.

main agent는 되는데 새 agent는 왜 실패하나요?

새 agent의 모델이나 실행 방식이 다르거나, 로컬 프로필이 공유 프로필을 덮어쓰거나, 인증 우선순위가 다를 수 있습니다. 현재 OpenClaw는 로컬 프로필이 없으면 공유 인증을 읽으므로 모든 agent에 별도 키가 필요한 것은 아닙니다. 실패한 agent를 지정한 상태와 해당 대화의 /model status를 함께 확인하세요. 공식 저장 설명

auth-profiles.json에 키가 있는데 왜 인식하지 못하나요?

현재 런타임은 이전 JSON 파일의 키를 직접 사용하지 않습니다. 지원되는 파일은 openclaw doctor --fix로 SQLite에 가져와야 합니다. 먼저 백업과 doctor 진단을 확인하세요. 오래된 credentials/oauth.json은 별도의 중간 버전 이전이 필요하므로 같은 방법을 일괄 적용하면 안 됩니다. 공식 이전 조건

setup-token은 지금도 지원되나요?

공식 문서에 지원되는 인증 방식으로 남아 있습니다. 다만 현재 Anthropic 문제 해결 안내는 토큰이 갑자기 무효화된 경우와 신규 설정에서 API 키를 권합니다. setup-token 지원과 사용 중인 토큰의 유효성은 별개의 문제입니다. Anthropic 문제 해결

models status --check가 성공했는데 대화는 왜 401인가요?

--check는 설정된 인증·실행 환경의 상태를 확인하며 모델 요청 성공을 보장하지 않습니다. 해당 대화가 agent 기본값과 다른 모델이나 계정을 선택했을 수도 있습니다. /model status로 대화의 선택을 확인하고 같은 경로에 짧은 요청을 보내세요. models CLI 상태 확인 범위