Быстрый старт с OpenHands Coding Assistant: установка, флаги командной строки, примеры

Быстрый старт с OpenHands CLI за несколько минут

Содержимое страницы

OpenHands — это открытая платформа, не зависящая от конкретной модели, для агентов ИИ в сфере разработки программного обеспечения. Она позволяет агенту вести себя скорее как партнер по программированию, чем как простой инструмент автодополнения.

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

Этот быстрый старт сосредоточен на CLI OpenHands, так как это самый быстрый способ начать продуктивную работу из терминала, и он идеально подходит для автоматизации паттернов, таких как скрипты и CI-запуски. Чтобы получить более широкий обзор этой сферы, см. Инструменты разработчика ИИ: Полное руководство по разработке с помощью ИИ.

openhands text user interface

Что такое OpenHands и в чем его особенность

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

OpenHands также широко известен как проект, ранее называвшийся OpenDevin, и он вырос в общедоступную платформу с множеством способов использования: CLI, локальный веб-интерфейс, облачный UI и SDK.

С инженерной точки зрения ключевое отличие заключается в том, что OpenHands построен вокруг среды выполнения (песочницы), чтобы агент мог безопасно запускать команды и инструменты, а не просто генерировать текст. В статье об OpenHands описывается среда выполнения с песочницей Docker, оснащенная оболочкой и возможностью просмотра веб-страниц, специально для поддержки реалистичных паттернов взаимодействия, характерных для разработчиков.

Установка CLI OpenHands

OpenHands поддерживает несколько методов установки. Для большинства разработчиков лучше всего начать с локальной установки CLI (быстрая итерация) и по желанию добавить workflows на основе Docker позже, когда потребуется строгая изоляция выполнения.

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

В текущей документации CLI OpenHands рекомендуется установка с помощью uv, и требуется Python 3.12+.

uv tool install openhands --python 3.12
openhands

Обновление аналогично просто.

uv tool upgrade openhands --python 3.12

Почему uv важен на практике: uv обеспечивает лучшую изоляцию от вашей текущей среды проекта и необходим для серверов MCP по умолчанию.

Установка автономного CLI-бинарника

Если вы хотите использовать поток установки «одной командой», OpenHands предоставляет скрипт установки.

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

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

Запуск через Docker для изоляции

Если вы предпочитаете содержать установку в одном месте, документация CLI также показывает поток на основе Docker. Этот подход опирается на монтирование директории, к которой OpenHands должен иметь доступ, и передачу вашего ID пользователя, чтобы избежать создания файлов, принадлежащих root, в смонтированном рабочем пространстве.

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.12.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"

Настройка при первом запуске и расположение настроек

При первом запуске CLI проведет вас через настройку необходимых настроек LLM и сохранит их для будущих сессий. Документация CLI гласит, что настройки сохраняются в ~/.openhands/settings.json, а история разговоров хранится в ~/.openhands/conversations, но когда я недавно установил OpenHands, он сохранил конфигурацию в ~/.openhands/agent_settings.json, так что, возможно, документация не совсем точна.

Для более глубокой настройки и интеграции инструментов OpenHands также документирует дополнительные файлы конфигурации, такие как ~/.openhands/agent_settings.json (настройки агента и LLM), ~/.openhands/cli_config.json (предпочтения CLI) и ~/.openhands/mcp.json (серверы MCP).

Настройка OpenHands с локальным Ollama и llama.cpp

OpenHands работает с любым локальным бэкендом, совместимым с OpenAI — Ollama, LocalAI, llama.cpp и другие. Если вы не уверены, что выбрать, см. Ollama vs vLLM vs LM Studio: Лучший способ запускать LLM локально для сравнения.

Когда вы запускаете OpenHands впервые, он показывает вам страницу настроек, Если вы уже прошли этот этап первого запуска, вы можете открыть эту страницу снова, набрав /settings, а затем ctrl+j Теперь введите:

  • в поле Custom Model: ollama/devstral-small-2:24b, или другую вашу любимую локальную модель,
  • и в поле Base Url: http://localhost:11434

