Файл конфигурации `settings.json`¶

Koda CLI читает настройки из JSON-файлов с комментариями. Значения можно менять вручную или через /settings.

Файлы настроек¶

Scope	Путь
User	`~/.kodacli/settings.json`
Workspace	`<workspace>/.kodacli/settings.json`

При слиянии настроек system имеет наивысший приоритет, затем workspace, затем user. Параметры mcpServers, customThemes, includeDirectories, network и chatCompression объединяются.

Приоритет настроек¶

От низшего к высшему:

Значения по умолчанию — встроены в код;
settings.json — файлы настроек;
Переменные окружения — переопределяют настройки (если заданы);
CLI-флаги — переопределяют переменные окружения и настройки (если заданы явно).

Структура файла¶

settings.json

{
  "model": "koda-base",
  "selectedAuthType": "koda-auth",
  "theme": "Default",
  "language": "ru",
  "checkpointing": {
    "enabled": true
  },
  "fileFiltering": {
    "respectGitIgnore": true,
    "respectKodaIgnore": true,
    "enableRecursiveFileSearch": true
  },
  "includeDirectories": ["../shared"],
  "loadMemoryFromIncludeDirectories": false,
  "contextFileName": ["KODA.md", "AGENTS.md"]
}

Каждый параметр ниже описан отдельной секцией с указанием значения по умолчанию.

Общие настройки¶

`model`¶

koda-base

Модель по умолчанию. Подробнее о выборе модели — на странице модели.

`maxContextByModel`¶

Ручное ограничение контекста для каждой модели: ключ — идентификатор модели в нижнем регистре, значение — объект с полями enabled (включено ли ограничение) и tokens (число токенов). Значение не может превышать жёсткий лимит модели; если метаданные API снижают потолок, сохранённое число ограничивается сверху без удаления.

settings.json

{
  "maxContextByModel": {
    "koda-pro": { "enabled": true, "tokens": 512000 }
  }
}

Обычно задаётся командой /maxcontext; подробнее — на странице о моделях.

Размышления модели¶

`reasoningEffortByModel`¶

Уровень размышлений для каждой модели: none, minimal, low, medium, high, xhigh.

Ключ — идентификатор модели, значение — уровень. Уровень применяется, только если модель его поддерживает. Если уровень не задан или не поддерживается, используется уровень по умолчанию, который объявляет сервер.

Выбор уровня также можно менять командой /reasoning — подробнее на странице модели.

settings.json

{
  "reasoningEffortByModel": {
    "koda-base": "high",
    "koda-pro": "xhigh"
  }
}

`reasoningDisplay`¶

compact

Как показывать размышления модели в интерфейсе во время ответа:

off — не показывать и не сохранять;
compact — одна строка-заголовок фазы рядом со спиннером и короткая пометка в истории;
stream — скользящее окно с текстом размышлений;
full — как stream, но полный текст размышлений остаётся в истории.

Режим также можно менять командой /reasoning display или /reasoning-display.

`selectedAuthType`¶

Способ входа: koda-auth, github или skip. Значение выбирается в диалоге входа и сохраняется автоматически.

Подробнее — на странице авторизации.

`language`¶

ru

Язык интерфейса: ru или en.

`theme`¶

Название встроенной или пользовательской темы.

Подробнее — на странице о темах.

`customThemes`¶

Определения пользовательских тем.

Подробнее — на странице о темах.

`vimMode`¶

Включить vim keybindings.

`ideMode`¶

Включить IDE-интеграцию через компаньона.

Подробнее — на странице о компаньоне.

`showLineNumbers`¶

Показывать номера строк в чате.

`showMemoryUsage`¶

Показывать использование памяти.

`hideTips`¶

false

Скрывать полезные подсказки в интерфейсе.

`hideBanner`¶

false

Скрывать стартовый баннер приложения.

`hideWindowTitle`¶

false

Не менять заголовок окна терминала. Требует перезапуска.

`preferredEditor`¶

Внешний редактор, в котором открывается текущий ввод по Ctrl + X (см. горячие клавиши). Значение выбирается командой /editor; без него CLI определяет редактор автоматически.

Контекст и файлы¶

`includeDirectories`¶

Дополнительные workspace-каталоги.

`loadMemoryFromIncludeDirectories`¶

false

Загружать файлы памяти из каталогов, добавленных через includeDirectories.

`contextFileName`¶

["KODA.md", "AGENTS.md"]

Имя или список имён файлов памяти, например KODA.md и AGENTS.md. Дополнительно CLI читает системные правила из файла .kodarules в корне рабочей области — см. Контекстные файлы.

