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 — для делегации.

Чем отличается от codex (upstream)?

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

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

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 (ChaCha20-Poly1305 с scrypt-деривацией ключа из парольной фразы). Master-ключ хранится в OS keyring; если keyring недоступен (например, на headless-сервере) — используется fallback-файл ~/.astracode/secrets/local.key. Без доступа к keyring (или к local.key) расшифровать local.age нельзя.

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

Sandbox + approvals защищают от случайностей: - Не пишет в .git/, .astracode/, .agents/ никогда. - Не пишет вне writable_roots без approval'а. - Не запускает сетевые запросы без флага.

Но никакая защита не абсолютна. Если сами разрешили Allow always чему-то опасному — ничего не остановит.

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

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

Зависит от провайдера. Грубо: - Дешёвые модели (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 для несвязанных задач.
  • Использовать дешёвую модель для рутины, дорогую — для сложного.
  • Выключать неиспользуемые скиллы через /skills.
  • /side для уточнений, чтобы не раздувать основной контекст.

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

text
/diff

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

text
/resume

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

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

text
/review

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

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

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

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

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

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

Да. В версии 0.5.1 используйте /undo: откроется picker изменений файлов, записанных перед apply_patch или write_file. Выберите правку и подтвердите восстановление. /undo <call_id> отменяет конкретное изменение.

Undo восстанавливает сохранённые байты файла, поэтому работает и для бинарных файлов; файл, созданный агентом, будет удалён. Redo пока нет. Изменения сабагента хранятся в его собственном треде, поэтому отменять их нужно там.

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

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

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

Это вызов tool'а моделью — например, exec_command (shell), apply_patch (изменение файла), list_dir и т.п. Такие действия выполняются с текущими ограничениями sandbox и при необходимости требуют вашего подтверждения.

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

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

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

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

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

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

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

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

/side — это что?

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

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

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

Если bwrap всё равно не запускается (например, в контейнере без --privileged) — используйте landlock: он настраивается через [features] в config (use_legacy_landlock), а не через CLI-флаг. Либо поднимите AstraCode с sandbox_mode = "danger-full-access", если контейнер уже сам изолирует систему. См. 15-troubleshooting.md.

use_legacy_landlock помечен DEPRECATED и будет удалён. Предпочтительный способ — astracode sandbox linux (видимое имя landlock) и текущий sandbox-режим. Подробнее — 15-troubleshooting.md.

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

  • 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. Варианты: включить landlock через [features] в config (use_legacy_landlock) — это не CLI-флаг, а настройка features — либо поднять AstraCode с sandbox_mode = "danger-full-access" (рискованно, только если container уже изолирован).

use_legacy_landlock помечен DEPRECATED и будет удалён. Предпочтительный способ — astracode sandbox linux (видимое имя landlock).

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

TUI — основной интерфейс AstraCode. При этом существует и активно развивается app-server backend (app-server + app-server-protocol) — он предназначен для интеграции с внешними клиентами, включая VS Code и web-клиенты. Полноценного packaged VS Code-расширения в репозитории пока нет (оно в разработке), но бэкенд для такой интеграции уже есть.

Пока расширения нет — можно запустить AstraCode в интегрированном терминале VS Code, он будет работать как обычно.

Сравнение

AstraCode vs Aider?

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

AstraCode vs Continue?

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

AstraCode vs OpenAI Codex CLI?

AstraCode — форк codex с расширениями. Если важна русская локализация, /goal, расширенные скиллы — AstraCode. Если нужна upstream-совместимость — codex.

Прочее

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

Этот user guide — основная документация для пользователей AstraCode.

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

text
/feedback

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

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

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

text
/feedback

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

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

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

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

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

Что в roadmap?

Из обозримых направлений (зависит от форка): - Packaged VS Code extension поверх app-server backend. - Дополнительные платформы и варианты сборок. - Дальнейшее развитие collaboration modes и пользовательских ролей сабагентов. - Расширение /personality. - Улучшение Memory Phase 2.

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

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

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