OpenHands CLI: Быстрый старт, установка, флаги, headless-режим

OpenHands — это агент для кодирования с открытым исходным кодом, который редактирует файлы и выполняет команды в песочнице. Данный быстрый старт для CLI был проверен 26.10.2026 г. в соответствии с пакетом версии 1.16.0.

Пакет на PyPI openhands версии 1.16.0 был загружен 8 мая 2026 г. и закреплён на openhands-sdk==1.21.0. В README с тегом указано требование Python 3.12 и uv версии 0.11.6 или новее. README ветки по умолчанию репозитория OpenHands-CLI сообщает, что этот репозиторий более не активно поддерживается и направляет новых пользователей на Agent Canvas. Режим headless и команда openhands acp по-прежнему входят в набор команд версии 1.16.0.

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

Что такое CLI

Ассистент ИИ для кодирования, как правило, генерирует или редактирует код на основе запроса. OpenHands расширяет этот подход в агентный цикл: планирование, выполнение действия (например, запись файла или запуск теста), наблюдение за результатом и продолжение работы. Ранее проект назывался OpenDevin. Статья об OpenHands описывает среду выполнения в Docker-песочнице с оболочкой и возможностью просмотра веб-страниц, что является моделью выполнения, которую CLI по-прежнему оборачивает.

Выпуск 1.16.0 документирует пять способов запуска этого цикла.

Agent Canvas: текущая поддерживаемая установка

3 июня 2026 г. в FAQ проекта OpenHands было указано, что терминальный UI переходит в режим поддержки до 1 октября 2026 г., при этом headless-режим и ACP останутся полностью поддерживаемыми. Локальный GUI (openhands serve) также должен был оставаться в режиме поддержки, пока Agent Canvas не сможет запускать изолированные эфемерные песочницы. В этом FAQ поддержка определяется как обновление зависимостей, исправление критических ошибок и добавление новых LLM. В главном репозитории OpenHands 23 октября 2026 г. был выпущен Agent Canvas версии 1.33.0.

agent-canvas запускает текущий UI и его бэкенд. openhands serve запускает устаревший GUI и не запускает Agent Canvas.

Для Agent Canvas требуется Node.js версии 24 или новее и uv. Первый запуск без глобальной установки:

npx @openhands/agent-canvas

Процесс слушает порт на http://localhost:8000. Закрытие этого терминала останавливает локальный бэкенд. Глобальная установка выполняется командой npm install -g @openhands/agent-canvas, после чего запускается agent-canvas. Установка через npm запускает сервер агента под вашим пользователем, поэтому агент может воздействовать на локальные файлы с разрешениями вашей учётной записи.

Docker-путём порт публикуется только на localhost, а каталог проектов монтируется внутрь контейнера:

mkdir -p ~/projects

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -v openhands-data:/home/openhands/.openhands \
  -v ~/projects:/projects \
  ghcr.io/openhands/agent-canvas:latest

Контейнер предоставляет UI по адресу http://localhost:8000/canvas. Именованный том openhands-data сохраняет настройки после использования флага --rm. На Linux попытка bind-mount-а каталога ~/.openhands в этот образ завершается ошибкой unable to open database file: пользователь контейнера имеет UID 10001, а каталог на хосте обычно принадлежит вашему UID. Именно по этой причине на странице установки используется именованный том. Настройки, уже находящиеся в ~/.openhands, не копируются в новый том.

Установка OpenHands CLI

Используйте CLI, если вам всё ещё нужны команды openhands --headless или openhands acp. Опубликованное колесо устанавливается только в среде Python 3.12 (спецификация ==3.12.* на PyPI). Версия uv должна быть 0.11.6 или новее. На Windows страница установки рекомендует выполнять команды в WSL (Ubuntu).

Установка с помощью uv

uv tool install openhands --python 3.12
openhands

Обновление с тем же закреплением интерпретатора:

uv tool upgrade openhands --python 3.12

