메인 콘텐츠로 건너뛰기
빠른 시작 및 첫 실행 Q&A입니다. 일상적인 운영, 모델, 인증, 세션, 문제 해결은 기본 FAQ를 참조하세요.

​
빠른 시작 및 첫 실행 설정

내 컴퓨터를 볼 수 있는 로컬 AI 에이전트를 사용하세요. 대부분의 “막혔어요” 사례는 원격 도우미가 확인할 수 없는 로컬 구성 또는 환경 문제이므로, Discord에 묻는 것보다 훨씬 효과적입니다.이러한 도구는 repo를 읽고, 명령을 실행하고, 로그를 검사하며, 컴퓨터 수준의 설정(PATH, 서비스, 권한, 인증 파일)을 고치는 데 도움을 줄 수 있습니다. 해킹 가능한(git) 설치를 통해 전체 소스 체크아웃을 제공하세요.
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
이렇게 하면 OpenClaw가 git 체크아웃에서 설치되므로, 에이전트가 코드와 문서를 읽고 실행 중인 정확한 버전을 기준으로 판단할 수 있습니다. 나중에 언제든지 --install-method git 없이 설치 프로그램을 다시 실행해 안정 버전으로 돌아갈 수 있습니다.팁: 에이전트에게 수정 작업을 계획하고 감독하게 한 다음(단계별로), 필요한 명령만 실행하도록 요청하세요. 그러면 변경이 작고 감사하기 쉬워집니다.실제 버그나 수정 사항을 발견했다면 GitHub 이슈를 제출하거나 PR을 보내 주세요. https://github.com/openclaw/openclaw/issues https://github.com/openclaw/openclaw/pulls다음 명령으로 시작하세요(도움을 요청할 때 출력도 공유하세요).
openclaw status
openclaw models status
openclaw doctor
각 명령의 역할:
  • openclaw status: gateway/agent 상태와 기본 구성을 빠르게 요약합니다.
  • openclaw models status: provider 인증과 모델 사용 가능 여부를 확인합니다.
  • openclaw doctor: 일반적인 구성/상태 문제를 검증하고 복구합니다.
기타 유용한 CLI 확인 명령: openclaw status --all, openclaw logs --follow, openclaw gateway status, openclaw health --verbose.빠른 디버그 루프: 무언가 고장 났을 때 첫 60초. 설치 문서: 설치, 설치 프로그램 플래그, 업데이트.
일반적인 Heartbeat 건너뛰기 이유:
  • quiet-hours: 구성된 활성 시간 창 밖입니다.
  • empty-heartbeat-file: HEARTBEAT.md가 있지만 빈 줄, 주석, 헤더, fence, 또는 빈 체크리스트 뼈대만 포함합니다.
  • no-tasks-due: HEARTBEAT.md 작업 모드가 활성화되어 있지만 아직 어떤 작업 간격도 도래하지 않았습니다.
  • alerts-disabled: 모든 Heartbeat 표시가 비활성화되어 있습니다(showOk, showAlerts, useIndicator가 모두 꺼져 있음).
작업 모드에서는 실제 Heartbeat 실행이 완료된 뒤에만 기한 타임스탬프가 갱신됩니다. 건너뛴 실행은 작업을 완료로 표시하지 않습니다.문서: Heartbeat, 자동화.
repo에서는 소스에서 실행하고 온보딩을 사용하는 방식을 권장합니다.
curl -fsSL https://openclaw.ai/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
openclaw onboard
아직 전역 설치가 없다면 pnpm openclaw onboard로 실행하세요.
마법사는 온보딩 직후 깨끗한(토큰화되지 않은) 대시보드 URL로 브라우저를 열고, 요약에도 링크를 출력합니다. 해당 탭을 열어 두세요. 실행되지 않았다면 같은 컴퓨터에서 출력된 URL을 복사/붙여넣기 하세요.
Localhost(같은 컴퓨터):
  • http://127.0.0.1:18789/를 엽니다.
  • shared-secret 인증을 요청하면 구성된 토큰 또는 비밀번호를 Control UI 설정에 붙여넣습니다.
  • 토큰 출처: gateway.auth.token(또는 OPENCLAW_GATEWAY_TOKEN).
  • 비밀번호 출처: gateway.auth.password(또는 OPENCLAW_GATEWAY_PASSWORD).
  • 아직 shared secret이 구성되지 않았다면 openclaw doctor --generate-gateway-token으로 토큰을 생성합니다.
