자주 묻는 질문: 최초 실행 설정

사용자 머신을 볼 수 있는 로컬 AI 에이전트를 사용하세요. Discord에 질문하는 것보다 훨씬 효과적입니다. 대부분의 "막혔어요" 사례는 원격 도움 제공자가 확인할 수 없는 로컬 설정 또는 환경 문제이기 때문입니다.

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

이러한 도구는 저장소를 읽고, 명령을 실행하고, 로그를 검사하고, 머신 수준 설정(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/에이전트 상태와 기본 설정의 빠른 스냅샷입니다.
• openclaw models status: 제공자 인증과 모델 사용 가능 여부를 확인합니다.
• openclaw doctor: 일반적인 설정/상태 문제를 검증하고 복구합니다.

그 밖에 유용한 CLI 확인 명령: openclaw status --all, openclaw logs --follow, openclaw gateway status, openclaw health --verbose.

빠른 디버그 루프: 무언가 고장 났을 때 첫 60초. 설치 문서: 설치, 설치 프로그램 플래그, 업데이트.

일반적인 Heartbeat 건너뛰기 이유:

• quiet-hours: 설정된 활성 시간 창 밖입니다.
• empty-heartbeat-file: HEARTBEAT.md가 있지만 빈 내용/헤더만 있는 스캐폴딩만 포함합니다.
• no-tasks-due: HEARTBEAT.md 작업 모드가 활성화되었지만 아직 만료된 작업 간격이 없습니다.
• alerts-disabled: 모든 Heartbeat 표시가 비활성화되어 있습니다(showOk, showAlerts, useIndicator가 모두 꺼짐).

작업 모드에서는 실제 Heartbeat 실행이 완료된 후에만 예정 타임스탬프가 진행됩니다. 건너뛴 실행은 작업을 완료된 것으로 표시하지 않습니다.

문서: Heartbeat, 자동화 및 작업.

저장소는 소스에서 실행하고 온보딩을 사용하는 방법을 권장합니다.

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/를 엽니다.
• 공유 비밀 인증을 요청하면 설정된 토큰 또는 비밀번호를 Control UI 설정에 붙여 넣습니다.
• 토큰 소스: gateway.auth.token(또는 OPENCLAW_GATEWAY_TOKEN).
• 비밀번호 소스: gateway.auth.password(또는 OPENCLAW_GATEWAY_PASSWORD).
• 아직 공유 비밀이 설정되지 않았다면 openclaw doctor --generate-gateway-token으로 토큰을 생성합니다.

localhost가 아닌 경우:

• Tailscale Serve(권장): 바인드는 loopback으로 유지하고, openclaw gateway --tailscale serve를 실행한 뒤 https://<magicdns>/를 엽니다. gateway.auth.allowTailscale이 true이면 ID 헤더가 Control UI/WebSocket 인증을 충족합니다(공유 비밀을 붙여 넣을 필요 없음, 신뢰할 수 있는 Gateway 호스트라고 가정). HTTP APIs는 의도적으로 private-ingress none 또는 trusted-proxy HTTP 인증을 사용하지 않는 한 여전히 공유 비밀 인증이 필요합니다. 같은 클라이언트에서 동시에 발생한 잘못된 Serve 인증 시도는 실패 인증 제한기가 기록하기 전에 직렬화되므로, 두 번째 잘못된 재시도에서 이미 retry later가 표시될 수 있습니다.
• Tailnet 바인드: openclaw gateway --bind tailnet --token "<token>"을 실행하거나 비밀번호 인증을 설정하고, http://<tailscale-ip>:18789/를 연 다음 대시보드 설정에 일치하는 공유 비밀을 붙여 넣습니다.
• ID 인식 리버스 프록시: 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/를 엽니다. 터널을 통해서도 공유 비밀 인증이 적용됩니다. 요청되면 설정된 토큰 또는 비밀번호를 붙여 넣으세요.

바인드 모드와 인증 세부 정보는 대시보드와 웹 표면을 참조하세요.

서로 다른 계층을 제어합니다.

• approvals.exec: 승인 프롬프트를 채팅 대상으로 전달합니다.
• channels.<channel>.execApprovals: 해당 채널이 exec 승인용 네이티브 승인 클라이언트로 동작하게 합니다.

호스트 exec 정책이 여전히 실제 승인 게이트입니다. 채팅 설정은 승인 프롬프트가 어디에 표시되고 사람들이 어떻게 응답할 수 있는지만 제어합니다.

대부분의 설정에서는 둘 다 필요하지 않습니다.

• 채팅이 이미 명령과 답장을 지원한다면, 같은 채팅의 /approve가 공유 경로를 통해 작동합니다.
• 지원되는 네이티브 채널이 승인자를 안전하게 추론할 수 있으면, OpenClaw는 이제 channels.<channel>.execApprovals.enabled가 설정되지 않았거나 "auto"일 때 DM 우선 네이티브 승인을 자동으로 활성화합니다.
• 네이티브 승인 카드/버튼을 사용할 수 있으면 해당 네이티브 UI가 기본 경로입니다. 도구 결과가 채팅 승인을 사용할 수 없거나 수동 승인이 유일한 경로라고 말하는 경우에만 에이전트가 수동 /approve 명령을 포함해야 합니다.
• 프롬프트를 다른 채팅이나 명시적 운영 방에도 전달해야 할 때만 approvals.exec를 사용하세요.
• 승인 프롬프트를 원래 방/주제로 다시 게시하길 명시적으로 원하는 경우에만 channels.<channel>.execApprovals.target: "channel" 또는 "both"를 사용하세요.
• Plugin 승인은 또 별개입니다. 기본적으로 같은 채팅의 /approve, 선택적 approvals.plugin 전달을 사용하며, 일부 네이티브 채널만 그 위에 Plugin 승인 네이티브 처리를 유지합니다.

짧게 말하면 전달은 라우팅을 위한 것이고, 네이티브 클라이언트 설정은 더 풍부한 채널별 UX를 위한 것입니다. Exec 승인을 참조하세요.

Node >= 22가 필요합니다. pnpm을 권장합니다. Gateway에는 Bun을 권장하지 않습니다.

예. Gateway는 가볍습니다. 문서에서는 개인 사용에 512MB-1GB RAM, 1 core, 약 500MB 디스크면 충분하다고 하며, Raspberry Pi 4에서 실행할 수 있음을 명시합니다.

추가 여유 공간(로그, 미디어, 기타 서비스)을 원한다면 2GB를 권장하지만, 엄격한 최소 요구 사항은 아닙니다.

팁: 작은 Pi/VPS에서 Gateway를 호스팅하고, 노트북/휴대폰의 노드를 페어링하여 로컬 화면/카메라/캔버스 또는 명령 실행을 사용할 수 있습니다. 노드를 참조하세요.

짧게 말하면 작동하지만, 거친 부분을 예상하세요.

• 64-bit OS를 사용하고 Node >= 22를 유지하세요.
• 로그를 확인하고 빠르게 업데이트할 수 있도록 해킹 가능한(git) 설치를 선호하세요.
• 채널/Skills 없이 시작한 다음 하나씩 추가하세요.
• 이상한 바이너리 문제가 발생하면 보통 ARM 호환성 문제입니다.

문서: Linux, 설치.

해당 화면은 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를 가리키는지 확인하세요. 원격 접근을 참조하세요.

예. 상태 디렉터리와 워크스페이스를 복사한 다음 Doctor를 한 번 실행하세요. 두 위치를 모두 복사하면 봇을 "정확히 동일하게"(메모리, 세션 기록, 인증, 채널 상태) 유지할 수 있습니다.

1. 새 머신에 OpenClaw를 설치합니다.
2. 이전 머신에서 $OPENCLAW_STATE_DIR(기본값: ~/.openclaw)을 복사합니다.
3. 워크스페이스(기본값: ~/.openclaw/workspace)를 복사합니다.
4. openclaw doctor를 실행하고 Gateway 서비스를 다시 시작합니다.

그러면 설정, 인증 프로필, WhatsApp 자격 증명, 세션, 메모리가 보존됩니다. 원격 모드라면 Gateway 호스트가 세션 저장소와 워크스페이스를 소유한다는 점을 기억하세요.

중요: 워크스페이스만 GitHub에 커밋/푸시하면 메모리 + 부트스트랩 파일은 백업되지만, 세션 기록이나 인증은 백업되지 않습니다. 해당 항목은 ~/.openclaw/ 아래에 있습니다 (예: ~/.openclaw/agents/<agentId>/sessions/).

관련 항목: 마이그레이션, 디스크에서 항목이 저장되는 위치, 에이전트 워크스페이스, 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

Stable과 beta는 별도의 코드 라인이 아니라 npm dist-tag입니다.

• latest = stable
• beta = 테스트용 초기 빌드

보통 stable 릴리스는 먼저 beta에 올라간 다음, 명시적인 승격 단계에서 같은 버전을 latest로 이동합니다. Maintainer는 필요할 때 바로 latest에 게시할 수도 있습니다. 그래서 승격 후에는 beta와 stable이 같은 버전을 가리킬 수 있습니다.

변경 사항 보기: https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md

설치 한 줄 명령과 beta와 dev의 차이는 아래 아코디언을 참고하세요.

Beta는 npm dist-tag beta입니다(승격 후에는 latest와 같을 수 있음). Dev는 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. Dev 채널(git checkout):

openclaw update --channel dev

이 명령은 main 브랜치로 전환하고 소스에서 업데이트합니다.

2. 수정 가능한 설치(설치 관리자 사이트에서):

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

이 방식은 편집할 수 있는 로컬 repo를 제공하며, 이후 git으로 업데이트할 수 있습니다.

직접 깨끗하게 clone하고 싶다면 다음을 사용하세요.

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install
pnpm build

문서: 업데이트, 개발 채널, 설치.

대략적인 안내:

• 설치: 2-5분
• 온보딩: 구성하는 채널/모델 수에 따라 5-15분

멈춘 것 같다면 설치 관리자 멈춤과 막혔습니다의 빠른 디버그 루프를 사용하세요.

자세한 출력으로 설치 관리자를 다시 실행하세요.

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose

자세한 출력으로 beta 설치:

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 error spawn git / git not found

• Git for Windows를 설치하고 git이 PATH에 있는지 확인하세요.
• PowerShell을 닫았다가 다시 열고 설치 관리자를 다시 실행하세요.

2) 설치 후 openclaw가 인식되지 않음

