Решение проблем¶

Эта страница помогает быстро разобраться с типовыми проблемами в Koda CLI. Каждый раздел описывает симптом, вероятную причину и способ её устранения.

Если готового решения не нашлось, используйте диагностику, чтобы собрать сведения об окружении, и сообщите об ошибке.

Установка и запуск¶

CLI не стартует или падает при вводе¶

Проверьте текущую версию:

node --version

Koda CLI требует Node.js не ниже версии 20.

Если установлена более старая версия, обновите Node.js (например, через менеджер версий вроде nvm или fnm) и снова установите CLI.

koda: command not found¶

Команда koda не найдена в PATH.

Обычные причины:

• глобальная установка не завершилась или была выполнена без прав;
• каталог глобальных bin-пакетов npm не добавлен в PATH;
• использован npx, но переменная окружения не настроена.

Проверьте, что CLI установлен:

npm list -g @kodadev/koda-cli

Если CLI не установлен, установите его глобально:

npm install -g @kodadev/koda-cli

Каталог, в который npm кладёт бинари, должен быть в PATH. Обычно это $(npm prefix -g)/bin — добавьте его в PATH, если команда всё ещё не находится.

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

Установка через npm завершается ошибкой прав¶

Типичная ошибка — EACCES: permission denied при глобальной установке.

Решения:

• переустановите npm с корректным owner глобального каталога;
• либо настройте отдельный каталог для глобальных пакетов в ~/.npmrc.

Подробные инструкции зависят от операционной системы и способа установки Node.js.

npx @kodadev/koda-cli

Авторизация¶

CLI снова и снова запрашивает вход¶

Koda CLI хранит данные входа в ~/.config/koda/credentials.json. Если этот файл нельзя создать или обновить, CLI не сможет сохранить токены и будет повторно спрашивать доступ.

Проверьте:

ls -la ~/.config/koda/

Убедитесь, что каталог ~/.config/koda существует и у текущего пользователя есть права на запись. Файл credentials.json создаётся с правами 0600.

Проблемы обычно возникают:

• когда каталог принадлежит другому пользователю (например, после sudo);
• при некорректных правах на родительский каталог ~/.config;
• в некоторых корпоративных окружениях с ограничениями на домашний каталог.

Решение — восстановить владельца и права:

mkdir -p ~/.config/koda
chmod 700 ~/.config/koda

Затем повторите вход командой /auth.

Ошибка 401, «token expired» или «unauthorized»¶

Если CLI сообщает о невалидной или просроченной сессии, токен доступа стал недействителен.

Что сделать:

• повторно войдите через /auth;
• если вход выполняется вручную по ссылке, завершите его до истечения таймаута;
• в головном окружении (headless) убедитесь, что заданы актуальные токены, — подробнее в разделе headless-режим.

Полный сброс локального входа:

rm ~/.config/koda/credentials.json

После этого при следующем запуске CLI снова предложит войти.

Браузер не открывается при входе¶

По умолчанию CLI пытается открыть ссылку подтверждения в браузере. В SSH-сессиях, CI и окружениях без браузера это не сработает.

Запретите автоматическое открытие браузера:

NO_BROWSER=1 koda

CLI напечатает ссылку — откройте её на машине с браузером и завершите вход до истечения таймаута.

Сеть и прокси¶

Нет соединения с API¶

Ошибки соединения обычно связаны с доступом к сети.

Что проверить:

• доступность сервисов Koda из вашей сети;
• работу HTTPS через корпоративный прокси;
• системные корневые сертификаты.

При работе за прокси задайте его через переменные окружения или флаг --proxy:

export HTTPS_PROXY="http://user:pass@proxy:8080"
koda

Либо через флаг:

koda --proxy http://user:pass@proxy:8080

Проблемы с корневыми сертификатами¶

Если запросы не проходят из-за ошибок TLS (самоподписанные сертификаты, корпоративная цепочка), укажите набор корневых сертификатов:

koda --ca-file /path/to/ca-bundle.pem

При старте CLI может перезапуститься с системным набором сертификатов, если обнаружит проблему с TLS. Если это происходит постоянно, проверьте значение HTTPS_PROXY, HTTP_PROXY и настройку network.caFile в настройках.

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

CLI не стартует из-за ошибки в настройках¶

При старте CLI проверяет файлы настроек. Если они невалидны, появляется сообщение вроде:

Error in <путь>: <описание ошибки>
Please fix <путь> and try again.

Откройте указанный файл settings.json и исправьте ошибку каталога ~/.kodacli или <workspace>/.kodacli:

• валидный JSON (комментарии разрешены только в некоторых местах);
• корректные значения ключей.

После исправления перезапустите CLI.

Изменения настроек не применяются¶

Koda CLI читает настройки по приоритету: значения по умолчанию, затем settings.json, затем переменные окружения, затем CLI-флаги.

Если ожидаемый эффект не появился, проверьте, что:

