Устранение неполадок

Когда что-то идёт не так, Cusp старается сообщить, что произошло, почему и что делать. Если из сообщения это непонятно, это ошибка; пожалуйста, сообщите о ней.

Почти во всём помогают две команды:

• /status в CLI показывает подключение к демону, сессию, модель и рабочую область.
• cusp --verbose выводит диагностику в stderr, включая попытки подключения и, в неинтерактивном режиме, каждый отказ в разрешении.

Ключи и провайдерыСкопировать ссылку на раздел

«Couldn't detect a provider for this key»Скопировать ссылку на раздел

Cusp распознаёт многие ключи по префиксу, но у некоторых провайдеров (DeepSeek, Moonshot, Z.ai, MiniMax, Mistral и других) ключи без характерного префикса. Укажите вместе с ключом базовый URL провайдера. Адреса приведены в разделе Провайдеры и шлюзы.

Провайдер возвращает 401 или 403Скопировать ссылку на раздел

• Проверьте в консоли провайдера, что ключ активен и на счёте есть средства или квота.
• Некоторые провайдеры выдают отдельные ключи для разных продуктов. Например, ключ тарифа Z.ai для программирования работает только с конечной точкой этого тарифа.
• Для шлюзов проверьте, что у ключа есть доступ к выбранной модели.

«Rate limited by … — retrying in 8 s»Скопировать ссылку на раздел

Провайдер ограничивает частоту запросов. Cusp сам повторяет запросы с нарастающей задержкой. Если это повторяется постоянно, понизьте уровень рассуждений, перейдите на модель с более высокими лимитами или настройте fallbackModel.

Модель не вызывает инструменты или вызывает их неправильноСкопировать ссылку на раздел

• Убедитесь, что модель поддерживает вызов инструментов. В каталоге Cusp модели без такой поддержки помечены, и автоматически Cusp их не выбирает.
• Для локальных моделей проверьте длину контекста на сервере. Во многих средах по умолчанию стоит 4k или 8k токенов, а агенту этого мало; задайте не меньше 32k.
• Небольшим моделям лучше подходит формат правок Cusp с привязкой к строкам. Он выбирается автоматически для моделей, которые Cusp считает более слабыми; для неизвестного id модели этого может не произойти.

Расходы кажутся высокимиСкопировать ссылку на раздел

• Проверьте /cost. Если чтение из кеша почти нулевое, кеш промптов не срабатывает. Смена модели или провайдера посреди сессии начинает с пустого кеша.
• Понизьте уровень рассуждений для рутинной работы.
• Используйте модель поменьше для субагентов, которые ведут широкий поиск.

ДемонСкопировать ссылку на раздел

CLI сообщает, что не может связаться с демономСкопировать ссылку на раздел

• В режиме по умолчанию --daemon auto CLI запускает свой демон (daemon), если работающего нет. Если запуск не удался, выполните команду с --verbose, чтобы узнать причину.
• С --daemon connect проверьте --daemon-url и --daemon-token (или CUSP_DAEMON_URL и CUSP_DAEMON_TOKEN). Токен должен быть тем, с которым запущен этот демон.
• Попробуйте --daemon embedded: демон запускается внутри процесса CLI, и сеть не нужна вовсе.

«reconnecting…» в терминальном интерфейсеСкопировать ссылку на раздел

Соединение с демоном прервалось. CLI переподключается сам и догоняет события с последнего полученного. Если демон перезапустили, сессия продолжится, когда он снова заработает.

Сессии из десктопного приложения не видны в CLIСкопировать ссылку на раздел

По умолчанию у них разные папки данных. Подключите CLI к демону приложения через --daemon-url и --daemon-token или используйте одну и ту же --data-dir.

РазрешенияСкопировать ссылку на раздел

Агент постоянно спрашивает одно и то жеСкопировать ссылку на раздел

Выберите Разрешить на сессию или Разрешать всегда вместо Разрешить один раз. «Разрешать всегда» записывает правило в .cusp/settings.local.json. Если запросы касаются правки файлов, можно также переключиться в режим acceptEdits клавишами Shift+Tab.

Команда запрещена в неинтерактивном режимеСкопировать ссылку на раздел

В неинтерактивном режиме спросить некого, поэтому всё, что не разрешено заранее, запрещается. В JSON-результате каждый отказ указан в permission_denials. Добавьте инструмент в --allowedTools, например --allowedTools "Bash(npm test *)".

