테마 전환

OpenClaw openclaw.json 설정 방법과 보안 모범 사례

Easton editorial illustration: one large JSON configuration card controlling an agent device

2026-06-08 업데이트: OpenClaw 공식 Gateway 설정 문서를 기준으로 필드, dmPolicy, 보안 감사 명령과 CVE-2026-25253 대응 내용을 다시 확인하고 같은 시리즈의 관련 글을 추가했습니다. 설정 항목은 공식 문서를 기준으로 확인하세요.

OpenClaw 서비스를 실행한 뒤 ~/.openclaw/openclaw.json을 열면 gateway, channel, skills, provider 등 수많은 설정 매개변수와 중첩 옵션이 보입니다. dmPolicypairingallowlist 중 무엇으로 설정해야 할까요? gateway.auth.token은 비밀번호와 같은 것일까요? 스킬을 전부 켜도 될까요?

더 신경 쓰이는 문제도 있습니다. OpenClaw는 2026년 1월 말 심각한 보안 취약점(CVE-2026-25253, CVSS 8.8)을 수정했습니다. 공격자는 URL 매개변수를 통해 인증 token을 훔친 뒤 임의 명령을 실행할 수 있었습니다. 설정이 잘못되면 AI 비서가 다른 사람의 백도어로 바뀔 수 있습니다.

당시 제가 가장 필요했던 것도 바로 이런 안내서였습니다. 아래에서는 openclaw.json의 모든 설정 모듈을 체계적으로 나눠 살펴봅니다. 각 매개변수의 의미와 필요한 이유, 운영 환경에서의 설정 방법을 설명하고, 직접 겪은 문제와 보안 설정 체크리스트도 함께 정리했습니다.

저비용으로 ‘새우 키우기’: ArkClaw로 AI Agent를 더 쉽게 사용하기

요즘 인기 있는 OpenClaw(랍스터)는 유용하지만 설정 장벽이 높습니다. ByteDance Volcano Engine의 ArkClaw는 서버나 Token 설정을 직접 다루지 않고도 클릭 한 번으로 24시간 온라인 상태에서 브라우저 제어, 스크립트 실행, 일정 관리를 수행하는 AI 작업 도우미를 만들 수 있습니다.

가격도 저렴합니다. 월 9.9위안이며, 제 초대 코드 ZLKUK54M을 사용해 여기에서 가입하면 8.9위안입니다. 개발자라면 Coding Plan Pro를 통해 무료로 이용할 수도 있습니다.

설정 파일의 기본 이해

파일 위치와 형태

OpenClaw 설정 파일은 기본적으로 ~/.openclaw/openclaw.json에 저장됩니다. 설치 마법사로 설정했다면 자동으로 생성되고, 수동 설치했다면 직접 만들어야 할 수 있습니다. 필드 이름, 중첩 구조, 기본값은 Gateway 공식 설정 문서를 기준으로 합니다. 아래 예시는 구조를 이해하기 위한 것이므로 메이저 버전을 올린 뒤에는 문서와 대조해 확인하세요.

파일을 열면 다섯 가지 핵심 모듈이 보입니다.

  • Gateway: 게이트웨이 서비스의 포트, 인증, 로그 설정
  • Channel: WhatsApp, Telegram 등 통신 채널 설정
  • Skills: 스킬 모듈 관리와 권한
  • Provider: Anthropic, OpenAI, 로컬 모델 등 AI 모델 제공자
  • Security: 보안 정책과 접근 제어

구조는 역할에 따라 잘 나뉘어 있습니다. Gateway는 진입점, Channel은 통신, Skills는 기능, Provider는 두뇌, Security는 보호를 담당합니다.

설정 방법과 우선순위

OpenClaw는 네 가지 설정 방식을 지원합니다.

  1. 대화형 마법사: 설치 중 단계별로 선택하며 초보자에게 적합
  2. JSON 직접 편집: vim이나 nano로 파일을 직접 수정하며 설정에 익숙한 사용자에게 적합
  3. 환경 변수: 컨테이너 배포나 특정 매개변수의 임시 덮어쓰기에 적합
  4. 스크립트 자동화: 대량 배포 시 스크립트로 설정 생성

중요한 점은 이 방식들에 우선순위가 있다는 것입니다. 환경 변수 > 설정 파일 > 기본값 순입니다.

예를 들어 설정 파일에 gateway.port: 18789를 지정했지만 환경 변수 OPENCLAW_GATEWAY_PORT=9000도 설정했다면 최종적으로 9000이 적용됩니다. 디버깅할 때는 설정 파일을 바꾸지 않고 환경 변수만 잠시 지정해 테스트할 수 있어 편리합니다.

2026년 버전에는 여러 검색 엔진과 도구를 통합 연결할 수 있는 MCP 서버(Model Context Protocol) 지원도 추가되었습니다. 또한 openclaw doctor 명령으로 설정 상태를 자동 점검하고 문제에 대한 수정 제안을 받을 수 있습니다.

Gateway 게이트웨이 설정

