0.4.11
Поиск по документации… ⌘K
16 · Руководство пользователя

16. FAQ — частые вопросы

Общие

Что такое AstraCode?

TUI-агент кодинга на Rust. Вы пишете задачу обычным текстом, он читает ваш код, запускает команды, редактирует файлы, и объясняет, что делает. Под капотом — большая языковая модель (GPT, Claude, или локальная).

Чем отличается от ChatGPT / Claude в браузере?

  • AstraCode видит ваш код напрямую (не нужно копировать).
  • Может запускать команды (тесты, сборка, git).
  • Может редактировать файлы (с вашего разрешения).
  • Запоминает контекст между сессиями (если включить память).
  • Работает в терминале, можно интегрировать в workflow (tmux, vim и т.п.).

Чем отличается от Cursor / Copilot?

  • Cursor / Copilot — в IDE, синхронное автодополнение и refactor.
  • AstraCode — в терминале, асинхронный «агент» для долгих задач.

Они дополняют друг друга, а не конкурируют. Cursor — для активного кодинга; AstraCode — для делегации.

Чем отличается от других LLM-фронтендов в терминале?

AstraCode заточен под российские команды и on-prem инфраструктуру: - Полная русская локализация (TUI на двух языках, локализованы команды, ошибки, отчёты ревью). - Долгие задачи через /goal с бюджетом токенов и продолжением через /resume. - Голосовой режим (realtime). - Расширенные скиллы (русские описания, неявная активация по контексту). - Локализованный /help с pager'ом. - Поддержка кастомных on-prem provider'ов (включая в-процесс Chat Completions bridge). - Лицензирование через offline-подписанные ключи. - Мультиагентные треды. - Дополнительные slash-команды (/cd popup, /sandbox-add-read-dir, /index).

Безопасность и приватность

AstraCode видит мой код?

Только когда вы запросите. AstraCode сам не сканирует — каждое чтение происходит через read_file / list_dir / exec_command tools, по запросу модели. Контент уходит в provider'а (OpenAI / Anthropic / ваш on-prem).

Мой код попадает в обучение модели?

Зависит от провайдера: - OpenAI API — по умолчанию данные не используются для тренировки (если у вас не enterprise / opt-in). - Anthropic API — то же. - Локальный LLM — данные не уходят никуда вообще.

Читайте политики конкретных провайдеров.

Можно ли работать с конфиденциальным кодом?

Если используете cloud LLM — формально код уходит провайдеру. Решения: - Локальный LLM (Llama, Qwen, DeepSeek через vLLM / Ollama). - On-prem gateway компании. - Дополнительные guardrails — [shell_environment_policy] для фильтрации env.

См. 13-safety.md.

Где хранятся мои API-ключи?

В ~/.astracode/secrets/local.age — зашифрованы с помощью age (passphrase хранится в системном хранилище ключей ОС — OS keyring). Без вашего входа в ОС расшифровать нельзя.

Может ли AstraCode сделать что-то плохое с моими файлами?

Песочница (sandbox) и подтверждения (approvals) защищают от случайностей: - По умолчанию не пишет за пределами рабочей директории без вашего подтверждения. - Не выходит в сеть без отдельного разрешения. - Опасные действия требуют подтверждения в диалоге.

Но никакая защита не абсолютна. Если вы сами разрешили выполнять что-то опасное «не спрашивать снова» — ничего не остановит.

Использование

Сколько это стоит?

Зависит от провайдера. Грубо: - Дешёвые модели (haiku, mini): $0.5-2 / день при активной работе. - Средние (sonnet, 4o): $5-20 / день. - Большие (opus, GPT-5): $20-100 / день.

/status показывает текущий расход в сессии. У провайдеров есть dashboards (platform.openai.com/usage, console.anthropic.com).

Как сэкономить токены?

  • /compact при длинной сессии.
  • /new для несвязанных задач.
  • Использовать дешёвую модель для рутины, дорогую — только когда нужно.
  • model_reasoning_effort = "low" или "none" для простых задач.
  • Отключить лишние скиллы (/skills).

Можно ли использовать без интернета?