localhost가 아닌 경우:
  • Tailscale Serve(권장): bind는 loopback으로 유지하고, openclaw gateway --tailscale serve를 실행한 뒤 https://<magicdns>/를 엽니다. gateway.auth.allowTailscale이 true이면 identity 헤더가 Control UI/WebSocket 인증을 충족합니다(붙여넣은 shared secret이 필요 없으며, 신뢰된 gateway 호스트를 가정). HTTP API는 private-ingress none 또는 trusted-proxy HTTP 인증을 의도적으로 사용하지 않는 한 여전히 shared-secret 인증이 필요합니다. 같은 클라이언트의 잘못된 동시 Serve 인증 시도는 failed-auth limiter가 기록하기 전에 직렬화되므로, 두 번째 잘못된 재시도에서 이미 retry later가 표시될 수 있습니다.
  • Tailnet bind: openclaw gateway --bind tailnet --token "<token>"을 실행하거나 비밀번호 인증을 구성하고, http://<tailscale-ip>:18789/를 연 다음 일치하는 shared secret을 대시보드 설정에 붙여넣습니다.
  • Identity-aware reverse proxy: Gateway를 신뢰된 프록시 뒤에 두고, gateway.auth.mode: "trusted-proxy"를 구성한 다음 프록시 URL을 엽니다. 같은 호스트의 loopback 프록시는 명시적으로 gateway.auth.trustedProxy.allowLoopback = true가 필요합니다.
  • SSH 터널: ssh -N -L 18789:127.0.0.1:18789 user@host를 실행한 다음 http://127.0.0.1:18789/를 엽니다. 터널을 통해서도 shared-secret 인증이 적용됩니다. 요청되면 구성된 토큰 또는 비밀번호를 붙여넣으세요.
bind 모드와 인증 세부 정보는 대시보드 및 웹 표면을 참조하세요.
서로 다른 계층을 제어합니다.
  • approvals.exec: 승인 프롬프트를 채팅 대상에 전달합니다.
  • channels.<channel>.execApprovals: 해당 채널이 exec 승인용 네이티브 승인 클라이언트로 동작하게 합니다.
호스트 exec 정책이 여전히 실제 승인 게이트입니다. 채팅 구성은 승인 프롬프트가 어디에 표시되고 사람들이 어떻게 응답할 수 있는지만 제어합니다.대부분의 설정에서는 둘 다 필요하지 않습니다.
  • 채팅이 이미 명령과 답장을 지원한다면, 같은 채팅의 /approve는 공유 경로를 통해 작동합니다.
  • 지원되는 네이티브 채널이 승인자를 안전하게 추론할 수 있으면, channels.<channel>.execApprovals.enabled가 설정되지 않았거나 "auto"일 때 OpenClaw가 이제 DM 우선 네이티브 승인을 자동 활성화합니다.
  • 네이티브 승인 카드/버튼을 사용할 수 있으면, 해당 네이티브 UI가 기본 경로입니다. 에이전트는 도구 결과가 채팅 승인을 사용할 수 없다고 하거나 수동 승인만 가능한 경로라고 말할 때만 수동 /approve 명령을 포함해야 합니다.
  • 프롬프트를 다른 채팅이나 명시적인 운영 방에도 전달해야 할 때만 approvals.exec를 사용하세요.
  • 승인 프롬프트를 원래 방/주제에 다시 게시하기를 명시적으로 원할 때만 channels.<channel>.execApprovals.target: "channel" 또는 "both"를 사용하세요.
  • Plugin 승인은 또 별개입니다. 기본적으로 같은 채팅의 /approve, 선택적 approvals.plugin 전달을 사용하며, 일부 네이티브 채널만 그 위에 plugin-approval-native 처리를 유지합니다.
짧게 말하면: 전달은 라우팅을 위한 것이고, 네이티브 클라이언트 구성은 더 풍부한 채널별 UX를 위한 것입니다. Exec 승인을 참조하세요.
Node >= 22가 필요합니다. pnpm을 권장합니다. Gateway에는 Bun을 권장하지 않습니다.
예. Gateway는 가볍습니다. 문서에는 개인 용도로 512MB-1GB RAM, 1 core, 약 500MB 디스크면 충분하다고 나와 있으며, Raspberry Pi 4에서 실행할 수 있음도 언급합니다.추가 여유(로그, 미디어, 기타 서비스)를 원한다면 2GB를 권장하지만, 엄격한 최소 요구 사항은 아닙니다.팁: 작은 Raspberry Pi/VPS가 Gateway를 호스팅할 수 있고, 로컬 화면/카메라/캔버스 또는 명령 실행을 위해 노트북/휴대폰의 노드를 페어링할 수 있습니다. 노드를 참조하세요.
짧게 말하면: 작동하지만, 거친 부분이 있을 수 있습니다.
  • 64-bit OS를 사용하고 Node >= 22를 유지하세요.
  • 로그를 확인하고 빠르게 업데이트할 수 있도록 해킹 가능한(git) 설치를 선호하세요.
  • 채널/skills 없이 시작한 뒤 하나씩 추가하세요.
  • 이상한 바이너리 문제가 발생하면 대개 ARM 호환성 문제입니다.
문서: Linux, 설치.
해당 화면은 Gateway에 연결할 수 있고 인증되어 있어야 작동합니다. TUI도 첫 부화 시 “Wake up, my friend!”를 자동으로 보냅니다. 해당 줄이 응답 없이 보이고 토큰이 0에 머문다면, 에이전트가 실행되지 않은 것입니다.
  1. Gateway를 다시 시작합니다.
