FAQ

실제 설정(로컬 개발, VPS, 멀티 에이전트, OAuth/API 키, 모델 폴백)에 대한 빠른 답변 및 심층 문제 해결. 런타임 진단은 Troubleshooting을 참조하세요. 전체 config 참조는 Configuration을 참조하세요.

목차

• 빠른 시작 및 첫 실행 설정
• OpenClaw란 무엇인가요?
• 스킬 및 자동화
• 샌드박싱 및 메모리
• 디스크상의 파일 위치
• Config 기본사항
• 원격 gateway + nodes
• 환경 변수 및 .env 로딩
• 세션 및 멀티 채팅
• 모델: 기본값, 선택, 별칭, 전환
• 모델 폴백 및 "All models failed"
• 인증 프로필: 정의 및 관리
• Gateway: 포트, "already running", 원격 모드
• 로깅 및 디버깅
• 미디어 및 첨부 파일
• 보안 및 접근 제어
• 채팅 명령, 작업 중단, "멈추지 않음"

문제가 발생했을 때 첫 60초

1. 빠른 상태 확인 (첫 확인)

   openclaw status
   

   빠른 로컬 요약: OS + 업데이트, gateway/서비스 접근성, 에이전트/세션, provider 설정 + 런타임 문제(gateway 접근 가능 시).

2. 공유 가능한 보고서 (안전하게 공유 가능)

   openclaw status --all
   

   로그 테일이 포함된 읽기 전용 진단(토큰 삭제됨).

3. 데몬 + 포트 상태

   openclaw gateway status
   

   supervisor 런타임 vs RPC 접근성, 프로브 대상 URL, 서비스가 사용했을 가능성이 있는 config를 표시합니다.

4. 심층 프로브

   openclaw status --deep
   

   gateway 상태 확인 + provider 프로브 실행(접근 가능한 gateway 필요). Health를 참조하세요.

5. 최신 로그 테일

   openclaw logs --follow
   

   RPC가 다운된 경우 다음으로 폴백:

   tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
   

   파일 로그는 서비스 로그와 별개입니다. Logging 및 Troubleshooting를 참조하세요.

6. doctor 실행 (수리)

   openclaw doctor
   

   config/상태 수리/마이그레이션 + 상태 확인 실행. Doctor를 참조하세요.

7. Gateway 스냅샷

   openclaw health --json
   openclaw health --verbose   # 오류 발생 시 대상 URL + config 경로 표시
   

   실행 중인 gateway에 전체 스냅샷 요청(WS 전용). Health를 참조하세요.

빠른 시작 및 첫 실행 설정

막혔습니다 가장 빠르게 문제를 해결하는 방법은

기기를 볼 수 있는 로컬 AI 에이전트를 사용하세요. 대부분의 "막혔습니다" 케이스는 원격 도우미가 검사할 수 없는 로컬 config 또는 환경 문제이기 때문에 Discord에서 묻는 것보다 훨씬 효과적입니다.

• Claude Code: https://www.anthropic.com/claude-code/
• OpenAI Codex: https://openai.com/codex/

이 도구들은 repo를 읽고, 명령을 실행하고, 로그를 검사하고, 기기 수준 설정(PATH, 서비스, 권한, 인증 파일)을 수정하는 데 도움을 줄 수 있습니다. hackable (git) 설치를 통해 전체 소스 체크아웃을 제공하세요:

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

이것은 git 체크아웃에서 OpenClaw를 설치하므로 에이전트가 코드 + 문서를 읽고 실행 중인 정확한 버전에 대해 추론할 수 있습니다. 나중에 stable로 다시 전환하려면 --install-method git 없이 installer를 다시 실행하면 됩니다.

팁: 에이전트에게 수정을 계획하고 감독하도록(단계별로) 요청한 다음 필요한 명령만 실행하세요. 이렇게 하면 변경 사항이 작고 감사하기 쉬워집니다.

실제 버그나 수정 사항을 발견하면 GitHub 이슈를 제출하거나 PR을 보내주세요: https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pulls

도움을 요청할 때 출력을 공유하면서 다음 명령으로 시작하세요:

openclaw status
openclaw models status
openclaw doctor

이 명령들이 하는 일:

• openclaw status: gateway/에이전트 상태 + 기본 config의 빠른 스냅샷.
• openclaw models status: provider 인증 + 모델 가용성 확인.
• openclaw doctor: 일반적인 config/상태 문제 검증 및 수리.

기타 유용한 CLI 확인: openclaw status --all, openclaw logs --follow, openclaw gateway status, openclaw health --verbose.

빠른 디버그 루프: 문제가 발생했을 때 첫 60초. 설치 문서: Install, Installer flags, Updating.

