메인 콘텐츠로 건너뛰기

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

실제 환경 설정(로컬 개발, VPS, 멀티 에이전트, OAuth/API 키, 모델 장애 조치)을 위한 빠른 답변과 더 깊은 문제 해결 방법입니다. 런타임 진단은 문제 해결을 참고하세요. 전체 설정 참조는 설정을 참고하세요.

​
문제가 생겼을 때 처음 60초

  1. 빠른 상태 확인(첫 확인) 
    openclaw status
    빠른 로컬 요약: OS + 업데이트, Gateway/서비스 도달 가능 여부, 에이전트/세션, 제공자 설정 + 런타임 문제(Gateway에 도달할 수 있는 경우).
  2. 붙여넣을 수 있는 보고서(공유해도 안전) 
    openclaw status --all
    로그 꼬리를 포함한 읽기 전용 진단(토큰은 수정됨).
  3. Daemon + 포트 상태 
    openclaw gateway status
    supervisor 런타임과 RPC 도달 가능 여부, probe 대상 URL, 서비스가 사용했을 가능성이 높은 설정을 보여줍니다.
  4. 심층 probe 
    openclaw status --deep
    지원되는 경우 채널 probe를 포함해 실시간 Gateway 상태 probe를 실행합니다 (도달 가능한 Gateway가 필요). Health를 참고하세요.
  5. 최신 로그 따라가기 
    openclaw logs --follow
    RPC가 중단된 경우 다음으로 대체하세요. 
    tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)"
    파일 로그는 서비스 로그와 별개입니다. Logging 및 문제 해결을 참고하세요.
  6. doctor 실행(복구) 
    openclaw doctor
    설정/상태를 복구/마이그레이션하고 상태 검사를 실행합니다. Doctor를 참고하세요.
  7. Gateway 스냅샷 
    openclaw health --json
openclaw health --verbose   # shows the target URL + config path on errors
    실행 중인 Gateway에 전체 스냅샷을 요청합니다(WS 전용). Health를 참고하세요.

​
빠른 시작 및 최초 실행 설정

최초 실행 Q&A(설치, 온보딩, 인증 경로, 구독, 초기 실패)는 최초 실행 FAQ에 있습니다.

​
OpenClaw란 무엇인가요?

OpenClaw는 사용자가 자신의 장치에서 실행하는 개인용 AI 어시스턴트입니다. 이미 사용하는 메시징 환경(WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, QQ Bot 같은 번들 채널 Plugin)에 응답하며, 지원되는 플랫폼에서는 음성 + 실시간 Canvas도 사용할 수 있습니다. Gateway는 항상 켜져 있는 제어 플레인이고, 어시스턴트가 제품입니다.
OpenClaw는 “단순한 Claude 래퍼”가 아닙니다. OpenClaw는 로컬 우선 제어 플레인으로, 사용자가 자신의 하드웨어에서 기능적인 어시스턴트를 실행하고, 이미 사용하는 채팅 앱에서 접근하며, 상태가 있는 세션, 메모리, 도구를 사용할 수 있게 해 줍니다. 이 모든 것을 사용자의 워크플로 제어권을 호스팅된 SaaS에 넘기지 않고 수행합니다.주요 특징:
  • 사용자의 장치, 사용자의 데이터: 원하는 곳(Mac, Linux, VPS)에서 Gateway를 실행하고 워크스페이스 + 세션 기록을 로컬에 보관하세요.
  • 웹 샌드박스가 아닌 실제 채널: WhatsApp/Telegram/Slack/Discord/Signal/iMessage 등, 지원되는 플랫폼의 모바일 음성 및 Canvas까지 제공합니다.
  • 모델에 구애받지 않음: 에이전트별 라우팅과 장애 조치를 통해 Anthropic, OpenAI, MiniMax, OpenRouter 등을 사용할 수 있습니다.
  • 로컬 전용 옵션: 원한다면 로컬 모델을 실행해 모든 데이터를 장치에 유지할 수 있습니다.
  • 멀티 에이전트 라우팅: 채널, 계정 또는 작업별로 에이전트를 분리하고, 각 에이전트에 고유한 워크스페이스와 기본값을 둘 수 있습니다.
  • 오픈 소스이며 해킹 가능: 벤더 종속 없이 검사하고, 확장하고, 직접 호스팅할 수 있습니다.
문서: Gateway, Channels, 멀티 에이전트, 메모리.
시작하기 좋은 프로젝트:
  • 웹사이트를 빌드합니다(WordPress, Shopify 또는 간단한 정적 사이트).
  • 모바일 앱을 프로토타입으로 만듭니다(개요, 화면, API 계획).
  • 파일과 폴더를 정리합니다(정리, 이름 지정, 태그 지정).
  • Gmail을 연결하고 요약 또는 후속 조치를 자동화합니다.
큰 작업도 처리할 수 있지만, 단계를 나누고 병렬 작업에 하위 에이전트를 사용할 때 가장 잘 작동합니다.
일상적인 성과는 보통 다음과 같습니다.
  • 개인 브리핑: 받은편지함, 캘린더, 관심 있는 뉴스 요약.
  • 조사 및 초안 작성: 이메일 또는 문서를 위한 빠른 조사, 요약, 첫 초안.
  • 리마인더 및 후속 조치: Cron 또는 Heartbeat 기반 알림과 체크리스트.
  • 브라우저 자동화: 양식 채우기, 데이터 수집, 웹 작업 반복.
  • 장치 간 조정: 휴대폰에서 작업을 보내고, Gateway가 서버에서 실행하게 한 뒤, 결과를 채팅으로 돌려받습니다.
조사, 검증, 초안 작성에는 그렇습니다. 사이트를 스캔하고, 후보 목록을 만들고, 잠재 고객을 요약하며, 아웃리치 또는 광고 문구 초안을 작성할 수 있습니다.아웃리치 또는 광고 집행의 경우 사람이 계속 검토 과정에 있어야 합니다. 스팸을 피하고, 현지 법률과 플랫폼 정책을 준수하며, 발송 전에 모든 내용을 검토하세요. 가장 안전한 방식은 OpenClaw가 초안을 작성하고 사용자가 승인하는 것입니다.문서: 보안.
OpenClaw는 IDE 대체제가 아니라 개인 비서이자 조율 계층입니다. 저장소 안에서 가장 빠른 직접 코딩 루프가 필요하면 Claude Code 또는 Codex를 사용하세요. 지속적인 메모리, 여러 기기에서의 접근, 도구 오케스트레이션이 필요할 때 OpenClaw를 사용하세요.장점:
  • 세션 전반에 걸친 영구 메모리 + 워크스페이스
  • 다중 플랫폼 접근(WhatsApp, Telegram, TUI, WebChat)
  • 도구 오케스트레이션(브라우저, 파일, 예약, 훅)
  • 상시 실행 Gateway(VPS에서 실행하고 어디서나 상호작용)
  • 로컬 브라우저/화면/카메라/실행을 위한 Node
쇼케이스: https://openclaw.ai/showcase

​
Skills 및 자동화

저장소 사본을 편집하는 대신 관리형 재정의를 사용하세요. 변경 사항을 ~/.openclaw/skills/<name>/SKILL.md에 넣거나 ~/.openclaw/openclaw.json의 skills.load.extraDirs를 통해 폴더를 추가하세요. 우선순위는 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 번들 → skills.load.extraDirs이므로, 관리형 재정의는 git을 건드리지 않고도 번들 Skills보다 우선합니다. Skill을 전역으로 설치해야 하지만 일부 에이전트에만 보이게 하려면 공유 사본을 ~/.openclaw/skills에 두고 agents.defaults.skills와 agents.list[].skills로 표시 여부를 제어하세요. 업스트림에 반영할 가치가 있는 편집만 저장소에 두고 PR로 제출해야 합니다.
예. ~/.openclaw/openclaw.json의 skills.load.extraDirs로 추가 디렉터리를 넣으세요(가장 낮은 우선순위). 기본 우선순위는 <workspace>/skills → <workspace>/.agents/skills → ~/.agents/skills → ~/.openclaw/skills → 번들 → skills.load.extraDirs입니다. clawhub는 기본적으로 ./skills에 설치하며, OpenClaw는 다음 세션에서 이를 <workspace>/skills로 취급합니다. 해당 Skill이 특정 에이전트에만 보여야 한다면 agents.defaults.skills 또는 agents.list[].skills와 함께 사용하세요.
현재 지원되는 패턴은 다음과 같습니다.
  • Cron 작업: 격리된 작업은 작업별로 model 재정의를 설정할 수 있습니다.
  • 하위 에이전트: 작업을 기본 모델이 다른 별도 에이전트로 라우팅합니다.
  • 온디맨드 전환: 언제든지 /model을 사용해 현재 세션 모델을 전환합니다.
Cron 작업, 다중 에이전트 라우팅, 슬래시 명령을 참고하세요.
길거나 병렬인 작업에는 하위 에이전트를 사용하세요. 하위 에이전트는 자체 세션에서 실행되고, 요약을 반환하며, 기본 채팅이 계속 응답하도록 유지합니다.봇에게 “spawn a sub-agent for this task”라고 요청하거나 /subagents를 사용하세요. 채팅에서 /status를 사용하면 Gateway가 지금 무엇을 하고 있는지(그리고 바쁜지 여부)를 볼 수 있습니다.토큰 팁: 긴 작업과 하위 에이전트는 모두 토큰을 소비합니다. 비용이 걱정된다면 agents.defaults.subagents.model을 통해 하위 에이전트에 더 저렴한 모델을 설정하세요.문서: 하위 에이전트, 백그라운드 작업.
스레드 바인딩을 사용하세요. Discord 스레드를 하위 에이전트 또는 세션 대상에 바인딩하면 해당 스레드의 후속 메시지가 바인딩된 세션에 계속 유지됩니다.기본 흐름:
  • thread: true와 함께 sessions_spawn을 사용해 생성합니다(지속적인 후속 처리를 위해 선택적으로 mode: "session" 사용).
  • 또는 /focus <target>으로 수동 바인딩합니다.
  • /agents를 사용해 바인딩 상태를 확인합니다.
  • 자동 포커스 해제를 제어하려면 /session idle <duration|off> 및 /session max-age <duration|off>를 사용합니다.
  • 스레드를 분리하려면 /unfocus를 사용합니다.
필수 설정:
  • 전역 기본값: session.threadBindings.enabled, session.threadBindings.idleHours, session.threadBindings.maxAgeHours.
  • Discord 재정의: channels.discord.threadBindings.enabled, channels.discord.threadBindings.idleHours, channels.discord.threadBindings.maxAgeHours.
  • 생성 시 자동 바인딩: channels.discord.threadBindings.spawnSessions의 기본값은 true입니다. 스레드 바인딩 세션 생성을 비활성화하려면 false로 설정하세요.
