문제 해결 🔧

OpenClaw가 잘못 작동할 때 문제를 해결하는 방법입니다.

빠른 분류 방법을 원하시면 FAQ의 First 60 seconds부터 시작하세요. 이 페이지는 런타임 오류 및 진단에 대해 더 깊이 다룹니다.

제공자별 바로 가기: /channels/troubleshooting

상태 및 진단

빠른 분류 명령 (순서대로):

출력 공유: openclaw status --all을 선호합니다 (토큰을 수정함). openclaw status를 붙여넣는 경우 먼저 OPENCLAW_SHOW_SECRETS=0을 설정하는 것을 고려하세요 (토큰 미리보기).

참조: Health checks 및 Logging.

일반적인 문제

No API key found for provider "anthropic"

이는 에이전트의 인증 저장소가 비어 있거나 Anthropic 자격 증명이 누락되었음을 의미합니다. 인증은 에이전트별이므로 새 에이전트는 메인 에이전트의 키를 상속하지 않습니다.

수정 옵션:

• 온보딩을 다시 실행하고 해당 에이전트에 대해 Anthropic을 선택합니다.
• 또는 gateway 호스트에서 setup-token을 붙여넣습니다:

  openclaw models auth setup-token --provider anthropic
  

• 또는 메인 에이전트 디렉토리에서 새 에이전트 디렉토리로 auth-profiles.json을 복사합니다.

확인:

openclaw models status

OAuth token refresh failed (Anthropic Claude subscription)

이는 저장된 Anthropic OAuth 토큰이 만료되고 새로 고침에 실패했음을 의미합니다. Claude 구독 (API 키 없음)을 사용하는 경우 가장 신뢰할 수 있는 수정은 Claude Code setup-token으로 전환하고 gateway 호스트에 붙여넣는 것입니다.

권장 (setup-token):

# Run on the gateway host (paste the setup-token)
openclaw models auth setup-token --provider anthropic
openclaw models status

다른 곳에서 토큰을 생성한 경우:

openclaw models auth paste-token --provider anthropic
openclaw models status

자세한 내용: Anthropic 및 OAuth.

Control UI fails on HTTP ("device identity required" / "connect failed")