openclaw gateway restart
  1. 상태와 인증을 확인합니다.
openclaw status
openclaw models status
openclaw logs --follow
  1. 그래도 멈춘다면 다음을 실행합니다.
openclaw doctor
Gateway가 원격이라면 터널/Tailscale 연결이 올라와 있고 UI가 올바른 Gateway를 가리키는지 확인하세요. 원격 액세스를 참조하세요.
예. 상태 디렉터리와 workspace를 복사한 다음 Doctor를 한 번 실행하세요. 두 위치를 모두 복사하면 봇을 “완전히 동일하게”(메모리, 세션 기록, 인증, 채널 상태) 유지할 수 있습니다.
  1. 새 컴퓨터에 OpenClaw를 설치합니다.
  2. 이전 컴퓨터에서 $OPENCLAW_STATE_DIR(기본값: ~/.openclaw)을 복사합니다.
  3. workspace(기본값: ~/.openclaw/workspace)를 복사합니다.
  4. openclaw doctor를 실행하고 Gateway 서비스를 다시 시작합니다.
이렇게 하면 구성, 인증 프로필, WhatsApp 자격 증명, 세션, 메모리가 보존됩니다. 원격 모드라면 gateway 호스트가 세션 저장소와 workspace를 소유한다는 점을 기억하세요.중요: workspace만 GitHub에 commit/push하면 메모리 + bootstrap 파일은 백업되지만, 세션 기록이나 인증은 백업되지 않습니다. 이것들은 ~/.openclaw/ 아래에 있습니다(예: ~/.openclaw/agents/<agentId>/sessions/).관련 항목: 마이그레이션, 디스크에서 항목이 저장되는 위치, 에이전트 workspace, Doctor, 원격 모드.
GitHub 변경 로그를 확인하세요. https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md최신 항목은 맨 위에 있습니다. 맨 위 섹션이 Unreleased로 표시되어 있으면, 그 다음 날짜가 있는 섹션이 최신 출시 버전입니다. 항목은 Highlights, Changes, Fixes별로 묶이며, 필요할 때 문서/기타 섹션도 포함됩니다.
일부 Comcast/Xfinity 연결은 Xfinity Advanced Security를 통해 docs.openclaw.ai를 잘못 차단합니다. 이를 비활성화하거나 docs.openclaw.ai를 허용 목록에 추가한 다음 다시 시도하세요. 여기에서 신고해 차단 해제에 도움을 주세요: https://spa.xfinity.com/check_url_status.그래도 사이트에 접속할 수 없다면, 문서가 GitHub에 미러링되어 있습니다. https://github.com/openclaw/openclaw/tree/main/docs
안정 버전과 베타는 별도의 코드 라인이 아니라 npm dist-tag입니다.
  • latest = 안정 버전
  • beta = 테스트용 초기 빌드
일반적으로 안정 릴리스는 먼저 beta에 배포된 다음, 명시적인 승격 단계에서 같은 버전을 latest로 이동합니다. 관리자가 필요할 때는 바로 latest로 게시할 수도 있습니다. 그래서 승격 후에는 베타와 안정 버전이 같은 버전을 가리킬 수 있습니다.변경 사항 보기: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md설치 한 줄 명령과 베타와 개발 버전의 차이는 아래 아코디언을 참고하세요.
베타는 npm dist-tag beta입니다(승격 후에는 latest와 같을 수 있음). 개발 버전은 main의 움직이는 최신 상태(git)이며, 게시될 때는 npm dist-tag dev를 사용합니다.한 줄 명령(macOS/Linux):
curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --beta

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
Windows 설치 프로그램(PowerShell): https://openclaw.ai/install.ps1자세한 내용: 개발 채널 및 설치 프로그램 플래그.
두 가지 옵션이 있습니다.
  1. 개발 채널(git 체크아웃):
openclaw update --channel dev
이 명령은 main 브랜치로 전환하고 소스에서 업데이트합니다.
  1. 수정 가능한 설치(설치 프로그램 사이트에서):
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
그러면 편집할 수 있는 로컬 저장소가 생기고, 이후 git으로 업데이트할 수 있습니다.깔끔한 클론을 수동으로 선호한다면 다음을 사용하세요.
git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build
문서: 업데이트, 개발 채널, 설치.
대략적인 기준:
  • 설치: 2-5분
  • QuickStart 온보딩: 보통 몇 분
  • 전체 온보딩: 제공자 로그인, 채널 페어링, 데몬 설치, 네트워크 다운로드, Skills 또는 선택 Plugin에 추가 설정이 필요하면 더 오래 걸립니다.