• npm 전역 bin 폴더가 PATH에 없습니다.

• 경로를 확인하세요.

  npm config get prefix
  

• 해당 디렉터리를 사용자 PATH에 추가하세요(Windows에서는 \bin 접미사가 필요 없으며, 대부분의 시스템에서는 %AppData%\npm입니다).

• PATH를 업데이트한 뒤 PowerShell을 닫았다가 다시 여세요.

가장 매끄러운 Windows 설정을 원한다면 네이티브 Windows 대신 WSL2를 사용하세요. 문서: Windows.

이는 보통 네이티브 Windows 셸의 콘솔 코드 페이지 불일치입니다.

증상:

• system.run/exec 출력에서 중국어가 mojibake로 표시됨
• 같은 명령이 다른 터미널 프로필에서는 정상적으로 보임

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에서도 여전히 재현된다면 다음에서 추적/보고하세요.

• Issue #30640

수정 가능한(git) 설치를 사용해 전체 소스와 문서를 로컬에 둔 다음, bot(또는 Claude/Codex)에게 그 폴더에서 질문하세요. 그러면 repo를 읽고 정확하게 답할 수 있습니다.

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

자세한 내용: 설치 및 설치 관리자 플래그.

짧은 답: Linux 가이드를 따른 다음 온보딩을 실행하세요.

