OpenClaw 설정 가이드: openclaw.json

OpenClaw 설정 가이드: openclaw.json

OpenClaw를 설치하고 온보딩까지 마쳤는데, 채널 설정을 바꾸고 싶거나 보안 정책을 조정하고 싶다면 어디를 건드려야 할까요? 답은 ~/.openclaw/openclaw.json입니다. 🦞

이 글에서는 OpenClaw의 시스템 설정을 담당하는 openclaw.json을 중심으로, .env 파일, hooks, skills 같은 인프라 설정을 다룹니다. 에이전트의 성격이나 기억을 설정하는 워크스페이스 프롬프트 파일(IDENTITY.md, SOUL.md 등)에 대해서는 워크스페이스 가이드를 참고하세요.

디렉토리 구조

OpenClaw를 설치하면 ~/.openclaw/ 디렉토리에 설정과 상태 파일이 생깁니다.

~/.openclaw/
├── openclaw.json          # 핵심 설정 파일
├── .env                   # API 키와 환경 변수
├── credentials/           # 채널별 인증 토큰
├── hooks/                 # 커스텀 훅
├── skills/                # 전역 스킬
├── logs/                  # Gateway 로그
└── workspace/             # 에이전트 워크스페이스 (→ 별도 가이드)

workspace/ 안에는 에이전트의 성격과 행동을 정의하는 마크다운 파일들이 있는데, 이 부분은 워크스페이스 가이드에서 자세히 다루고 있습니다.

openclaw.json — 핵심 설정 파일

~/.openclaw/openclaw.json은 OpenClaw의 시스템 설정을 모아둔 파일입니다. JSON5 형식이라 주석과 후행 쉼표를 사용할 수 있어서 편집이 편합니다.

identity 블록

에이전트의 표시 이름과 외형을 설정합니다.

{
  identity: {
    name: "Jasper", // 에이전트 표시 이름, @멘션에도 사용
    theme: "sharp-eyed hawk with dry wit",
    emoji: "🦅", // 리액션에 사용, 기본값 👀
    avatar: "workspace://avatar.png", // 경로, URL, data: URI 가능
  },
}

agents.list에서 에이전트별로 다른 identity를 지정할 수도 있습니다.

agents 블록

에이전트의 기본 동작을 결정하는 핵심 설정입니다.

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "Asia/Seoul",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["openai/gpt-5.1-codex"], // 기본 모델 실패 시 폴백
      },
      sandbox: {
        mode: "non-main", // "off", "non-main", "all"
        scope: "session", // "session", "agent", "shared"
        workspaceAccess: "ro", // "ro", "rw", "none"
      },
    },
    list: [
      {
        id: "code-reviewer",
        identity: { name: "Hawk", emoji: "🔍" },
        model: { primary: "anthropic/claude-opus-4-6" },
      },
    ],
  },
}

model.fallbacks를 설정해두면 기본 모델의 API가 다운됐을 때 자동으로 대체 모델로 전환됩니다. agents.list로 여러 에이전트를 정의해두고 /agent <id> 명령으로 전환할 수 있어요.

channels 블록

메시징 채널별로 세부 설정을 잡아주는 곳입니다.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "${TELEGRAM_BOT_TOKEN}",
      dmPolicy: "pairing",
      groupPolicy: "allowlist",
      requireMention: true,
    },
    discord: {
      enabled: true,
      botToken: "${DISCORD_BOT_TOKEN}",
      applicationId: "your-app-id",
      requireMention: true,
      disabledCommands: ["/reasoning", "/verbose", "/system"],
    },
  },
}

토큰 같은 민감한 값은 ${ENV_VAR} 문법으로 환경 변수를 참조하는 게 안전합니다. 그룹 채팅에서는 requireMention: true로 설정해서 명시적으로 멘션했을 때만 응답하게 하는 걸 권장합니다.

security 블록

DM 정책과 게이트웨이 보안을 설정합니다.

{
  security: {
    dm: {
      policy: "pairing", // "pairing", "allowlist", "open", "disabled"
      pairingTtl: 3600, // 페어링 코드 유효 시간 (초)
    },
  },
  gateway: {
    mode: "local",
    bind: "loopback", // localhost만 접근 허용
    port: 18789,
    auth: {
      token: "${GATEWAY_TOKEN}",
    },
  },
}

기본값인 pairing 정책은 모르는 사람이 DM을 보내면 1시간짜리 페어링 코드를 요구합니다. 한 채널당 대기 중인 페어링 요청은 최대 3개까지만 허용돼요.

tools 블록

에이전트가 어떤 도구를 쓸 수 있는지 여기서 결정됩니다.