일반 HTTP를 통해 대시보드를 열면 (예: http://<lan-ip>:18789/ 또는 http://<tailscale-ip>:18789/), 브라우저가 비보안 컨텍스트에서 실행되고 WebCrypto를 차단하므로 장치 ID를 생성할 수 없습니다.

수정:

• Tailscale Serve를 통해 HTTPS를 선호합니다.
• 또는 gateway 호스트에서 로컬로 엽니다: http://127.0.0.1:18789/.
• HTTP를 유지해야 하는 경우 gateway.controlUi.allowInsecureAuth: true를 활성화하고 gateway 토큰을 사용합니다 (토큰만; 장치 ID/페어링 없음). Control UI 참조.

CI Secrets Scan Failed

이는 detect-secrets가 베이스라인에 아직 없는 새로운 후보를 발견했음을 의미합니다. Secret scanning을 따르세요.

Service Installed but Nothing is Running

Gateway 서비스가 설치되었지만 프로세스가 즉시 종료되면 서비스가 "로드된" 것처럼 보이지만 실행되지 않습니다.

확인:

openclaw gateway status
openclaw doctor

Doctor/service는 런타임 상태 (PID/마지막 종료) 및 로그 힌트를 보여줍니다.

로그:

• 선호: openclaw logs --follow
• 파일 로그 (항상): /tmp/openclaw/openclaw-YYYY-MM-DD.log (또는 설정된 logging.file)
• macOS LaunchAgent (설치된 경우): $OPENCLAW_STATE_DIR/logs/gateway.log 및 gateway.err.log
• Linux systemd (설치된 경우): journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
• Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST

더 많은 로깅 활성화:

• 파일 로그 세부 정보 증가 (지속된 JSONL):

  { "logging": { "level": "debug" } }
  

• 콘솔 verbosity 증가 (TTY 출력만):

  { "logging": { "consoleLevel": "debug", "consoleStyle": "pretty" } }
  

• 빠른 팁: --verbose는 콘솔 출력만 영향을 줍니다. 파일 로그는 logging.level에 의해 제어됩니다.

형식, 설정 및 액세스에 대한 전체 개요는 /logging을 참조하세요.

"Gateway start blocked: set gateway.mode=local"

이는 설정이 존재하지만 gateway.mode가 설정되지 않았거나 (local이 아님) Gateway가 시작을 거부함을 의미합니다.

수정 (권장):

• 마법사를 실행하고 Gateway 실행 모드를 Local로 설정합니다:

  openclaw configure
  

• 또는 직접 설정합니다:

  openclaw config set gateway.mode local
  

대신 원격 Gateway를 실행하려는 경우:

• 원격 URL을 설정하고 gateway.mode=remote를 유지합니다:

  openclaw config set gateway.mode remote
  openclaw config set gateway.remote.url "wss://gateway.example.com"
  

임시/개발 전용: gateway.mode=local 없이 gateway를 시작하려면 --allow-unconfigured를 전달합니다.

아직 설정 파일이 없나요? openclaw setup을 실행하여 스타터 설정을 생성한 다음 gateway를 다시 실행합니다.

Service Environment (PATH + runtime)

Gateway 서비스는 shell/manager cruft를 피하기 위해 최소 PATH로 실행됩니다:

• macOS: /opt/homebrew/bin, /usr/local/bin, /usr/bin, /bin
• Linux: /usr/local/bin, /usr/bin, /bin

이는 의도적으로 버전 관리자 (nvm/fnm/volta/asdf) 및 패키지 관리자 (pnpm/npm)를 제외합니다. 왜냐하면 서비스가 shell init을 로드하지 않기 때문입니다. DISPLAY와 같은 런타임 변수는 ~/.openclaw/.env에 있어야 합니다 (gateway가 일찍 로드함). host=gateway에서 실행되는 Exec는 로그인 shell PATH를 exec 환경에 병합하므로 누락된 도구는 일반적으로 shell init이 내보내지 않았음을 의미합니다 (또는 tools.exec.pathPrepend를 설정). /tools/exec 참조.

WhatsApp + Telegram 채널은 Node가 필요합니다; Bun은 지원되지 않습니다. 서비스가 Bun 또는 버전 관리 Node 경로로 설치된 경우 openclaw doctor를 실행하여 시스템 Node 설치로 마이그레이션하세요.

Skill missing API key in sandbox

증상: 호스트에서는 Skill이 작동하지만 샌드박스에서는 API 키 누락으로 실패합니다.

이유: 샌드박스화된 exec는 Docker 내부에서 실행되며 호스트 process.env를 상속하지 않습니다.

수정:

• agents.defaults.sandbox.docker.env (또는 에이전트별 agents.list[].sandbox.docker.env)를 설정
• 또는 키를 커스텀 샌드박스 이미지에 베이킹
• 그런 다음 openclaw sandbox recreate --agent <id> (또는 --all)를 실행

Service Running but Port Not Listening

서비스가 실행 중으로 보고되지만 gateway 포트에서 아무것도 수신하지 않는 경우 Gateway가 바인딩을 거부했을 가능성이 높습니다.

여기서 "실행 중"의 의미

• Runtime: running은 supervisor (launchd/systemd/schtasks)가 프로세스가 살아 있다고 생각함을 의미합니다.
• RPC probe는 CLI가 실제로 gateway WebSocket에 연결하고 status를 호출할 수 있었음을 의미합니다.
• 항상 Probe target: + Config (service):를 "실제로 무엇을 시도했는가?" 줄로 신뢰하세요.

확인:

• openclaw gateway 및 서비스에 대해 gateway.mode는 local이어야 합니다.
• gateway.mode=remote를 설정한 경우 CLI는 기본적으로 원격 URL로 설정됩니다. 서비스는 여전히 로컬에서 실행 중일 수 있지만 CLI가 잘못된 곳을 프로브할 수 있습니다. openclaw gateway status를 사용하여 서비스의 해결된 포트 + 프로브 대상을 확인하세요 (또는 --url 전달).
• openclaw gateway status 및 openclaw doctor는 서비스가 실행 중으로 보이지만 포트가 닫혀 있을 때 로그에서 마지막 gateway 오류를 표시합니다.
• 루프백이 아닌 바인딩 (lan/tailnet/custom, 또는 루프백을 사용할 수 없을 때 auto)은 인증이 필요합니다: gateway.auth.token (또는 OPENCLAW_GATEWAY_TOKEN).
• gateway.remote.token은 원격 CLI 호출 전용입니다; 로컬 인증을 활성화하지 않습니다.
• gateway.token은 무시됩니다; gateway.auth.token을 사용하세요.

openclaw gateway status가 설정 불일치를 보여주는 경우

• Config (cli): ... 및 Config (service): ...는 일반적으로 일치해야 합니다.
• 일치하지 않으면 서비스가 다른 설정을 실행하는 동안 하나의 설정을 편집하고 있을 가능성이 매우 높습니다.
• 수정: 서비스가 사용하도록 하려는 동일한 --profile / OPENCLAW_STATE_DIR에서 openclaw gateway install --force를 다시 실행합니다.

openclaw gateway status가 서비스 설정 문제를 보고하는 경우

• Supervisor 설정 (launchd/systemd/schtasks)이 현재 기본값을 누락하고 있습니다.
• 수정: openclaw doctor를 실행하여 업데이트합니다 (또는 전체 재작성을 위해 openclaw gateway install --force).

Last gateway error:가 "refusing to bind … without auth"를 언급하는 경우

• gateway.bind를 루프백이 아닌 모드 (lan/tailnet/custom, 또는 루프백을 사용할 수 없을 때 auto)로 설정했지만 인증을 설정하지 않았습니다.
• 수정: gateway.auth.mode + gateway.auth.token (또는 OPENCLAW_GATEWAY_TOKEN 내보내기)을 설정하고 서비스를 다시 시작합니다.

openclaw gateway status가 bind=tailnet이라고 하지만 tailnet 인터페이스를 찾을 수 없는 경우

• Gateway가 Tailscale IP (100.64.0.0/10)에 바인딩하려고 했지만 호스트에서 감지되지 않았습니다.
• 수정: 해당 머신에서 Tailscale을 가동합니다 (또는 gateway.bind를 loopback/lan으로 변경).

Probe note:가 프로브가 루프백을 사용한다고 말하는 경우

• bind=lan의 경우 예상됩니다: gateway는 0.0.0.0 (모든 인터페이스)에서 수신하며 루프백은 여전히 로컬로 연결해야 합니다.
• 원격 클라이언트의 경우 실제 LAN IP (0.0.0.0이 아님)와 포트를 사용하고 인증이 설정되어 있는지 확인하세요.

Address Already in Use (Port 18789)

이는 이미 gateway 포트에서 무언가가 수신하고 있음을 의미합니다.

확인:

openclaw gateway status

리스너와 가능한 원인 (gateway가 이미 실행 중, SSH 터널)을 보여줍니다. 필요한 경우 서비스를 중지하거나 다른 포트를 선택하세요.

Extra Workspace Folders Detected

이전 설치에서 업그레이드한 경우 디스크에 여전히 ~/openclaw가 있을 수 있습니다. 여러 워크스페이스 디렉토리는 혼란스러운 인증 또는 상태 드리프트를 일으킬 수 있습니다. 왜냐하면 하나의 워크스페이스만 활성이기 때문입니다.

수정: 단일 활성 워크스페이스를 유지하고 나머지를 보관/제거합니다. Agent workspace 참조.

Main chat running in a sandbox workspace

증상: pwd 또는 파일 도구가 호스트 워크스페이스를 예상했지만 ~/.openclaw/sandboxes/...를 표시합니다.

이유: agents.defaults.sandbox.mode: "non-main"은 session.mainKey (기본값 "main")에서 키를 가져옵니다. 그룹/채널 세션은 자체 키를 사용하므로 non-main으로 처리되고 샌드박스 워크스페이스를 얻습니다.

수정 옵션:

• 에이전트에 대해 호스트 워크스페이스를 원하는 경우: agents.list[].sandbox.mode: "off"를 설정합니다.
• 샌드박스 내에서 호스트 워크스페이스 액세스를 원하는 경우: 해당 에이전트에 대해 workspaceAccess: "rw"를 설정합니다.

"Agent was aborted"

에이전트가 응답 중간에 중단되었습니다.

원인:

• 사용자가 stop, abort, esc, wait 또는 exit를 보냄
• 시간 초과 초과
• 프로세스 충돌

수정: 다른 메시지를 보내기만 하면 됩니다. 세션이 계속됩니다.

"Agent failed before reply: Unknown model: anthropic/claude-haiku-3-5"

OpenClaw는 의도적으로 이전/안전하지 않은 모델 (특히 프롬프트 인젝션에 더 취약한 모델)을 거부합니다. 이 오류가 표시되면 모델 이름이 더 이상 지원되지 않습니다.

수정:

• 제공자에 대해 최신 모델을 선택하고 설정 또는 모델 별칭을 업데이트합니다.
• 사용 가능한 모델이 확실하지 않은 경우 openclaw models list 또는 openclaw models scan을 실행하고 지원되는 모델을 선택합니다.
• 자세한 오류 이유는 gateway 로그를 확인하세요.

참조: Models CLI 및 Model providers.

Messages Not Triggering

확인 1: 발신자가 허용 목록에 있나요?

openclaw status

출력에서 AllowFrom: ...을 찾습니다.

확인 2: 그룹 채팅의 경우 멘션이 필요한가요?

# The message must match mentionPatterns or explicit mentions; defaults live in channel groups/guilds.
# Multi-agent: `agents.list[].groupChat.mentionPatterns` overrides global patterns.
grep -n "agents\\|groupChat\\|mentionPatterns\\|channels\\.whatsapp\\.groups\\|channels\\.telegram\\.groups\\|channels\\.imessage\\.groups\\|channels\\.discord\\.guilds" \
  "${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json}"

확인 3: 로그 확인

openclaw logs --follow
# or if you want quick filters:
tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | grep "blocked\\|skip\\|unauthorized"

Pairing Code Not Arriving

dmPolicy가 pairing인 경우 알 수 없는 발신자는 코드를 받아야 하며 승인될 때까지 메시지가 무시됩니다.

확인 1: 대기 중인 요청이 이미 기다리고 있나요?

openclaw pairing list <channel>

대기 중인 DM 페어링 요청은 기본적으로 채널당 3개로 제한됩니다. 목록이 가득 찬 경우 하나가 승인되거나 만료될 때까지 새 요청이 코드를 생성하지 않습니다.

확인 2: 요청이 생성되었지만 응답이 전송되지 않았나요?

openclaw logs --follow | grep "pairing request"

확인 3: 해당 채널에 대해 dmPolicy가 open/allowlist가 아닌지 확인합니다.

Image + Mention Not Working

알려진 문제: 멘션만 있는 이미지를 보내면 (다른 텍스트 없음), WhatsApp이 때때로 멘션 메타데이터를 포함하지 않습니다.

해결 방법: 멘션과 함께 텍스트를 추가합니다:

• ❌ @openclaw + 이미지
• ✅ @openclaw check this + 이미지

Session Not Resuming

확인 1: 세션 파일이 있나요?

ls -la ~/.openclaw/agents/<agentId>/sessions/

확인 2: 재설정 창이 너무 짧나요?

{
  "session": {
    "reset": {
      "mode": "daily",
      "atHour": 4,
      "idleMinutes": 10080  // 7 days
    }
  }
}

확인 3: 누군가 /new, /reset 또는 재설정 트리거를 보냈나요?

Agent Timing Out

기본 시간 초과는 30분입니다. 긴 작업의 경우:

{
  "reply": {
    "timeoutSeconds": 3600  // 1 hour
  }
}

또는 process 도구를 사용하여 긴 명령을 백그라운드로 실행합니다.

WhatsApp Disconnected

# Check local status (creds, sessions, queued events)
openclaw status
# Probe the running gateway + channels (WA connect + Telegram + Discord APIs)
openclaw status --deep

# View recent connection events
openclaw logs --limit 200 | grep "connection\\|disconnect\\|logout"

수정: 일반적으로 Gateway가 실행되면 자동으로 다시 연결됩니다. 문제가 지속되면 Gateway 프로세스를 다시 시작하거나 (감독 방법에 따라) verbose 출력과 함께 수동으로 실행합니다:

openclaw gateway --verbose

로그아웃 / 연결 해제된 경우:

openclaw channels logout
trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}/credentials" # if logout can't cleanly remove everything
openclaw channels login --verbose       # re-scan QR