`fileFiltering.respectGitIgnore`¶

true

Исключать файлы, игнорируемые git.

`fileFiltering.respectKodaIgnore`¶

true

Исключать файлы по правилам .kodaignore.

`fileFiltering.enableRecursiveFileSearch`¶

true

Разрешить рекурсивный поиск файлов.

`autoCompressContext`¶

true

Включает автоматическое сжатие контекста: сжатие запускается, когда до лимита токенов модели остаётся 40 000 токенов, а для моделей с окном до 40 000 токенов — при занятии 75% лимита. При отключении остаются ручное /compress и защита от превышения лимита.

Подробнее — на странице о сжатии контекста.

`chatCompression.contextPercentageThreshold`¶

0.5

Устаревший ключ: доля от лимита токенов модели (от 0 до 1), при которой раньше запускалось сжатие. В текущем алгоритме порог фиксирован и задаёт его autoCompressContext; значение вне диапазона 0–1 отбрасывается с предупреждением.

Сессия и поведение агента¶

`maxSessionTurns`¶

Максимальное число ходов (пользователь/модель/инструмент) в одной сессии. По умолчанию не задано — без ограничения. Используется в headless-режиме.

`maxTurnRequests`¶

100

Максимум запросов к модели в пределах одного хода агента. Значение -1 снимает ограничение. Требует перезапуска.

Обновления¶

`disableAutoUpdate`¶

false

Отключить автоматическое обновление CLI.

`disableUpdateNag`¶

false

Отключить напоминания о доступных обновлениях.

Checkpointing¶

`checkpointing.enabled`¶

false

Сохранять snapshots перед изменением файлов. Включается также флагом --checkpointing при запуске.

Подробнее — на странице о контрольных точках.

Песочница¶

`sandbox`¶

Значение: true, false, docker, podman или sandbox-exec.

Подробнее — на странице о песочнице.

Сеть¶

`network`¶

Настройки прокси и сертификатов для HTTP-запросов CLI. Требуют перезапуска. Флаги --proxy и --ca-file имеют приоритет над этими настройками.

settings.json

{
  "network": {
    "proxy": "https://proxy.example.com:8443",
    "noProxy": "localhost,127.0.0.1",
    "caFile": "/path/to/ca-bundle.pem",
    "useSystemCa": true,
    "requestTimeoutMs": 60000
  }
}

Ключ	По умолчанию	Назначение
`proxy`	пусто	прокси для HTTP и HTTPS одновременно
`httpProxy`	пусто	прокси только для HTTP
`httpsProxy`	пусто	прокси только для HTTPS
`noProxy`	пусто	хосты через запятую, для которых прокси пропускается
`caFile`	пусто	путь к PEM-набору корневых сертификатов
`caFiles`	пусто	список путей к PEM-наборам сертификатов
`useSystemCa`	`true`	использовать системные центры сертификации, когда ОС это поддерживает
`requestTimeoutMs`	пусто	миллисекунды без данных ответа до обрыва запроса; `0` отключает тайм-аут

Инструменты¶

Перечень доступных инструментов — в справочнике инструментов.

`coreTools`¶

Allowlist встроенных tools.

`excludeTools`¶

Tools, которые нельзя использовать.

`summarizeToolOutput`¶

Лимиты summary для output tools.

MCP-серверы¶

`mcpServers`¶

Конфигурация MCP-серверов.

Примеры подключения — на странице с примерами использования.

settings.json

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "trust": false,
      "includeTools": ["read_file"],
      "excludeTools": []
    },
    "remote-api": {
      "httpUrl": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      },
      "timeout": 10000
    }
  }
}

Для stdio используйте command, args, env. Для SSE используйте url. Для streamable HTTP используйте httpUrl.

`allowMCPServers`¶

Белый список MCP-серверов (запускать указанные).

`excludeMCPServers`¶

Чёрный список MCP-серверов (не запускать указанные).

Команды¶

`bugCommand`¶

Переопределение поведения /bug.

`usageStatisticsEnabled`¶

true

Сбор обезличенной статистики использования. Требует перезапуска.

`accessibility.disableLoadingPhrases`¶

false

Отключить фразы загрузки («думаю», «анализирую» и подобные) — полезно для скринридеров.

`dnsResolutionOrder`¶

Порядок разрешения DNS-имён: ipv4first или verbatim. Требует перезапуска.

Удалённый доступ через Telegram¶

Подробнее — на странице об интеграции с Telegram.

`telegramRemote`¶

