{/* This page is auto-generated from the skill's SKILL.md by website/scripts/generate-skill-docs.py. Edit the source SKILL.md, not this page. */}

Openhands

把编码委派给 OpenHands CLI（模型无关、LiteLLM）。

Skill 元数据

参考：完整 SKILL.md

OpenHands CLI

经 terminal 工具把编码任务委派给 OpenHands CLI。OpenHands 模型无关：任何 LiteLLM 支持的提供商（OpenAI、Anthropic、OpenRouter、DeepSeek、Ollama、vLLM 等）。

本 skill 是批量/一次性委派的无头模式包装器。交互式文本 UI 不从 Hermes 使用。

何时使用

• 用户要把编码任务专门委派给 OpenHands。
• 用户要能跑在非 Anthropic/非 OpenAI 提供商上的编码 agent（DeepSeek、Qwen、Ollama、vLLM、Nous 等）——兄弟 skill claude-code 和 codex 绑单一厂商。
• 工作区内多步文件编辑 + shell 命令。

Claude 原生优先 claude-code。OpenAI 原生优先 codex。Hermes 原生子代理用 delegate_task。

前置条件

1. 安装上游（需 Python 3.12+ 和 uv）：

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

   验证：openhands --version（撰写时当前 OpenHands CLI 1.16.0 / SDK v1.21.0）。

2. 选模型并为 --override-with-envs 设环境变量：

   export LLM_MODEL=openrouter/openai/gpt-4o-mini       # 或任何 LiteLLM slug
   export LLM_API_KEY=$OPENROUTER_API_KEY
   export LLM_BASE_URL=https://openrouter.ai/api/v1     # 原生 OpenAI 省略
   

   LLM_MODEL 用 LiteLLM 完整 slug。提供商是 OpenRouter 时 slug 双前缀：openrouter/<vendor>/<model>（如 openrouter/anthropic/claude-sonnet-4.5）。原生 Anthropic：anthropic/claude-sonnet-4-5。原生 OpenAI：openai/gpt-4o-mini。

3. 抑制启动横幅，使 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="<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>")

恢复先前对话

OpenHands 每次运行结束打印 Conversation ID: <32-hex> 和 Hint: openhands --resume <dashed-uuid> 行。用虚线形式恢复：

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"
)

真实标志清单

对照 openhands --help（CLI 1.16.0）验证。此表外任何东西都不是标志——经环境变量或设置文件传。

没有 --model、--max-iterations、--workspace、--sandbox、--sandbox-type 标志。 模型是 LLM_MODEL。工作区是你传给 terminal 工具的 workdir。沙箱/运行时是 RUNTIME 和 SANDBOX_VOLUMES 环境变量。

JSON 事件 schema

带 --json --headless，OpenHands 发 JSONL——每行一个 JSON 对象，加少数非 JSON 状态行（Initializing agent...、Agent is working、Agent finished、最终摘要框、Goodbye!、Conversation ID:、Hint:）。过滤以 { 开头的行。

顶层 kind 字段区分事件：

• MessageEvent——用户/agent 文本轮。source 是 user 或 agent。
• ActionEvent——agent 选了工具。读 tool_name（file_editor、terminal、finish）和 action.kind（FileEditorAction、TerminalAction、FinishAction）。
• ObservationEvent——工具结果。observation.is_error 是成功标志。source 是 environment。
• ActionEvent 内的 FinishAction 在 action.message 带 agent 最终消息。

cli 先打印 LiteLLM/Authlib 的所有 stderr——见常见陷阱。只逐行解析 stdout，忽略不以 { 开头的行。

常见陷阱

• 每次调用 LiteLLM 警告。 CLI 因未装 botocore 把 bedrock-runtime 和 sagemaker-runtime 警告打到 stderr。加 Authlib 弃用。这些是噪声，非失败。把 stderr 管道到 /dev/null 或在给用户前过滤。
• 横幅刷屏。 无 OPENHANDS_SUPPRESS_BANNER=1，每次运行以多行 +--+ ASCII 框广告 SDK 开头。总导出它。
• --override-with-envs 自动化必需。 无它，OpenHands 忽略 LLM_API_KEY / LLM_BASE_URL / LLM_MODEL，回退 ~/.openhands/settings.json。全新安装此文件不存在，CLI 挂起等首次运行设置。
• 模型 slug 是 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 包。
• Resume ID 格式麻烦。 CLI 以 Conversation ID: f46573d9cfdb45e492ca189bde40019b（无连字符）结束，然后 Hint: openhands --resume f46573d9-cfdb-45e4-92ca-189bde40019b（带连字符）。用虚线形式。
• 无头忽略 --llm-approve。 传了会得 argparse 错误。无头模式硬编码 always-approve。
• 上游无 Windows 支持。 OpenHands 文档要求 Windows 上 WSL。本 skill 相应门控 [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="~/.hermes/cache/scratch",
  timeout=120
)

若 JSONL 流以 FinishAction 结束且其 action.message 提到 OPENHANDS_OK，安装工作。

相关

• OpenHands GitHub
• OpenHands CLI 命令参考
• 兄弟 skill：claude-code（仅 Anthropic）、codex（仅 OpenAI）、opencode（经 OpenCode 多提供商）、hermes-agent（经 delegate_task 的 Hermes 子代理）。