15. Решение проблем

Каталог типовых проблем и решений. Если что-то не описано — ~/.astracode/log/astracode-tui.log часто содержит подсказку.

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

astracode: command not found

Бинарь не в PATH.

which astracode               # должно вывести путь
ls -la /usr/local/bin/astracode

Если файла нет — переустановите (02-installation.md).

Если файл есть, но не находится — проверьте $PATH:

echo $PATH

/usr/local/bin должен быть там. Иначе:

export PATH="/usr/local/bin:$PATH"

TUI запускается, но «висит» на старте

Чаще всего — MCP-сервер с required = true не отвечает.

tail -50 ~/.astracode/log/astracode-tui.log

Ищите mcp:: строки. Если сервер падает — отключите его в config:

[mcp_servers.problematic]
enabled = false

Или, если временно, запустите без mcp:

astracode -c 'mcp_servers={}'

Could not find suitable model provider

Провайдер не настроен.

В TUI:

/model

→ выбрать или добавить.

Если TUI не открывается до конфигурации — задайте провайдера через CLI override -c:

astracode -c model_provider=openai -c model=gpt-5

Сам API-ключ вводится через /model в TUI после запуска (он сохраняется в зашифрованный secrets). CLI-команды настройки провайдера/ключа (auth set ...) в AstraCode нет.

TUI запускается, но цвета сломаны

Проверьте, что терминал поддерживает 256 цветов:

echo $TERM
# должно быть xterm-256color или похожее

Установить:

export TERM=xterm-256color

Или в ~/.bashrc / ~/.zshrc.

Sandbox / bwrap (Linux)

bwrap: setting up uid map: Permission denied

Linux запретил unprivileged user namespaces.

sudo sysctl kernel.unprivileged_userns_clone=1

Или, чтобы постоянно:

echo 'kernel.unprivileged_userns_clone=1' | sudo tee /etc/sysctl.d/00-userns.conf
sudo sysctl -p

В ограниченных контейнерах (Docker без --privileged) bwrap не работает. Варианты: - Включить landlock через [features] в config (см. ниже) и использовать его как sandbox-бэкенд. - Поднять AstraCode с sandbox_mode = "danger-full-access" (рискованно — только если контейнер уже сам по себе изолирует систему).

Landlock и use_legacy_landlock

landlock — это отдельный sandbox-режим, доступный как подкоманда astracode sandbox linux (видимое имя landlock). CLI-флага --use-legacy-landlock нет. Поле use_legacy_landlock в секции [features] конфига помечено DEPRECATED и будет удалено — оно лишь включает устаревший Linux sandbox-бэкенд. Для новых настроек полагайтесь на astracode sandbox linux и текущий sandbox-режим, а не на это поле.

# [features]
# use_legacy_landlock = true   # DEPRECATED — избегайте, будет удалено

bwrap: No such file or directory

System bwrap не установлен. AstraCode использует встроенный (если есть).

Лучше установить:

sudo apt install bubblewrap     # Debian/Ubuntu
sudo dnf install bubblewrap     # Fedora

Sandbox блокирует нужную операцию

Например, нужно прочитать /opt/proprietary-data/.

/sandbox-add-read-dir /opt/proprietary-data

(Только на сессию. Для постоянного — [sandbox_workspace_write].writable_roots в config.)

⚠️ /sandbox-add-read-dir доступна только на Windows. На Linux/macOS используйте [sandbox_workspace_write].writable_roots в config или -c override.

Секреты

Failed to decrypt secrets file

Master-ключ из OS keyring разъехался с зашифрованным файлом. Не баг версии, не проблема обновления.

Лечение (если у вас немного API-ключей и не жалко переввести):

rm ~/.astracode/secrets/local.age
astracode
# /model → ввести ключи заново

Если ключей много — единственный способ восстановить: - Вспомнить, в каком keyring они лежали. - Восстановить (восстановить пароль, импортировать backup keyring).

Бэкап секретов без master-ключа из keyring невозможен. Это особенность дизайна — для безопасности.

OS keyring недоступен (headless server)

AstraCode упадёт с предложением fallback'а в файл ~/.astracode/secrets/local.key.

Это безопаснее, чем plaintext, но менее безопасно, чем keyring.

Если у вас headless Linux без D-Bus:

# поставить и запустить keyring демона
sudo apt install gnome-keyring
eval $(gnome-keyring-daemon --start)

Или использовать fallback (он включится автоматически, если keyring не отвечает).

Модели и провайдеры

401 Unauthorized при запросе к модели

API-ключ протух или неверный.

/model

→ выбрать провайдера → d (удалить) → + Add provider (заново).

Или проверьте baseURL — иногда у API endpoint меняется адрес.

429 Rate limit exceeded

Провайдер ограничивает запросы. Что делать: - Подождать (обычно проходит за минуту-две). - Снизить model_reasoning_effort. - Переключиться на другую модель/провайдера (/model).

Rollout-файл не пишется

Проверьте права:

ls -la ~/.astracode/sessions/

Должны быть RW для вас.

Slash-команды

/locale ru ничего не делает

Команда доступна только до первого сообщения. Если уже отправляли:

/new
/locale ru

/cd <path> — directory not found

Tab автодополнение покажет валидные пути. Используйте абсолютный путь, если относительный не работает.

/review зависает

Большой diff (>5000 строк) — модель долго думает. Подождите, или прерывайте (Ctrl-C) и:

/review only the changes in src/

С фокусом на меньший scope.

/goal не сохраняется

