OpenHands

OpenHands 是什么

OpenHands（前身为 OpenDevin）是一个聚焦于「AI 驱动开发」的开源社区与软件框架。它的核心目标，是让一个 AI 智能体能够像人类工程师一样实际操作开发环境——执行 bash 命令、读写与编辑文件、浏览网页、调用工具，从而自主完成编程任务，而不只是停留在「聊天给建议」的层面。

与单纯的代码补全工具不同，OpenHands 提供的是一整套从研究原型到生产部署的连续光谱：你既可以在终端里像使用 Claude Code、Codex 那样直接对话编程，也可以用它的 Python SDK 在代码里定义智能体、扩展到云端并行运行成千上万个 agent。

所有核心代码都在 MIT 许可证下开放，仅 enterprise/ 目录采用商业许可。核心 openhands 与 agent-server 镜像同样完全 MIT 授权。

五种使用形态

OpenHands 不是单一产品，而是同一引擎的五层封装。理解这张图，就理解了整个项目的版图：

核心概念

在动手之前，先建立四个基础概念的心智模型。它们贯穿 CLI、SDK 与整个架构：

// 基础工作流

无论用哪种形态，一次完整的智能体运行都遵循这条主线：

CLI 安装与第一次对话

CLI 是门槛最低的入口。它需要 Python 3.12+，官方推荐用 uv 包管理器安装。

// 方式一：uv（推荐）

# 安装
uv tool install openhands --python 3.12

# 运行
openhands

# 升级
uv tool upgrade openhands --python 3.12

// 方式二：可执行二进制

curl -fsSL https://install.openhands.dev/install.sh | sh
openhands

macOS 首次运行若提示「无法验证开发者」，到「系统设置 → 隐私与安全性 → 安全性」点击「仍要打开」即可。

// 方式三：Docker

docker run -it --pull=always \
    -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
    -e AGENT_SERVER_IMAGE_TAG=1.19.1-python \
    -e SANDBOX_USER_ID=$(id -u) \
    -e SANDBOX_VOLUMES=$SANDBOX_VOLUMES \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v ~/.openhands:/root/.openhands \
    --add-host host.docker.internal:host-gateway \
    python:3.12-slim \
    bash -c "pip install uv && uv tool install openhands --python 3.12 && openhands"

其中 SANDBOX_USER_ID=$(id -u) 让沙箱用户与宿主机权限对齐，避免智能体在挂载目录里创建 root 属主的文件。

// 第一次运行

首次运行时，CLI 会引导你配置 LLM。配置会保存在 ~/.openhands/settings.json，会话历史保存在 ~/.openhands/conversations。

# 选项 A：登录 OpenHands Cloud（推荐，自动拉取设置）
openhands login

# 选项 B：手动配置 —— 首次运行时按提示填写 LLM 提供商与 API Key
openhands

进入交互界面后，输入一个任务即可，例如：

Create a Python script that prints "Hello, World!"

智能体会理解需求、探索项目、创建文件并展示结果。

// 交互快捷键

// 带任务启动 & 恢复会话

# 直接带任务启动
openhands -t "Fix the bug in auth.py"
openhands -f task.txt          # 从文件读取任务

# 恢复历史会话
openhands --resume             # 列出最近会话并选择
openhands --resume --last      # 恢复最近一次
openhands --resume abc123def   # 按 ID 恢复

CLI 的五种运行模式

同一个 openhands 命令通过不同子命令，可以化身为五种截然不同的工具：

IDE 集成通过 ACP（Agent Client Protocol）实现，意味着你可以在自己喜欢的编辑器里直接调用 OpenHands 智能体，而 Headless 模式则让它能无缝嵌入流水线脚本。

用 SDK 写第一个智能体

如果你想在代码里完全掌控智能体，SDK 才是核心。它是一个模块化、类型安全的框架，让 agent 能够操作代码、文件与系统命令。

// 前置条件与安装

# 1. 安装 uv 包管理器（0.8.13+）
curl -LsSf https://astral.sh/uv/install.sh | sh

# 2. 安装 SDK + 内置工具（务必同一条命令，保证版本对齐）
pip install -U openhands-sdk openhands-tools

