การกำหนดค่า — เอเจนต์

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ค่าเริ่มต้นของ Agent

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.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
    ],
  },
}

• ละ agents.defaults.skills เพื่อให้ใช้ skills ได้ไม่จำกัดโดยค่าเริ่มต้น
• ละ agents.list[].skills เพื่อสืบทอดค่าเริ่มต้น
• ตั้งค่า agents.list[].skills: [] เพื่อไม่ให้มี skills
• รายการ agents.list[].skills ที่ไม่ว่างเปล่าคือชุดสุดท้ายสำหรับ agent นั้น และ จะไม่รวมกับค่าเริ่มต้น

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip": เทิร์นการต่อเนื่องที่ปลอดภัย (หลังจากคำตอบของ assistant เสร็จสมบูรณ์) จะข้ามการฉีด bootstrap ของ workspace ซ้ำ เพื่อลดขนาด prompt การรัน Heartbeat และการลองใหม่หลัง Compaction ยังคงสร้างบริบทใหม่
• "never": ปิดใช้งาน bootstrap ของ workspace และการฉีดไฟล์บริบทในทุกเทิร์น ใช้ค่านี้เฉพาะกับ agent ที่ควบคุมวงจรชีวิต prompt ของตนเองอย่างสมบูรณ์ (เอนจินบริบทแบบกำหนดเอง รันไทม์เนทีฟที่สร้างบริบทของตนเอง หรือเวิร์กโฟลว์เฉพาะทางที่ไม่ต้องใช้ bootstrap) เทิร์น Heartbeat และเทิร์นกู้คืนหลัง Compaction ก็จะข้ามการฉีดด้วย

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": ไม่ฉีดข้อความแจ้งการตัดทอนเข้าไปใน system prompt
• "once": ฉีดประกาศแบบกระชับหนึ่งครั้งต่อ signature การตัดทอนที่ไม่ซ้ำกัน (แนะนำ)
• "always": ฉีดประกาศแบบกระชับในทุกการรันเมื่อมีการตัดทอน

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

​

