문제 해결

• 로컬 MLX/vLLM 스타일 서버에서 model_not_found → baseUrl에 /v1이 포함되어 있고, /v1/chat/completions 백엔드에 대해 api가 "openai-completions"이며, models.providers.<provider>.models[].id가 기본 제공자 로컬 id인지 확인하세요. 예를 들어 mlx/mlx-community/Qwen3-30B-A3B-6bit처럼 제공자 접두사를 한 번 붙여 선택하고, 카탈로그 항목은 mlx-community/Qwen3-30B-A3B-6bit로 유지하세요.
• messages[...].content: invalid type: sequence, expected a string → 백엔드가 구조화된 Chat Completions 콘텐츠 부분을 거부합니다. 수정: models.providers.<provider>.models[].compat.requiresStringContent: true를 설정하세요.
• incomplete turn detected ... stopReason=stop payloads=0 → 백엔드가 Chat Completions 요청을 완료했지만 해당 턴에 사용자가 볼 수 있는 어시스턴트 텍스트를 반환하지 않았습니다. OpenClaw는 replay-safe인 빈 OpenAI 호환 턴을 한 번 재시도합니다. 지속적인 실패는 보통 백엔드가 빈/비텍스트 콘텐츠를 내보내거나 최종 답변 텍스트를 억제한다는 뜻입니다.
• 작은 직접 요청은 성공하지만 OpenClaw 에이전트 실행이 백엔드/모델 충돌로 실패함(예: 일부 inferrs 빌드의 Gemma) → OpenClaw 전송은 이미 올바를 가능성이 높고, 백엔드가 더 큰 에이전트 런타임 프롬프트 형태에서 실패하는 것입니다.
• 도구를 비활성화한 후 실패가 줄어들지만 사라지지는 않음 → 도구 스키마가 압박 요인의 일부였지만, 남은 문제는 여전히 업스트림 모델/서버 용량 또는 백엔드 버그입니다.

1. 문자열 전용 Chat Completions 백엔드에는 compat.requiresStringContent: true를 설정하세요.
2. OpenClaw의 도구 스키마 표면을 안정적으로 처리할 수 없는 모델/백엔드에는 compat.supportsTools: false를 설정하세요.
3. 가능한 곳에서 프롬프트 압박을 낮추세요: 더 작은 워크스페이스 부트스트랩, 더 짧은 세션 기록, 더 가벼운 로컬 모델, 또는 더 강력한 긴 컨텍스트 지원을 갖춘 백엔드.
4. 작은 직접 요청은 계속 통과하지만 OpenClaw 에이전트 턴이 여전히 백엔드 내부에서 충돌한다면, 업스트림 서버/모델 제한으로 보고 허용된 payload 형태와 함께 재현 사례를 제출하세요.

• device identity required → 비보안 컨텍스트이거나 디바이스 인증이 누락되었습니다.
• origin not allowed → 브라우저 Origin이 gateway.controlUi.allowedOrigins에 없습니다(또는 명시적 허용 목록 없이 local loopback이 아닌 브라우저 origin에서 연결 중입니다).
• device nonce required / device nonce mismatch → 클라이언트가 challenge 기반 디바이스 인증 흐름(connect.challenge + device.nonce)을 완료하지 않고 있습니다.
• device signature invalid / device signature expired → 클라이언트가 현재 핸드셰이크에 대해 잘못된 payload(또는 오래된 타임스탬프)에 서명했습니다.
• AUTH_TOKEN_MISMATCH와 canRetryWithDeviceToken=true → 클라이언트는 캐시된 디바이스 토큰으로 신뢰할 수 있는 재시도를 한 번 수행할 수 있습니다.
• 해당 캐시된 토큰 재시도는 페어링된 디바이스 토큰과 함께 저장된 캐시된 scope 집합을 재사용합니다. 명시적 deviceToken / 명시적 scopes 호출자는 대신 요청한 scope 집합을 유지합니다.
• 해당 재시도 경로 밖에서는 connect 인증 우선순위가 명시적 공유 토큰/비밀번호, 명시적 deviceToken, 저장된 디바이스 토큰, 부트스트랩 토큰 순입니다.
• 비동기 Tailscale Serve Control UI 경로에서는 리미터가 실패를 기록하기 전에 동일한 {scope, ip}에 대한 실패한 시도가 직렬화됩니다. 따라서 같은 클라이언트의 잘못된 동시 재시도 두 번은 두 개의 일반 불일치 대신 두 번째 시도에서 retry later로 나타날 수 있습니다.
• 브라우저 origin local loopback 클라이언트에서 too many failed authentication attempts (retry later) → 같은 정규화된 Origin의 반복 실패가 일시적으로 잠깁니다. 다른 localhost origin은 별도 버킷을 사용합니다.
• 해당 재시도 후에도 반복되는 unauthorized → 공유 토큰/디바이스 토큰 드리프트입니다. 토큰 구성을 새로 고치고 필요하면 디바이스 토큰을 다시 승인/교체하세요.
• gateway connect failed: → 잘못된 host/port/url 대상입니다.

