OpenClaw 설치 운영 메뉴얼

1. OpenClaw를 한 문장으로 이해하기

OpenClaw는 내 컴퓨터나 서버에서 실행되는 자가 호스팅 AI 비서 Gateway입니다. 채팅앱, 브라우저 대시보드, 모바일 노드, 로컬 파일/브라우저/스케줄러를 한 곳에 묶어 “말하면 실제로 실행하는” 개인 AI 운영 환경을 만듭니다.

2. 참고 이미지·영상 링크

공식 문서/사이트에서 제공하는 자료입니다. soylab.ai 삽입 시 원문 CDN 링크를 그대로 사용합니다.

▶전체 설정 워크스루

VelvetShark, 28분. 설치, 온보딩, 첫 동작하는 비서까지.

▶커뮤니티 쇼케이스 릴

OpenClaw로 구축된 실제 프로젝트와 워크플로를 빠르게 확인.

▶현실 속 프로젝트

채팅 네이티브 코딩 루프, 하드웨어, 개인 자동화 사례.

3. 설치와 온보딩

준비물

• Node.js: Node 24 권장, Node 22.14+ 지원.
• 모델 Provider 인증: OpenAI, Anthropic, Google, OpenRouter 등 API 키나 OAuth.
• 운영 방식 선택: 로컬 Gateway, 원격 Gateway, 또는 WSL2/Linux 서버.

node --version
# v24.x 권장 / v22.14+ 지원

빠른 설치

온보딩이 설정하는 것

1. 모델/인증: API key, OAuth, Claude CLI, Codex OAuth 등.
2. 워크스페이스: 기본값 ~/.openclaw/workspace.
3. Gateway: 포트, bind, 인증, Tailscale 노출.
4. 채널: Discord, Telegram, WhatsApp, Signal 등.
5. Daemon: macOS LaunchAgent, Linux/WSL2 systemd user unit, Windows Scheduled Task.
6. Health check와 권장 Skills 설치.

4. 플랫폼별 설치 포인트

맥미니/macOS

brew install node
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
openclaw gateway status
openclaw dashboard

• 장시간 운영용 맥미니는 LaunchAgent 설치가 편합니다.
• Gateway 재시작: openclaw gateway restart
• 로그: openclaw logs --follow

Windows: WSL2 권장

# PowerShell 관리자
wsl --install
wsl --install -d Ubuntu-24.04

# WSL Ubuntu 안에서 systemd 활성화
sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true
EOF
wsl --shutdown

# WSL 재접속 후
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon

Linux / VPS

curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt-get install -y nodejs
curl -fsSL https://openclaw.ai/install.sh | bash
openclaw onboard --install-daemon
sudo loginctl enable-linger $(whoami)

5. LLM 연결·인증·기본 모델 바꾸기

OpenClaw에서 모델은 provider/model 형식으로 지정합니다. 예: openai/gpt-5.5, openai-codex/gpt-5.5, anthropic/claude-opus-4-6, google/gemini-3-flash-preview.

openclaw models status
openclaw models list
openclaw models list --provider openai
openclaw models set openai/gpt-5.5
openclaw models auth add
openclaw models auth login --provider <provider-id>

기본 모델 설정

openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
openclaw config set agents.defaults.model.primary anthropic/claude-opus-4-6
openclaw gateway restart

인증/키 변경의 기본 원칙

• 새 provider로 바꿀 때는 먼저 openclaw models auth login 또는 openclaw onboard/openclaw configure로 인증을 준비합니다.
• 그다음 agents.defaults.model.primary를 원하는 model ref로 바꿉니다.
• Control UI의 Config 탭에서도 같은 설정을 폼/Raw JSON으로 바꿀 수 있습니다.
• config 변경 후에는 openclaw doctor, openclaw gateway restart, openclaw models status로 확인합니다.

6. OpenAI / Codex 인증

API key 경로

openclaw onboard --auth-choice openai-api-key
# 또는
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
openclaw models list --provider openai
openclaw config set agents.defaults.model.primary openai/gpt-5.5

Codex OAuth 경로

