Конфигурация 🔧

OpenClaw читает опциональный конфигурационный файл JSON5 из ~/.openclaw/openclaw.json (разрешены комментарии и завершающие запятые).

Если файл отсутствует, OpenClaw использует безопасные настройки по умолчанию (встроенный агент Pi + сессии для каждого отправителя + рабочее пространство ~/.openclaw/workspace). Обычно конфигурация нужна только для:

  • ограничения того, кто может активировать бота (channels.whatsapp.allowFrom, channels.telegram.allowFrom и т.д.)
  • управления списками разрешений для групп + поведением упоминаний (channels.whatsapp.groups, channels.telegram.groups, channels.discord.guilds, agents.list[].groupChat)
  • настройки префиксов сообщений (messages)
  • установки рабочего пространства агента (agents.defaults.workspace или agents.list[].workspace)
  • настройки параметров встроенного агента по умолчанию (agents.defaults) и поведения сессий (session)
  • установки идентичности для каждого агента (agents.list[].identity)

Новичок в конфигурации? Ознакомьтесь с руководством Configuration Examples для полных примеров с подробными объяснениями!

Строгая валидация конфигурации

OpenClaw принимает только конфигурации, которые полностью соответствуют схеме. Неизвестные ключи, неправильные типы или недопустимые значения приводят к тому, что Gateway отказывается запускаться из соображений безопасности.

Когда валидация не удается:

  • Gateway не загружается.
  • Разрешены только диагностические команды (например: openclaw doctor, openclaw logs, openclaw health, openclaw status, openclaw service, openclaw help).
  • Запустите openclaw doctor чтобы увидеть точные проблемы.
  • Запустите openclaw doctor --fix (или --yes) для применения миграций/исправлений.

Doctor никогда не записывает изменения, если вы явно не выберете --fix/--yes.

Схема + подсказки для UI

Gateway предоставляет JSON Schema представление конфигурации через config.schema для UI-редакторов. Control UI отображает форму из этой схемы, с редактором Raw JSON в качестве запасного варианта.

Плагины каналов и расширения могут регистрировать схему + подсказки UI для своей конфигурации, чтобы настройки каналов оставались управляемыми схемой во всех приложениях без жестко закодированных форм.

Подсказки (метки, группировка, конфиденциальные поля) поставляются вместе со схемой, чтобы клиенты могли отображать лучшие формы без жестко закодированных знаний о конфигурации.

Применение + перезапуск (RPC)

Используйте config.apply для валидации + записи полной конфигурации и перезапуска Gateway за один шаг. Он записывает sentinel перезапуска и пингует последнюю активную сессию после возвращения Gateway.

Предупреждение: config.apply заменяет всю конфигурацию. Если вы хотите изменить только несколько ключей, используйте config.patch или openclaw config set. Сохраните резервную копию ~/.openclaw/openclaw.json.

Параметры:

  • raw (string) — JSON5 payload для всей конфигурации
  • baseHash (опционально) — хеш конфигурации из config.get (требуется, когда конфигурация уже существует)
  • sessionKey (опционально) — ключ последней активной сессии для wake-up ping
  • note (опционально) — заметка для включения в sentinel перезапуска
  • restartDelayMs (опционально) — задержка перед перезапуском (по умолчанию 2000)

Пример (через gateway call):

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

Частичные обновления (RPC)

Используйте config.patch для слияния частичного обновления в существующую конфигурацию без перезаписи несвязанных ключей. Применяется семантика JSON merge patch:

  • объекты сливаются рекурсивно
  • null удаляет ключ
  • массивы заменяются Как и config.apply, он валидирует, записывает конфигурацию, сохраняет sentinel перезапуска и планирует перезапуск Gateway (с опциональным wake при указании sessionKey).

Параметры:

  • raw (string) — JSON5 payload, содержащий только ключи для изменения
  • baseHash (обязательно) — хеш конфигурации из config.get
  • sessionKey (опционально) — ключ последней активной сессии для wake-up ping
  • note (опционально) — заметка для включения в sentinel перезапуска
  • restartDelayMs (опционально) — задержка перед перезапуском (по умолчанию 2000)

Пример:

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

Минимальная конфигурация (рекомендуемая отправная точка)

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } }
}

Соберите образ по умолчанию один раз с помощью:

scripts/sandbox-setup.sh

Режим самочата (рекомендуется для управления группой)

Чтобы запретить боту отвечать на @-упоминания WhatsApp в группах (отвечать только на определенные текстовые триггеры):

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] }
      }
    ]
  },
  channels: {
    whatsapp: {
      // Список разрешений только для DM; включение вашего собственного номера активирует режим самочата.
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  }
}

Включения конфигурации ($include)

Разделите свою конфигурацию на несколько файлов, используя директиву $include. Это полезно для:

  • Организации больших конфигураций (например, определения агентов для каждого клиента)
  • Совместного использования общих настроек в разных средах
  • Хранения конфиденциальных конфигураций отдельно

Базовое использование

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  
  // Включить один файл (заменяет значение ключа)
  agents: { "$include": "./agents.json5" },
  
  // Включить несколько файлов (глубокое слияние по порядку)
  broadcast: { 
    "$include": [
      "./clients/mueller.json5",
      "./clients/schmidt.json5"
    ]
  }
}

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [
    { id: "main", workspace: "~/.openclaw/workspace" }
  ]
}