Media Send Failing

확인 1: 파일 경로가 유효한가요?

ls -la /path/to/your/image.jpg

확인 2: 너무 큰가요?

• 이미지: 최대 6MB
• 오디오/비디오: 최대 16MB
• 문서: 최대 100MB

확인 3: 미디어 로그 확인

grep "media\\|fetch\\|download" "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" | tail -20

High Memory Usage

OpenClaw는 대화 기록을 메모리에 유지합니다.

수정: 정기적으로 다시 시작하거나 세션 제한을 설정합니다:

{
  "session": {
    "historyLimit": 100  // Max messages to keep
  }
}

일반적인 문제 해결

"Gateway won't start — configuration invalid"

OpenClaw는 이제 설정에 알 수 없는 키, 잘못된 형식의 값 또는 잘못된 유형이 포함되어 있을 때 시작을 거부합니다. 이는 안전을 위해 의도적입니다.

Doctor로 수정:

openclaw doctor
openclaw doctor --fix

참고사항:

• openclaw doctor는 모든 잘못된 항목을 보고합니다.
• openclaw doctor --fix는 마이그레이션/수리를 적용하고 설정을 다시 작성합니다.
• openclaw logs, openclaw health, openclaw status, openclaw gateway status 및 openclaw gateway probe와 같은 진단 명령은 설정이 잘못된 경우에도 여전히 실행됩니다.

