Перейти к содержанию

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

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

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

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

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

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

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

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

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

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

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

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

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

includeDirectories

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

loadMemoryFromIncludeDirectories

false

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

contextFileName

[&quot;KODA.md&quot;, &quot;AGENTS.md&quot;]

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

fileFiltering.respectGitIgnore

true

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

fileFiltering.respectKodaIgnore

true

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

true

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

chatCompression.contextPercentageThreshold

0.5

Порог автоматического сжатия контекста — доля от лимита токенов модели (от 0 до 1). Когда история занимает указанную долю лимита, перед следующим запросом она заменяется снимком состояния.

settings.json
{
  "chatCompression": {
    "contextPercentageThreshold": 0.8
  }
}

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

Checkpointing

checkpointing.enabled

false

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

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

Песочница

sandbox

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

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

Инструменты

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

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.

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

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

skills.disabled

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

extensions.disabled

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

Субагенты

subagents

false

Фоновые read-only субагенты, которых агент делегирует инструментом 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 пусто список read-only инструментов субагента; пустое значение — все разрешённые
disabledAgentNames пусто выключенные роли субагентов по имени

Секция применяется без перезапуска: 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.