Cấu hình — tác nhân

​

Mặc định của tác tử

​

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

• Bỏ qua agents.defaults.skills để mặc định không giới hạn skills.
• Bỏ qua agents.list[].skills để kế thừa các mặc định.
• Đặt agents.list[].skills: [] để không có skills.
• Danh sách agents.list[].skills không rỗng là tập cuối cùng cho tác tử đó; nó không hợp nhất với các mặc định.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip": các lượt tiếp tục an toàn (sau một phản hồi assistant đã hoàn tất) bỏ qua việc chèn lại bootstrap workspace, giảm kích thước prompt. Các lần chạy Heartbeat và thử lại sau Compaction vẫn dựng lại ngữ cảnh.
• "never": tắt bootstrap workspace và chèn tệp ngữ cảnh trên mọi lượt. Chỉ dùng tùy chọn này cho các tác tử hoàn toàn sở hữu vòng đời prompt của chúng (công cụ ngữ cảnh tùy chỉnh, runtime gốc tự xây dựng ngữ cảnh riêng, hoặc quy trình chuyên biệt không dùng bootstrap). Các lượt Heartbeat và khôi phục sau Compaction cũng bỏ qua việc chèn.

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

​

agents.defaults.bootstrapMaxChars

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

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

​

Ghi đè hồ sơ bootstrap theo tác tử