Gateway는 OpenClaw의 진입점으로, Web 인터페이스 접근과 원격 클라이언트 연결을 담당합니다.

기본 설정: 포트와 인증

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token-here"
    },
    "remote": {
      "token": "your-remote-token-here"
    }
  }
}
  • port: Web 인터페이스의 접근 포트이며 기본값은 18789입니다. http://localhost:18789에서 OpenClaw 제어판을 열 수 있습니다. 포트가 사용 중이면 19000처럼 다른 값으로 바꾸면 됩니다.

  • auth.token: 비밀번호에 해당하는 게이트웨이 인증 token입니다. 이 token을 얻은 사람은 OpenClaw 인스턴스를 완전히 제어할 수 있습니다. CVE-2026-25253은 URL 매개변수를 통해 token이 유출될 수 있었던 취약점입니다.

  • remote.token: 휴대전화 App이나 데스크톱 클라이언트 같은 원격 클라이언트가 연결할 때 사용하는 token입니다. auth.token과 분리하면 각각 따로 교체할 수 있습니다.

보안 참고: 2026년 1월 29일 버전에서는 "auth: none" 옵션이 제거되었습니다. 이전에는 개발 편의를 위해 인증을 끌 수 있었지만, 이제는 보안 취약점에 대한 강제 조치로 token 또는 password 인증을 사용해야 합니다.

고급 설정: 로그와 WebSocket

{
  "gateway": {
    "logging": {
      "redactSensitive": true
    }
  }
}

redactSensitive를 true로 설정하면 로그에서 API 키, token 등 민감 정보가 자동으로 ***로 대체됩니다. 문제를 조사하며 로그를 복사해 공개 issue에 올리더라도 키가 함께 노출되는 일을 줄일 수 있습니다.

게이트웨이 서비스는 openclaw gateway 명령으로 시작합니다. 서비스가 실행되면 다음과 비슷한 출력이 표시됩니다.

[Gateway] Listening on http://localhost:18789
[Gateway] Authentication: Token-based

Channel 채널 설정 전략

Channel 모듈은 OpenClaw가 어떤 플랫폼을 통해 사용자와 대화할지 결정합니다.

지원 채널 유형

현재 네 가지 주요 채널을 지원합니다.

  1. WhatsApp: QR 코드로 페어링하며 가장 일반적으로 사용
  2. Telegram: Bot API를 사용하며 그룹 환경에 적합
  3. Discord: 기술 커뮤니티에 적합
  4. Mattermost: 기업 팀 협업에 적합

채널마다 설정 방식이 다릅니다. WhatsApp은 QR 코드 페어링을 사용하고, Telegram은 Bot Token이 필요하며, Discord는 Application을 만들어야 합니다.

DM(개인 메시지) 정책 설정

많은 사용자가 헷갈리는 부분입니다. dmPolicy는 모르는 사람이 AI 비서에게 메시지를 보낼 수 있는지를 결정합니다.

네 가지 모드가 있습니다.

1. pairing(기본 모드)

{
  "channel": {
    "dmPolicy": "pairing"
  }
}

알 수 없는 발신자는 먼저 페어링 인증을 해야 합니다. OpenClaw가 유효 기간 1시간인 6자리 페어링 코드를 생성하며, 다음 명령으로 직접 승인합니다.

openclaw pairing approve whatsapp ABC123

이 모드는 보안과 사용성의 균형을 맞춥니다. 친구가 AI 비서에 처음 연락할 때 한 번 승인하면 이후에는 바로 대화할 수 있습니다.

2. allowlist(허용 목록 모드)

{
  "channel": {
    "dmPolicy": "allowlist",
    "allowFrom": [
      "+1234567890",
      "telegram:@username"
    ]
  }
}

허용 목록에 있는 사람만 메시지를 보낼 수 있고 나머지는 즉시 차단됩니다. 누가 사용할지 명확한 환경에 적합합니다.

3. open(공개 모드)

{
  "channel": {
    "dmPolicy": "open",
    "allowFrom": ["*"]
  }
}

누구나 메시지를 보낼 수 있습니다. 솔직히 위험이 큰 모드입니다. 공개 데모나 테스트가 아니라면 사용하지 않는 편이 좋습니다.

4. disabled(비활성화 모드)

DM 기능을 완전히 끄고 그룹 메시지만 받습니다.

다중 사용자 환경의 세션 격리

팀이 공유하는 경우처럼 OpenClaw 서비스를 여러 사람이 사용한다면 세션 격리가 중요합니다.

{
  "channel": {
    "session": {
      "dmScope": "per-channel-peer"
    }
  }
}

이렇게 하면 각 사용자의 대화 기록이 서로 독립되어 내용이 섞이지 않습니다.

Group 그룹 정책 설정

그룹 설정은 비교적 단순하지만 mentionGating(@멘션 게이트)이라는 핵심 옵션이 있습니다.

{
  "channel": {
    "groupPolicy": "mention",
    "mentionGating": true
  }
}

