Перейти к содержанию

Управление компьютером

Инструмент computer_use позволяет агенту видеть окна приложений на вашем компьютере и действовать в них: нажимать кнопки, заполнять поля, переключать вкладки, прокручивать списки. Работа идёт в фоне: агент не перехватывает вашу мышь и клавиатуру и не выводит окна на передний план.

Это нужно для задач, которые не сводятся к коду: повторить шаги в интерфейсе, проверить, что форма действительно сохраняется, заполнить таблицу данными из проекта, найти причину ошибки по тому, что видно на экране.

Что нужно для работы

  • Режим агента. В режиме планирования инструмент недоступен: там нет действий, меняющих состояние.
  • Локальный компьютер. SSH, WSL, удалённые окружения и контейнеры не поддерживаются.
  • Без песочницы. При запуске с --sandbox инструмент не регистрируется.
  • Поддерживаемая система. macOS 14 и новее (Apple Silicon и Intel), Windows x64, Linux x64 с X11 или XWayland. Чистый Wayland и Windows/Linux на ARM64 не поддерживаются.
  • Модель с поддержкой изображений. Агент получает снимки окон, поэтому модель должна уметь работать с изображениями. Если поддержка изображений у модели неизвестна, инструмент не предлагается.
  • Исправный помощник. В поставку CLI входит помощник Koda Computer Use. Если он отсутствует или не запускается, инструмент скрыт из списка, а остальная работа CLI не меняется.
  • Разрешения операционной системы. На macOS нужны два разрешения, см. «Разрешения macOS».

Список доступных инструментов текущей сессии показывает команда /tools.

Как агент работает с окнами

  1. Находит окно: list_windows возвращает список окон с приложением, заголовком и ссылкой на окно. Поиск по приложению или заголовку сужает список, остальные окна доступны следующими страницами по 30 штук.
  2. Делает снимок нужного окна действием screenshot: к изображению прилагается список доступных элементов управления с идентификаторами.
  3. Действует: нажимает элемент по идентификатору, заполняет поле целиком или вводит текст в позицию курсора. Если подходящего элемента нет, используются координаты последнего снимка.
  4. Проверяет результат: после ввода возвращается новый снимок окна, и агент сверяет видимое значение с ожидаемым.

Одно действие за вызов

За один вызов выполняется одно действие либо явно заданный пакет шагов. Поэтому агент не «пробегает» интерфейс вслепую: между действиями он смотрит на новый снимок.

Ссылки и идентификаторы устаревают

Ссылка на окно действует в пределах текущего процесса CLI и хранится не дольше 10 минут; снимок тоже живёт 10 минут. Идентификаторы элементов и снимков сбрасываются после любого ввода, поэтому агент копирует их из последнего результата, а не придумывает. После перезапуска CLI старые ссылки на окна недействительны.

Действия инструмента

Действие Что делает
list_windows Список окон: приложение, заголовок, ссылка на окно
screenshot Снимок окна с элементами управления; без указания окна — снимок рабочего стола (только macOS)
zoom Увеличение области последнего снимка
click, double_click, triple_click, right_click Нажатие по элементу или координате снимка
move Наведение указателя
drag Перетаскивание из точки в точку
scroll Прокрутка по вертикали или по горизонтали
type Вставка текста в позицию курсора
set_value Замена значения текстового поля целиком, включая очистку
key Клавиша или сочетание клавиш, в том числе повтор до 20 раз
wait Пауза от 0,5 до 5 секунд и новое наблюдение
batch Заранее заданные шаги в одном окне

Замена значения поля

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

Пакет шагов

batch объединяет 2–3 заранее известных шага в одном окне: например, нажать поле, ввести текст и перейти к следующему полю. Пакет нужен только тогда, когда между шагами не требуется решение по новому снимку.

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

Ожидание результата

Действие wait делает паузу и возвращает новое наблюдение. С параметром query и условием оно ждёт появления элемента, его исчезновения или изменения значения — это удобно для загрузки, сохранения и появления уведомлений. Истечение времени ожидания не доказывает ни появление, ни отсутствие изменения: агент опирается на снимок и сообщает, что удалось подтвердить.

Подтверждения

Наблюдение и ввод различаются по уровню риска.

Что делает агент Поведение по умолчанию
Список окон, снимок конкретного окна, увеличение, ожидание Выполняется без вопросов
Поиск окна по приложению или заголовку, снимок рабочего стола Требует подтверждения
Клики, клавиши, ввод текста, прокрутка, перетаскивание, пакет шагов Требует подтверждения

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

Режим подтверждений влияет на доступность инструмента:

  • default и auto_edit оставляют подтверждение для ввода;
  • yolo выполняет и ввод без вопросов.

В неинтерактивном режиме инструмент доступен только при yolo: этот запуск не умеет спрашивать согласие.

Разрешения macOS

На macOS встроенному помощнику Koda Computer Use нужны два разрешения:

  • Универсальный доступ — чтобы нажимать элементы и вводить текст;
  • Запись экрана — чтобы делать снимки окон.

