# Справочник по конфигурации dbt Wizard [Бета-версия](https://docs.getdbt.tech/docs/dbt-versions/product-lifecycles "Подробнее о статусе или тарифе") Локальная разработка dbt Wizard хранит конфигурацию в двух файлах TOML в каталоге `~/.dbt/wizard/`, каждый из которых управляет отдельной частью продукта. ## Два файла конфигурации Посмотрите, как это работает, и поделитесь отзывом Хотите увидеть dbt Wizard в действии? Посмотрите [демонстрационное видео](https://www.youtube.com/watch?v=-lIzh1xQWMA). Нам было бы интересно узнать о вашем опыте работы с dbt Wizard. Поделитесь отзывом, выполнив слеш-команду `/feedback` в интерактивном сеансе терминала или перейдя в канал [#dbt-wizard](https://getdbt.slack.com/archives/C0B6KLW6T26) в [Slack-сообществе dbt](https://docs.getdbt.com/community/join?version=2.0). Большое спасибо за помощь в улучшении dbt Wizard и процесса разработки данных с помощью dbt! TOML (Tom's Obvious, Minimal Language) — это формат файлов конфигурации. Если вы уже работали с YAML или JSON, он покажется вам знакомым — ключи и значения разделяются знаком `=` (с пробелами до и после знака равенства), а для вложенных разделов используются заголовки `[section.name]` вместо отступов или фигурных скобок. Например: \~/.dbt/wizard/config.toml ```toml model = "gpt-4o" [projects."/Users/you/jaffle-shop"] trust_level = "trusted" ``` Эта конфигурация задаёт модель ИИ по умолчанию для всех новых сеансов и применяется ко всем последующим запускам во всех проектах. Вы можете переопределить модель ИИ по умолчанию для конкретного проекта, задав ключ `model` в файле `wizard_config.toml` для этого проекта или воспользовавшись меню выбора `/model` в текстовом пользовательском интерфейсе (TUI). | Файл | Чем управляет | Когда использовать | | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------- | | `~/.dbt/wizard/config.toml` | Среда выполнения агента — модель ИИ, серверы MCP, правила подтверждения, доверенные проекты | Чтобы изменить поведение агента во всех сеансах | | `~/.dbt/wizard/wizard_config.toml` | Настройки отдельных проектов — путь к исполняемому файлу dbt, отложенное разрешение ссылок, сохранённые предпочтения модели | Чтобы изменить работу dbt Wizard с конкретным проектом dbt | Обратите внимание: `dbt_project.yml` — это отдельный файл, который управляет тем, как dbt собирает ваш проект. ## Типовые задачи | Цель | Что изменить | Нужен перезапуск? | | ----------------------------------------------------------- | ---------------------------------------------------------------------- | ----------------- | | Изменить модель ИИ по умолчанию | `config.toml` → `model = "gpt-4o"` | Да | | Указать dbt Wizard конкретный исполняемый файл dbt | `wizard_config.toml` → `path` | Да | | Добавить сервер dbt MCP | `config.toml` → `[mcp_servers.dbt]` | Да | | Пометить репозиторий как доверенный | `config.toml` → `trust_level = "trusted"` в разделе `[projects."..."]` | Да | | Изменить настройки подтверждения или песочницы по умолчанию | `config.toml` | Да | ## Приоритет настроек Настройки применяются в следующем порядке (от наивысшего приоритета к низшему): 1. Флаги CLI (`-m`, `-c`), указанные при запуске 2. Меню выбора модели в сеансе (`/model`) 3. `~/.dbt/wizard/config.toml` 4. `~/.dbt/wizard/wizard_config.toml` 5. Встроенные значения по умолчанию ## config.toml Глобальные настройки агента: модели, подтверждения, песочница, веб-поиск и серверы MCP. `~/.dbt/wizard/config.toml` управляет поведением сеанса агента. Он создаётся автоматически при установке dbt Wizard. ### Ключи конфигурации Ниже перечислены ключи конфигурации, которые можно задать в `config.toml`. * `model` * `approval_policy` * `sandbox_mode` * `web_search` Чтобы узнать больше, выполните `wizard config --help`. #### Модель ИИ и API При новой установке CLI dbt Wizard по умолчанию используются модели, управляемые dbt Labs. Чтобы использовать другого поставщика, см. раздел [Настройка BYOK](https://docs.getdbt.tech/docs/dbt-ai/wizard-byok.md). | Ключ | Тип | По умолчанию | Описание | | ------- | ------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `model` | string | — | Модель ИИ по умолчанию для новых сеансов. См. раздел [Формат идентификатора модели ИИ](#ai-model-id-format) ниже. Для интерактивного изменения используйте `/model` в TUI. | #### Поведение | Ключ | Тип | По умолчанию | Описание | | ----------------- | ------ | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `approval_policy` | string | `on-request` | Определяет, когда Wizard запрашивает подтверждение перед выполнением команд. Варианты: `untrusted` (запрашивать для недоверенных команд), `on-request` (решает dbt Wizard), `never` (выполнять без запроса). | | `sandbox_mode` | string | `read-only` | Политика песочницы для командной оболочки. Варианты: `read-only` (по умолчанию), `workspace-write` (разрешить запись в каталоге проекта), `danger-full-access` (без ограничений). | | `web_search` | string | `cached` | Режим веб-поиска. Варианты: `disabled`, `cached` или `live`. | #### Доверие к проекту Задайте `trust_level` для отдельного проекта, чтобы разрешить dbt Wizard использовать локальную конфигурацию проекта: ```toml [projects."/absolute/path/to/your-repo"] trust_level = "trusted" ``` #### Серверы MCP ```toml [mcp_servers.dbt] command = "DBT_MCP_ENDPOINT" ``` ### Формат идентификатора модели ИИ В качестве идентификаторов моделей ИИ в `config.toml` используются публичные идентификаторы моделей, например `gpt-4o`. Чтобы вывести список всех доступных идентификаторов моделей ИИ: ```bash wizard debug models ``` ### Переменные окружения Любой ключ можно задать через переменную окружения с префиксом `DBT_WIZARD_`, записав имя в формате `SCREAMING_SNAKE_CASE`: ```bash export DBT_WIZARD_MODEL=gpt-4o export DBT_WIZARD_APPROVAL_POLICY=never export OPENAI_API_KEY=sk-... # OpenAI (префикс не нужен) export ANTHROPIC_API_KEY=sk-ant-... # Anthropic (префикс не нужен) ``` `OPENAI_API_KEY` и `ANTHROPIC_API_KEY` считываются напрямую без префикса `DBT_WIZARD_`, в соответствии с соглашениями каждого поставщика. ### Когда считывается файл `config.toml` считывается в начале сеанса при запуске `wizard`. Изменения вступают в силу только после выхода из CLI и его перезапуска. Флаги `-c`, указанные для отдельного запуска, и меню выбора `/model` внутри сеанса переопределяют настройки этого файла только для текущего сеанса. ### Пример ```toml model = "gpt-4o" [projects."/Users/you/jaffle-shop"] trust_level = "trusted" [mcp_servers.dbt] command = "DBT_MCP_ENDPOINT" ``` ## wizard\_config.toml Настройки отдельных проектов, которые Wizard записывает во время первоначальной настройки, включая путь к dbt и параметры отложенного разрешения ссылок. `~/.dbt/wizard/wizard_config.toml` хранит сведения dbt Wizard о каждом из ваших проектов dbt. dbt Wizard автоматически записывает данные в этот файл во время первоначальной настройки и при изменении настроек проекта. Вы также можете редактировать его вручную. ### Ключи конфигурации | Ключ | Описание | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `version` | Версия схемы этого файла (сейчас `1`). Не изменяйте её вручную. | | `global.terms_of_use_accepted_at` | Отметка времени принятия Условий использования dbt Wizard. Записывается один раз в разделе `[global]` и применяется ко всем проектам. | | `global.dbt_compile_on_startup` | Определяет, нужно ли компилировать проект разработки при запуске. По умолчанию `true`. | | `global.prod_parse_on_startup` | Определяет, нужно ли выполнять разбор производственной среды и обновлять состояние для отложенного разрешения ссылок при запуске. По умолчанию `true`. | | `global.prod_parse_args` | Аргументы для разбора производственной среды. По умолчанию `["parse", "--target", "prod"]`. | | `global.prod_state_ttl_hours` | Количество часов, в течение которых снимок состояния производственной среды считается актуальным. По умолчанию `24`. | | `global.prod_state_dir` | Каталог для снимков состояния производственной среды. По умолчанию `target/prod-state` в проекте. | | `global.compile_extra_args` | Дополнительные аргументы, добавляемые при компиляции любого проекта в dbt Wizard, если для проекта не задано переопределение. | | `onboarded_at` | Отметка времени первоначальной настройки этого проекта в dbt Wizard. | | `path` | Путь к исполняемому файлу dbt, который dbt Wizard должен использовать для этого проекта. | | `compile_extra_args` | Дополнительные аргументы, добавляемые при компиляции этого проекта в dbt Wizard. | | `prod_parse_args` | Аргументы команды разбора производственной среды для конкретного проекта. | | `deferral.mode` | Определяет, кто управляет [отложенным разрешением ссылок](https://docs.getdbt.tech/reference/node-selection/defer.md) для этого проекта. См. раздел [Отложенное разрешение ссылок](#deferral) ниже. | | `deferral.target` | [Целевая среда (target)](https://docs.getdbt.tech/docs/local/profiles.yml.md) из вашего `profiles.yml`, которую dbt Wizard компилирует и использует для отложенного разрешения ссылок, когда `deferral.mode` имеет значение `"wizard"` (например, `"prod"`). | | `deferral.state` | Путь к каталогу состояния, когда `deferral.mode` имеет значение `"manual"`. | | `deferral.favor_state` | Определяет, имеют ли приоритет отношения, используемые при отложенном разрешении ссылок. По умолчанию `true`. | | `profile_override.path` | Путь к альтернативному файлу `profiles.yml` для этого проекта. | | `profile_override.profile` | Имя профиля из выбранного файла профилей, который следует использовать. | | `profile_override.target` | Целевая среда из выбранного профиля, которую следует использовать. | Настройки хранятся отдельно для каждого проекта в блоках `[projects."/absolute/path/to/repo"]`: \~/.dbt/wizard/wizard\_config.toml ```toml version = 1 [global] terms_of_use_accepted_at = "2026-05-28T15:06:54Z" dbt_compile_on_startup = true prod_parse_on_startup = true prod_state_ttl_hours = 24 [projects."/Users/you/jaffle-shop"] onboarded_at = "2026-05-20T11:09:01.410346" path = "/Users/you/jaffle-shop/.venv/bin/dbt" [projects."/Users/you/jaffle-shop".deferral] mode = "wizard" target = "prod" favor_state = true ``` #### Отложенное разрешение ссылок [Отложенное разрешение ссылок (deferral)](https://docs.getdbt.tech/reference/node-selection/defer.md) позволяет dbt Wizard повторно использовать модели, уже собранные в другой среде (например, в производственной), вместо того чтобы пересобирать всё, когда вы работаете только с частью проекта. Это экономит время и снижает затраты на хранилище данных. Настройка `deferral.mode` в `wizard_config.toml` определяет, кто управляет отложенным разрешением ссылок. Она принимает шесть значений, и dbt Wizard обычно задаёт её за вас во время первоначальной настройки: | Значение `deferral.mode` | Что оно означает | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `"wizard"` | dbt Wizard управляет отложенным разрешением ссылок за вас. Вы указываете dbt Wizard, какую [целевую среду](https://docs.getdbt.tech/docs/local/profiles.yml.md) из вашего `profiles.yml` использовать для отложенного разрешения ссылок (при первоначальной настройке проекта он пытается определить её автоматически). Затем dbt Wizard компилирует эту целевую среду и повторно использует её модели для любых вышестоящих моделей, которые вы ещё не собрали самостоятельно. | | `"fusion_cloud"` | dbt platform управляет отложенным разрешением ссылок на основе подключённой среды, поэтому dbt Wizard не управляет локальным состоянием. Задаётся автоматически при подключении к платформе. | | `"cloud_cli"` | dbt platform CLI управляет учётными данными и отложенным разрешением ссылок через dbt platform, поэтому dbt Wizard пропускает компиляцию производственной среды и добавление флагов отложенного разрешения ссылок. | | `"dbt_state"` | dbt State или кеш запусков управляет отложенным разрешением ссылок, поэтому dbt Wizard пропускает собственную компиляцию производственной среды. | | `"manual"` | Вы указываете каталог с манифестом для отложенного разрешения ссылок с помощью `state`. | | `"disabled"` | Отложенное разрешение ссылок отключено для проекта. | Подробнее о dbt State см. в разделе [О dbt State](https://docs.getdbt.tech/docs/deploy/dbt-state-about.md). Если `mode = "manual"`, задайте для `state` каталог, содержащий совместимый файл `manifest.json`: ```toml [projects."/Users/you/jaffle-shop".deferral] mode = "manual" state = "/Users/you/dbt-state/production" favor_state = true ``` **О параметре [favor-state](https://docs.getdbt.tech/reference/node-selection/defer.md?version=2.0#favor-state):** параметр `favor_state` настраивается и по умолчанию имеет значение `true`. При значении `true` dbt Wizard передаёт `--favor-state`, чтобы отношения, используемые при отложенном разрешении ссылок, имели приоритет. Задайте `false`, чтобы использовать отношение, уже существующее в среде разработки, и обращаться к состоянию для отложенного разрешения ссылок, только если такого отношения нет. Вы также можете настроить поведение снимков производственной среды и компиляции с помощью глобальных параметров `prod_parse_on_startup`, `prod_parse_args`, `prod_state_ttl_hours`, `prod_state_dir` и `compile_extra_args`. Значения `compile_extra_args` и `prod_parse_args` на уровне проекта позволяют переопределить глобальное поведение для одного проекта. Используйте блок `profile_override`, чтобы выбрать другой файл профилей, профиль или целевую среду для компиляции. Примеры конфигурации и порядок проверки см. в разделе [Разработка с отложенным разрешением ссылок на производственную среду](https://docs.getdbt.tech/best-practices/how-to-use-wizard/wizard-6-production-deferral.md). ## Устранение неполадок Ниже приведены распространённые ошибки конфигурации и способы их устранения: | Симптом | Вероятная причина | Решение | | ------------------------------------------------------------------------------------ | ------------------------------------- | ----------------------------------------------------------------------------------- | | После редактирования `wizard_config.toml` по-прежнему используется прежняя модель ИИ | `wizard_config.toml` не хранит модель | Задайте `model` в `config.toml` и перезапустите `wizard` | | Модель ИИ не изменилась после редактирования `config.toml` | Старый сеанс всё ещё работает | Нажмите Ctrl+C, затем снова запустите `wizard` | | Ошибка "Invalid model" | Неверный идентификатор модели ИИ | Выполните `wizard debug models`, чтобы увидеть допустимые идентификаторы моделей ИИ | ### Повторный запуск процедур первоначальной настройки Если вам нужно повторить часть настройки — например, после случайного удаления записей конфигурации или перехода к новому проекту, — вы можете сбросить отдельные процедуры, удалив соответствующий файл. При следующем запуске dbt Wizard снова предложит выполнить настройку. Чтобы удалить файл, выполните команду в терминале (macOS/Linux). Например: ```bash rm ~/.dbt/wizard/auth.json ``` Если вы получили ошибку `No such file or directory`, файл не существует — это означает, что соответствующая часть настройки ещё не выполнялась или уже была сброшена. Эту ошибку можно игнорировать. | Что вы хотите повторить | Какой файл удалить | | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | | Повторно вызвать запрос о доверии к папке | Удалите запись вашего проекта из `~/.dbt/wizard/config.toml` в разделе `[projects."..."]` | | Повторно пройти аутентификацию в dbt platform | `~/.dbt/wizard/auth.json` | | Повторно настроить проект dbt | Удалите запись вашего проекта из `~/.dbt/wizard/wizard_config.toml` в разделе `[projects."..."]` или удалите файл целиком, чтобы сбросить все проекты | | Повторно запустить настройку ключа BYOK | `~/.dbt/wizard/provider*` (соответствует всем файлам поставщиков) | предупреждение `config.toml` и `wizard_config.toml` — это отдельные файлы, которые управляют разными настройками. Если вы хотите повторно настроить проект, изменяйте `wizard_config.toml`, а не `config.toml`. Изменение не того файла не запустит ожидаемую процедуру первоначальной настройки. Различия описаны в разделе [Два файла конфигурации](#the-two-config-files) в начале этой страницы. ## Связанная документация Ссылки на настройку BYOK, порядок подтверждения действий и справочник команд CLI. * [Настройка BYOK](https://docs.getdbt.tech/docs/dbt-ai/wizard-byok.md) * [Подтверждение действий и песочница](https://docs.getdbt.tech/docs/dbt-ai/wizard-how-it-works.md#approval-and-sandboxing) * [Справочник команд dbt Wizard](https://docs.getdbt.tech/docs/dbt-ai/wizard-cli-reference.md) * [Как работает dbt Wizard](https://docs.getdbt.tech/docs/dbt-ai/wizard-how-it-works.md)