"All models failed" — what should I check first?

• 시도 중인 제공자에 대한 자격 증명 존재 (인증 프로필 + env 변수).
• 모델 라우팅: agents.defaults.model.primary 및 fallback이 액세스할 수 있는 모델인지 확인합니다.
• 정확한 제공자 오류를 위해 /tmp/openclaw/…의 Gateway 로그.
• 모델 상태: /model status (채팅) 또는 openclaw models status (CLI) 사용.

I'm running on my personal WhatsApp number — why is self-chat weird?

self-chat 모드를 활성화하고 자신의 번호를 허용 목록에 추가합니다:

{
  channels: {
    whatsapp: {
      selfChatMode: true,
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123"]
    }
  }
}

WhatsApp setup 참조.

WhatsApp logged me out. How do I re‑auth?

로그인 명령을 다시 실행하고 QR 코드를 스캔합니다:

openclaw channels login

Build errors on main — what's the standard fix path?

1. git pull origin main && pnpm install
2. openclaw doctor
3. GitHub 이슈 또는 Discord 확인
4. 임시 해결 방법: 이전 커밋 체크아웃

npm install fails (allow-build-scripts / missing tar or yargs). What now?

소스에서 실행하는 경우 저장소의 패키지 관리자를 사용하세요: pnpm (선호). 저장소는 packageManager: "pnpm@…"를 선언합니다.

