03. Конфигурация — AstraCode — Техническая документация

AstraCode собирает эффективную конфигурацию из упорядоченного стека слоёв. Точный набор зависит от платформы и запуска, но в него могут входить:

managed requirements и MDM/admin policy;
системный config.toml;
пользовательский $ASTRACODE_HOME/config.toml;
project-конфиги .astracode/config.toml, найденные от рабочей директории к корню репозитория;
session/runtime flags, включая CLI overrides (-c, --model и т.д.).

Слои объединяются от низкого приоритета к высокому. Project-слои не активируются для недоверенного проекта. Legacy managed config поддерживается отдельно и может иметь административно заданный приоритет и requirements. Фактический стек и источники значений показывает /debug-config; считать пользовательский файл единственным config-файлом нельзя.

1. Параметры модели

Настройки из TUI

/model выбирает активную пару «провайдер + модель» и сохраняет её в [ui_state].last_used_provider и [ui_state].last_used_model. Поэтому в обычной конфигурации не нужно дублировать этот выбор устаревшими top-level полями model и model_provider. В частности, явно заданный model_provider имеет приоритет над сохранённым выбором /model при следующем запуске.
/personality выбирает стиль общения только для текущей сессии и не меняет config.toml.
Alt+, и Alt+. понижают и повышают поддерживаемый текущей моделью уровень reasoning. В обычном режиме меняется model_reasoning_effort текущей сессии, а в Plan mode — Plan-specific override. Эти изменения не сохраняются в config.toml.

Постоянные настройки в `config.toml`

toml

model_reasoning_effort = "medium"      # none | minimal | low | medium | high | xhigh
plan_mode_reasoning_effort = "high"
model_verbosity = "medium"             # low | medium | high
personality = "none"                   # none | friendly | pragmatic

# Необязательно: модель должна быть доступна у текущего провайдера.
# review_model = "model-id-from-current-provider"

model_reasoning_effort задаёт глобальный уровень reasoning по умолчанию.
plan_mode_reasoning_effort переопределяет его для Plan mode. Отдельного постоянного меню для этих двух параметров нет.
model_verbosity управляет подробностью ответа только у моделей, которые поддерживают verbosity. Для остальных моделей значение игнорируется с предупреждением.
personality задаёт начальный стиль для новых сессий. Значения default нет; нейтральному стилю соответствует none.
review_model используется командой /review; отдельного picker для неё нет. Если параметр не задан, используется активная модель. review_model меняет только ID модели, но не провайдера, поэтому выбранная модель должна быть доступна у текущего провайдера.

Экспертные overrides метаданных модели

model_context_window и model_auto_compact_token_limit можно задать вручную, но обычно этого делать не следует: значения берутся из каталога выбранной модели и автоматически меняются вместе с ней.

model_context_window переопределяет известный AstraCode размер контекстного окна, но ограничивается максимумом модели и внутренним пределом 200 000 токенов. Неверное значение искажает индикатор контекста и момент сжатия.
model_auto_compact_token_limit задаёт порог, при достижении которого AstraCode автоматически запускает сжатие истории, а не только предлагает выполнить /compact. При известном контекстном окне эффективный порог не превышает 70% окна и 120 000 токенов. Например, значение 180000 при окне 200000 фактически даст порог 120000.

2. Sandbox

toml

sandbox_mode = "workspace-write"  # read-only | workspace-write | danger-full-access

[sandbox_workspace_write]
writable_roots = ["/home/user/work/myproject", "/tmp/scratch"]
network_access = false
exclude_tmpdir_env_var = false
exclude_slash_tmp = false

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

3. Approvals (разрешения)

toml

approval_policy = "on-failure"   # untrusted | on-failure | on-request | never
approvals_reviewer = "user"      # user | guardian_subagent (алиас: auto_review)

# Глобальный профиль разрешений по умолчанию.
default_permissions = "default"

[permissions.default.filesystem]
":minimal" = "read"              # read | write | none
"." = "write"

[permissions.default.network]
enabled = false

approvals_reviewer = "guardian_subagent" использует второго субагента-ревьюера для принятия решений на основе рисков. auto_review — алиас для guardian_subagent.

4. Провайдеры моделей

toml

default_provider = "openai"

[[providers]]
id = "openai"
display_name = "OpenAI"
base_url = "https://api.openai.com/v1"

[[providers]]
id = "local-astra"
display_name = "Local AstraCode"
base_url = "http://172.16.20.83:8000/v1"

[[providers]]
id = "provider-glm"
display_name = "Zhipu GLM"
base_url = "https://api.z.ai/api/coding/paas/v4"

API-ключи не хранятся в config.toml. Они шифруются в ~/.astracode/secrets/local.age и привязываются к ID провайдера. См. 10-providers.md.

5. MCP-серверы

toml

[mcp_servers.example_stdio]
command = "python"
args = ["-m", "my_mcp_server"]
env_vars = ["MY_TOKEN"]
cwd = "/path/to/dir"
enabled = true
required = false
default_tools_approval_mode = "prompt"   # auto | prompt | approve
startup_timeout_sec = 10
supports_parallel_tool_calls = true