{
  agents: {
    defaults: {
      contextInjection: "continuation-skip",
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 60000,
    },
    list: [
      {
        id: "strict-worker",
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    ],
  },
}

​

agents.defaults.bootstrapPromptTruncationWarning

• "off": không bao giờ chèn văn bản thông báo cắt ngắn vào system prompt.
• "once": chèn một thông báo ngắn gọn một lần cho mỗi chữ ký cắt ngắn duy nhất.
• "always": chèn một thông báo ngắn gọn trong mọi lần chạy khi có cắt ngắn (khuyến nghị).

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

​

Bản đồ quyền sở hữu ngân sách ngữ cảnh

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: chèn bootstrap workspace thông thường.
• agents.defaults.startupContext.*: phần mở đầu một lần cho lượt chạy mô hình khi reset/khởi động, bao gồm các tệp memory/*.md hằng ngày gần đây. Các lệnh chat trần /new và /reset được xác nhận mà không gọi mô hình.
• skills.limits.*: danh sách skills gọn được chèn vào system prompt.
• agents.defaults.contextLimits.*: các đoạn trích runtime có giới hạn và các khối do runtime sở hữu được chèn vào.
• memory.qmd.limits.*: đoạn trích tìm kiếm bộ nhớ đã lập chỉ mục và kích thước chèn.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextInjection
• agents.list[].bootstrapMaxChars
• agents.list[].bootstrapTotalMaxChars
• 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,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: giới hạn đoạn trích memory_get mặc định trước khi siêu dữ liệu cắt ngắn và thông báo tiếp tục được thêm vào.
• memoryGetDefaultLines: cửa sổ dòng memory_get mặc định khi lines bị bỏ qua.
• toolResultMaxChars: trần kết quả công cụ trực tiếp nâng cao dùng cho kết quả được lưu bền vững và khôi phục tràn. Để không đặt cho giới hạn tự động theo ngữ cảnh mô hình: 16000 ký tự dưới 100K token, 32000 ký tự ở 100K+ token, và 64000 ký tự ở 200K+ token. Giá trị tường minh đến 1000000 được chấp nhận cho các mô hình ngữ cảnh dài, nhưng giới hạn hiệu dụng vẫn bị giới hạn ở khoảng 30% của cửa sổ ngữ cảnh mô hình. openclaw doctor --deep in giới hạn hiệu dụng, và doctor chỉ cảnh báo khi một ghi đè tường minh đã cũ hoặc không có hiệu lực.
• postCompactionMaxChars: giới hạn đoạn trích AGENTS.md dùng trong quá trình chèn làm mới sau Compaction.

​

agents.list[].contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000, // advanced ceiling for this agent
        },
      },
    ],
  },
}

​

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.imageQuality

• auto: thích nghi với giới hạn mô hình và số lượng hình ảnh.
• efficient: ưu tiên hình ảnh nhỏ hơn để giảm mức dùng token và byte.
• balanced: dùng thang trung gian tiêu chuẩn.
• high: giữ lại nhiều chi tiết hơn cho ảnh chụp màn hình, sơ đồ, và hình ảnh tài liệu.

{
  agents: { defaults: { imageQuality: "auto" } },
}

​

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: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Dạng chuỗi chỉ đặt mô hình chính.
  • Dạng đối tượng đặt mô hình chính kèm các mô hình chuyển đổi dự phòng có thứ tự.
• imageModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được đường dẫn công cụ image dùng làm cấu hình mô hình thị giác.
  • Cũng được dùng làm định tuyến dự phòng khi mô hình đã chọn/mặc định không thể chấp nhận đầu vào hình ảnh.
  • Ưu tiên các tham chiếu provider/model rõ ràng. ID trần được chấp nhận để tương thích; nếu một ID trần khớp duy nhất với một mục có khả năng xử lý hình ảnh đã cấu hình trong models.providers.*.models, OpenClaw sẽ xác định nó thuộc provider đó. Các kết quả khớp đã cấu hình nhưng không rõ ràng cần tiền tố provider rõ ràng.
• imageGenerationModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được năng lực tạo hình ảnh dùng chung và mọi bề mặt công cụ/plugin trong tương lai tạo hình ảnh sử dụng.
  • Giá trị thường dùng: google/gemini-3.1-flash-image-preview cho tạo hình ảnh Gemini gốc, fal/fal-ai/flux/dev cho fal, openai/gpt-image-2 cho OpenAI Images, hoặc openai/gpt-image-1.5 cho đầu ra OpenAI PNG/WebP nền trong suốt.
  • Nếu bạn chọn trực tiếp một provider/model, hãy cấu hình cả xác thực provider tương ứng (ví dụ GEMINI_API_KEY hoặc GOOGLE_API_KEY cho google/*, OPENAI_API_KEY hoặc OpenAI Codex OAuth cho openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY cho fal/*).
  • Nếu bỏ qua, image_generate vẫn có thể suy ra provider mặc định được hỗ trợ bởi xác thực. Nó thử provider mặc định hiện tại trước, rồi đến các provider tạo hình ảnh đã đăng ký còn lại theo thứ tự ID provider.
• musicGenerationModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được năng lực tạo nhạc dùng chung và công cụ tích hợp sẵn music_generate sử dụng.
  • Giá trị thường dùng: google/lyria-3-clip-preview, google/lyria-3-pro-preview, hoặc minimax/music-2.6.
  • Nếu bỏ qua, music_generate vẫn có thể suy ra provider mặc định được hỗ trợ bởi xác thực. Nó thử provider mặc định hiện tại trước, rồi đến các provider tạo nhạc đã đăng ký còn lại theo thứ tự ID provider.
  • Nếu bạn chọn trực tiếp một provider/model, hãy cấu hình cả xác thực/khóa API provider tương ứng.
• videoGenerationModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được năng lực tạo video dùng chung và công cụ tích hợp sẵn video_generate sử dụng.
  • Giá trị thường dùng: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash, hoặc qwen/wan2.7-r2v.
  • Nếu bỏ qua, video_generate vẫn có thể suy ra provider mặc định được hỗ trợ bởi xác thực. Nó thử provider mặc định hiện tại trước, rồi đến các provider tạo video đã đăng ký còn lại theo thứ tự ID provider.
  • Nếu bạn chọn trực tiếp một provider/model, hãy cấu hình cả xác thực/khóa API provider tương ứng.
  • Plugin tạo video Qwen chính thức hỗ trợ tối đa 1 video đầu ra, 1 hình ảnh đầu vào, 4 video đầu vào, thời lượng 10 giây, và các tùy chọn cấp provider size, aspectRatio, resolution, audio, và watermark.
• pdfModel: chấp nhận chuỗi ("provider/model") hoặc đối tượng ({ primary, fallbacks }).
  • Được công cụ pdf dùng để định tuyến mô hình.
  • Nếu bỏ qua, công cụ PDF sẽ quay về imageModel, rồi đến mô hình phiên/mặc định đã phân giải.
• pdfMaxBytesMb: giới hạn kích thước PDF mặc định cho công cụ pdf khi maxBytesMb không được truyền tại thời điểm gọi.
• pdfMaxPages: số trang tối đa mặc định được xem xét bởi chế độ dự phòng trích xuất trong công cụ pdf.
• verboseDefault: mức chi tiết mặc định cho agent. Giá trị: "off", "on", "full". Mặc định: "off".
• toolProgressDetail: chế độ chi tiết cho tóm tắt công cụ /verbose và các dòng công cụ trong bản nháp tiến độ. Giá trị: "explain" (mặc định, nhãn ngắn gọn cho con người) hoặc "raw" (thêm lệnh/chi tiết thô khi có). agents.list[].toolProgressDetail theo từng agent ghi đè mặc định này.
• reasoningDefault: khả năng hiển thị suy luận mặc định cho agent. Giá trị: "off", "on", "stream". agents.list[].reasoningDefault theo từng agent ghi đè mặc định này. Các mặc định suy luận đã cấu hình chỉ được áp dụng cho chủ sở hữu, người gửi được ủy quyền, hoặc ngữ cảnh Gateway quản trị vận hành khi không đặt ghi đè suy luận theo từng tin nhắn hoặc phiên.
• elevatedDefault: mức đầu ra nâng cao mặc định cho agent. Giá trị: "off", "on", "ask", "full". Mặc định: "on".
• model.primary: định dạng provider/model (ví dụ openai/gpt-5.5 cho truy cập bằng khóa API OpenAI hoặc Codex OAuth). Nếu bạn bỏ qua provider, OpenClaw trước tiên thử một bí danh, rồi đến kết quả khớp provider đã cấu hình duy nhất cho đúng ID mô hình đó, và chỉ sau đó mới quay về provider mặc định đã cấu hình (hành vi tương thích đã lỗi thời, vì vậy nên ưu tiên provider/model rõ ràng). Nếu provider đó không còn cung cấp mô hình mặc định đã cấu hình, OpenClaw sẽ quay về provider/model đầu tiên đã cấu hình thay vì hiển thị một mặc định provider đã bị xóa và lỗi thời.
• models: catalog mô hình đã cấu hình và danh sách cho phép cho /model. Mỗi mục có thể bao gồm alias (lối tắt) và params (theo provider cụ thể, ví dụ temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, định tuyến provider của OpenRouter, chat_template_kwargs, extra_body/extraBody).
  • Dùng các mục provider/* như "openai/*": {} hoặc "vllm/*": {} để hiển thị tất cả mô hình đã phát hiện cho các provider đã chọn mà không cần liệt kê thủ công từng ID mô hình.
  • Thêm agentRuntime vào mục provider/* khi mọi mô hình được phát hiện động cho provider đó nên dùng cùng thời gian chạy. Chính sách thời gian chạy provider/model chính xác vẫn thắng wildcard.
  • Chỉnh sửa an toàn: dùng openclaw config set agents.defaults.models '<json>' --strict-json --merge để thêm mục. config set từ chối các thay thế sẽ xóa mục hiện có trong danh sách cho phép trừ khi bạn truyền --replace.
  • Các luồng cấu hình/onboarding theo phạm vi provider hợp nhất các mô hình provider đã chọn vào map này và giữ nguyên các provider không liên quan đã được cấu hình.
  • Với các mô hình OpenAI Responses trực tiếp, Compaction phía máy chủ được bật tự động. Dùng params.responsesServerCompaction: false để dừng chèn context_management, hoặc params.responsesCompactThreshold để ghi đè ngưỡng. Xem Compaction phía máy chủ OpenAI.
• params: tham số provider mặc định toàn cục áp dụng cho mọi mô hình. Đặt tại agents.defaults.params (ví dụ { cacheRetention: "long" }).
• Thứ tự ưu tiên hợp nhất params (cấu hình): agents.defaults.params (nền tảng toàn cục) bị ghi đè bởi agents.defaults.models["provider/model"].params (theo mô hình), rồi agents.list[].params (khớp ID agent) ghi đè theo khóa. Xem Lưu bộ nhớ đệm prompt để biết chi tiết.
• models.providers.openrouter.params.provider: chính sách định tuyến provider mặc định trên toàn OpenRouter. OpenClaw chuyển tiếp giá trị này đến đối tượng provider trong yêu cầu của OpenRouter; agents.defaults.models["openrouter/<model>"].params.provider theo từng mô hình và tham số agent ghi đè theo khóa. Xem Định tuyến provider OpenRouter.
• params.extra_body/params.extraBody: JSON truyền xuyên nâng cao được hợp nhất vào thân yêu cầu api: "openai-completions" cho các proxy tương thích với OpenAI. Nếu nó xung đột với các khóa yêu cầu được tạo, phần thân bổ sung sẽ thắng; các tuyến completions không gốc vẫn loại bỏ store chỉ dành cho OpenAI sau đó.
• params.chat_template_kwargs: đối số mẫu chat tương thích vLLM/OpenAI được hợp nhất vào thân yêu cầu api: "openai-completions" cấp cao nhất. Với vllm/nemotron-3-* khi tắt thinking, Plugin vLLM đi kèm tự động gửi enable_thinking: false và force_nonempty_content: true; chat_template_kwargs rõ ràng ghi đè mặc định được tạo, và extra_body.chat_template_kwargs vẫn có quyền ưu tiên cuối cùng. Các mô hình thinking Qwen và Nemotron vLLM đã cấu hình hiển thị lựa chọn /think nhị phân (off, on) thay vì thang nỗ lực nhiều mức.
• compat.thinkingFormat: kiểu payload thinking tương thích với OpenAI. Dùng "together" cho reasoning.enabled kiểu Together, "qwen" cho enable_thinking cấp cao nhất kiểu Qwen, hoặc "qwen-chat-template" cho chat_template_kwargs.enable_thinking trên các backend họ Qwen hỗ trợ kwargs mẫu chat cấp yêu cầu, chẳng hạn như vLLM. OpenClaw ánh xạ thinking bị tắt thành false và thinking được bật thành true, còn các mô hình Qwen vLLM đã cấu hình hiển thị lựa chọn /think nhị phân cho các định dạng này.
• compat.supportedReasoningEfforts: danh sách mức nỗ lực suy luận tương thích với OpenAI theo từng mô hình. Bao gồm "xhigh" cho các endpoint tùy chỉnh thực sự chấp nhận nó; khi đó OpenClaw hiển thị /think xhigh trong menu lệnh, hàng phiên Gateway, xác thực bản vá phiên, xác thực CLI agent, và xác thực llm-task cho provider/model đã cấu hình đó. Dùng compat.reasoningEffortMap khi backend muốn một giá trị theo provider cụ thể cho một mức chuẩn.
• params.preserveThinking: tùy chọn chỉ dành cho Z.AI để giữ nguyên thinking. Khi được bật và thinking đang bật, OpenClaw gửi thinking.clear_thinking: false và phát lại reasoning_content trước đó; xem thinking và thinking được giữ nguyên của Z.AI.
• localService: trình quản lý tiến trình cấp provider tùy chọn cho máy chủ mô hình cục bộ/tự lưu trữ. Khi mô hình đã chọn thuộc provider đó, OpenClaw thăm dò healthUrl (hoặc baseUrl + "/models"), khởi động command với args nếu endpoint ngừng hoạt động, chờ tối đa readyTimeoutMs, rồi gửi yêu cầu mô hình. command phải là đường dẫn tuyệt đối. idleStopMs: 0 giữ tiến trình sống cho đến khi OpenClaw thoát; giá trị dương dừng tiến trình do OpenClaw khởi tạo sau số mili giây nhàn rỗi đó. Xem Dịch vụ mô hình cục bộ.
• Chính sách thời gian chạy thuộc về provider hoặc mô hình, không thuộc agents.defaults. Dùng models.providers.<provider>.agentRuntime cho quy tắc trên toàn provider hoặc agents.defaults.models["provider/model"].agentRuntime / agents.list[].models["provider/model"].agentRuntime cho quy tắc theo mô hình. Các mô hình agent OpenAI trên provider OpenAI chính thức chọn Codex theo mặc định.
• Các trình ghi cấu hình thay đổi các trường này (ví dụ /models set, /models set-image, và các lệnh thêm/xóa dự phòng) lưu dạng đối tượng chuẩn và giữ nguyên danh sách dự phòng hiện có khi có thể.
• maxConcurrent: số lần chạy agent song song tối đa giữa các phiên (mỗi phiên vẫn được tuần tự hóa). Mặc định: 4.

​

Chính sách thời gian chạy

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

• id: "auto", "openclaw", id harness plugin đã đăng ký, hoặc bí danh backend CLI được hỗ trợ. Plugin Codex đi kèm đăng ký codex; Plugin Anthropic đi kèm cung cấp backend CLI claude-cli.
• id: "auto" cho phép các harness plugin đã đăng ký nhận các lượt được hỗ trợ và dùng OpenClaw khi không có harness nào khớp. Runtime plugin tường minh như id: "codex" yêu cầu harness đó và thất bại đóng nếu harness không khả dụng hoặc thất bại.
• id: "pi" chỉ được chấp nhận như một bí danh không còn khuyến nghị cho openclaw để giữ nguyên các cấu hình đã phát hành từ v2026.5.22 trở về trước. Cấu hình mới nên dùng openclaw.
• Thứ tự ưu tiên runtime là chính sách mô hình chính xác trước (agents.list[].models["provider/model"], agents.defaults.models["provider/model"], hoặc models.providers.<provider>.models[]), sau đó là agents.list[] / agents.defaults.models["provider/*"], rồi chính sách toàn provider tại models.providers.<provider>.agentRuntime.
• Các khóa runtime toàn agent là di sản. agents.defaults.agentRuntime, agents.list[].agentRuntime, ghim runtime phiên, và OPENCLAW_AGENT_RUNTIME bị bỏ qua khi chọn runtime. Chạy openclaw doctor --fix để xóa các giá trị cũ.
• Các mô hình agent OpenAI mặc định dùng harness Codex; provider/model agentRuntime.id: "codex" vẫn hợp lệ khi bạn muốn nêu rõ điều đó.
• Với các bản triển khai Claude CLI, ưu tiên model: "anthropic/claude-opus-4-8" cùng agentRuntime.id: "claude-cli" theo phạm vi mô hình. Các ref mô hình di sản claude-cli/claude-opus-4-7 vẫn hoạt động để tương thích, nhưng cấu hình mới nên giữ lựa chọn provider/model theo dạng chuẩn và đặt backend thực thi trong chính sách runtime provider/model.
• Điều này chỉ kiểm soát việc thực thi lượt agent dạng văn bản. Tạo phương tiện, thị giác, PDF, nhạc, video và TTS vẫn dùng cài đặt provider/model của chúng.

​

agents.defaults.cliBackends

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "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",
        },
      },
    },
  },
}

• Backend CLI ưu tiên văn bản; công cụ luôn bị tắt.
• Phiên được hỗ trợ khi sessionArg được đặt.
• Truyền ảnh xuyên qua được hỗ trợ khi imageArg chấp nhận đường dẫn tệp.
• reseedFromRawTranscriptWhenUncompacted: true cho phép một backend khôi phục an toàn các phiên đã bị vô hiệu hóa từ phần đuôi transcript OpenClaw thô có giới hạn trước khi có bản tóm tắt Compaction đầu tiên. Thay đổi hồ sơ xác thực hoặc credential-epoch vẫn không bao giờ reseed thô.

​

agents.defaults.promptOverlays

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

• "friendly" (mặc định) và "on" bật lớp phong cách tương tác thân thiện.
• "off" chỉ tắt lớp thân thiện; hợp đồng hành vi GPT-5 có gắn thẻ vẫn được bật.
• plugins.entries.openai.config.personality di sản vẫn được đọc khi cài đặt dùng chung này chưa được đặt.

​

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: chuỗi thời lượng (ms/s/m/h). Mặc định: 30m (xác thực bằng khóa API) hoặc 1h (xác thực OAuth). Đặt thành 0m để tắt.
• includeSystemPromptSection: khi là false, bỏ qua phần Heartbeat khỏi system prompt và bỏ qua việc chèn HEARTBEAT.md vào ngữ cảnh bootstrap. Mặc định: true.
• suppressToolErrorWarnings: khi là true, ẩn các payload cảnh báo lỗi công cụ trong các lượt chạy heartbeat.
• timeoutSeconds: thời gian tối đa tính bằng giây cho phép một lượt agent heartbeat chạy trước khi bị hủy. Để trống để dùng agents.defaults.timeoutSeconds khi được đặt, nếu không thì dùng nhịp heartbeat giới hạn ở 600 giây.
• directPolicy: chính sách gửi trực tiếp/DM. allow (mặc định) cho phép gửi tới mục tiêu trực tiếp. block chặn gửi tới mục tiêu trực tiếp và phát ra reason=dm-blocked.
• lightContext: khi là true, các lượt chạy heartbeat dùng ngữ cảnh bootstrap nhẹ và chỉ giữ HEARTBEAT.md từ các tệp bootstrap workspace.
• isolatedSession: khi là true, mỗi heartbeat chạy trong một phiên mới không có lịch sử hội thoại trước đó. Cùng mẫu cô lập như cron sessionTarget: "isolated". Giảm chi phí token mỗi heartbeat từ khoảng 100K xuống khoảng 2-5K token.
• skipWhenBusy: khi là true, các lượt chạy heartbeat sẽ hoãn trên các luồng bận bổ sung của agent đó: subagent theo khóa phiên hoặc công việc lệnh lồng nhau của chính nó. Các luồng Cron luôn hoãn heartbeat, ngay cả khi không có cờ này.
• Theo từng agent: đặt agents.list[].heartbeat. Khi bất kỳ agent nào định nghĩa heartbeat, chỉ các agent đó chạy heartbeat.
• Heartbeat chạy các lượt agent đầy đủ — khoảng thời gian ngắn hơn tiêu tốn nhiều token hơn.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 180,
        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 tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // opt in to AGENTS.md section 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 hoặc safeguard (tóm tắt theo đoạn cho lịch sử dài). Xem Compaction.
• provider: id của Plugin nhà cung cấp Compaction đã đăng ký. Khi được đặt, summarize() của nhà cung cấp sẽ được gọi thay vì cơ chế tóm tắt LLM tích hợp sẵn. Sẽ quay về cơ chế tích hợp sẵn khi thất bại. Việc đặt nhà cung cấp sẽ buộc mode: "safeguard". Xem Compaction.
• timeoutSeconds: số giây tối đa cho phép đối với một thao tác Compaction đơn lẻ trước khi OpenClaw hủy thao tác đó. Mặc định: 180.
• keepRecentTokens: ngân sách điểm cắt của agent để giữ nguyên văn phần đuôi bản ghi gần nhất. /compact thủ công tuân theo giá trị này khi được đặt rõ ràng; nếu không, Compaction thủ công là một checkpoint cứng.
• identifierPolicy: strict (mặc định), off, hoặc custom. strict thêm trước hướng dẫn giữ lại định danh mờ tích hợp sẵn trong quá trình tóm tắt Compaction.
• identifierInstructions: văn bản tùy chỉnh tùy chọn để bảo toàn định danh, dùng khi identifierPolicy=custom.
• qualityGuard: các kiểm tra thử lại khi đầu ra sai định dạng cho bản tóm tắt safeguard. Được bật theo mặc định trong chế độ safeguard; đặt enabled: false để bỏ qua kiểm tra.
• midTurnPrecheck: kiểm tra áp lực vòng lặp công cụ tùy chọn. Khi enabled: true, OpenClaw kiểm tra áp lực ngữ cảnh sau khi kết quả công cụ được nối thêm và trước lần gọi mô hình tiếp theo. Nếu ngữ cảnh không còn vừa, nó hủy lần thử hiện tại trước khi gửi prompt và dùng lại đường khôi phục precheck hiện có để cắt ngắn kết quả công cụ hoặc Compaction rồi thử lại. Hoạt động với cả hai chế độ Compaction default và safeguard. Mặc định: tắt.
• postCompactionSections: tên phần H2/H3 trong AGENTS.md tùy chọn để chèn lại sau Compaction. Việc chèn lại bị tắt khi không đặt hoặc đặt thành []. Đặt rõ ràng ["Session Startup", "Red Lines"] sẽ bật cặp đó và giữ fallback kế thừa Every Session/Safety. Chỉ bật tùy chọn này khi ngữ cảnh bổ sung đáng với rủi ro trùng lặp hướng dẫn dự án đã được ghi lại trong bản tóm tắt Compaction.
• model: provider/model-id tùy chọn hoặc alias trần từ agents.defaults.models chỉ dành cho tóm tắt Compaction. Alias trần được phân giải trước khi dispatch; các ID mô hình literal đã cấu hình vẫn được ưu tiên khi có xung đột. Dùng tùy chọn này khi phiên chính cần giữ một mô hình nhưng bản tóm tắt Compaction cần chạy trên mô hình khác; khi không đặt, Compaction dùng mô hình chính của phiên.
• maxActiveTranscriptBytes: ngưỡng byte tùy chọn (number hoặc chuỗi như "20mb") kích hoạt Compaction cục bộ thông thường trước một lượt chạy khi JSONL đang hoạt động vượt ngưỡng. Yêu cầu truncateAfterCompaction để Compaction thành công có thể xoay vòng sang bản ghi kế nhiệm nhỏ hơn. Tắt khi không đặt hoặc là 0.
• notifyUser: khi true, gửi thông báo ngắn cho người dùng khi Compaction bắt đầu và khi hoàn tất (ví dụ: “Compacting context…” và “Compaction complete”). Tắt theo mặc định để giữ Compaction im lặng.
• memoryFlush: lượt agentic im lặng trước auto-compaction để lưu ký ức bền vững. Đặt model thành một nhà cung cấp/mô hình chính xác như ollama/qwen3:8b khi lượt dọn dẹp này cần ở trên mô hình cục bộ; override này không kế thừa chuỗi fallback của phiên đang hoạt động. Bị bỏ qua khi workspace ở chế độ chỉ đọc.

​

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: số lần lặp thử lại chạy cơ sở cho vòng chạy ngoài. Mặc định: 24.
• perProfile: số lần lặp thử lại chạy bổ sung được cấp cho mỗi ứng viên hồ sơ fallback. Mặc định: 8.
• min: giới hạn tuyệt đối tối thiểu cho số lần lặp thử lại chạy. Mặc định: 32.
• max: giới hạn tuyệt đối tối đa cho số lần lặp thử lại chạy để ngăn thực thi mất kiểm soát. Mặc định: 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"] },
      },
    },
  },
}

​

Phát trực tuyến theo khối

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

• Các kênh không phải Telegram cần *.blockStreaming: true rõ ràng để bật phản hồi theo khối.
• Override theo kênh: channels.<channel>.blockStreamingCoalesce (và các biến thể theo từng tài khoản). Signal/Slack/Discord/Google Chat mặc định minChars: 1500.
• humanDelay: khoảng tạm dừng ngẫu nhiên giữa các phản hồi theo khối. natural = 800–2500ms. Override theo từng agent: agents.list[].humanDelay.

​

Chỉ báo đang nhập

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

• Mặc định: instant cho cuộc trò chuyện trực tiếp/lượt nhắc đến, message cho cuộc trò chuyện nhóm không nhắc đến.
• Override theo phiên: 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 (ghi đè theo từng tác tử)

{
  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: { speakerVoiceId: "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 tác tử ổn định (bắt buộc).
• default: khi đặt nhiều mục, mục đầu tiên thắng (ghi log cảnh báo). Nếu không đặt mục nào, mục đầu tiên trong danh sách là mặc định.
• model: dạng chuỗi đặt một primary nghiêm ngặt theo từng tác tử mà không có fallback model; dạng đối tượng { primary } cũng nghiêm ngặt trừ khi bạn thêm fallbacks. Dùng { primary, fallbacks: [...] } để bật fallback cho tác tử đó, hoặc { primary, fallbacks: [] } để làm rõ hành vi nghiêm ngặt. Các Cron job chỉ ghi đè primary vẫn kế thừa fallback mặc định trừ khi bạn đặt fallbacks: [].
• params: tham số stream theo từng tác tử được hợp nhất lên trên mục model đã chọn trong agents.defaults.models. Dùng mục này cho các ghi đè riêng theo tác tử như cacheRetention, temperature, hoặc maxTokens mà không cần nhân bản toàn bộ catalog model.
• tts: ghi đè text-to-speech tùy chọn theo từng tác tử. Khối này deep-merge lên trên messages.tts, vì vậy hãy giữ thông tin xác thực provider dùng chung và chính sách fallback trong messages.tts, và chỉ đặt các giá trị theo persona như provider, giọng nói, model, style, hoặc chế độ tự động ở đây.
• skills: allowlist skill tùy chọn theo từng tác tử. Nếu bỏ qua, tác tử kế thừa agents.defaults.skills khi được đặt; một danh sách rõ ràng sẽ thay thế mặc định thay vì hợp nhất, và [] nghĩa là không có skill nào.
• thinkingDefault: mức thinking mặc định tùy chọn theo từng tác tử (off | minimal | low | medium | high | xhigh | adaptive | max). Ghi đè agents.defaults.thinkingDefault cho tác tử này khi không có ghi đè theo từng tin nhắn hoặc phiên. Profile provider/model đã chọn kiểm soát giá trị nào hợp lệ; với Google Gemini, adaptive giữ thinking động do provider sở hữu (thinkingLevel bị bỏ qua trên Gemini 3/3.1, thinkingBudget: -1 trên Gemini 2.5).
• reasoningDefault: khả năng hiển thị reasoning mặc định tùy chọn theo từng tác tử (on | off | stream). Ghi đè agents.defaults.reasoningDefault cho tác tử này khi không có ghi đè reasoning theo từng tin nhắn hoặc phiên.
• fastModeDefault: mặc định tùy chọn theo từng tác tử cho fast mode ("auto" | true | false). Áp dụng khi không có ghi đè fast-mode theo từng tin nhắn hoặc phiên.
• models: catalog model/ghi đè runtime tùy chọn theo từng tác tử, được khóa theo id provider/model đầy đủ. Dùng models["provider/model"].agentRuntime cho các ngoại lệ runtime theo từng tác tử.
• runtime: mô tả runtime tùy chọn theo từng tác tử. Dùng type: "acp" với mặc định runtime.acp (agent, backend, mode, cwd) khi tác tử nên mặc định dùng các phiên harness ACP.
• identity.avatar: đường dẫn tương đối với không gian làm việc, URL http(s), hoặc URI data:.
• Các tệp ảnh identity.avatar cục bộ tương đối với không gian làm việc bị giới hạn 2 MB. URL http(s) và URI data: không được kiểm tra bằng giới hạn kích thước tệp cục bộ.
• identity suy ra mặc định: ackReaction từ emoji, mentionPatterns từ name/emoji.
• subagents.allowAgents: allowlist các id tác tử đã cấu hình cho target sessions_spawn.agentId rõ ràng (["*"] = bất kỳ target đã cấu hình nào; mặc định: chỉ cùng tác tử). Bao gồm id của bên yêu cầu khi các lệnh gọi agentId tự nhắm mục tiêu nên được phép. Các mục cũ có cấu hình tác tử đã bị xóa sẽ bị sessions_spawn từ chối và bị bỏ khỏi agents_list; chạy openclaw doctor --fix để dọn dẹp, hoặc thêm một mục agents.list[] tối thiểu nếu target đó vẫn nên có thể spawn trong khi kế thừa mặc định.
• Bộ bảo vệ kế thừa sandbox: nếu phiên của bên yêu cầu đang ở trong sandbox, sessions_spawn từ chối các target sẽ chạy không có sandbox.
• subagents.requireAgentId: khi true, chặn các lệnh gọi sessions_spawn bỏ qua agentId (buộc chọn profile rõ ràng; mặc định: false).

​

Định tuyến đa tác tử

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

​

Trường khớp binding

• type (tùy chọn): route cho định tuyến thông thường (thiếu type thì mặc định là route), acp cho binding hội thoại ACP liên tục.
• match.channel (bắt buộc)
• match.accountId (tùy chọn; * = bất kỳ tài khoản nào; bỏ qua = tài khoản mặc định)
• match.peer (tùy chọn; { kind: direct|group|channel, id })
• match.guildId / match.teamId (tùy chọn; tùy theo kênh)
• acp (tùy chọn; chỉ cho type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (chính xác, không có peer/guild/team)
5. match.accountId: "*" (toàn kênh)
6. Tác tử mặc định

​

Profile truy cập theo từng tác tử

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

​

Phiên

{
  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: "enforce", // enforce (default) | warn
      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",
    },
  },
}

​

Tin nhắn

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

​

Tiền tố phản hồi

​

Phản ứng xác nhận

• Mặc định là identity.emoji của tác nhân đang hoạt động, nếu không thì là "👀". Đặt "" để tắt.
• Ghi đè theo kênh: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Thứ tự phân giải: tài khoản → kênh → messages.ackReaction → dự phòng danh tính.
• Phạm vi: group-mentions (mặc định), group-all, direct, all.
• removeAckAfterReply: xóa xác nhận sau khi trả lời trên các kênh hỗ trợ phản ứng như Slack, Discord, Signal, Telegram, WhatsApp và iMessage.
• messages.statusReactions.enabled: bật phản ứng trạng thái vòng đời trên Slack, Discord, Signal, Telegram và WhatsApp. Trên Slack và Discord, nếu không đặt thì phản ứng trạng thái vẫn bật khi phản ứng xác nhận đang hoạt động. Trên Signal, Telegram và WhatsApp, hãy đặt tường minh thành true để bật phản ứng trạng thái vòng đời.
• messages.statusReactions.emojis: ghi đè các khóa emoji vòng đời: queued, thinking, compacting, tool, coding, web, deploy, build, concierge, done, error, stallSoft, và stallHard. Telegram chỉ cho phép một tập phản ứng cố định, nên emoji được cấu hình nhưng không được hỗ trợ sẽ dự phòng về biến thể trạng thái được hỗ trợ gần nhất cho cuộc trò chuyện đó.

​

Debounce đầu vào

​

TTS (chuyển văn bản thành giọng nói)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-5.4-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      providers: {
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          speakerVoiceId: "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: {
          speakerVoice: "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",
          speakerVoice: "alloy",
        },
      },
    },
  },
}

• auto kiểm soát chế độ auto-TTS mặc định: off, always, inbound, hoặc tagged. /tts on|off có thể ghi đè tùy chọn cục bộ, và /tts status hiển thị trạng thái có hiệu lực.
• summaryModel ghi đè agents.defaults.model.primary cho tự động tóm tắt.
• modelOverrides được bật theo mặc định; modelOverrides.allowProvider mặc định là false (chọn tham gia).
• API key dự phòng về ELEVENLABS_API_KEY/XI_API_KEY và OPENAI_API_KEY.
• Các nhà cung cấp giọng nói đi kèm thuộc sở hữu Plugin. Nếu plugins.allow được đặt, hãy bao gồm từng Plugin nhà cung cấp TTS mà bạn muốn dùng, ví dụ microsoft cho Edge TTS. Id nhà cung cấp cũ edge được chấp nhận làm bí danh cho microsoft.
• providers.openai.baseUrl ghi đè endpoint OpenAI TTS. Thứ tự phân giải là cấu hình, rồi OPENAI_TTS_BASE_URL, rồi https://api.openai.com/v1.
• Khi providers.openai.baseUrl trỏ đến một endpoint không phải OpenAI, OpenClaw coi đó là máy chủ TTS tương thích OpenAI và nới lỏng việc xác thực model/voice.

​

Nói chuyện

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "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",
          speakerVoice: "cedar",
        },
      },
      instructions: "Speak warmly and keep answers brief.",
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider phải khớp với một khóa trong talk.providers khi nhiều nhà cung cấp Nói chuyện được cấu hình.
• Các khóa Nói chuyện phẳng cũ (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) chỉ dành cho tương thích. Chạy openclaw doctor --fix để ghi lại cấu hình đã lưu thành talk.providers.<provider>.
• Voice ID dự phòng về ELEVENLABS_VOICE_ID hoặc SAG_VOICE_ID.
• providers.*.apiKey chấp nhận chuỗi văn bản thuần hoặc đối tượng SecretRef.
• Dự phòng ELEVENLABS_API_KEY chỉ áp dụng khi không có API key Nói chuyện nào được cấu hình.
• providers.*.voiceAliases cho phép chỉ thị Nói chuyện dùng tên thân thiện.
• providers.mlx.modelId chọn repo Hugging Face được helper MLX cục bộ trên macOS dùng. Nếu bỏ qua, macOS dùng mlx-community/Soprano-80M-bf16.
• Phát lại MLX trên macOS chạy qua helper openclaw-mlx-tts đi kèm khi có, hoặc một tệp thực thi trên PATH; OPENCLAW_MLX_TTS_BIN ghi đè đường dẫn helper cho phát triển.
• consultThinkingLevel kiểm soát mức suy nghĩ cho lượt chạy tác nhân OpenClaw đầy đủ phía sau các lệnh gọi Control UI Talk realtime openclaw_agent_consult. Để trống để giữ nguyên hành vi phiên/model bình thường.
• consultFastMode đặt ghi đè chế độ nhanh một lần cho các lượt tham vấn Control UI Talk realtime mà không thay đổi cài đặt chế độ nhanh bình thường của phiên.
• speechLocale đặt id locale BCP 47 được nhận dạng giọng nói Talk trên iOS/macOS dùng. Để trống để dùng mặc định của thiết bị.
• silenceTimeoutMs kiểm soát thời gian chế độ Nói chuyện chờ sau khi người dùng im lặng trước khi gửi bản chép lời. Không đặt sẽ giữ cửa sổ tạm dừng mặc định của nền tảng (700 ms trên macOS và Android, 900 ms trên iOS).
• realtime.instructions nối thêm chỉ dẫn hệ thống hướng tới nhà cung cấp vào prompt realtime tích hợp sẵn của OpenClaw, để có thể cấu hình phong cách giọng nói mà không mất hướng dẫn openclaw_agent_consult mặc định.
• realtime.consultRouting kiểm soát dự phòng chuyển tiếp Gateway khi nhà cung cấp realtime tạo bản chép lời người dùng cuối cùng mà không có openclaw_agent_consult: provider-direct giữ nguyên phản hồi trực tiếp của nhà cung cấp, còn force-agent-consult định tuyến yêu cầu đã hoàn tất qua OpenClaw.

​

Liên quan

• Tham chiếu cấu hình — tất cả khóa cấu hình khác
• Cấu hình — tác vụ thường gặp và thiết lập nhanh
• Ví dụ cấu hình