Настройки удалённого доступа к текущему экземпляру CLI через Telegram. Обычно заполняются автоматически командами /telegram setup и /telegram link.

settings.json

{
  "telegramRemote": {
    "enabled": true,
    "botToken": "123456:ABC...",
    "ownerId": 123456789,
    "notifyOn": "confirmation"
  }
}

Ключ	По умолчанию	Назначение
`enabled`	`false`	включить удалённый доступ
`botToken`	пусто	токен Telegram-бота
`ownerId`	пусто	идентификатор владельца — единственного пользователя, который управляет CLI
`ownerUsername`	пусто	username владельца
`ownerDisplayName`	пусто	отображаемое имя владельца
`notifyOn`	`confirmation`	когда уведомлять владельца о локальных запросах: `finish`, `confirmation`, `off`

Навыки и расширения¶

См. подробнее: навыки агента и расширения.

`skills.disabled`¶

Отключённые навыки.

`extensions.disabled`¶

Отключённые расширения.

Субагенты¶

`subagents`¶

false

Фоновые субагенты, которых агент делегирует инструментом run_subagent; по умолчанию они работают только на чтение. О работе субагентов в CLI подробнее — в разделе Субагенты. Состояние задач — командой /subagents.

settings.json

{
  "subagents": {
    "enabled": true,
    "allowParentToContinue": false,
    "maxConcurrent": 2,
    "model": "",
    "reasoningEffort": null,
    "maxRuntimeMinutes": 30,
    "stalledAfterMinutes": 2,
    "tools": null,
    "disabledAgentNames": []
  }
}

Ключ	По умолчанию	Назначение
`enabled`	`false`	регистрировать инструмент `run_subagent`; применяется сразу, без перезапуска
`allowParentToContinue`	`false`	продолжает ли основной агент работу, пока субагенты заняты
`maxConcurrent`	`2`	сколько субагентов может работать одновременно (1–4); лишние запуски отклоняются
`model`	пусто	модель субагентов; пустое значение — наследовать основную модель
`reasoningEffort`	пусто	уровень рассуждений субагентов; пустое значение — уровень по умолчанию модели
`maxRuntimeMinutes`	`30`	бюджет времени одной задачи, по истечении watchdog её останавливает
`stalledAfterMinutes`	`2`	сколько минут без завершённого шага задача помечается как `stalled`
`tools`	пусто	инструменты субагента; пустое значение — набор только для чтения
`disabledAgentNames`	пусто	выключенные роли субагентов по имени

Ключ tools по умолчанию (null) оставляет субагенту «читающие» инструменты. Перечислив replace, write_file, run_shell_command или save_memory, вы разрешаете субагенту менять рабочую область: править файлы, выполнять команды и сохранять заметки в память. Инструмент, который в текущем режиме подтверждений спросил бы подтверждения, субагенту не выдаётся: фоновой задаче некому его дать. Неизвестные имена молча отбрасываются; run_subagent и update_plan недоступны субагенту всегда. Пустой список — осознанный выбор: субагент останется вообще без инструментов.

Секция применяется без перезапуска: CLI следит за settings.json и подхватывает изменения за доли секунды, даже внесённые другим процессом.

Безопасность¶

`folderTrustFeature`¶

Включить trust-механику workspace.

`excludedProjectEnvVars`¶

Env-переменные, исключаемые из project context.

Звуковые уведомления¶

`notificationSound`¶

Звуковой сигнал при запросе подтверждения и завершении работы.

Koda подаёт сигнал, когда требуется подтвердить вызов инструмента или когда агент закончил работу. По умолчанию сигнал звучит только если окно терминала не в фокусе.

settings.json

{
  "notificationSound": {
    "mode": "unfocused",
    "onApproval": true,
    "onComplete": true,
    "desktopNotification": true
  }
}

Ключ	Назначение
`mode`	`off` — выключено, `unfocused` (по умолчанию) — только когда окно не в фокусе, `always` — всегда
`onApproval`	сигнал, когда вызов инструмента ждёт подтверждения
`onComplete`	сигнал, когда агент завершил работу
`desktopNotification`	дополнительно отправлять уведомление OSC 9
`command`	команда оболочки вместо системного сигнала терминала

Звук — это стандартный сигнал терминала (BEL), поэтому он работает и через SSH; как именно его отработать, решает сам терминал (мигание вкладки, значок в доке, системное уведомление).

Режим unfocused опирается на focus reporting терминала (DECSET 1004). Терминалы без его поддержки — в частности macOS Terminal.app — никогда не сообщают о потере фокуса, поэтому сигнал не прозвучит. В таком случае выберите "mode": "always".