Состояние разрешений и запрос одного права выполняет команда /computer-use:

/computer-use                       показать состояние разрешений
/computer-use accessibility         запросить универсальный доступ
/computer-use screen-recording      запросить запись экрана

Запрос показывает системное предложение macOS: выдайте разрешение в нём, а не в отдельно открытых настройках. Команда не повторяет запрос сама, а чтение состояния не вызывает системных предложений.

Два разных разрешения

Для оконного режима разрешение нужно помощнику Koda Computer Use. Для режима рабочего стола на macOS права нужны приложению, из которого запущен CLI, — терминалу или Koda Desktop: это отдельная запись в системных настройках, и разрешение помощника её не заменяет.

Пока разрешений нет, ввод не отправляется, а задача останавливается. После выдачи разрешений отправьте новый запрос: прежнее действие не повторяется автоматически.

Работа вместе с другими продуктами

Koda CLI и Koda Desktop делят один компьютер, поэтому их операции управления компьютером выполняются по очереди через общий механизм координации. Если ввод уже начат другим процессом, CLI дождётся своей очереди, а не отправит действия одновременно.

Плагин для IDE в этой координации пока не участвует: если вы работаете с окнами и через плагин, и через CLI, между действиями нужен новый снимок, а параллельную работу лучше не планировать.

Что видит модель

Снимок окна приходит модели как изображение вместе с текстовым описанием элементов. В запросе к модели остаются последние 2–4 полных наблюдения: более старые заменяются короткой строкой с окном и номером шага, без идентификаторов. История диалога при этом не переписывается — сокращается только то, что отправляется модели, поэтому в разговоре по-прежнему видны все снимки.

Если помощник недоступен или не хватает разрешений, ответ содержит типизированную ошибку настройки. Остальные вызовы computer_use в этом же ходе к компьютеру не обращаются, а ход завершается: сначала нужно устранить причину и отправить новый запрос.

Ограничения платформ

  • работа с окнами идёт в фоне;
  • доступен режим рабочего стола: снимок всех дисплеев и ввод по координатам экрана. Такой ввод использует настоящую мышь и текущее активное приложение, поэтому требует отдельного подтверждения;
  • для рабочего стола нужен хотя бы один и не больше четырёх активных дисплеев;
  • увеличение области для рабочего стола не поддерживается;
  • перетаскивание в фоне не поддерживается;
  • нужны разрешения Универсальный доступ и Запись экрана, см. «Разрешения macOS».
  • доступен только режим окон: снимок и ввод в конкретном окне;
  • защищённые и запущенные с повышенными правами приложения могут отказать во вводе;
  • CLI не повышает права и не отключает защиту автоматически.
  • доступен только режим окон, нужен X11 или XWayland;
  • чистая сессия Wayland не поддерживается, а XWayland открывает не все окна Wayland;
  • часть приложений отдаёт неполное дерево элементов, поэтому агент чаще использует координаты;
  • некоторым приложениям для фонового ввода нужен доступ к /dev/uinput; CLI не меняет права устройств и настройки рабочего стола автоматически.

Безопасность

  • Содержимое окон — это данные, а не команды. В письме, на веб-странице или в документе может встретиться текст с инструкциями; агент не считает его задачей.
  • Подтверждайте чувствительные действия. Клик по кнопке отправки, публикация или удаление лучше оставлять с подтверждением.
  • Не поручайте ввод секретов. Пароли и ключи, набранные агентом, попадают в снимки и историю сессии.
  • Отказ приложения окончателен. Если приложение не принимает фоновый ввод, Koda не обходит ограничение через shell, сценарии системы или передний план.
  • Повторов нет. После ошибки, отказа или остановки действие не повторяется само: сначала нужно новое наблюдение.
  • Координация не защищает документ от человека. Ввод агента и ваша работа в том же окне не изолированы друг от друга.

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

  • Инструмента нет в списке /tools. Проверьте режим, локальность сессии, отсутствие песочницы, операционную систему, поддержку изображений моделью и значение coreTools/excludeTools.
  • /computer-use сообщает, что Computer Use недоступен. Помощник не поставлен или не запускается: обновите CLI, а на Linux убедитесь, что запущена графическая сессия X11 или XWayland.
  • /computer-use показывает, что разрешения не выданы. Запросите нужное право командой /computer-use accessibility или /computer-use screen-recording и выдайте его в системном предложении.
  • Ввод не отправляется, хотя разрешение выдано. Проверьте, что разрешение получил помощник Koda Computer Use, а для режима рабочего стола — приложение, из которого запущен CLI.
  • Агент не находит нужное окно. Уточните приложение или заголовок окна: одинаковые окна одного приложения различаются, а список выдаётся страницами.
  • Приложение не реагирует на действия. Защищённые приложения, чистая сессия Wayland и отсутствие доступа к /dev/uinput на Linux могут блокировать фоновый ввод.
  • Действие не повторилось после выдачи разрешений. Так и задумано: отправьте новый запрос, и агент начнёт с нового наблюдения.

Читайте также