Openhands

将编程任务委托给 OpenHands CLI (模型无关, LiteLLM)。

技能元数据


来源	可选 — 通过 `hermes skills install official/autonomous-ai-agents/openhands` 安装
路径	`optional-skills/autonomous-ai-agents/openhands`
版本	`0.1.0`
作者	Tim Koepsel (xzessmedia), Hermes Agent
许可证	MIT
平台	linux, macos
标签	`Coding-Agent`, `OpenHands`, `Model-Agnostic`, `LiteLLM`
相关技能	`claude-code`, `codex`, `opencode`, `hermes-agent`

参考：完整的 SKILL.md

信息

以下是当此技能被触发时，Hermes 加载的完整技能定义。这是技能激活时智能体看到的指令。

OpenHands CLI

通过 terminal 工具将编程任务委托给 OpenHands CLI。OpenHands 是模型无关的：支持任何 LiteLLM 支持的提供商 (OpenAI, Anthropic, OpenRouter, DeepSeek, Ollama, vLLM 等)。

此技能是用于批量/一次性委托的无头模式包装器。Hermes 不使用交互式文本 UI。

何时使用

用户希望将编程任务专门委托给 OpenHands。
用户希望使用一个可以在非 Anthropic / 非 OpenAI 提供商 (DeepSeek, Qwen, Ollama, vLLM, Nous 等) 上运行的编程智能体 — 兄弟技能 claude-code 和 codex 则绑定到单一供应商。
在工作空间内进行多步骤的文件编辑 + shell 命令操作。

对于原生 Claude 环境，首选 claude-code。对于原生 OpenAI 环境，首选 codex。对于 Hermes 原生的子智能体，使用 delegate_task。

前提条件

安装上游工具 (需要 Python 3.12+ 和 uv)：
```
terminal(command="uv tool install openhands --python 3.12")
```
验证：openhands --version (撰写时为 OpenHands CLI 1.16.0 / SDK v1.21.0)。
选择一个模型并为 --override-with-envs 设置环境变量：
```
export LLM_MODEL=openrouter/openai/gpt-4o-mini       # 或任何 LiteLLM 标识符
export LLM_API_KEY=$OPENROUTER_API_KEY
export LLM_BASE_URL=https://openrouter.ai/api/v1     # 对于原生 OpenAI 可省略
```
LLM_MODEL 使用 LiteLLM 的完整标识符。当提供商是 OpenRouter 时，标识符带有双重前缀：openrouter/<vendor>/<model> (例如 openrouter/anthropic/claude-sonnet-4.5)。对于原生 Anthropic：anthropic/claude-sonnet-4-5。对于原生 OpenAI：openai/gpt-4o-mini。
抑制启动横幅，以避免 JSON 输出前出现 ASCII 艺术字：
```
export OPENHANDS_SUPPRESS_BANNER=1
```

如何运行

始终通过 terminal 工具调用。始终传递 --headless --json --override-with-envs --exit-without-confirmation 以实现自动化。

一次性任务

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
)

长时间任务的后台运行

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

恢复之前的对话

OpenHands 会在每次运行结束时打印 Conversation ID: <32位十六进制> 和一行 Hint: openhands --resume <带横线的UUID>。使用带横线的形式来恢复：

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

完整的标志列表

根据 openhands --help (CLI 1.16.0) 验证。任何不在此表中的都不是标志 — 请通过环境变量或设置文件传递。

标志	作用
`--headless`	无 UI，需要 `-t` 或 `-f`。自动批准所有操作 (此模式下无 `--llm-approve`)。
`--json`	JSONL 事件流 (需要 `--headless`)。
`-t TEXT`	任务提示。
`-f PATH`	从文件读取任务。
`--resume [ID]`	恢复对话。不带 ID 则列出近期对话。
`--last`	恢复最近一次对话 (与 `--resume` 配合使用)。
`--override-with-envs`	应用 `LLM_API_KEY` / `LLM_BASE_URL` / `LLM_MODEL` 环境变量。如果不使用此标志，OpenHands 会使用 `~/.openhands/settings.json` 并忽略环境变量。
`--exit-without-confirmation`	不显示"您确定吗？"的退出对话框。
`--always-approve` / `--yolo`	自动批准每个操作 (`--headless` 模式下的默认行为)。
`--llm-approve`	基于 LLM 的安全门 (仅限交互模式 — 在无头模式下不起作用)。
`--version` / `-v`	打印版本并退出。

