openhands
Delegate coding to OpenHands CLI (model-agnostic, LiteLLM).
- License 许可
- MIT
- 最近更新
- 2026-11-04
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- openhands
- author
- Tim Koepsel (xzessmedia), Hermes Agent
- license
- MIT
- version
- 0.1.0
- metadata
- { "hermes": { "tags": [ "Coding-Agent", "OpenHands", "Model-Agnostic", "LiteLLM" ], "related_skills": [ "claude-code", "codex", "opencode", "hermes-agent" ] } }
- platforms
- [ "linux", "macos" ]
- description
- Delegate coding to OpenHands CLI (model-agnostic, LiteLLM).
03 SKILL.md 正文
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-codeandcodexare 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
-
Install upstream (requires Python 3.12+ and
uv):terminal(command="uv tool install openhands --python 3.12")Verify:
openhands --version(currentlyOpenHands CLI 1.16.0/SDK v1.21.0at time of writing). -
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 OpenAILLM_MODELuses 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. -
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.
| Flag | Effect |
|---|---|
--headless |
No UI, requires -t or -f. Auto-approves all actions (no --llm-approve in this mode). |
--json |
JSONL event stream (requires --headless). |
-t TEXT |
Task prompt. |
-f PATH |
Read task from file. |
--resume [ID] |
Resume conversation. No ID → list recent. |
--last |
Resume most recent (with --resume). |
--override-with-envs |
Apply LLM_API_KEY / LLM_BASE_URL / LLM_MODEL env vars. Without this, OpenHands uses ~/.openhands/settings.json and ignores the env. |
--exit-without-confirmation |
Don't show the "are you sure" exit dialog. |
--always-approve / --yolo |
Auto-approve every action (default in --headless). |
--llm-approve |
LLM-based security gate (interactive only — does NOT work in headless). |
--version / -v |
Print version and exit. |
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.sourceisuseroragent.ActionEvent— agent picked a tool. Readtool_name(file_editor,terminal,finish) andaction.kind(FileEditorAction,TerminalAction,FinishAction).ObservationEvent— tool result.observation.is_erroris the success flag.sourceisenvironment.FinishActioninside anActionEventcarries the agent's final message inaction.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 {.
Pitfalls
- LiteLLM warnings on every invocation. The CLI prints
bedrock-runtimeandsagemaker-runtimewarnings to stderr becausebotocoreisn't installed. Plus an Authlib deprecation. These are noise, not failures. Pipe stderr to/dev/nullor filter it out before showing the user. - Banner spam. Without
OPENHANDS_SUPPRESS_BANNER=1, every run starts with a multi-line+--+ASCII box advertising the SDK. Always export it. --override-with-envsis mandatory for automation. Without it, OpenHands ignoresLLM_API_KEY/LLM_BASE_URL/LLM_MODELand falls back to~/.openhands/settings.json. On a fresh install this file doesn't exist and the CLI hangs waiting for first-run setup.- Model slug is LiteLLM's, not the provider's.
openrouter/openai/gpt-4o-miniworks;openai/gpt-4o-miniwhile pointed at OpenRouter does not.anthropic/claude-sonnet-4-5(hyphen) is native Anthropic;openrouter/anthropic/claude-sonnet-4.5(dot) is via OpenRouter. Get it wrong → cryptic LiteLLM 400. pip install openhands-aiis the wrong package. That's the legacy V0 SDK. The new CLI isuv tool install openhands --python 3.12. There is no maintained conda package.- Resume ID format is fiddly. The CLI ends with
Conversation ID: f46573d9cfdb45e492ca189bde40019b(no dashes) and then aHint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b(with dashes). Use the dashed form. - Headless ignores
--llm-approve. If you pass it, you get an argparse error. Headless mode hardcodes always-approve. - No Windows support upstream. The OpenHands docs require WSL on Windows. This skill is gated
[linux, macos]accordingly. ~/.openhands/conversations/<id>/accumulates. Each run persists a trajectory. Clean it up if running batches.- Heavy install (~200 packages). Use
uv tool install(isolated venv) to avoid dependency conflicts with the active project.
Verification
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 'Print the string OPENHANDS_OK to stdout via the terminal tool.'",
workdir="/tmp",
timeout=120
)
If the JSONL stream ends with a FinishAction whose action.message mentions OPENHANDS_OK, the install is working.
Related
- OpenHands GitHub
- OpenHands CLI command reference
- Sibling skills:
claude-code(Anthropic-only),codex(OpenAI-only),opencode(multi-provider via OpenCode),hermes-agent(Hermes subagents viadelegate_task).
04 同仓库更多 Skills
nemoclaw-user-reference
Describes the NemoClaw integration layer and blueprint architecture and how they orchestrate compatible agent sandboxes. Use when looking up architecture, agent integration, plugin structure, or blueprint design. Trigger keywords - nemoclaw architecture, nemoclaw agent architecture, nemoclaw plugin blueprint structure, nemoclaw vs openshell, which cli, nemoclaw cli, openshell cli, sandbox commands, nemoclaw cli commands, nemoclaw command reference, nemoclaw network policy, sandbox egress control operator approval, nemoclaw troubleshooting, nemoclaw debug sandbox issues.
nemoclaw-user-overview
Explains how OpenClaw, OpenShell, and NemoClaw form the ecosystem, NemoClaw's position in the stack, what NemoClaw adds beyond the community sandbox, and when to prefer NemoClaw versus integrating OpenShell and OpenClaw directly. Use when users ask about the relationship between OpenClaw, OpenShell, and NemoClaw, or when to use NemoClaw versus OpenShell. Trigger keywords - nemoclaw ecosystem, openclaw openshell, nemoclaw vs openshell, sandboxed openclaw, how nemoclaw works, nemoclaw sandbox lifecycle blueprint, nemoclaw overview, openclaw always-on assistants, nvidia openshell, nvidia nemotron, nemoclaw release notes, nemoclaw changelog.
nemoclaw-user-monitor-sandbox
Inspects sandbox health, traces agent behavior, and diagnoses problems. Use when monitoring a running sandbox, debugging agent issues, or checking sandbox logs. Trigger keywords - monitor nemoclaw sandbox, debug nemoclaw agent issues.
nemoclaw-user-manage-sandboxes
Explains operational tasks after the quickstart: listing sandboxes, status and health checks, logs, diagnostics, port forwards, multiple sandboxes, credential reset, rebuilds, network presets, upgrades, and uninstall. Trigger keywords - manage nemoclaw sandboxes, nemoclaw status, nemoclaw list, nemoclaw dashboard port, nemoclaw rebuild, nemoclaw upgrade sandboxes, nemoclaw uninstall, sandbox mutability, sandbox runtime configuration, sandbox rebuild, nemoclaw backup, nemoclaw restore, workspace backup, openshell sandbox download upload, nemoclaw messaging channels, nemoclaw telegram, nemoclaw discord, nemoclaw slack, nemoclaw wechat, nemoclaw whatsapp, openshell channel messaging, nemoclaw workspace files, soul.md, user.md, identity.md, agents.md, sandbox persistence.
nemoclaw-user-manage-policy
Adds, removes, or modifies allowed endpoints in the sandbox policy. Use when customizing network policy, changing egress rules, or configuring sandbox endpoint access. Trigger keywords - customize nemoclaw network policy, sandbox egress policy configuration, nemoclaw integration policy examples, post-install policy setup, openshell approval workflow, policy preset, nemoclaw approve network requests, sandbox egress approval tui.
nemoclaw-user-get-started
Installs NemoClaw, launches a sandbox, and runs the first agent prompt. Use when onboarding, installing, or launching a NemoClaw sandbox for the first time. Trigger keywords - nemoclaw quickstart, install nemoclaw openclaw sandbox, nemohermes quickstart, hermes agent nemoclaw, run hermes openshell sandbox, nemoclaw prerequisites, nemoclaw supported platforms, nemoclaw hardware software, nemoclaw windows wsl2 setup, nemoclaw install windows docker desktop.