활성화하면 AI 비서는 그룹의 모든 메시지를 듣지 않고 자신을 @멘션한 메시지에만 답합니다. 그룹에서 계속 메시지를 쏟아 내는 ‘always-on’ 봇이 되는 일을 막을 수 있습니다.

Skills 스킬 모듈 설정

Skills는 OpenClaw에서 가장 흥미로운 부분으로, AI 비서가 무엇을 할 수 있는지 결정합니다.

Skills 기본 개념

스킬은 모듈식 기능 확장입니다. OpenClaw에는 몇 가지 기본 스킬이 포함되어 있고, ClawHub 스킬 스토어에서는 700개 이상의 스킬을 사용할 수 있습니다.

  • 일정 관리(Google Calendar, Outlook)
  • 웹 탐색(browser 스킬)
  • 파일 관리(file_manager)
  • 터미널 명령(exec 스킬)
  • 코드 실행(python, node)

스킬 설치 경로는 ~/.openclaw/skills/입니다. 우선순위는 워크스페이스 스킬 > 사용자 스킬 > 기본 스킬입니다.

예를 들어 프로젝트 디렉터리에 사용자 정의 browser 스킬을 두면 전역 설치 버전을 덮어씁니다. 이 구조 덕분에 프로젝트별로 기능을 맞춤 설정할 수 있습니다.

스킬 설정과 관리

각 스킬에는 메타데이터를 YAML 형식으로 정의하는 SKILL.md 파일이 있습니다.

---
name: google-calendar
description: Manage Google Calendar events
requirements:
  bins:
    - gcalcli
  env:
    - GOOGLE_CALENDAR_API_KEY
---

bins 필드에는 필요한 바이너리 프로그램이 나열됩니다. 이 일정 스킬은 gcalcli 명령줄 도구가 필요하며, 시스템에 설치되지 않았다면 스킬을 불러오지 못합니다.

설치 방법은 세 가지입니다.

  1. GUI 설치: Web 인터페이스에서 “Add Skill”을 클릭해 검색하고 설치
  2. CLI 설치: openclaw skill install google-calendar
  3. 수동 설치: 스킬 디렉터리를 ~/.openclaw/skills/에 복사

스킬 문제 해결

스킬 로드 실패는 흔한 문제입니다. 다음 명령으로 의존성을 확인하세요.

openclaw skill check google-calendar

누락된 의존성, 환경 변수 설정 여부, OS 설정 호환성을 확인할 수 있습니다.

그래도 문제가 해결되지 않으면 Gateway 로그를 확인합니다.

openclaw gateway --verbose

로그에는 스킬을 불러오는 전체 과정과 오류가 발생한 단계가 자세히 표시됩니다.

소형 모델 환경 최적화

7B 매개변수 양자화 모델처럼 컨텍스트 창이 작은 로컬 모델을 사용한다면 컨텍스트 크기를 제어하기 위해 일부 스킬을 비활성화해야 할 수 있습니다. 스킬이 많을수록 시스템 프롬프트가 길어지고 대화에 사용할 공간이 줄어듭니다.

고위험 스킬 제한

일부 스킬은 권한이 매우 높으므로 신중하게 사용해야 합니다.

  • exec: 임의 shell 명령 실행
  • browser: 임의 웹 페이지 접근
  • web_fetch: 외부 콘텐츠 가져오기
  • web_search: 검색 엔진 질의

이런 스킬은 악성 입력에 의해 오용될 수 있습니다. 꼭 필요하지 않다면 비활성화하는 것이 좋습니다.

Provider 모델 제공자 설정

Provider는 OpenClaw가 사용할 AI 두뇌를 결정합니다.

지원하는 AI Provider

  1. Anthropic(Claude): 공식적으로 주로 권장하며 API가 안정적이고 보안 기능이 잘 갖춰짐
  2. OpenAI: GPT-5 등의 모델 지원 예정
  3. 로컬 모델: LM Studio, Ollama 등
  4. OpenRouter: 하나의 API Key로 여러 모델에 접근하는 통합 인터페이스
  5. MCP 서버: 2026년 신규 기능으로 Model Context Protocol 지원

Provider 설정 매개변수

Anthropic을 사용하는 가장 간단한 설정은 다음과 같습니다.

{
  "provider": {
    "type": "anthropic",
    "apiKey": "sk-ant-..."
  }
}

다만 API Key는 설정 파일에 직접 쓰지 말고 환경 변수를 사용하는 것이 좋습니다.

export ANTHROPIC_API_KEY="sk-ant-..."

이렇게 하면 설정 파일을 버전 관리에 안전하게 커밋하면서 API Key 유출을 피할 수 있습니다.

로컬 모델 설정

{
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "kimi-k2.5-chat"
  }
}
  • baseURL: 로컬 모델 서버 주소(LM Studio 기본 포트는 1234)
  • modelId: 사용할 모델 이름

MCP 서버 설정(신규 기능)

{
  "provider": {
    "mcpServers": {
      "onesearch": {
        "command": "npx",
        "args": ["-y", "@onesearch/mcp-server"]
      }
    }
  }
}