• Linux 빠른 경로 + 서비스 설치: Linux.
• 전체 안내: 시작하기.
• 설치 관리자 + 업데이트: 설치 및 업데이트.

어떤 Linux VPS든 사용할 수 있습니다. 서버에 설치한 다음 SSH/Tailscale을 사용해 Gateway에 접속하세요.

가이드: exe.dev, Hetzner, Fly.io. 원격 접속: Gateway 원격.

일반적인 provider를 모아 둔 호스팅 허브를 제공합니다. 하나를 선택해 가이드를 따르세요.

• VPS 호스팅 (모든 provider를 한곳에 모음)
• Fly.io
• Hetzner
• exe.dev

cloud에서 동작하는 방식: Gateway는 서버에서 실행되고, 노트북/휴대폰에서 Control UI(또는 Tailscale/SSH)를 통해 접속합니다. 상태와 workspace는 서버에 있으므로, 호스트를 source of truth로 취급하고 백업하세요.

nodes(Mac/iOS/Android/headless)를 해당 cloud Gateway에 페어링하여 로컬 screen/camera/canvas에 접근하거나, Gateway는 cloud에 둔 채 노트북에서 명령을 실행할 수 있습니다.

허브: 플랫폼. 원격 접속: Gateway 원격. Nodes: Nodes, Nodes CLI.

