Cấu hình — các tác tử

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.

​

Mặc định cho tác nhân

​

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 giá trị 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 nhân đó; nó không hợp nhất với các giá trị 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úp giảm kích thước prompt. Các lượt Heartbeat và các lần thử lại sau Compaction vẫn xây dựng lại ngữ cảnh.
• "never": tắt bootstrap workspace và chèn tệp ngữ cảnh ở mọi lượt. Chỉ dùng tùy chọn này cho các tác nhân tự quản lý hoàn toàn vòng đời prompt của chúng (các engine ngữ cảnh tùy chỉnh, runtime native tự xây dựng ngữ cảnh riêng, hoặc các quy trình chuyên biệt không cần 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: 12000 } },
}

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

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

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // 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ần chạy model khi đặt lại/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 model.
• skills.limits.*: danh sách Skills rút 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[].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: giới hạn đoạn trích memory_get mặc định trước khi thêm siêu dữ liệu cắt bớt và thông báo tiếp tục.
• memoryGetDefaultLines: cửa sổ dòng memory_get mặc định khi bỏ qua lines.
• toolResultMaxChars: giới hạn kết quả công cụ trực tiếp được dùng cho kết quả được lưu bền vững và khôi phục tràn.
• postCompactionMaxChars: giới hạn đoạn trích AGENTS.md được dùng trong quá trình chèn làm mới sau 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: chấp nhận một chuỗi ("provider/model") hoặc một đố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 cùng các mô hình chuyển đổi dự phòng có thứ tự.
• imageModel: chấp nhận một chuỗi ("provider/model") hoặc một đố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ể nhận đầu vào hình ảnh.
  • Ưu tiên 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 hỗ trợ hình ảnh đã cấu hình trong models.providers.*.models, OpenClaw sẽ gán nó cho nhà cung cấp đó. Các khớp đã cấu hình nhưng mơ hồ yêu cầu tiền tố nhà cung cấp rõ ràng.
• imageGenerationModel: chấp nhận một chuỗi ("provider/model") hoặc một đố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 PNG/WebP OpenAI nền trong suốt.
  • Nếu bạn chọn trực tiếp một nhà cung cấp/mô hình, hãy cấu hình cả xác thực nhà cung cấp 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 mặc định nhà cung cấp dựa trên xác thực. Nó thử nhà cung cấp mặc định hiện tại trước, rồi đến các nhà cung cấp tạo hình ảnh đã đăng ký còn lại theo thứ tự ID nhà cung cấp.
• musicGenerationModel: chấp nhận một chuỗi ("provider/model") hoặc một đố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 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 mặc định nhà cung cấp dựa trên xác thực. Nó thử nhà cung cấp mặc định hiện tại trước, rồi đến các nhà cung cấp tạo nhạc đã đăng ký còn lại theo thứ tự ID nhà cung cấp.
  • Nếu bạn chọn trực tiếp một nhà cung cấp/mô hình, hãy cấu hình cả xác thực/khóa API nhà cung cấp tương ứng.
• videoGenerationModel: chấp nhận một chuỗi ("provider/model") hoặc một đối tượng ({ primary, fallbacks }).
  • Được năng lực tạo video dùng chung và công cụ tích hợp 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 mặc định nhà cung cấp dựa trên xác thực. Nó thử nhà cung cấp mặc định hiện tại trước, rồi đến các nhà cung cấp tạo video đã đăng ký còn lại theo thứ tự ID nhà cung cấp.
  • Nếu bạn chọn trực tiếp một nhà cung cấp/mô hình, hãy cấu hình cả xác thực/khóa API nhà cung cấp tương ứng.
  • Nhà cung cấp tạo video Qwen đi kèm 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 nhà cung cấp size, aspectRatio, resolution, audio, và watermark.