Поведение слияния

  • Один файл: Заменяет объект, содержащий $include
  • Массив файлов: Глубокое слияние файлов по порядку (более поздние файлы переопределяют более ранние)
  • С соседними ключами: Соседние ключи сливаются после включений (переопределяют включенные значения)
  • Соседние ключи + массивы/примитивы: Не поддерживается (включенное содержимое должно быть объектом)
// Соседние ключи переопределяют включенные значения
{
  "$include": "./base.json5",   // { a: 1, b: 2 }
  b: 99                          // Результат: { a: 1, b: 99 }
}

Вложенные включения

Включенные файлы могут сами содержать директивы $include (до 10 уровней вглубь):

// clients/mueller.json5
{
  agents: { "$include": "./mueller/agents.json5" },
  broadcast: { "$include": "./mueller/broadcast.json5" }
}

Разрешение путей

  • Относительные пути: Разрешаются относительно включающего файла
  • Абсолютные пути: Используются как есть
  • Родительские каталоги: Ссылки ../ работают как ожидается
{ "$include": "./sub/config.json5" }      // относительный
{ "$include": "/etc/openclaw/base.json5" } // абсолютный
{ "$include": "../shared/common.json5" }   // родительский каталог

Обработка ошибок

  • Отсутствующий файл: Четкая ошибка с разрешенным путем
  • Ошибка парсинга: Показывает, какой включенный файл не удалось разобрать
  • Циклические включения: Обнаруживаются и сообщаются с цепочкой включений

Пример: Многоклиентская юридическая настройка

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },
  
  // Общие настройки агентов по умолчанию
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" }
    },
    // Слияние списков агентов от всех клиентов
    list: { "$include": [
      "./clients/mueller/agents.json5",
      "./clients/schmidt/agents.json5"
    ]}
  },
  
  // Слияние конфигураций broadcast
  broadcast: { "$include": [
    "./clients/mueller/broadcast.json5",
    "./clients/schmidt/broadcast.json5"
  ]},
  
  channels: { whatsapp: { groupPolicy: "allowlist" } }
}

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" }
]

// ~/.openclaw/clients/mueller/broadcast.json5
{
  "[email protected]": ["mueller-transcribe", "mueller-docs"]
}

Общие опции

Переменные окружения + .env

OpenClaw читает переменные окружения из родительского процесса (shell, launchd/systemd, CI и т.д.).

Дополнительно он загружает:

  • .env из текущего рабочего каталога (если присутствует)
  • глобальный запасной .env из ~/.openclaw/.env (также известный как $OPENCLAW_STATE_DIR/.env)

Ни один файл .env не переопределяет существующие переменные окружения.

Вы также можете предоставить встроенные переменные окружения в конфигурации. Они применяются только если переменная окружения процесса отсутствует (то же правило без переопределения):

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-..."
    }
  }
}

См. /environment для полного приоритета и источников.

env.shellEnv (опционально)

Удобство с опцией включения: если включено и ни один из ожидаемых ключей еще не установлен, OpenClaw запускает ваш login shell и импортирует только отсутствующие ожидаемые ключи (никогда не переопределяет). Это фактически загружает ваш профиль shell.

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000
    }
  }
}

Эквивалент переменной окружения:

  • OPENCLAW_LOAD_SHELL_ENV=1
  • OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

Подстановка переменных окружения в конфигурации

Вы можете ссылаться на переменные окружения непосредственно в любом строковом значении конфигурации, используя синтаксис $\{VAR_NAME\}. Переменные подставляются во время загрузки конфигурации, перед валидацией.

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}"
      }
    }
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}"
    }
  }
}

Правила:

  • Сопоставляются только имена переменных окружения в верхнем регистре: [A-Z_][A-Z0-9_]*
  • Отсутствующие или пустые переменные окружения вызывают ошибку при загрузке конфигурации
  • Экранируйте с $$\{VAR\} для вывода литерала $\{VAR\}
  • Работает с $include (включенные файлы также получают подстановку)

Встроенная подстановка:

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1"  // → "https://api.example.com/v1"
      }
    }
  }
}

Хранилище аутентификации (OAuth + API ключи)

OpenClaw хранит профили аутентификации для каждого агента (OAuth + API ключи) в:

  • <agentDir>/auth-profiles.json (по умолчанию: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json)

См. также: /concepts/oauth

Импорт legacy OAuth:

  • ~/.openclaw/credentials/oauth.json (или $OPENCLAW_STATE_DIR/credentials/oauth.json)

Встроенный агент Pi поддерживает кеш во время выполнения в:

  • <agentDir>/auth.json (управляется автоматически; не редактируйте вручную)

