OpenClaw 완전 가이드: 설치부터 마스터까지

~/.openclaw/
├── openclaw.json          # 주 설정 파일 (JSON5)
├── .env                   # API 키 및 민감 정보
├── workspace/             # 기본 작업 공간
│   ├── SOUL.md            # 어시스턴트 인격 정의
│   ├── MEMORY.md          # 장기 기억
│   ├── USER.md            # 사용자 프로필
│   ├── AGENTS.md          # 작업 공간 지시
│   └── skills/            # 작업 공간 스킬
├── skills/                # 전역 스킬 디렉토리
├── agents/                # 다중 Agent 구성
│   └── main/              # 메인 Agent
│       └── agent/
│           └── auth-profiles.json  # 인증 구성
└── credentials/           # 채널 자격 증명

// ~/.openclaw/openclaw.json
{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      model: "claude-sonnet-4-20250514",
      thinkingDefault: "high",
      verboseDefault: "off",
      timeoutSeconds: 900,
      compaction: {
        mode: "auto",
      },
    },
  },
  channels: {
    telegram: {
      botToken: "${TELEGRAM_BOT_TOKEN}",
      allowFrom: ["123456789"],
    },
  },
  models: {
    providers: {
      anthropic: {
        apiKey: "${ANTHROPIC_API_KEY}",
      },
    },
  },
}

{
  models: {
    providers: {
      anthropic: {
        apiKey: "${ANTHROPIC_API_KEY}",
        apiType: "anthropic",
      },
      openai: {
        apiKey: "${OPENAI_API_KEY}",
        apiType: "openai",
      },
      openrouter: {
        apiKey: "${OPENROUTER_API_KEY}",
        baseUrl: "https://openrouter.ai/api/v1",
        apiType: "openai",
      },
      // 커스텀 엔드포인트 (vLLM / Ollama 등 연결)
      local: {
        baseUrl: "http://localhost:11434/v1",
        apiKey: "ollama",
        apiType: "openai",
      },
    },
  },
  agents: {
    defaults: {
      // 단일 모델
      model: "claude-sonnet-4-20250514",
      // 또는 장애 조치가 있는 모델 체인
      // model: {
      //   primary: "claude-sonnet-4-20250514",
      //   fallbacks: ["gpt-4o", "gemini-2.0-flash"],
      // },
    },
  },
}

// 1. 단순 문자열
"apiKey": "sk-ant-xxx..."

// 2. 환경 변수 참조
"apiKey": "${ANTHROPIC_API_KEY}"

// 3. SecretRef 객체 (고급)
"apiKey": { "source": "env", "id": "ANTHROPIC_API_KEY" }

{
  channels: {
    telegram: {
      botToken: "${TELEGRAM_BOT_TOKEN}",
      allowFrom: ["123456789", "987654321"],  // 허용된 사용자 ID
    },
  },
}

{
  channels: {
    telegram: {
      dmPolicy: "open",
      allowFrom: ["*"],
    },
  },
}

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    shopping: { workspace: "~/.openclaw/shopping-agent" },
    coding: { workspace: "~/.openclaw/coding-agent" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+155****0123"],
      agent: "shopping",  // WhatsApp 메시지를 쇼핑 Agent로 라우팅
    },
    discord: {
      token: "${DISCORD_BOT_TOKEN}",
      allowFrom: ["123456789"],
      agent: "coding",  // Discord 메시지를 코딩 Agent로 라우팅
    },
  },
}

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      // 다중 Agent 시나리오에서 workspace-{agentId} 사용
    },
  },
}