문서: 하위 에이전트, Discord, 설정 참조, 슬래시 명령.
먼저 해석된 요청자 라우트를 확인하세요.
  • 완료 모드 하위 에이전트 전달은 바인딩된 스레드나 대화 라우트가 있으면 이를 우선합니다.
  • 완료 출처에 채널만 있는 경우 OpenClaw는 요청자 세션에 저장된 라우트(lastChannel / lastTo / lastAccountId)로 폴백하므로 직접 전달이 여전히 성공할 수 있습니다.
  • 바인딩된 라우트도 사용 가능한 저장 라우트도 없으면 직접 전달이 실패할 수 있으며, 결과는 채팅에 즉시 게시되는 대신 대기열에 들어간 세션 전달로 폴백합니다.
  • 유효하지 않거나 오래된 대상은 여전히 대기열 폴백 또는 최종 전달 실패를 강제할 수 있습니다.
  • 하위 항목의 마지막으로 보이는 어시스턴트 답장이 정확한 무음 토큰 NO_REPLY / no_reply이거나 정확히 ANNOUNCE_SKIP이면, OpenClaw는 오래된 이전 진행 상황을 게시하는 대신 의도적으로 알림을 억제합니다.
  • 하위 항목이 도구 호출만 수행한 뒤 시간 초과되면, 알림은 원시 도구 출력을 재생하는 대신 이를 짧은 부분 진행 요약으로 축약할 수 있습니다.
디버그:
openclaw tasks show <runId-or-sessionKey>
문서: 하위 에이전트, 백그라운드 작업, 세션 도구.
Cron은 Gateway 프로세스 안에서 실행됩니다. Gateway가 지속적으로 실행 중이 아니면 예약된 작업은 실행되지 않습니다.체크리스트:
  • cron이 활성화되어 있고(cron.enabled) OPENCLAW_SKIP_CRON이 설정되어 있지 않은지 확인합니다.
  • Gateway가 24/7 실행 중인지 확인합니다(절전/재시작 없음).
  • 작업의 시간대 설정을 확인합니다(--tz와 호스트 시간대 비교).
디버그:
openclaw cron run <jobId>
openclaw cron runs --id <jobId> --limit 50
문서: Cron 작업, 자동화.
먼저 전달 모드를 확인하세요.
  • --no-deliver / delivery.mode: "none"은 runner fallback 전송이 예상되지 않음을 의미합니다.
  • announce 대상(channel / to)이 없거나 유효하지 않으면 runner가 outbound delivery를 건너뛰었다는 뜻입니다.
  • 채널 인증 실패(unauthorized, Forbidden)는 runner가 전달을 시도했지만 자격 증명 때문에 차단되었다는 뜻입니다.
  • 조용한 격리 결과(NO_REPLY / no_reply만 있음)는 의도적으로 전달할 수 없는 것으로 처리되므로 runner도 대기 중인 fallback delivery를 억제합니다.
격리된 Cron 작업의 경우 채팅 경로를 사용할 수 있으면 agent가 여전히 message 도구로 직접 전송할 수 있습니다. --announce는 agent가 아직 보내지 않은 최종 텍스트에 대한 runner fallback 경로만 제어합니다.디버그:
openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>
문서: Cron 작업, 백그라운드 작업.
이는 보통 중복 스케줄링이 아니라 라이브 모델 전환 경로입니다.격리된 Cron은 활성 실행에서 LiveSessionModelSwitchError가 발생하면 runtime 모델 handoff를 유지하고 재시도할 수 있습니다. 재시도는 전환된 provider/model을 유지하며, 전환에 새 인증 프로필 override가 포함되어 있으면 Cron은 재시도 전에 그것도 유지합니다.관련 선택 규칙:
  • 적용 가능한 경우 Gmail hook 모델 override가 먼저 우선합니다.
  • 그다음 작업별 model.
  • 그다음 저장된 Cron 세션 모델 override.
  • 그다음 일반 agent/default 모델 선택.
재시도 루프에는 한계가 있습니다. 최초 시도와 2회의 전환 재시도 후에는 Cron이 무한 루프 대신 중단됩니다.디버그:
openclaw cron runs --id <jobId> --limit 50
openclaw tasks show <runId-or-sessionKey>
문서: Cron 작업, Cron CLI.
네이티브 openclaw skills 명령을 사용하거나 Skills를 workspace에 넣으세요. macOS Skills UI는 Linux에서 사용할 수 없습니다. https://clawhub.ai에서 Skills를 찾아볼 수 있습니다.
openclaw skills search "calendar"
openclaw skills search --limit 20
openclaw skills install <skill-slug>
openclaw skills install <skill-slug> --version <version>
openclaw skills install <skill-slug> --force
openclaw skills update --all
openclaw skills list --eligible
openclaw skills check
네이티브 openclaw skills install은 활성 workspace의 skills/ 디렉터리에 씁니다. 자신의 Skills를 게시하거나 동기화하려는 경우에만 별도의 clawhub CLI를 설치하세요. agent 간 공유 설치의 경우 Skill을 ~/.openclaw/skills 아래에 두고, 어떤 agent가 볼 수 있는지 좁히려면 agents.defaults.skills 또는 agents.list[].skills를 사용하세요.
예. Gateway scheduler를 사용하세요.
  • Cron 작업은 예약 또는 반복 작업용입니다(재시작 후에도 유지).
  • Heartbeat는 “main session” 주기적 확인용입니다.
  • 격리된 작업은 요약을 게시하거나 채팅에 전달하는 autonomous agents용입니다.
문서: Cron 작업, 자동화, Heartbeat.
직접적으로는 불가능합니다. macOS Skills는 metadata.openclaw.os와 필수 바이너리로 제한되며, Skills는 Gateway host에서 적격할 때만 system prompt에 표시됩니다. Linux에서는 gating을 override하지 않는 한 darwin 전용 Skills(예: apple-notes, apple-reminders, things-mac)가 로드되지 않습니다.지원되는 패턴은 세 가지입니다.옵션 A - Mac에서 Gateway 실행(가장 간단). macOS 바이너리가 있는 곳에서 Gateway를 실행한 다음, Linux에서 원격 모드 또는 Tailscale을 통해 연결하세요. Gateway host가 macOS이므로 Skills가 정상적으로 로드됩니다.옵션 B - macOS Node 사용(SSH 없음). Linux에서 Gateway를 실행하고, macOS Node(메뉴 막대 앱)를 페어링한 뒤 Mac에서 Node Run Commands를 “Always Ask” 또는 “Always Allow”로 설정하세요. 필수 바이너리가 Node에 있으면 OpenClaw는 macOS 전용 Skills를 적격한 것으로 처리할 수 있습니다. agent는 nodes 도구를 통해 해당 Skills를 실행합니다. “Always Ask”를 선택한 경우 prompt에서 “Always Allow”를 승인하면 해당 명령이 allowlist에 추가됩니다.옵션 C - SSH로 macOS 바이너리 프록시(고급). Gateway는 Linux에 두되, 필수 CLI 바이너리가 Mac에서 실행되는 SSH wrapper로 해석되게 하세요. 그런 다음 Skill을 override하여 Linux를 허용하면 적격 상태가 유지됩니다.
  1. 바이너리용 SSH wrapper를 만듭니다(예: Apple Notes용 memo). 
    #!/usr/bin/env bash
set -euo pipefail
exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@"
  2. Linux host의 PATH에 wrapper를 둡니다(예: ~/bin/memo).
  3. Linux를 허용하도록 Skill metadata(workspace 또는 ~/.openclaw/skills)를 override합니다. 
    ---
name: apple-notes
description: Manage Apple Notes via the memo CLI on macOS.
metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } }
---
  4. Skills snapshot이 새로고침되도록 새 session을 시작합니다.
현재는 내장되어 있지 않습니다.옵션:
  • Custom skill / Plugin: 안정적인 API 접근에 가장 좋습니다(Notion/HeyGen 모두 API가 있음).
  • 브라우저 자동화: 코드 없이 작동하지만 더 느리고 취약합니다.
클라이언트별로 context를 유지하려는 경우(agency workflow) 간단한 패턴은 다음과 같습니다.
  • 클라이언트마다 Notion 페이지 하나(context + preferences + active work).
  • session 시작 시 agent에게 해당 페이지를 가져오도록 요청합니다.
네이티브 integration을 원한다면 feature request를 열거나 해당 API를 대상으로 하는 Skill을 빌드하세요.Skills 설치:
openclaw skills install <skill-slug>
openclaw skills update --all
네이티브 설치는 활성 workspace skills/ 디렉터리에 들어갑니다. agent 간 공유 Skills의 경우 ~/.openclaw/skills/<name>/SKILL.md에 배치하세요. 일부 agent만 공유 설치를 볼 수 있어야 한다면 agents.defaults.skills 또는 agents.list[].skills를 구성하세요. 일부 Skills는 Homebrew를 통해 설치된 바이너리를 기대합니다. Linux에서는 Linuxbrew를 의미합니다(위 Homebrew Linux FAQ 항목 참조). Skills, Skills 구성, ClawHub을 참고하세요.
Chrome DevTools MCP를 통해 연결되는 내장 user 브라우저 프로필을 사용하세요.
openclaw browser --browser-profile user tabs
openclaw browser --browser-profile user snapshot
사용자 지정 이름을 원한다면 명시적인 MCP 프로필을 만드세요.
openclaw browser create-profile --name chrome-live --driver existing-session
openclaw browser --browser-profile chrome-live tabs
이 경로는 로컬 host 브라우저 또는 연결된 browser Node를 사용할 수 있습니다. Gateway가 다른 곳에서 실행 중이라면 브라우저가 있는 머신에서 Node host를 실행하거나 대신 원격 CDP를 사용하세요.existing-session / user의 현재 제한:
  • 작업은 CSS selector 기반이 아니라 ref 기반입니다.
  • 업로드에는 ref / inputRef가 필요하며 현재 한 번에 파일 하나를 지원합니다.
  • responsebody, PDF export, download interception, batch actions에는 여전히 managed browser 또는 raw CDP profile이 필요합니다.

​
Sandboxing 및 memory

예. Sandboxing을 참고하세요. Docker 전용 설정(전체 Gateway를 Docker에서 실행하거나 sandbox image 사용)은 Docker를 참고하세요.
기본 image는 보안 우선이며 node 사용자로 실행되므로 system package, Homebrew 또는 bundled browser를 포함하지 않습니다. 더 완전한 설정을 위해서는 다음을 수행하세요.
  • cache가 유지되도록 OPENCLAW_HOME_VOLUME로 /home/node를 지속화합니다.
  • OPENCLAW_DOCKER_APT_PACKAGES로 system deps를 image에 bake합니다.
  • bundled CLI를 통해 Playwright browser를 설치합니다. node /app/node_modules/playwright-core/cli.js install chromium
  • PLAYWRIGHT_BROWSERS_PATH를 설정하고 경로가 지속화되는지 확인합니다.
