서문
OpenClaw의 모든 동작은 하나의 설정 파일로 구동됩니다. 기본 위치는 ~/.openclaw/openclaw.json입니다. 다른 글에서 기능별로 각 설정 섹션을 소개했지만, 실제 운영 시에는 "필드 수준"의 빠른 참조 매뉴얼이 필요한 경우가 많습니다. 이 글에서는 openclaw.json의 모든 유효한 필드를 표 형식으로 나열하고, 타입, 기본값, 제약 조건을 표시하여 설정 편집 시 빠르게 찾을 수 있도록 합니다.
최상위 구조
openclaw.json의 최상위는 다음 설정 섹션으로 구성됩니다:
{
"gateway": {},
"models": {},
"channels": {},
"agents": {},
"sessions": {},
"skills": {},
"persona": {},
"logging": {},
"security": {},
"advanced": {}
}
각 설정 섹션은 독립적이며, 실제로 사용하는 부분만 입력하면 나머지는 기본값이 적용됩니다.
gateway 필드 참조
게이트웨이는 OpenClaw의 HTTP 진입점으로, 모든 채널의 Webhook 콜백과 Dashboard 요청을 수신합니다.
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
port |
number | 18789 |
게이트웨이 수신 포트 |
host |
string | "127.0.0.1" |
수신 주소, "0.0.0.0"으로 설정하면 외부 연결 수신 가능 |
dashboardPassword |
string | "" |
Dashboard 접근 비밀번호, 비어 있으면 인증 불필요 |
apiKey |
string | "" |
REST API 인증 키 |
timeout |
number | 120000 |
요청 타임아웃, 단위 밀리초 |
maxBodySize |
string | "10mb" |
요청 본문 크기 상한 |
cors.enabled |
boolean | true |
CORS 활성화 여부 |
cors.origins |
string[] | ["*"] |
허용할 출처 도메인 목록 |
webhookBase |
string | "" |
Webhook 기본 URL, 콜백 주소 자동 등록에 사용 |
models 필드 참조
모델 설정은 OpenClaw이 연결할 AI 백엔드를 결정합니다.
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
default |
string | "claude" |
기본 모델 제공자 이름 |
providers.<name>.apiKey |
string | 필수 | 제공자 API 키 |
providers.<name>.model |
string | 필수 | 사용할 모델 식별자 |
providers.<name>.maxTokens |
number | 4096 |
단일 응답 최대 Token 수 |
providers.<name>.temperature |
number | 0.7 |
온도 매개변수, 0-2 사이 |
providers.<name>.baseUrl |
string | 제공자에 따라 다름 | 커스텀 API 엔드포인트 |
providers.<name>.headers |
object | {} |
추가 HTTP 요청 헤더 |
routing.rules |
array | [] |
모델 라우팅 규칙 배열 |
routing.fallback |
string | default과 동일 |
라우팅 미일치 시 폴백 모델 |
channels 필드 참조
채널 설정은 OpenClaw이 연결할 메신저 플랫폼을 정의합니다. 각 채널 유형은 공통 필드와 전용 필드를 가집니다.
공통 채널 필드
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
enabled |
boolean | false |
이 채널 활성화 여부 |
allowedUsers |
array | [] |
사용자 화이트리스트, 비어 있으면 제한 없음 |
allowedGroups |
array | [] |
그룹 화이트리스트 |
webhookPath |
string | 자동 생성 | 커스텀 Webhook 경로 |
mediaSupport |
object | 채널 기본값 | 미디어 타입 지원 스위치 |
Telegram 전용 필드
| 필드 | 타입 | 설명 |
|---|---|---|
token |
string | Bot Token |
parseMode |
string | 메시지 파싱 모드: "Markdown" 또는 "HTML" |
groupRules.triggerOnMention |
boolean | @멘션 시에만 응답할지 여부 |
WhatsApp 전용 필드
| 필드 | 타입 | 설명 |
|---|---|---|
phoneNumber |
string | 바인딩된 전화번호 |
accessToken |
string | Business API 접근 토큰 |
verifyToken |
string | Webhook 검증 토큰 |
Discord 전용 필드
| 필드 | 타입 | 설명 |
|---|---|---|
token |
string | Bot Token |
allowedChannels |
string[] | 상호작용을 허용할 채널명 또는 ID 목록 |
agents 필드 참조
Agent 설정은 멀티 에이전트 라우팅의 동작을 정의합니다.
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
default |
string | "default" |
기본 Agent ID |
list[].id |
string | 필수 | Agent 고유 식별자 |
list[].name |
string | 필수 | Agent 표시 이름 |
list[].model |
string | 전역 상속 | 해당 Agent가 사용할 모델 |
list[].systemPrompt |
string | "" |
Agent 전용 시스템 프롬프트 |
list[].skills |
string[] | [] |
해당 Agent가 사용 가능한 스킬 목록 |
list[].knowledgeBase |
string | "" |
지식 베이스 디렉터리 경로 |
sessions 필드 참조
세션 설정은 대화 기록의 저장 및 관리를 제어합니다.
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
storageFormat |
string | "jsonl" |
저장 형식, 현재 JSONL만 지원 |
storagePath |
string | "~/.openclaw/agents/<agentId>/sessions/" |
세션 파일 디렉터리 |
maxHistoryMessages |
number | 50 |
컨텍스트에 유지할 최대 메시지 수 |
maxHistoryTokens |
number | 8000 |
컨텍스트에 유지할 최대 Token 수 |
autoCompaction |
boolean | true |
컨텍스트 오버플로 시 자동 압축 여부 |
compactionStrategy |
string | "summary" |
압축 전략: "summary" 또는 "truncate" |
treeStructure |
boolean | true |
트리형 세션 구조 활성화 여부(분기 지원) |
security 필드 참조
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
rateLimit.enabled |
boolean | true |
속도 제한 활성화 여부 |
rateLimit.maxRequests |
number | 60 |
윈도우당 최대 요청 수 |
rateLimit.windowMs |
number | 60000 |
윈도우 기간(밀리초) |
ipWhitelist |
string[] | [] |
IP 화이트리스트 |
ipBlacklist |
string[] | [] |
IP 블랙리스트 |
tls.enabled |
boolean | false |
HTTPS 활성화 여부 |
tls.cert |
string | "" |
인증서 파일 경로 |
tls.key |
string | "" |
개인 키 파일 경로 |
logging 필드 참조
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
level |
string | "info" |
로그 수준: debug, info, warn, error |
file |
string | "" |
로그 파일 경로, 비어 있으면 터미널에만 출력 |
maxSize |
string | "10m" |
단일 로그 파일 최대 크기 |
maxFiles |
number | 5 |
보존할 로그 파일 수 |
format |
string | "text" |
출력 형식: "text" 또는 "json" |
advanced 필드 참조
| 필드 | 타입 | 기본값 | 설명 |
|---|---|---|---|
workers |
number | 0 |
워커 스레드 수, 0은 자동 |
queueSize |
number | 100 |
메시지 큐 크기 |
storage |
string | "sqlite" |
데이터 저장 백엔드 |
dbPath |
string | "~/.openclaw/data/openclaw.db" |
SQLite 데이터베이스 경로 |
redis.url |
string | "" |
Redis 연결 주소 |
redis.db |
number | 0 |
Redis 데이터베이스 번호 |
pluginDir |
string | "~/.openclaw/plugins" |
플러그인 디렉터리 |
설정 검증 및 디버깅
설정을 수정한 후에는 반드시 내장 도구로 검증하세요:
# 설정 파일 문법 및 필수 항목 검증
openclaw doctor
# 현재 적용된 전체 설정 출력(기본값 포함)
openclaw config --dump
--dump 옵션은 명시적으로 설정하지 않은 기본값을 포함한 모든 필드를 터미널에 출력하여, 최종 적용된 설정을 확인하는 데 도움이 됩니다.
정리
이 글에서는 필드 단위로 openclaw.json의 모든 설정 항목을 나열했습니다. 일상 사용 시 이 글을 빠른 참조 매뉴얼로 활용하시길 권장합니다. 대부분의 경우 gateway, models, channels 세 가지 핵심 섹션만 관심을 가지면 되며, 나머지는 기본값을 유지하면 됩니다. 특정 기능 섹션의 사용법을 자세히 알고 싶다면, 해당 주제별 튜토리얼을 참고하세요.