OneSearch MCP를 사용하면 검색 엔진마다 API Key를 따로 설정하지 않고도 통합 인터페이스로 Google, Bing, Brave 등 여러 검색 엔진에 접근할 수 있습니다.

로컬 모델 사용 시 주의점

로컬 모델에는 개인정보 보호, 비용, 오프라인 사용이라는 장점이 있습니다. 다만 보안 기능은 상용 모델보다 약한 편입니다.

  • 더 높은 프롬프트 인젝션 위험: 소형 모델은 악성 입력에 더 쉽게 속음
  • 작은 컨텍스트 창: 보안 기능에는 더 긴 시스템 프롬프트가 필요하지만 소형 모델은 이를 담기 어려움
  • 양자화 모델의 한계: 4-bit 양자화 후 지시 이행 능력이 저하될 수 있음

로컬 모델을 사용해야 한다면 다음을 권장합니다.

  • 스킬 권한을 엄격히 제한
  • 샌드박스 모드 활성화
  • 민감한 데이터가 있는 컴퓨터에서는 실행하지 않음

보안 설정 모범 사례

보안 설정은 언제나 최우선입니다. CVE-2026-25253은 잘못된 설정의 결과가 매우 심각할 수 있음을 보여 줍니다.

보안 설정 체크리스트

기본 보안(필수)

  • ✅ gateway token은 집 열쇠처럼 절대 공유하지 않기
  • ✅ 방화벽을 사용하고 필요한 포트(18789)만 공개하기
  • ✅ SSH는 비밀번호 대신 키 인증 사용하기
  • ✅ Web 인터페이스 접근 제한하기(VPN 또는 IP 허용 목록)
  • ✅ DM 정책은 pairing 또는 allowlist 우선 사용하기
  • ✅ 그룹 정책에서 mention gating 활성화하기

고급 보안(강력 권장)

  • ✅ token을 정기적으로, 최소 분기마다 교체하기
  • ✅ 로그의 민감 정보 마스킹 활성화하기
  • ✅ 고위험 스킬(exec, browser) 제한하기
  • ✅ 주 작업 컴퓨터와 분리된 전용 서버 사용하기

입력 보안과 샌드박스

반드시 지켜야 할 원칙이 있습니다. 모든 외부 입력을 악성으로 간주하세요.

링크, 첨부 파일, 붙여 넣은 지시에는 정교하게 만든 공격이 숨어 있을 수 있습니다. OpenClaw의 선택형 샌드박스 기능으로 고위험 작업을 격리할 수 있습니다.

{
  "security": {
    "sandbox": {
      "enabled": true,
      "skills": ["exec", "browser"]
    }
  }
}

이렇게 설정하면 exec와 browser 스킬이 격리 환경에서 실행되므로 공격에 성공하더라도 주 시스템에 미치는 영향을 줄일 수 있습니다.

Secrets 관리

API 키, token 같은 민감 정보는 다음과 같이 관리합니다.

  1. 기본 방법: 채팅에 붙여 넣지 말고 SCP로 .env 파일을 서버에 전송
  2. 고급 방법: Doppler, HashiCorp Vault 같은 전문 secrets 관리자 사용

절대 하지 말아야 할 일:

  • ❌ Telegram 메시지로 API Key 보내기
  • ❌ secrets를 Git 저장소에 커밋하기
  • ❌ token이 포함될 수 있는 로그를 공개 issue에 올리기

보안 감사와 유지 관리

OpenClaw에는 보안 감사 명령이 내장되어 있습니다.

# 기본 점검
openclaw security audit

# 심층 점검
openclaw security audit --deep

# 보안 조치 자동 적용
openclaw security audit --fix

이 명령은 다음 항목을 점검합니다.

  • Token 강도가 충분한지
  • 포트가 인터넷에 공개되어 있는지
  • 파일 권한이 올바른지(~/.openclaw는 700, 설정 파일은 600)
  • 고위험 스킬이 활성화되어 있는지
  • DM 정책이 안전한지

로컬 파일 권한

chmod 700 ~/.openclaw
chmod 600 ~/.openclaw/openclaw.json

이 권한을 적용하면 본인만 설정 파일을 읽고 쓸 수 있으며 다른 사용자는 내용을 볼 수도 없습니다.

절대 하지 말아야 할 일

  • ❌ 18789 포트를 인터넷에 공개하기
  • ❌ 위험을 이해하지 않은 채 shell 접근 권한 주기
  • ❌ 출처가 검증되지 않은 스킬 설치하기
  • ❌ 허용 목록 없이 dmPolicy: "open" 사용하기
  • ❌ 주요 이메일이나 은행 정보가 저장된 컴퓨터에서 OpenClaw 실행하기

실제 설정 예시

이론을 살펴봤으니 몇 가지 환경의 전체 설정을 확인해 보겠습니다.

사례 1: 개인용, WhatsApp만 사용, 페어링 모드

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "generate-a-strong-random-token"
    },
    "logging": {
      "redactSensitive": true
    }
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "pairing",
    "session": {
      "dmScope": "per-channel-peer"
    }
  },
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "file_manager"
    ],
    "disabled": [
      "exec",
      "browser"
    ]
  },
  "provider": {
    "type": "anthropic"
  },
  "security": {
    "sandbox": {
      "enabled": true
    }
  }
}