openhands settings ollama mistral

Для быстрого справочника по командам Ollama см. Шпаргалка CLI Ollama: serve, run, ps и управление моделями.

Чтобы вручную отредактировать файл конфигурации OpenHands, например, если вам не нравится, как выглядит страница настроек, выполните:

nano ~/.openhands/agent_settings.json

или, если вы предпочитаете редактор с большим GUI:

gedit GUI ~/.openhands/agent_settings.json

Свойство llm находится в двух местах, я установил их, чтобы иметь следующие подсвойства (среди прочих), указывающие на ollama:

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

Чтобы указать OpenHands на локальный экземпляр llama.cpp — то же самое, в двух местах:

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

Чтобы подключиться к llama.cpp, я настроил:

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

и запускал llama.cpp с помощью команды (см. Быстрый старт llama.cpp с CLI и сервером для деталей флагов):

./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

OpenHands успешно подключился к нему и выполнил мой тестовый запрос создай для меня CLI-инструмент на Go, который будет вызывать конечные точки indexnow Bing и других поисковых систем для уведомления об изменениях на моем сайте — с исходным кодом, исполняемым файлом и README.md.

Как работает CLI OpenHands на практике

Команда по умолчанию openhands запускает интерактивный опыт в терминале. OpenHands предоставляет палитру команд и команды внутри сессии, чтобы вы могли быстро направлять агента, пока он работает.

Полезные интерактивные элементы управления, которые стоит знать заранее, включают открытие палитры команд, приостановку агента и выход из приложения.

  • Ctrl+P открывает палитру команд.
  • Esc приостанавливает работающего агента.
  • Ctrl+Q или /exit завершает работу CLI.

Внутри CLI OpenHands также поддерживает команды с префиксом слэша, такие как /help, /new и /condense, что ценно, если вы хотите управлять длинными разговорами без перезапуска.

OpenHands не останавливается на терминальном интерфейсе. CLI включает несколько интерфейсов, которые хорошо соответствуют различным рабочим процессам разработчиков:

  • Безголовый режим (Headless mode) для автоматизации и CI.
  • Веб-интерфейс для запуска опыта CLI в браузере.
  • Сервер GUI для полноценного локального веб-приложения, запускаемого через Docker.
  • Интеграция с IDE через ACP для рабочих процессов на основе редактора.

Основные параметры командной строки, которые вы будете использовать

На высоком уровне CLI OpenHands следует этой структуре:

openhands [OPTIONS] [COMMAND]

Это включает глобальные опции (такие как задачи, возобновление, безголовый режим), плюс подкоманды (serve, web, cloud, acp, mcp, login, logout).

Основные опции для повседневной работы

Наиболее часто используемые глобальные опции:

  • -t, --task для инициализации разговора начальной задачей.
  • -f, --file для инициализации из файла, что удобно, когда вы хотите, чтобы задачи были зафиксированы в системе контроля версий.
  • --resume [ID] и --last для продолжения предыдущих запусков.
  • --headless для неинтерактивного выполнения, обычно в автоматизации.
  • --json для потоковой передачи вывода JSONL в безголовом режиме для машинного разбора.

Безопасность и одобрения также имеют первостепенное значение:

  • --always-approve автоматически одобряет действия без запросов.
  • --llm-approve использует анализатор безопасности на основе LLM для одобрения действий.

Конфигурация модели и провайдера через переменные окружения

OpenHands поддерживает переменные окружения для конфигурации модели:

  • LLM_API_KEY задает ваш API-ключ провайдера.
  • LLM_MODEL и LLM_BASE_URL могут применяться как переопределения при выполнении openhands --override-with-envs.

Пример потока переопределения:

export LLM_MODEL="gpt-4o"
export LLM_API_KEY="your-api-key"
openhands --override-with-envs

