Как начать работу с агентом на Mac, подключить телефон, основные команды и сценарии — и что именно происходит в каждом из них.
Установка
aictrlx для macOS
Установка одной командой
Терминал на Mac
git clone https://github.com/aictrlx/aictrlx_agent.git aictrlx && cd aictrlx && ./install.sh
Установщик поставит aictrlx в ~/.local/share/aictrlx, скачает Chromium для браузера агента и добавит команду aictrlx в PATH. Нужны git и Python 3.12 или новее: если такого Python нет, установщик подскажет, как его поставить (brew install python@3.12). Когда он закончит, откройте новое окно терминала. Обновление — в папке aictrlx: git pull && ./install.sh.
aictrlx loginвойдите: подтвердите код на aictrlx.ru/device
aictrlx config set model_privacy allow_remoteпока вы не разрешите удалённые модели, они не получают работу
aictrlx model policy --default aictrlxотправлять работу модели сервиса
aictrlx phone relay onоткрывать этот Mac с телефона вне дома
aictrlxинтерактивный режим в папке проекта: опишите задачу обычными словами
Три шага после aictrlx login команда напечатает сама — только те, что ещё не сделаны. aictrlx doctor проверит окружение.
Приложение для Android
Подтверждения, задачи и результаты на телефоне; привязка — у Mac командой aictrlx phone pair.
Бета
Бета-версия: приложение ещё будет меняться, возможны ошибки. Для Android 10 и новее. В первый раз Android попросит разрешить установку приложений из браузера; следующие версии ставятся поверх.
В конце установщик запускает aictrlx doctor — он проверяет окружение, хранилище ключей, подключения и возможности агента; запускайте его и потом, когда нужно.
Агент может работать и с моделью на вашем Mac или в локальной сети — LM Studio, llama.cpp, Ollama, vLLM: подойдёт OpenAI-совместимый сервер с моделью, которая умеет вызывать инструменты. Укажите агенту его адрес:
Терминал
aictrlx config set model_base_url http://gpu-box:1234/v1
Вход в aictrlx.ru
aictrlx login подключает этот Mac к аккаунту aictrlx.ru по коду устройства — ничего не нужно копировать вручную.
Выполните aictrlx login в терминале Mac. Команда покажет код и откроет aictrlx.ru/device в браузере (с --no-browser — только напечатает адрес и код, чтобы открыть их на любом устройстве).
Войдите на странице (или зарегистрируйтесь), проверьте, что код тот же, выберите проект и что разрешить этому Mac: «Модели» и, если тариф это включает, «Ретранслятор для телефона». Подтвердите.
Через несколько секунд терминал завершит вход и напечатает, что сохранено и что делать дальше:
aictrlx login
$ aictrlx login
To sign this Mac in to aictrlx, open https://aictrlx.ru/device
and check that it shows the code WDJB-MJHT
(opened in your browser). Waiting for you to approve it… Ctrl+C stops.
Signed in to aictrlx as anna@example.com — project "Default Project".
key "aictrlx — Anna's MacBook Pro", kept in the macOS Keychain only
models the model "aictrlx" (coding) at https://aictrlx.ru/v1 has this key — registered now
relay the phone relay key for relay.aictrlx.ru is set
Next (nothing else was changed):
aictrlx config set model_privacy allow_remote remote models get no work until you allow them
aictrlx model policy --default aictrlx send work to it
aictrlx phone relay on reach this Mac from the phone away from home
Сохраняется один обычный API-ключ проекта с именем «aictrlx — <имя Mac>»: он виден на странице API-ключей, его можно отозвать, а на Mac он хранится только в связке ключей macOS. С «Моделями» он становится ключом моделей сервиса — и, если модели ещё нет, команда регистрирует модель aictrlx (режим маршрутизации coding); с «Ретранслятором» — ключом ретранслятора.
Команда не меняет model_privacy, local_only_capabilities, модель по умолчанию и маршрутизацию и не включает маршрут через ретранслятор — вместо этого печатает нужные команды.
Параметры и связанные команды
aictrlx login --no-browserнапечатать адрес и код, чтобы открыть их на любом устройстве
aictrlx login --name "Work Mac"как назвать этот Mac в кабинете (по умолчанию — имя компьютера)
aictrlx accountпод каким аккаунтом вошёл Mac, его ключ, ретранслятор, баланс
aictrlx logoutотозвать ключ, выданный при входе, и удалить его с Mac
Повторный вход заменяет ключ: выданный aictrlx login отзывается, созданный в кабинете остаётся действующим. После aictrlx logout зарегистрированные модели остаются, но без ключа — до следующего aictrlx login. Вставить ключ вручную тоже можно: aictrlx model set-key и aictrlx phone relay set-key.
Модели и приватность
По умолчанию model_privacy равен local_only: модель на чужом сервере — в том числе модель сервиса — не видит работу агента. Два шага, которые печатает aictrlx login, отправляют работу модели сервиса:
Терминал
aictrlx config set model_privacy allow_remote
aictrlx model policy --default aictrlx
Модель, которую вы назвали сами, — /model в интерактивном режиме, --model у aictrlx run, — та, на которой выполняется задача; если это невозможно, задача завершится с объяснением, но на другую модель не перейдёт.
Почта, календарь, Drive, память и управление компьютером остаются локальными при любой настройке приватности (local_only_capabilities, по умолчанию gmail,calendar,drive,memory,computer): задача на выбранной вами облачной модели выполняется без них, а разговор, в котором уже есть их данные, остаётся на локальных моделях. Для такой работы нужна модель на Mac или в локальной сети.
Модель aictrlx работает в режиме маршрутизации coding: он выбирает модель по навыкам программирования, размеру контекста и поддержке инструментов. Другой режим — auto, smart, fast — или конкретную модель из каталога можно зарегистрировать вручную:
Расходы по умолчанию показываются в рублях, а то, что сервис списал за вызов, — как есть. Лимиты на то, сколько может потратить одна задача и один разговор (например, 300rub), — в aictrlx settings --group limits.
Телефон
Шлюз, к которому подключается телефон, работает внутри aictrlx daemon run (или службы, которую устанавливает aictrlx daemon install), один на Mac; пока телефон не привязан, он ничего не слушает.
Привязка по QR-коду
Запустите фоновый процесс: aictrlx daemon run — или aictrlx daemon install, чтобы macOS запускала его при входе в систему (команда покажет, что именно запишет и запустит, и спросит).
Выполните aictrlx phone pair: в терминале появится QR-код, действительный один раз в течение 5 минут.
Отсканируйте его в приложении aictrlx. На обоих экранах появятся шесть цифр: сравните их и нажмите y на Mac. Если телефон пишет, что код уже использован другим устройством, нажмите n.
При привязке приложение спросит, можно ли открывать ключ подтверждений PIN-кодом блокировки экрана вместо отпечатка. Тогда подтверждать сможет любой, кто знает PIN; выключите это, чтобы каждое подтверждение требовало отпечатка.
aictrlx phone devices [--all]привязанные телефоны и как они подтвердили свои ключи
aictrlx phone revoke <id>отключить телефон; его расписания приостанавливаются
aictrlx phone statusшлюз, его порты, аренда и настройки
Подтверждения
Когда фоновая задача доходит до действия, которому нужно ваше решение, — отправить письмо, изменить календарь, — она останавливается: запрос сохраняется с превью из настоящих аргументов, и задача ждёт. Телефон показывает его со всеми получателями и участниками, а если текст показан не целиком, отмечает, где он обрезан. Вы отвечаете на каждый запрос отдельно и подписываете решение отпечатком. Задача выполнит действие, когда продолжит работу, и только если оно по-прежнему совпадает с тем, что вы подтвердили. На Mac те же запросы — в aictrlx approvals.
Вне дома: ретранслятор
Вне дома телефон подключается к Mac через relay.aictrlx.ru — без проброса портов. Для этого нужен API-ключ вашего аккаунта aictrlx.ru с включённым ретранслятором: aictrlx login сохраняет такой ключ, если вы разрешили «Ретранслятор для телефона». Затем:
aictrlx phone relay onчерез ретранслятор сервиса aictrlx, откуда угодно; relay off — выключить
aictrlx phone relay statusподключён ли Mac, тариф аккаунта, причина отказа
aictrlx phone relay set-keyключ сервиса aictrlx: вводится скрыто, хранится в связке ключей — если без aictrlx login
Привязанные телефоны узнают маршрут из подписанного набора маршрутов — новый код не нужен. Доступен ли ретранслятор вашему аккаунту, зависит от тарифа и настроек сервиса: Тарифы.
Основные команды
Задачи
aictrlxинтерактивный режим: задачи одна за другой, в этой папке
aictrlx --continueпродолжить последний разговор в этой папке
aictrlx run "Review the parser for bugs" --mode reviewтолько читает, ничего не меняет
aictrlx run "Tidy the changelog" --backgroundпоставить в очередь, а не выполнять здесь
Фоновая работа и подтверждения
aictrlx jobsзадачи в очереди, выполняющиеся, ожидающие и завершённые
aictrlx job watch <id>следить за выполнением задачи, где бы она ни шла (Ctrl-C — перестать)
aictrlx notificationsчто произошло, пока вас не было
aictrlx schedulesрасписания: включено ли и когда следующий запуск
aictrlx daemon installзапускать фоновый процесс при входе в систему: покажет, что запишет и запустит, и спросит
aictrlx daemon statusочередь, кто что занимает, загруженные модели, сколько стоили вызовы сегодня
Состояние и настройки
aictrlx doctorокружение, хранилище ключей, подключения, возможности
aictrlx connectorsподключения: состояние, аккаунт, выданные разрешения
aictrlx mcp listMCP-серверы: подключён ли и почему нет, их инструменты
aictrlx memoriesвсё, что агент помнит, и как часто это использовалось
aictrlx actionsчто агент отправил или изменил за пределами этого Mac
aictrlx settingsменю: группа, настройка, новое значение
Аккаунт aictrlx.ru
aictrlx login [--server URL] [--name NAME] [--no-browser]подключить этот Mac; подтверждение в браузере
aictrlx accountпод каким аккаунтом вошёл Mac, ключ, ретранслятор, баланс
aictrlx logoutотозвать ключ, выданный при входе, и удалить его с Mac
Подключение Gmail, Календаря и Drive
Нужен собственный OAuth-клиент Google (клиент типа Desktop app в Google Cloud Console с включёнными Gmail API и Google Calendar API). Затем выдайте ровно те разрешения, которые хотите, — без -p запрашивается только чтение:
Каждый сценарий — это просьба обычными словами; команды — примеры из документации самой программы.
Исправить падающий тест от начала до конца
aictrlx run "Fix the failing test in tests/test_parser.py"
Что происходит: Агент запускает тесты, читает код, вносит правку и снова запускает тесты; перед изменением каждого файла сохраняется его копия. Прежде чем задача завершится, независимый проверяющий — отдельный вызов модели, который не видит переписку, — оценивает diff и изменённые файлы; если судить он не может, задача завершается как «не проверено», но не как успешная. В интерактивном режиме /diff покажет изменения задачи, а /undo вернёт всё как было.
Разобрать входящие
aictrlx run "Find emails from today that probably need a reply from me"aictrlx run "Archive the obvious newsletters from the last week"
Что происходит: Поиск возвращает краткие сведения — отправителя, тему, дату, метки, фрагмент, — а целиком загружаются только нужные письма. Архивирование по запросу всегда сначала спрашивает — с превью: сколько писем, за какие даты и от каких отправителей; подтверждается ровно этот набор.
Нужно: Подключённый Gmail и модель на Mac или в локальной сети: почта не уходит на удалённые модели.
Найти свободный час на следующей неделе
aictrlx run "find the latest mail from Alex about the architecture meeting and suggest when we could meet next week"
Что происходит: Одна задача для одного агента: он находит письмо, читает цепочку и вычисляет действительно свободные окна по данным free/busy — это делает код, а не модель. Создание встречи сначала спрашивает вас — в превью календарь, время и участники.
Нужно: Подключённые Gmail и Календарь и модель на Mac или в локальной сети.
Сайт без API
aictrlx run "Check the order status on the supplier site" --headed
Что происходит: Агент открывает настоящий Chromium (--headed показывает окно), читает страницу как снимок доступности и действует на её элементы. Один раз войдите на сайт сами — aictrlx browser login <profile> --url https://site: профиль сохранит вход, а пароль агент не увидит. Клик, который что-то отправляет, удаляет или покупает, сначала спрашивает вас; CAPTCHA и одноразовые коды агент передаёт вам.
Нужно: Chromium для браузера: aictrlx browser install, один раз на компьютер (aictrlx browser status проверит).
Что происходит: Каждый раз в назначенное время расписание ставит в очередь обычную задачу, а фоновый процесс её выполняет; 08:30 остаётся 08:30 и при переходе на летнее время. Расписание не даёт никаких разрешений: всё, что требует решения человека, ждёт его, а aictrlx notifications покажет, что произошло без вас.
Что происходит: Задача из очереди доходит до отправки письма и останавливается. Телефон показывает запрос — все получатели, тема и текст (обрезанный текст отмечен там, где он обрывается), — и вы подтверждаете его отпечатком: один запрос — одно решение. Задача отправит письмо, когда продолжит работу, и только если черновик всё ещё ровно тот, что вы подтвердили; изменённый после этого черновик не отправляется, и вас спросят снова. На Mac тот же запрос виден в aictrlx approvals.
Нужно: Привязанный телефон; вне дома — ретранслятор (aictrlx phone relay on).
Ревью репозитория силами субагентов
aictrlx run "Analyse this repository: have separate agents look at architecture, test quality and security, then give me one report" --agent-mode multi
Что происходит: Сначала задача решает, как работать: пока она не распределила работу или не решила сделать её сама, она может только читать. Каждый агент получает задание, а не всю переписку, и права не шире, чем у самой задачи; выводы объединяются по доказательствам, а расхождения показываются рядом. Это не всегда быстрее: задачу, которая сводится к одной линии работы, один агент сделает быстрее и дешевле.
Вопросы и ответы
Что где работает?
Агент, его инструменты, память и история работы — на вашем Mac. Модели — там, где они запущены: на Mac или в локальной сети (например, LM Studio) либо в сервисе, по адресу https://aictrlx.ru/v1. Телефон — лишь интерфейс: он показывает и отвечает, а работа остаётся на Mac.
Что отправляется в сервис?
Только когда задача выполняется на модели сервиса, и только после того, как вы разрешили удалённые модели: всё, что запуск отправляет модели, — задача, файлы, которые читает агент, результаты инструментов, переписка. Почта, календарь, Drive, память и управление компьютером по умолчанию остаются на Mac. API-ключ отправляется только тому сервису, который его выдал (а ключ ретранслятора — только ретранслятору). Как сервис хранит запросы — в Политике конфиденциальности.
Что видит ретранслятор, а что нет?
Шифротекст и метаданные: аккаунт, к которому привязан Mac, идентификаторы и транспортные ключи привязанных телефонов, адреса, с которых подключаются обе стороны, а также когда, как долго и сколько байт передал каждый сеанс. Содержимое — какая задача, какое подтверждение, превью, тексты, сообщения, результаты — ему недоступно, как и адреса Mac в домашней сети: всё это идёт внутри TLS между телефоном и Mac, зашифрованное ключами, которых у ретранслятора нет. Он может отказать в соединении, задержать или разорвать его.
Сколько это стоит?
Модели сервиса оплачиваются как обычно — с баланса или из объёма, включённого в подписку, по ценам со страницы «Тарифы»; баланс показывает aictrlx account. Модель на Mac или в локальной сети ничего не стоит. Лимиты расходов на задачу и на разговор останавливают запуск до вызова, который мог бы их превысить.
Нужен ли аккаунт?
Для моделей сервиса и ретранслятора — да: к нему Mac подключается командой aictrlx login. С моделью на Mac или в локальной сети агент работает и без аккаунта.
А Windows или Linux?
Сейчас aictrlx работает на macOS, на других операционных системах он появится позже.
Как отключить Mac от аккаунта?
aictrlx logout отзывает ключ, выданный aictrlx login, и удаляет его с Mac. В кабинете на странице «Агент для Mac» перечислены все устройства, вошедшие через aictrlx login, — выйти можно на любом из них; любой ключ можно отозвать и на странице «API-ключи».