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

Documentation Index

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

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

​

Mặc định của 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 hạn chế kỹ năng.
• Bỏ qua agents.list[].skills để kế thừa các giá trị mặc định.
• Đặt agents.list[].skills: [] để không có kỹ năng.
• Danh sách agents.list[].skills không rỗng là tập cuối cùng cho tác nhân đó; danh sách này 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 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ầ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 ở mọi lượt. Chỉ dùng tùy chọn này cho các tác nhân hoàn toàn tự sở hữu vòng đời prompt của chúng (công cụ ngữ cảnh tùy chỉnh, runtime native tự xây dựng ngữ cảnh, hoặc quy trình chuyên biệt không cần bootstrap). Các lượt Heartbeat và phục hồi 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 ngắn 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 ngắn duy nhất (khuyến nghị).
• "always": chèn thông báo ngắn gọn ở mọi lần chạy khi có cắt ngắn.

{
  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 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 thuần /new và /reset được xác nhận mà không gọi mô hình.
• skills.limits.*: danh sách Skills rút gọn được chèn vào system prompt.
• agents.defaults.contextLimits.*: trích đoạn runtime có giới hạn và các khối do runtime sở hữu được chèn.
• memory.qmd.limits.*: kích thước đoạn trích tìm kiếm bộ nhớ đã lập chỉ mục và phần 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 trích đoạn memory_get mặc định trước khi thêm metadata cắt ngắn 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 dùng cho kết quả được lưu lâu dài và phục hồi khi tràn.
• postCompactionMaxChars: giới hạn trích đoạn AGENTS.md 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 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 cùng 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 được 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 đã cấu hình có khả năng xử lý hình ảnh trong models.providers.*.models, OpenClaw sẽ gắn nó với provider đó. Các kết quả khớp đã cấu hình nhưng mơ hồ yêu cầu 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ị điển hình: 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 nền trong suốt của OpenAI.
  • 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 mặc định provider có xác thực hỗ trợ. Nó thử provider mặc định hiện tại trước, sau đó thử 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ị điển hình: 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 provider có xác thực hỗ trợ. Nó thử provider mặc định hiện tại trước, sau đó thử 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ả khóa xác thực/API của 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ị điển hình: 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 provider có xác thực hỗ trợ. Nó thử provider mặc định hiện tại trước, sau đó thử 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ả khóa xác thực/API của provider tương ứng.
  • Provider 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, cùng 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ẽ 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 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 phần 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 dùng) hoặc "raw" (nối 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ị reasoning 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 reasoning đã 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 operator-admin khi không đặt ghi đè reasoning 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 quyền truy cập bằng khóa API OpenAI hoặc Codex OAuth). Nếu bạn bỏ qua provider, OpenClaw sẽ thử alias trước, rồi 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ẽ dự phòng về provider/model đã cấu hình đầu tiên thay vì hiển thị mặc định provider đã bị loại bỏ và lỗi thời.
• 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 (đặc thù provider, 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ị tất cả mô hình được 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.
  • 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.
  • Đối 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ố provider mặc định toàn cục áp dụng cho tất cả 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 Prompt Caching để biết chi tiết.
• params.extra_body/params.extraBody: JSON chuyển tiếp nâng cao được hợp nhất vào thân yêu cầu api: "openai-completions" cho proxy tương thích 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 trò chuyện tương thích vLLM/OpenAI được hợp nhất vào thân yêu cầu cấp cao nhất api: "openai-completions". 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 đè các mặc định được tạo, và extra_body.chat_template_kwargs vẫn có quyền ưu tiên cuối cùng. Đối với điều khiển thinking của vLLM Qwen, đặt params.qwenThinkingFormat thành "chat-template" hoặc "top-level" trên mục mô hình đó.
• compat.thinkingFormat: kiểu payload 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 trò chuyện cấp yêu cầu, chẳng hạn vLLM. OpenClaw ánh xạ thinking đã tắt thành false và thinking đã bật thành true.
• compat.supportedReasoningEfforts: danh sách effort reasoning tương thích 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 giá trị đặc thù provider cho một mức chuẩn.
• params.preserveThinking: tùy chọn bật riêng cho Z.AI để giữ thinking. Khi 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 của Z.AI và thinking được giữ lại.
• localService: trình quản lý tiến trình tùy chọn ở cấp provider cho máy chủ mô hình cục bộ/tự lưu trữ. Khi mô hình được chọn thuộc provider đó, OpenClaw thăm dò healthUrl (hoặc baseUrl + "/models"), khởi động command với args nếu endpoint đang 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 hoạt động cho đến khi OpenClaw thoát; giá trị dương 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ề provider hoặc mô hình, không thuộc về 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 những 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 trên 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 alias 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. 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.
• 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ị lựa chọn runtime bỏ qua. Chạy openclaw doctor --fix để xóa các giá trị lỗi thời.
• Các mô hình agent OpenAI dùng harness Codex theo mặc định; agentRuntime.id: "codex" theo provider/model vẫn hợp lệ khi bạn muốn làm 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" trong phạm vi mô hình. Tham chiếu 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 ở dạng chuẩn và đặt backend thực thi trong chính sách runtime provider/model.
• Điều này chỉ điều khiển thực thi lượt agent văn bản. Tạo nội dung media, thị giác, PDF, nhạc, video, và TTS vẫn dùng thiết lập provider/model của chú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",
        },
      },
    },
  },
}