일반 개인 사용자에게 적합한 설정입니다. 보안성이 높고 기능은 충분하며 고위험 스킬은 비활성화되어 있습니다.

사례 2: 팀 협업, 다중 채널, 허용 목록 모드

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "team-gateway-token"
    },
    "remote": {
      "token": "team-remote-token"
    }
  },
  "channel": [
    {
      "type": "telegram",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "telegram:@alice",
        "telegram:@bob",
        "telegram:@carol"
      ],
      "groupPolicy": "mention",
      "mentionGating": true
    },
    {
      "type": "discord",
      "dmPolicy": "allowlist",
      "allowFrom": [
        "discord:123456789"
      ]
    }
  ],
  "skills": {
    "enabled": [
      "calendar",
      "web_search",
      "github",
      "jira"
    ]
  },
  "provider": {
    "type": "anthropic"
  }
}

다중 채널은 배열로 설정하며 각 채널의 허용 목록을 독립적으로 관리합니다. 그룹에서는 mention gating을 켜 도배를 막습니다.

사례 3: 로컬 모델, 오프라인 사용, 최소 스킬

{
  "gateway": {
    "port": 19000
  },
  "channel": {
    "type": "whatsapp",
    "dmPolicy": "allowlist",
    "allowFrom": ["+1234567890"]
  },
  "skills": {
    "enabled": [
      "calculator",
      "file_manager"
    ]
  },
  "provider": {
    "type": "openai-compatible",
    "baseURL": "http://localhost:1234/v1",
    "modelId": "llama-3.1-8b"
  }
}

로컬 모델을 사용할 때는 스킬을 가능한 한 줄여야 합니다. 소형 모델의 컨텍스트 창에는 너무 많은 시스템 프롬프트를 담을 수 없습니다.

흔한 설정 오류와 해결 방법

오류 1: token 불일치로 연결할 수 없음

증상: Web 인터페이스에 “Authentication failed” 표시

해결: gateway.auth.token과 입력한 token이 완전히 같은지 확인합니다. 공백과 줄바꿈도 확인하세요.

오류 2: 스킬 의존성이 없어 로드 실패

증상: 로그에 “Skill ‘google-calendar’ failed to load” 표시

해결: openclaw skill check google-calendar를 실행하고 안내에 따라 누락된 의존성을 설치합니다.

오류 3: 포트 충돌로 Gateway를 시작할 수 없음

증상: Error: listen EADDRINUSE :::18789

해결: 다른 포트를 사용하거나 18789 포트를 사용 중인 프로세스를 찾아 종료합니다.

오류 4: 설정 파일 형식 오류

증상: SyntaxError: Unexpected token } in JSON

해결: JSON 검증 도구로 형식을 확인합니다. 불필요한 쉼표나 맞지 않는 따옴표가 흔한 원인입니다.

문제 해결 명령

# 서비스 상태 보기
openclaw status

# 상태 점검
openclaw doctor

# 상세 로그
openclaw gateway --verbose

관련 글

결론

핵심은 세 가지입니다.

첫째, 설정 파일은 OpenClaw의 심장입니다. 각 매개변수의 의미를 제대로 이해해야 합니다. 지식을 과시하기 위해서가 아니라 문제가 생겼을 때 빠르게 원인을 찾기 위해서입니다.

둘째, 보안 설정은 언제나 최우선입니다. CVE-2026-25253은 잘못된 설정의 위험이 실제임을 보여 줍니다. token은 비밀로 유지하고, 포트 접근을 제한하며, DM 정책을 엄격하게 설정하고, 고위험 스킬은 신중하게 활성화해야 합니다.

셋째, 설정은 한 번으로 끝나는 작업이 아닙니다. 사용 환경이 바뀌고 팀원이 늘거나 줄며 새 스킬이 출시될 때마다 설정도 계속 다듬어야 합니다. 일정한 간격으로 설정을 검토하고 openclaw security audit을 실행해 모든 것이 통제되고 있는지 확인하세요.

지금 바로 다음 세 가지를 실행하세요.

  1. openclaw security audit --deep으로 현재 설정 점검
  2. 이 글의 모범 사례 체크리스트와 대조해 설정을 항목별로 개선
  3. 개선한 설정을 안전한 장소에 백업하되 token은 함께 백업하지 않기

설정 과정에서 문제가 생겼다면 활발한 OpenClaw 커뮤니티를 이용할 수 있습니다. GitHub Discussions와 Discord 채널에서 도움을 받을 수 있습니다. 직접 쌓은 설정 경험도 공유해 보세요. 모두가 이런 시행착오를 거쳐 익숙해집니다.

OpenClaw 설정 파일 전체 구성 절차

openclaw.json을 처음부터 설정하는 단계별 방법으로 Gateway, Channel, Skills, Provider, Security 모듈을 모두 다룹니다.