แผนผังเจ้าของงบบริบท

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: การฉีด bootstrap ของ workspace ตามปกติ
• agents.defaults.startupContext.*: prelude สำหรับการรันโมเดลแบบ one-shot เมื่อ reset/startup รวมถึงไฟล์ memory/*.md รายวันล่าสุด คำสั่งแชตเปล่า /new และ /reset จะได้รับการตอบรับ โดยไม่เรียกโมเดล
• skills.limits.*: รายการ skills แบบย่อที่ฉีดเข้าไปใน system prompt
• agents.defaults.contextLimits.*: excerpt ของรันไทม์ที่มีขอบเขตและบล็อกที่ฉีดซึ่งรันไทม์เป็นเจ้าของ
• memory.qmd.limits.*: snippet ค้นหาหน่วยความจำแบบจัดทำดัชนีและขนาดการฉีด

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

​

agents.defaults.startupContext

{
  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: เพดาน excerpt เริ่มต้นของ memory_get ก่อนเพิ่ม metadata การตัดทอนและประกาศการต่อเนื่อง
• memoryGetDefaultLines: หน้าต่างบรรทัดเริ่มต้นของ memory_get เมื่อ ละ lines
• toolResultMaxChars: เพดานผลลัพธ์เครื่องมือแบบสดที่ใช้สำหรับผลลัพธ์ที่บันทึกถาวรและ การกู้คืน overflow
• postCompactionMaxChars: เพดาน excerpt ของ AGENTS.md ที่ใช้ระหว่างการฉีด รีเฟรชหลัง Compaction

​

agents.list[].contextLimits

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

​

skills.limits.maxSkillsPromptChars

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

​

agents.list[].skillsLimits.maxSkillsPromptChars

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

​

agents.defaults.imageMaxDimensionPx

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

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

{
  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
      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 })
  • รูปแบบสตริงตั้งค่าเฉพาะโมเดลหลักเท่านั้น
  • รูปแบบอ็อบเจ็กต์ตั้งค่าโมเดลหลักพร้อมโมเดล failover ตามลำดับ
• imageModel: รับได้ทั้งสตริง ("provider/model") หรืออ็อบเจ็กต์ ({ primary, fallbacks })
  • ใช้โดยเส้นทางเครื่องมือ image เป็นการกำหนดค่าโมเดลวิชัน
  • ใช้เป็นการกำหนดเส้นทางสำรองด้วยเมื่อโมเดลที่เลือก/โมเดลเริ่มต้นรับอินพุตรูปภาพไม่ได้
  • ควรใช้ ref provider/model แบบชัดเจน ID เปล่าจะยังรับได้เพื่อความเข้ากันได้ หาก ID เปล่าตรงกับรายการที่กำหนดค่าไว้และรองรับรูปภาพใน models.providers.*.models เพียงรายการเดียว OpenClaw จะเติม provider นั้นให้ ID ดังกล่าว รายการที่กำหนดค่าไว้ซึ่งตรงกันแบบกำกวมต้องใช้คำนำหน้า provider แบบชัดเจน
• imageGenerationModel: รับได้ทั้งสตริง ("provider/model") หรืออ็อบเจ็กต์ ({ primary, fallbacks })
  • ใช้โดยความสามารถสร้างรูปภาพแบบใช้ร่วมกัน และพื้นผิวเครื่องมือ/Plugin ในอนาคตที่สร้างรูปภาพ
  • ค่าทั่วไป: google/gemini-3.1-flash-image-preview สำหรับการสร้างรูปภาพ Gemini แบบ native, fal/fal-ai/flux/dev สำหรับ fal, openai/gpt-image-2 สำหรับ OpenAI Images หรือ openai/gpt-image-1.5 สำหรับเอาต์พุต OpenAI PNG/WebP พื้นหลังโปร่งใส
  • หากคุณเลือก provider/model โดยตรง ให้กำหนดค่า auth ของ provider ที่ตรงกันด้วย (เช่น GEMINI_API_KEY หรือ GOOGLE_API_KEY สำหรับ google/*, OPENAI_API_KEY หรือ OpenAI Codex OAuth สำหรับ openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY สำหรับ fal/*)
  • หากละไว้ image_generate ยังสามารถอนุมานค่าเริ่มต้นของ provider ที่มี auth รองรับได้ โดยจะลอง provider เริ่มต้นปัจจุบันก่อน จากนั้นจึงลอง provider การสร้างรูปภาพที่ลงทะเบียนไว้ที่เหลือตามลำดับ provider-id
• musicGenerationModel: รับได้ทั้งสตริง ("provider/model") หรืออ็อบเจ็กต์ ({ primary, fallbacks })
  • ใช้โดยความสามารถสร้างเพลงแบบใช้ร่วมกัน และเครื่องมือในตัว music_generate
  • ค่าทั่วไป: google/lyria-3-clip-preview, google/lyria-3-pro-preview หรือ minimax/music-2.6
  • หากละไว้ music_generate ยังสามารถอนุมานค่าเริ่มต้นของ provider ที่มี auth รองรับได้ โดยจะลอง provider เริ่มต้นปัจจุบันก่อน จากนั้นจึงลอง provider การสร้างเพลงที่ลงทะเบียนไว้ที่เหลือตามลำดับ provider-id
  • หากคุณเลือก provider/model โดยตรง ให้กำหนดค่า auth/API key ของ provider ที่ตรงกันด้วย
• 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 ยังสามารถอนุมานค่าเริ่มต้นของ provider ที่มี auth รองรับได้ โดยจะลอง provider เริ่มต้นปัจจุบันก่อน จากนั้นจึงลอง provider การสร้างวิดีโอที่ลงทะเบียนไว้ที่เหลือตามลำดับ provider-id
  • หากคุณเลือก provider/model โดยตรง ให้กำหนดค่า auth/API key ของ provider ที่ตรงกันด้วย
  • provider การสร้างวิดีโอ Qwen ที่รวมมารองรับวิดีโอเอาต์พุตได้สูงสุด 1 รายการ, รูปภาพอินพุต 1 รายการ, วิดีโออินพุต 4 รายการ, ระยะเวลา 10 วินาที และตัวเลือกระดับ provider ได้แก่ size, aspectRatio, resolution, audio และ watermark
• pdfModel: รับได้ทั้งสตริง ("provider/model") หรืออ็อบเจ็กต์ ({ primary, fallbacks })
  • ใช้โดยเครื่องมือ pdf สำหรับการกำหนดเส้นทางโมเดล
  • หากละไว้ เครื่องมือ PDF จะ fallback ไปที่ imageModel แล้วจึงไปที่โมเดลเซสชัน/โมเดลเริ่มต้นที่ resolve แล้ว
• pdfMaxBytesMb: ขีดจำกัดขนาด PDF เริ่มต้นสำหรับเครื่องมือ pdf เมื่อไม่ได้ส่ง maxBytesMb ตอนเรียกใช้
• pdfMaxPages: จำนวนหน้าสูงสุดเริ่มต้นที่โหมด fallback ของการแยกข้อมูลในเครื่องมือ pdf พิจารณา
• verboseDefault: ระดับ verbose เริ่มต้นสำหรับ agent ค่า: "off", "on", "full" ค่าเริ่มต้น: "off"
• toolProgressDetail: โหมดรายละเอียดสำหรับสรุปเครื่องมือ /verbose และบรรทัดเครื่องมือแบบ progress-draft ค่า: "explain" (ค่าเริ่มต้น, ป้ายกำกับสำหรับมนุษย์แบบกระชับ) หรือ "raw" (ต่อท้ายคำสั่ง/รายละเอียด raw เมื่อมี) agents.list[].toolProgressDetail ราย agent จะ override ค่าเริ่มต้นนี้
• reasoningDefault: การมองเห็น reasoning เริ่มต้นสำหรับ agent ค่า: "off", "on", "stream" agents.list[].reasoningDefault ราย agent จะ override ค่าเริ่มต้นนี้ ค่าเริ่มต้นของ reasoning ที่กำหนดค่าไว้จะถูกใช้เฉพาะสำหรับ owner, sender ที่ได้รับอนุญาต หรือบริบท operator-admin ของ Gateway เมื่อไม่มีการตั้งค่า override reasoning รายข้อความหรือรายเซสชัน
• elevatedDefault: ระดับเอาต์พุต elevated เริ่มต้นสำหรับ agent ค่า: "off", "on", "ask", "full" ค่าเริ่มต้น: "on"
• model.primary: รูปแบบ provider/model (เช่น openai/gpt-5.5 สำหรับการเข้าถึงด้วย OpenAI API-key หรือ Codex OAuth) หากคุณละ provider ไว้ OpenClaw จะลอง alias ก่อน จากนั้นจึงลองรายการที่ตรงกันแบบ configured-provider เดียวสำหรับ model id นั้นแบบตรงตัว แล้วจึง fallback ไปที่ provider เริ่มต้นที่กำหนดค่าไว้ (พฤติกรรมความเข้ากันได้ที่เลิกแนะนำแล้ว ดังนั้นควรใช้ provider/model แบบชัดเจน) หาก provider นั้นไม่เผยโมเดลเริ่มต้นที่กำหนดค่าไว้อีกต่อไป OpenClaw จะ fallback ไปยัง provider/model แรกที่กำหนดค่าไว้แทนการแสดงค่าเริ่มต้นของ removed-provider ที่ค้างอยู่
• models: แค็ตตาล็อกโมเดลและ allowlist ที่กำหนดค่าไว้สำหรับ /model แต่ละรายการสามารถมี alias (ทางลัด) และ params (เฉพาะ provider เช่น temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody)
  • ใช้รายการ provider/* เช่น "openai-codex/*": {} หรือ "vllm/*": {} เพื่อแสดงโมเดลที่ค้นพบทั้งหมดสำหรับ provider ที่เลือกโดยไม่ต้องระบุ model id ทุกตัวด้วยตนเอง
  • การแก้ไขที่ปลอดภัย: ใช้ openclaw config set agents.defaults.models '<json>' --strict-json --merge เพื่อเพิ่มรายการ config set จะปฏิเสธการแทนที่ที่จะลบรายการ allowlist ที่มีอยู่ เว้นแต่คุณจะส่ง --replace
  • โฟลว์ configure/onboarding ที่ scope ตาม provider จะ merge โมเดลของ provider ที่เลือกเข้าใน map นี้ และคง provider ที่ไม่เกี่ยวข้องซึ่งกำหนดค่าไว้แล้วไว้
  • สำหรับโมเดล OpenAI Responses โดยตรง Compaction ฝั่งเซิร์ฟเวอร์จะเปิดใช้อัตโนมัติ ใช้ params.responsesServerCompaction: false เพื่อหยุดการ inject context_management หรือใช้ params.responsesCompactThreshold เพื่อ override threshold ดู OpenAI server-side compaction
• params: พารามิเตอร์ provider เริ่มต้นแบบ global ที่ใช้กับทุกโมเดล ตั้งค่าที่ agents.defaults.params (เช่น { cacheRetention: "long" })
• ลำดับความสำคัญการ merge ของ params (config): agents.defaults.params (ฐาน global) จะถูก override โดย agents.defaults.models["provider/model"].params (รายโมเดล) จากนั้น agents.list[].params (agent id ที่ตรงกัน) จะ override ตาม key ดูรายละเอียดใน Prompt Caching
• params.extra_body/params.extraBody: JSON pass-through ขั้นสูงที่ merge เข้าใน request body ของ api: "openai-completions" สำหรับพร็อกซีที่เข้ากันได้กับ OpenAI หากชนกับ key ของ request ที่สร้างขึ้น extra body จะเป็นฝ่ายชนะ เส้นทาง completions ที่ไม่ใช่ native จะยังตัด store เฉพาะ OpenAI ออกหลังจากนั้น
• params.chat_template_kwargs: อาร์กิวเมนต์ chat-template ที่เข้ากันได้กับ vLLM/OpenAI ซึ่ง merge เข้าใน request body ระดับบนสุดของ api: "openai-completions" สำหรับ vllm/nemotron-3-* ที่ปิด thinking อยู่ Plugin vLLM ที่รวมมาจะส่ง enable_thinking: false และ force_nonempty_content: true โดยอัตโนมัติ chat_template_kwargs แบบชัดเจนจะ override ค่าเริ่มต้นที่สร้างขึ้น และ extra_body.chat_template_kwargs ยังมีลำดับความสำคัญสุดท้าย สำหรับการควบคุม thinking ของ vLLM Qwen ให้ตั้งค่า params.qwenThinkingFormat เป็น "chat-template" หรือ "top-level" ในรายการโมเดลนั้น
• compat.thinkingFormat: รูปแบบ payload thinking ที่เข้ากันได้กับ OpenAI ใช้ "qwen" สำหรับ enable_thinking ระดับบนสุดแบบ Qwen หรือ "qwen-chat-template" สำหรับ chat_template_kwargs.enable_thinking บน backend ตระกูล Qwen ที่รองรับ kwargs ของ chat-template ระดับ request เช่น vLLM OpenClaw map thinking ที่ปิดไว้เป็น false และ thinking ที่เปิดไว้เป็น true
• compat.supportedReasoningEfforts: รายการ reasoning effort ที่เข้ากันได้กับ OpenAI รายโมเดล ใส่ "xhigh" สำหรับ endpoint แบบกำหนดเองที่รับค่านี้จริง จากนั้น OpenClaw จะแสดง /think xhigh ในเมนูคำสั่ง, แถวเซสชันของ Gateway, การตรวจสอบ session patch, การตรวจสอบ agent CLI และการตรวจสอบ llm-task สำหรับ provider/model ที่กำหนดค่าไว้นั้น ใช้ compat.reasoningEffortMap เมื่อ backend ต้องการค่าเฉพาะ provider สำหรับระดับ canonical
• params.preserveThinking: การ opt-in เฉพาะ Z.AI สำหรับ preserved thinking เมื่อเปิดใช้และ thinking เปิดอยู่ OpenClaw จะส่ง thinking.clear_thinking: false และ replay reasoning_content ก่อนหน้า ดู Z.AI thinking and preserved thinking
• localService: process manager ระดับ provider แบบไม่บังคับสำหรับเซิร์ฟเวอร์โมเดล local/self-hosted เมื่อโมเดลที่เลือกเป็นของ provider นั้น OpenClaw จะ probe healthUrl (หรือ baseUrl + "/models"), start command พร้อม args หาก endpoint ใช้งานไม่ได้, รอสูงสุด readyTimeoutMs แล้วจึงส่ง request โมเดล command ต้องเป็น path แบบ absolute idleStopMs: 0 จะทำให้ process คงอยู่จนกว่า OpenClaw จะ exit ค่าบวกจะหยุด process ที่ OpenClaw spawn หลังจาก idle เป็นจำนวนมิลลิวินาทีนั้น ดู Local model services
• นโยบาย runtime อยู่บน provider หรือโมเดล ไม่ใช่บน agents.defaults ใช้ models.providers.<provider>.agentRuntime สำหรับกฎทั้ง provider หรือ agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime สำหรับกฎเฉพาะโมเดล โมเดล agent ของ OpenAI บน provider OpenAI อย่างเป็นทางการจะเลือก Codex เป็นค่าเริ่มต้น
• config writer ที่ mutate ฟิลด์เหล่านี้ (เช่น /models set, /models set-image และคำสั่ง fallback add/remove) จะบันทึกรูปแบบอ็อบเจ็กต์ canonical และคงรายการ fallback ที่มีอยู่ไว้เมื่อทำได้
• maxConcurrent: จำนวนการรัน agent แบบขนานสูงสุดข้ามเซสชัน (แต่ละเซสชันยังคงทำงานแบบ serialized) ค่าเริ่มต้น: 4

​

นโยบาย Runtime

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      models: {
        "anthropic/claude-opus-4-7": {
          agentRuntime: { id: "claude-cli" },
        },
      },
    },
  },
}

• id: "auto", "pi", id ของ harness ของ Plugin ที่ลงทะเบียนไว้ หรือ alias ของ CLI backend ที่รองรับ Plugin Codex ที่รวมมาลงทะเบียน codex; Plugin Anthropic ที่รวมมามี CLI backend claude-cli
• id: "auto" ให้ harness ของ Plugin ที่ลงทะเบียนไว้อ้างสิทธิ์ turn ที่รองรับ และใช้ PI เมื่อไม่มี harness ที่ตรงกัน runtime ของ Plugin แบบชัดเจน เช่น id: "codex" ต้องใช้ harness นั้นและ fail closed หากไม่พร้อมใช้งานหรือทำงานล้มเหลว
• key runtime ทั้ง agent เป็น legacy agents.defaults.agentRuntime, agents.list[].agentRuntime, session runtime pins และ OPENCLAW_AGENT_RUNTIME จะถูกละเว้นโดยการเลือก runtime รัน openclaw doctor --fix เพื่อลบค่าค้างเก่า
• โมเดล agent ของ OpenAI ใช้ harness Codex เป็นค่าเริ่มต้น; agentRuntime.id: "codex" ระดับ provider/model ยังคงใช้ได้เมื่อคุณต้องการระบุให้ชัดเจน
• สำหรับ deployment ของ Claude CLI ควรใช้ model: "anthropic/claude-opus-4-7" พร้อม agentRuntime.id: "claude-cli" ที่ scope ตามโมเดล ref โมเดล legacy claude-cli/claude-opus-4-7 ยังใช้ได้เพื่อความเข้ากันได้ แต่ config ใหม่ควรคงการเลือก provider/model ให้เป็น canonical และใส่ execution backend ไว้ในนโยบาย runtime ระดับ provider/model
• สิ่งนี้ควบคุมเฉพาะการประมวลผล turn ของ agent แบบข้อความเท่านั้น การสร้างสื่อ, วิชัน, PDF, เพลง, วิดีโอ และ TTS ยังคงใช้การตั้งค่า provider/model ของตัวเอง

​

agents.defaults.cliBackends

{
  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 รับพาธไฟล์ได้
• reseedFromRawTranscriptWhenUncompacted: true ช่วยให้แบ็กเอนด์กู้คืนเซสชันที่ถูกทำให้ใช้ไม่ได้อย่างปลอดภัยจากส่วนท้ายของทรานสคริปต์ดิบ OpenClaw แบบจำกัดขนาด ก่อนที่จะมีสรุป Compaction แรก การเปลี่ยนโปรไฟล์ยืนยันตัวตนหรือ credential-epoch จะยังไม่ raw-reseed

​

agents.defaults.systemPromptOverride

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

​

agents.defaults.promptOverlays

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

• "friendly" (ค่าเริ่มต้น) และ "on" เปิดใช้งานเลเยอร์รูปแบบการโต้ตอบที่เป็นมิตร
• "off" ปิดใช้งานเฉพาะเลเยอร์ที่เป็นมิตร สัญญาพฤติกรรม GPT-5 ที่ติดแท็กยังคงเปิดใช้งานอยู่
• plugins.entries.openai.config.personality แบบเดิมยังคงถูกอ่านเมื่อยังไม่ได้ตั้งค่าการตั้งค่าร่วมนี้

​

agents.defaults.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 this agent's 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 จะเลื่อนออกไปเมื่อเลนที่ยุ่งเพิ่มเติมของเอเจนต์นั้นกำลังทำงาน ได้แก่ ซับเอเจนต์ตามคีย์เซสชันของตนเองหรืองานคำสั่งแบบซ้อน เลน Cron จะเลื่อน 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: รหัสของ Plugin ผู้ให้บริการ Compaction ที่ลงทะเบียนไว้ เมื่อตั้งค่าแล้ว จะเรียก summarize() ของผู้ให้บริการแทนการสรุปด้วย LLM ในตัว หากล้มเหลวจะถอยกลับไปใช้แบบในตัว การตั้งค่าผู้ให้บริการจะบังคับ mode: "safeguard" ดู Compaction
• timeoutSeconds: จำนวนวินาทีสูงสุดที่อนุญาตให้การดำเนินการ Compaction ครั้งเดียวทำงาน ก่อนที่ OpenClaw จะยกเลิก ค่าเริ่มต้น: 900
• keepRecentTokens: งบประมาณจุดตัด Pi สำหรับเก็บส่วนท้ายของทรานสคริปต์ล่าสุดแบบคำต่อคำ /compact แบบแมนนวลจะเคารพค่านี้เมื่อตั้งไว้อย่างชัดเจน มิฉะนั้น Compaction แบบแมนนวลจะเป็นเช็กพอยต์แบบตายตัว
• identifierPolicy: strict (ค่าเริ่มต้น), off หรือ custom strict จะเติมคำแนะนำในตัวสำหรับการคงตัวระบุแบบทึบไว้ข้างหน้าระหว่างการสรุป Compaction
• identifierInstructions: ข้อความกำหนดเองทางเลือกสำหรับการรักษาตัวระบุ ใช้เมื่อ identifierPolicy=custom
• qualityGuard: การตรวจ retry-on-malformed-output สำหรับสรุปแบบ safeguard เปิดใช้งานเป็นค่าเริ่มต้นในโหมด safeguard ตั้งค่า enabled: false เพื่อข้ามการตรวจสอบ
• midTurnPrecheck: การตรวจแรงกดดัน tool-loop ของ Pi แบบทางเลือก เมื่อ enabled: true OpenClaw จะตรวจแรงกดดันของบริบทหลังจากเพิ่มผลลัพธ์เครื่องมือแล้วและก่อนการเรียกโมเดลครั้งถัดไป หากบริบทไม่พอดีอีกต่อไป จะยกเลิกความพยายามปัจจุบันก่อนส่งพรอมป์ และใช้เส้นทางกู้คืน precheck ที่มีอยู่ซ้ำ เพื่อตัดทอนผลลัพธ์เครื่องมือหรือทำ Compaction แล้วลองใหม่ ทำงานได้กับทั้งโหมด Compaction default และ safeguard ค่าเริ่มต้น: ปิดใช้งาน
• postCompactionSections: ชื่อส่วน H2/H3 ของ AGENTS.md แบบทางเลือกที่จะฉีดกลับเข้าไปหลัง Compaction ค่าเริ่มต้นคือ ["Session Startup", "Red Lines"]; ตั้งค่า [] เพื่อปิดใช้งานการฉีดกลับ เมื่อไม่ได้ตั้งค่าหรือตั้งค่าอย่างชัดเจนเป็นคู่ค่าเริ่มต้นนั้น หัวข้อ Every Session/Safety แบบเก่าจะถูกยอมรับเป็น fallback เดิมด้วย
• model: การแทนที่ provider/model-id ทางเลือกสำหรับการสรุป Compaction เท่านั้น ใช้ค่านี้เมื่อเซสชันหลักควรคงโมเดลหนึ่งไว้ แต่สรุป Compaction ควรรันบนอีกโมเดลหนึ่ง เมื่อไม่ได้ตั้งค่า Compaction จะใช้โมเดลหลักของเซสชัน
• maxActiveTranscriptBytes: เกณฑ์ไบต์ทางเลือก (number หรือสตริงอย่าง "20mb") ที่ทริกเกอร์ Compaction ภายในปกติก่อนการรัน เมื่อ JSONL ที่ใช้งานอยู่โตเกินเกณฑ์ ต้องใช้ truncateAfterCompaction เพื่อให้ Compaction ที่สำเร็จสามารถหมุนไปยังทรานสคริปต์ถัดไปที่เล็กกว่า ปิดใช้งานเมื่อไม่ได้ตั้งค่าหรือเป็น 0
• notifyUser: เมื่อเป็น true จะส่งการแจ้งสั้น ๆ ให้ผู้ใช้เมื่อ Compaction เริ่มและเมื่อเสร็จสิ้น (เช่น “Compacting context…” และ “Compaction complete”) ปิดใช้งานเป็นค่าเริ่มต้นเพื่อให้ Compaction เงียบ
• memoryFlush: เทิร์นเอเจนต์แบบเงียบก่อน auto-compaction เพื่อเก็บความจำถาวร ตั้งค่า model เป็นผู้ให้บริการ/โมเดลที่แน่นอน เช่น ollama/qwen3:8b เมื่อเทิร์นดูแลระบบนี้ควรอยู่บนโมเดล local เท่านั้น การแทนที่นี้จะไม่สืบทอดลำดับ fallback ของเซสชันที่ใช้งานอยู่ ข้ามเมื่อพื้นที่ทำงานเป็นแบบอ่านอย่างเดียว

​

agents.defaults.runRetries

{
  agents: {
    defaults: {
      runRetries: {
        base: 24,
        perProfile: 8,
        min: 32,
        max: 160,
      },
    },
    list: [
      {
        id: "main",
        runRetries: { max: 50 }, // optional per-agent overrides
      },
    ],
  },
}

• base: จำนวนพื้นฐานของการวนซ้ำ retry การรันสำหรับลูปรันชั้นนอก ค่าเริ่มต้น: 24
• perProfile: จำนวนการวนซ้ำ retry การรันเพิ่มเติมที่ให้ต่อผู้สมัครโปรไฟล์ fallback ค่าเริ่มต้น: 8
• min: ขีดจำกัดสัมบูรณ์ขั้นต่ำสำหรับการวนซ้ำ retry การรัน ค่าเริ่มต้น: 32
• max: ขีดจำกัดสัมบูรณ์สูงสุดสำหรับการวนซ้ำ retry การรัน เพื่อป้องกันการดำเนินการหลุดควบคุม ค่าเริ่มต้น: 160

​

agents.defaults.contextPruning

{
  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 การแทนที่ค่าระดับ agent: 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,
        },
      },
    },
  },
}

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

​

agents.list (การแทนที่ค่าต่อ agent)

{
  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
        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 แบบเคร่งครัดต่อเอเจนต์โดยไม่มี model fallback; รูปแบบอ็อบเจกต์ { primary } ก็เคร่งครัดเช่นกัน เว้นแต่คุณจะเพิ่ม fallbacks ใช้ { primary, fallbacks: [...] } เพื่อให้เอเจนต์นั้นเลือกใช้ fallback หรือ { primary, fallbacks: [] } เพื่อระบุพฤติกรรมแบบเคร่งครัดอย่างชัดเจน งาน Cron ที่ override เฉพาะ primary จะยังคงสืบทอด fallback เริ่มต้น เว้นแต่คุณจะตั้ง fallbacks: []
• params: พารามิเตอร์สตรีมต่อเอเจนต์ที่ merge ทับรายการโมเดลที่เลือกใน agents.defaults.models ใช้สิ่งนี้สำหรับ override เฉพาะเอเจนต์ เช่น cacheRetention, temperature หรือ maxTokens โดยไม่ต้องทำซ้ำแคตตาล็อกโมเดลทั้งหมด
• tts: override ข้อความเป็นเสียงต่อเอเจนต์แบบไม่บังคับ บล็อกนี้จะ deep-merge ทับ messages.tts ดังนั้นให้เก็บข้อมูลรับรองผู้ให้บริการที่ใช้ร่วมกันและนโยบาย fallback ไว้ใน messages.tts และตั้งเฉพาะค่าที่ขึ้นกับบุคลิก เช่น ผู้ให้บริการ เสียง โมเดล สไตล์ หรือโหมดอัตโนมัติไว้ที่นี่
• skills: allowlist ของ Skills ต่อเอเจนต์แบบไม่บังคับ หากละไว้ เอเจนต์จะสืบทอด agents.defaults.skills เมื่อตั้งค่าไว้; ลิสต์ที่ระบุอย่างชัดเจนจะแทนที่ค่าเริ่มต้นแทนการ merge และ [] หมายถึงไม่มี Skills
• thinkingDefault: ระดับการคิดเริ่มต้นต่อเอเจนต์แบบไม่บังคับ (off | minimal | low | medium | high | xhigh | adaptive | max) override agents.defaults.thinkingDefault สำหรับเอเจนต์นี้เมื่อไม่ได้ตั้ง override ต่อข้อความหรือเซสชัน โปรไฟล์ผู้ให้บริการ/โมเดลที่เลือกจะควบคุมว่าค่าใดใช้ได้; สำหรับ Google Gemini, adaptive จะคงการคิดแบบไดนามิกที่ผู้ให้บริการเป็นเจ้าของไว้ (thinkingLevel จะถูกละไว้บน Gemini 3/3.1, thinkingBudget: -1 บน Gemini 2.5)
• reasoningDefault: การแสดงผล reasoning เริ่มต้นต่อเอเจนต์แบบไม่บังคับ (on | off | stream) override agents.defaults.reasoningDefault สำหรับเอเจนต์นี้เมื่อไม่ได้ตั้ง override reasoning ต่อข้อความหรือเซสชัน
• fastModeDefault: ค่าเริ่มต้นต่อเอเจนต์แบบไม่บังคับสำหรับโหมดเร็ว (true | false) ใช้เมื่อไม่ได้ตั้ง override โหมดเร็วต่อข้อความหรือเซสชัน
• models: override แคตตาล็อกโมเดล/รันไทม์ต่อเอเจนต์แบบไม่บังคับ โดยใช้ full provider/model ids เป็นคีย์ ใช้ models["provider/model"].agentRuntime สำหรับข้อยกเว้นรันไทม์ต่อเอเจนต์
• runtime: descriptor รันไทม์ต่อเอเจนต์แบบไม่บังคับ ใช้ type: "acp" พร้อมค่าเริ่มต้น runtime.acp (agent, backend, mode, cwd) เมื่อเอเจนต์ควรใช้เซสชัน harness ของ ACP เป็นค่าเริ่มต้น
• identity.avatar: พาธที่สัมพันธ์กับ workspace, URL http(s) หรือ URI data:
• identity จะอนุมานค่าเริ่มต้น: ackReaction จาก emoji, mentionPatterns จาก name/emoji
• subagents.allowAgents: allowlist ของ id เอเจนต์สำหรับเป้าหมาย sessions_spawn.agentId แบบชัดเจน (["*"] = ใดก็ได้; ค่าเริ่มต้น: เอเจนต์เดียวกันเท่านั้น) ใส่ id ของผู้ร้องขอเมื่อควรอนุญาตการเรียก agentId ที่ชี้มายังตัวเอง
• ตัวป้องกันการสืบทอด sandbox: หากเซสชันผู้ร้องขออยู่ใน sandbox, sessions_spawn จะปฏิเสธเป้าหมายที่จะรันแบบไม่มี sandbox
• subagents.requireAgentId: เมื่อเป็น true จะบล็อกการเรียก sessions_spawn ที่ละ agentId (บังคับให้เลือกโปรไฟล์อย่างชัดเจน; ค่าเริ่มต้น: false)

​

การกำหนดเส้นทางหลายเอเจนต์

{
  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" } },
  ],
}

​

ฟิลด์การจับคู่ของ binding

• type (ไม่บังคับ): route สำหรับการกำหนดเส้นทางปกติ (type ที่หายไปจะมีค่าเริ่มต้นเป็น route), acp สำหรับ binding การสนทนา ACP แบบ persistent
• match.channel (จำเป็น)
• match.accountId (ไม่บังคับ; * = บัญชีใดก็ได้; ละไว้ = บัญชีเริ่มต้น)
• match.peer (ไม่บังคับ; { kind: direct|group|channel, id })
• match.guildId / match.teamId (ไม่บังคับ; เฉพาะ channel)
• 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: "*" (ครอบคลุมทั้ง channel)
6. เอเจนต์เริ่มต้น

​

โปรไฟล์การเข้าถึงต่อเอเจนต์

{
  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",
          ],
        },
      },
    ],
  },
}

​

เซสชัน

{
  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,
      },
    },
  },
}

​

คำนำหน้าการตอบกลับ

​

รีแอ็กชันรับทราบ

• ค่าเริ่มต้นเป็น identity.emoji ของเอเจนต์ที่ใช้งานอยู่ มิฉะนั้นเป็น "👀" ตั้งค่า "" เพื่อปิดใช้งาน
• การแทนที่รายช่องทาง: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• ลำดับการแก้ค่า: บัญชี → ช่องทาง → messages.ackReaction → fallback ของอัตลักษณ์
• ขอบเขต: group-mentions (ค่าเริ่มต้น), group-all, direct, all
• removeAckAfterReply: นำการรับทราบออกหลังการตอบกลับบนช่องทางที่รองรับรีแอ็กชัน เช่น Slack, Discord, Telegram, WhatsApp และ iMessage
• messages.statusReactions.enabled: เปิดใช้งานรีแอ็กชันสถานะตามวงจรชีวิตบน Slack, Discord และ Telegram บน Slack และ Discord หากไม่ตั้งค่าไว้ จะคงการเปิดใช้งานรีแอ็กชันสถานะเมื่อรีแอ็กชันรับทราบทำงานอยู่ บน Telegram ให้ตั้งค่าเป็น true อย่างชัดเจนเพื่อเปิดใช้งานรีแอ็กชันสถานะตามวงจรชีวิต

​

ดีบาวซ์ขาเข้า

​

TTS (text-to-speech)

{
  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 ควบคุมโหมด auto-TTS เริ่มต้น: off, always, inbound หรือ tagged /tts on|off สามารถแทนที่ prefs โลคัลได้ และ /tts status แสดงสถานะที่มีผลจริง
• summaryModel แทนที่ agents.defaults.model.primary สำหรับ auto-summary
• modelOverrides เปิดใช้งานเป็นค่าเริ่มต้น; modelOverrides.allowProvider มีค่าเริ่มต้นเป็น false (เลือกเปิดใช้งาน)
• API keys fallback ไปที่ ELEVENLABS_API_KEY/XI_API_KEY และ OPENAI_API_KEY
• ผู้ให้บริการเสียงพูดที่รวมมาเป็นของ Plugin หากตั้งค่า plugins.allow ให้รวม Plugin ผู้ให้บริการ TTS แต่ละรายการที่ต้องการใช้ เช่น microsoft สำหรับ Edge TTS รองรับ ID ผู้ให้บริการแบบเดิม edge เป็น alias ของ microsoft
• providers.openai.baseUrl แทนที่ endpoint TTS ของ OpenAI ลำดับการแก้ค่าคือ config จากนั้น OPENAI_TTS_BASE_URL จากนั้น https://api.openai.com/v1
• เมื่อ providers.openai.baseUrl ชี้ไปยัง endpoint ที่ไม่ใช่ OpenAI, OpenClaw จะถือว่าเป็นเซิร์ฟเวอร์ TTS ที่เข้ากันได้กับ OpenAI และผ่อนปรนการตรวจสอบโมเดล/เสียง

​

พูดคุย

{
  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: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2",
          voice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider ต้องตรงกับคีย์ใน talk.providers เมื่อกำหนดค่าผู้ให้บริการพูดคุยหลายราย
• คีย์พูดคุยแบบแบนเดิม (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) มีไว้เพื่อความเข้ากันได้เท่านั้น เรียกใช้ openclaw doctor --fix เพื่อเขียน config ที่บันทึกไว้ใหม่เป็น talk.providers.<provider>
• Voice IDs fallback ไปที่ ELEVENLABS_VOICE_ID หรือ SAG_VOICE_ID
• providers.*.apiKey รองรับสตริง plaintext หรืออ็อบเจ็กต์ SecretRef
• fallback ของ ELEVENLABS_API_KEY ใช้เฉพาะเมื่อไม่ได้กำหนดค่า Talk API key
• providers.*.voiceAliases ช่วยให้คำสั่งพูดคุยใช้ชื่อที่เป็นมิตรได้
• providers.mlx.modelId เลือก repo Hugging Face ที่ตัวช่วย MLX โลคัลของ macOS ใช้ หากละไว้ macOS จะใช้ mlx-community/Soprano-80M-bf16
• การเล่นเสียง MLX บน macOS ทำงานผ่านตัวช่วย openclaw-mlx-tts ที่รวมมาเมื่อมีอยู่ หรือ executable บน PATH; OPENCLAW_MLX_TTS_BIN แทนที่เส้นทางตัวช่วยสำหรับการพัฒนา
• consultThinkingLevel ควบคุมระดับการคิดสำหรับการรันเอเจนต์ OpenClaw แบบเต็มที่อยู่เบื้องหลังการเรียก Control UI Talk realtime openclaw_agent_consult เว้นว่างไว้เพื่อคงพฤติกรรมเซสชัน/โมเดลปกติ
• consultFastMode ตั้งค่าการแทนที่ fast-mode แบบ one-shot สำหรับ consults ของ Control UI Talk realtime โดยไม่เปลี่ยนการตั้งค่า fast-mode ปกติของเซสชัน
• speechLocale ตั้งค่า ID โลเคล BCP 47 ที่ใช้โดยการรู้จำเสียงพูดของ iOS/macOS Talk เว้นว่างไว้เพื่อใช้ค่าเริ่มต้นของอุปกรณ์
• silenceTimeoutMs ควบคุมระยะเวลาที่โหมดพูดคุยรอหลังผู้ใช้เงียบก่อนส่ง transcript หากไม่ตั้งค่าไว้จะคงหน้าต่างหยุดชั่วคราวเริ่มต้นของแพลตฟอร์ม (700 ms บน macOS และ Android, 900 ms บน iOS)
• realtime.instructions ผนวกคำสั่งระบบที่หันไปหาผู้ให้บริการเข้ากับพรอมป์ realtime ในตัวของ OpenClaw เพื่อให้กำหนดค่าสไตล์เสียงได้โดยไม่สูญเสียแนวทาง openclaw_agent_consult เริ่มต้น

​

ที่เกี่ยวข้อง

• เอกสารอ้างอิงการกำหนดค่า — คีย์ config อื่นทั้งหมด
• การกำหนดค่า — งานทั่วไปและการตั้งค่าอย่างรวดเร็ว
• ตัวอย่างการกำหนดค่า