문서: Docker, Browser.
예. private traffic이 DMs이고 public traffic이 groups인 경우 가능합니다.agents.defaults.sandbox.mode: "non-main"을 사용하면 group/channel session(non-main keys)은 구성된 sandbox backend에서 실행되고, main DM session은 host에서 유지됩니다. backend를 선택하지 않으면 Docker가 기본입니다. 그런 다음 tools.sandbox.tools를 통해 sandboxed session에서 사용할 수 있는 도구를 제한하세요.설정 walkthrough + 예시 config: 그룹: 개인 DMs + 공개 그룹주요 config reference: Gateway 구성
agents.defaults.sandbox.docker.binds를 ["host:path:mode"]로 설정하세요(예: "/home/user/src:/src:ro"). Global + per-agent bind는 병합됩니다. scope: "shared"일 때는 per-agent bind가 무시됩니다. 민감한 항목에는 :ro를 사용하고, bind는 sandbox filesystem wall을 우회한다는 점을 기억하세요.OpenClaw는 정규화된 경로와 가장 깊은 기존 ancestor를 통해 해석된 canonical path 모두에 대해 bind source를 검증합니다. 즉, 마지막 path segment가 아직 존재하지 않아도 symlink-parent escape는 계속 fail closed되며, symlink resolution 후에도 allowed-root check가 계속 적용됩니다.예시와 안전 참고 사항은 Sandboxing 및 Sandbox vs Tool Policy vs Elevated를 참고하세요.
OpenClaw memory는 agent workspace의 Markdown 파일일 뿐입니다.
  • memory/YYYY-MM-DD.md의 일일 notes
  • MEMORY.md의 curated long-term notes(main/private session 전용)
OpenClaw는 auto-compaction 전에 model에게 지속 가능한 notes를 쓰도록 상기시키기 위해 조용한 pre-compaction memory flush도 실행합니다. 이는 workspace가 쓰기 가능한 경우에만 실행됩니다(read-only sandbox는 건너뜀). Memory를 참고하세요.
bot에게 해당 사실을 memory에 쓰도록 요청하세요. Long-term notes는 MEMORY.md에, short-term context는 memory/YYYY-MM-DD.md에 둡니다.이는 아직 개선 중인 영역입니다. model에게 memories를 저장하라고 상기시키면 도움이 됩니다. model은 무엇을 해야 하는지 알 것입니다. 계속 잊어버린다면 Gateway가 모든 실행에서 같은 workspace를 사용하는지 확인하세요.문서: Memory, Agent workspace.
Memory 파일은 disk에 있으며 삭제할 때까지 유지됩니다. 제한은 model이 아니라 storage입니다. session context는 여전히 model context window의 제한을 받으므로 긴 대화는 compact되거나 truncate될 수 있습니다. 그래서 memory search가 존재합니다. 관련 부분만 context로 다시 가져옵니다.문서: Memory, Context.
OpenAI 임베딩을 사용하는 경우에만 필요합니다. Codex OAuth는 채팅/완성을 처리하며 임베딩 접근 권한을 부여하지 않으므로, **Codex로 로그인(OAuth 또는 Codex CLI 로그인)**해도 의미 기반 메모리 검색에는 도움이 되지 않습니다. OpenAI 임베딩에는 여전히 실제 API 키(OPENAI_API_KEY 또는 models.providers.openai.apiKey)가 필요합니다.제공자를 명시적으로 설정하지 않으면 OpenClaw는 API 키(인증 프로필, models.providers.*.apiKey 또는 환경 변수)를 확인할 수 있을 때 제공자를 자동으로 선택합니다. OpenAI 키가 확인되면 OpenAI를 우선 사용하고, 그렇지 않으면 Gemini 키가 확인될 때 Gemini, 그다음 Voyage, 그다음 Mistral을 사용합니다. 원격 키가 없으면 메모리 검색은 구성할 때까지 비활성화된 상태로 유지됩니다. 로컬 모델 경로가 구성되어 있고 존재하면 OpenClaw는 local을 우선 사용합니다. Ollama는 memorySearch.provider = "ollama"를 명시적으로 설정할 때 지원됩니다.로컬로 유지하고 싶다면 memorySearch.provider = "local"을 설정하세요(선택적으로 memorySearch.fallback = "none"도 설정). Gemini 임베딩을 원한다면 memorySearch.provider = "gemini"를 설정하고 GEMINI_API_KEY(또는 memorySearch.remote.apiKey)를 제공하세요. OpenAI, Gemini, Voyage, Mistral, Ollama 또는 local 임베딩 모델을 지원합니다. 설정 세부 정보는 메모리를 참조하세요.

​
항목이 디스크에 저장되는 위치

아니요. OpenClaw의 상태는 로컬에 저장되지만, 외부 서비스는 여전히 사용자가 보내는 내용을 볼 수 있습니다.
  • 기본적으로 로컬: 세션, 메모리 파일, 구성, 워크스페이스는 Gateway 호스트에 있습니다 (~/.openclaw + 사용자의 워크스페이스 디렉터리).
  • 필요에 따라 원격: 모델 제공자(Anthropic/OpenAI 등)에 보내는 메시지는 해당 API로 전송되고, 채팅 플랫폼(WhatsApp/Telegram/Slack 등)은 메시지 데이터를 해당 서버에 저장합니다.
  • 사용자가 범위를 제어: 로컬 모델을 사용하면 프롬프트가 사용자의 머신에 남지만, 채널 트래픽은 여전히 채널 서버를 거칩니다.