• Gateway start blocked: set gateway.mode=local 또는 existing config is missing gateway.mode → 로컬 Gateway 모드가 활성화되지 않았거나, 구성 파일이 덮어써져 gateway.mode가 손실되었습니다. 수정: 구성에서 gateway.mode="local"을 설정하거나, openclaw onboard --mode local / openclaw setup을 다시 실행해 예상되는 로컬 모드 구성을 다시 찍으세요. Podman으로 OpenClaw를 실행 중이라면 기본 구성 경로는 ~/.openclaw/openclaw.json입니다.
• refusing to bind gateway ... without auth → 유효한 Gateway 인증 경로(토큰/비밀번호 또는 구성된 경우 신뢰할 수 있는 프록시) 없이 비-loopback에 바인딩했습니다.
• another gateway instance is already listening / EADDRINUSE → 포트 충돌입니다.
• Other gateway-like services detected (best effort) → 오래되었거나 병렬인 launchd/systemd/schtasks 유닛이 존재합니다. 대부분의 설정에서는 머신당 하나의 Gateway를 유지해야 합니다. 둘 이상이 정말 필요하다면 포트 + 구성/상태/작업 영역을 분리하세요. /gateway#multiple-gateways-same-host를 참조하세요.
• doctor의 System-level OpenClaw gateway service detected → 사용자 수준 서비스가 없는 상태에서 systemd 시스템 유닛이 존재합니다. doctor가 사용자 서비스를 설치하도록 허용하기 전에 중복 서비스를 제거하거나 비활성화하세요. 또는 시스템 유닛이 의도한 감독자인 경우 OPENCLAW_SERVICE_REPAIR_POLICY=external을 설정하세요.
• Gateway service port does not match current gateway config → 설치된 supervisor가 여전히 이전 --port를 고정하고 있습니다. openclaw doctor --fix 또는 openclaw gateway install --force를 실행한 다음 Gateway 서비스를 다시 시작하세요.

• 시작, 핫 리로드 또는 OpenClaw 소유 쓰기 중에 구성이 검증을 통과하지 못했습니다.
• Gateway 시작은 openclaw.json을 다시 쓰는 대신 닫힌 상태로 실패합니다.
• 핫 리로드는 잘못된 외부 편집을 건너뛰고 현재 런타임 구성을 활성 상태로 유지합니다.
• OpenClaw 소유 쓰기는 커밋 전에 잘못되었거나 파괴적인 페이로드를 거부하고 .rejected.*를 저장합니다.
• openclaw doctor --fix가 복구를 담당합니다. JSON이 아닌 접두사를 제거하거나 마지막 정상 사본을 복원하면서 거부된 페이로드를 .clobbered.*로 보존할 수 있습니다.

CONFIG="$(openclaw config file)"
ls -lt "$CONFIG".clobbered.* "$CONFIG".rejected.* 2>/dev/null | head
diff -u "$CONFIG" "$(ls -t "$CONFIG".clobbered.* 2>/dev/null | head -n 1)"
openclaw config validate
openclaw doctor