{
  tools: {
    allow: ["shell", "browser", "files", "calendar"],
    profile: "coding", // 도구 프로필
    exec: {
      requireApproval: true, // 명령 실행 전 승인 요구
    },
  },
}

v2026.3.2부터 로컬 온보딩의 기본 도구 프로필이 coding으로 변경됐습니다. exec, web_fetch 같은 도구가 안 보인다면 tools.profile 설정을 확인해 보세요.

.env 파일 — 시크릿 관리

API 키와 토큰 같은 민감한 정보는 ~/.openclaw/.env 파일에 저장합니다.

~/.openclaw/.env
# AI Provider
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...

# Channels
TELEGRAM_BOT_TOKEN=123456:ABC...
DISCORD_BOT_TOKEN=...

# Tools
ELEVENLABS_API_KEY=...
GITHUB_TOKEN=ghp_...

환경 변수의 해석 순서가 정해져 있어서 이미 시스템 환경에 설정된 변수가 있으면 .env 파일이 덮어쓰지 않습니다.

  1. 프로세스 환경 (부모 셸/데몬)
  2. 현재 디렉토리의 .env
  3. ~/.openclaw/.env (전역)
  4. openclaw.json의 env 블록
  5. 로그인 셸 환경 (옵션)

파일 권한도 신경 써야 합니다.

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

프로덕션 환경이라면 .env 파일의 소유자를 root로 설정해서 에이전트가 자기 자신의 키를 덮어쓰지 못하게 하는 것도 고려해 볼 만합니다.

hooks/ — 커스텀 자동화

훅은 특정 이벤트에 반응해서 실행되는 자동화 스크립트입니다. ~/.openclaw/hooks/ 디렉토리에 각 훅마다 하위 폴더를 만들고, HOOK.md(메타데이터)와 handler.ts(실행 로직)를 넣으면 됩니다.

기본 제공되는 번들 훅 네 가지가 있습니다.

  • boot-md — Gateway 시작 시 BOOT.md 실행
  • bootstrap-extra-files — 부트스트랩 프롬프트에 추가 파일 주입
  • session-memory — /new나 /reset 명령 시 세션 컨텍스트를 메모리에 저장
  • command-logger — 모든 명령 이벤트를 JSONL 파일로 감사 로깅

새로 설치한 훅은 보안상 기본적으로 비활성화 상태입니다.

# 훅 목록 확인
openclaw hooks list

# 특정 훅 활성화
openclaw hooks enable session-memory

# 훅 비활성화
openclaw hooks disable boot-md

커스텀 훅을 만들려면 handler.ts에 이벤트 핸들러를 작성하고 HOOK.md에 메타데이터를 정의하면 됩니다. npm 패키지로 훅을 배포할 수도 있어서 팀 전체가 같은 자동화를 공유하기 좋습니다.

skills/ — 스킬 확장

스킬(Skills)은 에이전트에게 특정 작업 능력을 부여하는 확장 모듈입니다. 세 곳에서 스킬이 로드되며, 우선순위가 다릅니다.

  1. <workspace>/skills/ — 프로젝트별 스킬 (최고 우선순위)
  2. ~/.openclaw/skills/ — 전역 설치 스킬
  3. 번들 스킬 — OpenClaw에 기본 포함 (최저 우선순위)

같은 이름의 스킬이 여러 곳에 있으면 우선순위가 높은 쪽이 사용됩니다.

커스텀 스킬을 만들려면 skills/<name>/SKILL.md 파일을 생성합니다.

skills/daily-digest/SKILL.md
---
name: daily-digest
description: 매일 아침 뉴스와 일정을 요약해주는 스킬
version: 1.0.0
---

# Daily Digest

사용자가 "오늘 브리핑" 또는 "모닝 다이제스트"를 요청하면:

1. 오늘 캘린더 일정을 확인한다
2. GitHub 알림을 확인한다
3. 날씨를 확인한다
4. 간결한 요약을 작성하여 전송한다

ClawHub에서 13,000개 이상의 커뮤니티 스킬을 검색하고 설치할 수도 있습니다.

# 스킬 검색
clawhub search "productivity"

# 스킬 설치
clawhub install obsidian github-pr

# 설치된 스킬 확인
openclaw skills list --eligible --verbose

설정 검증과 디버깅

설정 파일에 오타가 있거나 잘못된 값이 들어가면 Gateway가 아예 시작되지 않아요. 이런 상황에서는 openclaw doctor 명령이 유용합니다.

# 설정 검증
openclaw doctor

# 보안 감사 (78가지 항목 점검)
openclaw security audit --deep