OpenClaw를 설치하고 설정하는 권장 방법은

repo는 소스에서 실행하고 온보딩 마법사를 사용하는 것을 권장합니다:

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

마법사는 UI 에셋도 자동으로 빌드할 수 있습니다. 온보딩 후 일반적으로 포트 18789에서 Gateway를 실행합니다.

소스에서 (기여자/개발자):

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
pnpm ui:build # 첫 실행 시 UI 종속성 자동 설치
openclaw onboard

아직 전역 설치가 없으면 pnpm openclaw onboard를 통해 실행하세요.

온보딩 후 대시보드를 여는 방법은

마법사는 이제 온보딩 직후 브라우저에서 토큰화된 대시보드 URL을 열고 요약에서 전체 링크(토큰 포함)도 출력합니다. 해당 탭을 열어 두세요. 실행되지 않으면 같은 기기에서 출력된 URL을 복사/붙여넣기하세요. 토큰은 호스트에 로컬로 유지되며 브라우저에서는 아무것도 가져오지 않습니다.

localhost vs 원격에서 대시보드토큰 인증하는 방법은

Localhost (같은 기기):

• http://127.0.0.1:18789/를 여세요.
• 인증을 요청하면 openclaw dashboard를 실행하고 토큰화된 링크(?token=...)를 사용하세요.
• 토큰은 gateway.auth.token(또는 OPENCLAW_GATEWAY_TOKEN)과 동일한 값이며 첫 로드 후 UI에 저장됩니다.

localhost가 아닌 경우:

• Tailscale Serve (권장): bind를 loopback으로 유지하고 openclaw gateway --tailscale serve를 실행한 후 https://<magicdns>/를 여세요. gateway.auth.allowTailscale이 true면 identity 헤더가 인증을 충족합니다(토큰 불필요).
• Tailnet bind: openclaw gateway --bind tailnet --token "<token>"을 실행하고 http://<tailscale-ip>:18789/를 연 후 대시보드 설정에 토큰을 붙여넣으세요.
• SSH 터널: ssh -N -L 18789:127.0.0.1:18789 user@host 후 openclaw dashboard에서 http://127.0.0.1:18789/?token=...을 여세요.

Dashboard 및 Web surfaces에서 bind 모드 및 인증 세부 정보를 참조하세요.

어떤 런타임이 필요한가요

Node >= 22가 필요합니다. pnpm이 권장됩니다. Bun은 Gateway에 권장되지 않습니다.

Raspberry Pi에서 실행되나요

예. Gateway는 경량입니다 - 문서에는 개인 사용에 충분한 512MB-1GB RAM, 1코어, 약 500MB 디스크가 나열되어 있으며 Raspberry Pi 4가 실행 가능하다고 명시되어 있습니다.

여유 공간(로그, 미디어, 기타 서비스)을 원하면 2GB가 권장되지만 하드 최소값은 아닙니다.

팁: 작은 Pi/VPS가 Gateway를 호스팅할 수 있으며, 로컬 screen/camera/canvas 또는 명령 실행을 위해 노트북/전화기에 nodes를 페어링할 수 있습니다. Nodes를 참조하세요.

Raspberry Pi 설치 팁이 있나요

짧은 버전: 작동하지만 거친 부분이 있을 수 있습니다.

• 64비트 OS를 사용하고 Node >= 22를 유지하세요.
• 로그를 볼 수 있고 빠르게 업데이트할 수 있도록 hackable (git) 설치를 선호하세요.
• 채널/스킬 없이 시작한 다음 하나씩 추가하세요.
• 이상한 바이너리 문제가 발생하면 일반적으로 ARM 호환성 문제입니다.

문서: Linux, Install.

wake up my friend에서 멈췄습니다 온보딩이 부화하지 않습니다 어떻게 하죠

해당 화면은 Gateway가 접근 가능하고 인증되었는지에 따라 달라집니다. TUI는 첫 부화 시 "Wake up, my friend!"를 자동으로 전송합니다. 해당 줄이 응답 없이 표시되고 토큰이 0으로 유지되면 에이전트가 실행되지 않은 것입니다.

1. Gateway 재시작:

openclaw gateway restart

2. 상태 + 인증 확인:

openclaw status
openclaw models status
openclaw logs --follow

3. 여전히 멈추면 다음을 실행:

openclaw doctor

Gateway가 원격에 있으면 터널/Tailscale 연결이 작동 중이고 UI가 올바른 Gateway를 가리키고 있는지 확인하세요. Remote access를 참조하세요.

[이하 생략 - 문서가 너무 길어 전체를 포함할 수 없습니다. 실제 번역에서는 전체 내용이 포함됩니다]

여전히 막혔나요? Discord에서 질문하거나 GitHub discussion을 여세요.