Да — через локальную LLM: - Ollama (http://localhost:11434/v1). - llama.cpp server. - vLLM.

Качество ниже, чем у GPT-5 / Claude, но всё работает.

См. 06-model-and-providers.md.

Можно ли работать с большим репозиторием?

Да, но: - Контекст модели ограничен (обычно от ~128k до ~1M токенов в зависимости от модели). Весь репозиторий в него не вместится. - AstraCode не пытается читать всё — только то, что попросите или что нужно для задачи. - Для огромных репо — узкие задачи в /cd <subdirectory>. - AGENTS.md с указаниями типа «не лезь в /legacy» поможет фокусу.

Как остановить ответ модели?

Esc.

Как выйти из AstraCode?

Ctrl-C дважды (одно нажатие прерывает текущий ответ, второе — выходит).

Или команда /quit.

Можно ли использовать в CI/CD?

Скорее нет для типичного AstraCode-flow — это интерактивный TUI с approvals. Для headless:

bash
astracode exec "запусти тесты и почини если упадут"

С approval_policy = "never" — но это рискованно для автоматизации. Лучше — обычные CI-инструменты.

Можно ли использовать с несколькими репозиториями параллельно?

Да: - В разных терминалах одновременно (каждая — свой cwd). - Или в одном через /cd.

Подробнее — 05-working-with-project.md.

Команды и интерфейс

Как переключиться на русский?

text
/locale ru

Только до первого сообщения в сессии. Иначе /new, потом /locale ru.

Постоянно — в ~/.astracode/config.toml:

toml
[tui]
locale = "ru"

Как сменить модель посреди сессии?

text
/model

Picker → выбрать → активируется со следующего turn'а.

Как открыть git diff в полный экран?

text
/diff

Как продолжить вчерашнюю работу?

text
/resume

Picker всех сохранённых сессий — выберите. История восстановится.

Как сделать code review своих изменений?

text
/review

Меню — выберите цель ревью. Или сразу:

text
/review проверь безопасность

Что делать, если модель не понимает, что я хочу?

Дайте больше контекста. Чем конкретнее задача — тем лучше:

Плохо: «почини».
Хорошо: «в @src/auth.rs функция verify_token возвращает Unauthorized для валидных токенов с пробелами в конце — добавь trim()».

Можно ли отменить изменения, которые сделал AstraCode?

Да, через git:

bash
git status
git diff
git checkout -- <file>     # откатить файл
git reset HEAD~1            # откатить последний коммит (если committed, не запушено)

Что значит 🔧 Tool: ... в чате?

Это вызов инструмента (tool) моделью — например, exec_command (shell-команда), apply_patch (изменение файла), list_dir и т.п. Подробнее — Каталог инструментов (dev-вики).

Как добавить новый MCP-сервер?

Через ~/.astracode/config.toml:

toml
[mcp_servers.my_server]
command = "..."
args = [...]

Подробнее — 11-mcp.md.

Что такое /goal и когда использовать?

/goal — для долгих задач на день и больше. Цель переживает /new и перезапуск.

text
/goal Реализовать OAuth-вход

Подробнее — 07-goals.md.

/side — это что?

Побочный разговор для уточнений, не загрязняющий основную задачу.

text
/side как работает Arc<Mutex<T>>?

Esc — закрыть. Главная задача продолжается, не «увидев» вопроса.

Подробнее — 09-side-conversations.md.

Что такое /autoreview и «авто-проверка»?

«Авто-проверка» (auto-review) — это режим, в котором запросы на подтверждение действий агента (запуск команды, правка файла, выход в сеть) обрабатывает не вы, а специальный сабагент-«страж»: он оценивает риск и сам разрешает или отклоняет действие. Режим включается в настройках подтверждений (/approvals, пресет «Авто-проверка»).

Команда /autoreview открывает список последних действий, которые страж отклонил (до 10). Выбрав отклонённое действие, вы вручную разрешаете один его повтор.

text
/autoreview

Ожидаемая реакция: - Если отказов не было — сообщение «В этом треде нет недавних отказов авто-проверки». - Если были — список отклонённых действий с обоснованием; после выбора AstraCode сообщит, что разрешение записано. Важно: повтор всё равно снова пройдёт авто-проверку.

Что делают /agent и /subagents?

Это две формы одной команды — они открывают список агентных тредов («Subagents») и позволяют переключиться между ними. Отдельной команды /agents нет.

text
/agent

Важно: эти команды не создают субагентов — они только переключают, какой тред вы сейчас видите. Субагентов запускает сама модель в ходе сложной задачи. Переключаться между тредами можно также горячими клавишами Alt+← / Alt+→.

Скиллы и расширения

Что такое скиллы?

Специализации агента — markdown + опциональные скрипты. Активируются по $<name> или автоматически. Помогают агенту лучше работать в конкретной области (PDF, web design, code review, и т.п.).

Подробнее — 10-skills.md.

Как поставить новый скилл?

Через встроенный скилл skill-installer — введите в строке ввода $skill-installer и укажите источник на GitHub. Репозиторий не захардкожен: нужно явно задать его и путь к папке скилла внутри репозитория.

Конкретный пример — установка скилла pdf из реального публичного репозитория github.com/anthropics/skills:

text
$skill-installer --repo anthropics/skills --path skills/pdf

или через URL:

text
$skill-installer --url https://github.com/anthropics/skills/tree/main/skills/pdf

Папка скилла обязана содержать SKILL.md. Голый адрес репозитория без пути к папке скилла не сработает (установщик попросит --path). Подробнее и про формат репозитория — 10-skills.md.

Или вручную: скопируйте папку скилла в ~/.astracode/skills/<name>/.

Как написать свой скилл?

text
$skill-creator

Проведёт через шаги: имя, описание, default_prompt.

Скиллы безопасны?

Если скилл содержит scripts/ — они выполняются с правами sandbox (как любая shell-команда, с approval'ом). Не ставьте скиллы из недоверенных источников.

Память

Что такое память?

Долгосрочные факты, которые AstraCode помнит между сессиями: ваш стиль, контекст проекта, предпочтения. Хранятся в ~/.astracode/memories/.

Подробнее — 12-memory.md.

Как включить память?

В TUI: /memories → согласиться включить функцию → включить оба переключателя (Use memories и Generate memories). По умолчанию память выключена (экспериментальная функция).

В IDE-плагине всплывающего окна нет — включайте через ~/.astracode/config.toml, причём нужен и мастер-флаг функции:

toml
[features]
memories = true

[memories]
use_memories = true
generate_memories = true

Почему агент говорит «запомнил», но не запоминает?

Это ожидаемое поведение. Агент не пишет память во время диалога — у него нет такого инструмента. Память наполняет отдельный фоновый процесс, который разбирает ваши прошлые («отлежавшиеся») сессии при следующих запусках AstraCode. Поэтому только что сказанное в память сразу не попадёт, а просьба «запомни» в текущем разговоре ничего не сохранит. Подробнее — 12-memory.md.

Можно ли удалить, что AstraCode о мне помнит?

Да, но только вручную — агент не может править память по просьбе: - Конкретный факт — отредактируйте файл в ~/.astracode/memories/. - Всё — «Сбросить всю память» (Reset all memories) через /memories.

Ошибки и проблемы

Failed to decrypt secrets file

OS keyring потерял master-ключ. Лечение:

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

См. 15-troubleshooting.md.

bwrap: Permission denied

Linux выключил unprivileged user namespaces:

bash
sudo sysctl kernel.unprivileged_userns_clone=1

Модель отвечает медленно

  • Reasoning высокий — снизить (model_reasoning_effort = "low").
  • Большая история — /compact или /new.
  • Слабая локальная LLM — переключиться на cloud.
  • Провайдер перегружен — подождать или сменить.

TUI не запускается / висит

Ctrl-C несколько раз. Если не помогло:

bash
kill -9 $(pgrep astracode)

Потом разобраться в ~/.astracode/log/astracode-tui.log (см. 15-troubleshooting.md).

Платформы

Работает на Windows?

Да, но в degraded режиме: sandbox через AppContainer (ограниченная функциональность). Лучше — WSL2 или Linux/macOS виртуалка.

Работает на ARM Mac?

Да — есть нативные сборки astracode-macos (arm64).

Можно ли в Docker?

Да, но bwrap не работает в обычном Docker без --privileged. Вариант — запустить AstraCode с sandbox_mode = "danger-full-access" (рискованно; оправдано, только если сам контейнер уже изолирован). Подробнее про режимы песочницы — 13-safety.md.

Поддерживается ли в VS Code?

Расширения нет (это TUI). Можете запустить AstraCode в интегрированном терминале VS Code — будет работать как обычно.

В roadmap есть планы на VS Code extension.

Сравнение

AstraCode vs Aider?

Похожие концепции. AstraCode — Rust, ориентирован на интеграцию с провайдерами, имеет sandboxing, /goal, скиллы, MCP. Aider — Python, более старый, активный community.

AstraCode vs Continue?

Continue — VS Code extension с автодополнением. AstraCode — TUI-агент для делегации задач. Разные ниши.

AstraCode для команд с on-prem инфраструктурой?

Да — это один из основных use cases. Поддерживаются кастомные провайдеры через OpenAI-совместимый протокол (vLLM, llama.cpp, LiteLLM, Ollama и т. п.). В 0.4.11 добавлен in-process Chat Completions bridge — даже если ваш upstream отвечает только в Chat Completions формате, AstraCode сам транслирует. Лицензия offline (не нужно интернет-callback'ов).

Прочее

Где живёт документация?

Как сообщить о баге?

text
/feedback

Категория Bug → описание. Отправит метаданные + ваш текст (без логов и кода).

Или GitHub issues, если репо публичный.

Как предложить фичу?

text
/feedback

Категория Other. Описание идеи.

Где обсуждение / community?

См. репозиторий проекта. Конкретные ссылки зависят от вашей установки (внутренний чат / GitHub Discussions / Discord).

Можно ли использовать AstraCode коммерчески?

Лицензия в репозитории (LICENSE). Кратко — обычно да, но проверьте именно версию, которую используете.

Что в roadmap?

Из обозримых направлений: - VS Code extension. - Параллельные сборки (musl Linux, x86_64 macOS). - Доп. collaboration modes. - Расширение /personality. - Улучшение Memory Phase 2.

Конкретные планы — в issue tracker'е проекта.

Если ваш вопрос не здесь

  1. /help <команда> — встроенная справка.
  2. $astracode-help — встроенный скилл с подробными ответами.
  3. 15-troubleshooting.md — типовые проблемы.
  4. Техническая документация (dev-вики) — для глубоких вопросов.
  5. /feedback (категория Other) — задайте напрямую разработчикам.
ESC