sqlite3 ~/.astracode/state_5.sqlite "SELECT * FROM thread_goals;"

Если БД сломана — см. выше (восстановление state_5.sqlite).

Производительность

TUI медленно реагирует

• Большая история — /compact или /new.
• Включены все скиллы — отключите ненужные через /skills.
• Локальная LLM медленная — переключитесь на cloud (/model).

Высокая загрузка CPU

• Анимации — [tui].animations = false.
• Memory Phase 2 в фоне — это нормально, проходит сама.
• Если постоянно — RUST_LOG=debug astracode 2> /tmp/log покажет, где затык.

Большой расход токенов

• Длинная история — /compact.
• Много активных скиллов — /skills → выключить лишние.
• Многие MCP-серверы — то же.
• Reasoning на high — снизить до medium: toml model_reasoning_effort = "medium"

Approval-диалоги

Каждое действие спрашивает разрешение

У вас approval_policy = untrusted. Сменить:

/approvals

→ выбрать Default (auto) или Agent mode.

Или в config:

approval_policy = "on-request"

on-failure помечен DEPRECATED и не используется по умолчанию. Для интерактивной работы используйте on-request, для скриптов — never.

Approval-диалог не появляется, тулз не выполняется

Возможно, hook блокирует. Проверьте:

grep -i hook ~/.astracode/log/astracode-tui.log

Или временно отключите хуки:

hooks = {}

Память

Память не «помнит» меня после перезапуска

Проверьте:

/memories

Должны быть включены обе toggle: Use memories и Generate memories.

Phase 1 требует минимум 6 часов idle после сессии (min_rollout_idle_hours = 6). Если пользуетесь без пауз — память не успевает извлечься.

MEMORY.md пустой

Phase 2 запускается при старте root-сессии, сразу после Phase 1. Если MEMORY.md пустой — скорее всего Phase 1 ещё не успел отработать (нужно ≥6 часов idle), либо память отключена в /memories.

Принудительно — пока нет UI-кнопки. Можно подождать.

Память «загрязнилась» случайным фактом

nano ~/.astracode/memories/<file>.md

Удалите неправильный фрагмент. Или попросите AstraCode:

Удали из памяти факт X. Он неверный.

MCP

MCP-сервер не запускается

/mcp verbose

Покажет статус и последнюю ошибку. Логи:

grep mcp:: ~/.astracode/log/astracode-tui.log

Типовое: - Сервер не установлен: command not found. Поставьте (npm install, pip install, ...). - Переменная окружения отсутствует: проверьте env_vars = [...]. - Таймаут: увеличьте startup_timeout_sec = 30.

MCP-tools не появляются у модели

Проверьте:

/mcp

Если сервер «not authenticated» — OAuth-вход через CLI: astracode mcp login <server> (в TUI у /mcp подкоманды auth нет — она принимает только verbose).

Если enabled = false — поставьте true в config.

После правки — перезапустите AstraCode.

Локализация

Интерфейс на английском, хочу русский

/locale ru

(Если не сработало — см. выше «only before first message».)

Или в config:

[tui]
locale = "ru"

И перезапуск.

Часть текстов на английском, часть на русском

Это норма — переведено не всё (например, имена slash-команд /cd, /help). Ответы модели — на языке, на котором вы пишете.

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

TUI «исчез» после Ctrl-Z

Вы случайно нажали Ctrl-Z (SIGTSTP) — AstraCode приостановился.

fg

Вернёт его. Или просто bg чтобы оставил в фоне (но тогда не управляется).

Чтобы Ctrl-Z вообще не работал в AstraCode — добавьте hook или перебиндите в /keymap.

Терминал «сломался» после выхода из AstraCode

Особенно если выход был не «чистый» (Ctrl-Z, kill). Восстановить:

reset
# или
stty sane

Иногда помогает:

tput reset

Файлы в проекте изменились, а я не помню

Сначала откройте /undo: AstraCode покажет записанные изменения файлов, сделанные агентом в текущем треде. Выберите запись, чтобы восстановить предыдущее состояние. Правки сабагента находятся в его собственном треде.

Если изменение сделано вручную, shell-командой или не попало в историю undo, проверьте Git:

git status
git diff

Откатить, если не нужно:

git checkout -- <file>

В будущем — approval_policy = "untrusted" для проектов, где не хотите изменений без явного согласия.

Сбор логов для bug-report'а

Если ничего не помогает:

# Самые свежие логи
tail -200 ~/.astracode/log/astracode-tui.log > /tmp/astracode-debug.txt

# Версия
astracode --version >> /tmp/astracode-debug.txt

Текущую конфигурацию удобно посмотреть внутри TUI через /debug-config (CLI-эквивалента debug-config нет; из командной строки доступны только astracode debug models / astracode debug app-server / astracode debug prompt-input — это отдельные диагностические подкоманды, а не дамп конфига).

Отправляйте через /feedback (категория Bug) — приложит метаданные автоматически. Не отправляйте secrets/, sessions/, rollout — они могут содержать ваш код и промпты.

Полный сброс

Когда всё сломалось и хочется начать с чистого листа:

# Бэкап (опционально):
tar czf astracode-backup.tar.gz ~/.astracode/config.toml ~/.astracode/skills/

# Сносим всё:
rm -rf ~/.astracode

# Запуск с нуля:
astracode

⚠️ Это удалит все ваши сессии, секреты, память, custom скиллы.

Куда писать, если ничего не помогло

• /feedback в TUI (категория Bug).
• GitHub issues (если репо публичный).
• Внутренний чат команды (если корпоративный).