AGENT SKILL

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

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

Pitfalls

  • LiteLLM warnings on every invocation. The CLI prints bedrock-runtime and sagemaker-runtime warnings to stderr because botocore isn't installed. Plus an Authlib deprecation. These are noise, not failures. Pipe stderr to /dev/null or 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-envs is mandatory for automation. Without it, OpenHands ignores LLM_API_KEY / LLM_BASE_URL / LLM_MODEL and 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-mini works; openai/gpt-4o-mini while 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-ai is the wrong package. That's the legacy V0 SDK. The new CLI is uv 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 a Hint: 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

04 同仓库更多 Skills

GrupoANDevelopment-m
GrupoANDevelopment-m/alberto-ai

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.

★ 0
GrupoANDevelopment-m
GrupoANDevelopment-m/alberto-ai

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.

★ 0
GrupoANDevelopment-m
GrupoANDevelopment-m/alberto-ai

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.

★ 0
GrupoANDevelopment-m
GrupoANDevelopment-m/alberto-ai

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.

★ 0
GrupoANDevelopment-m
GrupoANDevelopment-m/alberto-ai

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.

★ 0
GrupoANDevelopment-m
GrupoANDevelopment-m/alberto-ai

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.

★ 0