没有 --model, --max-iterations, --workspace, --sandbox, --sandbox-type 标志。 模型通过 LLM_MODEL 设置。工作空间是你传递给 terminal 工具的 workdir。沙箱/运行时通过 RUNTIME 和 SANDBOX_VOLUMES 环境变量控制。

JSON 事件模式

使用 --json --headless 时，OpenHands 输出 JSONL — 每行一个 JSON 对象，外加少量非 JSON 状态行 (Initializing agent..., Agent is working, Agent finished, 最终的汇总框, Goodbye!, Conversation ID:, Hint:)。过滤以 { 开头的行。

顶层 kind 字段用于区分事件：

MessageEvent — 用户/智能体文本轮次。source 是 user 或 agent。
ActionEvent — 智能体选择了一个工具。读取 tool_name (file_editor, terminal, finish) 和 action.kind (FileEditorAction, TerminalAction, FinishAction)。
ObservationEvent — 工具结果。observation.is_error 是成功标志。source 是 environment。
ActionEvent 内部的 FinishAction 在 action.message 中携带智能体的最终消息。

CLI 会先打印所有来自 LiteLLM/Authlib 的 stderr 内容 — 参见常见问题。仅解析 stdout，逐行进行，忽略不以 { 开头的行。

常见问题

每次调用时的 LiteLLM 警告。 CLI 会将 bedrock-runtime 和 sagemaker-runtime 的警告打印到 stderr，因为 botocore 未安装。外加一个 Authlib 废弃警告。这些是噪音，不是错误。将 stderr 重定向到 /dev/null 或在显示给用户之前将其过滤掉。
横幅垃圾信息。 如果没有 OPENHANDS_SUPPRESS_BANNER=1，每次运行都会以一个宣传 SDK 的多行 +--+ ASCII 框开始。请始终导出此变量。
--override-with-envs 对于自动化是强制性的。 如果不使用它，OpenHands 会忽略 LLM_API_KEY / LLM_BASE_URL / LLM_MODEL 并回退到 ~/.openhands/settings.json。在新安装的系统上，此文件不存在，CLI 会挂起等待首次运行设置。
模型标识符是 LiteLLM 的，不是提供商的。 openrouter/openai/gpt-4o-mini 可以工作；当指向 OpenRouter 时，openai/gpt-4o-mini 不行。anthropic/claude-sonnet-4-5 (连字符) 是原生 Anthropic；openrouter/anthropic/claude-sonnet-4.5 (点号) 是通过 OpenRouter。搞错会导致晦涩的 LiteLLM 400 错误。
pip install openhands-ai 是错误的包。 那是旧版 V0 SDK。新的 CLI 是 uv tool install openhands --python 3.12。没有维护的 conda 包。
恢复 ID 格式很繁琐。 CLI 以 Conversation ID: f46573d9cfdb45e492ca189bde40019b (无横线) 结束，然后是一个 Hint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b (带横线)。请使用带横线的形式。
无头模式忽略 --llm-approve。 如果传递它，你会得到一个 argparse 错误。无头模式硬编码为始终批准。
上游不支持 Windows。 OpenHands 文档要求在 Windows 上使用 WSL。此技能相应地限定为 [linux, macos]。
~/.openhands/conversations/<id>/ 会累积。 每次运行都会持久化一个轨迹。如果运行批量任务，请清理它。
安装包很重 (~200 个包)。 使用 uv tool install (隔离的 venv) 以避免与当前项目的依赖冲突。

验证

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
)

如果 JSONL 流以一个 action.message 提及 OPENHANDS_OK 的 FinishAction 结束，则说明安装正常工作。

技能元数据​

参考：完整的 SKILL.md​

OpenHands CLI

何时使用​

前提条件​

如何运行​

一次性任务​

长时间任务的后台运行​

恢复之前的对话​

完整的标志列表​

JSON 事件模式​

常见问题​

验证​

相关链接​