OpenHands явно указывает, что переопределения, примененные с --override-with-envs, не сохраняются.

Подкоманды, которые стоит знать

Вам не нужны все подкоманды с первого дня, но эти появляются быстро:

  • openhands serve запускает полный сервер GUI с использованием Docker, обычно доступный по адресу http://localhost:3000, с опциями, такими как --mount-cwd и --gpu.
  • openhands web запускает CLI как веб-приложение, доступное из браузера, по умолчанию на порту 12000.
  • openhands login аутентифицирует вас в OpenHands Cloud и загружает ваши настройки.
  • openhands cloud создает новый разговор в OpenHands Cloud из CLI.

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

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

Запустите интерактивную сессию программирования с начальной задачей

Это «стандартный опыт разработчика» и один из самых распространенных паттернов.

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

Документация CLI OpenHands показывает именно эту идею для инициализации сессии с помощью -t.

Инициализация задачи из файла

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

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

openhands -f task.txt

CLI Quick Start явно поддерживает запуск из файла задачи с помощью -f.

Запустите в безголовом режиме для CI или автоматизации

Безголовый режим работает без интерактивного интерфейса и предназначен для CI-конвейеров и автоматизированных скриптов.

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

Два важных инженерных факта здесь:

  • Безголовый режим требует --task или --file.
  • В безголовом режиме всегда включен режим автоматического одобрения, и его нельзя изменить, а --llm-approve недоступен в безголовом режиме. Относитесь к этому как к мощной автоматизации и запускайте в контролируемой среде.

Для интеграции с анализом логов или другими инструментами включите вывод JSONL:

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

OpenHands документирует --json как потоковую передачу событий JSONL в безголовом режиме и показывает перенаправление вывода в файл.

Возобновите работу без потери контекста

Возобновление критически важно, как только вы начнете использовать OpenHands для нетривиальных изменений.

Список последних разговоров:

openhands --resume

Возобновить последний:

openhands --resume --last

Или возобновить конкретный ID разговора:

openhands --resume abc123def456

Эти потоки задокументированы в справочнике команд CLI и руководстве «Возобновление разговоров».

Запустите CLI в браузере, когда это необходимо

openhands web запускает доступный из сети CLI (порт по умолчанию 12000).

openhands web

Если вы работаете локально, привязка только к localhost является разумным значением по умолчанию:

openhands web --host 127.0.0.1 --port 12000

OpenHands предупреждает, что публикация веб-интерфейса в сети требует соответствующих мер безопасности, так как он предоставляет полный доступ к возможностям OpenHands.

Безопасность, устранение неполадок и острые углы

Самый важный рычаг безопасности в CLI OpenHands — это одобрения:

  • Интерактивный CLI может запрашивать подтверждение перед выполнением чувствительных действий, и вы можете настроить настройки подтверждения в сессии.
  • --always-approve устраняет трение, но также убирает средства защиты.
  • --llm-approve добавляет анализатор на основе LLM для одобрений.
  • В безголовом режиме всегда происходит одобрение, поэтому используйте его только для автоматизации в контролируемых средах.

При работе с локальным кодом предпочитайте явные паттерны доступа с минимальными привилегиями:

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

Если у вас есть старые директории состояния OpenHands, OpenHands указывает путь миграции с ~/.openhands-state на ~/.openhands в документации по локальной установке и руководствах по устранению неполадок.

Наконец, если вы интегрируете OpenHands в скрипты, коды выхода задокументированы как:

  • 0 успех
  • 1 ошибка или задача не выполнена
  • 2 некорректные аргументы

Мой опыт работы с OpenHands

Для меня OpenHands работал хорошо, но не всегда… Я пытался заставить его работать с Devstral-Small-2, размещенным на Ollama, и он постоянно останавливался.

OpenHands with Ollama-hosted Devstral-Small-2.

Хотя OpenHands хорошо работал с локально размещенным на llama.cpp Qwen 3.5 35b. Пока что для меня OpenCode намного более надежен.