짧은 답: 가능하지만 권장하지 않습니다. 업데이트 흐름은 Gateway를 재시작할 수 있고(활성 세션이 끊김), 깨끗한 git checkout이 필요할 수 있으며, 확인을 요청할 수 있습니다. 더 안전한 방법은 운영자가 셸에서 업데이트를 실행하는 것입니다.

CLI를 사용하세요.

openclaw update
openclaw update status
openclaw update --channel stable|beta|dev
openclaw update --tag <dist-tag|version>
openclaw update --no-restart

agent에서 자동화해야 한다면:

openclaw update --yes --no-restart
openclaw gateway restart

문서: 업데이트, 업데이트하기.

openclaw onboard는 권장 설정 경로입니다. 로컬 모드에서는 다음을 안내합니다.

• 모델/인증 설정(provider OAuth, API 키, Anthropic setup-token, LM Studio 같은 로컬 모델 옵션 포함)
• Workspace 위치 + 부트스트랩 파일
• Gateway 설정(bind/port/auth/tailscale)
• 채널(WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, QQ Bot 같은 번들 채널 Plugin 포함)
• Daemon 설치(macOS의 LaunchAgent, Linux/WSL2의 systemd user unit)
• 상태 확인 및 skills 선택

구성된 모델을 알 수 없거나 인증이 누락된 경우에도 경고합니다.

아니요. API 키(Anthropic/OpenAI/기타) 또는 로컬 전용 모델로 OpenClaw를 실행할 수 있어 데이터가 기기에 머뭅니다. 구독(Claude Pro/Max 또는 OpenAI Codex)은 해당 provider를 인증하는 선택적 방법입니다.

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, GLM Models, 로컬 모델, 모델.

예.

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를 선호합니다. 프로덕션 또는 다중 사용자 workload에서는 Anthropic API 키 인증이 여전히 더 안전하고 예측 가능한 선택입니다. OpenClaw에서 다른 구독형 호스팅 옵션을 원한다면 OpenAI, Qwen / Model Cloud, MiniMax, GLM Models을 참고하세요.

이는 현재 기간의 Anthropic 할당량/rate limit이 소진되었다는 뜻입니다. Claude CLI를 사용하는 경우 기간이 재설정될 때까지 기다리거나 plan을 업그레이드하세요. Anthropic API 키를 사용하는 경우 Anthropic Console에서 usage/billing을 확인하고 필요에 따라 한도를 올리세요.

메시지가 구체적으로 다음과 같다면: Extra usage is required for long context requests, 해당 요청은 Anthropic의 1M 컨텍스트 베타(context1m: true)를 사용하려는 것입니다. 이는 자격 증명이 긴 컨텍스트 과금(API 키 과금 또는 Extra Usage가 활성화된 OpenClaw Claude 로그인 경로)에 적격한 경우에만 작동합니다.