• pdfModel: chấp nhận một chuỗi ("provider/model") hoặc một đố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 dự phòng 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 chế độ dự phòng trích xuất trong công cụ pdf xem xét.
• verboseDefault: mức chi tiết mặc định cho tác tử. 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ụ bản nháp tiến độ. Giá trị: "explain" (mặc định, nhãn ngắn gọn cho người đọc) hoặc "raw" (thêm lệnh/chi tiết thô khi có). agents.list[].toolProgressDetail theo từng tác tử ghi đè mặc định này.
• reasoningDefault: mức hiển thị suy luận mặc định cho tác tử. Giá trị: "off", "on", "stream". agents.list[].reasoningDefault theo từng tác tử 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 của quản trị viên vận hành khi không có 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 tác tử. Giá trị: "off", "on", "ask", "full". Mặc định: "on".
• model.primary: định dạng provider/model (ví dụ openai/gpt-5.5 cho quyền truy cập bằng khóa API OpenAI hoặc Codex OAuth). Nếu bạn bỏ qua nhà cung cấp, OpenClaw thử bí danh trước, rồi đến một khớp nhà cung cấp đã cấu hình duy nhất cho đúng ID mô hình đó, và chỉ sau đó mới dự phòng về nhà cung cấp mặc định đã cấu hình (hành vi tương thích đã lỗi thời, nên hãy ưu tiên provider/model rõ ràng). Nếu nhà cung cấp đó không còn cung cấp mô hình mặc định đã cấu hình, OpenClaw dự phòng về nhà cung cấp/mô hình đã cấu hình đầu tiên thay vì hiển thị mặc định nhà cung cấp cũ đã bị gỡ.
• models: danh mục 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 nhà cung cấp, ví dụ temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody).
  • Dùng các mục provider/* như "openai-codex/*": {} hoặc "vllm/*": {} để hiển thị mọi mô hình được phát hiện cho các nhà cung cấp đã chọn mà không phải liệt kê thủ công từng ID mô hình.
  • 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 danh sách cho phép hiện có trừ khi bạn truyền --replace.
  • Các luồng cấu hình/onboarding theo phạm vi nhà cung cấp hợp nhất các mô hình nhà cung cấp đã chọn vào bản đồ này và giữ nguyên các nhà cung cấp 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 để ngừng chèn context_management, hoặc params.responsesCompactThreshold để ghi đè ngưỡng. Xem Compaction phía máy chủ OpenAI.
• params: tham số nhà cung cấp 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 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 tác tử) ghi đè theo khóa. Xem Prompt Caching để biết chi tiết.
• params.extra_body/params.extraBody: JSON truyền qua 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 OpenAI. Nếu nó xung đột với các khóa yêu cầu được tạo, 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ó độ ưu tiên cuối cùng. Với điều khiển thinking Qwen trên vLLM, đặt params.qwenThinkingFormat thành "chat-template" hoặc "top-level" trên mục mô hình đó.
• compat.thinkingFormat: kiểu tải trọng thinking tương thích OpenAI. Dùng "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 vLLM. OpenClaw ánh xạ thinking bị tắt thành false và thinking được bật thành true.
• compat.supportedReasoningEfforts: danh sách mức nỗ lực suy luận tương thích OpenAI theo mô hình. Bao gồm "xhigh" cho các endpoint tùy chỉnh thực sự chấp nhận giá trị đó; 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 tác tử, và xác thực llm-task cho nhà cung cấp/mô hình đã cấu hình đó. Dùng compat.reasoningEffortMap khi backend muốn một giá trị riêng theo nhà cung cấp cho một mức chuẩn.
• params.preserveThinking: tùy chọn bật riêng 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 tùy chọn cấp nhà cung cấp cho máy chủ mô hình cục bộ/tự lưu trữ. Khi mô hình đã chọn thuộc nhà cung cấp đó, 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à một đường dẫn tuyệt đối. idleStopMs: 0 giữ tiến trình chạy cho đến khi OpenClaw thoát; một giá trị dương sẽ dừng tiến trình do OpenClaw 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 runtime thuộc về nhà cung cấp hoặc mô hình, không thuộc agents.defaults. Dùng models.providers.<provider>.agentRuntime cho quy tắc toàn nhà cung cấp 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 tác tử OpenAI trên nhà cung cấp OpenAI chính thức chọn Codex theo mặc định.
• Trình ghi cấu hình thay đổi các trường này (ví dụ các lệnh /models set, /models set-image, và thêm/xóa dự phòng) lưu dạng đối tượng chuẩn và giữ lại danh sách dự phòng hiện có khi có thể.
• maxConcurrent: số lượt chạy tác tử 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 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 đã đă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 PI khi không có harness nào khớp. Một runtime Plugin rõ ràng như id: "codex" yêu cầu harness đó và đóng lỗi nếu nó không khả dụng hoặc thất bại.
• Khóa runtime toàn tác tử là di sản. agents.defaults.agentRuntime, agents.list[].agentRuntime, ghim runtime phiên, và OPENCLAW_AGENT_RUNTIME bị bỏ qua trong lựa chọn runtime. Chạy openclaw doctor --fix để xóa các giá trị cũ.
• Các mô hình tác tử OpenAI dùng harness Codex theo mặc định; agentRuntime.id: "codex" theo nhà cung cấp/mô hình vẫn hợp lệ khi bạn muốn biểu thị rõ điều đó.
• Với triển khai Claude CLI, ưu tiên model: "anthropic/claude-opus-4-7" cùng agentRuntime.id: "claude-cli" theo phạm vi mô hình. Tham chiếu mô hình claude-cli/claude-opus-4-7 cũ vẫn hoạt động để tương thích, nhưng cấu hình mới nên giữ lựa chọn nhà cung cấp/mô hình ở dạng chuẩn và đặt backend thực thi trong chính sách runtime nhà cung cấp/mô hình.
• Điều này chỉ kiểm soát thực thi lượt tác tử văn bản. Tạo phương tiện, thị giác, PDF, nhạc, video, và TTS vẫn dùng các thiết lập nhà cung cấp/mô hình tương ứng.

​

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

• Các backend CLI ưu tiên văn bản; công cụ luôn bị tắt.
• Hỗ trợ phiên khi sessionArg được đặt.
• Hỗ trợ chuyển tiếp hình ảnh khi imageArg chấp nhận đường dẫn tệp.
• reseedFromRawTranscriptWhenUncompacted: true cho phép backend khôi phục các phiên đã bị vô hiệu hóa một cách an toàn từ phần đuôi transcript OpenClaw thô có giới hạn trước khi bản tóm tắt compaction đầu tiên tồn tại. Các thay đổi hồ sơ xác thực hoặc credential-epoch vẫn không bao giờ 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" (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 cũ vẫn được đọc khi thiết lập 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 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ỏ 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, chặ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 đối với một lượt agent Heartbeat trước khi bị hủy. Để trống để dùng agents.defaults.timeoutSeconds.
• 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 việc 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 của 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 với 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ẽ trì hoãn trên các làn bận bổ sung: công việc subagent hoặc lệnh lồng nhau. Các làn Cron luôn trì hoãn Heartbeat, ngay cả khi không có cờ này.
• Theo 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: 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 hoặc safeguard (tóm tắt theo khối cho lịch sử dài). Xem Compaction.
• provider: ID của một Plugin nhà cung cấp Compaction đã đăng ký. Khi được đặt, summarize() của nhà cung cấp được gọi thay vì tóm tắt LLM tích hợp. Quay về tích hợp nếu lỗi. Việc đặt nhà cung cấp 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 trước khi OpenClaw hủy nó. Mặc định: 900.
• keepRecentTokens: ngân sách điểm cắt Pi để giữ nguyên văn phần đuôi transcript gần đây nhất. /compact thủ công tôn trọng 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 hướng dẫn giữ lại định danh mờ tích hợp ở đầu 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 tóm tắt safeguard. Được bật theo mặc định ở chế độ safeguard; đặt enabled: false để bỏ qua kiểm toán.
• midTurnPrecheck: kiểm tra áp lực tool-loop Pi 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ệnh 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 dẫn khôi phục precheck hiện có để cắt ngắn kết quả công cụ hoặc compact rồi thử lại. Hoạt động với cả chế độ Compaction default và safeguard. Mặc định: tắt.
• postCompactionSections: tên phần H2/H3 AGENTS.md tùy chọn để chèn lại sau Compaction. Mặc định là ["Session Startup", "Red Lines"]; đặt [] để tắt chèn lại. Khi chưa đặt hoặc được đặt rõ ràng thành cặp mặc định đó, các tiêu đề cũ Every Session/Safety cũng được chấp nhận như fallback kế thừa.
• model: ghi đè provider/model-id tùy chọn chỉ dành cho tóm tắt Compaction. Dùng khi phiên chính cần giữ một mô hình nhưng tóm tắt Compaction cần chạy trên mô hình khác; khi chưa đặ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 quá ngưỡng. Yêu cầu truncateAfterCompaction để Compaction thành công có thể xoay sang transcript kế tiếp nhỏ hơn. Bị tắt khi chưa đặt hoặc bằng 0.
• notifyUser: khi là 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 trữ 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 housekeeping này nên ở trên mô hình cục bộ; ghi đè 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.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"] },
      },
    },
  },
}

​

Truyền trực tuyến 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 đặt rõ *.blockStreaming: true để bật phản hồi theo khối.
• Ghi đè theo kênh: channels.<channel>.blockStreamingCoalesce (và các biến thể theo tài khoản). Signal/Slack/Discord/Google Chat mặc định minChars: 1500.
• humanDelay: khoảng dừng ngẫu nhiên giữa các phản hồi theo khối. natural = 800–2500ms. Ghi đè theo 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 trò chuyện trực tiếp/lượt nhắc tên, message cho trò chuyện nhóm không nhắc tên.
• Ghi đè 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 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: mã định danh tác nhân ổn định (bắt buộc).
• default: khi đặt nhiều mục, mục đầu tiên sẽ thắng (ghi nhật ký 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 mô hình chính nghiêm ngặt cho từng tác nhân, không có mô hình dự phòng; dạng đối tượng { primary } cũng nghiêm ngặt trừ khi bạn thêm fallbacks. Dùng { primary, fallbacks: [...] } để cho tác nhân đó dùng dự phòng, 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 dự phòng mặc định trừ khi bạn đặt fallbacks: [].
• params: tham số luồng cho từng tác nhân, được hợp nhất đè lên mục mô hình đã chọn trong agents.defaults.models. Dùng mục này cho các ghi đè riêng theo tác nhân như cacheRetention, temperature, hoặc maxTokens mà không cần sao chép toàn bộ danh mục mô hình.
• tts: ghi đè văn bản thành giọng nói tùy chọn cho từng tác nhân. Khối này hợp nhất sâu đè lên messages.tts, vì vậy hãy giữ thông tin xác thực nhà cung cấp dùng chung và chính sách dự phòng trong messages.tts, rồi chỉ đặt các giá trị riêng theo persona như nhà cung cấp, giọng nói, mô hình, phong cách, hoặc chế độ tự động ở đây.
• skills: danh sách cho phép skill tùy chọn cho từng tác nhân. Nếu bỏ qua, tác nhân kế thừa agents.defaults.skills khi được đặ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.
• thinkingDefault: mức suy nghĩ mặc định tùy chọn cho từng tác nhân (off | minimal | low | medium | high | xhigh | adaptive | max). Ghi đè agents.defaults.thinkingDefault cho tác nhân này khi không đặt ghi đè theo tin nhắn hoặc phiên. Hồ sơ nhà cung cấp/mô hình đã chọn kiểm soát những giá trị nào hợp lệ; với Google Gemini, adaptive giữ cơ chế suy nghĩ động do nhà cung cấp 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 cho từng tác nhân (on | off | stream). Ghi đè agents.defaults.reasoningDefault cho tác nhân này khi không đặt ghi đè reasoning theo tin nhắn hoặc phiên.
• fastModeDefault: mặc định tùy chọn cho từng tác nhân đối với chế độ nhanh (true | false). Áp dụng khi không đặt ghi đè chế độ nhanh theo tin nhắn hoặc phiên.
• models: ghi đè danh mục mô hình/runtime tùy chọn cho từng tác nhân, được khóa theo mã định danh provider/model đầy đủ. Dùng models["provider/model"].agentRuntime cho các ngoại lệ runtime theo từng tác nhân.
• runtime: bộ mô tả runtime tùy chọn cho từng tác nhân. Dùng type: "acp" với các mặc định runtime.acp (agent, backend, mode, cwd) khi tác nhân nên mặc định dùng các phiên ACP harness.
• identity.avatar: đường dẫn tương đối với workspace, URL http(s), hoặc URI data:.
• identity suy ra các mặc định: ackReaction từ emoji, mentionPatterns từ name/emoji.
• subagents.allowAgents: danh sách cho phép các mã định danh tác nhân cho đích sessions_spawn.agentId rõ ràng (["*"] = bất kỳ; mặc định: chỉ cùng tác nhân). Bao gồm mã định danh của bên yêu cầu khi cần cho phép các lệnh gọi agentId tự nhắm mục tiêu.
• Bộ bảo vệ kế thừa sandbox: nếu phiên của bên yêu cầu đang bị sandbox, sessions_spawn từ chối các đích sẽ chạy không bị sandbox.
• subagents.requireAgentId: khi là true, chặn các lệnh gọi sessions_spawn bỏ qua agentId (buộc chọn hồ sơ rõ ràng; mặc định: false).

​

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

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

​

Các trường khớp binding

• type (tùy chọn): route cho định tuyến thông thường (thiếu type mặc định là route), acp cho binding hội thoại ACP bền vững.
• 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; theo từng kênh)
• acp (tùy chọn; chỉ dành 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 nhân mặc định

​

Hồ sơ truy cập theo từng tác nhân

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

​

Tin nhắn

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

​

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ì "👀". Đặ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 phản ứng xác nhận sau khi trả lời trên các kênh hỗ trợ phản ứng như Slack, Discord, Telegram, WhatsApp và iMessage.
• messages.statusReactions.enabled: bật phản ứng trạng thái vòng đời trên Slack, Discord và Telegram. Trên Slack và Discord, khi chưa đặ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 Telegram, hãy đặt rõ thành true để bật phản ứng trạng thái vòng đời.

​

Chống dội đầ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-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 điều khiển chế độ tự động 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 hiệu lực.
• summaryModel ghi đè agents.defaults.model.primary cho tóm tắt tự động.
• modelOverrides được bật theo mặc định; modelOverrides.allowProvider mặc định là false (chọn tham gia).
• Khóa API dự phòng về ELEVENLABS_API_KEY/XI_API_KEY và OPENAI_API_KEY.
• Các nhà cung cấp giọng nói đóng gói thuộc sở hữu Plugin. Nếu đặt plugins.allow, hãy bao gồm từng Plugin nhà cung cấp TTS 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, sau đó OPENAI_TTS_BASE_URL, rồi https://api.openai.com/v1.
• Khi providers.openai.baseUrl trỏ tới endpoint không phải OpenAI, OpenClaw coi nó là máy chủ TTS tương thích OpenAI và nới lỏng xác thực mô hình/giọng nói.

​

Talk

{
  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 phải khớp với một khóa trong talk.providers khi cấu hình nhiều nhà cung cấp Talk.
• Các khóa Talk phẳng cũ (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) chỉ để tương thích. Chạy openclaw doctor --fix để ghi lại cấu hình đã lưu vào 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 chưa cấu hình khóa API Talk.
• providers.*.voiceAliases cho phép chỉ thị Talk 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 sử 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 đóng gói 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 điều khiển mức suy nghĩ cho toàn bộ lần chạy tác nhân OpenClaw 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/mô hình bình thường.
• consultFastMode đặt ghi đè chế độ nhanh một lần cho các lần consult Control UI Talk realtime mà không thay đổi thiết lập chế độ nhanh bình thường của phiên.
• speechLocale đặt id locale BCP 47 dùng cho nhận dạng giọng nói Talk trên iOS/macOS. Để trống để dùng mặc định của thiết bị.
• silenceTimeoutMs điều khiển thời gian chế độ Talk chờ sau khi người dùng im lặng trước khi gửi transcript. Khi chưa đặt, cửa sổ tạm dừng mặc định của nền tảng được giữ nguyên (700 ms trên macOS và Android, 900 ms trên iOS).
• realtime.instructions nối thêm hướng dẫn hệ thống dành cho nhà cung cấp vào prompt realtime tích hợp 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 mặc định openclaw_agent_consult.

​

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ụ phổ biến và thiết lập nhanh
• Ví dụ cấu hình