구성
OpenClaw는 ~/.openclaw/openclaw.json에서 선택적 <Tooltip tip="JSON5는 주석과 후행 쉼표를 지원합니다">JSON5</Tooltip> 구성을 읽습니다.
파일이 없으면 OpenClaw는 안전한 기본값을 사용합니다. 구성을 추가하는 일반적인 이유:
- 채널을 연결하고 봇에 메시지를 보낼 수 있는 사람을 제어
- 모델, 툴, 샌드박싱, 또는 자동화(cron, 훅) 설정
- 세션, 미디어, 네트워킹, 또는 UI 조정
모든 사용 가능한 필드는 전체 레퍼런스를 참조하십시오.
TIP
구성이 처음이신가요? 대화형 설정을 위해 openclaw onboard로 시작하거나, 완전한 복사-붙여넣기 구성을 위해 구성 예시 가이드를 확인하십시오.
최소 구성
json5
// ~/.openclaw/openclaw.json
{
agents: { defaults: { workspace: "~/.openclaw/workspace" } },
channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}구성 편집
대화형 마법사
bash
openclaw onboard # 전체 온보딩 흐름
openclaw configure # 구성 마법사
```
**CLI (한 줄 명령)**
```bash
openclaw config get agents.defaults.workspace
openclaw config set agents.defaults.heartbeat.every "2h"
openclaw config unset plugins.entries.brave.config.webSearch.apiKey
```
**Control UI**
[http://127.0.0.1:18789](http://127.0.0.1:18789)를 열고 **Config** 탭을 사용하십시오.
Control UI는 라이브 구성 스키마에서 양식을 렌더링하며, 가용한 경우 필드 `title`/`description` 문서 메타데이터와 플러그인 및 채널 스키마를 포함하고, **Raw JSON** 편집기를 이스케이프 해치로 제공합니다. 드릴다운 UI 및 기타 툴링을 위해 게이트웨이는 `config.schema.lookup`도 노출하여 하나의 경로 범위 스키마 노드와 즉각적인 자식 요약을 가져올 수 있습니다.
**직접 편집**
`~/.openclaw/openclaw.json`을 직접 편집하십시오. 게이트웨이는 파일을 감시하고 변경 사항을 자동으로 적용합니다([핫 리로드](#config-hot-reload) 참조).
## 엄격한 유효성 검사
::: warning
OpenClaw는 스키마와 완전히 일치하는 구성만 허용합니다. 알 수 없는 키, 잘못된 유형, 또는 유효하지 않은 값은 게이트웨이가 **시작을 거부**하도록 합니다. 유일한 루트 레벨 예외는 `$schema`(문자열)이며, 편집기가 JSON 스키마 메타데이터를 첨부할 수 있습니다.
:::
스키마 툴링 참고:
- `openclaw config schema`는 Control UI 및 구성 유효성 검사에서 사용하는 동일한 JSON 스키마 패밀리를 출력합니다.
- 해당 스키마 출력을 `openclaw.json`의 표준 기계 읽기 가능 계약으로 처리하십시오.
- `pnpm config:docs:check`는 현재 스키마 표면에 대한 문서 대면 구성 기준 아티팩트 드리프트를 감지합니다.
유효성 검사가 실패하는 경우:
- 게이트웨이가 부팅되지 않습니다
- 진단 명령만 작동합니다(`openclaw doctor`, `openclaw logs`, `openclaw health`, `openclaw status`)
- `openclaw doctor`를 실행하여 정확한 문제 확인
- `openclaw doctor --fix`(또는 `--yes`)를 실행하여 수정 적용
## 일반 작업
::: details 채널 설정 (WhatsApp, Telegram, Discord 등)
각 채널에는 `channels.<provider>` 아래에 자체 구성 섹션이 있습니다. 설정 단계는 전용 채널 페이지를 참조하십시오:
- [WhatsApp](/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/channels/telegram) — `channels.telegram`
- [Discord](/channels/discord) — `channels.discord`
- [Feishu](/channels/feishu) — `channels.feishu`
- [Google Chat](/channels/googlechat) — `channels.googlechat`
- [Microsoft Teams](/channels/msteams) — `channels.msteams`
- [Slack](/channels/slack) — `channels.slack`
- [Signal](/channels/signal) — `channels.signal`
- [iMessage](/channels/imessage) — `channels.imessage`
- [Mattermost](/channels/mattermost) — `channels.mattermost`
모든 채널은 동일한 DM 정책 패턴을 공유합니다:
```json5
{
channels: {
telegram: {
enabled: true,
botToken: "123:abc",
dmPolicy: "pairing", // pairing | allowlist | open | disabled
allowFrom: ["tg:123"], // allowlist/open에만 필요
},
},
}
```
:::
::: details 모델 선택 및 구성
기본 모델과 선택적 폴백 설정:
```json5
{
agents: {
defaults: {
model: {
primary: "anthropic/claude-sonnet-4-6",
fallbacks: ["openai/gpt-5.4"],
},
models: {
"anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
"openai/gpt-5.4": { alias: "GPT" },
},
},
},
}
```
- `agents.defaults.models`는 모델 카탈로그를 정의하고 `/model`의 허용 목록 역할을 합니다.
- 모델 refs는 `provider/model` 형식을 사용합니다(예: `anthropic/claude-opus-4-6`).
- 사용자 정의/자가 호스팅 프로바이더의 경우, 레퍼런스의 [사용자 정의 프로바이더](/gateway/configuration-reference#custom-providers-and-base-urls)를 참조하십시오.
:::
::: details 봇에 메시지를 보낼 수 있는 사람 제어
DM 접근은 `dmPolicy`를 통해 채널별로 제어됩니다:
- `"pairing"` (기본값): 알 수 없는 발신자는 승인을 위한 일회용 페어링 코드를 받습니다
- `"allowlist"`: `allowFrom`에 있는 발신자만(또는 페어링된 허용 저장소)
- `"open"`: 모든 인바운드 DM 허용(`allowFrom: ["*"]` 필요)
- `"disabled"`: 모든 DM 무시
그룹의 경우, `groupPolicy` + `groupAllowFrom` 또는 채널별 허용 목록을 사용하십시오.
채널별 세부 정보는 [전체 레퍼런스](/gateway/configuration-reference#dm-and-group-access)를 참조하십시오.
:::
::: details 그룹 채팅 언급 게이팅 설정
그룹 메시지는 기본적으로 **언급 필요**합니다. 에이전트별 패턴 구성:
```json5
{
agents: {
list: [
{
id: "main",
groupChat: {
mentionPatterns: ["@openclaw", "openclaw"],
},
},
],
},
channels: {
whatsapp: {
groups: { "*": { requireMention: true } },
},
},
}
```
:::
::: details 에이전트별 스킬 제한
공유 기준에 `agents.defaults.skills`를 사용하고, `agents.list[].skills`로 특정 에이전트 재정의:
```json5
{
agents: {
defaults: {
skills: ["github", "weather"],
},
list: [
{ id: "writer" }, // github, weather 상속
{ id: "docs", skills: ["docs-search"] }, // 기본값 대체
{ id: "locked-down", skills: [] }, // 스킬 없음
],
},
}
```
:::
::: details 샌드박싱 활성화
격리된 Docker 컨테이너에서 에이전트 세션 실행:
```json5
{
agents: {
defaults: {
sandbox: {
mode: "non-main", // off | non-main | all
scope: "agent", // session | agent | shared
},
},
},
}
```
먼저 이미지를 빌드하십시오: `scripts/sandbox-setup.sh`
전체 가이드는 [샌드박싱](/gateway/sandboxing)을 참조하십시오.
:::
::: details 하트비트 설정 (주기적 체크인)�OC_CODE_2�
{
gateway: {
reload: { mode: "hybrid", debounceMs: 300 },
},
}�OC_CODE_3�
{
env: {
OPENROUTER_API_KEY: "sk-or-...",
vars: { GROQ_API_KEY: "gsk-..." },
},
}�OC_CODE_4�
{
env: {
shellEnv: { enabled: true, timeoutMs: 15000 },
},
}�OC_CODE_5�
{
gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}�OC_CODE_6�
{
models: {
providers: {
openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
},
},
skills: {
entries: {
"image-lab": {
apiKey: {
source: "file",
provider: "filemain",
id: "/skills/entries/image-lab/apiKey",
},
},
},
},
}SecretRef 세부 정보는 시크릿 관리를 참조하십시오. 지원되는 자격 증명 경로는 SecretRef 자격 증명 표면에 나열되어 있습니다. :::
전체 우선순위 및 소스는 환경을 참조하십시오.
전체 레퍼런스
완전한 필드별 레퍼런스는 **구성 레퍼런스**를 참조하십시오.