Estimated time: PT30M

  1. 1

    Step 1: 1단계: 설정 파일 생성 및 위치 확인

    설정 파일 위치: ~/.openclaw/openclaw.json
  2. 2

    Step 2: 2단계: Gateway 게이트웨이 모듈 설정

    기본 설정 매개변수:
  3. 3

    Step 3: 3단계: Channel 채널 모듈 설정

    지원하는 채널 유형:
  4. 4

    Step 4: 4단계: Skills 스킬 모듈 설정

    스킬 설치 경로: ~/.openclaw/skills/
  5. 5

    Step 5: 5단계: Provider 모델 제공자 설정

    지원하는 Provider 유형:
  6. 6

    Step 6: Anthropic(Claude)

    공식 권장
  7. 7

    Step 7: OpenAI(GPT-5 등)

    지원 예정
  8. 8

    Step 8: 6단계: Security 보안 모듈 설정

    기본 보안 설정(필수):
  9. 9

    Step 9: 7단계: 확인과 문제 해결

    설정 확인:

FAQ

dmPolicy는 pairing과 allowlist 중 무엇을 선택해야 하나요?
사용 환경에 따라 선택합니다.

pairing 모드(대부분의 환경에 권장):
• 적합한 경우: 모든 사용자가 누구인지 미리 알 수 없지만 승인이 필요한 경우
• 장점: 유연하며, 친구가 처음 한 번 페어링하면 이후에는 바로 통신 가능
• 절차: 모르는 사람이 메시지 전송 → 6자리 페어링 코드 생성 → 사용자가 승인 → 이후 바로 통신
• 명령: openclaw pairing approve whatsapp ABC123

allowlist 모드(높은 보안이 필요한 환경에 권장):
• 적합한 경우: 모든 사용자(가족, 팀원)를 명확히 아는 경우
• 장점: 가장 안전하며 허용 목록 밖의 사용자는 즉시 차단
• 설정: "allowFrom": ["+1234567890", "telegram:@username"]
• 관리: 새 사용자를 수동으로 허용 목록에 추가해야 함

선택 기준:
개인용이며 누가 연락할지 불확실함 → pairing
고정된 팀원만 사용함 → allowlist
공개 데모/테스트 → open(일시적으로만 사용하고 장기 사용은 비추천)
CVE-2026-25253은 어떤 취약점이며 어떻게 방어하나요?
취약점 정보:
• CVE 번호: CVE-2026-25253
• CVSS 점수: 8.8(심각)
• 발견 시점: 2026년 1월 말
• 영향 버전: 2026년 1월 29일 이전 버전

공격 원리:
공격자는 다음과 같이 URL 매개변수를 통해 인증 token을 훔칠 수 있습니다.
http://victim.com:18789/?token=leaked-token
token을 얻으면 OpenClaw 인스턴스를 완전히 제어하고 임의 명령을 실행할 수 있습니다.

공식 수정 사항:
1. "auth: none" 옵션을 제거하고 인증을 강제함
2. URL 매개변수로 token을 전달하지 않음
3. 모든 요청은 Header로 인증 정보를 전달해야 함

방어 방법:
• 즉시 최신 버전(2026년 1월 29일 이후)으로 업데이트
• 기존 token을 모두 교체(이전 token이 이미 유출됐을 수 있음)
• URL에 token을 절대 포함하지 않음
• Web 인터페이스 접근 제한(VPN/IP 허용 목록/방화벽)
• 18789 포트를 인터넷에 공개하지 않음
• openclaw security audit으로 설정을 정기 점검

영향 여부 확인:
openclaw --version
표시된 버전 날짜가 2026-01-29보다 이르면 업데이트가 필요합니다.
로컬 모델과 Anthropic API는 보안 면에서 어떻게 다른가요?
Anthropic API의 보안상 장점:

1. 프롬프트 인젝션 방어:
• 악성 prompt를 식별하는 보안 계층 내장
• 위험한 지시 실행 거부
• 보안 규칙 정기 업데이트

2. 지시 이행 능력:
• 시스템 프롬프트를 엄격히 따름
• 사용자 입력에 속을 가능성이 낮음

3. 컨텍스트 처리:
• 큰 창(200K tokens)에 전체 보안 프롬프트를 담을 수 있음

로컬 모델의 보안 한계:

1. 높은 프롬프트 인젝션 위험:
• 소형 모델(7B-13B)은 정교하게 만든 입력에 우회되기 쉬움
• 전용 보안 학습 부족

2. 양자화 모델 문제:
• 4-bit 양자화 후 지시 이행 능력이 크게 저하될 수 있음
• 보안 특성이 무력화될 수 있음

3. 컨텍스트 제한:
• 작은 창(4K-8K tokens)에 전체 보안 프롬프트를 담기 어려움
• 스킬과 시스템 프롬프트를 줄여야 함

로컬 모델을 안전하게 사용하는 방법:
• 스킬 권한을 엄격히 제한하고 저위험 스킬만 활성화
• 샌드박스 모드를 반드시 켜서 격리 실행
• 민감한 데이터가 있는 컴퓨터에 배포하지 않음
• allowlist로 사용자 제한
• exec, browser 등 고위험 스킬 비활성화
• 로그를 정기 검토하고 이상 행동 감시