팁: 대체 모델을 설정하면 제공자가 속도 제한에 걸려도 OpenClaw가 계속 응답할 수 있습니다. Models, 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)**를 지원합니다. 일반적인 설정에는 agentRuntime.id: "codex"와 함께 openai/gpt-5.5를 사용하세요. 이는 ChatGPT/Codex 구독 인증과 네이티브 Codex 앱 서버 실행을 함께 사용합니다. 기본 Codex 런타임을 통해 Codex OAuth를 사용하려는 경우에만 openai-codex/gpt-5.5를 사용하세요. 직접 OpenAI API 키 액세스는 비에이전트 OpenAI API 표면과 정렬된 openai-codex API 키 프로필을 통한 에이전트 모델에 계속 사용할 수 있습니다. 모델 제공자 및 온보딩(CLI)을 참조하세요.

openai-codex는 ChatGPT/Codex OAuth의 제공자 및 인증 프로필 id입니다. 이전 설정에서는 이를 모델 접두사로도 사용했습니다.

• openai/gpt-5.5 = 에이전트 턴에 네이티브 Codex 런타임을 사용하는 ChatGPT/Codex 구독 인증
• openai-codex/gpt-5.5 = openclaw doctor --fix로 복구되는 레거시 모델 경로
• openai/gpt-5.5와 정렬된 openai-codex API 키 프로필 = OpenAI 에이전트 모델용 API 키 인증
• openai-codex:... = 모델 참조가 아니라 인증 프로필 id

직접 OpenAI Platform 과금/제한 경로를 원한다면 OPENAI_API_KEY를 설정하세요. ChatGPT/Codex 구독 인증을 원한다면 openclaw models auth login --provider openai-codex로 로그인하세요. 모델 참조는 openai/gpt-5.5로 유지하세요. openai-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나 secret이 아니라 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의 경우 BlueBubbles를 사용하세요(권장). BlueBubbles 서버는 어떤 Mac에서든 실행되며, Gateway는 Linux나 다른 곳에서 실행할 수 있습니다. 다른 macOS 전용 도구를 원한다면 Gateway를 Mac에서 실행하거나 macOS Node를 페어링하세요.

문서: BlueBubbles, Nodes, Mac 원격 모드.

메시지에 로그인된 어떤 macOS 기기가 필요합니다. 반드시 Mac mini일 필요는 없습니다. 어떤 Mac이든 작동합니다. iMessage에는 BlueBubbles를 사용하세요(권장). BlueBubbles 서버는 macOS에서 실행되고, Gateway는 Linux나 다른 곳에서 실행할 수 있습니다.

일반적인 설정:

• Gateway를 Linux/VPS에서 실행하고, 메시지에 로그인된 아무 Mac에서 BlueBubbles 서버를 실행합니다.
• 가장 단순한 단일 머신 설정을 원한다면 모든 것을 Mac에서 실행합니다.

문서: BlueBubbles, Nodes, Mac 원격 모드.

예. Mac mini는 Gateway를 실행할 수 있고, MacBook Pro는 Node(동반 기기)로 연결할 수 있습니다. Nodes는 Gateway를 실행하지 않습니다. 대신 해당 기기의 화면/카메라/canvas 및 system.run 같은 추가 기능을 제공합니다.

일반적인 패턴:

• Mac mini에서 Gateway를 실행합니다(항상 켜짐).
• MacBook Pro는 macOS 앱 또는 Node 호스트를 실행하고 Gateway에 페어링합니다.
• openclaw nodes status / openclaw nodes list로 확인합니다.

문서: Nodes, Nodes 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/Pi): 항상 켜짐, 절전/재부팅으로 인한 중단이 적음, 권한이 더 깔끔함, 계속 실행 상태로 유지하기 쉬움.
• 공유 노트북/데스크톱: 테스트와 능동적인 사용에는 전혀 문제없지만, 머신이 절전 모드로 들어가거나 업데이트될 때 일시 중지를 예상해야 합니다.

두 방식의 장점을 모두 원한다면 Gateway는 전용 호스트에 두고, 노트북을 로컬 화면/카메라/실행 도구용 Node로 페어링하세요. Nodes를 참고하세요. 보안 지침은 보안을 읽어보세요.

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를 사용 중이라면 WSL2가 가장 쉬운 VM 방식 설정이며 도구 호환성이 가장 좋습니다. Windows, VPS 호스팅을 참고하세요. macOS를 VM에서 실행 중이라면 macOS VM을 참고하세요.