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.
tools.* ключі конфігурації та налаштування власного провайдера / базової URL-адреси. Для агентів, каналів та інших ключів конфігурації верхнього рівня див. довідник конфігурації.
Інструменти
Профілі інструментів
tools.profile задає базовий список дозволеного перед tools.allow/tools.deny:
Локальне початкове налаштування за замовчуванням встановлює для нових локальних конфігурацій
tools.profile: "coding", якщо його не задано (наявні явно задані профілі зберігаються).| Профіль | Містить |
|---|---|
minimal | лише session_status |
coding | group:fs, group:runtime, group:web, group:sessions, group:memory, cron, image, image_generate, video_generate |
messaging | group:messaging, sessions_list, sessions_history, sessions_send, session_status |
full | Без обмежень (те саме, що й не задано) |
Групи інструментів
| Група | Інструменти |
|---|---|
group:runtime | exec, process, code_execution (bash приймається як псевдонім для exec) |
group:fs | read, write, edit, apply_patch |
group:sessions | sessions_list, sessions_history, sessions_send, sessions_spawn, sessions_yield, subagents, session_status |
group:memory | memory_search, memory_get |
group:web | web_search, x_search, web_fetch |
group:ui | browser, canvas |
group:automation | heartbeat_respond, cron, gateway |
group:messaging | message |
group:nodes | nodes |
group:agents | agents_list, update_plan |
group:media | image, image_generate, music_generate, video_generate, tts |
group:openclaw | Усі вбудовані інструменти (не включає Plugin провайдерів) |
tools.allow / tools.deny
Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Не чутлива до регістру, підтримує символи-замінники *. Застосовується навіть тоді, коли пісочницю Docker вимкнено.
write і apply_patch — окремі ідентифікатори інструментів. allow: ["write"] також вмикає apply_patch для сумісних моделей, але deny: ["write"] не забороняє apply_patch. Щоб заблокувати всі зміни файлів, забороніть group:fs або явно перелічіть кожен інструмент, що вносить зміни:
tools.byProvider
Додатково обмежує інструменти для конкретних провайдерів або моделей. Порядок: базовий профіль → профіль провайдера → дозволити/заборонити.
tools.toolsBySender
Обмежує інструменти для конкретної ідентичності запитувача. Це додатковий рівень захисту поверх контролю доступу каналу; значення відправника мають надходити з адаптера каналу, а не з тексту повідомлення.
channel:<channelId>:<senderId>, id:<senderId>, e164:<phone>, username:<handle>, name:<displayName> або "*". Ідентифікатори каналів — канонічні ідентифікатори OpenClaw; псевдоніми на кшталт teams нормалізуються до msteams. Застарілі ключі без префікса приймаються лише як id:. Порядок зіставлення: channel+id, id, e164, username, name, потім символ-замінник.
agents.list[].tools.toolsBySender на рівні агента перевизначає глобальне зіставлення відправника, коли збігається, навіть із порожньою політикою {}.
tools.elevated
Керує підвищеним доступом exec поза пісочницею:
- Перевизначення на рівні агента (
agents.list[].tools.elevated) може лише додатково обмежувати. /elevated on|off|ask|fullзберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення.- Підвищений
execобходить пісочницю та використовує налаштований шлях виходу (gatewayза замовчуванням абоnode, коли цільexec—node).
tools.exec
tools.loopDetection
Перевірки безпеки циклів інструментів вимкнені за замовчуванням. Установіть enabled: true, щоб активувати виявлення. Налаштування можна визначити глобально в tools.loopDetection і перевизначити для кожного агента в agents.list[].tools.loopDetection.
Максимальна історія викликів інструментів, що зберігається для аналізу циклів.
Поріг повторюваного шаблону без прогресу для попереджень.
Вищий поріг повторення для блокування критичних циклів.
Поріг жорсткої зупинки для будь-якого виконання без прогресу.
Попереджати про повторні виклики того самого інструмента з тими самими аргументами.
Попереджати/блокувати відомі інструменти опитування (
process.poll, command_status тощо).Попереджати/блокувати почергові парні шаблони без прогресу.
tools.web
tools.media
Налаштовує розуміння вхідних медіа (зображення/аудіо/відео):
Поля запису медіамоделі
Поля запису медіамоделі
Запис провайдера (
type: "provider" або пропущено):provider: ідентифікатор API-провайдера (openai,anthropic,google/gemini,groqтощо)model: перевизначення ідентифікатора моделіprofile/preferredProfile: вибір профілюauth-profiles.json
type: "cli"):command: виконуваний файл для запускуargs: шаблонні аргументи (підтримує{{MediaPath}},{{Prompt}},{{MaxChars}}тощо;openclaw doctor --fixпереносить застарілі заповнювачі{input}до{{MediaPath}})
capabilities: необов’язковий список (image,audio,video). Значення за замовчуванням:openai/anthropic/minimax→ зображення,google→ зображення+аудіо+відео,groq→ аудіо.prompt,maxChars,maxBytes,timeoutSeconds,language: перевизначення для окремого запису.tools.media.image.timeoutSecondsі відповідні записиtimeoutSecondsмоделей зображень також застосовуються, коли агент викликає явний інструментimage.- У разі збоїв виконується перехід до наступного запису.
auth-profiles.json → змінні середовища → models.providers.*.apiKey.Поля асинхронного завершення:asyncCompletion.directSend: застарілий прапорець сумісності. Завершені асинхронні медіазавдання залишаються опосередкованими сеансом запитувача, щоб агент отримав результат, вирішив, як повідомити користувача, і використав інструмент повідомлень, коли цього вимагає доставлення з джерела.
tools.agentToAgent
tools.sessions
Керує тим, на які сеанси можуть націлюватися інструменти сеансів (sessions_list, sessions_history, sessions_send).
За замовчуванням: tree (поточний сеанс + сеанси, породжені ним, наприклад підагенти).
Області видимості
Області видимості
self: лише ключ поточного сеансу.tree: поточний сеанс + сеанси, породжені поточним сеансом (підагенти).agent: будь-який сеанс, що належить поточному ідентифікатору агента (може включати інших користувачів, якщо ви запускаєте сеанси для кожного відправника з тим самим ідентифікатором агента).all: будь-який сеанс. Націлювання між агентами все одно потребуєtools.agentToAgent.- Обмеження пісочниці: коли поточний сеанс ізольовано в пісочниці й
agents.defaults.sandbox.sessionToolsVisibility="spawned", видимість примусово встановлюється наtree, навіть якщоtools.sessions.visibility="all".
tools.sessions_spawn
Керує підтримкою вбудованих вкладень для sessions_spawn.
Примітки щодо вкладень
Примітки щодо вкладень
- Вкладення підтримуються лише для
runtime: "subagent". Середовище виконання ACP їх відхиляє. - Файли матеріалізуються в дочірній робочій області за шляхом
.openclaw/attachments/<uuid>/з файлом.manifest.json. - Вміст вкладень автоматично редагується збереженням транскрипту.
- Вхідні дані Base64 перевіряються суворими перевірками алфавіту/доповнення та захистом розміру перед декодуванням.
- Дозволи файлів:
0700для каталогів і0600для файлів. - Очищення відповідає політиці
cleanup:deleteзавжди видаляє вкладення;keepзберігає їх лише колиretainOnSessionKeep: true.
tools.experimental
Експериментальні прапорці вбудованих інструментів. Типово вимкнено, якщо не застосовується правило суворого агентного автоматичного ввімкнення GPT-5.
planTool: вмикає структурований інструментupdate_planдля відстеження нетривіальної багатоетапної роботи.- Типово:
false, якщоagents.defaults.embeddedPi.executionContract(або перевизначення для окремого агента) не встановлено в"strict-agentic"для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установітьtrue, щоб примусово ввімкнути інструмент поза цією областю, абоfalse, щоб залишити його вимкненим навіть для суворих агентних запусків GPT-5. - Коли ввімкнено, системний промпт також додає рекомендації з використання, щоб модель застосовувала його лише для суттєвої роботи й мала щонайбільше один крок
in_progress.
agents.defaults.subagents
model: типова модель для породжених субагентів. Якщо пропущено, субагенти успадковують модель викликача.allowAgents: типовий список дозволених ідентифікаторів цільових агентів дляsessions_spawn, коли агент-запитувач не задає власнийsubagents.allowAgents(["*"]= будь-який; типово: лише той самий агент).runTimeoutSeconds: типовий тайм-аут (у секундах) дляsessions_spawn, коли виклик інструмента пропускаєrunTimeoutSeconds.0означає без тайм-ауту.announceTimeoutMs: тайм-аут для кожного виклику (у мілісекундах) для спроб доставки оголошенняagentчерез Gateway. Типово:120000. Тимчасові повторні спроби можуть зробити загальне очікування оголошення довшим за один налаштований тайм-аут.- Політика інструментів для кожного субагента:
tools.subagents.tools.allow/tools.subagents.tools.deny.
Користувацькі провайдери та базові URL
OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів черезmodels.providers у конфігурації або ~/.openclaw/agents/<agentId>/agent/models.json.
Автентифікація та пріоритет злиття
Автентифікація та пріоритет злиття
- Використовуйте
authHeader: true+headersдля користувацьких потреб автентифікації. - Перевизначте корінь конфігурації агента за допомогою
OPENCLAW_AGENT_DIR(абоPI_CODING_AGENT_DIR, застарілого псевдоніма змінної середовища). - Пріоритет злиття для збіжних ідентифікаторів провайдерів:
- Непорожні значення
baseUrlз агентськогоmodels.jsonмають перевагу. - Непорожні значення
apiKeyагента мають перевагу лише коли цей провайдер не керується SecretRef у поточному контексті конфігурації/профілю автентифікації. - Значення
apiKeyпровайдера, керованого SecretRef, оновлюються з маркерів джерела (ENV_VAR_NAMEдля посилань на змінні середовища,secretref-managedдля посилань на файл/exec) замість збереження розв’язаних секретів. - Значення заголовків провайдера, керованого SecretRef, оновлюються з маркерів джерела (
secretref-env:ENV_VAR_NAMEдля посилань на змінні середовища,secretref-managedдля посилань на файл/exec). - Порожні або відсутні
apiKey/baseUrlагента повертаються доmodels.providersу конфігурації. - Збіжні
contextWindow/maxTokensмоделі використовують вище значення між явною конфігурацією та неявними значеннями каталогу. - Збіжний
contextTokensмоделі зберігає явне обмеження середовища виконання, коли воно є; використовуйте його, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. - Використовуйте
models.mode: "replace", коли потрібно, щоб конфігурація повністю перезаписувалаmodels.json. - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних секретних значень часу виконання.
- Непорожні значення
Деталі полів провайдера
Каталог верхнього рівня
Каталог верхнього рівня
models.mode: поведінка каталогу провайдерів (mergeабоreplace).models.providers: мапа користувацьких провайдерів, ключована ідентифікатором провайдера.- Безпечні редагування: використовуйте
openclaw config set models.providers.<id> '<json>' --strict-json --mergeабоopenclaw config set models.providers.<id>.models '<json-array>' --strict-json --mergeдля адитивних оновлень.config setвідмовляється від руйнівних замін, якщо не передати--replace.
- Безпечні редагування: використовуйте
Підключення провайдера та автентифікація
Підключення провайдера та автентифікація
models.providers.*.api: адаптер запитів (openai-completions,openai-responses,anthropic-messages,google-generative-aiтощо). Для самостійно розгорнутих бекендів/v1/chat/completions, таких як MLX, vLLM, SGLang і більшість локальних серверів, сумісних з OpenAI, використовуйтеopenai-completions. Користувацький провайдер ізbaseUrl, але безapi, типово використовуєopenai-completions; установлюйтеopenai-responsesлише коли бекенд підтримує/v1/responses.models.providers.*.apiKey: облікові дані провайдера (надавайте перевагу підстановці SecretRef/змінних середовища).models.providers.*.auth: стратегія автентифікації (api-key,token,oauth,aws-sdk).models.providers.*.contextWindow: типове нативне контекстне вікно для моделей цього провайдера, коли запис моделі не задаєcontextWindow.models.providers.*.contextTokens: типове ефективне обмеження контексту часу виконання для моделей цього провайдера, коли запис моделі не задаєcontextTokens.models.providers.*.maxTokens: типове обмеження вихідних токенів для моделей цього провайдера, коли запис моделі не задаєmaxTokens.models.providers.*.timeoutSeconds: необов’язковий тайм-аут HTTP-запиту моделі для кожного провайдера в секундах, включно з підключенням, заголовками, тілом і обробкою переривання всього запиту.models.providers.*.injectNumCtxForOpenAICompat: для Ollama +openai-completions, впроваджуватиoptions.num_ctxу запити (типово:true).models.providers.*.authHeader: примусово передавати облікові дані в заголовкуAuthorization, коли це потрібно.models.providers.*.baseUrl: базовий URL висхідного API.models.providers.*.headers: додаткові статичні заголовки для маршрутизації проксі/орендаря.
Перевизначення транспорту запитів
Перевизначення транспорту запитів
models.providers.*.request: перевизначення транспорту для HTTP-запитів провайдера моделей.request.headers: додаткові заголовки (об’єднуються з типовими значеннями провайдера). Значення приймають SecretRef.request.auth: перевизначення стратегії автентифікації. Режими:"provider-default"(використовувати вбудовану автентифікацію провайдера),"authorization-bearer"(зtoken),"header"(зheaderName,value, необов’язковимprefix).request.proxy: перевизначення HTTP-проксі. Режими:"env-proxy"(використовувати змінні середовищаHTTP_PROXY/HTTPS_PROXY),"explicit-proxy"(зurl). Обидва режими приймають необов’язковий підоб’єктtls.request.tls: перевизначення TLS для прямих підключень. Поля:ca,cert,key,passphrase(усі приймають SecretRef),serverName,insecureSkipVerify.request.allowPrivateNetwork: колиtrue, дозволяє HTTPS доbaseUrl, коли DNS розв’язується у приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (операторська явна згода для довірених самостійно розгорнутих кінцевих точок, сумісних з OpenAI). Потокові URL провайдера моделей local loopback, такі якlocalhost,127.0.0.1і[::1], дозволені автоматично, якщо це явно не встановлено вfalse; хости LAN, tailnet і приватного DNS усе ще потребують явної згоди. WebSocket використовує той самийrequestдля заголовків/TLS, але не цей SSRF-шлюз fetch. Типовоfalse.
Записи каталогу моделей
Записи каталогу моделей
models.providers.*.models: явні записи каталогу моделей провайдера.models.providers.*.models.*.input: модальності введення моделі. Використовуйте["text"]для моделей лише з текстом і["text", "image"]для нативних моделей із зображеннями/комп’ютерним зором. Вкладення зображень впроваджуються в ходи агента лише коли вибрану модель позначено як здатну працювати із зображеннями.models.providers.*.models.*.contextWindow: метадані нативного контекстного вікна моделі. Це перевизначаєcontextWindowрівня провайдера для цієї моделі.models.providers.*.models.*.contextTokens: необов’язкове обмеження контексту часу виконання. Це перевизначаєcontextTokensрівня провайдера; використовуйте його, коли потрібен менший ефективний бюджет контексту, ніж нативнийcontextWindowмоделі;openclaw models listпоказує обидва значення, коли вони відрізняються.models.providers.*.models.*.compat.supportsDeveloperRole: необов’язкова підказка сумісності. Дляapi: "openai-completions"з непорожнім ненативнимbaseUrl(хост неapi.openai.com) OpenClaw примусово встановлює це вfalseпід час виконання. Порожній/пропущенийbaseUrlзберігає типову поведінку OpenAI.models.providers.*.models.*.compat.requiresStringContent: необов’язкова підказка сумісності для чат-ендпоїнтів, сумісних з OpenAI, які підтримують лише рядки. Колиtrue, OpenClaw сплощує масиви суто текстовогоmessages[].contentу прості рядки перед надсиланням запиту.models.providers.*.models.*.compat.strictMessageKeys: необов’язкова підказка сумісності для суворих чат-ендпоїнтів, сумісних з OpenAI. Колиtrue, OpenClaw обрізає вихідні об’єкти повідомлень Chat Completions доroleіcontentперед надсиланням запиту.models.providers.*.models.*.compat.thinkingFormat: необов’язкова підказка формату корисного навантаження мислення. Використовуйте"qwen"для верхньорівневогоenable_thinkingабо"qwen-chat-template"дляchat_template_kwargs.enable_thinkingна серверах Qwen-сімейства, сумісних з OpenAI, які підтримують kwargs чат-шаблону на рівні запиту, таких як vLLM.
Виявлення Amazon Bedrock
Виявлення Amazon Bedrock
plugins.entries.amazon-bedrock.config.discovery: корінь налаштувань автовиявлення Bedrock.plugins.entries.amazon-bedrock.config.discovery.enabled: увімкнути/вимкнути неявне виявлення.plugins.entries.amazon-bedrock.config.discovery.region: регіон AWS для виявлення.plugins.entries.amazon-bedrock.config.discovery.providerFilter: необов’язковий фільтр ідентифікатора провайдера для цільового виявлення.plugins.entries.amazon-bedrock.config.discovery.refreshInterval: інтервал опитування для оновлення виявлення.plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow: резервне контекстне вікно для виявлених моделей.plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens: резервна максимальна кількість вихідних токенів для виявлених моделей.
--custom-image-input, щоб примусово встановити метадані з підтримкою зображень, або --custom-text-input, щоб примусово встановити метадані лише для тексту.
Приклади провайдерів
Cerebras (GLM 4.7 / GPT OSS)
Cerebras (GLM 4.7 / GPT OSS)
Вбудований Plugin провайдера Використовуйте
cerebras може налаштувати це через openclaw onboard --auth-choice cerebras-api-key. Використовуйте явну конфігурацію провайдера лише тоді, коли перевизначаєте стандартні значення.cerebras/zai-glm-4.7 для Cerebras; zai/glm-4.7 для прямого Z.AI.Kimi Coding
Kimi Coding
openclaw onboard --auth-choice kimi-code-api-key.Local models (LM Studio)
Local models (LM Studio)
Див. Локальні моделі. TL;DR: запускайте велику локальну модель через LM Studio Responses API на потужному обладнанні; залишайте розміщені моделі об’єднаними для резервного варіанта.
MiniMax M2.7 (direct)
MiniMax M2.7 (direct)
MINIMAX_API_KEY. Скорочення: openclaw onboard --auth-choice minimax-global-api або openclaw onboard --auth-choice minimax-cn-api. Каталог моделей за замовчуванням містить лише M2.7. На Anthropic-сумісному шляху потокового передавання OpenClaw стандартно вимикає мислення MiniMax, якщо ви явно не встановите thinking самостійно. /fast on або params.fastMode: true переписує MiniMax-M2.7 на MiniMax-M2.7-highspeed.Moonshot AI (Kimi)
Moonshot AI (Kimi)
baseUrl: "https://api.moonshot.cn/v1" або openclaw onboard --auth-choice moonshot-api-key-cn.Нативні endpoint Moonshot оголошують сумісність використання потокового передавання на спільному транспорті openai-completions, а OpenClaw прив’язує це до можливостей endpoint, а не лише до ідентифікатора вбудованого провайдера.OpenCode
OpenCode
OPENCODE_API_KEY (або OPENCODE_ZEN_API_KEY). Використовуйте refs opencode/... для каталогу Zen або refs opencode-go/... для каталогу Go. Скорочення: openclaw onboard --auth-choice opencode-zen або openclaw onboard --auth-choice opencode-go.Synthetic (Anthropic-compatible)
Synthetic (Anthropic-compatible)
/v1 (клієнт Anthropic додає його). Скорочення: openclaw onboard --auth-choice synthetic-api-key.Z.AI (GLM-4.7)
Z.AI (GLM-4.7)
ZAI_API_KEY. z.ai/* і z-ai/* приймаються як псевдоніми. Скорочення: openclaw onboard --auth-choice zai-api-key.- Загальний endpoint:
https://api.z.ai/api/paas/v4 - Endpoint для кодування (за замовчуванням):
https://api.z.ai/api/coding/paas/v4 - Для загального endpoint визначте користувацького провайдера з перевизначенням базового URL.
Пов’язане
- Конфігурація — агенти
- Конфігурація — канали
- Довідник конфігурації — інші ключі верхнього рівня
- Інструменти та plugins