CLI 마법사는 이 타임라인을 처음에 보여줍니다. 선택 단계는 건너뛰고 나중에 openclaw configure로 돌아올 수 있습니다.멈춘 것 같다면 설치 프로그램 멈춤과 막혔습니다의 빠른 디버그 루프를 사용하세요.
상세 출력으로 설치 프로그램을 다시 실행하세요.
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose
상세 출력으로 베타 설치:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose
수정 가능한(git) 설치:
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose
Windows(PowerShell) 동등 명령:
# install.ps1 has no dedicated -Verbose flag yet.
Set-PSDebug -Trace 1
& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
Set-PSDebug -Trace 0
추가 옵션: 설치 프로그램 플래그.
Windows에서 흔한 문제 두 가지:1) npm 오류 spawn git / git을 찾을 수 없음
  • Git for Windows를 설치하고 git이 PATH에 있는지 확인하세요.
  • PowerShell을 닫았다가 다시 열고 설치 프로그램을 다시 실행하세요.
2) 설치 후 openclaw가 인식되지 않음
  • npm 전역 bin 폴더가 PATH에 없습니다.
  • 경로를 확인하세요. 
    npm config get prefix
  • 해당 디렉터리를 사용자 PATH에 추가하세요(Windows에서는 \bin 접미사가 필요하지 않으며, 대부분의 시스템에서는 %AppData%\npm입니다).
  • PATH를 업데이트한 후 PowerShell을 닫았다가 다시 여세요.
데스크톱 설정에는 네이티브 Windows Hub 앱을 사용하세요. 터미널 전용 설정에는 PowerShell 설치 프로그램과 WSL2 Gateway 경로가 모두 지원됩니다. 문서: Windows.
이는 보통 네이티브 Windows 셸의 콘솔 코드 페이지 불일치입니다.증상:
  • system.run/exec 출력에서 중국어가 깨진 문자로 렌더링됨
  • 같은 명령이 다른 터미널 프로필에서는 정상으로 보임
PowerShell의 빠른 우회 방법:
chcp 65001
[Console]::InputEncoding = [System.Text.UTF8Encoding]::new($false)
[Console]::OutputEncoding = [System.Text.UTF8Encoding]::new($false)
$OutputEncoding = [System.Text.UTF8Encoding]::new($false)
그런 다음 Gateway를 다시 시작하고 명령을 재시도하세요.
openclaw gateway restart
최신 OpenClaw에서도 여전히 재현된다면 다음에서 추적하거나 보고하세요.
수정 가능한(git) 설치를 사용하면 전체 소스와 문서를 로컬에 둘 수 있습니다. 그런 다음 봇(또는 Claude/Codex)에게 그 폴더에서 질문하면 저장소를 읽고 정확하게 답할 수 있습니다.
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
자세한 내용: 설치 및 설치 프로그램 플래그.
짧은 답: Linux 가이드를 따른 다음 온보딩을 실행하세요.
어떤 Linux VPS든 사용할 수 있습니다. 서버에 설치한 다음 SSH/Tailscale로 Gateway에 접속하세요.가이드: exe.dev, Hetzner, Fly.io. 원격 접근: Gateway 원격.
일반적인 제공자를 모아 둔 호스팅 허브를 유지하고 있습니다. 하나를 선택해 가이드를 따르세요.클라우드에서의 작동 방식: Gateway는 서버에서 실행되고, 사용자는 노트북/휴대폰에서 Control UI(또는 Tailscale/SSH)를 통해 접근합니다. 상태 + 작업공간은 서버에 있으므로, 호스트를 신뢰 원본으로 취급하고 백업하세요.노드(Mac/iOS/Android/headless)를 해당 클라우드 Gateway에 페어링하여 로컬 화면/카메라/캔버스에 접근하거나, Gateway는 클라우드에 둔 채 노트북에서 명령을 실행할 수 있습니다.허브: 플랫폼. 원격 접근: Gateway 원격. 노드: 노드, 노드 CLI.
짧은 답: 가능하지만 권장하지 않습니다. 업데이트 흐름은 Gateway를 다시 시작할 수 있고(활성 세션이 끊김), 깨끗한 git 체크아웃이 필요할 수 있으며, 확인 프롬프트가 표시될 수 있습니다. 더 안전한 방법은 운영자가 셸에서 업데이트를 실행하는 것입니다.CLI를 사용하세요.
openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart
에이전트에서 반드시 자동화해야 한다면:
openclaw update --yes --no-restart
openclaw gateway restart
문서: 업데이트, 업데이트하기.
openclaw onboard는 권장 설정 경로입니다. 로컬 모드에서는 다음을 안내합니다.
  • 모델/인증 설정(제공자 OAuth, API 키, Anthropic setup-token, LM Studio 같은 로컬 모델 옵션)
  • 작업공간 위치 + 부트스트랩 파일
  • Gateway 설정(bind/port/auth/tailscale)
  • 채널(WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage 및 QQ Bot 같은 번들 채널 Plugin)
  • 데몬 설치(macOS의 LaunchAgent, Linux/WSL2의 systemd 사용자 유닛)
  • 상태 점검 및 Skills 선택