На странице локальной настройки указано, что uv изолирует CLI от виртуального окружения проекта, и что по умолчанию MCP-серверы требуют его.

Установка автономного бинарного файла

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

На macOS диалоговое окно Gatekeeper может блокировать бинарный файл («openhands не может быть открыт, потому что Apple не может проверить его на наличие вредоносного ПО»). Путь, указанный на странице установки: Система -> Настройки -> Конфиденциальность и безопасность -> Разрешить всё равно (в разделе Безопасность), после чего снова выполнить openhands.

Запуск CLI через Docker

Контейнер на странице установки устанавливает переменную AGENT_SERVER_IMAGE_TAG для образа agent-server. Команда uv tool install openhands внутри контейнера устанавливает CLI с PyPI. Тег в этом примере, проверенный для этой страницы, — 1.26.0-python. В более старых копиях этой команды использовался тег 1.12.0-python.

export SANDBOX_VOLUMES="$PWD:/workspace"

docker run -it \
  --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e SANDBOX_USER_ID=$(id -u) \
  -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/root/.openhands \
  --add-host host.docker.internal:host-gateway \
  --name openhands-cli-$(date +%Y%m%d%H%M%S) \
  python:3.12-slim \
  bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

Параметр SANDBOX_USER_ID=$(id -u) делает пользователя песочницы идентичным пользователю хоста, чтобы агент не оставлял файлов, принадлежащих root, в смонтированном рабочем каталоге. SANDBOX_VOLUMES — это каталог, к которому агент имеет доступ.

Переменная OPENHANDS_VERSION выбирает версию Docker-образа для openhands serve. Она не меняет версию CLI с PyPI.

Файлы настроек

При первом запуске CLI запрашивает настройки модели и записывает их в ~/.openhands/. В README версии 1.16.0 и справочнике по командам указаны следующие файлы:

Страница установки всё ещё сообщает пользователям Docker готовить файл ~/.openhands/settings.json. Однако CLI README и класс AgentStore в дереве версии 1.16.0 сохраняют спецификацию агента в agent_settings.json. Установка CLI, пропустившая имя файла со страницы установки и записавшая agent_settings.json, соответствует этому источнику.

Функция create_and_save_from_settings создаёт два объекта LLM из одной модели, API-ключа и base URL: один для агента и один для суммаризирующего конденсатора. Поэтому в сохранённом файле дублируются поля llm. Редактируйте файл агента любым редактором:

nano ~/.openhands/agent_settings.json

Переменные LLM_API_KEY, LLM_MODEL и LLM_BASE_URL игнорируются, если вы не включите опцию переопределения. Переопределение не сохраняется:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="ваш-api-ключ"
openhands --override-with-envs

OPENHANDS_CLOUD_URL задает сервер облака по умолчанию. Команды cloud и login используют https://app.all-hands.dev по умолчанию, если эта переменная не установлена.

Обновление с версий CLI старше 1.0.0 требует повторного ввода настроек. На странице установки указано, что формат конфигурации изменился в версии 1.0.0.

Локальные модели

В руководстве по локальным LLM от 21 мая 2026 г. рекомендуется Qwen3.6-35B-A3B как первая локальная модель для проверки. Требуется GPU с видеопамятью не менее 24 ГБ для квантованной сборки или Mac с Apple Silicon с объёмной памятью не менее 64 ГБ. На той же странице рекомендуется установить длину контекста не менее 22000 токенов, а также указано, что значение по умолчанию Ollama (4096) слишком мало для системного промпта.

Если агент никогда не вызывает инструменты, руководство считает это ограничением модели и ссылается на сообщения сообщества для qwen2.5-coder-14b-instruct и qwopus3.5-27b-v3. Сравнение локального хостинга служит таблицей сравнения по серверам, если выбор между Ollama, vLLM, LM Studio или LocalAI ещё не сделан.

Ollama