{
  agents: {
    defaults: {
      sandbox: {
        // 샌드박스 모드: non-main 세션은 샌드박스에서 실행
        mode: "non-main",
        backend: "docker",  // docker / ssh / openshell
        docker: {
          image: "openclaw/sandbox:latest",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      providers: {
        elevenlabs: {
          voiceId: "21m00Tcm4TlvDq8ikWAM",
          modelId: "eleven_multilingual_v2",
        },
        // 또는 시스템 TTS 사용
        microsoft: {
          voice: "en-US-AriaNeural",
        },
      },
    },
  },
}

{
  mcp: {
    servers: {
      "my-server": {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
        env: {},
        cwd: "/tmp",
        // 또는 HTTP 전송
        // url: "https://mcp.example.com/sse",
        tools: {
          include: ["read_file", "write_file"],
          // exclude: ["dangerous_tool"],
        },
      },
    },
  },
}

{
  session: {
    reset: {
      mode: "daily",        // "daily" / "idle" / 둘 다
      atHour: 0,            // daily 모드: 매일 0시에 재설정
      idleMinutes: 30,      // idle 모드: 30분 비활동 시 재설정
    },
    // 또는 간소화된 형식 사용
    // resetTriggers: ["daily", "idle"],
  },
}

{
  // 설정 파일에 정의
  // 또는 openclaw 명령을 통해 관리
}

{
  gateway: {
    auth: {
      token: "${HERMES_GATEWAY_TOKEN}",  // Gateway 접근 토큰
    },
  },
}

/status              Gateway 및 세션 상태 확인
/new                 새 세션 시작
/reset               현재 세션 재설정
/compact             컨텍스트 압축
/think <level>       사고 깊이 설정 (off/low/medium/high)
/verbose on|off      상세 출력 켜기/끄기
/trace on|off        호출 추적 켜기/끄기
/usage off|tokens|full  Token 사용량 확인
/restart             Gateway 재시작
/activation mention|always  활성화 모드 설정

{
  agents: {
    defaults: {
      model: {
        primary: "claude-sonnet-4-20250514",
        fallbacks: ["gpt-4o", "gemini-2.0-flash"],
      },
    },
  },
}

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    work: {
      workspace: "~/.openclaw/work-agent",
      model: "claude-sonnet-4-20250514",
    },
    personal: {
      workspace: "~/.openclaw/personal-agent",
      model: "gpt-4o",
    },
  },
  channels: {
    slack: {
      botToken: "${SLACK_BOT_TOKEN}",
      agent: "work",  // Slack -> 업무 Agent
    },
    whatsapp: {
      allowFrom: ["+155****0123"],
      agent: "personal",  // WhatsApp -> 개인 Agent
    },
  },
}

{
  agents: {
    defaults: {
      compaction: {
        mode: "auto",     // "auto" / "off"
        model: "gpt-4o-mini",  // 압축용 모델 (선택 사항)
      },
    },
  },
}

/think high
마이크로서비스 아키텍처 방안 설계해 줘

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",
        backend: "docker",
      },
    },
  },
  gateway: {
    auth: {
      token: "${GATEWAY_TOKEN}",
    },
  },
  channels: {
    telegram: {
      dmPolicy: "pairing",
      allowFrom: ["123456789"],
    },
  },
}

{
  agents: {
    defaults: {
      timeoutSeconds: 900,  // 최대 실행 시간 (초)
      humanDelay: {
        mode: "natural",   // "natural" / "custom" / "off"
        minMs: 500,        // 커스텀 모드에서 최소 지연
        maxMs: 2000,       // 최대 지연
      },
    },
  },
}

# 설치 및 업데이트
openclaw onboard              # Onboarding 마법사
openclaw onboard --install-daemon  # 데몬 설치
openclaw update               # 최신 버전으로 업데이트
openclaw update --channel dev  # 개발 버전으로 전환
openclaw doctor               # 헬스 체크

# Gateway 제어
openclaw gateway status       # 상태 확인
openclaw gateway stop         # 중지
openclaw gateway --port 18789 --verbose  # 포그라운드 디버그
openclaw dashboard            # 제어판 열기

# 구성
openclaw configure            # 구성 마법사
openclaw config get KEY       # 설정 읽기
openclaw config set KEY VAL   # 설정 지정
openclaw config unset KEY     # 설정 삭제

# 메시지 및 대화
openclaw message send --target +123 --message "Hello"  # 메시지 전송
openclaw agent --message "질문" --thinking high         # 어시스턴트와 대화

# 보안
openclaw pairing approve <channel> <code>  # DM 페어링 승인

# 마이그레이션 (Hermes에서 OpenClaw로)
# 참조 https://docs.openclaw.ai/install/migrating/migrating-from-hermes