또한 주요 프롬프트가 시작되기 전에 예상 소요 시간을 설정하고, 구성된 모델이 알 수 없거나 인증이 누락된 경우 경고합니다.
아니요. OpenClaw는 API 키(Anthropic/OpenAI/기타) 또는 로컬 전용 모델로 실행할 수 있으므로 데이터가 기기에 남습니다. 구독(Claude Pro/Max 또는 OpenAI Codex)은 해당 제공자를 인증하는 선택적 방법입니다.OpenClaw에서 Anthropic의 실질적인 구분은 다음과 같습니다.
  • Anthropic API 키: 일반 Anthropic API 과금
  • OpenClaw의 Claude CLI / Claude 구독 인증: Anthropic 직원이 이 사용이 다시 허용된다고 알려왔으며, OpenClaw는 Anthropic이 새 정책을 게시하지 않는 한 이 통합에서 claude -p 사용을 승인된 것으로 취급합니다.
장기간 실행되는 Gateway 호스트에는 Anthropic API 키가 여전히 더 예측 가능한 설정입니다. OpenAI Codex OAuth는 OpenClaw 같은 외부 도구에서 명시적으로 지원됩니다.OpenClaw는 Qwen Cloud Coding Plan, MiniMax Coding Plan, Z.AI / GLM Coding Plan을 포함한 다른 호스팅 구독형 옵션도 지원합니다.문서: Anthropic, OpenAI, Qwen Cloud, MiniMax, Z.AI (GLM), 로컬 모델, 모델.
예.Anthropic 직원이 OpenClaw 스타일의 Claude CLI 사용이 다시 허용된다고 알려왔으므로, OpenClaw는 Anthropic이 새 정책을 게시하지 않는 한 이 통합에서 Claude 구독 인증과 claude -p 사용을 승인된 것으로 취급합니다. 가장 예측 가능한 서버 측 설정을 원한다면 대신 Anthropic API 키를 사용하세요.
예.Anthropic 직원이 이 사용이 다시 허용된다고 알려왔으므로, OpenClaw는 Anthropic이 새 정책을 게시하지 않는 한 이 통합에서 Claude CLI 재사용과 claude -p 사용을 승인된 것으로 취급합니다.Anthropic setup-token은 여전히 지원되는 OpenClaw 토큰 경로로 사용할 수 있지만, OpenClaw는 이제 사용 가능할 때 Claude CLI 재사용과 claude -p를 선호합니다. 프로덕션 또는 다중 사용자 워크로드에는 Anthropic API 키 인증이 여전히 더 안전하고 예측 가능한 선택입니다. OpenClaw의 다른 구독형 호스팅 옵션을 원한다면 OpenAI, Qwen / Model Cloud, MiniMax, GLM Models를 참고하세요.
이는 현재 기간의 Anthropic 할당량/속도 제한이 소진되었음을 의미합니다. Claude CLI를 사용하는 경우 기간이 재설정될 때까지 기다리거나 플랜을 업그레이드하세요. Anthropic API 키를 사용하는 경우 Anthropic Console에서 사용량/청구를 확인하고 필요에 따라 한도를 올리세요.메시지가 구체적으로 다음과 같다면: Extra usage is required for long context requests, 요청이 Anthropic의 1M 컨텍스트 창(GA 지원 1M Claude 4.x 모델 또는 레거시 context1m: true 설정)을 사용하려는 것입니다. 이는 자격 증명이 긴 컨텍스트 청구(API 키 청구 또는 Extra Usage가 활성화된 OpenClaw Claude 로그인 경로)에 적합한 경우에만 작동합니다.팁: 제공자가 속도 제한에 걸린 동안에도 OpenClaw가 계속 응답할 수 있도록 대체 모델을 설정하세요. 모델, OAuth, 그리고 /gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context를 참조하세요.
예. OpenClaw에는 번들 Amazon Bedrock (Converse) 제공자가 있습니다. AWS env 마커가 있으면 OpenClaw가 스트리밍/텍스트 Bedrock 카탈로그를 자동으로 검색하고 암시적 amazon-bedrock 제공자로 병합할 수 있습니다. 그렇지 않으면 plugins.entries.amazon-bedrock.config.discovery.enabled를 명시적으로 활성화하거나 수동 제공자 항목을 추가할 수 있습니다. Amazon Bedrock 및 모델 제공자를 참조하세요. 관리형 키 흐름을 선호한다면 Bedrock 앞단의 OpenAI 호환 프록시도 여전히 유효한 옵션입니다.
OpenClaw는 OAuth(ChatGPT 로그인)를 통해 **OpenAI Code (Codex)**를 지원합니다. 일반적인 설정에는 openai/gpt-5.5를 사용하세요. ChatGPT/Codex 구독 인증과 네이티브 Codex 앱 서버 실행입니다. 레거시 Codex GPT 참조는 openclaw doctor --fix로 복구되는 레거시 설정입니다. 직접 OpenAI API 키 접근은 비에이전트 OpenAI API 표면과 정렬된 openai API 키 프로필을 통한 에이전트 모델에 계속 사용할 수 있습니다. 모델 제공자 및 온보딩(CLI)을 참조하세요.
openai는 OpenAI API 키와 ChatGPT/Codex OAuth 모두의 제공자 및 인증 프로필 ID입니다. 레거시 설정과 마이그레이션 경고에서 레거시 OpenAI Codex 접두사를 여전히 볼 수 있습니다. 이전 설정에서는 이를 모델 접두사로도 사용했습니다.
  • openai/gpt-5.5 = 에이전트 턴에 네이티브 Codex 런타임을 사용하는 ChatGPT/Codex 구독 인증
  • 레거시 Codex GPT-5.5 참조 = openclaw doctor --fix로 복구되는 레거시 모델 경로
  • openai/gpt-5.5와 정렬된 openai API 키 프로필 = OpenAI 에이전트 모델용 API 키 인증
  • 레거시 Codex 인증 프로필 ID = openclaw doctor --fix로 마이그레이션되는 레거시 인증 프로필 ID
