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

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

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

Возможность работает в VS Code и в IDE на платформе IntelliJ.

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

Режим агента. В чате и в режиме планирования инструмент недоступен: там нет действий, меняющих состояние.
Локальный компьютер. Удалённые окружения не поддерживаются: Remote SSH, WSL, Dev Containers и GitHub Codespaces инструмент не получают.
Поддерживаемая система. macOS 14 и новее (Apple Silicon и Intel), Windows x64, Linux x64 с X11 или XWayland. Чистый Wayland не поддерживается.
Модель с поддержкой изображений. Агент получает снимки окон, поэтому выбранная модель должна уметь работать с изображениями. Если модель текстовая, инструмент не предлагается.
Включённый инструмент. computer_use есть в списке Инструменты в режиме Агент. Политика по умолчанию — С подтверждением, см. «Разрешения и подтверждения».
Разрешения операционной системы. На macOS нужны два разрешения, см. «Разрешения macOS».

Как это выглядит в чате¶

Вызов инструмента показывается отдельной карточкой с названием действия. В карточке видны параметры вызова: окно, элемент или координаты, вводимый текст.

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

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

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

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

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

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

Ссылка на окно, идентификатор элемента и идентификатор снимка берутся из конкретного наблюдения. Они действуют 10 минут и сбрасываются после любого ввода, поэтому агент копирует их из последнего результата, а не придумывает.

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

Действие	Что делает
`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 и условием оно ждёт появления элемента, его исчезновения или изменения значения — это удобно для загрузки, сохранения и появления уведомлений. Истечение времени ожидания не доказывает ни появление, ни отсутствие изменения: агент опирается на снимок и сообщает, что удалось подтвердить.

Разрешения и подтверждения¶

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

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

Политику можно изменить в списке Инструменты режима Агент: Автоматически, С подтверждением или Выключен. Как это устроено — в разделе «Как управлять инструментами».

Автоматическое наблюдение не расширяет права: снимок рабочего стола и любой ввод по-прежнему подчиняются политике инструмента. Если политика — Автоматически, агент выполняет и ввод, поэтому включайте её только для задач, где вы готовы доверить действия целиком.

Разрешения macOS¶

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

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

Когда разрешений не хватает, в чате появляется карточка Доступ к Mac с кнопками Универсальный доступ и Запись экрана. Кнопки открывают нужный раздел системных настроек, а карточка сама обновляет состояние, пока вы не закроете её.

Разрешение выдаётся помощнику, а не редактору

В системных настройках разрешение нужно включить для Koda Computer Use, а не для VS Code или IntelliJ. Если включить доступ только редактору, снимки и ввод всё равно не заработают.

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

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

macOSWindowsLinux

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

доступен только режим окон: снимок и ввод в конкретном окне;
защищённые и запущенные с повышенными правами приложения могут отказать во вводе;
Koda не повышает права и не отключает защиту автоматически.

доступен только режим окон, нужен X11 или XWayland;
чистая сессия Wayland не поддерживается, а XWayland открывает не все окна Wayland;
часть приложений отдаёт неполное дерево элементов, поэтому агент чаще использует координаты;
некоторым приложениям для фонового ввода нужен доступ к /dev/uinput; Koda не меняет права устройств и настройки рабочего стола автоматически.

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

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

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

Инструмента нет в списке. Проверьте режим (нужен агент), локальность проекта, операционную систему, поддержку изображений выбранной моделью и политику инструмента.
Появилась карточка «Доступ к Mac». Нажмите обе кнопки и выдайте разрешения помощнику Koda Computer Use в системных настройках.
В карточке вызова написано «Разрешите управление Mac в настройках». Проверьте разрешения помощника в системных настройках: без них ввод не отправляется.
Koda сообщает, что Koda Computer Use недоступен. Встроенный помощник не запускается или его версия не подходит: обновите либо переустановите расширение Koda.
Агент не находит нужное окно. Уточните приложение или заголовок окна: одинаковые окна одного приложения различаются, а список выдаётся страницами.
Приложение не реагирует на действия. Защищённые приложения, чистая сессия Wayland и отсутствие доступа к /dev/uinput на Linux могут блокировать фоновый ввод.
Действие не повторилось после выдачи разрешений. Так и задумано: отправьте новый запрос, и агент начнёт с нового наблюдения.