Legacy каталог агента (до мультиагента):

  • ~/.openclaw/agent/* (мигрирован openclaw doctor в ~/.openclaw/agents/<defaultAgentId>/agent/*)

Переопределения:

  • Каталог OAuth (только импорт legacy): OPENCLAW_OAUTH_DIR
  • Каталог агента (переопределение корня агента по умолчанию): OPENCLAW_AGENT_DIR (предпочтительно), PI_CODING_AGENT_DIR (legacy)

При первом использовании OpenClaw импортирует записи oauth.json в auth-profiles.json.

auth

Опциональные метаданные для профилей аутентификации. Это не хранит секреты; он сопоставляет идентификаторы профилей с провайдером + режимом (и опциональным email) и определяет порядок ротации провайдера, используемый для failover.

{
  auth: {
    profiles: {
      "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" }
    },
    order: {
      anthropic: ["anthropic:[email protected]", "anthropic:work"]
    }
  }
}

agents.list[].identity

Опциональная идентичность для каждого агента, используемая для настроек по умолчанию и UX. Это записывается помощником onboarding macOS.

Если установлено, OpenClaw выводит настройки по умолчанию (только когда вы не установили их явно):

  • messages.ackReaction из identity.emoji активного агента (откат к 👀)
  • agents.list[].groupChat.mentionPatterns из identity.name/identity.emoji агента (так что "@Samantha" работает в группах через Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp)
  • identity.avatar принимает путь к изображению относительно рабочего пространства или удаленный URL/data URL. Локальные файлы должны находиться внутри рабочего пространства агента.

identity.avatar принимает:

  • Путь относительно рабочего пространства (должен оставаться внутри рабочего пространства агента)
  • http(s) URL
  • data: URI
{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png"
        }
      }
    ]
  }
}

wizard

Метаданные, записываемые CLI wizard'ами (onboard, configure, doctor).

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local"
  }
}

logging

  • Лог-файл по умолчанию: /tmp/openclaw/openclaw-YYYY-MM-DD.log
  • Если вы хотите стабильный путь, установите logging.file на /tmp/openclaw/openclaw.log.
  • Вывод в консоль можно настроить отдельно через:
    • logging.consoleLevel (по умолчанию info, повышается до debug при --verbose)
    • logging.consoleStyle (pretty | compact | json)
  • Сводки инструментов могут быть отредактированы для предотвращения утечки секретов:
    • logging.redactSensitive (off | tools, по умолчанию: tools)
    • logging.redactPatterns (массив строк regex; переопределяет настройки по умолчанию)
{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // Пример: переопределите настройки по умолчанию своими правилами.
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi"
    ]
  }
}

channels.whatsapp.dmPolicy

Управляет обработкой прямых чатов WhatsApp (DM):

  • "pairing" (по умолчанию): неизвестные отправители получают код сопряжения; владелец должен одобрить
  • "allowlist": разрешать только отправителей из channels.whatsapp.allowFrom (или paired allow store)
  • "open": разрешать все входящие DM (требует channels.whatsapp.allowFrom включать "*")
  • "disabled": игнорировать все входящие DM

Коды сопряжения истекают через 1 час; бот отправляет код сопряжения только при создании нового запроса. Ожидающие запросы сопряжения DM ограничены 3 на канал по умолчанию.

Одобрения сопряжения:

  • openclaw pairing list whatsapp
  • openclaw pairing approve whatsapp <code>

channels.whatsapp.allowFrom

Список разрешений номеров телефонов E.164, которые могут вызывать автоответы WhatsApp (только DM). Если пусто и channels.whatsapp.dmPolicy="pairing", неизвестные отправители получат код сопряжения. Для групп используйте channels.whatsapp.groupPolicy + channels.whatsapp.groupAllowFrom.

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // опциональный размер исходящего чанка (символы)
      chunkMode: "length", // опциональный режим чанков (length | newline)
      mediaMaxMb: 50 // опциональный предел входящих медиа (MB)
    }
  }
}

channels.whatsapp.sendReadReceipts

Управляет тем, помечаются ли входящие сообщения WhatsApp как прочитанные (синие галочки). По умолчанию: true.

Режим самочата всегда пропускает подтверждения прочтения, даже когда включено.

Переопределение для каждого аккаунта: channels.whatsapp.accounts.<id>.sendReadReceipts.

{
  channels: {
    whatsapp: { sendReadReceipts: false }
  }
}

channels.whatsapp.accounts (мультиаккаунт)

Запустите несколько аккаунтов WhatsApp в одном gateway:

{
  channels: {
    whatsapp: {
      accounts: {
        default: {}, // опционально; сохраняет стабильный id по умолчанию
        personal: {},
        biz: {
          // Опциональное переопределение. По умолчанию: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        }
      }
    }
  }
}

Примечания:

  • Исходящие команды по умолчанию используют аккаунт default, если присутствует; в противном случае первый настроенный id аккаунта (отсортированный).
  • Legacy каталог аутентификации single-account Baileys мигрируется openclaw doctor в whatsapp/default.

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts

Запустите несколько аккаунтов для каждого канала (каждый аккаунт имеет свой accountId и опциональное name):

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC..."
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ..."
        }
      }
    }
  }
}

Примечания:

  • default используется, когда accountId опущен (CLI + маршрутизация).
  • Токены окружения применяются только к аккаунту default.
  • Базовые настройки канала (политика группы, контроль упоминаний и т.д.) применяются ко всем аккаунтам, если не переопределено для каждого аккаунта.
  • Используйте bindings[].match.accountId для маршрутизации каждого аккаунта к разным agents.defaults.

Контроль упоминаний в групповых чатах (agents.list[].groupChat + messages.groupChat)

Групповые сообщения по умолчанию требуют упоминания (либо упоминание в метаданных, либо regex паттерны). Применяется к групповым чатам WhatsApp, Telegram, Discord, Google Chat и iMessage.

Типы упоминаний:

  • Упоминания в метаданных: Нативные @-упоминания платформы (например, tap-to-mention в WhatsApp). Игнорируются в режиме самочата WhatsApp (см. channels.whatsapp.allowFrom).
  • Текстовые паттерны: Regex паттерны, определенные в agents.list[].groupChat.mentionPatterns. Всегда проверяются независимо от режима самочата.
  • Контроль упоминаний применяется только когда обнаружение упоминаний возможно (нативные упоминания или хотя бы один mentionPattern).
{
  messages: {
    groupChat: { historyLimit: 50 }
  },
  agents: {
    list: [
      { id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }
    ]
  }
}

messages.groupChat.historyLimit устанавливает глобальное значение по умолчанию для контекста истории группы. Каналы могут переопределить с channels.<channel>.historyLimit (или channels.<channel>.accounts.*.historyLimit для мультиаккаунта). Установите 0 для отключения обертывания истории.

Лимиты истории DM

DM разговоры используют историю на основе сессий, управляемую агентом. Вы можете ограничить количество пользовательских ходов, сохраняемых для каждой DM сессии:

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,  // ограничить DM сессии до 30 пользовательских ходов
      dms: {
        "123456789": { historyLimit: 50 }  // переопределение для каждого пользователя (ID пользователя)
      }
    }
  }
}

Порядок разрешения:

  1. Переопределение для каждого DM: channels.<provider>.dms[userId].historyLimit
  2. Значение по умолчанию для провайдера: channels.<provider>.dmHistoryLimit
  3. Без ограничений (вся история сохраняется)

Поддерживаемые провайдеры: telegram, whatsapp, discord, slack, signal, imessage, msteams.

Переопределение для каждого агента (имеет приоритет при установке, даже []):

{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } }
    ]
  }
}

Настройки контроля упоминаний по умолчанию живут для каждого канала (channels.whatsapp.groups, channels.telegram.groups, channels.imessage.groups, channels.discord.guilds). Когда установлен *.groups, он также действует как список разрешений группы; включите "*" для разрешения всех групп.

Чтобы отвечать только на определенные текстовые триггеры (игнорируя нативные @-упоминания):

{
  channels: {
    whatsapp: {
      // Включите свой собственный номер для включения режима самочата (игнорировать нативные @-упоминания).
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } }
    }
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // Только эти текстовые паттерны будут вызывать ответы
          mentionPatterns: ["reisponde", "@openclaw"]
        }
      }
    ]
  }
}

Политика группы (для каждого канала)

Используйте channels.*.groupPolicy для контроля того, принимаются ли сообщения группы/комнаты вообще:

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"]
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"]
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123"]
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"]
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        "GUILD_ID": {
          channels: { help: { allow: true } }
        }
      }
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } }
    }
  }
}

Примечания:

  • "open": группы обходят списки разрешений; контроль упоминаний все еще применяется.
  • "disabled": блокировать все сообщения группы/комнаты.
  • "allowlist": разрешать только группы/комнаты, соответствующие настроенному списку разрешений.
  • channels.defaults.groupPolicy устанавливает значение по умолчанию, когда groupPolicy провайдера не установлен.
  • WhatsApp/Telegram/Signal/iMessage/Microsoft Teams используют groupAllowFrom (откат: явный allowFrom).
  • Discord/Slack используют списки разрешений каналов (channels.discord.guilds.*.channels, channels.slack.channels).
  • Групповые DM (Discord/Slack) все еще контролируются dm.groupEnabled + dm.groupChannels.
  • По умолчанию groupPolicy: "allowlist" (если не переопределено channels.defaults.groupPolicy); если список разрешений не настроен, групповые сообщения блокируются.

Маршрутизация мультиагента (agents.list + bindings)

Запустите несколько изолированных агентов (отдельное рабочее пространство, agentDir, сессии) внутри одного Gateway. Входящие сообщения маршрутизируются к агенту через bindings.

  • agents.list[]: переопределения для каждого агента.
    • id: стабильный id агента (обязательно).
    • default: опционально; когда установлено несколько, побеждает первый и записывается предупреждение. Если ничего не установлено, первая запись в списке является агентом по умолчанию.
    • name: отображаемое имя для агента.
    • workspace: по умолчанию ~/.openclaw/workspace-<agentId> (для main, откат к agents.defaults.workspace).
    • agentDir: по умолчанию ~/.openclaw/agents/<agentId>/agent.
    • model: модель по умолчанию для каждого агента, переопределяет agents.defaults.model для этого агента.
      • строковая форма: "provider/model", переопределяет только agents.defaults.model.primary
      • форма объекта: \{ primary, fallbacks \} (fallbacks переопределяют agents.defaults.model.fallbacks; [] отключает глобальные fallbacks для этого агента)
    • identity: имя/тема/emoji для каждого агента (используется для паттернов упоминаний + ack реакций).
    • groupChat: контроль упоминаний для каждого агента (mentionPatterns).
    • sandbox: конфигурация sandbox для каждого агента (переопределяет agents.defaults.sandbox).
      • mode: "off" | "non-main" | "all"
      • workspaceAccess: "none" | "ro" | "rw"
      • scope: "session" | "agent" | "shared"
      • workspaceRoot: пользовательский корень рабочего пространства sandbox
      • docker: переопределения docker для каждого агента (например image, network, env, setupCommand, лимиты; игнорируются при scope: "shared")
      • browser: переопределения sandbox браузера для каждого агента (игнорируются при scope: "shared")
      • prune: переопределения очистки sandbox для каждого агента (игнорируются при scope: "shared")
    • subagents: настройки sub-agent по умолчанию для каждого агента.
      • allowAgents: список разрешений id агентов для sessions_spawn от этого агента (["*"] = разрешить любой; по умолчанию: только тот же агент)
    • tools: ограничения инструментов для каждого агента (применяются перед политикой инструментов sandbox).
      • profile: базовый профиль инструментов (применяется перед allow/deny)
      • allow: массив разрешенных имен инструментов
      • deny: массив запрещенных имен инструментов (deny выигрывает)
  • agents.defaults: общие настройки агентов по умолчанию (модель, рабочее пространство, sandbox и т.д.).
  • bindings[]: маршрутизирует входящие сообщения к agentId.
    • match.channel (обязательно)
    • match.accountId (опционально; * = любой аккаунт; опущено = аккаунт по умолчанию)
    • match.peer (опционально; \{ kind: dm|group|channel, id \})
    • match.guildId / match.teamId (опционально; специфично для канала)

Детерминированный порядок совпадений:

  1. match.peer
  2. match.guildId
  3. match.teamId
  4. match.accountId (точное, без peer/guild/team)
  5. match.accountId: "*" (на всем канале, без peer/guild/team)
  6. агент по умолчанию (agents.list[].default, иначе первая запись списка, иначе "main")

В пределах каждого уровня совпадения побеждает первая совпадающая запись в bindings.

Профили доступа для каждого агента (мультиагент)

Каждый агент может иметь свою собственную политику sandbox + инструментов. Используйте это для смешивания уровней доступа в одном gateway:

  • Полный доступ (личный агент)
  • Инструменты только для чтения + рабочее пространство
  • Без доступа к файловой системе (только инструменты обмена сообщениями/сессий)

См. Multi-Agent Sandbox & Tools для приоритета и дополнительных примеров.

Полный доступ (без sandbox):

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

Пример: два аккаунта WhatsApp → два агента:

{
  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" } }
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {},
      }
    }
  }
}

tools.agentToAgent (опционально)

Обмен сообщениями между агентами opt-in:

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"]
    }
  }
}

messages.queue

Управляет поведением входящих сообщений, когда выполнение агента уже активно.

{
  messages: {
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog (steer+backlog ok) | interrupt (queue=steer legacy)
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        imessage: "collect",
        webchat: "collect"
      }
    }
  }
}

messages.inbound

Отскок быстрых входящих сообщений от того же отправителя, чтобы несколько последовательных сообщений стали одним ходом агента. Отскок ограничен каналом + разговором и использует самое последнее сообщение для threading/ID ответа.

{
  messages: {
    inbound: {
      debounceMs: 2000, // 0 отключает
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500
      }
    }
  }
}

Примечания:

  • Отскок батчит только текстовые сообщения; медиа/вложения сбрасываются немедленно.
  • Контрольные команды (например /queue, /new) обходят отскок, поэтому они остаются автономными.

commands (обработка команд чата)

Управляет тем, как команды чата включены в коннекторах.

{
  commands: {
    native: "auto",         // регистрировать нативные команды при поддержке (auto)
    text: true,             // парсить slash команды в сообщениях чата
    bash: false,            // разрешить ! (псевдоним: /bash) (только хост; требует tools.elevated allowlists)
    bashForegroundMs: 2000, // окно переднего плана bash (0 сразу фонирует)
    config: false,          // разрешить /config (записывает на диск)
    debug: false,           // разрешить /debug (переопределения только во время выполнения)
    restart: false,         // разрешить /restart + инструмент restart gateway
    useAccessGroups: true   // применять списки разрешений/политики access-group для команд
  }
}

Примечания:

  • Текстовые команды должны быть отправлены как отдельное сообщение и использовать ведущий / (без псевдонимов в простом тексте).
  • commands.text: false отключает парсинг сообщений чата для команд.
  • commands.native: "auto" (по умолчанию) включает нативные команды для Discord/Telegram и оставляет Slack отключенным; неподдерживаемые каналы остаются только текстовыми.
  • Установите commands.native: true|false для принудительного включения всех, или переопределите для каждого канала с channels.discord.commands.native, channels.telegram.commands.native, channels.slack.commands.native (bool или "auto"). false очищает ранее зарегистрированные команды на Discord/Telegram при запуске; команды Slack управляются в приложении Slack.
  • channels.telegram.customCommands добавляет дополнительные записи меню бота Telegram. Имена нормализуются; конфликты с нативными командами игнорируются.
  • commands.bash: true включает ! <cmd> для запуска команд host shell (/bash <cmd> также работает как псевдоним). Требует tools.elevated.enabled и внесения отправителя в список разрешений в tools.elevated.allowFrom.<channel>.
  • commands.bashForegroundMs контролирует, как долго bash ждет перед фонированием. Пока bash задание выполняется, новые запросы ! <cmd> отклоняются (один за раз).
  • commands.config: true включает /config (читает/записывает openclaw.json).
  • channels.<provider>.configWrites контролирует мутации конфигурации, инициированные этим каналом (по умолчанию: true). Это применяется к /config set|unset плюс автомиграции специфичные для провайдера (изменения ID supergroup Telegram, изменения ID канала Slack).
  • commands.debug: true включает /debug (переопределения только во время выполнения).
  • commands.restart: true включает /restart и действие restart инструмента gateway.
  • commands.useAccessGroups: false позволяет командам обходить списки разрешений/политики access-group.
  • Slash команды и директивы соблюдаются только для авторизованных отправителей. Авторизация выводится из списков разрешений/сопряжения каналов плюс commands.useAccessGroups.

web (среда выполнения веб-канала WhatsApp)

WhatsApp работает через веб-канал gateway (Baileys Web). Он запускается автоматически, когда существует связанная сессия. Установите web.enabled: false чтобы держать его выключенным по умолчанию.

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0
    }
  }
}

channels.telegram (bot транспорт)

OpenClaw запускает Telegram только когда существует раздел конфигурации channels.telegram. Токен бота разрешается из channels.telegram.botToken (или channels.telegram.tokenFile), с TELEGRAM_BOT_TOKEN как откат для аккаунта по умолчанию. Установите channels.telegram.enabled: false для отключения автоматического запуска. Поддержка мультиаккаунта живет под channels.telegram.accounts (см. раздел мультиаккаунта выше). Токены окружения применяются только к аккаунту по умолчанию. Установите channels.telegram.configWrites: false для блокировки записей конфигурации, инициированных Telegram (включая миграции ID supergroup и /config set|unset).

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",                 // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"],         // опционально; "open" требует ["*"]
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic."
            }
          }
        }
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" }
      ],
      historyLimit: 50,                     // включить последние N групповых сообщений как контекст (0 отключает)
      replyToMode: "first",                 // off | first | all
      linkPreview: true,                   // переключить исходящие превью ссылок
      streamMode: "partial",               // off | partial | block (черновик стриминга; отдельно от блочного стриминга)
      draftChunk: {                        // опционально; только для streamMode=block
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph"       // paragraph | newline | sentence
      },
      actions: { reactions: true, sendMessage: true }, // контроль действий инструмента (false отключает)
      reactionNotifications: "own",   // off | own | all
      mediaMaxMb: 5,
      retry: {                             // политика повтора исходящих
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1
      },
      network: {                           // переопределения транспорта
        autoSelectFamily: false
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook"
    }
  }
}

Примечания черновика стриминга:

  • Использует Telegram sendMessageDraft (пузырь черновика, не реальное сообщение).
  • Требует приватные темы чата (message_thread_id в DM; у бота включены темы).
  • /reasoning stream стримит reasoning в черновик, затем отправляет финальный ответ. Настройки по умолчанию политики повтора и поведение задокументированы в Retry policy.

channels.discord (bot транспорт)

Настройте Discord бота, установив токен бота и опциональный контроль: Поддержка мультиаккаунта живет под channels.discord.accounts (см. раздел мультиаккаунта выше). Токены окружения применяются только к аккаунту по умолчанию.

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,                          // ограничить размер входящих медиа
      allowBots: false,                       // разрешить сообщения, созданные ботом
      actions: {                              // контроль действий инструмента (false отключает)
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false
      },
      replyToMode: "off",                     // off | first | all
      dm: {
        enabled: true,                        // отключить все DM при false
        policy: "pairing",                    // pairing | allowlist | open | disabled
        allowFrom: ["1234567890", "steipete"], // опциональный список разрешений DM ("open" требует ["*"])
        groupEnabled: false,                 // включить групповые DM
        groupChannels: ["openclaw-dm"]          // опциональный список разрешений групповых DM
      },
      guilds: {
        "123456789012345678": {               // id гильдии (предпочтительно) или slug
          slug: "friends-of-openclaw",
          requireMention: false,              // значение по умолчанию для гильдии
          reactionNotifications: "own",       // off | own | all | allowlist
          users: ["987654321098765432"],      // опциональный список разрешений пользователей для гильдии
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only."
            }
          }
        }
      },
      historyLimit: 20,                       // включить последние N сообщений гильдии как контекст
      textChunkLimit: 2000,                   // опциональный размер исходящего текстового чанка (символы)
      chunkMode: "length",                    // опциональный режим чанков (length | newline)
      maxLinesPerMessage: 17,                 // мягкий максимум строк на сообщение (обрезка UI Discord)
      retry: {                                // политика повтора исходящих
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1
      }
    }
  }
}

OpenClaw запускает Discord только когда существует раздел конфигурации channels.discord. Токен разрешается из channels.discord.token, с DISCORD_BOT_TOKEN как откат для аккаунта по умолчанию (если channels.discord.enabled не false). Используйте user:<id> (DM) или channel:<id> (канал гильдии) при указании целей доставки для cron/CLI команд; голые числовые ID неоднозначны и отклоняются. Guild slugs в нижнем регистре с пробелами, замененными на -; ключи каналов используют slug имя канала (без ведущего #). Предпочитайте id гильдии в качестве ключей, чтобы избежать неоднозначности переименования. Сообщения, созданные ботом, игнорируются по умолчанию. Включите с channels.discord.allowBots (собственные сообщения все еще фильтруются для предотвращения циклов self-reply). Режимы уведомлений реакций:

  • off: нет событий реакций.
  • own: реакции на собственные сообщения бота (по умолчанию).
  • all: все реакции на все сообщения.
  • allowlist: реакции от guilds.<id>.users на все сообщения (пустой список отключает). Исходящий текст чанкируется по channels.discord.textChunkLimit (по умолчанию 2000). Установите channels.discord.chunkMode="newline" для разделения по пустым строкам (границы параграфов) перед length чанкингом. Клиенты Discord могут обрезать очень высокие сообщения, поэтому channels.discord.maxLinesPerMessage (по умолчанию 17) разделяет длинные многострочные ответы, даже когда под 2000 символов. Настройки по умолчанию политики повтора и поведение задокументированы в Retry policy.

channels.googlechat (вебхук Chat API)

Google Chat работает через HTTP вебхуки с аутентификацией на уровне приложения (service account). Поддержка мультиаккаунта живет под channels.googlechat.accounts (см. раздел мультиаккаунта выше). Переменные окружения применяются только к аккаунту по умолчанию.

{
  channels: {
    "googlechat": {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url",             // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",        // опционально; улучшает обнаружение упоминаний
      dm: {
        enabled: true,
        policy: "pairing",                // pairing | allowlist | open | disabled
        allowFrom: ["users/1234567890"]   // опционально; "open" требует ["*"]
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true }
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20
    }
  }
}

Примечания:

  • Service account JSON может быть встроенным (serviceAccount) или файловым (serviceAccountFile).
  • Откаты окружения для аккаунта по умолчанию: GOOGLE_CHAT_SERVICE_ACCOUNT или GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
  • audienceType + audience должны соответствовать конфигурации аутентификации вебхука приложения Chat.
  • Используйте spaces/<spaceId> или users/<userId|email> при установке целей доставки.

channels.slack (socket mode)

Slack работает в Socket Mode и требует как токен бота, так и токен приложения:

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["U123", "U456", "*"], // опционально; "open" требует ["*"]
        groupEnabled: false,
        groupChannels: ["G123"]
      },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only."
        }
      },
      historyLimit: 50,          // включить последние N сообщений канала/группы как контекст (0 отключает)
      allowBots: false,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["U123"],
      replyToMode: "off",           // off | first | all
      thread: {
        historyScope: "thread",     // thread | channel
        inheritParent: false
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true
      },
      textChunkLimit: 4000,
      chunkMode: "length",
      mediaMaxMb: 20
    }
  }
}

Поддержка мультиаккаунта живет под channels.slack.accounts (см. раздел мультиаккаунта выше). Токены окружения применяются только к аккаунту по умолчанию.

OpenClaw запускает Slack когда провайдер включен и оба токена установлены (через конфигурацию или SLACK_BOT_TOKEN + SLACK_APP_TOKEN). Используйте user:<id> (DM) или channel:<id> при указании целей доставки для cron/CLI команд. Установите channels.slack.configWrites: false для блокировки записей конфигурации, инициированных Slack (включая миграции ID канала и /config set|unset).

Сообщения, созданные ботом, игнорируются по умолчанию. Включите с channels.slack.allowBots или channels.slack.channels.<id>.allowBots.

Режимы уведомлений реакций:

  • off: нет событий реакций.
  • own: реакции на собственные сообщения бота (по умолчанию).
  • all: все реакции на все сообщения.
  • allowlist: реакции от channels.slack.reactionAllowlist на все сообщения (пустой список отключает).

Изоляция сессий потоков:

  • channels.slack.thread.historyScope контролирует, является ли история потока для каждого потока (thread, по умолчанию) или общая по всему каналу (channel).
  • channels.slack.thread.inheritParent контролирует, наследуют ли новые сессии потоков транскрипт родительского канала (по умолчанию: false).

Группы действий Slack (контроль действий инструмента slack):

Группа действийПо умолчаниюПримечания
reactionsвключеноРеагировать + список реакций
messagesвключеноЧитать/отправлять/редактировать/удалять
pinsвключеноЗакреплять/открепить/список
memberInfoвключеноИнформация о членах
emojiListвключеноСписок пользовательских emoji

channels.mattermost (токен бота)

Mattermost поставляется как плагин и не входит в основную установку. Сначала установите его: openclaw plugins install @openclaw/mattermost (или ./extensions/mattermost из git checkout).

Mattermost требует токен бота плюс базовый URL для вашего сервера:

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      textChunkLimit: 4000,
      chunkMode: "length"
    }
  }
}

OpenClaw запускает Mattermost когда аккаунт настроен (токен бота + базовый URL) и включен. Токен + базовый URL разрешаются из channels.mattermost.botToken + channels.mattermost.baseUrl или MATTERMOST_BOT_TOKEN + MATTERMOST_URL для аккаунта по умолчанию (если channels.mattermost.enabled не false).

Режимы чата:

  • oncall (по умолчанию): отвечать на сообщения канала только при @упоминании.
  • onmessage: отвечать на каждое сообщение канала.
  • onchar: отвечать, когда сообщение начинается с префикса триггера (channels.mattermost.oncharPrefixes, по умолчанию [">", "!"]).

Контроль доступа:

  • DM по умолчанию: channels.mattermost.dmPolicy="pairing" (неизвестные отправители получают код сопряжения).
  • Публичные DM: channels.mattermost.dmPolicy="open" плюс channels.mattermost.allowFrom=["*"].
  • Группы: channels.mattermost.groupPolicy="allowlist" по умолчанию (контроль упоминаний). Используйте channels.mattermost.groupAllowFrom для ограничения отправителей.

Поддержка мультиаккаунта живет под channels.mattermost.accounts (см. раздел мультиаккаунта выше). Переменные окружения применяются только к аккаунту по умолчанию. Используйте channel:<id> или user:<id> (или @username) при указании целей доставки; голые id обрабатываются как id каналов.

channels.signal (signal-cli)

Реакции Signal могут вызывать системные события (общая инструментальная система реакций):

{
  channels: {
    signal: {
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50 // включить последние N групповых сообщений как контекст (0 отключает)
    }
  }
}

Режимы уведомлений реакций:

  • off: нет событий реакций.
  • own: реакции на собственные сообщения бота (по умолчанию).
  • all: все реакции на все сообщения.
  • allowlist: реакции от channels.signal.reactionAllowlist на все сообщения (пустой список отключает).

channels.imessage (imsg CLI)

OpenClaw порождает imsg rpc (JSON-RPC через stdio). Не требуется демон или порт.

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host", // SCP для удаленных вложений при использовании обертки SSH
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50,    // включить последние N групповых сообщений как контекст (0 отключает)
      includeAttachments: false,
      mediaMaxMb: 16,
      service: "auto",
      region: "US"
    }
  }
}

Поддержка мультиаккаунта живет под channels.imessage.accounts (см. раздел мультиаккаунта выше).

Примечания:

  • Требуется Full Disk Access к Messages DB.
  • Первая отправка запросит разрешение автоматизации Messages.
  • Предпочитайте цели chat_id:<id>. Используйте imsg chats --limit 20 для списка чатов.
  • channels.imessage.cliPath может указывать на скрипт-обертку (например ssh на другой Mac, который запускает imsg rpc); используйте SSH ключи, чтобы избежать запросов пароля.
  • Для удаленных оберток SSH установите channels.imessage.remoteHost для получения вложений через SCP, когда includeAttachments включен.

Пример обертки:

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

agents.defaults.workspace

Устанавливает единое глобальное рабочее пространство, используемое агентом для операций с файлами.

По умолчанию: ~/.openclaw/workspace.

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

Если agents.defaults.sandbox включен, сессии не-main могут переопределить это своими собственными рабочими пространствами для каждой области под agents.defaults.sandbox.workspaceRoot.

agents.defaults.repoRoot

Опциональный корень репозитория для отображения в строке Runtime системного промпта. Если не установлено, OpenClaw пытается обнаружить каталог .git, проходя вверх от рабочего пространства (и текущего рабочего каталога). Путь должен существовать для использования.

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

agents.defaults.skipBootstrap

Отключает автоматическое создание файлов bootstrap рабочего пространства (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md и BOOTSTRAP.md).

Используйте это для предварительно заполненных развертываний, где файлы рабочего пространства поступают из репозитория.

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

agents.defaults.bootstrapMaxChars

Максимум символов каждого файла bootstrap рабочего пространства, вставленного в системный промпт перед усечением. По умолчанию: 20000.

Когда файл превышает этот лимит, OpenClaw записывает предупреждение и вставляет усеченные head/tail с маркером.

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

agents.defaults.userTimezone

Устанавливает часовой пояс пользователя для контекста системного промпта (не для временных меток в конвертах сообщений). Если не установлено, OpenClaw использует часовой пояс хоста во время выполнения.

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

agents.defaults.timeFormat

Управляет форматом времени, показанным в разделе Current Date & Time системного промпта. По умолчанию: auto (предпочтение ОС).

{
  agents: { defaults: { timeFormat: "auto" } } // auto | 12 | 24
}

messages

Управляет входящими/исходящими префиксами и опциональными ack реакциями. См. Messages для очередей, сессий и контекста стриминга.

{
  messages: {
    responsePrefix: "🦞", // или "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false
  }
}

responsePrefix применяется ко всем исходящим ответам (сводки инструментов, блок стриминга, финальные ответы) через каналы, если уже не присутствует.

Если messages.responsePrefix не установлен, префикс не применяется по умолчанию. Ответы самочата WhatsApp являются исключением: они по умолчанию используют [\{identity.name\}] когда установлено, иначе [openclaw], чтобы разговоры на одном телефоне оставались читаемыми. Установите его в "auto" для вывода [\{identity.name\}] для маршрутизируемого агента (когда установлено).

Переменные шаблона

Строка responsePrefix может включать переменные шаблона, которые разрешаются динамически:

ПеременнаяОписаниеПример
\{model\}Короткое имя моделиclaude-opus-4-5, gpt-4o
\{modelFull\}Полный идентификатор моделиanthropic/claude-opus-4-5
\{provider\}Имя провайдераanthropic, openai
\{thinkingLevel\}Текущий уровень мышленияhigh, low, off
\{identity.name\}Имя идентичности агента(то же, что режим "auto")

Переменные не чувствительны к регистру (\{MODEL\} = \{model\}). \{think\} является псевдонимом для \{thinkingLevel\}. Неразрешенные переменные остаются как буквальный текст.

{
  messages: {
    responsePrefix: "[\{model\} | think:\{thinkingLevel\}]"
  }
}

Пример вывода: [claude-opus-4-5 | think:high] Here's my response...

Входящий префикс WhatsApp настраивается через channels.whatsapp.messagePrefix (устарело: messages.messagePrefix). По умолчанию остается неизменным: "[openclaw]" когда channels.whatsapp.allowFrom пусто, иначе "" (без префикса). При использовании "[openclaw]", OpenClaw вместо этого использует [\{identity.name\}] когда у маршрутизируемого агента установлен identity.name.

ackReaction отправляет emoji реакцию best-effort для подтверждения входящих сообщений на каналах, поддерживающих реакции (Slack/Discord/Telegram/Google Chat). По умолчанию использует identity.emoji активного агента когда установлено, иначе "👀". Установите в "" для отключения.

ackReactionScope контролирует, когда срабатывают реакции:

  • group-mentions (по умолчанию): только когда группа/комната требует упоминаний и бот был упомянут
  • group-all: все сообщения группы/комнаты
  • direct: только прямые сообщения
  • all: все сообщения

removeAckAfterReply удаляет ack реакцию бота после отправки ответа (только Slack/Discord/Telegram/Google Chat). По умолчанию: false.

messages.tts

Настройки TTS (Text-to-Speech). См. TTS для подробностей.

← Назад к документации