• 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ợ truyền ảnh qua khi imageArg chấp nhận đường dẫn tệp.
• reseedFromRawTranscriptWhenUncompacted: true cho phép một 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 tồn tại 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ờ khởi tạo lại từ bản thô.

​

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 kiểu 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 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ỏ 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, tắt 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 được phép cho 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 đích trực tiếp. block chặn gửi tới đích 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 gọn 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 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ẽ trì hoãn trên các lane 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 lane Cron luôn trì hoãn Heartbeat, kể 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ỉ những agent đó chạy Heartbeat.
• Heartbeat chạy đầy đủ các lượt agent — khoảng thời gian ngắn hơn sẽ 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 sẽ được gọi thay cho tóm tắt LLM tích hợp sẵn. Quay về tích hợp sẵn khi gặp lỗi. Việc đặt nhà cung cấp buộc mode: "safeguard". Xem Compaction.
• timeoutSeconds: số giây tối đa được phép cho một thao tác compaction trước khi OpenClaw hủy thao tác đó. 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 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 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 về bảo toàn định danh, dùng khi identifierPolicy=custom.
• qualityGuard: kiểm tra thử lại khi đầu ra sai định dạng cho các 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ụ 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 thêm vào và trước lệnh gọi mô hình tiếp theo. Nếu ngữ cảnh không còn vừa, OpenClaw 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 bớt kết quả công cụ hoặc compact 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 tùy chọn trong AGENTS.md để 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 làm phương án tương thích kế thừa.
• model: ghi đè provider/model-id tùy chọn chỉ cho tóm tắt compaction. Dùng tùy chọn này khi phiên chính nên giữ một mô hình nhưng bản tóm tắt compaction nê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ộ bình 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 là 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ụ: “Đang compact ngữ cảnh…” và “Compaction hoàn tất”). Mặc định tắt để giữ compaction im lặng.
• memoryFlush: lượt agent im lặng trước auto-compaction để lưu các ghi nhớ lâu bền. Đặ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 nên giữ trên mô hình cục bộ; ghi đè này không kế thừa chuỗi dự phòng của phiên đang hoạt động. Bị bỏ qua khi workspace 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ố vòng lặp thử lại cơ sở cho vòng chạy bên ngoài. Mặc định: 24.
• perProfile: số vòng lặp thử lại bổ sung được cấp cho mỗi ứng viên hồ sơ dự phòng. Mặc định: 8.
• min: giới hạn tuyệt đối tối thiểu cho số vòng lặp thử lại. Mặc định: 32.
• max: giới hạn tuyệt đối tối đa cho số vòng lặp thử lại để 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"] },
      },
    },
  },
}

​

Truyền phát 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 yêu cầu *.blockStreaming: true rõ ràng để bật phản hồi theo khối.
• Ghi đè 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 là minChars: 1500.
• humanDelay: tạm dừng ngẫu nhiên giữa các phản hồi theo khối. natural = 800–2500ms. Ghi đè theo từng tác nhân: 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 từng tác nhân)

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