desktopNotification использует OSC 9: поддерживают iTerm2, Windows Terminal, kitty, WezTerm; остальные терминалы молча игнорируют последовательность.

Чтобы задать собственный звук вместо сигнала терминала, укажите command:

settings.json

{
  "notificationSound": {
    "mode": "always",
    "command": "afplay /System/Library/Sounds/Glass.aiff"
  }
}

Команда запускается отсоединённым процессом, её вывод и ошибки игнорируются. Учтите, что при работе через SSH звук прозвучит на удалённой машине, а не на вашей — там лучше оставить BEL.

Переменные окружения¶

Koda CLI дополнительно учитывает:

KODA_MODEL — модель по умолчанию (см. --model);
KODA_AUTH_ACCESS_TOKEN, KODA_AUTH_REFRESH_TOKEN, KODA_API_KEY — аутентификация в headless-режиме (см. авторизацию);
HTTPS_PROXY, HTTP_PROXY;
NO_BROWSER;
DEBUG, DEBUG_MODE;
sandbox-переменные вроде KODA_SANDBOX, KODA_SANDBOX_IMAGE, SANDBOX_MOUNTS, SANDBOX_ENV.

Файл конфигурации settings.json¶

Файлы настроек¶

Приоритет настроек¶

Структура файла¶

Общие настройки¶

model¶

maxContextByModel¶

Размышления модели¶

reasoningEffortByModel¶

reasoningDisplay¶

selectedAuthType¶

language¶

theme¶

customThemes¶

vimMode¶

ideMode¶

showLineNumbers¶

showMemoryUsage¶

hideTips¶

hideBanner¶

hideWindowTitle¶

preferredEditor¶

Контекст и файлы¶

includeDirectories¶

loadMemoryFromIncludeDirectories¶

contextFileName¶

fileFiltering.respectGitIgnore¶

fileFiltering.respectKodaIgnore¶

fileFiltering.enableRecursiveFileSearch¶

autoCompressContext¶

chatCompression.contextPercentageThreshold¶

Сессия и поведение агента¶

maxSessionTurns¶

maxTurnRequests¶

Обновления¶

disableAutoUpdate¶

disableUpdateNag¶

Checkpointing¶

checkpointing.enabled¶

Песочница¶

sandbox¶

Сеть¶

network¶

Инструменты¶

coreTools¶

excludeTools¶

summarizeToolOutput¶

MCP-серверы¶

mcpServers¶

allowMCPServers¶

excludeMCPServers¶

Команды¶

bugCommand¶

usageStatisticsEnabled¶

accessibility.disableLoadingPhrases¶

dnsResolutionOrder¶

Удалённый доступ через Telegram¶

telegramRemote¶

Навыки и расширения¶

skills.disabled¶

extensions.disabled¶

Субагенты¶

subagents¶

Безопасность¶

folderTrustFeature¶

excludedProjectEnvVars¶

Звуковые уведомления¶

notificationSound¶

Переменные окружения¶

Файл конфигурации `settings.json`¶

`model`¶

`maxContextByModel`¶

`reasoningEffortByModel`¶

`reasoningDisplay`¶

`selectedAuthType`¶

`language`¶

`theme`¶

`customThemes`¶

`vimMode`¶

`ideMode`¶

`showLineNumbers`¶

`showMemoryUsage`¶

`hideTips`¶

`hideBanner`¶

`hideWindowTitle`¶

`preferredEditor`¶

`includeDirectories`¶

`loadMemoryFromIncludeDirectories`¶

`contextFileName`¶

`fileFiltering.respectGitIgnore`¶

`fileFiltering.respectKodaIgnore`¶

`fileFiltering.enableRecursiveFileSearch`¶

`autoCompressContext`¶

`chatCompression.contextPercentageThreshold`¶

`maxSessionTurns`¶

`maxTurnRequests`¶

`disableAutoUpdate`¶

`disableUpdateNag`¶

`checkpointing.enabled`¶

`sandbox`¶

`network`¶

`coreTools`¶

`excludeTools`¶

`summarizeToolOutput`¶

`mcpServers`¶

`allowMCPServers`¶

`excludeMCPServers`¶

`bugCommand`¶

`usageStatisticsEnabled`¶

`accessibility.disableLoadingPhrases`¶

`dnsResolutionOrder`¶

`telegramRemote`¶

`skills.disabled`¶

`extensions.disabled`¶

`subagents`¶

`folderTrustFeature`¶

`excludedProjectEnvVars`¶

`notificationSound`¶