SimpleClaw

Руководства

Установить Pi и подключить SimpleClaw

От установки клиента до первого ответа через API SimpleClaw в отдельном профиле.

Что такое Pi и что понадобится

Pi — помощник для работы с кодом в терминале. Он может читать и менять файлы, запускать команды и обращаться к выбранной модели. SimpleClaw предоставляет ему доступ к моделям через API.

Понадобятся компьютер с Windows, macOS или Linux, интернет, терминал и аккаунт SimpleClaw с активным Provider-доступом или пополненным балансом. Для начала выберите отдельную учебную папку без секретов.

Команды сверены с официальной документацией Pi и версией 1.5.0. Pi требует Node.js 22.19 или новее; официальные установщики могут установить его сами. На Windows также установите Git for Windows: Pi использует Git Bash для выполнения команд. Рекомендуется Windows Terminal.

1. Установите клиент Pi

macOS и Linux. Откройте «Терминал» и выполните:

curl -fsSL https://pi.dev/install.sh | sh

Windows. Откройте PowerShell в Windows Terminal и выполните:

powershell -c "irm https://pi.dev/install.ps1 | iex"

Закройте терминал, откройте его заново и проверьте установку:

pi --version

Команда должна вывести номер версии. Установка клиента ещё не подключает API SimpleClaw. Если Node.js уже установлен, официальный альтернативный способ — npm install -g --ignore-scripts @earendil-works/pi-coding-agent.

2. Подготовьте ключ и отдельный профиль

  1. Войдите в кабинет и откройте «API-ключи». Создайте ключ с именем «Pi» и подходящим недельным бюджетом. Подробности — в инструкции по ключам.
  2. Откройте каталог моделей. Выберите текстовую модель с протоколом chat_completions и скопируйте её публичный ID, а не отображаемое название. Модели только для messages, изображений, аудио или эмбеддингов для этого примера не подходят.
  3. В новом терминале выполните блок для своей системы и вставьте ключ по приглашению. Ввод скрыт. Ключ действует только в этом окне терминала и не записывается в конфигурацию.

macOS и Linux:

export PI_CODING_AGENT_DIR="$HOME/.pi/simpleclaw"
mkdir -p "$PI_CODING_AGENT_DIR"
printf 'API-ключ SimpleClaw: '
read -r -s SIMPLECLAW_API_KEY
printf '\n'
export SIMPLECLAW_API_KEY

Windows PowerShell:

$env:PI_CODING_AGENT_DIR = "$env:USERPROFILE\.pi\simpleclaw"
New-Item -ItemType Directory -Force $env:PI_CODING_AGENT_DIR | Out-Null
$key = Read-Host "API-ключ SimpleClaw" -AsSecureString
$env:SIMPLECLAW_API_KEY = [System.Net.NetworkCredential]::new("", $key).Password

Так Pi использует профиль SimpleClaw вместо обычного ~/.pi/agent. В каждом новом терминале повторяйте этот блок перед запуском Pi. Не вставляйте ключ в команды, чат или файлы проекта.

3. Сохраните настройки провайдера

В текстовом редакторе создайте файл models.json в папке профиля: ~/.pi/simpleclaw/models.json на macOS/Linux или %USERPROFILE%\.pi\simpleclaw\models.json на Windows. Сохраните как обычный текст UTF-8, без дополнительного расширения .txt. Если файл уже существует, добавьте провайдер simpleclaw в его объект providers, сохранив остальные настройки.

Скопируйте пример и замените model-id-from-catalog на ID выбранной модели:

{
  "providers": {
    "simpleclaw": {
      "baseUrl": "https://simple-claw.ru/v1",
      "api": "openai-completions",
      "apiKey": "$SIMPLECLAW_API_KEY",
      "authHeader": true,
      "models": [
        {
          "id": "model-id-from-catalog",
          "maxTokens": 1024
        }
      ]
    }
  }
}

$SIMPLECLAW_API_KEY оставьте как есть: Pi прочитает ключ из переменной, заданной на прошлом шаге. maxTokens: 1024 ограничивает длину ответа для первого теста. Стоимость смотрите в SimpleClaw: внутренняя оценка Pi может отличаться.

Адрес должен быть ровно https://simple-claw.ru/v1. В формате Pi openai-completions означает Chat Completions: клиент добавляет /chat/completions сам и отправляет Bearer-ключ. Не добавляйте этот путь или второй /v1 в адрес.

Формат описан в документации провайдеров Pi. Каталог SimpleClaw не загружается в Pi автоматически: для другой модели добавьте её ID в models.

4. Запустите Pi и получите первый ответ

В том же терминале перейдите в папку проекта, заменив путь в примере на свой. Для первого теста отключите инструменты, чтобы запрос не выполнял команды и не менял файлы.

macOS/Linux: cd "/path/to/project". Windows: cd "C:\path\to\project".

pi --provider simpleclaw --model model-id-from-catalog --no-tools

В команде тоже замените model-id-from-catalog. Если Pi спрашивает о доверии проекту, разрешайте загрузку его настроек только для знакомой папки. Введите:

Ответь одним словом: OK

Ожидаемый результат — ответ OK. Это платный запрос по тарифу модели, включая служебные инструкции Pi. Проверьте модель, статус и расход в истории запросов. Для обычной работы завершите тест сочетанием Ctrl+C дважды и запустите ту же команду без --no-tools. Pi сможет работать с файлами и командами проекта.

Внутри Pi команда /model перечитывает models.json и позволяет выбрать добавленную модель. Для проверки одним запуском из терминала:

pi --provider simpleclaw --model model-id-from-catalog --no-tools --no-session --print "Ответь одним словом: OK"

Если что-то не работает

  • Команда pi не найдена. Откройте новый терминал и повторите pi --version. Проверьте command -v pi на macOS/Linux или Get-Command pi в PowerShell. Если команда не найдена, повторите официальный установщик и выполните его подсказки по PATH.
  • Ошибка чтения конфигурации или модель не появилась. Проверьте путь профиля: echo "$PI_CODING_AGENT_DIR" или $env:PI_CODING_AGENT_DIR. Проверьте имя models.json, кавычки и запятые; уберите комментарии и завершающие запятые. Перезапустите Pi или откройте /model.
  • 401 или INVALID_API_KEY. Убедитесь, что ключ активен в кабинете, затем повторите скрытый ввод в том же терминале. Не выводите ключ на экран. В конфигурации должны остаться apiKey: "$SIMPLECLAW_API_KEY" и authHeader: true.
  • 404 или неверный адрес. Сверьте baseUrl с https://simple-claw.ru/v1. Если ошибка называет модель, сверьте её ID с каталогом.
  • Модель не поддерживается. Для этого примера нужен протокол chat_completions. Замените ID одновременно в файле и команде запуска. При MODEL_NOT_IN_PLAN выберите доступную вашему тарифу модель.
  • 429, нет доступа или долгая пауза. Проверьте баланс, Provider-доступ и недельный бюджет ключа. В потоковом режиме текст поступает по мере получения. При ошибке поставщика или прерванном ожидании сначала проверьте историю, затем обращайтесь в поддержку с requestId, без ключа. Не повторяйте платный запрос автоматически.
Установить Pi и подключить SimpleClaw — документация SimpleClaw