Openhands

OpenHands CLI

Delegate coding tasks to the OpenHands CLI via the terminal tool. OpenHands is model-agnostic: any LiteLLM-supported provider (OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, vLLM, etc.).

This skill is the headless-mode wrapper for batch / one-shot delegation. The interactive textual UI is not used from Hermes.

When to Use

• User wants a coding task delegated to OpenHands specifically.
• User wants a coding agent that can run on a non-Anthropic / non-OpenAI provider (DeepSeek, Qwen, Ollama, vLLM, Nous, etc.) — sibling skills claude-code and codex are tied to one vendor.
• Multi-step file edits + shell commands inside a workspace.

For Claude-native, prefer claude-code. For OpenAI-native, prefer codex. For Hermes-native subagents, use delegate_task.

Prerequisites

1. Install upstream (requires Python 3.12+ and uv):

   terminal(command="uv tool install openhands --python 3.12")

   Verify: openhands --version (currently OpenHands CLI 1.16.0 / SDK v1.21.0 at time of writing).

2. Pick a model and set env vars for --override-with-envs:

   export LLM_MODEL=openrouter/openai/gpt-4o-mini       # or any LiteLLM slug
   export LLM_API_KEY=$OPENROUTER_API_KEY
   export LLM_BASE_URL=https://openrouter.ai/api/v1     # omit for native OpenAI

   LLM_MODEL uses LiteLLM's full slug. When the provider is OpenRouter the slug is doubly-prefixed: openrouter/<vendor>/<model> (e.g. openrouter/anthropic/claude-sonnet-4.5). For native Anthropic: anthropic/claude-sonnet-4-5. For native OpenAI: openai/gpt-4o-mini.

3. Suppress the startup banner so JSON output isn't preceded by ASCII art:

   export OPENHANDS_SUPPRESS_BANNER=1

How to Run

Always invoke through the terminal tool. Always pass --headless --json --override-with-envs --exit-without-confirmation for automation.

One-shot task

terminal(
  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=openrouter/openai/gpt-4o-mini LLM_API_KEY=$OPENROUTER_API_KEY LLM_BASE_URL=https://openrouter.ai/api/v1 openhands --headless --json --override-with-envs --exit-without-confirmation -t 'Add error handling to all API calls in src/'",
  workdir="/path/to/project",
  timeout=600
)

Background for long tasks

terminal(command="<same as above>", workdir="/path/to/project", background=true, notify_on_complete=true)
process(action="poll", session_id="<id>")
process(action="log", session_id="<id>")

Resume a previous conversation

OpenHands prints Conversation ID: <32-hex> and a Hint: openhands --resume <dashed-uuid> line at the end of each run. Use the dashed form to resume:

terminal(
  command="OPENHANDS_SUPPRESS_BANNER=1 LLM_MODEL=... openhands --headless --json --override-with-envs --exit-without-confirmation --resume <dashed-uuid> -t 'Now fix the bug you found'",
  workdir="/path/to/project"
)

Real Flag List

Verified against openhands --help (CLI 1.16.0). Anything not in this table is not a flag — pass it via env var or settings file.

There is no --model, --max-iterations, --workspace, --sandbox, --sandbox-type flag. Model is LLM_MODEL. Workspace is the workdir you pass to the terminal tool. Sandbox / runtime is the RUNTIME and SANDBOX_VOLUMES env vars.

JSON Event Schema

With --json --headless, OpenHands emits JSONL — one JSON object per line, plus a handful of non-JSON status lines (Initializing agent..., Agent is working, Agent finished, the final summary box, Goodbye!, Conversation ID:, Hint:). Filter for lines starting with {.

Top-level kind field discriminates events:

• MessageEvent — user / agent text turn. source is user or agent.
• ActionEvent — agent picked a tool. Read tool_name (file_editor, terminal, finish) and action.kind (FileEditorAction, TerminalAction, FinishAction).
• ObservationEvent — tool result. observation.is_error is the success flag. source is environment.
• FinishAction inside an ActionEvent carries the agent's final message in action.message.

The cli prints all stderr from LiteLLM/Authlib first — see Pitfalls. Parse only stdout, line by line, ignoring lines that don't start with {.