В руководстве для запуска Ollama длина контекста устанавливается до выполнения ollama serve. Шпаргалка по CLI Ollama описывает serve, run и ps вместе с этой переменной.

OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 OLLAMA_KEEP_ALIVE=-1 ollama serve
ollama pull qwen3.6:35b-a3b

Для OpenHands, работающего в Docker, в руководстве указаны настраиваемая модель openai/qwen3.6:35b-a3b, base URL http://host.docker.internal:11434/v1 и любой плейсхолдер API-ключа. CLI, работающий на том же хосте, что и Ollama, использует http://127.0.0.1:11434/v1 вместо host.docker.internal. Linux LM Studio и другие серверы, работающие только на loopback, недоступны из контейнера через 127.0.0.1; проверка в руководстве заключается в включении обслуживания в локальной сети и выполнении curl host.docker.internal изнутри контейнера.

Страница терминала открывает этот экран сочетанием Ctrl+P, затем выбирает Настройки. Сохранённый профиль CLI использовал идентификатор модели ollama/ и base URL без /v1:

• Пользовательская модель: ollama/devstral-small-2:24b
• Base URL: http://localhost:11434

Именно сессия с Devstral-Small-2, описанная выше, постоянно останавливалась. Поля, записанные для неё (как в LLM агента, так и в LLM конденсатора), были следующими:

"llm": {
  "model": "ollama/devstral-small-2:24b",
  "api_key": "aaa",
  "base_url": "http://localhost:11434"
}

llama.cpp и vLLM

llama.cpp использовал префикс, совместимый с OpenAI, и base URL /v1, снова в обоих объектах LLM:

• "model": "openai/Qwen3.5-35B-A3B-UD-IQ3_S.gguf"
• "base_url": "http://localhost:8080/v1"

Команда сервера, флаги которой описаны в быстром старте llama.cpp, была следующей:

./llama.cpp/llama-server \
    -m /mnt/ggufs/Qwen3.5-35B-A3B-UD-IQ3_S.gguf \
    --ctx-size 70000 \
    -ngl 40 \
    --temp 0.6 \
    --top-p 0.95 \
    --top-k 20 \
    --min-p 0.00

Против этого сервера CLI завершил работу над клиентом Go IndexNow: исходный код, исполняемый файл и README. Текст задачи был: создай для меня CLI-инструмент на Go, который будет вызывать endpoints indexnow поисковых систем bing и других для уведомления об изменениях на моём сайте.

Пример vLLM в руководстве по локальным LLM для более новой модели Qwen3.6 — это обслуживание на двух GPU. Быстрый старт vLLM проходит через флаги vllm serve и проверки исчерпания памяти. Соответствующая строка модели OpenHands в руководстве — openai/Qwen3.6-35B-A3B, base URL http://host.docker.internal:8000/v1 и тот же --api-key, с которым был запущен сервер (mykey в их примере).

vllm serve Qwen/Qwen3.6-35B-A3B \
    --host 0.0.0.0 --port 8000 \
    --api-key mykey \
    --tensor-parallel-size 2 \
    --served-model-name Qwen3.6-35B-A3B \
    --enable-prefix-caching

Интерактивные элементы управления

Запуск openhands без подкоманды открывает терминальный UI. На странице терминала перечислены эти элементы управления:

Слэш-команды из справочника по командам: /help, /new, /history, /confirm, /condense, /skills, /feedback, /exit. Изменения модели из палитры (раздел Настройки) применяются без перезапуска. --exit-without-confirmation пропускает диалог подтверждения выхода. --exp выбирает текстовый UI и задокументирован как флаг совместимости, так как этот UI уже является значением по умолчанию.

Флаги и подкоманды

openhands [ОПЦИИ] [КОМАНДА]

Глобальные опции из справочника по командам, проверенные относительно argparsers/util.py в теге 1.16.0 для флагов подтверждения и окружения:

Флаги --always-approve и --llm-approve не могут использоваться одновременно. В режиме интерактивного использования по умолчанию перед действиями запрашивается подтверждение.

Подкоманды, которые появляются, когда TUI недостаточны:

• openhands serve запускает устаревший GUI в Docker. --mount-cwd монтирует текущий каталог в /workspace. --gpu включает nvidia-docker.
• openhands web предоставляет CLI в браузере. --host по умолчанию 0.0.0.0, --port — 12000, --debug выключен.
• openhands acp общается по протоколу Agent Client Protocol через stdio. Флаги: --resume, --last, --always-approve, --llm-approve, --streaming.
• openhands cloud -t "задача" открывает облачный разговор. --server-url переопределяет https://app.all-hands.dev.
• openhands login и openhands logout управляют этой облачной учётной записью. logout без --server-url выходит из всех сохранённых серверов.
• openhands mcp управляет серверами: add, list, get, remove, enable, disable. Команда add требует --transport типа http, sse или stdio.

MCP-сервер из README версии 1.16.0:

openhands mcp list
openhands mcp add tavily --transport stdio \
  npx -- -y mcp-remote "https://mcp.tavily.com/mcp/?tavilyApiKey=<ваш-api-ключ>"
openhands mcp enable tavily
openhands mcp disable tavily

Примеры

Интерактивная задача

openhands -t "Исправь ошибку в auth.py и добавь регрессионный тест"

Файл задачи

cat > task.txt << 'EOF'
Рефакторинг модуля подключения к базе данных.
Добавление юнит-тестов и обеспечение прохода тестового набора.
EOF

openhands -f task.txt

Headless, включая JSONL

Режим headless требует --task или --file. Он всегда работает с полным подтверждением действий, а --llm-approve там отклоняется. Рассматривайте рабочий каталог как тот, который агент может свободно модифицировать.

openhands --headless -t "Добавь юнит-тесты для auth.py и запусти их"

openhands --headless --json -t "Создай простое приложение Flask с healthcheck endpoint" > openhands-output.jsonl

Страница headless описывает --json как один JSON-объект на событие, потоково передаваемый в формате JSONL.

Возобновление

openhands --resume
openhands --resume --last
openhands --resume abc123def456

Браузерный TUI с привязкой к localhost

openhands web по умолчанию привязывается к 0.0.0.0:12000, что делает его доступным из сети. В документации CLI указано, что этот интерфейс обладает полным функционалом CLI, поэтому привязка только к локальному хосту — более безопасный вариант по умолчанию:

openhands web --host 127.0.0.1 --port 12000

ACP для редактора

ACP-клиенты на странице IDE — это Zed и JetBrains (нативные), Toad (нативный) и VS Code (расширение сообщества). Редактор запускает openhands acp и общается через JSON-RPC 2.0 по stdio, используя сохранённые настройки LLM CLI.

openhands acp
openhands acp --llm-approve
openhands acp --resume --last

Подтверждения, коды выхода и результаты локальных моделей

В интерактивных сессиях перед действиями запрашивается подтверждение. /confirm меняет эту политику в сессии. --always-approve (алиас --yolo) подтверждает всё. --llm-approve запрашивает подтверждение только для действий, которые анализатор безопасности оценивает как высокий риск. Режим headless всегда работает с полным подтверждением на протяжении всего запуска.

openhands serve --mount-cwd монтирует текущий каталог в /workspace внутри контейнера устаревшего GUI. Docker CLI-поток использует SANDBOX_VOLUMES для той же границы.

Коды выхода из справочника по командам:

Devstral-Small-2 24B на Ollama неоднократно останавливался в этом CLI.

Сессия llama.cpp выше (Qwen3.5-35B-A3B с контекстом в 70000 токенов) успешно завершила задачу IndexNow. Для терминального агента, который продолжал работать на той же машине, быстрый старт OpenCode служит руководством по установке и настройке провайдеров.