직접 OpenAI Platform 청구/한도 경로를 원하면 OPENAI_API_KEY를 설정하세요. ChatGPT/Codex 구독 인증을 원하면 openclaw models auth login --provider openai로 로그인하세요. 모델 참조는 openai/gpt-5.5로 유지하세요. 레거시 Codex 모델 참조는 openclaw doctor --fix가 다시 쓰는 레거시 설정입니다.
Codex OAuth는 OpenAI가 관리하는 플랜 종속 할당량 기간을 사용합니다. 실제로 이러한 한도는 동일한 계정에 연결되어 있더라도 ChatGPT 웹사이트/앱 경험과 다를 수 있습니다.OpenClaw는 현재 표시되는 제공자 사용량/할당량 기간을 openclaw models status에 표시할 수 있지만, ChatGPT 웹 권한을 직접 API 접근 권한으로 만들어 내거나 정규화하지 않습니다. 직접 OpenAI Platform 청구/한도 경로를 원하면 API 키와 함께 openai/*를 사용하세요.
예. OpenClaw는 OpenAI Code (Codex) 구독 OAuth를 완전히 지원합니다. OpenAI는 OpenClaw 같은 외부 도구/워크플로에서 구독 OAuth 사용을 명시적으로 허용합니다. 온보딩이 OAuth 흐름을 대신 실행할 수 있습니다.OAuth, 모델 제공자, 온보딩(CLI)을 참조하세요.
Gemini CLI는 openclaw.json의 클라이언트 ID나 비밀이 아니라 Plugin 인증 흐름을 사용합니다.단계:
  1. gemini가 PATH에 있도록 Gemini CLI를 로컬에 설치합니다.
    • Homebrew: brew install gemini-cli
    • npm: npm install -g @google/gemini-cli
  2. Plugin을 활성화합니다: openclaw plugins enable google
  3. 로그인합니다: openclaw models auth login --provider google-gemini-cli --set-default
  4. 로그인 후 기본 모델: google-gemini-cli/gemini-3-flash-preview
  5. 요청이 실패하면 Gateway 호스트에 GOOGLE_CLOUD_PROJECT 또는 GOOGLE_CLOUD_PROJECT_ID를 설정합니다.
이렇게 하면 OAuth 토큰이 Gateway 호스트의 인증 프로필에 저장됩니다. 자세한 내용: 모델 제공자.
일반적으로는 아닙니다. OpenClaw에는 큰 컨텍스트와 강력한 안전성이 필요합니다. 작은 카드는 잘리고 유출됩니다. 꼭 필요하다면 로컬에서 실행할 수 있는 가장 큰 모델 빌드(LM Studio)를 실행하고 /gateway/local-models를 참조하세요. 더 작거나 양자화된 모델은 프롬프트 인젝션 위험을 높입니다. 보안을 참조하세요.
리전 고정 엔드포인트를 선택하세요. OpenRouter는 MiniMax, Kimi, GLM에 대해 미국 호스팅 옵션을 제공합니다. 데이터를 리전 내에 유지하려면 미국 호스팅 변형을 선택하세요. models.mode: "merge"를 사용하면 선택한 리전 제공자를 존중하면서 대체 모델을 계속 사용할 수 있도록 Anthropic/OpenAI도 함께 나열할 수 있습니다.
아니요. OpenClaw는 macOS 또는 Linux(Windows는 WSL2를 통해)에서 실행됩니다. Mac mini는 선택 사항입니다. 일부 사람들은 항상 켜져 있는 호스트로 하나를 사지만, 작은 VPS, 홈 서버, 또는 Raspberry Pi급 장치도 작동합니다.Mac은 macOS 전용 도구에만 필요합니다. iMessage의 경우 Messages에 로그인된 아무 Mac에서 imsg와 함께 iMessage를 사용하세요. Gateway가 Linux나 다른 곳에서 실행되는 경우 channels.imessage.cliPath를 해당 Mac에서 imsg를 실행하는 SSH 래퍼로 설정하세요. 다른 macOS 전용 도구를 원하면 Gateway를 Mac에서 실행하거나 macOS 노드를 페어링하세요.문서: iMessage, 노드, Mac 원격 모드.
Messages에 로그인된 어떤 macOS 기기가 필요합니다. Mac mini일 필요는 없습니다. 어떤 Mac이든 됩니다. imsg와 함께 iMessage를 사용하세요. Gateway는 해당 Mac에서 실행할 수도 있고, SSH 래퍼 cliPath를 사용해 다른 곳에서 실행할 수도 있습니다.일반적인 설정:
  • Gateway를 Linux/VPS에서 실행하고, channels.imessage.cliPath를 Messages에 로그인된 Mac에서 imsg를 실행하는 SSH 래퍼로 설정합니다.
  • 가장 단순한 단일 머신 설정을 원하면 모든 것을 Mac에서 실행합니다.
문서: iMessage, 노드, Mac 원격 모드.
예. Mac mini가 Gateway를 실행할 수 있고, MacBook Pro는 노드(동반 기기)로 연결할 수 있습니다. 노드는 Gateway를 실행하지 않습니다. 대신 해당 기기의 화면/카메라/캔버스 및 system.run 같은 추가 기능을 제공합니다.일반적인 패턴:
  • Mac mini에서 Gateway 실행(항상 켜짐).
  • MacBook Pro가 macOS 앱 또는 노드 호스트를 실행하고 Gateway에 페어링됩니다.
  • 확인하려면 openclaw nodes status / openclaw nodes list를 사용합니다.
문서: 노드, 노드 CLI.
Bun은 권장하지 않습니다. 특히 WhatsApp과 Telegram에서 런타임 버그가 보입니다. 안정적인 Gateway에는 Node를 사용하세요.그래도 Bun을 실험하고 싶다면 WhatsApp/Telegram이 없는 비프로덕션 Gateway에서 하세요.
channels.telegram.allowFrom은 사람 발신자의 Telegram 사용자 ID(숫자)입니다. 봇 사용자 이름이 아닙니다.설정은 숫자 사용자 ID만 요청합니다. 설정에 이미 레거시 @username 항목이 있으면 openclaw doctor --fix가 이를 해석해 볼 수 있습니다.더 안전한 방법(서드파티 봇 없음):
  • 봇에게 DM을 보낸 다음 openclaw logs --follow를 실행하고 from.id를 읽습니다.
공식 Bot API:
  • 봇에게 DM을 보낸 다음 https://api.telegram.org/bot<bot_token>/getUpdates를 호출하고 message.from.id를 읽습니다.
서드파티(개인정보 보호가 더 약함):
  • @userinfobot 또는 @getidsbot에 DM을 보냅니다.
/channels/telegram를 참조하세요.
예, 다중 에이전트 라우팅을 통해 가능합니다. 각 발신자의 WhatsApp DM(피어 kind: "direct", 발신자 E.164 예: +15551234567)을 서로 다른 agentId에 바인딩하면 각 사람이 자신의 워크스페이스와 세션 저장소를 갖게 됩니다. 응답은 여전히 동일한 WhatsApp 계정에서 나오며, DM 접근 제어(channels.whatsapp.dmPolicy / channels.whatsapp.allowFrom)는 WhatsApp 계정별로 전역입니다. 다중 에이전트 라우팅 및 WhatsApp을 참조하세요.
예. 다중 에이전트 라우팅을 사용하세요. 각 에이전트에 고유한 기본 모델을 지정한 다음 인바운드 경로(제공자 계정 또는 특정 피어)를 각 에이전트에 바인딩합니다. 예시 설정은 다중 에이전트 라우팅에 있습니다. 모델 및 설정도 참조하세요.
예. Homebrew는 Linux(Linuxbrew)를 지원합니다. 빠른 설정:
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
echo 'eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"' >> ~/.profile
eval "$(/home/linuxbrew/.linuxbrew/bin/brew shellenv)"
brew install <formula>
systemd로 OpenClaw를 실행하는 경우, 비로그인 셸에서 brew로 설치한 도구가 해석되도록 서비스 PATH에 /home/linuxbrew/.linuxbrew/bin(또는 brew 접두사)이 포함되어 있는지 확인하세요. 최근 빌드는 Linux systemd 서비스에서 일반적인 사용자 bin 디렉터리(예: ~/.local/bin, ~/.npm-global/bin, ~/.local/share/pnpm, ~/.bun/bin)도 앞에 추가하며, 설정된 경우 PNPM_HOME, NPM_CONFIG_PREFIX, BUN_INSTALL, VOLTA_HOME, ASDF_DATA_DIR, NVM_DIR, FNM_DIR를 존중합니다.
  • 수정 가능한(git) 설치: 전체 소스 체크아웃, 편집 가능, 기여자에게 가장 적합합니다. 로컬에서 빌드를 실행하고 코드/문서를 패치할 수 있습니다.
  • npm 설치: 전역 CLI 설치, 저장소 없음, “그냥 실행”하기에 가장 적합합니다. 업데이트는 npm dist-tags에서 가져옵니다.
문서: 시작하기, 업데이트.
예. OpenClaw가 이미 설치되어 있으면 openclaw update --channel ...를 사용하세요. 이는 데이터를 삭제하지 않습니다. OpenClaw 코드 설치만 변경합니다. 상태(~/.openclaw)와 워크스페이스(~/.openclaw/workspace)는 그대로 유지됩니다.npm에서 git으로:
openclaw update --channel dev
git에서 npm으로:
openclaw update --channel stable
--dry-run을 추가하면 계획된 모드 전환을 먼저 미리 볼 수 있습니다. 업데이터는 Doctor 후속 작업을 실행하고, 대상 채널의 Plugin 소스를 새로 고치며, --no-restart를 전달하지 않는 한 Gateway를 다시 시작합니다.설치 프로그램도 두 모드 중 하나를 강제로 지정할 수 있습니다.
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git
curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method npm
백업 팁: 백업 전략을 참조하세요.
짧은 답변: 24/7 안정성을 원한다면 VPS를 사용하세요. 마찰이 가장 적고 절전/재시작을 감수할 수 있다면 로컬에서 실행하세요.노트북(로컬 Gateway)
  • 장점: 서버 비용 없음, 로컬 파일에 직접 접근, 실시간 브라우저 창.
  • 단점: 절전/네트워크 끊김 = 연결 해제, OS 업데이트/재부팅으로 중단, 계속 깨어 있어야 함.
VPS / 클라우드
  • 장점: 상시 가동, 안정적인 네트워크, 노트북 절전 문제 없음, 계속 실행 상태 유지가 더 쉬움.
  • 단점: 보통 헤드리스로 실행됨(스크린샷 사용), 원격 파일 접근만 가능, 업데이트에는 SSH가 필요함.
OpenClaw 관련 참고: WhatsApp/Telegram/Slack/Mattermost/Discord는 모두 VPS에서 문제없이 작동합니다. 실제 트레이드오프는 헤드리스 브라우저와 보이는 창 중 어느 쪽을 선택하느냐뿐입니다. 브라우저를 참조하세요.권장 기본값: 이전에 Gateway 연결 끊김을 겪었다면 VPS를 사용하세요. Mac을 능동적으로 사용 중이고 로컬 파일 접근 또는 보이는 브라우저를 통한 UI 자동화를 원한다면 로컬이 좋습니다.
필수는 아니지만, 안정성과 격리를 위해 권장됩니다.
  • 전용 호스트(VPS/Mac mini/Raspberry Pi): 상시 가동, 절전/재부팅 중단 감소, 더 깔끔한 권한, 계속 실행 상태 유지가 더 쉬움.
  • 공유 노트북/데스크톱: 테스트와 능동적 사용에는 전혀 문제없지만, 머신이 절전 모드로 들어가거나 업데이트될 때 일시 중지를 예상해야 합니다.
두 방식의 장점을 모두 원한다면 Gateway는 전용 호스트에 두고, 노트북을 로컬 화면/카메라/실행 도구용 노드로 페어링하세요. 노드를 참조하세요. 보안 지침은 보안을 읽어 보세요.
OpenClaw는 가볍습니다. 기본 Gateway + 채팅 채널 하나의 경우:
  • 절대 최소: 1 vCPU, 1GB RAM, 디스크 약 500MB.
  • 권장: 여유 용량(로그, 미디어, 여러 채널)을 위해 1-2 vCPU, 2GB RAM 이상. Node 도구와 브라우저 자동화는 리소스를 많이 사용할 수 있습니다.
OS: Ubuntu LTS(또는 최신 Debian/Ubuntu)를 사용하세요. Linux 설치 경로는 그 환경에서 가장 잘 테스트되었습니다.문서: Linux, VPS 호스팅.
예. VM은 VPS와 동일하게 취급하세요. 항상 켜져 있고, 접근 가능하며, Gateway와 활성화한 모든 채널을 실행하기에 충분한 RAM이 필요합니다.기준 지침:
  • 절대 최소: 1 vCPU, 1GB RAM.
  • 권장: 여러 채널, 브라우저 자동화 또는 미디어 도구를 실행한다면 2GB RAM 이상.
  • OS: Ubuntu LTS 또는 다른 최신 Debian/Ubuntu.
Windows를 사용하는 경우 데스크톱 설정에는 Windows Hub를 사용하거나, 다양한 도구와의 호환성을 갖춘 Linux 스타일 Gateway VM을 특별히 원할 때는 WSL2를 사용하세요. Windows, VPS 호스팅를 참조하세요. VM에서 macOS를 실행 중이라면 macOS VM을 참조하세요.

​
관련