# 可选：沙箱工作区（Docker / 远程服务器）
pip install -U openhands-sdk openhands-tools openhands-workspace openhands-agent-server

// 配置 API Key

SDK 通过 LiteLLM 支持数十家提供商。三种取得 Key 的途径：

• 直连提供商——自带 Anthropic / OpenAI 等 Key，模型名用提供商前缀，如 anthropic/claude-sonnet-4-5-20250929
• OpenHands Cloud（推荐）——在云端充值后取得 OpenHands LLM Key，模型名用 openhands/ 前缀，无加价
• ChatGPT 订阅——用 LLM.subscription_login() 以 ChatGPT Plus/Pro 账号访问 Codex 模型，不消耗 API 额度

export LLM_API_KEY="your-api-key-here"
export LLM_MODEL="openhands/claude-sonnet-4-5-20250929"   # 若用云端

// Hello World：完整示例

import os
from openhands.sdk import LLM, Agent, Conversation, Tool
from openhands.tools.file_editor import FileEditorTool
from openhands.tools.task_tracker import TaskTrackerTool
from openhands.tools.terminal import TerminalTool

# 1) 配置 LLM
llm = LLM(
    model=os.getenv("LLM_MODEL", "anthropic/claude-sonnet-4-5-20250929"),
    api_key=os.getenv("LLM_API_KEY"),
    base_url=os.getenv("LLM_BASE_URL", None),
)

# 2) 创建 Agent，并挂载三个工具
agent = Agent(
    llm=llm,
    tools=[
        Tool(name=TerminalTool.name),
        Tool(name=FileEditorTool.name),
        Tool(name=TaskTrackerTool.name),
    ],
)

# 3) 建立会话，工作区设为当前目录
cwd = os.getcwd()
conversation = Conversation(agent=agent, workspace=cwd)

# 4) 发送任务并运行
conversation.send_message("Write 3 facts about the current project into FACTS.txt.")
conversation.run()
print("All done!")

# 运行
uv run python examples/01_standalone_sdk/01_hello_world.py

你会看到智能体理解请求、探索项目、并创建出包含项目事实的文件。官方仓库还附带 24+ 个示例（自定义工具、激活技能、异步会话等），位于 examples/01_standalone_sdk/。

SDK 架构剖析

设计哲学：无状态（statelessness）、可组合（composability）、研究与部署之间边界清晰。

SDK 是 OpenHands 中「智能体的唯一真理来源」。GUI、CLI、Cloud 都只是消费 SDK API 的界面——它们从持久化的设置中「水合」出 SDK 组件，再通过 SDK 接口编排执行。这保证了所有形态下配置与默认值的一致性。

// 四包架构

agent-sdk 被拆分为四个独立的 Python 包：

// 核心组件

所有组件均为无状态、不可变，基于类型安全的 Pydantic 模型。

推理-行动循环

Agent 的灵魂是 reasoning-action loop（推理-行动循环）。它采用单步执行模型：每次 step() 调用只处理一个推理周期，每一步都是原子的、可暂停可恢复的。

// 一次 step() 的内部流程

这个循环的三个关键特征：

• 无状态——Agent 在步骤之间不持有任何可变状态，全部从事件历史读取
• 事件驱动——读取事件历史，写入新事件，状态即历史
• 可中断——每一步原子化，可随时暂停/恢复

// 工具的行动-观察模式

所有工具都遵循严格的 Action → Observation 模式。LLM 生成 tool_call，被转换为 ActionEvent；根据是否处于确认模式，要么立即执行、要么暂存为 pending；执行成功产生带结果的 ObservationEvent，失败则产生带错误的 ObservationEvent。

// 安全分析器的风险分级

执行前，Security Analyzer 会评估每个行动的风险等级：

• 低风险 → 立即执行
• 中风险 → 记录警告，带监控执行
• 高风险 → 阻断执行，请求用户确认

// Agent Context：技能与提示

Agent 会应用 AgentContext 来塑造 LLM 行为，其中包含两类技能：

沙箱：代码在哪里执行

沙箱（Sandbox）是 OpenHands 运行命令、编辑文件、启动服务的环境。在 V1 中，这一概念统一称为 sandbox（旧版 V0 称 runtime）。

在某些部署中，沙箱选择仍由历史遗留的 RUNTIME 环境变量控制：