선택 기준:
민감한 데이터를 처리해 높은 보안이 필요함 → Anthropic API
개인정보 보호와 오프라인 사용을 중시함 → 로컬 모델 + 엄격한 보안 설정
스킬이 너무 많으면 성능에 영향을 주나요? 몇 개를 활성화해야 하나요?
스킬 수의 영향:

1. 컨텍스트 사용량:
각 스킬은 시스템 프롬프트 길이를 늘립니다.
• 스킬 1개: 평균 200-500 tokens
• 스킬 10개: 약 2000-5000 tokens
• 대화에 쓸 공간은 그만큼 줄어듦

2. 모델 유형에 따른 전략:

대형 모델(Anthropic Claude):
• 컨텍스트 창: 200K tokens
• 권장: 자주 쓰는 스킬 10-20개 활성화 가능
• 영향: 거의 무시할 수 있으며 성능 저하가 크지 않음

중형 모델(로컬 13B-30B):
• 컨텍스트 창: 8K-32K tokens
• 권장: 필수 스킬 5-10개 활성화
• 영향: 기능과 컨텍스트 공간 사이의 균형 필요

소형 모델(로컬 7B 양자화):
• 컨텍스트 창: 4K-8K tokens
• 권장: 핵심 스킬 2-5개만 활성화
• 영향: 반드시 줄여야 대화 가능

3. 필요에 따른 활성화 전략:

개인 비서 환경(권장):
• calendar(일정 관리)
• web_search(웹 검색)
• file_manager(파일 관리)
• calculator(계산기)

개발 환경(권장):
• github(코드 저장소)
• web_search(기술 검색)
• exec(명령 실행, 샌드박스 필요)

기업 환경(권장):
• calendar(일정)
• jira(프로젝트 관리)
• slack(팀 협업)
• web_search(검색)

동적 조정:
• 워크스페이스 스킬이 전역 스킬보다 우선함
• 프로젝트마다 다른 설정을 만들 수 있음
• 자주 쓰지 않는 스킬은 바로 비활성화

성능 최적화:
openclaw skill list
활성화된 스킬과 컨텍스트 사용량을 확인합니다.

쓰지 않는 스킬 비활성화:
"skills": {"disabled": ["skill-name"]}
개발/테스트/운영 등 여러 환경의 설정을 안전하게 관리하려면 어떻게 하나요?
다중 환경 설정 관리 전략:

방법 1: 환경 변수 덮어쓰기(권장)

기본 설정 파일(~/.openclaw/openclaw.json):
공통 설정만 포함하고 민감 정보는 제외합니다.

개발 환경(.env.development):
export OPENCLAW_GATEWAY_PORT=18789
export OPENCLAW_DM_POLICY=open
export ANTHROPIC_API_KEY=sk-ant-dev-key

운영 환경(.env.production):
export OPENCLAW_GATEWAY_PORT=18789
export OPENCLAW_DM_POLICY=allowlist
export ANTHROPIC_API_KEY=sk-ant-prod-key

환경 전환:
source .env.development
openclaw gateway

우선순위: 환경 변수 > 설정 파일 > 기본값

방법 2: 여러 설정 파일

서로 다른 설정 생성:
~/.openclaw/openclaw.dev.json
~/.openclaw/openclaw.prod.json

설정 파일을 지정해 실행:
openclaw gateway --config ~/.openclaw/openclaw.prod.json

방법 3: Git 관리(팀에 권장)

버전 관리:
openclaw.json.template(템플릿, Git에 커밋)
openclaw.json(실제 설정, .gitignore에 추가)
.env.example(환경 변수 예시)

.gitignore 설정:
openclaw.json
.env
.env.local
.env.*.local

팀 협업 절차:
1. 템플릿 복사: cp openclaw.json.template openclaw.json
2. 로컬 설정 입력
3. 환경 변수에 민감 정보 저장

방법 4: Secrets 관리자(기업에 권장)

Doppler 예시:
doppler secrets set GATEWAY_TOKEN xxx
doppler run -- openclaw gateway

HashiCorp Vault 예시:
vault kv get -field=token secret/openclaw/gateway

보안 체크리스트:
✅ 설정 파일에 API 키와 token 없음
✅ 환경 변수로 민감 정보 저장
✅ .gitignore에 모든 설정 파일 포함
✅ 운영 token과 개발 token이 다름
✅ 운영 token을 정기 교체
✅ 설정 파일 권한이 올바름(600)
✅ 채팅/issue에서 설정을 공유하지 않음

백업 전략:
개발 설정: 민감 정보가 없으면 Git 커밋 가능
운영 설정: 안전한 위치(1Password/Bitwarden)에 암호화해 백업
그룹 채팅에서 AI 비서가 계속 답장할 때는 어떻게 하나요?
원인:
mention gating을 켜지 않아 AI가 그룹의 모든 메시지를 듣고 답장합니다.

