跳到主要内容

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
相关 skillclaude-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。

前提条件​

  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       # 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 使用 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。

  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)验证。此表中未列出的都不是参数 — 请通过环境变量或设置文件传递。

参数效果
--headless无 UI,需要 -t 或 -f。自动批准所有操作(此模式下没有 --llm-approve)。
--jsonJSONL 事件流(需要 --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)。