[mcp_servers.example_stdio.tools.dangerous_tool]
approval_mode = "prompt"

[mcp_servers.example_http]
url = "https://mcp-server.example.com"
bearer_token_env_var = "MCP_AUTH_TOKEN"
http_headers = { "X-Custom" = "value" }

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

6. TUI

toml

[tui]
locale = "ru"                    # en | ru
theme = "default"
animations = true
show_tooltips = true
alternate_screen = "auto"              # auto | always | never
status_line = ["model", "tokens", "branch"]
terminal_title = ["thread_title", "model"]

[tui.keymap]
# Поддерживаемые контексты: global, chat, composer, editor,
# pager, list, approval.
global.open_transcript = "ctrl-t"
global.copy = ["ctrl-o", "alt-c"]
composer.submit = "enter"
editor.insert_newline = ["shift-enter", "ctrl-j"]
pager.close = "q"

Подробнее — 11-localization.md, 12-keymap.md.

7. Память

toml

[memories]
generate_memories = true
use_memories = true
disable_on_external_context = false
max_raw_memories_for_consolidation = 50
max_rollout_age_days = 30
min_rollout_idle_hours = 4
extract_model = "claude-haiku-4-5"
consolidation_model = "claude-sonnet-4-6"

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

8. Хуки

toml

[[hooks.PreToolUse]]
matcher = "Bash"
hooks = [
  { type = "command", command = "jq -r '.tool_name' >> /tmp/astracode-tools.log", timeout = 5 },
]

[[hooks.PostToolUse]]
matcher = "^mcp__"
hooks = [
  { type = "command", command = "jq -r '.tool_name' >> /tmp/astracode-mcp.log", timeout = 5 },
]

Hook получает JSON события через stdin. Shell-like tools имеют hook-имя Bash; имена exec и local_shell matcher не увидит. Expression DSL и исполняемые prompt/agent/async handlers пока не поддерживаются. PostToolUse запускается только после успешного результата и только для tools, handlers которых формируют hook-payload.

Отдельный top-level параметр notify = ["/path/to/program", "--arg"] — это legacy after-agent notification: JSON передаётся последним argv-аргументом, а не через hook stdin.

Подробнее — 08-hooks.md.

9. Инструкции и приложения

toml

instructions = """
You are working on the AstraCode project.
Prefer Rust idioms. Use rustfmt before committing.
"""

developer_instructions = """
Run `cargo test --workspace` before claiming a task done.
"""

[apps._default]
enabled = true
approval_mode = "prompt"

[apps.git_review]
enabled = true
approval_mode = "approve"

[apps.git_review.tools]
push = "prompt"
force_push = "prompt"

10. История и shell

toml

[history]
persistence = "save-all"   # save-all | none
max_bytes = 10485760        # опциональный предел history file

[shell_environment_policy]
inherit = "core"           # all | core | none
set = { PATH = "/usr/bin", HOME = "/home/me" }
include_only = ["PATH", "HOME", "USER", "LANG", "TERM"]
exclude = ["SECRET_*", "*_TOKEN", "*_KEY"]

shell_environment_policy фильтрует env переменные, которые видны командам, запускаемым агентом — защита от случайной утечки секретов. set — задаёт конкретные значения; include_only — whitelist-паттерны; exclude — blacklist-паттерны (glob */?).

11. Проекты и доверие

toml

[projects."/home/user/work/myproject"]
trust_level = "trusted"    # trusted | untrusted

[projects."/tmp"]
trust_level = "untrusted"

Для trusted проектов AstraCode может стартовать сразу в workspace-write без вопроса.

12. Logging и SQLite

toml

log_dir = "/home/user/.astracode/log"
sqlite_home = "/home/user/.astracode"    # или через ASTRACODE_SQLITE_HOME

13. UI state (автоматический)

AstraCode сам пишет в config.toml секцию [ui_state] при изменениях:

toml

[ui_state]
last_used_provider = "provider-glm"
last_used_model = "glm-5.1"
last_thread_id = "..."
custom_agent_model = { provider = "local", model = "glm-5.1" }

# Назначения моделей для ролей субагентов (через /submodel)
[ui_state.role_models.explorer]
provider = "local"
model = "glm-5.1"

[ui_state.role_models.worker]
provider = "remote"
model = "qwen3-coder"

role_models — map по имени роли (explorer, worker, …). Когда у роли есть запись, субагенты с этой ролью используют именно этот (provider, model); отсутствие записи = наследование модели/провайдера родителя. Оба поля обязательны: одно имя модели может быть у нескольких провайдеров. custom_agent_model — общее назначение для всех user-defined ролей. Удаление провайдера через /model (d) очищает ссылающиеся role assignments, а для active/default провайдера ещё default_provider и устаревшую top-level model. Эту секцию не нужно редактировать вручную.

14. Feature flags

toml

[features]
memories = true
realtime_conversation = false
plugins = true
astracode_hooks = true
plugin_hooks = true
collaboration_modes = true
goals = true
personality = true
apps = true
fast_mode = true
artifact = false
code_mode = false