openclaw onboard --auth-choice openai-codex
# 또는
openclaw models auth login --provider openai-codex
openclaw models auth login --provider openai-codex --device-code
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5

이미지 생성 기본 모델

openclaw config set agents.defaults.imageGenerationModel.primary openai/gpt-image-2

7. Anthropic / Claude 인증

Anthropic은 직접 API key와 Claude CLI 로그인 재사용을 지원합니다.

API key

openclaw onboard
# 선택: Anthropic API key
# 또는
openclaw onboard --anthropic-api-key "$ANTHROPIC_API_KEY"
openclaw models list --provider anthropic
openclaw config set agents.defaults.model.primary anthropic/claude-opus-4-6

Claude CLI 재사용

claude --version
openclaw onboard
# 선택: Claude CLI
openclaw models list --provider anthropic

Thinking / Cache 설정 예시

openclaw config set 'agents.defaults.models."anthropic/claude-opus-4-6".params.thinking' adaptive
openclaw config set 'agents.defaults.models."anthropic/claude-opus-4-6".params.cacheRetention' long

8. Gemini / OpenRouter / 기타 Provider

openclaw onboard --auth-choice gemini-api-key
openclaw models auth login --provider google-gemini-cli --set-default
openclaw models scan
openclaw models set openrouter/auto

9. Skills: 설치·우선순위·비활성화·API 키

Skill은 에이전트에게 특정 도구나 반복 업무 절차를 가르치는 SKILL.md 폴더입니다. OpenClaw는 AgentSkills 호환 구조를 사용합니다.

Skill 로드 우선순위

1. <workspace>/skills — 가장 높음
2. <workspace>/.agents/skills
3. ~/.agents/skills
4. ~/.openclaw/skills
5. 번들 Skills
6. skills.load.extraDirs — 가장 낮음

ClawHub에서 설치

openclaw skills install <skill-slug>
openclaw skills update --all
openclaw skills list
openclaw skills inspect <skill-name>

에이전트별 Skill allowlist

{
  skills: {
    load: { watch: true, extraDirs: ["~/Projects/my-skills"] },
    install: { preferBrew: true, nodeManager: "npm" },
    entries: {
      "image-lab": {
        enabled: true,
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },
        env: { GEMINI_API_KEY: "..." }
      },
      sag: { enabled: false }
    }
  },
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" },
      { id: "docs", skills: ["docs-search"] },
      { id: "locked-down", skills: [] }
    ]
  }
}

Skill 파일 기본 형태

---
name: image-lab
description: Generate or edit images via a provider-backed workflow
metadata: { "openclaw": { "requires": { "bins": ["uv"], "env": ["GEMINI_API_KEY"] }, "primaryEnv": "GEMINI_API_KEY" } }
---

사용법, 주의사항, 예시 명령을 여기에 적습니다.

10. Gateway 운영

openclaw gateway --port 18789
openclaw gateway --force
openclaw channels status --probe
openclaw health

11. localhost Control UI 접속과 기능

openclaw dashboard
openclaw dashboard --no-open
http://127.0.0.1:18789/
http://localhost:18789/

Control UI에서 할 수 있는 일

새 브라우저/기기 pairing

openclaw devices list
openclaw devices approve <requestId>

12. 업데이트·재설치·리셋

업데이트

openclaw update
openclaw update --dry-run
openclaw update --channel beta
openclaw update --tag main
openclaw update --no-restart
openclaw doctor
openclaw gateway restart
openclaw health

Reset / 재설치

openclaw backup create
openclaw reset --dry-run
openclaw reset --scope config --yes --non-interactive
openclaw reset --scope config+creds+sessions --yes --non-interactive
openclaw reset --scope full --yes --non-interactive
openclaw uninstall

13. 문제 해결 60초 루틴

openclaw status
openclaw status --all
openclaw gateway probe
openclaw gateway status
openclaw doctor
openclaw channels status --probe
openclaw logs --follow

14. 공식 문서 링크

• 한국어 시작하기
• 한국어 온보딩 CLI
• Control UI
• Skills
• 모델 Provider
• OpenAI Provider
• Anthropic Provider
• OpenClaw 공식 사이트