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

AstraCode читает конфигурацию из иерархии слоёв:

Встроенные значения по умолчанию (в config крейте).
Managed-слой (managed_config.toml / MDM, если задан хостом).
~/.astracode/config.toml — основной пользовательский конфиг.
Проектный слой (конфиг проекта, при наличии).
CLI-флаги / session flags (-c key=value, --model, и т.д.) — высший приоритет.

Все секции конфига объединяются по правилам TOML (слияние секций, переопределение скаляров).

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

Единого поля «модель по умолчанию» в AstraCode нет: список моделей берётся из эндпоинта /v1/models выбранного провайдера, сама модель выбирается командой /model и сохраняется в [ui_state].last_used_model (см. §13). Поэтому в обычном сценарии перечисленные ниже поля вручную задавать не нужно — это необязательные переопределения:

toml

# Необязательные переопределения (как правило, задаются через /model, а не руками):
model = "glm-5.1"                        # переопределить активную модель (id из /v1/models провайдера)
model_provider = "provider-glm"          # из какого провайдера брать модель (см. §4)
model_context_window = 200000            # размер окна контекста в токенах (обычно определяется автоматически)
model_auto_compact_token_limit = 180000  # порог авто-предложения /compact

model_reasoning_effort = "medium"        # none | minimal | low | medium | high | xhigh
plan_mode_reasoning_effort = "high"      # усилие рассуждений в режиме /plan
model_verbosity = "medium"               # многословность ответа: low | medium | high
personality = "default"                  # стиль ответов

review_model = "claude-sonnet-4-6"       # модель для /review (если не задана — используется текущая)

model / model_provider — переопределения; имя модели должно совпадать с тем, что отдаёт /v1/models провайдера. Если ни model, ни сохранённое [ui_state].last_used_model не заданы, AstraCode считает модель ненастроенной и предложит выбрать её через /model.
model_auto_compact_token_limit — порог, при котором AstraCode сам предложит /compact.

Конкретные имена моделей (glm-5.1, claude-sonnet-4-6 и т.п.) приведены как примеры — подставляйте те, что доступны у вашего провайдера.

2. Sandbox

toml

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

[sandbox_workspace_write]
writable_roots = ["/home/timur/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-request"   # untrusted | on-request | on-failure | granular | never (по умолчанию on-request; on-failure устарел)
approvals_reviewer = "user"      # user | auto_review (по умолчанию user)

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

[permissions.default]
read = "always"                  # always | prompt | never
write = "prompt"
shell = "prompt"
network = "never"

approvals_reviewer = "auto_review" (синоним — guardian_subagent) включает режим авто-проверки: запросы на подтверждение обрабатывает сабагент-«страж», а не пользователь. См. команду /autoreview в 04-slash-commands.md.

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 = true
status_line = ["model", "tokens", "branch"]
terminal_title = ["thread_title", "model"]

[tui.keymap]
# Привязки задаются по контекстам: global / chat / composer / editor / pager / list / approval.
# Переопределяются только настраиваемые действия (некоторые клавиши — ctrl-c, esc, символы / @ $ ! —
# зарезервированы и не переназначаются).
composer.submit = "enter"
composer.newline = "shift-enter"

Полный список контекстов, действий и зарезервированных клавиш — в 12-keymap.md.

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

7. Память

toml

[features]
memories = true                          # мастер-выключатель (по умолчанию false — память выключена)

[memories]
generate_memories = true                 # дефолт true, но без эффекта при выключенном feature-флаге
use_memories = true                      # дефолт true
disable_on_external_context = false
max_raw_memories_for_consolidation = 256 # дефолт 256
max_rollout_age_days = 10                # дефолт 10
min_rollout_idle_hours = 6               # дефолт 6
extract_model = "claude-haiku-4-5"
consolidation_model = "claude-sonnet-4-6"

Память — экспериментальная функция, по умолчанию выключена. Без [features] memories = true настройки [memories] не действуют. Подробнее — 07-memories.md.

8. Хуки

matcher — это regex по имени инструмента (Bash, Edit|Write, mcp__<server>__.*, * — для всех), а не выражение. Данные события приходят команде JSON-ом в stdin (а не через переменные окружения). Поддерживается только обработчик type = "command".

toml

[[hooks.PreToolUse]]
matcher = "Bash"
hooks = [
  # JSON события читается из stdin; пример — записать имя инструмента в лог:
  { type = "command", command = "jq -r .tool_name >> ~/tool.log", timeout = 5 },
]

Подробнее (поля события, форматы matcher, что не реализовано) — 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 = "rollouts"   # rollouts | none
max_messages = 1000

[shell_environment_policy]
inherit = "minimal"        # all | minimal | none
allow = ["PATH", "HOME", "USER", "LANG", "TERM"]
deny = ["SECRET_*"]

shell_environment_policy фильтрует env переменные, которые видны командам, запускаемым агентом — защита от случайной утечки секретов.

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

toml

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

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

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

12. Logging и SQLite

toml

log_dir = "/home/timur/.astracode/log"
sqlite_home = "/home/timur/.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 = "..."

Эту секцию не нужно редактировать вручную.

14. Feature flags

toml

[features]
memories = true
realtime = false
plugins = false
collaboration_modes = true
goal_command = true
personality_command = false
audio_device_selection = false
elevate_sandbox = true

Управляют видимостью команд и фич в TUI. Команда /experimental показывает текущие флаги.

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

Переменная	Эффект
`ASTRACODE_HOME`	Альтернатива `~/.astracode/`. Должна существовать.
`ASTRACODE_SQLITE_HOME`	Где лежат `state_*.sqlite`.
`ASTRACODE_LOCALE`	`en` / `ru` / `russian` / `ru_RU` — переопределяет `[tui].locale`.
`ASTRACODE_CA_CERTIFICATE`	Корневой CA в PEM (для on-prem с self-signed).
`SSL_CERT_FILE`	Fallback для CA.
`ASTRACODE_NO_TELEMETRY`	Отключить телеметрию.
`ASTRACODE_ESCALATE_SOCKET`	(системная) сокет для shell-escalation, не трогать вручную.
`LANG`, `LC_MESSAGES`	Учитываются при автодетекте локали.
`HTTP_PROXY` / `HTTPS_PROXY` / `NO_PROXY`	Стандартные HTTP-прокси.

16. CLI-флаги

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

bash

astracode -c model=glm-5.1 -c sandbox_mode=read-only
astracode -c 'tui.locale="en"'

Также есть короткие псевдонимы: --model, --provider, --sandbox, --approval, --locale.

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

В TUI:

text

/debug-config

Покажет все слои с источниками значений (где переопределено: дефолт / managed / config.toml / проект / CLI).

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-request"

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

[shell_environment_policy]
inherit = "minimal"
deny = ["AWS_*", "GITHUB_TOKEN", "*_API_KEY"]