• id: id tác tử ổn định (bắt buộc).
• default: khi có nhiều mục được đặt, mục đầu tiên thắng (ghi 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 theo từng tác tử mà 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 tử đó tham gia cơ chế dự phòng, hoặc { primary, fallbacks: [] } để làm rõ hành vi nghiêm ngặt. Các tác vụ Cron chỉ ghi đè primary vẫn kế thừa các dự phòng mặc định trừ khi bạn đặt fallbacks: [].
• params: tham số luồng theo từng tác tử được hợp nhất lên trê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 tử như cacheRetention, temperature, hoặc maxTokens mà không cần nhân bản toàn bộ danh mục mô hình.
• tts: ghi đè chuyển văn bản thành giọng nói tùy chọn theo từng tác tử. Khối này hợp nhất sâu lên trên messages.tts, vì vậy hãy giữ thông tin đăng nhập 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 tính cách như nhà cung cấp, giọng, mô hình, phong cách, hoặc chế độ tự động tại đây.
• skills: danh sách cho phép 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; danh sách tường minh 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 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 đặt ghi đè theo từng tin nhắn hoặc phiên. Hồ sơ nhà cung cấp/mô hình đã chọn kiểm soát các giá trị 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: hiển thị suy luận 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 đặt ghi đè suy luận 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 chế độ nhanh (true | false). Áp dụng khi không đặt ghi đè chế độ nhanh theo từng tin nhắn hoặc phiên.
• models: ghi đè danh mục/thời gian chạy mô hình tùy chọn theo từng tác tử, được khóa bằng id provider/model đầy đủ. Dùng models["provider/model"].agentRuntime cho các ngoại lệ thời gian chạy theo từng tác tử.
• runtime: mô tả thời gian chạy 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 so 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 id tác tử cho các mục tiêu sessions_spawn.agentId tường minh (["*"] = bất kỳ; mặc định: chỉ cùng tác tử). Bao gồm id người yêu cầu khi các lệnh gọi agentId tự nhắm mục tiêu cần được cho phép.
• Bộ bảo vệ kế thừa sandbox: nếu phiên người yêu cầu bị sandbox, sessions_spawn từ chối các mục tiêu sẽ chạy không 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ơ tường minh; 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" } },
  ],
}

​

Các trường khớp ràng buộc

• type (tùy chọn): route cho định tuyến thông thường (thiếu type mặc định là route), acp cho các ràng buộc 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; theo kênh cụ thể)
• 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 tử mặc định

​

Hồ sơ 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: "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 tử đ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 theo 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 có 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 không đặt, phản ứng trạng thái vẫn bật nếu phản ứng xác nhận đang hoạt động. Trên Telegram, đặt rõ thành true để bật phản ứng trạng thái vòng đời.

​

Gộp trễ tin nhắn đến

​

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ự động tóm tắt.
• modelOverrides được bật theo mặc định; modelOverrides.allowProvider mặc định là false (phải chọn bật).
• Khóa API dự phòng sang ELEVENLABS_API_KEY/XI_API_KEY và OPENAI_API_KEY.
• Các nhà cung cấp giọng nói đi kèm do plugin sở hữu. Nếu đặt plugins.allow, 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 đè điểm cuối 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 điểm cuối không phải OpenAI, OpenClaw xem đó là máy chủ TTS tương thích OpenAI và nới lỏng kiểm tra mô hình/giọng nói.

​

Trò chuyện

{
  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 Trò chuyện.
• Các khóa Trò chuyện phẳng cũ (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) chỉ nhằm tương thích. Chạy openclaw doctor --fix để viết lại cấu hình đã lưu vào talk.providers.<provider>.
• ID giọng nói dự phòng sang 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ấu hình khóa API Trò chuyện.
• providers.*.voiceAliases cho phép chỉ thị Trò chuyện dùng tên thân thiện.
• providers.mlx.modelId chọn repo Hugging Face được trình trợ giúp 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 trình trợ giúp 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 trình trợ giúp cho phát triển.
• consultThinkingLevel điều khiển mức suy nghĩ cho lần chạy tác tử OpenClaw đầy đủ phía sau các lệnh gọi openclaw_agent_consult thời gian thực của Trò chuyện trong Control UI. Để 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 tham vấn Trò chuyện thời gian thực trong Control UI 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 Trò chuyện của iOS/macOS sử dụng. Để trống để dùng mặc định của thiết bị.
• silenceTimeoutMs điều khiển thời gian chế độ Trò 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ữ khoảng 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ỉ thị hệ thống hướng đến nhà cung cấp vào prompt thời gian thực 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 openclaw_agent_consult mặc định.

​

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