일반적인 복구:

git status   # ensure you're in the repo root
pnpm install
pnpm build
openclaw doctor
openclaw gateway restart

이유: pnpm은 이 저장소의 설정된 패키지 관리자입니다.

How do I switch between git installs and npm installs?

웹사이트 설치 프로그램을 사용하고 플래그로 설치 방법을 선택합니다. 제자리에서 업그레이드하고 gateway 서비스를 다시 작성하여 새 설치를 가리킵니다.

git 설치로 전환:

curl -fsSL https://openclaw.bot/install.sh | bash -s -- --install-method git --no-onboard

npm 전역으로 전환:

curl -fsSL https://openclaw.bot/install.sh | bash

참고사항:

• git 흐름은 저장소가 깨끗한 경우에만 rebase합니다. 먼저 변경 사항을 커밋하거나 stash합니다.
• 전환 후 다음을 실행합니다:

  openclaw doctor
  openclaw gateway restart
  

Telegram block streaming isn't splitting text between tool calls. Why?

블록 스트리밍은 완료된 텍스트 블록만 전송합니다. 단일 메시지를 보는 일반적인 이유:

• agents.defaults.blockStreamingDefault가 여전히 "off"입니다.
• channels.telegram.blockStreaming이 false로 설정되어 있습니다.
• channels.telegram.streamMode가 partial 또는 block이고 draft 스트리밍이 활성화됨 (개인 채팅 + 주제). 이 경우 draft 스트리밍이 블록 스트리밍을 비활성화합니다.
• minChars / coalesce 설정이 너무 높아 청크가 병합됩니다.
• 모델이 하나의 큰 텍스트 블록을 방출합니다 (중간 응답 플러시 지점 없음).

