Openhands
将编码任务委派给 OpenHands CLI(模型无关,基于 LiteLLM)。
Skill 元数据
| 来源 | 可选 — 使用 kopi skills install official/autonomous-ai-agents/openhands 安装 |
| 路径 | optional-skills/autonomous-ai-agents/openhands |
| 版本 | 0.1.0 |
| 作者 | Tim Koepsel (xzessmedia), KOPI AI AGENT |
| 许可证 | MIT |
| 平台 | linux, macos |
| 标签 | Coding-Agent, OpenHands, Model-Agnostic, LiteLLM |
| 相关 skill | claude-code, codex, opencode, kopi-ai-agent |
参考:完整的 SKILL.md
以下是当此 skill 被触发时 Kopi Agent 加载的完整 skill 定义。这就是 skill 激活时 agent 看到的指令内容。
OpenHands CLI
通过 terminal 工具将编码任务委派给 OpenHands CLI。OpenHands 是模型无关的:支持任何 LiteLLM 支持的 provider(服务提供商)(OpenAI、Anthropic、OpenRouter、DeepSeek、Ollama、vLLM 等)。
此 skill 是用于批量 / 一次性委派的无头模式(headless)封装器。Kopi Agent 不会使用其交互式文本 UI。
何时使用
- 用户希望将编码任务专门委派给 OpenHands。
- 用户需要一个可以在非 Anthropic / 非 OpenAI provider(DeepSeek、Qwen、Ollama、vLLM、Nous 等)上运行的编码 agent — 同级 skill
claude-code和codex绑定了单一厂商。 - 在工作区内进行多步骤文件编辑 + shell 命令。
对于 Claude 原生场景,优先使用 claude-code。对于 OpenAI 原生场景,优先使用 codex。对于 Kopi Agent 原生子 agent,请使用 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 # or any LiteLLM slug
export LLM_API_KEY=$OPENROUTER_API_KEY
export LLM_BASE_URL=https://openrouter.ai/api/v1 # omit for native OpenAILLM_MODEL使用 LiteLLM 的完整 slug。当 provider 为 OpenRouter 时,该 slug 会带有双重前缀: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="<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)验证。此表中未列出的都不是参数 — 请通过环境变量或设置文件传递。
| 参数 | 效果 |
|---|---|
--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 事件 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。FinishAction位于ActionEvent内,其action.message中包含 agent 的最终消息。
CLI 会先将 LiteLLM/Authlib 的所有 stderr 输出打印出来 — 参见"常见陷阱"。请逐行解析 stdout,忽略不以 { 开头的行。
常见问题(Pitfalls)
- 每次调用都会出现 LiteLLM 警告。 由于未安装
botocore,CLI 会向 stderr 打印bedrock-runtime和sagemaker-runtime警告。此外还有一条 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 的格式,而非 provider 的格式。
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(带连字符)。请使用带连字符的形式。 - Headless 模式会忽略
--llm-approve。 如果传入它,会得到 argparse 错误。Headless 模式硬编码为始终批准。 - 上游不支持 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="/tmp",
timeout=120
)
如果 JSONL 流以一个 FinishAction 结尾,且其 action.message 中提到了 OPENHANDS_OK,说明安装工作正常。
相关内容
- OpenHands GitHub
- OpenHands CLI 命令参考
- 同级 skill:
claude-code(仅限 Anthropic)、codex(仅限 OpenAI)、opencode(通过 OpenCode 支持多 provider)、kopi-ai-agent(通过delegate_task使用 Kopi Agent 子 agent)。