Управляют видимостью команд и фич в TUI. Команда /experimental показывает текущие флаги. Полный список ключей — в enum Feature (features/src/lib.rs); ниже основные пользовательски-релевантные (дефолты указаны для обычной сборки):

Ключ	Default	Назначение
`memories`	`false`	Startup memory extraction + file-backed consolidation
`realtime_conversation`	`false`	Экспериментальный голосовой режим в TUI
`plugins`	`true`	Загрузка и использование плагинов
`astracode_hooks`	`true`	Lifecycle command-hooks из config, requirements и plugins
`plugin_hooks`	`true`	Загрузка hook sources активных плагинов; исполнение также требует `astracode_hooks`
`collaboration_modes`	`true`	Режимы ответа Default/Plan — ключ оставлен для back-compat, поведение всегда включено
`goals`	`true`	`/goal` и автопродолжение цели
`personality`	`true`	Выбор personality в TUI
`apps`	`true`	Apps / коннекторы
`fast_mode`	`true`	Fast mode в TUI и request layer
`artifact`	`false`	Native artifact tools
`code_mode`	`false`	JavaScript code mode поверх V8
`apply_patch_freeform`	`false`	Freeform apply_patch tool
`multi_agent`	`true`	Стабильный v1 multi-agent API (`fork_context`, UUID-адресация)
`multi_agent_v2`	`false`	Task-path multi-agent routing
`enable_fanout`	`false`	Экспериментальные CSV agent jobs
`sqlite`	`true`	Persist rollout metadata в SQLite

Ключи audio_device_selection, elevate_sandbox, goal_command, personality_command в коде не существуют — используйте перечисленные выше. Неизвестные ключи в [features] игнорируются (is_known_feature_key).

15. Переменные окружения

Переменная	Эффект
`ASTRACODE_HOME`	Альтернатива `~/.astracode/`. Должна существовать.
`ASTRACODE_SQLITE_HOME`	Где лежат `state_*.sqlite`.
`ASTRACODE_PROVIDER_SECRETS_KEY_STORAGE`	Хранилище ключа provider secrets: `auto`, `file` или `keyring`.
`ASTRACODE_LICENSE_KEY_STORAGE`	Backend состояния лицензии: `auto`, `file` или `keyring`.
`ASTRACODE_LICENSE_DISABLE_KEYRING`	`1` принудительно включает file-only license storage.
`ASTRACODE_LICENSE_ENFORCE`	`1` включает license gate даже в сборке без default feature; отключить gate licensed-сборки через env нельзя.
`ASTRACODE_LOCALE`	`en` / `ru` / `russian` / `ru_RU` — переопределяет `[tui].locale`.
`ASTRACODE_CA_CERTIFICATE`	Корневой CA в PEM (для on-prem с self-signed).
`SSL_CERT_FILE`	Fallback для CA.
`ASTRACODE_ESCALATE_SOCKET`	(системная) сокет для shell-escalation, не трогать вручную.
`LANG`, `LC_MESSAGES`	Учитываются при автодетекте локали.
`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`	Стандартные HTTP-прокси.

Подробнее о license-specific переменных и persistence — в 24-license.

16. CLI-флаги

astracode принимает overrides через -c:

bash

astracode -c model=gpt-5 -c sandbox_mode=read-only
astracode -c 'tui.locale="en"'

Также есть флаги: --model / -m, --sandbox / -s, --ask-for-approval / -a, --locale, --cd / -C, --add-dir, --image / -i, --dangerously-bypass-approvals-and-sandbox. Флага --provider и --approval нет — провайдер выбирается через model_provider в конфиге или /model в TUI, а approval — через --ask-for-approval.

17. Просмотр текущего конфига

bash

/debug-config

В TUI команда /debug-config (SlashCommandId::DebugConfig) показывает все слои с источниками значений (где переопределено: дефолт / config.toml / CLI). CLI-подкоманды astracode debug-config не существует; для CLI-отладки есть astracode debug models / astracode debug prompt-input.

18. Примеры

Минимальный конфиг для on-prem:

toml

model = "glm-5.1"
model_provider = "provider-glm"

[[providers]]
id = "provider-glm"
base_url = "https://api.z.ai/api/coding/paas/v4"

[tui]
locale = "ru"

[features]
memories = true

Конфиг для безопасной разработки:

toml

sandbox_mode = "workspace-write"
approval_policy = "on-failure"

[sandbox_workspace_write]
network_access = false
writable_roots = ["/home/me/work"]

[shell_environment_policy]
inherit = "core"
exclude = ["AWS_*", "GITHUB_TOKEN", "*_API_KEY"]

1. Параметры модели

Настройки из TUI

Постоянные настройки в config.toml

Экспертные overrides метаданных модели

2. Sandbox

3. Approvals (разрешения)

4. Провайдеры моделей

5. MCP-серверы

6. TUI

7. Память

8. Хуки

9. Инструкции и приложения

10. История и shell

11. Проекты и доверие

12. Logging и SQLite

13. UI state (автоматический)

14. Feature flags

15. Переменные окружения

16. CLI-флаги

17. Просмотр текущего конфига

18. Примеры

Постоянные настройки в `config.toml`