설정 — 에이전트

agents.*, multiAgent.*, session.*, messages.*, talk.* 아래의 에이전트 범위 구성 키입니다. 채널, 도구, Gateway 런타임 및 기타 최상위 키는 구성 참조를 참조하세요.

# 에이전트 기본값

# agents.defaults.workspace

기본값: ~/.openclaw/workspace.

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

# agents.defaults.repoRoot

시스템 프롬프트의 런타임 줄에 표시되는 선택적 저장소 루트입니다. 설정하지 않으면 OpenClaw가 작업 공간에서 위쪽으로 탐색해 자동 감지합니다.

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

# agents.defaults.skills

agents.list[].skills를 설정하지 않는 에이전트에 적용할 선택적 기본 Skills 허용 목록입니다.

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // inherits github, weather
      { id: "docs", skills: ["docs-search"] }, // replaces defaults
      { id: "locked-down", skills: [] }, // no skills
    ],
  },
}

• 기본적으로 Skills를 제한하지 않으려면 agents.defaults.skills를 생략하세요.
• 기본값을 상속하려면 agents.list[].skills를 생략하세요.
• Skills를 사용하지 않으려면 agents.list[].skills: []로 설정하세요.
• 비어 있지 않은 agents.list[].skills 목록은 해당 에이전트의 최종 집합이며, 기본값과 병합되지 않습니다.

# agents.defaults.skipBootstrap

작업 공간 부트스트랩 파일(AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md)의 자동 생성을 비활성화합니다.

{
  agents: { defaults: { skipBootstrap: true } },
}

# agents.defaults.skipOptionalBootstrapFiles

필수 부트스트랩 파일은 계속 작성하면서 선택한 선택적 작업 공간 파일의 생성을 건너뜁니다. 유효한 값: SOUL.md, USER.md, HEARTBEAT.md, IDENTITY.md.

{
  agents: {
    defaults: {
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
    },
  },
}

# agents.defaults.contextInjection

작업 공간 부트스트랩 파일을 시스템 프롬프트에 주입하는 시점을 제어합니다. 기본값: "always".

• "continuation-skip": 안전한 이어받기 턴(완료된 어시스턴트 응답 이후)에서는 작업 공간 부트스트랩 재주입을 건너뛰어 프롬프트 크기를 줄입니다. Heartbeat 실행과 Compaction 이후 재시도는 여전히 컨텍스트를 다시 빌드합니다.
• "never": 모든 턴에서 작업 공간 부트스트랩 및 컨텍스트 파일 주입을 비활성화합니다. 프롬프트 수명 주기를 완전히 직접 소유하는 에이전트(사용자 지정 컨텍스트 엔진, 자체 컨텍스트를 빌드하는 네이티브 런타임, 또는 특수한 부트스트랩 없는 워크플로)에서만 사용하세요. Heartbeat 및 Compaction 복구 턴에서도 주입을 건너뜁니다.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

# agents.defaults.bootstrapMaxChars

잘라내기 전 작업 공간 부트스트랩 파일당 최대 문자 수입니다. 기본값: 12000.

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

# agents.defaults.bootstrapTotalMaxChars

모든 작업 공간 부트스트랩 파일에 걸쳐 주입되는 총 최대 문자 수입니다. 기본값: 60000.

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

# agents.defaults.bootstrapPromptTruncationWarning

부트스트랩 컨텍스트가 잘릴 때 에이전트가 볼 수 있는 시스템 프롬프트 알림을 제어합니다. 기본값: "once".

• "off": 잘림 알림 텍스트를 시스템 프롬프트에 주입하지 않습니다.
• "once": 고유한 잘림 시그니처마다 간결한 알림을 한 번 주입합니다(권장).
• "always": 잘림이 있을 때마다 모든 실행에서 간결한 알림을 주입합니다.

상세한 원시/주입 개수와 구성 조정 필드는 컨텍스트/상태 보고서 및 로그 같은 진단 정보에 유지됩니다. 일반 WebChat 사용자/런타임 컨텍스트에는 간결한 복구 알림만 포함됩니다.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

# 컨텍스트 예산 소유권 맵