# 자동 수정 가능한 항목 수정
openclaw security audit --fix

Gateway가 openclaw.json 파일 변경을 감지해서 대부분의 설정을 자동으로 반영합니다. 다만 포트 변경이나 채널 추가처럼 일부 설정은 재시작이 필요해요.

openclaw gateway restart

참고로 openclaw.json을 직접 편집하는 것 외에도, 웹 UI(http://127.0.0.1:18789의 Config 탭)에서 설정을 변경하거나 openclaw onboard 명령으로 대화형 설정을 진행할 수도 있습니다.

마치며

openclaw.json은 OpenClaw의 두뇌라면, 워크스페이스의 마크다운 파일들은 성격입니다. 이 글에서는 시스템이 “어떻게 동작하는가”를 다뤘고, 에이전트가 “어떤 존재인가”는 워크스페이스 가이드에서 다루고 있습니다.

처음에는 채널 설정과 보안 정책만 잡아두고, 나머지는 필요할 때마다 추가해 나가면 됩니다.

OpenClaw를 아직 설치하지 않으셨다면 OpenClaw 소개 글을 먼저 읽어 보시고, 에이전트 스킬에 대해서도 알아보세요. 공식 문서는 docs.openclaw.ai에서 확인할 수 있습니다.

This work is licensed under CC BY 4.0 CC BY

개발자를 위한 뉴스레터

달레가 정리한 AI 개발 트렌드와 직접 만든 콘텐츠를 전해드립니다.

관련 포스트

OpenClaw: 메신저에서 만나는 AI 비서

여러분은 WhatsApp, Telegram, Discord, Slack 같은 메신저를 하루에 얼마나 사용하시나요? 대부분이 이미 익숙하게 사용하는 이런 플랫폼에서 AI 비서를 직접 만날 수 있다면 어떨까요? 오늘 소개할 OpenClaw는 바로 그런 도구입니다. 🦞 OpenClaw란? OpenClaw는 여러분의 기기에서 직접 실행되는 개인 AI 비서입니다. 가장 큰 특징은 우리가 매일 사용하는 메신저 플랫폼을 통해 AI와 소통할 수 있다는 점인데요. WhatsApp, Telegram, Slack, Discord, Signal, iM

OpenClaw 워크스페이스: 마크다운 파일 정리

OpenClaw를 설치하고 나면 ~/.openclaw/workspace/ 디렉토리에 여러 마크다운 파일이 생기는데요. 이 파일들이 에이전트의 성격, 행동, 기억을 결정합니다. 잘 다듬으면 에이전트가 확 달라지고, 대충 남겨두면 범용 챗봇이랑 큰 차이가 없어요. 오늘은 워크스페이스의 마크다운 파일을 하나씩 살펴보면서 에이전트를 나만의 비서로 만드는 방법을 알아보겠습니다. 🦞 워크스페이스란? OpenClaw의 설정은 두 곳에 나뉘어 있습니다. openclaw.json이나 .env 같은 시스템 설정은 ~/.openclaw/에 있고, 에

Agent Skills: AI를 위한 업무 매뉴얼

AI 코딩 에이전트를 사용하다 보면 같은 종류의 작업을 반복적으로 요청하게 될 때가 있습니다. 예를 들어, "이 프로젝트에서는 Jest 대신 Vitest를 사용해", "API 테스트를 작성할 때는 이런 패턴을 따라줘", "마이그레이션 스크립트를 작성할 때는 항상 롤백 코드도 함께 작성해" 같은 지시를 매번 반복하게 되죠. 🤔 AGENTS.md나 CLAUDE.md 같은 컨텍스트 파일로 프로젝트 전반에 대한 정보를 제공할 수 있지만, 특정 작업에 대한 세부 지침까지 모두 담기에는 한계가 있습니다. 컨텍스트 파일이 너무 길어지면 AI가

Moltbook: AI 에이전트들의 소셜 네트워크

AI 에이전트들이 서로 대화하고 커뮤니티를 만들고, 심지어 자체적인 종교까지 창시한다면 믿으시겠어요? 🤯 2026년 1월 말, "에이전트 인터넷의 첫 페이지"라는 슬로건을 내건 소셜 네트워크가 등장했습니다. 이름은 Moltbook. Reddit과 비슷한 형태의 이 플랫폼은 인간이 아닌 AI 에이전트만 글을 쓰고 댓글을 달고 투표할 수 있도록 설계되었는데요. 출시 72시간 만에 150만 에이전트가 가입했고 Elon Musk는 "특이점의 초기 단계"라고 평했습니다. 수많은 언론이 앞다투어 보도하기도 했고요. 대체 뭐길래 이 난리인지,