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

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

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

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

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

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

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

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

{
  "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¶

v0.1.17 koda-base

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

maxContextByModel¶

v1.2.5

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

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

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

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

reasoningEffortByModel¶

v1.1.1

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

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

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

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

reasoningDisplay¶

v1.1.1 compact

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

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

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

selectedAuthType¶

v0.1.6

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

language¶

v1.1.1 ru

Язык интерфейса: ru или en. Этот же язык CLI передаёт модели как язык ответов: он попадает в системную инструкцию, поэтому ответы и рассуждения идут на выбранном языке. В ACP-сессиях язык интерфейса и язык ответов можно задать независимо.

theme¶

v0.1.6

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

customThemes¶

v0.1.14

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

vimMode¶

v0.1.15

Включить vim keybindings.

ideMode¶

v0.1.13

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

showLineNumbers¶

v0.1.19

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

showMemoryUsage¶

v0.1.6

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

hideTips¶

v0.1.8 false

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

hideBanner¶

v0.1.13 false

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

hideWindowTitle¶

v0.1.6 false

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

preferredEditor¶

v0.1.6

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

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

includeDirectories¶

v0.1.18

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

loadMemoryFromIncludeDirectories¶

v0.1.18 false

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

contextFileName¶

v0.1.6 ["KODA.md", "AGENTS.md", "agents.md", "AGENT.md"]

Имя или список имён файлов памяти. По умолчанию в каждом каталоге используется первый найденный файл в порядке KODA.md → AGENTS.md → agents.md → AGENT.md. Порядок такой же, как в плагине для IDE. Настройка заменяет этот список целиком.

Файлы в корне рабочей области загружаются при старте сессии. Файлы подкаталогов агент получает по мере чтения файлов и просмотра каталогов — подробнее в разделе «Контекст проекта».

Файл, который начинается с # [DISABLED], не загружается, но всё равно занимает свой каталог: остальные имена в этом каталоге не используются.

Дополнительно CLI читает системные правила из файла .kodarules в корне рабочей области — см. Контекстные файлы.

memoryDiscoveryMaxDirs¶

v0.1.14

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

fileFiltering.respectGitIgnore¶

v0.1.6 true

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

fileFiltering.respectKodaIgnore¶

v1.1.1 true

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

fileFiltering.enableRecursiveFileSearch¶

v0.1.6 true

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

autoCompressContext¶

v1.2.0 true

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

chatCompression.contextPercentageThreshold¶

v0.1.19 0.5

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

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

maxSessionTurns¶

v0.1.12

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

maxTurnRequests¶

v1.2.3 100

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

Обновления¶

checkForUpdatesAtStartup¶

v1.2.7 true

Проверять новую версию CLI при каждом запуске самостоятельного интерактивного CLI. В ACP-режиме и неинтерактивном режиме проверка не выполняется. Требует перезапуска.

Настройка также доступна в /settings как «Проверять обновления при запуске». Значение false полностью отключает запрос при следующем запуске и исключает автоматическую установку по результату проверки.

disableAutoUpdate¶

v0.1.16 false

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

disableUpdateNag¶

v0.1.17 false

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

Checkpointing¶

checkpointing.enabled¶

v0.1.6 false

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

Песочница¶

sandbox¶

v0.1.6

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

Сеть¶

network¶

v1.1.1

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

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

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

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

coreTools¶

v0.1.6

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

excludeTools¶

v0.1.6

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

Имя computer_use в этих списках действует как для остальных инструментов: в excludeTools оно скрывает управление компьютером, а в coreTools — оставляет его только при явном перечислении.

summarizeToolOutput¶

v0.1.13

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

MCP-серверы¶

mcpServers¶

v0.1.6

Конфигурация MCP-серверов. Ключ — имя сервера, значение — его параметры. Транспорт определяется заполненным полем: command для stdio, httpUrl для Streamable HTTP, url для SSE.

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "."],
      "env": {
        "LOG_LEVEL": "info"
      },
      "cwd": "/path/to/workdir",
      "trust": false,
      "includeTools": ["read_file"],
      "excludeTools": []
    },
    "remote-api": {
      "httpUrl": "https://example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      },
      "timeout": 30000
    },
    "remote-sse": {
      "url": "https://example.com/sse",
      "headers": {
        "Authorization": "Bearer ${MCP_TOKEN}"
      }
    }
  }
}

В строках настроек подставляются значения переменных окружения в форматах $VAR и ${VAR}, поэтому токен удобно хранить не в файле, а в окружении.

allowMCPServers¶

v0.1.13

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

excludeMCPServers¶

v0.1.13

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

Команды¶

bugCommand¶

v0.1.6

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

usageStatisticsEnabled¶

v0.1.6 true

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

accessibility.disableLoadingPhrases¶

v0.1.6 false

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

dnsResolutionOrder¶

v0.1.16

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

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

telegramRemote¶

v1.1.1

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

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

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

skills.disabled¶

v1.1.1

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

extensions.disabled¶

v1.1.1

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

Субагенты¶

subagents¶

v1.2.0 false

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

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

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

В редакторе настроек список инструментов отмечается клавишей Space, а Enter сохраняет весь текущий выбор, включая последнюю отметку. Пустой выбор снимает ограничение и возвращает набор по умолчанию; Esc закрывает редактор без сохранения.

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

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

folderTrustFeature¶

v0.1.19

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

excludedProjectEnvVars¶

v0.1.17

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

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

notificationSound¶

v1.1.1

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

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

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

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

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

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

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

{
  "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.