✅ Создайте QwenPaw Workspace с кастомными навыками и API за 5 шагов

Что делает ваш скрипт и зачем он нужен?

Скрипт — это небольшая «инициализационная рутина» для проекта QwenPaw. Его цель — подготовить рабочую директорию, подобрать подходящего провайдера LLM‑модели и сохранить все настройки в config.json. Если вы хотите быстро запустить эксперименты в Google Colab, протестировать несколько API или собрать собственный набор агентов, эта статья покажет, как избавиться от «мутных» ошибок и понять, что происходит под капотом.

Пошаговый разбор кода

Разберём каждый блок, чтобы вы знали, какой кусок отвечает за что.

Проверка наличия config.json
```
if not (WORKING_DIR / "config.json").exists():
    run(qwenpaw_cmd("init", "--defaults"), check=False)
else:
    print("QwenPaw working directory already initialized:", WORKING_DIR)
```
Если файл конфигурации ещё не создан, скрипт вызывает qwenpaw init --defaults, который автоматически генерирует базовые настройки. При уже существующей конфигурации выводится путь к ней – удобно для отладки.
Список провайдеров
```
provider_candidates = [ ... ]
```
Каждый словарь описывает один провайдер (OpenAI, OpenRouter, DashScope, DeepSeek, Google Gemini). Важные поля:
- env — имя переменной окружения, где хранится ваш API‑key.
- provider_id и name — идентификатор и читаемое название.
- base_url — конечная точка API.
- model — модель по умолчанию (можно переопределить переменной QWENPAW_MODEL).
- prefix — префикс ключа, который требуется добавить к API‑key (например, sk- у OpenAI).
Эти данные позволяют скрипту автоматически подобрать первый доступный провайдер.
Выбор провайдера
```
selected = None
for candidate in provider_candidates:
    api_key = colab_secret_or_env(candidate["env"])
    if api_key:
        selected = {**candidate, "api_key": api_key}
        break
```
Функция colab_secret_or_env ищет ключ в переменных среды или в секрете Google Colab. Как только найден первый подходящий провайдер, его параметры сохраняются в selected и цикл прерывается.
Чтение и запись JSON‑файла
```
def read_json(path, default): ... 
def write_json(path, data): ...
```
Эти вспомогательные функции безопасно читают config.json (если файл испорчен — возвращают default) и записывают обновлённые данные, автоматически создавая недостающие каталоги.
Формирование структуры конфигурации
```
config = read_json(config_path, {})
config.setdefault("agents", {})
...
write_json(config_path, config)
```
Здесь задаются базовые параметры:
- active_agent — текущий агент (по умолчанию default).
- agent_order — порядок переключения агентов.
- profiles — описание профиля агента, включая путь к рабочей директории, имя и короткую справку.
- Дополнительные служебные поля: last_api, show_tool_details, user_timezone.
Эти настройки нужны не только скрипту, но и любой UI‑надстройке, которая будет отображать список агентов.

Как подготовить окружение перед запуском

Чтобы всё прошло гладко, выполните минимум три простых шага.

Установите переменные окружения. В Colab это делается так:

import os
os.environ["OPENAI_API_KEY"] = "sk-ваш_ключ"
# или любой другой, в зависимости от провайдера

Если используете секреты Colab, откройте боковую панель Secrets и добавьте переменную с тем же именем.

Убедитесь, что каталог WORKING_DIR доступен. По умолчанию это /content/qwenpaw в Colab, но вы можете переопределить переменную WORKING_DIR перед запуском скрипта.
Проверьте наличие Python‑зависимостей. Основные пакеты:

pip install -U qwenpaw tqdm python-dotenv

Если ваш проект использует виртуальное окружение, активируйте его перед установкой.

Тонкая настройка профиля агента

После первого запуска в config.json уже будет профиль default. Вы можете добавить свои, например, для разных проектов или наборов навыков.

{
    "id": "research",
    "name": "Research Assistant",
    "description": "Помогает анализировать научные статьи и генерировать рефераты.",
    "workspace_dir": "/content/research_workspace",
    "enabled": true
}

Чтобы активировать новый профиль, просто измените поле active_agent в корне agents или используйте встроенную команду CLI:

qwenpaw agent set --id research

Отладка типичных проблем

«API‑key not found» – убедитесь, что переменная окружения объявлена именно так, как указано в env провайдера, и без лишних пробелов.
«config.json is not valid JSON» – откройте файл, проверьте запятые и кавычки. Функция read_json автоматически вернёт пустой словарь, но следующая запись перезапишет файл корректно.
«Connection timed out» – проверьте, доступен ли base_url из вашего текущего сетевого окружения (в некоторых корпоративных VPN доступ к api.openai.com может быть ограничен).

Где найти официальную документацию и репозиторий

GitHub‑репозиторий QwenPaw: github.com/qwenpai/qwenpaw
Документация по API провайдеров (OpenAI, OpenRouter, DashScope, DeepSeek, Gemini) доступна на их официальных сайтах; ссылки указаны в полях base_url каждого провайдера.

Краткое резюме

Скрипт автоматически:

Создаёт config.json, если его нет;
Подбирает первый рабочий LLM‑провайдер по наличию API‑key;
Заполняет базовую структуру конфигурации с профилем агента;
Сохраняет всё в удобочитаемом JSON‑формате.

Следуя рекомендациям выше, вы сможете быстро настроить рабочее окружение, добавить новые профили и безболезненно переключаться между различными моделями — всё без лишних «загадок» и «красных» сообщений. Удачной разработки!