OpenClaw에는 대용량 프롬프트/컨텍스트 예산이 여러 개 있으며, 하나의 일반 노브를 통해 모두 흐르게 하지 않고 의도적으로 하위 시스템별로 분리되어 있습니다.

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: 일반 작업 공간 부트스트랩 주입.
• agents.defaults.startupContext.*: 최근 일일 memory/*.md 파일을 포함하는 일회성 재설정/시작 모델 실행 프렐류드. 단독 채팅 /new 및 /reset 명령은 모델을 호출하지 않고 확인만 합니다.
• skills.limits.*: 시스템 프롬프트에 주입되는 압축된 Skills 목록.
• agents.defaults.contextLimits.*: 제한된 런타임 발췌와 주입되는 런타임 소유 블록.
• memory.qmd.limits.*: 인덱싱된 메모리 검색 스니펫 및 주입 크기.

한 에이전트에 다른 예산이 필요할 때만 일치하는 에이전트별 재정의를 사용하세요.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextLimits.*

# agents.defaults.startupContext

재설정/시작 모델 실행 시 첫 턴에 주입되는 시작 프렐류드를 제어합니다. 단독 채팅 /new 및 /reset 명령은 모델을 호출하지 않고 재설정만 확인하므로, 이 프렐류드를 로드하지 않습니다.

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

# agents.defaults.contextLimits

제한된 런타임 컨텍스트 표면을 위한 공유 기본값입니다.

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: 잘림 메타데이터와 이어받기 알림이 추가되기 전 기본 memory_get 발췌 상한입니다.
• memoryGetDefaultLines: lines가 생략되었을 때 기본 memory_get 줄 창입니다.
• toolResultMaxChars: 저장된 결과와 오버플로 복구에 사용되는 실시간 도구 결과 상한입니다.
• postCompactionMaxChars: Compaction 이후 새로고침 주입 중 사용되는 AGENTS.md 발췌 상한입니다.

# agents.list[].contextLimits

공유 contextLimits 노브에 대한 에이전트별 재정의입니다. 생략된 필드는 agents.defaults.contextLimits에서 상속됩니다.

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

# skills.limits.maxSkillsPromptChars

시스템 프롬프트에 주입되는 압축된 Skills 목록의 전역 상한입니다. 이는 필요할 때 SKILL.md 파일을 읽는 데 영향을 주지 않습니다.

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

# agents.list[].skillsLimits.maxSkillsPromptChars

Skills 프롬프트 예산에 대한 에이전트별 재정의입니다.

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

# agents.defaults.imageMaxDimensionPx

제공자 호출 전 트랜스크립트/도구 이미지 블록에서 이미지의 가장 긴 변에 대한 최대 픽셀 크기입니다. 기본값: 1200.

값이 낮을수록 일반적으로 스크린샷이 많은 실행에서 비전 토큰 사용량과 요청 페이로드 크기가 줄어듭니다. 값이 높을수록 더 많은 시각적 세부 정보를 보존합니다.

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

# agents.defaults.userTimezone

시스템 프롬프트 컨텍스트의 시간대입니다(메시지 타임스탬프 아님). 호스트 시간대로 폴백합니다.

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

# agents.defaults.timeFormat

시스템 프롬프트의 시간 형식입니다. 기본값: auto(OS 환경설정).

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

# agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-2",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      agentRuntime: {
        id: "pi", // pi | auto | registered harness id, e.g. codex
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: 문자열("provider/model") 또는 객체({ primary, fallbacks })를 허용합니다.
  • 문자열 형식은 기본 모델만 설정합니다.
  • 객체 형식은 기본 모델과 순서가 지정된 장애 조치 모델을 설정합니다.
• imageModel: 문자열("provider/model") 또는 객체({ primary, fallbacks })를 허용합니다.
  • image 도구 경로에서 비전 모델 구성으로 사용됩니다.
  • 선택된/기본 모델이 이미지 입력을 받을 수 없을 때 대체 라우팅으로도 사용됩니다.
  • 명시적인 provider/model 참조를 권장합니다. 호환성을 위해 단독 ID도 허용됩니다. 단독 ID가 models.providers.*.models에서 구성된 이미지 지원 항목 하나와 고유하게 일치하면 OpenClaw가 해당 제공자로 한정합니다. 구성된 일치 항목이 모호하면 명시적인 제공자 접두사가 필요합니다.
• imageGenerationModel: 문자열("provider/model") 또는 객체({ primary, fallbacks })를 허용합니다.
  • 공유 이미지 생성 기능과 이미지를 생성하는 향후 모든 도구/Plugin 표면에서 사용됩니다.
  • 일반적인 값: 네이티브 Gemini 이미지 생성에는 google/gemini-3.1-flash-image-preview, fal에는 fal/fal-ai/flux/dev, OpenAI Images에는 openai/gpt-image-2, 투명 배경 OpenAI PNG/WebP 출력에는 openai/gpt-image-1.5를 사용합니다.
  • 제공자/모델을 직접 선택하는 경우 일치하는 제공자 인증도 구성하세요(예: google/*에는 GEMINI_API_KEY 또는 GOOGLE_API_KEY, openai/gpt-image-2 / openai/gpt-image-1.5에는 OPENAI_API_KEY 또는 OpenAI Codex OAuth, fal/*에는 FAL_KEY).
  • 생략하면 image_generate는 여전히 인증이 설정된 제공자 기본값을 추론할 수 있습니다. 현재 기본 제공자를 먼저 시도한 다음, 나머지 등록된 이미지 생성 제공자를 제공자 ID 순서대로 시도합니다.
• musicGenerationModel: 문자열("provider/model") 또는 객체({ primary, fallbacks })를 허용합니다.
  • 공유 음악 생성 기능과 내장 music_generate 도구에서 사용됩니다.
  • 일반적인 값: google/lyria-3-clip-preview, google/lyria-3-pro-preview 또는 minimax/music-2.6.
  • 생략하면 music_generate는 여전히 인증이 설정된 제공자 기본값을 추론할 수 있습니다. 현재 기본 제공자를 먼저 시도한 다음, 나머지 등록된 음악 생성 제공자를 제공자 ID 순서대로 시도합니다.
  • 제공자/모델을 직접 선택하는 경우 일치하는 제공자 인증/API 키도 구성하세요.
• videoGenerationModel: 문자열("provider/model") 또는 객체({ primary, fallbacks })를 허용합니다.
  • 공유 비디오 생성 기능과 내장 video_generate 도구에서 사용됩니다.
  • 일반적인 값: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash 또는 qwen/wan2.7-r2v.
  • 생략하면 video_generate는 여전히 인증이 설정된 제공자 기본값을 추론할 수 있습니다. 현재 기본 제공자를 먼저 시도한 다음, 나머지 등록된 비디오 생성 제공자를 제공자 ID 순서대로 시도합니다.
  • 제공자/모델을 직접 선택하는 경우 일치하는 제공자 인증/API 키도 구성하세요.
  • 번들로 제공되는 Qwen 비디오 생성 제공자는 출력 비디오 최대 1개, 입력 이미지 1개, 입력 비디오 4개, 지속 시간 10초, 그리고 제공자 수준의 size, aspectRatio, resolution, audio, watermark 옵션을 지원합니다.
• pdfModel: 문자열("provider/model") 또는 객체({ primary, fallbacks })를 허용합니다.
  • 모델 라우팅을 위해 pdf 도구에서 사용됩니다.
  • 생략하면 PDF 도구는 imageModel로 대체한 다음, 해석된 세션/기본 모델로 대체합니다.
• pdfMaxBytesMb: 호출 시 maxBytesMb가 전달되지 않았을 때 pdf 도구의 기본 PDF 크기 제한입니다.
• pdfMaxPages: pdf 도구의 추출 대체 모드에서 고려하는 기본 최대 페이지 수입니다.
• verboseDefault: 에이전트의 기본 상세 출력 수준입니다. 값: "off", "on", "full". 기본값: "off".
• toolProgressDetail: /verbose 도구 요약과 진행 초안 도구 줄의 세부 모드입니다. 값: "explain"(기본값, 간결한 사람이 읽을 수 있는 레이블) 또는 "raw"(사용 가능한 경우 원시 명령/세부 정보 추가). 에이전트별 agents.list[].toolProgressDetail이 이 기본값을 재정의합니다.
• reasoningDefault: 에이전트의 기본 추론 표시 여부입니다. 값: "off", "on", "stream". 에이전트별 agents.list[].reasoningDefault가 이 기본값을 재정의합니다. 구성된 추론 기본값은 메시지별 또는 세션 추론 재정의가 설정되지 않은 경우에만 소유자, 승인된 발신자 또는 운영자 관리자 Gateway 컨텍스트에 적용됩니다.
• elevatedDefault: 에이전트의 기본 elevated-output 수준입니다. 값: "off", "on", "ask", "full". 기본값: "on".
• model.primary: 형식은 provider/model입니다(예: OpenAI API 키 또는 Codex OAuth 액세스의 경우 openai/gpt-5.5). 제공자를 생략하면 OpenClaw는 먼저 별칭을 시도한 다음, 해당 정확한 모델 ID에 대해 고유하게 구성된 제공자 일치를 시도하고, 그 후에야 구성된 기본 제공자로 대체합니다(사용 중단된 호환성 동작이므로 명시적인 provider/model을 권장합니다). 해당 제공자가 더 이상 구성된 기본 모델을 노출하지 않으면 OpenClaw는 오래되어 제거된 제공자 기본값을 표시하는 대신, 처음 구성된 제공자/모델로 대체합니다.
• models: /model에 대해 구성된 모델 카탈로그와 허용 목록입니다. 각 항목에는 alias(단축명)와 params(제공자별 값, 예: temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody)가 포함될 수 있습니다.
  • 안전한 편집: 항목을 추가하려면 openclaw config set agents.defaults.models '<json>' --strict-json --merge를 사용하세요. config set은 --replace를 전달하지 않는 한 기존 허용 목록 항목을 제거하는 교체를 거부합니다.
  • 제공자 범위 구성/온보딩 흐름은 선택한 제공자 모델을 이 맵에 병합하고 이미 구성된 관련 없는 제공자를 보존합니다.
  • 직접 OpenAI Responses 모델의 경우 서버 측 Compaction이 자동으로 활성화됩니다. context_management 주입을 중지하려면 params.responsesServerCompaction: false를 사용하고, 임계값을 재정의하려면 params.responsesCompactThreshold를 사용하세요. OpenAI 서버 측 Compaction을 참조하세요.
• params: 모든 모델에 적용되는 전역 기본 제공자 매개변수입니다. agents.defaults.params에 설정합니다(예: { cacheRetention: "long" }).
• params 병합 우선순위(구성): agents.defaults.params(전역 기준)는 agents.defaults.models["provider/model"].params(모델별)에 의해 재정의되고, 그 다음 agents.list[].params(일치하는 에이전트 ID)가 키별로 재정의합니다. 자세한 내용은 프롬프트 캐싱을 참조하세요.
• params.extra_body/params.extraBody: OpenAI 호환 프록시의 api: "openai-completions" 요청 본문에 병합되는 고급 패스스루 JSON입니다. 생성된 요청 키와 충돌하면 추가 본문이 우선합니다. 비네이티브 completions 경로는 이후에도 OpenAI 전용 store를 제거합니다.
• params.chat_template_kwargs: 최상위 api: "openai-completions" 요청 본문에 병합되는 vLLM/OpenAI 호환 채팅 템플릿 인수입니다. thinking이 꺼진 vllm/nemotron-3-*의 경우, 번들 vLLM Plugin이 자동으로 enable_thinking: false 및 force_nonempty_content: true를 전송합니다. 명시적 chat_template_kwargs는 생성된 기본값을 재정의하며, extra_body.chat_template_kwargs가 여전히 최종 우선순위를 가집니다. vLLM Qwen thinking 제어의 경우 해당 모델 항목에서 params.qwenThinkingFormat을 "chat-template" 또는 "top-level"로 설정하세요.
• compat.supportedReasoningEfforts: 모델별 OpenAI 호환 추론 effort 목록입니다. 실제로 이를 허용하는 사용자 지정 엔드포인트에는 "xhigh"를 포함하세요. 그러면 OpenClaw는 해당 구성된 제공자/모델에 대해 명령 메뉴, Gateway 세션 행, 세션 패치 검증, 에이전트 CLI 검증, llm-task 검증에서 /think xhigh를 노출합니다. 백엔드가 표준 수준에 대해 제공자별 값을 요구하는 경우 compat.reasoningEffortMap을 사용하세요.
• params.preserveThinking: 보존된 thinking을 위한 Z.AI 전용 옵트인입니다. 활성화되고 thinking이 켜져 있으면 OpenClaw는 thinking.clear_thinking: false를 전송하고 이전 reasoning_content를 재생합니다. Z.AI thinking 및 보존된 thinking을 참조하세요.
• agentRuntime: 기본 저수준 에이전트 런타임 정책입니다. ID를 생략하면 기본값은 OpenClaw Pi입니다. 내장 PI 하네스를 강제하려면 id: "pi"를 사용하고, 등록된 Plugin 하네스가 지원되는 모델을 클레임하고 일치하는 항목이 없을 때 PI를 사용하도록 하려면 id: "auto"를 사용하며, 해당 하네스를 요구하려면 id: "codex" 같은 등록된 하네스 ID를 사용하거나, 지원되는 CLI 백엔드 별칭(예: id: "claude-cli")을 사용하세요. 명시적 Plugin 런타임은 하네스를 사용할 수 없거나 실패하면 폐쇄적으로 실패합니다. 모델 참조는 provider/model로 정규화해 유지하세요. 레거시 런타임 제공자 접두사 대신 런타임 구성을 통해 Codex, Claude CLI, Gemini CLI 및 기타 실행 백엔드를 선택하세요. 이것이 제공자/모델 선택과 어떻게 다른지는 에이전트 런타임을 참조하세요.
• 이러한 필드를 변경하는 구성 작성기(예: /models set, /models set-image, 대체 추가/제거 명령)는 정규 객체 형식으로 저장하고 가능한 경우 기존 대체 목록을 보존합니다.
• maxConcurrent: 세션 전체의 최대 병렬 에이전트 실행 수입니다(각 세션은 여전히 직렬화됩니다). 기본값: 4.

# agents.defaults.agentRuntime

agentRuntime은 에이전트 턴을 실행하는 저수준 실행기를 제어합니다. 대부분의 배포는 기본 OpenClaw Pi 런타임을 유지해야 합니다. 번들 Codex 앱 서버 하네스처럼 신뢰할 수 있는 Plugin이 네이티브 하네스를 제공하거나 Claude CLI 같은 지원되는 CLI 백엔드를 사용하려는 경우 사용하세요. 개념적 모델은 에이전트 런타임을 참조하세요.

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

• id: "auto", "pi", 등록된 Plugin 하네스 ID 또는 지원되는 CLI 백엔드 별칭입니다. 번들 Codex Plugin은 codex를 등록하며, 번들 Anthropic Plugin은 claude-cli CLI 백엔드를 제공합니다.
• id: "auto"는 등록된 Plugin 하네스가 지원되는 턴을 클레임하도록 하고, 일치하는 하네스가 없으면 PI를 사용합니다. id: "codex" 같은 명시적 Plugin 런타임은 해당 하네스를 요구하며, 사용할 수 없거나 실패하면 폐쇄적으로 실패합니다.
• 환경 재정의: OPENCLAW_AGENT_RUNTIME=<id|auto|pi>는 해당 프로세스의 id를 재정의합니다.
• OpenAI 에이전트 모델은 기본적으로 Codex 하네스를 사용합니다. 이를 명시하고 싶을 때 agentRuntime.id: "codex"는 여전히 유효합니다.
• Claude CLI 배포의 경우 model: "anthropic/claude-opus-4-7"와 agentRuntime.id: "claude-cli"를 함께 사용하는 것을 권장합니다. 레거시 claude-cli/claude-opus-4-7 모델 참조는 호환성을 위해 여전히 작동하지만, 새 구성에서는 제공자/모델 선택을 정규 형식으로 유지하고 실행 백엔드를 agentRuntime.id에 두어야 합니다.
• 오래된 런타임 정책 키는 openclaw doctor --fix에 의해 agentRuntime으로 다시 작성됩니다.
• 하네스 선택은 첫 번째 임베디드 실행 후 세션 ID별로 고정됩니다. 구성/env 변경은 기존 transcript가 아니라 새 세션 또는 재설정된 세션에 영향을 줍니다. transcript 기록은 있지만 기록된 핀이 없는 레거시 OpenAI 세션은 Codex를 사용합니다. 오래된 OpenAI PI 핀은 openclaw doctor --fix로 복구할 수 있습니다. /status는 유효 런타임을 보고합니다. 예: Runtime: OpenClaw Pi Default 또는 Runtime: OpenAI Codex.
• 이는 텍스트 에이전트 턴 실행만 제어합니다. 미디어 생성, 비전, PDF, 음악, 비디오, TTS는 여전히 각각의 제공자/모델 설정을 사용합니다.

내장 별칭 단축형(agents.defaults.models에 모델이 있는 경우에만 적용):

구성한 별칭은 항상 기본값보다 우선합니다.

Z.AI GLM-4.x 모델은 --thinking off를 설정하거나 agents.defaults.models["zai/<model>"].params.thinking을 직접 정의하지 않으면 thinking 모드를 자동으로 활성화합니다. Z.AI 모델은 도구 호출 스트리밍을 위해 기본적으로 tool_stream을 활성화합니다. 비활성화하려면 agents.defaults.models["zai/<model>"].params.tool_stream을 false로 설정하세요. Anthropic Claude 4.6 모델은 명시적인 thinking 수준이 설정되지 않은 경우 기본값으로 adaptive thinking을 사용합니다.

# agents.defaults.cliBackends

텍스트 전용 폴백 실행(도구 호출 없음)을 위한 선택적 CLI 백엔드입니다. API 제공자가 실패할 때 백업으로 유용합니다.

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• CLI 백엔드는 텍스트 우선이며, 도구는 항상 비활성화됩니다.
• sessionArg가 설정되면 세션이 지원됩니다.
• imageArg가 파일 경로를 허용하면 이미지 패스스루가 지원됩니다.

# agents.defaults.systemPromptOverride

OpenClaw가 조립한 전체 시스템 프롬프트를 고정 문자열로 대체합니다. 기본 수준(agents.defaults.systemPromptOverride) 또는 에이전트별(agents.list[].systemPromptOverride)로 설정하세요. 에이전트별 값이 우선합니다. 비어 있거나 공백만 있는 값은 무시됩니다. 제어된 프롬프트 실험에 유용합니다.

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

# agents.defaults.promptOverlays

모델 패밀리별로 적용되는 제공자 독립 프롬프트 오버레이입니다. GPT-5 계열 모델 ID는 제공자 전반에서 공유 동작 계약을 받으며, personality는 친근한 상호작용 스타일 계층만 제어합니다.

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

• "friendly"(기본값)와 "on"은 친근한 상호작용 스타일 계층을 활성화합니다.
• "off"는 친근한 계층만 비활성화하며, 태그된 GPT-5 동작 계약은 계속 활성화됩니다.
• 이 공유 설정이 지정되지 않은 경우 레거시 plugins.entries.openai.config.personality도 계속 읽습니다.

# agents.defaults.heartbeat

주기적인 Heartbeat 실행입니다.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: 기간 문자열(ms/s/m/h)입니다. 기본값: 30m(API 키 인증) 또는 1h(OAuth 인증). 비활성화하려면 0m으로 설정하세요.
• includeSystemPromptSection: false이면 시스템 프롬프트에서 Heartbeat 섹션을 생략하고 부트스트랩 컨텍스트에 HEARTBEAT.md 삽입을 건너뜁니다. 기본값: true.
• suppressToolErrorWarnings: true이면 Heartbeat 실행 중 도구 오류 경고 페이로드를 억제합니다.
• timeoutSeconds: Heartbeat 에이전트 턴이 중단되기 전에 허용되는 최대 시간(초)입니다. 설정하지 않으면 agents.defaults.timeoutSeconds를 사용합니다.
• directPolicy: 직접/DM 전달 정책입니다. allow(기본값)는 직접 대상 전달을 허용합니다. block은 직접 대상 전달을 억제하고 reason=dm-blocked를 내보냅니다.
• lightContext: true이면 Heartbeat 실행은 경량 부트스트랩 컨텍스트를 사용하고 워크스페이스 부트스트랩 파일 중 HEARTBEAT.md만 유지합니다.
• isolatedSession: true이면 각 Heartbeat가 이전 대화 기록 없이 새 세션에서 실행됩니다. cron sessionTarget: "isolated"와 동일한 격리 패턴입니다. Heartbeat당 토큰 비용을 약 100K에서 약 2-5K 토큰으로 줄입니다.
• skipWhenBusy: true이면 Heartbeat 실행이 추가 busy lane, 즉 서브에이전트 또는 중첩 명령 작업에서 지연됩니다. Cron lane은 이 플래그가 없어도 항상 Heartbeat를 지연합니다.
• 에이전트별: agents.list[].heartbeat를 설정하세요. 어떤 에이전트라도 heartbeat를 정의하면 해당 에이전트만 Heartbeat를 실행합니다.
• Heartbeat는 전체 에이전트 턴을 실행합니다. 간격이 짧을수록 더 많은 토큰을 소비합니다.

# agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default 또는 safeguard(긴 기록을 위한 청크 단위 요약)입니다. Compaction을 참고하세요.
• provider: 등록된 compaction 제공자 Plugin의 ID입니다. 설정하면 내장 LLM 요약 대신 제공자의 summarize()가 호출됩니다. 실패 시 내장 방식으로 폴백합니다. 제공자를 설정하면 mode: "safeguard"가 강제됩니다. Compaction을 참고하세요.
• timeoutSeconds: OpenClaw가 단일 Compaction 작업을 중단하기 전에 허용하는 최대 초입니다. 기본값: 900.
• keepRecentTokens: 가장 최근 transcript tail을 그대로 유지하기 위한 Pi 컷 포인트 예산입니다. 명시적으로 설정된 경우 수동 /compact가 이를 따르며, 그렇지 않으면 수동 Compaction은 하드 체크포인트입니다.
• identifierPolicy: strict(기본값), off, 또는 custom입니다. strict는 Compaction 요약 중 내장 불투명 식별자 보존 지침을 앞에 추가합니다.
• identifierInstructions: identifierPolicy=custom일 때 사용되는 선택적 사용자 지정 식별자 보존 텍스트입니다.
• qualityGuard: safeguard 요약에서 형식이 잘못된 출력을 재시도하는 검사입니다. safeguard 모드에서 기본적으로 활성화되며, 감사를 건너뛰려면 enabled: false로 설정하세요.
• midTurnPrecheck: 선택적 Pi 도구 루프 압력 검사입니다. enabled: true이면 OpenClaw는 도구 결과가 추가된 후 다음 모델 호출 전에 컨텍스트 압력을 확인합니다. 컨텍스트가 더 이상 맞지 않으면 프롬프트를 제출하기 전에 현재 시도를 중단하고 기존 precheck 복구 경로를 재사용해 도구 결과를 잘라내거나 Compaction한 뒤 재시도합니다. default와 safeguard Compaction 모드 모두에서 작동합니다. 기본값: 비활성화.
• postCompactionSections: Compaction 후 다시 삽입할 선택적 AGENTS.md H2/H3 섹션 이름입니다. 기본값은 ["Session Startup", "Red Lines"]입니다. 재삽입을 비활성화하려면 []로 설정하세요. 설정되지 않았거나 해당 기본 쌍으로 명시적으로 설정된 경우, 이전 Every Session/Safety 제목도 레거시 폴백으로 허용됩니다.
• model: Compaction 요약에만 사용할 선택적 provider/model-id 재정의입니다. 메인 세션은 한 모델을 유지하되 Compaction 요약은 다른 모델에서 실행해야 할 때 사용하세요. 설정하지 않으면 Compaction은 세션의 기본 모델을 사용합니다.
• maxActiveTranscriptBytes: 활성 JSONL이 임계값을 넘으면 실행 전에 일반 로컬 Compaction을 트리거하는 선택적 바이트 임계값(number 또는 "20mb" 같은 문자열)입니다. 성공한 Compaction이 더 작은 후속 transcript로 회전할 수 있도록 truncateAfterCompaction이 필요합니다. 설정되지 않았거나 0이면 비활성화됩니다.
• notifyUser: true이면 Compaction이 시작될 때와 완료될 때 사용자에게 짧은 알림을 보냅니다(예: "Compacting context..." 및 "Compaction complete"). Compaction을 조용히 유지하기 위해 기본적으로 비활성화됩니다.
• memoryFlush: 자동 Compaction 전에 지속 가능한 메모리를 저장하기 위한 조용한 에이전트 턴입니다. 이 하우스키핑 턴을 로컬 모델에 유지해야 하는 경우 model을 ollama/qwen3:8b 같은 정확한 provider/model로 설정하세요. 이 재정의는 활성 세션 폴백 체인을 상속하지 않습니다. 워크스페이스가 읽기 전용이면 건너뜁니다.

# agents.defaults.contextPruning

LLM으로 보내기 전에 메모리 내 컨텍스트에서 오래된 도구 결과를 정리합니다. 디스크의 세션 기록은 수정하지 않습니다.

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

동작 세부 정보는 세션 프루닝을 참고하세요.

# 블록 스트리밍

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
    },
  },
}

• Telegram이 아닌 채널은 블록 응답을 활성화하려면 명시적인 *.blockStreaming: true가 필요합니다.
• 채널 재정의: channels.<channel>.blockStreamingCoalesce(및 계정별 변형). Signal/Slack/Discord/Google Chat의 기본값은 minChars: 1500입니다.
• humanDelay: 블록 응답 사이의 무작위 일시 정지입니다. natural = 800-2500ms. 에이전트별 재정의: agents.list[].humanDelay.

동작 및 청크 처리 세부 정보는 스트리밍을 참고하세요.

# 입력 표시기

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• 기본값: 직접 채팅/멘션에는 instant, 멘션되지 않은 그룹 채팅에는 message.
• 세션별 재정의: session.typingMode, session.typingIntervalSeconds.

입력 표시기를 참조하세요.

# agents.defaults.sandbox

내장 에이전트용 선택적 샌드박싱입니다. 전체 가이드는 샌드박싱을 참조하세요.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

{
plugins: {
  entries: {
    openshell: {
      enabled: true,
      config: {
        mode: "mirror", // mirror | remote
        from: "openclaw",
        remoteWorkspaceDir: "/sandbox",
        remoteAgentWorkspaceDir: "/agent",
        gateway: "lab", // optional
        gatewayEndpoint: "https://lab.example", // optional
        policy: "strict", // optional OpenShell policy id
        providers: ["openai"], // optional
        autoProviders: true,
        timeoutSeconds: 120,
      },
    },
  },
},
}

브라우저 샌드박싱과 sandbox.docker.binds는 Docker 전용입니다.

이미지 빌드(소스 체크아웃에서):

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

소스 체크아웃 없이 npm 설치를 사용하는 경우 인라인 docker build 명령은 샌드박싱 § 이미지와 설정을 참조하세요.

# agents.list(에이전트별 재정의)

agents.list[].tts를 사용하여 에이전트에 자체 TTS 제공자, 음성, 모델, 스타일 또는 자동 TTS 모드를 지정합니다. 에이전트 블록은 전역 messages.tts 위에 깊게 병합되므로, 공유 자격 증명은 한 곳에 유지하면서 개별 에이전트는 필요한 음성 또는 제공자 필드만 재정의할 수 있습니다. 활성 에이전트의 재정의는 자동 음성 응답, /tts audio, /tts status, 그리고 tts 에이전트 도구에 적용됩니다. 제공자 예시와 우선순위는 텍스트 음성 변환을 참조하세요.

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        agentRuntime: { id: "auto" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: 안정적인 에이전트 id(필수).
• default: 여러 개가 설정되면 첫 번째가 우선합니다(경고가 기록됨). 아무것도 설정되지 않으면 목록의 첫 번째 항목이 기본값입니다.
• model: 문자열 형식은 모델 폴백 없이 엄격한 에이전트별 기본 모델을 설정합니다. 객체 형식 { primary }도 fallbacks를 추가하지 않는 한 엄격합니다. 해당 에이전트에 폴백을 적용하려면 { primary, fallbacks: [...] }를 사용하고, 엄격한 동작을 명시하려면 { primary, fallbacks: [] }를 사용하세요. primary만 재정의하는 Cron 작업은 fallbacks: []를 설정하지 않는 한 여전히 기본 폴백을 상속합니다.
• params: agents.defaults.models에서 선택된 모델 항목 위에 병합되는 에이전트별 스트림 매개변수입니다. 전체 모델 카탈로그를 복제하지 않고 cacheRetention, temperature, maxTokens 같은 에이전트별 재정의에 사용하세요.
• tts: 선택적 에이전트별 텍스트 음성 변환 재정의입니다. 이 블록은 messages.tts 위에 깊은 병합되므로, 공유 제공자 자격 증명과 폴백 정책은 messages.tts에 유지하고 제공자, 음성, 모델, 스타일 또는 자동 모드 같은 페르소나별 값만 여기에서 설정하세요.
• skills: 선택적 에이전트별 skill 허용 목록입니다. 생략하면 설정된 경우 에이전트가 agents.defaults.skills를 상속합니다. 명시적 목록은 기본값과 병합하지 않고 대체하며, []는 Skills 없음을 의미합니다.
• thinkingDefault: 선택적 에이전트별 기본 사고 수준(off | minimal | low | medium | high | xhigh | adaptive | max)입니다. 메시지별 또는 세션별 재정의가 설정되지 않았을 때 이 에이전트에 대해 agents.defaults.thinkingDefault를 재정의합니다. 선택된 제공자/모델 프로필이 유효한 값을 제어합니다. Google Gemini의 경우 adaptive는 제공자 소유의 동적 사고를 유지합니다(Gemini 3/3.1에서는 thinkingLevel 생략, Gemini 2.5에서는 thinkingBudget: -1).
• reasoningDefault: 선택적 에이전트별 기본 추론 표시 여부(on | off | stream)입니다. 메시지별 또는 세션별 추론 재정의가 설정되지 않았을 때 이 에이전트에 대해 agents.defaults.reasoningDefault를 재정의합니다.
• fastModeDefault: 선택적 에이전트별 fast mode 기본값(true | false)입니다. 메시지별 또는 세션별 fast-mode 재정의가 설정되지 않았을 때 적용됩니다.
• agentRuntime: 선택적 에이전트별 저수준 런타임 정책 재정의입니다. 다른 에이전트는 auto 모드에서 기본 PI 폴백을 유지하면서 한 에이전트만 Codex 전용으로 만들려면 { id: "codex" }를 사용하세요.
• runtime: 선택적 에이전트별 런타임 설명자입니다. 에이전트가 기본적으로 ACP 하네스 세션을 사용해야 할 때 runtime.acp 기본값(agent, backend, mode, cwd)과 함께 type: "acp"를 사용하세요.
• identity.avatar: 워크스페이스 상대 경로, http(s) URL 또는 data: URI입니다.
• identity는 기본값을 파생합니다. ackReaction은 emoji에서, mentionPatterns는 name/emoji에서 파생됩니다.
• subagents.allowAgents: 명시적 sessions_spawn.agentId 대상에 대한 에이전트 id 허용 목록입니다(["*"] = 모두, 기본값: 동일 에이전트만). 자체 대상 agentId 호출을 허용해야 하는 경우 요청자 id를 포함하세요.
• 샌드박스 상속 가드: 요청자 세션이 샌드박스된 경우 sessions_spawn은 샌드박스 없이 실행될 대상을 거부합니다.
• subagents.requireAgentId: true이면 agentId를 생략한 sessions_spawn 호출을 차단합니다(명시적 프로필 선택 강제, 기본값: false).

# 멀티 에이전트 라우팅

하나의 Gateway 안에서 여러 격리된 에이전트를 실행합니다. 멀티 에이전트를 참조하세요.

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

# 바인딩 일치 필드

• type(선택 사항): 일반 라우팅은 route(type이 없으면 기본값은 route), 지속 ACP 대화 바인딩은 acp.
• match.channel(필수)
• match.accountId(선택 사항, * = 모든 계정, 생략 = 기본 계정)
• match.peer(선택 사항, { kind: direct|group|channel, id })
• match.guildId / match.teamId(선택 사항, 채널별)
• acp(선택 사항, type: "acp"에만 해당): { mode, label, cwd, backend }

결정적 일치 순서:

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId(정확히 일치, peer/guild/team 없음)
5. match.accountId: "*"(채널 전체)
6. 기본 에이전트

각 단계 안에서는 처음 일치하는 bindings 항목이 우선합니다.

type: "acp" 항목의 경우 OpenClaw는 정확한 대화 식별자(match.channel + 계정 + match.peer.id)로 확인하며, 위의 route 바인딩 단계 순서를 사용하지 않습니다.

# 에이전트별 접근 프로필

{
agents: {
  list: [
    {
      id: "personal",
      workspace: "~/.openclaw/workspace-personal",
      sandbox: { mode: "off" },
    },
  ],
},
}

{
agents: {
  list: [
    {
      id: "family",
      workspace: "~/.openclaw/workspace-family",
      sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
      tools: {
        allow: [
          "read",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
      },
    },
  ],
},
}

{
agents: {
  list: [
    {
      id: "public",
      workspace: "~/.openclaw/workspace-public",
      sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
      tools: {
        allow: [
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
          "whatsapp",
          "telegram",
          "slack",
          "discord",
          "gateway",
        ],
        deny: [
          "read",
          "write",
          "edit",
          "apply_patch",
          "exec",
          "process",
          "browser",
          "canvas",
          "nodes",
          "cron",
          "gateway",
          "image",
        ],
      },
    },
  ],
},
}

우선순위 세부 정보는 Multi-Agent Sandbox & Tools를 참조하세요.

# 세션

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

# 메시지

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "steer",
        telegram: "steer",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

# 응답 접두사

채널/계정별 재정의: channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix.

해결 방식(가장 구체적인 설정이 우선): 계정 → 채널 → 전역. ""는 비활성화하고 연쇄 적용을 중지합니다. "auto"는 [{identity.name}]에서 파생됩니다.

템플릿 변수:

변수는 대소문자를 구분하지 않습니다. {think}는 {thinkingLevel}의 별칭입니다.

# 확인 리액션

• 기본값은 활성 에이전트의 identity.emoji이며, 없으면 "👀"입니다. 비활성화하려면 ""로 설정하세요.
• 채널별 재정의: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• 해결 순서: 계정 → 채널 → messages.ackReaction → ID 대체값.
• 범위: group-mentions(기본값), group-all, direct, all.
• removeAckAfterReply: Slack, Discord, Telegram, WhatsApp, BlueBubbles처럼 리액션을 지원하는 채널에서 답장 후 확인 리액션을 제거합니다.
• messages.statusReactions.enabled: Slack, Discord, Telegram에서 수명 주기 상태 리액션을 활성화합니다. Slack과 Discord에서는 설정하지 않으면 확인 리액션이 활성화되어 있을 때 상태 리액션도 활성화된 상태로 유지됩니다. Telegram에서는 수명 주기 상태 리액션을 활성화하려면 명시적으로 true로 설정하세요.

# 인바운드 디바운스

같은 발신자가 빠르게 보낸 텍스트 전용 메시지를 하나의 에이전트 턴으로 묶습니다. 미디어/첨부 파일은 즉시 플러시됩니다. 제어 명령은 디바운스를 우회합니다.

# TTS(텍스트 음성 변환)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
        microsoft: {
          voice: "en-US-AvaMultilingualNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
      },
    },
  },
}

• auto는 기본 자동 TTS 모드를 제어합니다: off, always, inbound, tagged. /tts on|off는 로컬 환경설정을 재정의할 수 있으며, /tts status는 유효한 상태를 표시합니다.
• summaryModel은 자동 요약에 대해 agents.defaults.model.primary를 재정의합니다.
• modelOverrides는 기본적으로 활성화되어 있으며, modelOverrides.allowProvider의 기본값은 false입니다(옵트인).
• API 키는 ELEVENLABS_API_KEY/XI_API_KEY 및 OPENAI_API_KEY로 대체됩니다.
• 번들 음성 제공자는 Plugin 소유입니다. plugins.allow가 설정된 경우 사용하려는 각 TTS 제공자 Plugin을 포함하세요. 예를 들어 Edge TTS에는 microsoft를 포함합니다. 레거시 edge 제공자 ID는 microsoft의 별칭으로 허용됩니다.
• providers.openai.baseUrl은 OpenAI TTS 엔드포인트를 재정의합니다. 해결 순서는 구성, OPENAI_TTS_BASE_URL, https://api.openai.com/v1입니다.
• providers.openai.baseUrl이 OpenAI가 아닌 엔드포인트를 가리키면 OpenClaw는 이를 OpenAI 호환 TTS 서버로 취급하고 모델/음성 검증을 완화합니다.

# Talk

Talk 모드(macOS/iOS/Android)의 기본값입니다.

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_v3",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime",
          voice: "alloy",
        },
      },
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• 여러 Talk 제공자가 구성된 경우 talk.provider는 talk.providers의 키와 일치해야 합니다.
• 레거시 플랫 Talk 키(talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey)는 호환성 전용입니다. 유지된 구성을 talk.providers.<provider>로 다시 작성하려면 openclaw doctor --fix를 실행하세요.
• 음성 ID는 ELEVENLABS_VOICE_ID 또는 SAG_VOICE_ID로 대체됩니다.
• providers.*.apiKey는 일반 텍스트 문자열 또는 SecretRef 객체를 허용합니다.
• ELEVENLABS_API_KEY 대체값은 Talk API 키가 구성되지 않은 경우에만 적용됩니다.
• providers.*.voiceAliases를 사용하면 Talk 지시문에서 친숙한 이름을 사용할 수 있습니다.
• providers.mlx.modelId는 macOS 로컬 MLX 헬퍼가 사용하는 Hugging Face 저장소를 선택합니다. 생략하면 macOS는 mlx-community/Soprano-80M-bf16을 사용합니다.
• macOS MLX 재생은 번들 openclaw-mlx-tts 헬퍼가 있으면 이를 통해 실행되고, 없으면 PATH의 실행 파일을 통해 실행됩니다. OPENCLAW_MLX_TTS_BIN은 개발용 헬퍼 경로를 재정의합니다.
• speechLocale은 iOS/macOS Talk 음성 인식에 사용되는 BCP 47 로캘 ID를 설정합니다. 기기 기본값을 사용하려면 설정하지 마세요.
• silenceTimeoutMs는 사용자가 조용해진 뒤 Talk 모드가 스크립트를 전송하기 전까지 기다리는 시간을 제어합니다. 설정하지 않으면 플랫폼 기본 일시 중지 창(macOS 및 Android에서는 700 ms, iOS에서는 900 ms)을 유지합니다.

# 관련 항목

• 구성 참조 — 다른 모든 구성 키
• 구성 — 일반 작업 및 빠른 설정
• 구성 예시