• .clobbered.*가 존재함 → doctor가 활성 구성을 복구하면서 손상된 외부 편집을 보존했습니다.
• .rejected.*가 존재함 → OpenClaw 소유 구성 쓰기가 커밋 전에 스키마 또는 덮어쓰기 확인에 실패했습니다.
• Config write rejected: → 쓰기가 필수 구조를 제거하거나 파일을 급격히 줄이거나 잘못된 구성을 유지하려고 했습니다.
• config reload skipped (invalid config): → 직접 편집이 검증에 실패하여 실행 중인 Gateway에서 무시되었습니다.
• Invalid config at ... → Gateway 서비스가 부팅되기 전에 시작이 실패했습니다.
• missing-meta-vs-last-good, gateway-mode-missing-vs-last-good, 또는 size-drop-vs-last-good:* → OpenClaw 소유 쓰기가 마지막 정상 백업과 비교해 필드나 크기를 잃었기 때문에 거부되었습니다.
• Config last-known-good promotion skipped → 후보에 *** 같은 마스킹된 비밀 자리표시자가 포함되어 있었습니다.

1. openclaw doctor --fix를 실행해 doctor가 접두사가 붙었거나 덮어써진 구성을 복구하거나 마지막 정상 구성을 복원하게 하세요.
2. .clobbered.* 또는 .rejected.*에서 의도한 키만 복사한 다음 openclaw config set 또는 config.patch로 적용하세요.
3. 다시 시작하기 전에 openclaw config validate를 실행하세요.
4. 직접 편집하는 경우 변경하려는 부분 객체만이 아니라 전체 JSON5 구성을 유지하세요.

• cron: scheduler disabled; jobs will not run automatically → cron 비활성화됨.
• cron: timer tick failed → 스케줄러 틱 실패. 파일/로그/런타임 오류를 확인하세요.
• heartbeat skipped with reason=quiet-hours → 활성 시간 창 밖임.
• heartbeat skipped with reason=empty-heartbeat-file → HEARTBEAT.md가 있지만 빈 줄/마크다운 헤더만 포함되어 있어 OpenClaw가 모델 호출을 건너뜁니다.
• heartbeat skipped with reason=no-tasks-due → HEARTBEAT.md에 tasks: 블록이 있지만 이 틱에 기한이 된 작업이 없습니다.
• heartbeat: unknown accountId → Heartbeat 전달 대상의 계정 ID가 잘못됨.
• heartbeat skipped with reason=dm-blocked → Heartbeat 대상이 DM 스타일 목적지로 확인되었지만 agents.defaults.heartbeat.directPolicy(또는 에이전트별 재정의)가 block으로 설정되어 있음.

• unknown command "browser" 또는 unknown command 'browser' → 번들 브라우저 Plugin이 plugins.allow에 의해 제외됨.
• browser.enabled=true인데 브라우저 도구가 없거나 사용할 수 없음 → plugins.allow가 browser를 제외하므로 Plugin이 로드되지 않음.
• Failed to start Chrome CDP on port → 브라우저 프로세스 실행 실패.
• browser.executablePath not found → 구성된 경로가 잘못됨.
• browser.cdpUrl must be http(s) or ws(s) → 구성된 CDP URL이 file: 또는 ftp: 같은 지원되지 않는 스킴을 사용함.
• browser.cdpUrl has invalid port → 구성된 CDP URL에 잘못되었거나 범위를 벗어난 포트가 있음.
• Playwright is not available in this gateway build; '<feature>' is unsupported. → 현재 Gateway 설치에 핵심 브라우저 런타임 종속성이 없음. OpenClaw를 다시 설치하거나 업데이트한 다음 Gateway를 재시작하세요. ARIA 스냅샷과 기본 페이지 스크린샷은 여전히 작동할 수 있지만, 탐색, AI 스냅샷, CSS 선택자 요소 스크린샷, PDF 내보내기는 계속 사용할 수 없습니다.