수정 체크리스트:

1. 루트가 아닌 agents.defaults 아래에 블록 스트리밍 설정을 넣습니다.
2. 실제 다중 메시지 블록 응답을 원하는 경우 channels.telegram.streamMode: "off"를 설정합니다.
3. 디버깅하는 동안 더 작은 청크/coalesce 임계값을 사용합니다.

Streaming 참조.

Discord doesn't reply in my server even with requireMention: false. Why?

requireMention은 채널이 허용 목록을 통과한 후 멘션 게이팅만 제어합니다. 기본적으로 channels.discord.groupPolicy는 allowlist이므로 길드를 명시적으로 활성화해야 합니다. channels.discord.guilds.<guildId>.channels를 설정하면 나열된 채널만 허용됩니다; 길드의 모든 채널을 허용하려면 생략합니다.

수정 체크리스트:

1. channels.discord.groupPolicy: "open"을 설정하거나 또는 길드 허용 목록 항목을 추가합니다 (선택적으로 채널 허용 목록).
2. channels.discord.guilds.<guildId>.channels에서 숫자 채널 ID를 사용합니다.
3. requireMention: false를 channels.discord.guilds 아래에 넣습니다 (전역 또는 채널별). 최상위 channels.discord.requireMention은 지원되지 않는 키입니다.
4. 봇에 Message Content Intent 및 채널 권한이 있는지 확인합니다.
5. 감사 힌트를 위해 openclaw channels status --probe를 실행합니다.

문서: Discord, Channels troubleshooting.

Cloud Code Assist API error: invalid tool schema (400). What now?

이는 거의 항상 도구 스키마 호환성 문제입니다. Cloud Code Assist 엔드포인트는 JSON Schema의 엄격한 하위 집합을 허용합니다. OpenClaw는 현재 main에서 도구 스키마를 스크럽/정규화하지만 수정은 아직 마지막 릴리스에 포함되지 않았습니다 (2026년 1월 13일 기준).

수정 체크리스트:

1. OpenClaw 업데이트:
   • 소스에서 실행할 수 있는 경우 main을 pull하고 gateway를 다시 시작합니다.
   • 그렇지 않으면 스키마 스크러버를 포함하는 다음 릴리스를 기다립니다.
2. anyOf/oneOf/allOf, patternProperties, additionalProperties, minLength, maxLength, format 등과 같은 지원되지 않는 키워드를 피합니다.
3. 커스텀 도구를 정의하는 경우 최상위 스키마를 type: "object"로 유지하고 properties 및 간단한 열거형을 사용합니다.

Tools 및 TypeBox schemas 참조.

macOS 특정 문제

App Crashes when Granting Permissions (Speech/Mic)

