OpenClaw 401은 대개 하나의 bad token 문제가 아니라 세 가지 서로 다른 분기 중 하나입니다. invalid bearer token, missing authentication header, 또는 특정 agent에 자격 증명이 없는 경우입니다. 가장 먼저 해야 할 일은 정확한 오류 문자열을 올바른 분기로 돌려놓는 것입니다.
이 분기를 먼저 나누면 지금 깨진 가지에만 최소 수정 적용할 수 있습니다. 동시에 복구 후에 이 host에 어떤 인증 방식을 남겨야 할지도 더 쉽게 판단할 수 있습니다. 오래 켜 두는 gateway host라면 한 번 통했던 길보다 장기적으로 예측 가능한 길이 더 안전합니다.
30초 분기 보드
설정을 건드리기 전에 먼저 오류를 올바른 분기로 보내세요.
| 로그에 보이는 문구 | 먼저 의심할 지점 | 가장 안전한 첫 단계 | 같은 경로에서 확인할 것 | 언제 더 넓게 조사할지 |
|---|---|---|---|---|
invalid bearer token | token 기반 인증 경로가 만료되었거나, 덮어써졌거나, 현재 build에서 불안정함 | 그 경로를 다시 인증한다 | 같은 agent, 같은 host에서 같은 분기가 사라졌는지 본다 | clean re-auth 뒤에도 같은 분기가 남는다 |
missing authentication header | request routing, provider config, 혹은 auth를 아예 싣지 못한 전송 경로 | 어떤 레이어가 outbound request를 만들고 있는지 확인한다 | 재시도한 request에 auth header가 실제로 붙는지 본다 | 정상 credential로도 missing-header가 반복된다 |
한 agent는 되는데 다른 agent는 401 또는 no credentials | 실패한 그 agent 자체 | 실패한 agent에 credential을 추가하거나 갱신한다 | 그 agent만 다시 테스트한다 | 그 agent에 usable profile이 여전히 없다 |
이 분기는 추상적인 분류가 아닙니다. 현재 OpenClaw 문서는 Anthropic에 대해 API key, Claude CLI reuse, setup-token reuse 등 여러 인증 경로를 여전히 안내합니다. 동시에 현재 provider docs는 auth state가 agent별로 관리된다고 설명합니다. 공개 issue 역시 401이 서로 다른 분기에서 나온다는 점을 보여 줍니다. issue #23538은 OpenClaw 2026.2.21-2의 invalid bearer token을 기록하고, issue #34830은 별도의 401 missing authentication header 회귀를 보여 줍니다.
그래서 첫 질문은 “어떤 key를 바꿀까?”가 아니라 “지금 어느 분기인가?”여야 합니다. 이 질문을 건너뛰면 멀쩡하던 인증 경로까지 같이 망가뜨리기 쉽습니다.
invalid bearer token이 보일 때
invalid bearer token은 request에 credential이 실려 나갔지만 upstream이 그것을 사용할 수 없다고 판단했다는 뜻인 경우가 많습니다. 현재 OpenClaw의 공개 가이드에서는 이 분기가 direct Anthropic API key보다 Claude login reuse, Claude CLI reuse, setup-token reuse 같은 token-driven 경로와 더 자주 연결됩니다.
이 경우 첫 단계는 큰 설정 수술이 아니라 재인증입니다. 현재 OpenClaw Anthropic provider docs는 401 errors / token suddenly invalid를 독립된 운영 분기로 다룹니다. Claude Help는 ANTHROPIC_API_KEY가 Claude Code의 subscription-style auth를 덮어쓸 수 있다고 설명합니다. 즉, 사용자는 로그인된 것처럼 느끼지만 실제 request는 다른 인증 경로를 타고 있을 수 있습니다.
저장된 token이 있다는 사실만으로 runtime auth가 건강하다고 볼 수는 없습니다. issue #23538은 setup-token이 받아들여지고 저장되었는데도 Anthropic request가 HTTP 401 authentication_error: Invalid bearer token으로 실패한 사례입니다. 여기서 배워야 할 점은 setup-token이 항상 깨진다는 것이 아니라, 저장 성공만으로 장기 운영 증거가 되지 않는다는 것입니다.
안전한 복구 순서는 다음과 같습니다.
- 지금 사용할 예정인 token/setup-token flow를 current docs 기준으로 다시 수행합니다.
- 우선순위를 계속 잡아먹는 stale session이나 revoked token을 정리합니다. Claude session revoke 안내를 그대로 쓸 수 있습니다.
ANTHROPIC_API_KEY가 의도하지 않은 경로를 활성화하지 않았는지 확인합니다.- 재인증 후에는 같은 agent, 같은 host에서 다시 테스트합니다.
그래도 같은 분기가 남는다면, 이제 문제는 단순한 credential 교체가 아니라 이 host에 어떤 인증 방식을 남길지의 문제입니다. 장기 운영 host라면 fragile한 token reuse보다 direct API key가 더 다루기 쉬운 경우가 많습니다. Anthropic token 쪽을 더 깊게 봐야 한다면 영어 가이드인 OpenClaw Anthropic API key errors를 이어서 볼 수 있습니다.
missing authentication header가 보일 때
missing authentication header는 똑같이 401이지만 의미가 다릅니다. 이쪽은 request가 usable auth를 싣지 못하고 나갔을 가능성이 높습니다. invalid bearer token처럼 “보낸 credential이 거절됐다”는 이야기가 아닙니다.
Issue #34830이 중요한 이유도 여기에 있습니다. 이 issue는 401 missing authentication header를 별도 회귀 분기로 보여 줍니다. 로그가 header 누락을 직접 말해 주고 있다면, 첫 작업은 outbound request를 실제로 만드는 레이어가 어디인지 확인하는 것입니다.
최소한의 순서는 짧아도 충분합니다.
- 어떤 provider path 또는 어떤 agent가 failing request를 만들었는지 확인합니다.
- 그 경로가 읽는 active config, env, profile을 확인합니다.
- known-good credential로 다시 시도해 auth header가 붙는지 확인합니다.
그런데도 missing-header가 계속되면, 이후는 token rotation보다 routing, wiring, build behavior의 영역입니다. 이 분기에서 secrets만 계속 바꾸는 것은 대부분 헛수고가 됩니다.
main agent는 되는데 다른 agent만 실패할 때
이 분기도 앞의 두 가지와 별개입니다. 현재 OpenClaw docs와 CLI 구조는 auth profile을 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json 같은 agent 단위 위치에 둡니다. 운영 관점에서 풀면, 각 agent는 자기 credential이 필요합니다. main agent가 정상이라고 해서 새 agent가 같은 상태를 자동으로 가진다는 뜻은 아닙니다.
그래서 이 경우에는 host 전체가 아니라 실패한 agent를 고쳐야 합니다. 실패한 agent의 auth state를 정상 agent와 비교하고, 필요한 credential을 그 agent에만 추가하거나 갱신한 뒤, 그 agent만 다시 테스트하세요. host 전체 onboarding을 다시 돌리면 멀쩡한 경로까지 흔들릴 수 있습니다.
이 분기는 복잡한 auth 구성이 조사 비용을 높인다는 점도 보여 줍니다. local sign-in reuse, per-agent profiles, environment overrides를 한꺼번에 섞어 두면 동작은 할 수 있어도 어떤 분기가 깨졌는지 찾기 어려워집니다. 오래 운영할 gateway라면 단순한 경로가 강합니다.
이 host에 남길 인증 방식을 고르기
복구 후에 중요한 질문은 “방금 어떤 route가 한 번 통했나?”가 아니라 “이 host에서 무엇이 가장 덜 다시 깨질까?”입니다.
현재 OpenClaw guidance는 이 점에서 꽤 명확합니다. Gateway authentication docs는 always-on gateway host에서 API key 쪽으로 기웁니다. Anthropic provider docs는 Claude CLI reuse와 setup-token reuse를 여전히 허용하지만, OpenClaw FAQ는 local Claude login reuse를 production default로 권하지 않습니다. FAQ에는 2026년 4월 4일자 Anthropic 공지도 기록돼 있는데, OpenClaw의 Claude login path에는 subscription과 별도의 Extra Usage billing이 필요하다고 나옵니다.
실무 판단은 아래 정도면 충분합니다.
| 환경 | 남기기 쉬운 기본 선택 | 이유 |
|---|---|---|
| 오래 켜 두는 server / shared gateway host | direct API key | 숨은 상태가 적고, 재시작 후에도 설명과 디버깅이 쉽다 |
| 직접 관리하는 개인 로컬 머신 | Claude CLI 또는 subscription-linked auth도 가능 | 편의성이 중요하고 machine과 session이 모두 로컬이다 |
| setup-token reuse | 공식 지원은 되지만 version-sensitive | docs는 남겨 두지만 공개 issue는 universal default로 과신하면 안 된다는 점을 보여 준다 |
핵심은 host에 맞게 고르는 것입니다. 장기 운영 host에서는 predictability가 더 중요하고, 개인 로컬 환경에서는 convenience가 더 중요할 수 있습니다.
수정 후 짧게 확인하기
복구 뒤 같은 401을 반복하지 않으려면 짧은 확인 루틴이 필요합니다.
- 실제로 실패했던 같은 agent를 다시 테스트합니다.
- 남길 생각이던 인증 경로가 실제로 active인지 확인합니다.
- stale token path와 오래된 session을 정리합니다.
- 인증 방식을 바꿨다면 이 host의 default를 기록합니다.
여기서는 cooldown state와 credential failure를 섞지 않는 것도 중요합니다. 현재 Anthropic provider docs는 No available auth profile (all in cooldown/unavailable)를 openclaw models status --json으로 보라고 안내합니다. cooldown은 invalid bearer token도 아니고 missing authentication header도 아닙니다.
판단 기준은 단순하게 가져가면 됩니다.
invalid bearer token이 re-auth로 사라지면 그 분기는 닫고, 같은 경로를 계속 둘지 별도로 결정합니다.missing authentication header가 남으면 routing과 build behavior를 계속 봅니다.- 한 agent만 실패하면 그 agent를 먼저 고칩니다.
- 문제가 401 범위를 넘어서면 더 넓은 OpenClaw troubleshooting guide나 installation and deployment guide로 넘어갑니다.
FAQ
OpenClaw 401은 전부 API key가 틀렸다는 뜻인가요
아닙니다. 현재 공개 근거만으로도 invalid bearer token, missing authentication header, agent별 credential gap이라는 최소 세 가지 분기를 나눠야 합니다.
setup-token은 아직 지원되나요
네. 현재 OpenClaw docs는 setup-token을 계속 지원 경로로 다룹니다. 다만 2026년 4월 7일 기준 issue #23538은 OpenClaw 2026.2.21-2의 invalid bearer token을 보여 주므로, “지원되지만 version-sensitive하다”라고 말하는 편이 정확합니다.
왜 main agent는 되는데 새 agent는 실패하나요
현재 docs가 auth state를 agent별로 관리하기 때문입니다. main agent가 정상이어도 새 agent가 같은 credential을 자동 상속한 것은 아닙니다.
장기 운영 server에서는 무엇이 가장 안전한가요
long-lived host에서는 현재 guidance가 가장 예측 가능한 route를 권합니다. 실무에서는 direct API key가 자주 선택됩니다.
마지막 운영 규칙
OpenClaw 401을 빨리 고치려면 “무슨 credential을 바꿀까?”보다 “어느 분기가 깨졌나?”를 먼저 물어야 합니다. 정확한 오류 문자열로 분기를 나누고, 그 가지에만 최소 수정 적용한 뒤, 같은 경로에서 검증하고, 마지막에 이 host에 남길 인증 방식을 정하세요.