• настройка задана в файле с правильным scope (user или workspace);
• настройка не перекрыта переменной окружения;
• настройка не перекрыта флагом запуска.

Для некоторых параметров (например, mcpServers, includeDirectories) значение из настроек объединяется, а не заменяется. Подробнее о приоритете — в настройках.

Не работает звук подтверждения¶

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

Причины, почему звука нет:

• режим unfocused, а терминал не поддерживает focus reporting (например, macOS Terminal.app);
• сигнал направлен не туда (режим always, но терминал глотает BEL);
• звук воспроизводится через command, который не может запуститься.

Что сделать:

• включите сигнал всегда: "mode": "always" в настройке notificationSound;
• либо задайте собственную команду для звука через command.

Интерактивная сессия (TUI)¶

Сочетания клавиш ведут себя неожиданно¶

Часть клавиатурной обработки зависит от версии Node.js и возможностей терминала.

Если клавиши не отвечают или ведут себя странно:

• проверьте версию Node.js (см. выше);
• используйте терминал с поддержкой нужных escape-последовательностей;
• перезапустите CLI в чистой TTY-сессии.

Горячие клавиши и режим vim¶

Режим vim включается командой /vim или настройкой vimMode. Если переключение не работает, убедитесь, что нажатия не перехватываются самим терминалом (например, не назначены на vim пустые макросы в родительском терминале).

Headless-режим¶

No input provided via stdin¶

Если headless-режим запущен без промпта и stdin пуст, CLI завершается с ошибкой.

Передайте запрос одним из способов:

koda -p "Опиши проект"
echo "Опиши проект" | koda

Ошибка при комбинации -i и stdin¶

Флаг --prompt-interactive нельзя использовать вместе с вводом через конвейер. Если процесс запущен не в TTY, CLI завершается с кодом 1 и сообщением об ошибке.

Не передавайте stdin и используйте -i только в интерактивном терминале.

Ошибка аутентификации в headless¶

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

• KODA_AUTH_ACCESS_TOKEN;
• KODA_AUTH_REFRESH_TOKEN;
• KODA_API_KEY.

Без них CLI может потребовать вход в несовместимом с автоматизацией виде. Подробнее — в headless-режиме и авторизации.

Процесс завершается с кодом 1¶

Код 1 означает ошибку: сбой API, некорректные флаги, отсутствие ввода или ошибку аутентификации.

Сообщения об ошибках выводятся в stderr. Запустите команду с флагом --show-reasoning, чтобы увидеть reasoning модели, если проблема связана с ответом.

Подтверждения инструментов не запрашиваются¶

По умолчанию в headless-режиме инструменты, требующие подтверждения, отключены. Если агент не выполняет ожидаемые действия, выберите режим подтверждения:

koda -p "…" --approval-mode=auto_edit
koda -p "…" --approval-mode=yolo

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

MCP-серверы¶

Сервер не подключается¶

Если MCP-сервер не отвечает, проверьте:

• логи CLI — там будет причина падения сервера;
• что сервер запускается без CLI (выполните его command и args вручную);
• статус через подкоманду koda mcp list (✓ Connected / ✗ Disconnected);
• таймаут подключения для удалённых серверов.

OAuth-истёкший токен¶

Для MCP-серверов с OAuth может встретиться ошибка «OAuth token expired». Повторите аутентификацию для сервера:

/mcp auth <server>

или запросите повторное обнаружение серверов:

/mcp refresh

Checkpointing¶

Команда /restore недоступна¶

Команда регистрируется только когда checkpointing включён. Запустите CLI с флагом:

koda --checkpointing

или включите настройку checkpointing.enabled.

Checkpointing не работает¶

Для контрольных точек нужен Git. Проверьте, что в системе есть git и он выполняется из рабочей директории.

Файлы контрольных точек хранятся локально в ~/.kodacli/history/<project_hash> и ~/.kodacli/tmp — это отдельное shadow-хранилище, а не ваша основная git-история.

Песочница¶

Песочница не запускается¶

Koda CLI использует sandbox-exec на macOS и Docker или Podman на других платформах.

Если ничего не запускается, проверьте:

• установлены ли Docker или Podman и запущен ли демон Docker;
• корректность образа (например, --sandbox-image ...);
• разрешения для выполнения sandbox-exec на macOS.

Убедитесь, что процесс не запущен уже внутри другой песочницы — CLI не вкладывает sandbox повторно.

Команды не видят файлы¶

Подсказки — не видны файлы, не входящие в примонтированные пути.

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

Сеть недоступна внутри песочницы¶

Доступ к сети зависит от выбранного режима и прокси. Проверьте значения SANDBOX_PORTS и прокси-переменных, либо настройте KODA_SANDBOX_PROXY_COMMAND.

IDE-интеграция (Companion)¶

/ide status показывает disconnected¶

Интеграция работает, только когда koda запущен из встроенного терминала той же IDE, где установлен компаньон.

Что сделать:

