Gateway Agent 配置

agents.*、session.*、messages.*、talk.* 等 Agent 相关配置键。

Agent 默认值（agents.defaults）

工作区与基础设置

{
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      repoRoot: "~/Projects/openclaw",  // 可选，系统提示中显示的仓库根目录
      userTimezone: "America/Chicago",
      timeFormat: "auto",  // auto | 12 | 24
      imageMaxDimensionPx: 1200,  // 图片最长边像素上限，降低可减少 vision token 用量
    },
  },
}

模型配置

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: { primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free" },
      imageGenerationModel: { primary: "openai/gpt-image-2" },
      videoGenerationModel: { primary: "qwen/wan2.6-t2v" },
      pdfModel: { primary: "anthropic/claude-opus-4-6" },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "openai/gpt-5.5": { alias: "gpt" },
      },
      thinkingDefault: "low",  // off | minimal | low | medium | high | xhigh | adaptive | max
      verboseDefault: "off",
      toolProgressDetail: "explain",  // explain | raw
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      maxConcurrent: 4,
    },
  },
}

内置模型别名（仅当模型在 agents.defaults.models 中时生效）：

别名	模型
`opus`	`anthropic/claude-opus-4-6`
`sonnet`	`anthropic/claude-sonnet-4-6`
`gpt`	`openai/gpt-5.5`
`gemini`	`google/gemini-3.1-pro-preview`

Skills 配置

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" },                          // 继承 github, weather
      { id: "docs", skills: ["docs-search"] },   // 替换默认值
      { id: "locked-down", skills: [] },         // 无 skills
    ],
  },
}

省略 agents.defaults.skills：默认不限制 skills
省略 agents.list[].skills：继承默认值
设置 agents.list[].skills: []：无 skills

Bootstrap 文件控制

{
  agents: {
    defaults: {
      skipBootstrap: true,  // 禁用自动创建 AGENTS.md 等 bootstrap 文件
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
      contextInjection: "continuation-skip",  // always | continuation-skip | never
      bootstrapMaxChars: 12000,
      bootstrapTotalMaxChars: 60000,
    },
  },
}

Heartbeat（定期检查）

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",          // 0m 禁用
        target: "last",        // last | none | <channel-id>
        directPolicy: "allow", // allow | block
        model: "openai/gpt-5.4-mini",
        isolatedSession: false, // true 时每次 heartbeat 使用全新 session
        lightContext: false,    // true 时只保留 HEARTBEAT.md
        skipWhenBusy: false,
        timeoutSeconds: 45,
      },
    },
  },
}

Compaction（上下文压缩）

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard",  // default | safeguard
        timeoutSeconds: 900,
        keepRecentTokens: 50000,
        identifierPolicy: "strict",  // strict | off | custom
        model: "openrouter/anthropic/claude-sonnet-4-6",
        truncateAfterCompaction: true,
        notifyUser: true,
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b",
        },
      },
    },
  },
}

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
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          network: "none",
          user: "1000:1000",
          memory: "1g",
          cpus: 1,
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
        },
        prune: { idleHours: 24, maxAgeDays: 7 },
      },
    },
  },
}

构建沙箱镜像：

scripts/sandbox-setup.sh           # 主沙箱镜像
scripts/sandbox-browser-setup.sh   # 可选浏览器镜像

Context 预算

配置键	用途
`bootstrapMaxChars` / `bootstrapTotalMaxChars`	workspace bootstrap 注入
`startupContext.*`	重置/启动时的一次性前言
`skills.limits.*`	注入系统提示的 skills 列表
`contextLimits.*`	运行时有界摘录
`memory.qmd.limits.*`	内存搜索片段大小

每个 Agent 的覆盖（agents.list）

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        model: "anthropic/claude-opus-4-6",
        thinkingDefault: "high",
        reasoningDefault: "on",
        skills: ["docs-search"],
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
        },
        subagents: { allowAgents: ["*"] },
      },
    ],
  },
}

id：必填，稳定的 agent ID
default：多个时第一个生效；未设置时第一个列表条目为默认
model：字符串形式设置严格主模型（无回退）；对象形式 { primary, fallbacks } 支持回退

多 Agent 路由

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

绑定匹配字段

match.channel（必填）
match.accountId（可选；* = 任意账号）
match.peer（可选；{ kind: direct|group|channel, id }）

确定性匹配顺序：match.peer > match.guildId > match.teamId > match.accountId（精确）> match.accountId: "*" > 默认 agent

访问配置示例

完全访问（无沙箱）：

{ id: "personal", sandbox: { mode: "off" } }

只读工具 + 工作区：

{
  id: "family",
  sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
  tools: { deny: ["write", "edit", "apply_patch", "exec", "process", "browser"] },
}

仅消息（无文件系统访问）：

{
  id: "public",
  sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
  tools: { deny: ["read", "write", "edit", "exec", "process", "browser"] },
}

Session 配置

{
  session: {
    dmScope: "per-channel-peer",  // main | per-peer | per-channel-peer | per-account-channel-peer
    reset: {
      mode: "daily",  // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
    },
    maintenance: {
      mode: "warn",  // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      maxDiskBytes: "500mb",
    },
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

Messages 配置

{
  messages: {
    responsePrefix: "🦞",  // 或 "auto"（派生自 identity.name）
    ackReaction: "👀",
    ackReactionScope: "group-mentions",  // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "steer",  // steer | queue | followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
    },
    inbound: { debounceMs: 2000 },
    groupChat: {
      historyLimit: 50,
      visibleReplies: "message_tool",  // message_tool | automatic
    },
  },
}

Talk 模式配置

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        voiceId: "elevenlabs_voice_id",
        modelId: "eleven_v3",
        apiKey: "elevenlabs_api_key",
      },
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    realtime: {
      provider: "openai",
      providers: { openai: { model: "gpt-realtime-2", voice: "cedar" } },
      mode: "realtime",
    },
  },
}

Wiki AI

目录