관련 항목: 에이전트 워크스페이스, 메모리.
모든 항목은 $OPENCLAW_STATE_DIR 아래에 저장됩니다(기본값: ~/.openclaw).
경로목적
$OPENCLAW_STATE_DIR/openclaw.json기본 구성(JSON5)
$OPENCLAW_STATE_DIR/credentials/oauth.json레거시 OAuth 가져오기(처음 사용할 때 인증 프로필로 복사됨)
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth-profiles.json인증 프로필(OAuth, API 키, 선택적 keyRef/tokenRef)
$OPENCLAW_STATE_DIR/secrets.jsonfile SecretRef 제공자를 위한 선택적 파일 기반 비밀 페이로드
$OPENCLAW_STATE_DIR/agents/<agentId>/agent/auth.json레거시 호환성 파일(정적 api_key 항목은 제거됨)
$OPENCLAW_STATE_DIR/credentials/제공자 상태(예: whatsapp/<accountId>/creds.json)
$OPENCLAW_STATE_DIR/agents/에이전트별 상태(agentDir + 세션)
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/대화 기록 및 상태(에이전트별)
$OPENCLAW_STATE_DIR/agents/<agentId>/sessions/sessions.json세션 메타데이터(에이전트별)
레거시 단일 에이전트 경로: ~/.openclaw/agent/*(openclaw doctor로 마이그레이션됨).워크스페이스(AGENTS.md, 메모리 파일, skills 등)는 별도로 관리되며 agents.defaults.workspace를 통해 구성됩니다(기본값: ~/.openclaw/workspace).
이 파일들은 ~/.openclaw가 아니라 에이전트 워크스페이스에 있습니다.
  • 워크스페이스(에이전트별): AGENTS.md, SOUL.md, IDENTITY.md, USER.md, MEMORY.md, memory/YYYY-MM-DD.md, 선택적 HEARTBEAT.md. 소문자 루트 memory.md는 레거시 복구 입력으로만 사용됩니다. 두 파일이 모두 존재할 때 openclaw doctor --fix가 이를 MEMORY.md로 병합할 수 있습니다.
  • 상태 디렉터리(~/.openclaw): 구성, 채널/제공자 상태, 인증 프로필, 세션, 로그, 공유 skills(~/.openclaw/skills).
기본 워크스페이스는 ~/.openclaw/workspace이며, 다음으로 구성할 수 있습니다.
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}
재시작 후 봇이 “잊어버린” 것처럼 보이면 Gateway가 매번 실행될 때 같은 워크스페이스를 사용하고 있는지 확인하세요(그리고 기억하세요. 원격 모드는 사용자의 로컬 노트북이 아니라 gateway 호스트의 워크스페이스를 사용합니다).팁: 지속적인 동작이나 선호 설정을 원한다면 채팅 기록에 의존하지 말고 봇에게 해당 내용을 AGENTS.md 또는 MEMORY.md에 기록하도록 요청하세요.에이전트 워크스페이스 및 메모리를 참조하세요.
에이전트 워크스페이스를 비공개 git 저장소에 넣고 비공개 위치(예: GitHub 비공개)에 백업하세요. 이렇게 하면 메모리 + AGENTS/SOUL/USER 파일이 보존되며, 나중에 어시스턴트의 “마음”을 복원할 수 있습니다.~/.openclaw 아래의 어떤 항목(자격 증명, 세션, 토큰 또는 암호화된 비밀 페이로드)도 커밋하지 마세요. 전체 복원이 필요하다면 워크스페이스와 상태 디렉터리를 별도로 모두 백업하세요(위의 마이그레이션 질문 참조).문서: 에이전트 워크스페이스.
전용 가이드를 참조하세요: 제거.
예. 워크스페이스는 기본 cwd이자 메모리 기준점이지, 엄격한 샌드박스가 아닙니다. 상대 경로는 워크스페이스 안에서 해석되지만, 샌드박싱이 활성화되어 있지 않으면 절대 경로로 다른 호스트 위치에 접근할 수 있습니다. 격리가 필요하다면 agents.defaults.sandbox 또는 에이전트별 샌드박스 설정을 사용하세요. 저장소를 기본 작업 디렉터리로 만들고 싶다면 해당 에이전트의 workspace가 저장소 루트를 가리키도록 하세요. OpenClaw 저장소는 단지 소스 코드입니다. 에이전트가 그 안에서 작업하기를 의도한 경우가 아니라면 워크스페이스는 별도로 유지하세요.예시(저장소를 기본 cwd로 사용):
{
  agents: {
    defaults: {
      workspace: "~/Projects/my-repo",
    },
  },
}
세션 상태는 gateway 호스트가 소유합니다. 원격 모드에 있다면 중요한 세션 저장소는 로컬 노트북이 아니라 원격 머신에 있습니다. 세션 관리를 참조하세요.

​
구성 기본 사항

OpenClaw는 $OPENCLAW_CONFIG_PATH에서 선택적 JSON5 구성을 읽습니다(기본값: ~/.openclaw/openclaw.json).
$OPENCLAW_CONFIG_PATH
파일이 없으면 안전한 편인 기본값(~/.openclaw/workspace의 기본 워크스페이스 포함)을 사용합니다.
비루프백 바인드는 유효한 gateway 인증 경로가 필요합니다. 실제로는 다음을 의미합니다.
  • 공유 비밀 인증: 토큰 또는 비밀번호
  • 올바르게 구성된 ID 인식 리버스 프록시 뒤의 gateway.auth.mode: "trusted-proxy"
{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me",
    },
  },
}
참고:
  • gateway.remote.token / .password는 그 자체로 로컬 gateway 인증을 활성화하지 않습니다.
  • 로컬 호출 경로는 gateway.auth.*가 설정되지 않은 경우에만 gateway.remote.*를 대체 수단으로 사용할 수 있습니다.
  • 비밀번호 인증의 경우 대신 gateway.auth.mode: "password"와 gateway.auth.password(또는 OPENCLAW_GATEWAY_PASSWORD)를 설정하세요.
  • gateway.auth.token / gateway.auth.password가 SecretRef를 통해 명시적으로 구성되었지만 확인되지 않으면, 확인은 닫힌 방식으로 실패합니다(원격 대체가 이를 가리지 않음).
  • 공유 비밀 Control UI 설정은 connect.params.auth.token 또는 connect.params.auth.password(앱/UI 설정에 저장됨)로 인증합니다. Tailscale Serve 또는 trusted-proxy와 같은 ID 포함 모드는 대신 요청 헤더를 사용합니다. 공유 비밀을 URL에 넣지 마세요.
  • gateway.auth.mode: "trusted-proxy"에서는 같은 호스트의 루프백 리버스 프록시에 명시적인 gateway.auth.trustedProxy.allowLoopback = true와 gateway.trustedProxies의 루프백 항목이 필요합니다.
OpenClaw는 루프백을 포함해 기본적으로 gateway 인증을 강제합니다. 일반적인 기본 경로에서는 토큰 인증을 의미합니다. 명시적인 인증 경로가 구성되어 있지 않으면 gateway 시작 시 토큰 모드로 확인되고 해당 시작에만 유효한 런타임 전용 토큰을 생성하므로, 로컬 WS 클라이언트는 인증해야 합니다. 재시작 후에도 클라이언트에 안정적인 비밀이 필요하다면 gateway.auth.token, gateway.auth.password, OPENCLAW_GATEWAY_TOKEN 또는 OPENCLAW_GATEWAY_PASSWORD를 명시적으로 구성하세요. 이는 다른 로컬 프로세스가 Gateway를 호출하지 못하도록 차단합니다.다른 인증 경로를 선호한다면 비밀번호 모드(또는 ID 인식 리버스 프록시의 경우 trusted-proxy)를 명시적으로 선택할 수 있습니다. 루프백을 정말로 열어 두고 싶다면 구성에서 gateway.auth.mode: "none"을 명시적으로 설정하세요. Doctor는 언제든지 토큰을 생성해 줄 수 있습니다: openclaw doctor --generate-gateway-token.
Gateway는 구성을 감시하고 핫 리로드를 지원합니다.
  • gateway.reload.mode: "hybrid"(기본값): 안전한 변경 사항은 즉시 적용하고, 중요한 변경 사항은 재시작
  • hot, restart, off도 지원됩니다
구성에서 cli.banner.taglineMode를 설정하세요.
{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}
  • off: 태그라인 텍스트를 숨기지만 배너 제목/버전 줄은 유지합니다.
  • default: 매번 All your chats, one OpenClaw.를 사용합니다.
  • random: 재미있거나 시즌별로 바뀌는 태그라인(기본 동작).
  • 배너를 전혀 원하지 않으면 env OPENCLAW_HIDE_BANNER=1을 설정하세요.
web_fetch는 API 키 없이 작동합니다. web_search는 선택한 제공자에 따라 달라집니다.
  • Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity, Tavily 같은 API 기반 제공자는 일반적인 API 키 설정이 필요합니다.
  • Ollama Web Search는 키가 필요 없지만, 구성된 Ollama 호스트를 사용하며 ollama signin이 필요합니다.
  • DuckDuckGo는 키가 필요 없지만, 비공식 HTML 기반 통합입니다.
  • SearXNG는 키가 필요 없거나 자체 호스팅할 수 있습니다. SEARXNG_BASE_URL 또는 plugins.entries.searxng.config.webSearch.baseUrl을 구성하세요.
권장: openclaw configure --section web을 실행하고 제공자를 선택하세요. 환경 변수 대안:
  • Brave: BRAVE_API_KEY
  • Exa: EXA_API_KEY
  • Firecrawl: FIRECRAWL_API_KEY
  • Gemini: GEMINI_API_KEY
  • Grok: XAI_API_KEY
  • Kimi: KIMI_API_KEY 또는 MOONSHOT_API_KEY
  • MiniMax Search: MINIMAX_CODE_PLAN_KEY, MINIMAX_CODING_API_KEY 또는 MINIMAX_API_KEY
  • Perplexity: PERPLEXITY_API_KEY 또는 OPENROUTER_API_KEY
  • SearXNG: SEARXNG_BASE_URL
  • Tavily: TAVILY_API_KEY
{
  plugins: {
    entries: {
      brave: {
        config: {
          webSearch: {
            apiKey: "BRAVE_API_KEY_HERE",
          },
        },
      },
    },
    },
    tools: {
      web: {
        search: {
          enabled: true,
          provider: "brave",
          maxResults: 5,
        },
        fetch: {
          enabled: true,
          provider: "firecrawl", // optional; omit for auto-detect
        },
      },
    },
}
공급자별 웹 검색 설정은 이제 plugins.entries.<plugin>.config.webSearch.* 아래에 있습니다. 레거시 tools.web.search.* 공급자 경로는 호환성을 위해 아직 임시로 로드되지만, 새 설정에는 사용하지 않아야 합니다. Firecrawl 웹 가져오기 폴백 설정은 plugins.entries.firecrawl.config.webFetch.* 아래에 있습니다.참고:
  • 허용 목록을 사용하는 경우 web_search/web_fetch/x_search 또는 group:web을 추가하세요.
  • web_fetch는 기본적으로 활성화됩니다(명시적으로 비활성화하지 않은 경우).
  • tools.web.fetch.provider를 생략하면 OpenClaw가 사용 가능한 자격 증명에서 준비된 첫 번째 가져오기 폴백 공급자를 자동 감지합니다. 현재 번들 공급자는 Firecrawl입니다.
  • 데몬은 ~/.openclaw/.env(또는 서비스 환경)에서 환경 변수를 읽습니다.
문서: 웹 도구.
config.apply는 전체 설정을 교체합니다. 부분 객체를 보내면 나머지는 모두 제거됩니다.현재 OpenClaw는 여러 우발적인 덮어쓰기를 방지합니다.
  • OpenClaw가 소유한 설정 쓰기는 쓰기 전에 변경 후 전체 설정을 검증합니다.
  • 유효하지 않거나 파괴적인 OpenClaw 소유 쓰기는 거부되고 openclaw.json.rejected.*로 저장됩니다.
  • 직접 편집으로 시작 또는 핫 리로드가 깨지면 Gateway는 닫힌 상태로 실패하거나 리로드를 건너뜁니다. openclaw.json을 다시 쓰지 않습니다.
  • openclaw doctor --fix가 복구를 담당하며, 거부된 파일을 openclaw.json.clobbered.*로 저장하면서 마지막 정상 상태를 복원할 수 있습니다.
복구:
  • openclaw logs --follow에서 Invalid config at, Config write rejected: 또는 config reload skipped (invalid config)를 확인하세요.
  • 활성 설정 옆에 있는 최신 openclaw.json.clobbered.* 또는 openclaw.json.rejected.*를 검사하세요.
  • openclaw config validate와 openclaw doctor --fix를 실행하세요.
  • 의도한 키만 openclaw config set 또는 config.patch로 다시 복사하세요.
  • 마지막 정상 상태나 거부된 페이로드가 없으면 백업에서 복원하거나 openclaw doctor를 다시 실행하고 채널/모델을 다시 설정하세요.
  • 예상치 못한 일이었다면 버그를 제출하고 마지막으로 알려진 설정이나 백업을 포함하세요.
  • 로컬 코딩 에이전트는 로그나 기록에서 작동하는 설정을 재구성할 수 있는 경우가 많습니다.
방지:
  • 작은 변경에는 openclaw config set을 사용하세요.
  • 대화형 편집에는 openclaw configure를 사용하세요.
  • 정확한 경로나 필드 형태가 확실하지 않을 때는 먼저 config.schema.lookup을 사용하세요. 이 명령은 얕은 스키마 Node와 드릴다운을 위한 즉시 하위 요약을 반환합니다.
  • 부분 RPC 편집에는 config.patch를 사용하고, config.apply는 전체 설정 교체에만 사용하세요.
  • 에이전트 실행에서 소유자 전용 gateway 도구를 사용하는 경우에도 tools.exec.ask / tools.exec.security에 대한 쓰기는 계속 거부됩니다(동일한 보호된 exec 경로로 정규화되는 레거시 tools.bash.* 별칭 포함).
문서: 설정, 설정하기, Gateway 문제 해결, Doctor.
일반적인 패턴은 하나의 Gateway(예: Raspberry Pi)에 Node와 에이전트를 더하는 것입니다.
  • Gateway(중앙): 채널(Signal/WhatsApp), 라우팅, 세션을 소유합니다.
  • Node(기기): Mac/iOS/Android가 주변 기기로 연결되어 로컬 도구(system.run, canvas, camera)를 노출합니다.
  • 에이전트(워커): 특별한 역할(예: “Hetzner 운영”, “개인 데이터”)을 위한 별도의 두뇌/작업 공간입니다.
  • 하위 에이전트: 병렬 처리가 필요할 때 메인 에이전트에서 백그라운드 작업을 생성합니다.
  • TUI: Gateway에 연결하고 에이전트/세션을 전환합니다.
문서: Node, 원격 액세스, 멀티 에이전트 라우팅, 하위 에이전트, TUI.
예. 설정 옵션입니다.
{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } },
    },
  },
}
기본값은 false(헤드풀)입니다. 헤드리스는 일부 사이트에서 봇 방지 검사를 트리거할 가능성이 더 높습니다. 브라우저를 참조하세요.헤드리스는 동일한 Chromium 엔진을 사용하며 대부분의 자동화(양식, 클릭, 스크래핑, 로그인)에 작동합니다. 주요 차이점은 다음과 같습니다.
  • 보이는 브라우저 창이 없습니다(시각적 확인이 필요하면 스크린샷을 사용하세요).
  • 일부 사이트는 헤드리스 모드에서 자동화에 더 엄격합니다(CAPTCHA, 봇 방지). 예를 들어 X/Twitter는 헤드리스 세션을 자주 차단합니다.
browser.executablePath를 Brave 바이너리(또는 Chromium 기반 브라우저)로 설정하고 Gateway를 다시 시작하세요. 전체 설정 예시는 브라우저를 참조하세요.

​
원격 Gateway와 Node

Telegram 메시지는 Gateway가 처리합니다. Gateway는 에이전트를 실행한 다음 Node 도구가 필요할 때만 Gateway WebSocket을 통해 Node를 호출합니다.Telegram → Gateway → 에이전트 → node.* → Node → Gateway → TelegramNode는 들어오는 공급자 트래픽을 보지 않습니다. Node RPC 호출만 수신합니다.
짧은 답변: 컴퓨터를 Node로 페어링하세요. Gateway는 다른 곳에서 실행되지만, Gateway WebSocket을 통해 로컬 머신의 node.* 도구(화면, 카메라, 시스템)를 호출할 수 있습니다.일반적인 설정:
  1. 항상 켜져 있는 호스트(VPS/홈 서버)에서 Gateway를 실행합니다.
  2. Gateway 호스트와 컴퓨터를 같은 tailnet에 둡니다.
  3. Gateway WS에 접근할 수 있는지 확인합니다(tailnet 바인드 또는 SSH 터널).
  4. macOS 앱을 로컬에서 열고 SSH를 통한 원격 모드(또는 직접 tailnet)로 연결하여 Node로 등록할 수 있게 합니다.
  5. Gateway에서 Node를 승인합니다. 
    openclaw devices list
openclaw devices approve <requestId>
별도의 TCP 브리지는 필요하지 않습니다. Node는 Gateway WebSocket을 통해 연결됩니다.보안 알림: macOS Node를 페어링하면 해당 머신에서 system.run을 허용합니다. 신뢰하는 기기만 페어링하고 보안을 검토하세요.문서: Node, Gateway 프로토콜, macOS 원격 모드, 보안.
기본 사항을 확인하세요.
  • Gateway가 실행 중인지: openclaw gateway status
  • Gateway 상태: openclaw status
  • 채널 상태: openclaw channels status
그런 다음 인증과 라우팅을 확인하세요.
  • Tailscale Serve를 사용하는 경우 gateway.auth.allowTailscale이 올바르게 설정되어 있는지 확인하세요.
  • SSH 터널로 연결하는 경우 로컬 터널이 실행 중이고 올바른 포트를 가리키는지 확인하세요.
  • 허용 목록(DM 또는 그룹)에 계정이 포함되어 있는지 확인하세요.
문서: Tailscale, 원격 액세스, 채널.
예. 내장된 “봇 간” 브리지는 없지만, 몇 가지 신뢰할 수 있는 방식으로 연결할 수 있습니다.가장 간단한 방법: 두 봇이 모두 접근할 수 있는 일반 채팅 채널(Telegram/Slack/WhatsApp)을 사용하세요. 봇 A가 봇 B에게 메시지를 보내게 한 다음, 봇 B가 평소처럼 응답하게 하세요.CLI 브리지(일반): 다른 봇이 수신하는 채팅을 대상으로 openclaw agent --message ... --deliver로 다른 Gateway를 호출하는 스크립트를 실행하세요. 한 봇이 원격 VPS에 있다면 SSH/Tailscale을 통해 CLI가 해당 원격 Gateway를 가리키게 하세요 (원격 액세스 참조).예시 패턴(대상 Gateway에 접근할 수 있는 머신에서 실행):
openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to <chat-id>
팁: 두 봇이 끝없이 반복하지 않도록 가드레일을 추가하세요(멘션 전용, 채널 허용 목록, 또는 “봇 메시지에 응답하지 않기” 규칙).문서: 원격 액세스, 에이전트 CLI, 에이전트 보내기.
아니요. 하나의 Gateway가 여러 에이전트를 호스팅할 수 있으며, 각 에이전트는 자체 작업 공간, 모델 기본값, 라우팅을 가집니다. 이것이 일반적인 설정이며 에이전트마다 VPS를 하나씩 실행하는 것보다 훨씬 저렴하고 단순합니다.강한 격리(보안 경계)가 필요하거나 공유하고 싶지 않은 매우 다른 설정이 있을 때만 별도의 VPS를 사용하세요. 그렇지 않으면 하나의 Gateway를 유지하고 여러 에이전트 또는 하위 에이전트를 사용하세요.
예. Node는 원격 Gateway에서 노트북에 접근하는 일급 방식이며, 단순한 셸 접근 이상의 기능을 제공합니다. Gateway는 macOS/Linux(Windows는 WSL2를 통해)에서 실행되며 가볍기 때문에(작은 VPS 또는 Raspberry Pi급 장치면 충분하고, RAM 4GB면 넉넉합니다) 일반적인 설정은 항상 켜져 있는 호스트에 노트북을 Node로 추가하는 방식입니다.
  • 인바운드 SSH가 필요 없습니다. Node는 Gateway WebSocket으로 아웃바운드 연결하고 기기 페어링을 사용합니다.
  • 더 안전한 실행 제어. system.run은 해당 노트북의 Node 허용 목록/승인으로 제한됩니다.
  • 더 많은 기기 도구. Node는 system.run 외에도 canvas, camera, screen을 노출합니다.
  • 로컬 브라우저 자동화. Gateway는 VPS에 두고, 노트북의 Node 호스트를 통해 Chrome을 로컬에서 실행하거나 Chrome MCP를 통해 호스트의 로컬 Chrome에 연결하세요.
SSH는 임시 셸 접근에는 괜찮지만, 지속적인 에이전트 워크플로와 기기 자동화에는 Node가 더 단순합니다.문서: Node, Node CLI, 브라우저.
아니요. 의도적으로 격리된 프로필을 실행하는 경우가 아니라면 호스트당 하나의 Gateway만 실행해야 합니다(여러 Gateway 참조). Node는 Gateway에 연결되는 주변 기기입니다(iOS/Android Node 또는 메뉴바 앱의 macOS “Node 모드”). 헤드리스 Node 호스트와 CLI 제어는 Node 호스트 CLI를 참조하세요.gateway, discovery, 호스팅된 Plugin 표면 변경에는 전체 재시작이 필요합니다.
예.
  • config.schema.lookup: 쓰기 전에 얕은 스키마 노드, 일치한 UI 힌트, 즉시 하위 요약과 함께 구성 하위 트리 하나를 검사합니다
  • config.get: 현재 스냅샷 + 해시를 가져옵니다
  • config.patch: 안전한 부분 업데이트(대부분의 RPC 편집에 권장); 가능하면 핫 리로드하고 필요하면 다시 시작합니다
  • config.apply: 전체 구성을 검증 + 교체합니다; 가능하면 핫 리로드하고 필요하면 다시 시작합니다
  • 소유자 전용 gateway 런타임 도구는 여전히 tools.exec.ask / tools.exec.security 다시 쓰기를 거부합니다. 레거시 tools.bash.* 별칭은 동일한 보호된 exec 경로로 정규화됩니다
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}
이렇게 하면 작업 공간을 설정하고 봇을 트리거할 수 있는 사용자를 제한합니다.
최소 단계:
  1. VPS에 설치 + 로그인 
    curl -fsSL https://tailscale.com/install.sh | sh
sudo tailscale up
  2. Mac에 설치 + 로그인
    • Tailscale 앱을 사용하고 같은 tailnet에 로그인합니다.
  3. MagicDNS 활성화(권장)
    • Tailscale 관리자 콘솔에서 MagicDNS를 활성화하여 VPS가 안정적인 이름을 갖도록 합니다.
  4. tailnet 호스트 이름 사용
    • SSH: ssh user@your-vps.tailnet-xxxx.ts.net
    • Gateway WS: ws://your-vps.tailnet-xxxx.ts.net:18789
SSH 없이 Control UI를 원하면 VPS에서 Tailscale Serve를 사용하세요.
openclaw gateway --tailscale serve
이렇게 하면 gateway가 loopback에 바인딩된 상태를 유지하고 Tailscale을 통해 HTTPS를 노출합니다. Tailscale을 참조하세요.
Serve는 Gateway Control UI + WS를 노출합니다. 노드는 동일한 Gateway WS 엔드포인트를 통해 연결됩니다.권장 설정:
  1. VPS + Mac이 같은 tailnet에 있는지 확인합니다.
  2. Remote 모드에서 macOS 앱을 사용합니다(SSH 대상은 tailnet 호스트 이름일 수 있음). 앱이 Gateway 포트를 터널링하고 노드로 연결됩니다.
  3. gateway에서 노드를 승인합니다. 
    openclaw devices list
openclaw devices approve <requestId>
문서: Gateway 프로토콜, 검색, macOS 원격 모드.
두 번째 노트북에서 로컬 도구(화면/카메라/exec)만 필요하다면 노드로 추가하세요. 그러면 단일 Gateway를 유지하고 중복 구성을 피할 수 있습니다. 로컬 노드 도구는 현재 macOS 전용이지만, 다른 OS로 확장할 계획입니다.강한 격리 또는 완전히 별도인 봇 두 개가 필요할 때만 두 번째 Gateway를 설치하세요.문서: 노드, 노드 CLI, 여러 gateway.

​
환경 변수 및 .env 로드

OpenClaw는 부모 프로세스(shell, launchd/systemd, CI 등)에서 환경 변수를 읽고, 추가로 다음을 로드합니다.
  • 현재 작업 디렉터리의 .env
  • ~/.openclaw/.env의 전역 폴백 .env(일명 $OPENCLAW_STATE_DIR/.env)
어느 .env 파일도 기존 환경 변수를 덮어쓰지 않습니다.구성에서 인라인 환경 변수를 정의할 수도 있습니다(프로세스 환경에 없을 때만 적용됨).
{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}
전체 우선순위와 출처는 /environment를 참조하세요.
흔한 해결 방법 두 가지:
  1. 누락된 키를 ~/.openclaw/.env에 넣어 서비스가 shell 환경을 상속하지 않아도 선택되도록 합니다.
  2. shell 가져오기를 활성화합니다(옵트인 편의 기능).
{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}
이렇게 하면 로그인 shell을 실행하고 누락된 예상 키만 가져옵니다(절대 덮어쓰지 않음). 환경 변수 동등 항목: OPENCLAW_LOAD_SHELL_ENV=1, OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000.
openclaw models status는 shell 환경 가져오기가 활성화되어 있는지 보고합니다. “Shell env: off”는 환경 변수가 없다는 뜻이 아닙니다. OpenClaw가 로그인 shell을 자동으로 로드하지 않는다는 뜻일 뿐입니다.Gateway가 서비스(launchd/systemd)로 실행되면 shell 환경을 상속하지 않습니다. 다음 중 하나로 해결하세요.
  1. 토큰을 ~/.openclaw/.env에 넣습니다. 
    COPILOT_GITHUB_TOKEN=...
  2. 또는 shell 가져오기를 활성화합니다(env.shellEnv.enabled: true).
  3. 또는 구성의 env 블록에 추가합니다(없을 때만 적용됨).
그런 다음 gateway를 다시 시작하고 다시 확인합니다.
openclaw models status
Copilot 토큰은 COPILOT_GITHUB_TOKEN에서 읽습니다(GH_TOKEN / GITHUB_TOKEN도 포함). /concepts/model-providers 및 /environment를 참조하세요.

​
세션 및 여러 채팅

독립 메시지로 /new 또는 /reset을 보내세요. 세션 관리를 참조하세요.
세션은 session.idleMinutes 이후 만료될 수 있지만, 이는 기본적으로 비활성화되어 있습니다(기본값 0). 유휴 만료를 활성화하려면 양수 값으로 설정하세요. 활성화되면 유휴 기간 이후의 다음 메시지가 해당 채팅 키에 대한 새 세션 ID를 시작합니다. 이는 transcript를 삭제하지 않으며, 새 세션을 시작할 뿐입니다.
{
  session: {
    idleMinutes: 240,
  },
}
예, 다중 에이전트 라우팅 및 하위 에이전트를 통해 가능합니다. 하나의 코디네이터 에이전트와 자체 작업 공간 및 모델을 가진 여러 작업자 에이전트를 만들 수 있습니다.다만 이는 재미있는 실험으로 보는 것이 가장 좋습니다. 토큰을 많이 사용하고, 별도 세션이 있는 봇 하나를 사용하는 것보다 효율이 낮은 경우가 많습니다. 우리가 상정하는 일반적인 모델은 사용자가 대화하는 봇 하나와 병렬 작업을 위한 서로 다른 세션입니다. 그 봇은 필요할 때 하위 에이전트를 생성할 수도 있습니다.문서: 다중 에이전트 라우팅, 하위 에이전트, 에이전트 CLI.
세션 컨텍스트는 모델 창에 의해 제한됩니다. 긴 채팅, 큰 도구 출력 또는 많은 파일은 Compaction 또는 잘림을 유발할 수 있습니다.도움이 되는 방법:
  • 봇에게 현재 상태를 요약하고 파일에 쓰도록 요청합니다.
  • 긴 작업 전에는 /compact를 사용하고, 주제를 전환할 때는 /new를 사용합니다.
  • 중요한 컨텍스트는 작업 공간에 보관하고 봇에게 다시 읽도록 요청합니다.
  • 긴 작업이나 병렬 작업에는 하위 에이전트를 사용하여 메인 채팅을 더 작게 유지합니다.
  • 이런 일이 자주 발생하면 더 큰 컨텍스트 창을 가진 모델을 선택합니다.
reset 명령을 사용하세요.
openclaw reset
비대화형 전체 재설정:
openclaw reset --scope full --yes --non-interactive
그런 다음 설정을 다시 실행합니다.
openclaw onboard --install-daemon
참고:
  • 기존 구성이 보이면 온보딩도 Reset을 제공합니다. 온보딩(CLI)을 참조하세요.
  • 프로필(--profile / OPENCLAW_PROFILE)을 사용했다면 각 상태 디렉터리를 재설정하세요(기본값은 ~/.openclaw-<profile>).
  • 개발 재설정: openclaw gateway --dev --reset(개발 전용; 개발 구성 + 자격 증명 + 세션 + 작업 공간 삭제).
다음 중 하나를 사용하세요.
  • Compaction(대화를 유지하지만 오래된 턴을 요약): 
    /compact
    또는 요약을 안내하려면 /compact <instructions>를 사용합니다.
  • 재설정(같은 채팅 키에 대한 새 세션 ID): 
    /new
/reset
계속 발생하는 경우:
  • 세션 가지치기(agents.defaults.contextPruning)를 활성화하거나 조정하여 오래된 도구 출력을 다듬습니다.
  • 더 큰 컨텍스트 창을 가진 모델을 사용합니다.
문서: Compaction, 세션 가지치기, 세션 관리.
이는 공급자 검증 오류입니다. 모델이 필수 input 없이 tool_use 블록을 내보냈다는 뜻입니다. 보통 세션 기록이 오래되었거나 손상되었음을 의미합니다(긴 스레드 또는 도구/스키마 변경 이후에 자주 발생).해결: /new(독립 메시지)로 새 세션을 시작합니다.
Heartbeat는 기본적으로 30m마다 실행됩니다(OAuth 인증 사용 시 1h). 조정하거나 비활성화하세요.
{
  agents: {
    defaults: {
      heartbeat: {
        every: "2h", // or "0m" to disable
      },
    },
  },
}
HEARTBEAT.md가 존재하지만 사실상 비어 있는 경우(빈 줄과 # Heading 같은 markdown 헤더만 있는 경우), OpenClaw는 API 호출을 절약하기 위해 heartbeat 실행을 건너뜁니다. 파일이 없으면 heartbeat는 계속 실행되고 모델이 수행할 작업을 결정합니다.에이전트별 재정의에는 agents.list[].heartbeat를 사용합니다. 문서: Heartbeat.
아니요. OpenClaw는 사용자 자신의 계정에서 실행되므로, 사용자가 그룹에 있으면 OpenClaw가 볼 수 있습니다. 기본적으로 그룹 답장은 발신자를 허용할 때까지 차단됩니다(groupPolicy: "allowlist").사용자만 그룹 답장을 트리거할 수 있게 하려면 다음과 같이 설정하세요.
{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}
옵션 1(가장 빠름): 로그를 tail하고 그룹에 테스트 메시지를 보냅니다.
openclaw logs --follow --json
다음과 같이 @g.us로 끝나는 chatId(또는 from)를 찾습니다. 1234567890-1234567890@g.us.옵션 2(이미 구성/허용 목록에 있는 경우): 구성에서 그룹 목록을 표시합니다.
openclaw directory groups list --channel whatsapp
문서: WhatsApp, 디렉터리, 로그.
흔한 원인 두 가지:
  • 멘션 게이팅이 켜져 있습니다(기본값). 봇을 @mention해야 합니다(또는 mentionPatterns와 일치해야 함).
  • channels.whatsapp.groups를 "*" 없이 구성했고 그룹이 허용 목록에 없습니다.
그룹 및 그룹 메시지를 참조하세요.
직접 채팅은 기본적으로 메인 세션으로 합쳐집니다. 그룹/채널에는 자체 세션 키가 있고, Telegram 토픽 / Discord 스레드는 별도 세션입니다. 그룹 및 그룹 메시지를 참조하세요.
엄격한 제한은 없습니다. 수십 개, 심지어 수백 개도 괜찮지만 다음을 주의하세요.
  • 디스크 증가: 세션 + 트랜스크립트는 ~/.openclaw/agents/<agentId>/sessions/ 아래에 있습니다.
  • 토큰 비용: 에이전트가 많을수록 동시 모델 사용량이 늘어납니다.
  • 운영 부담: 에이전트별 인증 프로필, 워크스페이스, 채널 라우팅.
팁:
  • 에이전트마다 하나의 활성 워크스페이스를 유지하세요(agents.defaults.workspace).
  • 디스크가 커지면 오래된 세션을 정리하세요(JSONL 또는 저장소 항목 삭제).
  • openclaw doctor를 사용해 남은 워크스페이스와 프로필 불일치를 찾으세요.
예. Multi-Agent Routing을 사용해 격리된 여러 에이전트를 실행하고 수신 메시지를 채널/계정/피어별로 라우팅하세요. Slack은 채널로 지원되며 특정 에이전트에 바인딩할 수 있습니다.브라우저 접근은 강력하지만 “사람이 할 수 있는 모든 것을 수행”하는 것은 아닙니다. 안티봇, CAPTCHA, MFA가 여전히 자동화를 차단할 수 있습니다. 가장 안정적인 브라우저 제어를 위해서는 호스트에서 로컬 Chrome MCP를 사용하거나, 실제로 브라우저를 실행하는 머신에서 CDP를 사용하세요.권장 설정:
  • 상시 실행 Gateway 호스트(VPS/Mac mini).
  • 역할별 에이전트 하나(바인딩).
  • 해당 에이전트에 바인딩된 Slack 채널.
  • 필요 시 Chrome MCP 또는 노드를 통한 로컬 브라우저.
문서: Multi-Agent Routing, Slack, Browser, Nodes.

​
모델, 장애 조치, 인증 프로필

모델 Q&A — 기본값, 선택, 별칭, 전환, 장애 조치, 인증 프로필 — 는 모델 FAQ에 있습니다.

​
Gateway: 포트, “이미 실행 중”, 원격 모드

gateway.port는 WebSocket + HTTP(Control UI, 훅 등)를 위한 단일 멀티플렉스 포트를 제어합니다.우선순위:
--port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789
“running”은 슈퍼바이저 관점(launchd/systemd/schtasks)이기 때문입니다. 연결 프로브는 CLI가 실제로 Gateway WebSocket에 연결하는 것입니다.openclaw gateway status를 사용하고 다음 줄을 신뢰하세요.
  • Probe target: (프로브가 실제로 사용한 URL)
  • Listening: (포트에 실제로 바인딩된 대상)
  • Last gateway error: (프로세스는 살아 있지만 포트가 수신 중이 아닐 때의 일반적인 근본 원인)
서비스가 다른 구성 파일로 실행되는 동안 사용자는 한 구성 파일을 편집하고 있습니다(대개 --profile / OPENCLAW_STATE_DIR 불일치).해결:
openclaw gateway install --force
서비스가 사용하길 원하는 동일한 --profile / 환경에서 이 명령을 실행하세요.
OpenClaw는 시작 시 WebSocket 리스너를 즉시 바인딩하여 런타임 잠금을 적용합니다(기본값 ws://127.0.0.1:18789). 바인딩이 EADDRINUSE로 실패하면 다른 인스턴스가 이미 수신 중임을 나타내는 GatewayLockError를 throw합니다.해결: 다른 인스턴스를 중지하거나, 포트를 비우거나, openclaw gateway --port <port>로 실행하세요.
gateway.mode: "remote"를 설정하고 원격 WebSocket URL을 지정하세요. 선택적으로 공유 시크릿 원격 자격 증명을 사용할 수 있습니다.
{
  gateway: {
    mode: "remote",
    remote: {
      url: "ws://gateway.tailnet:18789",
      token: "your-token",
      password: "your-password",
    },
  },
}
참고:
  • openclaw gateway는 gateway.mode가 local일 때만 시작됩니다(또는 오버라이드 플래그를 전달한 경우).
  • macOS 앱은 구성 파일을 감시하며 이 값들이 변경되면 실시간으로 모드를 전환합니다.
  • gateway.remote.token / .password는 클라이언트 측 원격 자격 증명일 뿐이며, 그 자체로 로컬 Gateway 인증을 활성화하지 않습니다.
Gateway 인증 경로와 UI의 인증 방식이 일치하지 않습니다.사실(코드 기준):
  • Control UI는 현재 브라우저 탭 세션과 선택된 Gateway URL에 대해 토큰을 sessionStorage에 보관하므로, 같은 탭 새로고침은 장기 localStorage 토큰 지속성을 복원하지 않아도 계속 작동합니다.
  • AUTH_TOKEN_MISMATCH에서 Gateway가 재시도 힌트(canRetryWithDeviceToken=true, recommendedNextStep=retry_with_device_token)를 반환하면 신뢰된 클라이언트는 캐시된 디바이스 토큰으로 제한된 재시도를 한 번 시도할 수 있습니다.
  • 해당 캐시 토큰 재시도는 이제 디바이스 토큰과 함께 저장된 캐시된 승인 범위를 재사용합니다. 명시적 deviceToken / 명시적 scopes 호출자는 캐시된 범위를 상속하지 않고 요청한 범위 집합을 그대로 유지합니다.
  • 해당 재시도 경로 밖에서 연결 인증 우선순위는 명시적 공유 토큰/비밀번호, 명시적 deviceToken, 저장된 디바이스 토큰, 부트스트랩 토큰 순입니다.
  • 부트스트랩 토큰 범위 검사는 역할 접두사를 사용합니다. 내장 부트스트랩 운영자 허용 목록은 운영자 요청만 충족합니다. 노드 또는 기타 비운영자 역할은 여전히 자체 역할 접두사 아래의 범위가 필요합니다.
해결:
  • 가장 빠른 방법: openclaw dashboard(대시보드 URL을 출력 + 복사하고 열기를 시도하며, 헤드리스이면 SSH 힌트를 표시).
  • 아직 토큰이 없다면: openclaw doctor --generate-gateway-token.
  • 원격이면 먼저 터널링하세요: ssh -N -L 18789:127.0.0.1:18789 user@host를 실행한 다음 http://127.0.0.1:18789/를 여세요.
  • 공유 시크릿 모드: gateway.auth.token / OPENCLAW_GATEWAY_TOKEN 또는 gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD를 설정한 다음 Control UI 설정에 일치하는 시크릿을 붙여 넣으세요.
  • Tailscale Serve 모드: gateway.auth.allowTailscale이 활성화되어 있고, Tailscale ID 헤더를 우회하는 원시 loopback/tailnet URL이 아니라 Serve URL을 열고 있는지 확인하세요.
  • 신뢰된 프록시 모드: 원시 Gateway URL이 아니라 구성된 ID 인식 프록시를 통해 들어오고 있는지 확인하세요. 동일 호스트 loopback 프록시에도 gateway.auth.trustedProxy.allowLoopback = true가 필요합니다.
  • 한 번의 재시도 후에도 불일치가 계속되면 페어링된 디바이스 토큰을 교체/재승인하세요.
    • openclaw devices list
    • openclaw devices rotate --device <id> --role operator
  • 해당 rotate 호출이 거부되었다고 표시되면 다음 두 가지를 확인하세요.
    • 페어링된 디바이스 세션은 operator.admin도 보유한 경우가 아니라면 자신의 디바이스만 교체할 수 있습니다.
    • 명시적 --scope 값은 호출자의 현재 운영자 범위를 초과할 수 없습니다.
  • 여전히 막혀 있나요? openclaw status --all을 실행하고 문제 해결을 따르세요. 인증 세부 정보는 Dashboard를 참고하세요.
tailnet 바인딩은 네트워크 인터페이스(100.64.0.0/10)에서 Tailscale IP를 선택합니다. 머신이 Tailscale에 있지 않거나 인터페이스가 내려가 있으면 바인딩할 대상이 없습니다.해결:
  • 해당 호스트에서 Tailscale을 시작하거나(100.x 주소를 갖도록), 또는
  • gateway.bind: "loopback" / "lan"으로 전환하세요.
참고: tailnet은 명시적입니다. auto는 loopback을 선호합니다. tailnet 전용 바인딩을 원할 때는 gateway.bind: "tailnet"을 사용하세요.
보통은 아닙니다. 하나의 Gateway가 여러 메시징 채널과 에이전트를 실행할 수 있습니다. 여러 Gateway는 중복성(예: 구조 봇) 또는 강한 격리가 필요할 때만 사용하세요.가능하지만 반드시 격리해야 합니다.
  • OPENCLAW_CONFIG_PATH(인스턴스별 구성)
  • OPENCLAW_STATE_DIR(인스턴스별 상태)
  • agents.defaults.workspace(워크스페이스 격리)
  • gateway.port(고유 포트)
빠른 설정(권장):
  • 인스턴스마다 openclaw --profile <name> ...를 사용하세요(~/.openclaw-<name> 자동 생성).
  • 각 프로필 구성에 고유한 gateway.port를 설정하세요(또는 수동 실행 시 --port 전달).
  • 프로필별 서비스를 설치하세요: openclaw --profile <name> gateway install.
프로필은 서비스 이름에도 접미사를 붙입니다(ai.openclaw.<profile>, 레거시 com.openclaw.*, openclaw-gateway-<profile>.service, OpenClaw Gateway (<profile>)). 전체 가이드: 여러 Gateway.
Gateway는 WebSocket 서버이며, 맨 첫 메시지가 connect 프레임이기를 기대합니다. 그 외의 것을 받으면 코드 1008(정책 위반)로 연결을 닫습니다.일반적인 원인:
  • WS 클라이언트 대신 브라우저에서 HTTP URL(http://...)을 열었습니다.
  • 잘못된 포트 또는 경로를 사용했습니다.
  • 프록시 또는 터널이 인증 헤더를 제거했거나 Gateway가 아닌 요청을 보냈습니다.
빠른 해결:
  1. WS URL을 사용하세요: ws://<host>:18789(또는 HTTPS이면 wss://...).
  2. 일반 브라우저 탭에서 WS 포트를 열지 마세요.
  3. 인증이 켜져 있다면 connect 프레임에 토큰/비밀번호를 포함하세요.
CLI 또는 TUI를 사용하는 경우 URL은 다음과 같아야 합니다.
openclaw tui --url ws://<host>:18789 --token <token>
프로토콜 세부 정보: Gateway 프로토콜.

​
로깅 및 디버깅

파일 로그(구조화됨):
/tmp/openclaw/openclaw-YYYY-MM-DD.log
logging.file을 통해 안정적인 경로를 설정할 수 있습니다. 파일 로그 수준은 logging.level로 제어됩니다. 콘솔 상세도는 --verbose와 logging.consoleLevel로 제어됩니다.가장 빠른 로그 tail:
openclaw logs --follow
서비스/슈퍼바이저 로그(Gateway가 launchd/systemd를 통해 실행될 때):
  • macOS: $OPENCLAW_STATE_DIR/logs/gateway.log 및 gateway.err.log(기본값: ~/.openclaw/logs/..., 프로필은 ~/.openclaw-<profile>/logs/... 사용)
  • Linux: journalctl --user -u openclaw-gateway[-<profile>].service -n 200 --no-pager
  • Windows: schtasks /Query /TN "OpenClaw Gateway (<profile>)" /V /FO LIST
자세한 내용은 문제 해결을 참고하세요.
Gateway 헬퍼를 사용하세요.
openclaw gateway status
openclaw gateway restart
Gateway를 수동으로 실행하는 경우 openclaw gateway --force로 포트를 회수할 수 있습니다. Gateway를 참고하세요.
두 가지 Windows 설치 모드가 있습니다.1) WSL2(권장): Gateway가 Linux 내부에서 실행됩니다.PowerShell을 열고 WSL에 들어간 다음 재시작하세요.
wsl
openclaw gateway status
openclaw gateway restart
서비스를 설치한 적이 없다면 포그라운드에서 시작하세요.
openclaw gateway run
2) 네이티브 Windows(권장하지 않음): Gateway가 Windows에서 직접 실행됩니다.PowerShell을 열고 실행하세요.
openclaw gateway status
openclaw gateway restart
수동으로 실행하는 경우(서비스 없음) 다음을 사용하세요.
openclaw gateway run
문서: Windows (WSL2), Gateway 서비스 런북.
빠른 상태 점검부터 시작하세요.
openclaw status
openclaw models status
openclaw channels status
openclaw logs --follow
일반적인 원인:
  • gateway 호스트에서 모델 인증이 로드되지 않음(models status 확인).
  • 채널 페어링/허용 목록이 답변을 차단함(채널 설정 + 로그 확인).
  • 올바른 토큰 없이 WebChat/Dashboard가 열려 있음.
원격 환경이라면 터널/Tailscale 연결이 활성화되어 있고 Gateway WebSocket에 연결할 수 있는지 확인하세요.문서: 채널, 문제 해결, 원격 액세스.
이는 보통 UI가 WebSocket 연결을 잃었다는 뜻입니다. 다음을 확인하세요.
  1. Gateway가 실행 중인가요? openclaw gateway status
  2. Gateway가 정상인가요? openclaw status
  3. UI에 올바른 토큰이 있나요? openclaw dashboard
  4. 원격 환경이라면 터널/Tailscale 링크가 활성화되어 있나요?
그런 다음 로그를 tail하세요.
openclaw logs --follow
문서: Dashboard, 원격 액세스, 문제 해결.
로그와 채널 상태부터 시작하세요.
openclaw channels status
openclaw channels logs --channel telegram
그런 다음 오류를 대조하세요.
  • BOT_COMMANDS_TOO_MUCH: Telegram 메뉴 항목이 너무 많습니다. OpenClaw는 이미 Telegram 제한에 맞게 줄이고 더 적은 명령으로 재시도하지만, 일부 메뉴 항목은 여전히 제거해야 합니다. Plugin/스킬/사용자 지정 명령을 줄이거나, 메뉴가 필요하지 않다면 channels.telegram.commands.native를 비활성화하세요.
  • TypeError: fetch failed, Network request for 'setMyCommands' failed! 또는 유사한 네트워크 오류: VPS를 사용 중이거나 프록시 뒤에 있다면, 아웃바운드 HTTPS가 허용되고 api.telegram.org에 대한 DNS가 작동하는지 확인하세요.
Gateway가 원격에 있다면 Gateway 호스트의 로그를 보고 있는지 확인하세요.문서: Telegram, 채널 문제 해결.
먼저 Gateway에 연결할 수 있고 에이전트를 실행할 수 있는지 확인하세요.
openclaw status
openclaw models status
openclaw logs --follow
TUI에서 /status를 사용해 현재 상태를 확인하세요. 채팅 채널에서 답변을 기대한다면 전달이 활성화되어 있는지 확인하세요([DELIVER_ON]).문서: TUI, 슬래시 명령.
서비스를 설치했다면:
openclaw gateway stop
openclaw gateway start
이는 감독되는 서비스(macOS의 launchd, Linux의 systemd)를 중지/시작합니다. Gateway가 데몬으로 백그라운드에서 실행될 때 사용하세요.포그라운드에서 실행 중이라면 Ctrl-C로 중지한 다음:
openclaw gateway run
문서: Gateway 서비스 런북.
  • openclaw gateway restart: 백그라운드 서비스(launchd/systemd)를 다시 시작합니다.
  • openclaw gateway: 이 터미널 세션에서 gateway를 포그라운드로 실행합니다.
서비스를 설치했다면 gateway 명령을 사용하세요. 일회성 포그라운드 실행을 원할 때 openclaw gateway를 사용하세요.
더 많은 콘솔 세부 정보를 얻으려면 --verbose로 Gateway를 시작하세요. 그런 다음 채널 인증, 모델 라우팅, RPC 오류가 있는지 로그 파일을 검사하세요.

​
미디어 및 첨부 파일

에이전트의 아웃바운드 첨부 파일에는 MEDIA:<path-or-url> 줄이 포함되어야 합니다(해당 줄만 단독으로). OpenClaw 어시스턴트 설정 및 에이전트 전송을 참조하세요.CLI 전송:
openclaw message send --target +15555550123 --message "Here you go" --media /path/to/file.png
또한 다음을 확인하세요.
  • 대상 채널이 아웃바운드 미디어를 지원하고 허용 목록에 의해 차단되지 않는지 확인하세요.
  • 파일이 제공자의 크기 제한 내에 있는지 확인하세요(이미지는 최대 2048px로 크기가 조정됨).
  • tools.fs.workspaceOnly=true는 로컬 경로 전송을 워크스페이스, 임시/미디어 저장소, 샌드박스에서 검증된 파일로 제한합니다.
  • tools.fs.workspaceOnly=false는 MEDIA:가 에이전트가 이미 읽을 수 있는 호스트 로컬 파일을 보내도록 허용하지만, 미디어와 안전한 문서 유형(이미지, 오디오, 비디오, PDF, Office 문서)에만 해당합니다. 일반 텍스트와 비밀처럼 보이는 파일은 여전히 차단됩니다.
이미지를 참조하세요.

​
보안 및 액세스 제어

인바운드 DM은 신뢰할 수 없는 입력으로 취급하세요. 기본값은 위험을 줄이도록 설계되었습니다.
  • DM이 가능한 채널의 기본 동작은 페어링입니다.
    • 알 수 없는 발신자는 페어링 코드를 받으며, 봇은 해당 메시지를 처리하지 않습니다.
    • 다음으로 승인하세요: openclaw pairing approve --channel <channel> [--account <id>] <code>
    • 대기 중인 요청은 채널당 3개로 제한됩니다. 코드가 도착하지 않았다면 openclaw pairing list --channel <channel> [--account <id>]를 확인하세요.
  • DM을 공개적으로 열려면 명시적인 옵트인이 필요합니다(dmPolicy: "open" 및 허용 목록 "*").
위험한 DM 정책을 표시하려면 openclaw doctor를 실행하세요.
아니요. 프롬프트 인젝션은 봇에게 DM을 보낼 수 있는 사람이 아니라 신뢰할 수 없는 콘텐츠의 문제입니다. 어시스턴트가 외부 콘텐츠(웹 검색/가져오기, 브라우저 페이지, 이메일, 문서, 첨부 파일, 붙여넣은 로그)를 읽는다면, 그 콘텐츠에는 모델을 탈취하려는 지시가 포함될 수 있습니다. 이는 발신자가 본인뿐인 경우에도 발생할 수 있습니다.가장 큰 위험은 도구가 활성화되어 있을 때입니다. 모델이 속아서 컨텍스트를 유출하거나 사용자를 대신해 도구를 호출할 수 있습니다. 다음으로 영향 범위를 줄이세요.
  • 신뢰할 수 없는 콘텐츠를 요약할 때 읽기 전용 또는 도구 비활성화 “리더” 에이전트 사용
  • 도구가 활성화된 에이전트에서는 web_search / web_fetch / browser 끄기
  • 디코딩된 파일/문서 텍스트도 신뢰할 수 없는 것으로 취급하기: OpenResponses input_file과 미디어 첨부 추출은 모두 원시 파일 텍스트를 전달하는 대신 추출된 텍스트를 명시적인 외부 콘텐츠 경계 마커로 감쌉니다
  • 샌드박스와 엄격한 도구 허용 목록 사용
세부 정보: 보안.
대부분의 설정에서는 그렇습니다. 별도 계정과 전화번호로 봇을 격리하면 문제가 발생했을 때 영향 범위를 줄일 수 있습니다. 또한 개인 계정에 영향을 주지 않고 자격 증명을 교체하거나 액세스를 취소하기가 더 쉬워집니다.작게 시작하세요. 실제로 필요한 도구와 계정에만 액세스 권한을 부여하고, 필요하면 나중에 확장하세요.문서: 보안, 페어링.
개인 메시지에 대한 완전한 자율성은 권장하지 않습니다. 가장 안전한 패턴은 다음과 같습니다.
  • DM을 페어링 모드 또는 엄격한 허용 목록으로 유지하세요.
  • 사용자를 대신해 메시지를 보내게 하려면 별도 번호 또는 계정을 사용하세요.
  • 먼저 초안을 작성하게 한 다음 전송 전에 승인하세요.
실험하고 싶다면 전용 계정에서 수행하고 격리된 상태를 유지하세요. 보안을 참조하세요.
예, 에이전트가 채팅 전용이고 입력을 신뢰할 수 있다면 가능합니다. 더 작은 계층은 지시 탈취에 더 취약하므로, 도구가 활성화된 에이전트나 신뢰할 수 없는 콘텐츠를 읽을 때는 피하세요. 더 작은 모델을 꼭 사용해야 한다면, 도구를 잠그고 샌드박스 안에서 실행하세요. 보안을 참조하세요.
페어링 코드는 알 수 없는 발신자가 봇에게 메시지를 보내고 dmPolicy: "pairing"이 활성화되어 있을 때만 전송됩니다. /start 자체는 코드를 생성하지 않습니다.대기 중인 요청 확인:
openclaw pairing list telegram
즉시 액세스하려면 발신자 id를 허용 목록에 추가하거나 해당 계정의 dmPolicy: "open"을 설정하세요.
아니요. 기본 WhatsApp DM 정책은 페어링입니다. 알 수 없는 발신자는 페어링 코드만 받으며 해당 메시지는 처리되지 않습니다. OpenClaw는 수신한 채팅 또는 사용자가 명시적으로 트리거한 전송에만 답변합니다.다음으로 페어링을 승인하세요.
openclaw pairing approve whatsapp <code>
대기 중인 요청 목록:
openclaw pairing list whatsapp
마법사의 전화번호 프롬프트: 본인의 DM을 허용하기 위해 허용 목록/소유자를 설정하는 데 사용됩니다. 자동 전송에는 사용되지 않습니다. 개인 WhatsApp 번호에서 실행한다면 해당 번호를 사용하고 channels.whatsapp.selfChatMode를 활성화하세요.

​
채팅 명령, 작업 중단, 그리고 “멈추지 않습니다”

대부분의 내부 메시지나 도구 메시지는 해당 세션에서 verbose, trace 또는 reasoning이 활성화된 경우에만 표시됩니다.표시되는 채팅에서 수정하세요.
/verbose off
/trace off
/reasoning off
여전히 시끄럽다면 Control UI에서 세션 설정을 확인하고 verbose를 상속으로 설정하세요. 또한 설정에서 verboseDefault가 on으로 설정된 봇 프로필을 사용 중이 아닌지 확인하세요.문서: 사고 및 verbose, 보안.
다음 중 하나를 독립 메시지로 보내세요(슬래시 없음).
stop
stop action
stop current action
stop run
stop current run
stop agent
stop the agent
stop openclaw
openclaw stop
stop don't do anything
stop do not do anything
stop doing anything
please stop
stop please
abort
esc
wait
exit
interrupt
이는 중단 트리거입니다(슬래시 명령이 아님).백그라운드 프로세스(exec 도구에서 시작된 것)의 경우 에이전트에게 다음을 실행하도록 요청할 수 있습니다.
process action:kill sessionId:XXX
슬래시 명령 개요: 슬래시 명령을 참조하세요.대부분의 명령은 /로 시작하는 독립 메시지로 보내야 하지만, 일부 단축 명령(/status 등)은 허용 목록에 있는 발신자에게는 인라인에서도 작동합니다.
OpenClaw는 기본적으로 크로스 제공자 메시징을 차단합니다. 도구 호출이 Telegram에 바인딩되어 있으면 명시적으로 허용하지 않는 한 Discord로 전송되지 않습니다.에이전트에 대해 크로스 제공자 메시징을 활성화하세요.
{
  tools: {
    message: {
      crossContext: {
        allowAcrossProviders: true,
        marker: { enabled: true, prefix: "[from {channel}] " },
      },
    },
  },
}
설정을 편집한 후 gateway를 다시 시작하세요.
큐 모드는 새 메시지가 진행 중인 실행과 상호작용하는 방식을 제어합니다. 모드를 변경하려면 /queue를 사용하세요.
  • steer - 현재 실행의 다음 모델 경계까지 대기 중인 모든 조종을 큐에 넣음
  • queue - 기존의 한 번에 하나씩 조종
  • followup - 메시지를 한 번에 하나씩 실행
  • collect - 메시지를 배치 처리하고 한 번만 답변
  • steer-backlog - 지금 조종한 다음 backlog 처리
  • interrupt - 현재 실행을 중단하고 새로 시작
기본 모드는 steer입니다. 후속 모드에는 debounce:0.5s cap:25 drop:summarize 같은 옵션을 추가할 수 있습니다. 명령 큐와 스티어링 큐를 참조하세요.

​
기타

OpenClaw에서 자격 증명과 모델 선택은 별개입니다. ANTHROPIC_API_KEY를 설정하거나 인증 프로필에 Anthropic API 키를 저장하면 인증이 활성화되지만, 실제 기본 모델은 agents.defaults.model.primary에 구성한 값입니다(예: anthropic/claude-sonnet-4-6 또는 anthropic/claude-opus-4-6). No credentials found for profile "anthropic:default"가 표시되면, 실행 중인 에이전트의 예상 auth-profiles.json에서 Gateway가 Anthropic 자격 증명을 찾지 못했다는 뜻입니다.
아직 막혀 있나요? Discord에서 질문하거나 GitHub 토론을 여세요.

​
관련 항목