• Could not find DevToolsActivePort for chrome → Chrome MCP 기존 세션이 선택된 브라우저 데이터 디렉터리에 아직 연결할 수 없습니다. 브라우저 검사 페이지를 열고 원격 디버깅을 활성화한 뒤 브라우저를 열어 둔 상태에서 첫 연결 프롬프트를 승인한 다음 다시 시도하세요. 로그인 상태가 필요하지 않다면 관리형 openclaw 프로필을 사용하는 것이 좋습니다.
• No Chrome tabs found for profile="user" → Chrome MCP 연결 프로필에 열린 로컬 Chrome 탭이 없음.
• Remote CDP for profile "<name>" is not reachable → 구성된 원격 CDP 엔드포인트가 Gateway 호스트에서 도달할 수 없음.
• Browser attachOnly is enabled ... not reachable 또는 Browser attachOnly is enabled and CDP websocket ... is not reachable → 연결 전용 프로필에 도달 가능한 대상이 없거나 HTTP 엔드포인트가 응답했지만 CDP WebSocket을 열 수 없음.

• fullPage is not supported for element screenshots → 스크린샷 요청에서 --full-page를 --ref 또는 --element와 함께 사용함.
• element screenshots are not supported for existing-session profiles; use ref from snapshot. → Chrome MCP / existing-session 스크린샷 호출은 CSS --element가 아니라 페이지 캡처 또는 스냅샷 --ref를 사용해야 함.
• existing-session file uploads do not support element selectors; use ref/inputRef. → Chrome MCP 업로드 훅에는 CSS 선택자가 아니라 스냅샷 ref가 필요함.
• existing-session file uploads currently support one file at a time. → Chrome MCP 프로필에서는 호출당 업로드 하나를 보내세요.
• existing-session dialog handling does not support timeoutMs. → Chrome MCP 프로필의 대화 상자 훅은 timeout 재정의를 지원하지 않음.
• existing-session type does not support timeoutMs overrides. → profile="user" / Chrome MCP 기존 세션 프로필의 act:type에는 timeoutMs를 생략하거나, 사용자 지정 timeout이 필요하면 관리형/CDP 브라우저 프로필을 사용하세요.
• existing-session evaluate does not support timeoutMs overrides. → profile="user" / Chrome MCP 기존 세션 프로필의 act:evaluate에는 timeoutMs를 생략하거나, 사용자 지정 timeout이 필요하면 관리형/CDP 브라우저 프로필을 사용하세요.
• response body is not supported for existing-session profiles yet. → responsebody에는 아직 관리형 브라우저 또는 원시 CDP 프로필이 필요함.
• 연결 전용 또는 원격 CDP 프로필에서 오래된 viewport / dark-mode / locale / offline 재정의 → 전체 Gateway를 재시작하지 않고 활성 제어 세션을 닫고 Playwright/CDP 에뮬레이션 상태를 해제하려면 openclaw browser stop --browser-profile <name>을 실행하세요.

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode

확인할 항목:

• gateway.mode=remote이면 로컬 서비스가 정상이어도 CLI 호출이 원격을 대상으로 할 수 있습니다.
• 명시적 --url 호출은 저장된 자격 증명으로 폴백하지 않습니다.

일반적인 징후:

• gateway connect failed: → 잘못된 URL 대상.
• unauthorized → 엔드포인트에는 도달 가능하지만 인증이 잘못됨.

openclaw config get gateway.bind
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status
openclaw logs --follow

확인할 항목:

• local loopback이 아닌 바인드(lan, tailnet, custom)에는 유효한 Gateway 인증 경로가 필요합니다. 공유 토큰/비밀번호 인증 또는 올바르게 구성된 non-loopback trusted-proxy 배포가 필요합니다.
• gateway.token 같은 오래된 키는 gateway.auth.token을 대체하지 않습니다.

일반적인 징후:

• refusing to bind gateway ... without auth → 유효한 Gateway 인증 경로 없이 non-loopback 바인드.
• 런타임이 실행 중인데 Connectivity probe: failed → Gateway는 살아 있지만 현재 인증/URL로 접근할 수 없음.

openclaw devices list
openclaw pairing list --channel <channel> [--account <id>]
openclaw logs --follow
openclaw doctor

확인할 항목:

• 대시보드/Node에 대한 대기 중인 장치 승인.
• 정책 또는 ID 변경 후 대기 중인 DM 페어링 승인.

일반적인 징후:

• device identity required → 장치 인증이 충족되지 않음.
• pairing required → 발신자/장치가 승인되어야 함.