• откройте новый встроенный терминал IDE (Terminal > New Terminal);
• убедитесь, что терминал в корне того же проекта, что открыт в IDE;
• запустите koda из этого терминала;
• выполните /ide status.

Если терминал был открыт до установки компаньона, закройте его и откройте новый.

Нет поддержки IDE¶

CLI пишет, что IDE не поддерживается, когда запущен не из поддерживаемой IDE. Проверьте, что koda запущен из терминала VS Code (1.99+) или JetBrains IDE (2023.3+), где установлен компаньон.

Diff не появляется в редакторе¶

Обновите компаньона, перезапустите IDE и включите интеграцию заново:

/ide enable

Убедитесь, что в статусе (/ide status) передаются открытые файлы.

ACP-режим¶

koda --acp «висит» в терминале¶

--acp предназначен только для ACP-клиентов: CLI ждёт JSON-RPC сообщения от клиента и не открывает TUI. Не запускайте ACP-режим вручную в обычном терминале — используйте отдельный клиент, который запускает koda --acp как подпроцесс.

Клиент не видит агента¶

Убедитесь, что:

• в клиенте указана команда koda --acp;
• команда koda доступна в PATH;
• koda --version выполняется без ошибок;
• доступен ~/.config/koda/credentials.json (см. авторизация).

Вывод в stdout испорчен¶

В ACP-режиме stdout зарезервирован под JSON-RPC фреймы. Не выводите произвольный текст в stdout во wrapper-скриптах.

Подробнее — в ACP-режиме.

Telegram¶

Бот не отвечает¶

Проверьте, что:

• CLI запущен в интерактивном режиме;
• доступ включён;
• токен валиден.

Посмотрите статус:

/telegram status

«Токен занят»¶

Один токен не может использоваться двумя процессами одновременно. Завершите другой Koda CLI с этим токеном либо создайте отдельного бота.

Привязка не проходит¶

Ссылка и код привязки действуют ограниченное время (по умолчанию около 10 минут). Откройте /telegram link заново и завершите привязку до истечения срока.

Сообщения от других пользователей игнорируются¶

К одному боту привязан только один владелец. Проверьте привязанный аккаунт через /telegram status. При необходимости смените владельца через /telegram relink.

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

Расширение не загружается¶

Проверьте:

• что kodacli-extension.json лежит в корне каталога и содержит валидный JSON;
• что в манифесте заданы обязательные поля name и version;
• логи CLI на предупреждение о причине пропуска расширения;
• что каталог установленного расширения не переименован вручную (его имя берётся из name).

Изменения расширения применяются при старте сессии — перезапустите CLI.

Команда расширения не отвечает¶

Пользовательские и проектные команды имеют приоритет над командами расширений. Если имя конфликтует, вызовите команду по префиксному имени (например, /gcp.deploy). Список доступных команд — через /help.

Навык не виден¶

Проверьте, что навык находится в одном из каталогов поиска и не отключён: skills.disabled в настройках. Рабочие (workspace) навыки загружаются только для доверенной рабочей области при включённой trust-механике. Перечитайте навыки с диска:

/skills reload

Обновление¶

Автообновление не удалось¶

CLI периодически проверяет обновления. Если автообновление не сработало, обновите вручную:

npm install -g @kodadev/koda-cli@latest

Для запуска через npx обновление не требуется — npx использует актуальную версию. Проверьте текущую версию:

koda --version

Диагностика¶

Соберите сведения об окружении, чтобы быстрее найти причину.

Сведения о сессии¶

Внутри интерактивной сессии:

/about

Команда показывает версию CLI, git commit, модель, ОС и способ входа.

Debug-режим¶

Запустите CLI с отладкой:

koda --debug

Либо задайте переменные окружения DEBUG или DEBUG_MODE (значение true или 1). В headless-режиме служебные сообщения пишутся в stderr — выполните команду с флагом --debug и перенаправьте вывод в файл.

Как сообщить об ошибке¶

Если готовое решение не помогло, сообщите о проблеме — это поможет быстро её исправить.

Что собрать перед отправкой¶

Чем больше сведений вы приложите, тем быстрее разработчики смогут воспроизвести и починить проблему.

1. Сведения о сессии — выполните команду /about внутри интерактивной сессии:

   /about
   

   Команда покажет версию CLI, git commit, модель, ОС и способ входа.

2. JSON-лог сессии — сформируйте детальный лог действий за сессию:

   /bug log generate
   

   CLI создаст JSON-файл с полной хронологией событий — сохраните путь к нему.

3. Отладочный вывод — если проблема воспроизводится, запустите CLI с флагом --debug и перенаправьте вывод в файл (см. debug-режим):

   koda --debug 2> debug.log
   

Что указать в описании¶

В описании проблемы постарайтесь отразить:

• что вы делали и что ожидали увидеть;
• что произошло вместо ожидаемого;
• шаги для воспроизведения — чем точнее, тем лучше;
• версию CLI, ОС и версию Node.js;
• сообщения об ошибках из stderr или логов.

Куда отправить¶

/bug