개인 정보 보호 프롬프트에서 "허용"을 클릭하면 앱이 사라지거나 "Abort trap 6"을 표시하는 경우:

수정 1: TCC 캐시 재설정

tccutil reset All bot.molt.mac.debug

수정 2: 새 Bundle ID 강제 재설정이 작동하지 않으면 scripts/package-mac-app.sh에서 BUNDLE_ID를 변경하고 (예: .test 접미사 추가) 재빌드합니다. 이렇게 하면 macOS가 새 앱으로 처리합니다.

Gateway stuck on "Starting..."

앱은 포트 18789의 로컬 gateway에 연결합니다. 계속 정지된 경우:

수정 1: Supervisor 중지 (선호) Gateway가 launchd에 의해 감독되는 경우 PID를 종료하면 다시 생성됩니다. 먼저 supervisor를 중지합니다:

openclaw gateway status
openclaw gateway stop
# Or: launchctl bootout gui/$UID/bot.molt.gateway (replace with bot.molt.<profile>; legacy com.openclaw.* still works)

수정 2: 포트가 바쁨 (리스너 찾기)

lsof -nP -iTCP:18789 -sTCP:LISTEN

감독되지 않은 프로세스인 경우 먼저 우아한 중지를 시도한 다음 에스컬레이션합니다:

kill -TERM <PID>
sleep 1
kill -9 <PID> # last resort

수정 3: CLI 설치 확인 전역 openclaw CLI가 설치되어 있고 앱 버전과 일치하는지 확인합니다:

openclaw --version
npm install -g openclaw@<version>

Debug Mode

verbose 로깅 가져오기:

# Turn on trace logging in config:
#   ${OPENCLAW_CONFIG_PATH:-$HOME/.openclaw/openclaw.json} -> { logging: { level: "trace" } }
#
# Then run verbose commands to mirror debug output to stdout:
openclaw gateway --verbose
openclaw channels login --verbose

Log Locations

Health Check

# Supervisor + probe target + config paths
openclaw gateway status
# Include system-level scans (legacy/extra services, port listeners)
openclaw gateway status --deep

# Is the gateway reachable?
openclaw health --json
# If it fails, rerun with connection details:
openclaw health --verbose

# Is something listening on the default port?
lsof -nP -iTCP:18789 -sTCP:LISTEN

# Recent activity (RPC log tail)
openclaw logs --follow
# Fallback if RPC is down
tail -20 /tmp/openclaw/openclaw-*.log

Reset Everything

핵 옵션:

openclaw gateway stop
# If you installed a service and want a clean install:
# openclaw gateway uninstall

trash "${OPENCLAW_STATE_DIR:-$HOME/.openclaw}"
openclaw channels login         # re-pair WhatsApp
openclaw gateway restart           # or: openclaw gateway

⚠️ 이렇게 하면 모든 세션이 손실되고 WhatsApp을 다시 페어링해야 합니다.

Getting Help

1. 먼저 로그 확인: /tmp/openclaw/ (기본값: openclaw-YYYY-MM-DD.log, 또는 설정된 logging.file)
2. GitHub에서 기존 이슈 검색
3. 다음 내용으로 새 이슈 열기:
   • OpenClaw 버전
   • 관련 로그 스니펫
   • 재현 단계
   • 설정 (비밀 수정!)

"껐다가 다시 켜보셨나요?" — 모든 IT 담당자

🦞🔧

Browser Not Starting (Linux)

"Failed to start Chrome CDP on port 18800"이 표시되는 경우:

가장 가능성 높은 원인: Ubuntu의 Snap 패키지 Chromium.

빠른 수정: 대신 Google Chrome을 설치합니다:

wget https://dl.google.com/linux/direct/google-chrome-stable_current_amd64.deb
sudo dpkg -i google-chrome-stable_current_amd64.deb

그런 다음 설정에서 설정합니다:

{
  "browser": {
    "executablePath": "/usr/bin/google-chrome-stable"
  }
}

전체 가이드: browser-linux-troubleshooting 참조