OpenClaw 설정 가이드: 구성 파일 관리 및 최적화 방법

새로운 도구를 설치하고 나서 가장 먼저 마주하는 벽이 바로 설정이죠. 분명 가이드대로 한 것 같은데 왜 동작하지 않는지, 설정 파일은 대체 어디에 숨어 있는지 답답할 때가 많습니다.

OpenClaw를 여러분의 입맛에 딱 맞게 길들이기 위해 꼭 알아야 할 핵심 설정 방법들을 정리해 드릴게요. 이 가이드를 따라가다 보면 복잡해 보이던 시스템도 금방 익숙해질 거예요.

설정 파일 형식은 무엇이고 어디에 있나요?

OpenClaw는 $OPENCLAW_CONFIG_PATH 경로에서 JSON5 형식의 설정 파일을 읽어와요. 기본 경로는 ~/.openclaw/openclaw.json입니다.

만약 이 파일이 없더라도 걱정하지 마세요. ~/.openclaw/workspace를 기본 워크스페이스로 사용하는 등 안전한 기본값들을 알아서 적용하니까요.

gateway.bind를 “lan”이나 “tailnet”으로 설정했는데 아무것도 응답하지 않거나 권한 오류가 떠요

루프백(loopback)이 아닌 주소로 바인딩할 때는 인증이 필수예요. gateway.auth.mode와 gateway.auth.token을 설정하거나 OPENCLAW_GATEWAY_TOKEN 환경 변수를 사용해야 합니다.

{
  gateway: {
    bind: "lan",
    auth: {
      mode: "token",
      token: "replace-me"
    }
  }
}

왜 이제 localhost에서도 토큰이 필요한가요?

설정 마법사(wizard)가 기본적으로 Gateway 토큰을 생성하기 때문이에요. 루프백 환경이라도 로컬 WS 클라이언트가 반드시 인증을 거치도록 해서, 다른 로컬 프로세스가 함부로 Gateway를 호출하는 것을 막아줍니다.

만약 로컬에서 인증 없이 완전히 개방된 상태로 쓰고 싶다면 설정에서 gateway.auth 섹션을 삭제하면 돼요.

설정을 변경한 후에 다시 시작해야 하나요?

Gateway는 설정 파일을 계속 감시하고 있다가 실시간으로 반영하는 hot-reload를 지원해요.

• gateway.reload.mode: "hybrid" (기본값): 안전한 변경 사항은 즉시 적용하고, 중요한 변경 사항이 있을 때만 재시작합니다.
• hot, restart, off 모드도 선택해서 사용할 수 있어요.

웹 검색(및 웹 페치) 기능은 어떻게 활성화하나요?

web_fetch는 별도의 API 키 없이도 바로 작동해요. 하지만 web_search를 사용하려면 Brave Search API 키가 필요합니다.

추천 방법: openclaw configure --section web 명령어를 실행해서 tools.web.search.apiKey 항목에 키를 저장해 보세요.

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "BRAVE_API_KEY_HERE",
        maxResults: 5
      },
      fetch: { enabled: true }
    }
  }
}

config.apply를 썼더니 설정이 다 날아갔어요. 어떻게 복구하고 방지할 수 있나요?

config.apply는 설정 전체를 교체하는 명령어예요. 만약 일부 객체만 담아서 보내면 그 외의 모든 설정은 삭제됩니다.

복구 방법:

• 백업 파일에서 복원하세요.
• 백업이 없다면 openclaw doctor를 실행하고 다시 설정해야 합니다.

방지 방법:

• 작은 변경 사항은 openclaw config set을 사용하세요.
• 대화형 편집이 필요할 때는 openclaw configure를 활용하는 것이 좋습니다.

여러 기기에서 특화된 워커들을 중앙 Gateway와 함께 실행하려면 어떻게 하나요?

보통 하나의 Gateway에 여러 Node와 Agent를 조합하는 패턴을 사용해요.

• Gateway (중앙): 채널, 라우팅, 세션을 관리합니다.
• Nodes (기기): Mac, iOS, Android 기기들이 주변 장치로 연결되어 로컬 도구들을 제공합니다.
• Agents (워커): 특정 역할을 수행하기 위한 별도의 브레인이나 워크스페이스입니다.
• Sub-agents: 메인 Agent로부터 생성되어 백그라운드 작업을 수행합니다.
• TUI: Gateway에 접속해서 여러 Agent와 세션을 자유롭게 전환하며 사용합니다.

OpenClaw 브라우저를 headless 모드로 실행할 수 있나요?

네, 설정 옵션에서 변경할 수 있어요.

{
  browser: { headless: true },
  agents: {
    defaults: {
      sandbox: { browser: { headless: true } }
    }
  }
}

기본값은 브라우저 창이 보이는 false (headful) 상태예요. headless 모드는 일부 사이트에서 봇 방지 시스템에 감지될 가능성이 더 높다는 점을 기억해 주세요.

브라우저 제어에 Brave를 사용하려면 어떻게 하나요?

browser.executablePath 항목에 Brave 실행 파일 경로(또는 다른 Chromium 기반 브라우저 경로)를 입력하고 Gateway를 재시작하면 됩니다.

---

설정 과정에서 어려움이 있다면 언제든 도움을 받아보세요. AI Setup Assistant

다음 단계

• Gateway 인증 심화 가이드
• Node 및 Agent 연결 방법