Разрешающее правило будто не действуетСкопировать ссылку на раздел

• Правила deny и ask побеждают правила allow. Проверьте все файлы настроек, включая ~/.cusp/settings.json и управляемые настройки.
• В составных командах должна быть разрешена каждая часть. Для npm test && npm run lint нужны правила для обеих.
• Возможно, рабочей области ещё не доверяют. Пока доверия нет, собственные разрешающие правила проекта игнорируются.
• В режиме auto слишком широкие правила вроде Bash(*) намеренно игнорируются.
• Запись в защищённые пути (.git, .cusp, .claude, файлы запуска оболочки, …) всегда требует подтверждения, что бы ни говорили правила.

«plan mode: present a plan with ExitPlanMode first»Скопировать ссылку на раздел

Сессия в режиме планирования, поэтому правки и изменяющие команды запрещены. Подтвердите план агента или смените режим клавишами Shift+Tab.

ПесочницаСкопировать ссылку на раздел

Команды завершаются с «Operation not permitted»Скопировать ссылку на раздел

Песочница что-то заблокировала. Cusp сообщает агенту, какое ограничение сработало: запись за пределами рабочей области, чтение защищённого пути или доступ к сети. Если команде это действительно нужно, добавьте путь в sandbox.filesystem.allowWrite, откройте локальный порт через sandbox.network.allowLocalPorts, разрешите хост в sandbox.network.allowedDomains или подтвердите запуск без песочницы, когда агент спросит. Задавайте это в пользовательских настройках (~/.cusp/settings.json): собственные настройки проекта не могут расширить его песочницу.

«Sandbox unavailable»Скопировать ссылку на раздел

В Linux установите bubblewrap (sudo apt install bubblewrap или sudo dnf install bubblewrap). Некоторые контейнерные среды не дают создавать пространства имён, которые нужны bubblewrap. Windows пока не поддерживает песочницу. Без песочницы команды оболочки по умолчанию отклоняются; чтобы выполнять их без песочницы, когда единственным уровнем защиты остаются разрешения, задайте "sandbox": { "failIfUnavailable": false } в пользовательских настройках.

Инструкции и конфигурацияСкопировать ссылку на раздел

CLAUDE.md или CUSP.md не соблюдаетсяСкопировать ссылку на раздел

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

Настройка игнорируетсяСкопировать ссылку на раздел

Cusp отбрасывает недопустимые ключи с предупреждением, а не отклоняет весь файл. Запустите с --verbose, чтобы увидеть предупреждения. Проверьте и приоритет: значение в .cusp/settings.local.json переопределяет .cusp/settings.json, а .cusp/ переопределяет .claude/ на том же уровне.

Инструменты MCP-сервера не появляютсяСкопировать ссылку на раздел

Проектные серверы подключаются только после одобрения. Кроме того, инструменты MCP загружаются отложенно: агент загружает их по имени, когда они нужны. См. MCP-серверы.

Десктопное приложениеСкопировать ссылку на раздел

«Cusp is damaged and can't be opened» (macOS)Скопировать ссылку на раздел

Скорее всего, загрузка прервалась или файл был изменён. Удалите приложение и скачайте его заново на cusp.run/download.

Окно пустое или приложение показывает «daemon failed»Скопировать ссылку на раздел

Демон не запустился после нескольких попыток. Нажмите Перезапустить в окне ошибки. Если снова не получится, проверьте журналы в папке журналов приложения (в macOS — ~/Library/Logs/run.cusp.desktop/) и приложите их к сообщению об ошибке.

Ключи не сохраняются в LinuxСкопировать ссылку на раздел

Cusp хранит ключи через API Secret Service. Убедитесь, что связка ключей (GNOME Keyring или KWallet) установлена и разблокирована.

Ссылки cusp:// не открывают приложениеСкопировать ссылку на раздел

В macOS схема регистрируется при первом открытии приложения из папки «Программы». Откройте Cusp один раз и попробуйте ссылку снова.

Где получить помощьСкопировать ссылку на раздел

• Найдите или создайте issue на GitHub.
• Напишите на support@cusp.run. На странице Поддержка есть контакты по оплате и безопасности, а также ссылка на статус сервиса.

Укажите версию Cusp (cusp --version), операционную систему, провайдера и модель, а также чего вы ожидали. Не прикладывайте API-ключи и закрытый код.