RUNTIME=docker    # 默认
RUNTIME=process   # 旧称 RUNTIME=local
RUNTIME=remote

三种部署模式

SDK 最优雅的设计之一：同一份智能体代码，只需替换 workspace 类型，就能在三种环境间切换——LocalWorkspace → DockerWorkspace → RemoteAPIWorkspace。

模式一 · 本地开发

只装 openhands-sdk + openhands-tools。LocalWorkspace 已内置无需额外安装，一切在单进程内运行。适合原型与简单用例，无需 Docker，启动飞快。

模式二 · 生产 / 沙箱化

安装全部 4 个包。RemoteWorkspace 会在容器中自动拉起 agent-server，提供沙箱化执行、多用户部署与分布式（如 Kubernetes）支持。

工具运行在 workspace 所配置的环境里（本地/容器/远程），它们与 agent 并肩运行，而非「穿过」workspace API——这是理解隔离边界的要点。

技能 · 自定义工具 · MCP

OpenHands 的可扩展性主要通过三条路径展开：

Skills 技能

技能是特化的提示词，为智能体注入领域知识、专家指导与自动化任务处理能力。分层体系包括：

• Repo 技能——仓库级通用指南，让 OpenHands 更高效地与代码库协作（始终激活）
• Keyword-Triggered 关键词触发技能——当提示中出现特定关键词时激活，适合针对某工具/语言/框架定制行为
• Organization / User 技能——应用于组织或用户名下所有仓库
• Global 全局技能——对所有用户生效，官方注册表维护在 github.com/OpenHands/extensions

也可用 File-Based Agents——以带 YAML frontmatter 的 Markdown 文件定义子智能体，无需写 Python。

Custom Tools 自定义工具

工具定义了智能体「能做什么」。SDK 内置常用工具，也支持为特化需求创建自定义工具。所有工具遵循统一的 Action / Observation / Executor 模式，内建校验、错误处理与安全机制。

MCP（Model Context Protocol）

MCP 让智能体能动态集成来自外部服务器的工具——agent 可自动发现并使用 MCP 提供的工具。在 CLI 里可用命令面板查看 MCP 状态并管理 MCP 服务器；在 SDK 里通过配置接入。这是把 OpenHands 接入 Asana、Gmail、Salesforce 等外部生态的标准方式。

Sub-Agent Delegation 子智能体委派

通过把工作委派给多个独立运行的子智能体来实现并行任务执行，再汇总结果返回父智能体。配合 Task Tool Set，可把复杂工作分解给同步运行的特化子智能体。这对多智能体编排尤为关键。

典型应用场景

OpenHands 官方梳理了一批适合智能体接管的工程任务类型：

此外还可通过 GitHub Action 把 OpenHands 嵌入 CI，或用 Automations 创建定时 / 事件触发（GitHub 事件或自定义 webhook）的自动化任务。

提示词最佳实践

智能体的产出质量，极大程度取决于你给出的指令质量。官方「好指令 vs 坏指令」的核心原则可以浓缩为：

• 给出明确的成功标准——告诉智能体「怎样算完成」，它就能自我验证
• 提供可执行的检查手段——测试命令、lint 规则，让它能闭环
• 用 .openhands 目录定制仓库行为——在仓库根放置约定、技能与上下文
• 善用 Hooks——拦截危险命令、在停止前强制质量检查、注入上下文
• 分解大任务——把宏大目标拆成一系列范围清晰的子任务，逐个交付

总结与资源

把这篇教程压缩成一句话：OpenHands 是一个以无状态、事件驱动的推理-行动循环为核心的开源智能体框架，SDK 是唯一真理来源，CLI / GUI / Cloud / Enterprise 是它的不同消费界面，沙箱决定代码在哪里安全执行。

// 学习路径建议

// 官方资源

• 文档主站 · docs.openhands.dev
• LLM 友好文档索引 · docs.openhands.dev/llms.txt
• Software Agent SDK 源码 · github.com/OpenHands/software-agent-sdk
• OpenHands 主仓库 · github.com/OpenHands/OpenHands
• 全局技能注册表 · github.com/OpenHands/extensions
• 云端免费试用 · app.all-hands.dev
• 社区 Slack · openhands.dev/joinslack