해결 방법:

1. Mention Gating 활성화(권장)

설정:
"channel": {
"groupPolicy": "mention",
"mentionGating": true
}

효과: AI는 @멘션이 포함된 메시지에만 답합니다.

사용 예:
그룹 멤버가 "@OpenClaw 오늘 날씨가 어때?"라고 보낼 때만
AI가 응답합니다.

2. 키워드 트리거(대안)

설정:
"channel": {
"groupPolicy": "keyword",
"keywords": ["openclaw", "비서"]
}

효과: 키워드가 포함된 메시지만 응답을 트리거합니다.

3. 그룹 완전 비활성화

설정:
"channel": {
"groupPolicy": "disabled"
}

효과: AI는 그룹 메시지에 전혀 응답하지 않고 DM만 처리합니다.

4. 메시지 빈도 제한

설정:
"channel": {
"rateLimit": {
"maxMessages": 10,
"perMinutes": 1
}
}

효과: 분당 최대 10개의 답장으로 제한합니다.

긴급 임시 조치:

그룹 응답 즉시 중지:
openclaw channel disable --group

그룹에서 AI 제거:
WhatsApp/Telegram 그룹에서 OpenClaw를 제거합니다.

Gateway 재시작:
openclaw gateway restart

권장 설정:
"channel": {
"groupPolicy": "mention",
"mentionGating": true,
"rateLimit": {
"maxMessages": 5,
"perMinutes": 1
}
}

이렇게 설정하면:
• AI가 @멘션에만 응답
• 분당 최대 5개 답장
• 도배와 악용 방지
설정 파일이 갑자기 작동하지 않아 Gateway가 시작되지 않을 때는 어떻게 점검하나요?
체계적인 점검 절차:

1단계: 설정 파일 형식 확인

JSON 형식 검증:
cat ~/.openclaw/openclaw.json | python -m json.tool

흔한 형식 오류:
• 불필요한 쉼표: {"key": "value",}
• 맞지 않는 따옴표: "key: "value"
• 주석(JSON은 지원하지 않음): // this is wrong

온라인 검증 도구: jsonlint.com

2단계: 파일 권한 확인

권한 보기:
ls -la ~/.openclaw/openclaw.json

올바른 권한:
-rw------- (600), 소유자만 읽고 쓸 수 있음

권한 수정:
chmod 600 ~/.openclaw/openclaw.json
chmod 700 ~/.openclaw

3단계: 상세 오류 로그 확인

상세 모드로 실행:
openclaw gateway --verbose

로그 위치:
~/.openclaw/logs/gateway.log

최근 오류 보기:
tail -n 50 ~/.openclaw/logs/gateway.log

4단계: 상태 점검 실행

기본 점검:
openclaw doctor

출력 내용:
• 설정 파일 읽기 가능 여부
• 필수 필드 존재 여부
• 의존성 충족 여부
• 포트 사용 가능 여부

심층 점검:
openclaw security audit --deep

5단계: 흔한 장애와 해결 방법

장애 1: 포트가 이미 사용 중
오류: Error: listen EADDRINUSE :::18789
해결:
사용 중인 프로세스 찾기: lsof -i :18789
프로세스 종료: kill -9 [PID]
또는 다른 포트 사용: "port": 19000

장애 2: Token 형식 오류
오류: Invalid authentication token
해결:
token에 줄바꿈 문자가 없는지 확인: cat -A ~/.openclaw/openclaw.json
token 다시 생성: openssl rand -hex 32

장애 3: 환경 변수 충돌
오류: 설정이 의도치 않게 덮어써짐
해결:
환경 변수 보기: env | grep OPENCLAW
충돌 변수 제거: unset OPENCLAW_GATEWAY_PORT

장애 4: 설정 파일 손상
오류: SyntaxError 또는 Unexpected token
해결:
백업 복원: cp ~/.openclaw/openclaw.json.backup ~/.openclaw/openclaw.json
또는 템플릿 사용: cp openclaw.json.template ~/.openclaw/openclaw.json

6단계: 설정 초기화(최후 수단)

현재 설정 백업:
cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.broken

설정 삭제:
rm ~/.openclaw/openclaw.json

설정 마법사 다시 실행:
openclaw onboard

시작 확인:
openclaw gateway --verbose

예방 조치:

1. 설정 정기 백업:
crontab -e
추가: 0 0 * * * cp ~/.openclaw/openclaw.json ~/.openclaw/backup/openclaw-$(date +%Y%m%d).json

2. 버전 관리(민감 정보가 없는 템플릿):
git init ~/.openclaw
git add openclaw.json.template

3. 변경 전 테스트:
cp openclaw.json openclaw.json.test
# test 파일 수정
openclaw gateway --config openclaw.json.test --dry-run

4. 설정 검증 스크립트 사용:
openclaw config validate

3분 읽기 · 게시일: 2026년 2월 5일 · 수정일: 2026년 9월 4일

댓글

GitHub로 로그인하여 댓글을 남기세요

Easton BlogEaston Blog