跳至主要内容

OpenHands:开源 AI 编码代理全解

概览开源 AI 编码代理 OpenHands,涵盖其架构、基于 Ollama 的本地安装、实操修复缺陷、安全与局限,并与 Claude Code、Cursor、GitHub Copilot 对比。
· 15分钟 阅读

使用 AI 探索

OpenHands 是一个面向 AI 驱动软件开发的开源平台,围绕一个代理而构建,该代理可以检查您的代码仓库、编辑文件、执行命令并运行测试。它代表着向“代理式”软件开发的转变——您给出一个完整任务,代理逐步推进,直到完成或需要您的输入为止。

本文将带您了解 OpenHands 的架构和主要功能,演示如何用本地模型完成安装,并与 Claude Code、Cursor 和 GitHub Copilot 进行对比。

什么是 AI 代理?报名我们的AI Agent Fundamentals 学习路径,探索 AI 代理如何改变您的工作方式。

什么是 OpenHands?

OpenHands 是一个用于构建与运行代码类 AI 代理的开源平台。

该名称涵盖两层含义。其一是项目本身——包含 SDK、服务器、浏览器 UI 和托管服务的一组代码库。其二是在此之上运行的编码代理。

其工作方式如下:

  • 软件代理 SDK: 一组用于构建代码类代理的 Python 与 REST API,也是 OpenHands CLI 与 OpenHands Cloud 的引擎
  • 代理服务器: 通过 REST 与 WebSocket API 暴露代理执行、对话、工具与工作区
  • Agent Canvas: 一个浏览器界面,集成对话、文件、终端输出、模型配置、后端与自动化
  • OpenHands Cloud: 面向不想自建后端与沙箱基础设施团队的托管商业服务

大多数人提到“OpenHands”时,指的是代理。本文将与这一部分打交道。

通常,您给代理一个软件任务,将其指向包含您代码的工作区,它会用手头的工具推进任务。默认工具集包括终端、文件编辑器与任务跟踪器。

工作区不必在您的笔记本上。代理既可以使用本机作为工作区,也可以在临时工作区中运行,例如基于 Docker 或 Kubernetes。

OpenHands 也不绑定某个模型提供商。您可以配合 Claude、GPT 或其他任意 LLM,包括本地模型。Agent Canvas 甚至可以让第三方代理(如 Claude Code 和 Codex)替代默认的 OpenHands 代理运行。

简而言之,OpenHands 是一个可以按您意愿运行的开放代理平台。

OpenHands 如何工作

OpenHands 以循环方式运行。

聊天助理接收您的提示并返回文本。OpenHands 代理接收任务、执行操作、查看结果,然后决定下一步做什么。

The OpenHands agent loop

OpenHands 代理循环

大致流程如下:

  • 接收任务: 您用自然语言描述目标,例如“修复月度报表,避免将不同年份的同名月份合并”
  • 检查仓库: 代理列出目录、打开文件并搜索与任务相关的代码
  • 制定计划: 将任务拆分为步骤,并记录到任务跟踪器中
  • 编辑或创建文件: 通过文件编辑器修改代码
  • 运行命令与测试: 在终端中运行测试套件或应用
  • 检查结果: 读取输出,包括错误与失败的断言
  • 迭代: 若仍有问题,则回退、调整计划并再次尝试

循环会在任务完成时或代理需要您才能提供的内容(如缺失的凭据或需求决策)时停止。

第 6 步让 OpenHands 与竞争对手不同。代码补全工具从不会看到其生成的代码运行后的情况。OpenHands 会,因此它能对失败的测试做出反应并修复根因。

OpenHands 的关键特性

自动补全只是建议文本,而 OpenHands 会对您的项目采取行动。方式如下。

代码编辑

OpenHands 直接编辑文件,且不限于一次只改一个文件。

例如某个函数需要更名。代理会更新定义、找到每个调用点,并更新引用它的测试——全部作为一个任务的一部分完成。

终端与工具使用

代理拥有自己的终端。它可以安装依赖、运行脚本、执行测试并读取任意命令的输出。

您还可以连接 MCP(Model Context Protocol)服务器,为代理提供其原本不支持的工具,例如问题跟踪器或数据库客户端。

仓库理解

大多数代码生成器只能看到您粘贴进提示中的内容。

OpenHands 会打开并探索整个仓库。它能阅读 README、沿着 import 关系查找,并查看已有测试以理解项目结构。这意味着它的修改更可能与现有代码契合。

长任务会带来另一类问题——对话历史会超出模型上下文长度。OpenHands 使用“上下文压缩器”处理此问题,将较早的对话部分摘要化,以便代理能继续工作。

模型选择

模型调用通过 LiteLLM 进行,因此您可以使用其支持的任意提供商与模型。OpenHands 文档推荐 Claude、GPT 与 Gemini 系列模型,以及在 OpenHands Index 上表现良好的开源权重模型。

若您的代码不能离开本机,您可以运行本地模型。OpenHands 可连接 LM Studio、Ollama、vLLM 与 SGLang 等本地服务器。

需要注意的是,不同模型会极大影响结果。即便拥有较大的上下文窗口,一些本地模型在稳定使用工具方面仍有困难。

自主执行任务

一旦您移交任务,代理会独立完成循环。您无需将错误粘贴回聊天或告诉它接下来打开哪个文件。

Agent Canvas 更进一步提供自动化。它可与 Slack、GitHub、Linear 等集成,并按计划或响应 webhook 事件运行。

但自主并不等于正确。合并前您仍需审查差异与测试结果。

如何使用 OpenHands

理解 OpenHands 的最佳方式,是给它一个 bug,看看它会做什么。

本节将本地在 Docker 中运行 OpenHands,通过 Ollama 连接到本地模型,并让它修复一个小型 Python 项目中的 bug。

设置 OpenHands

您可以通过几种方式运行 OpenHands:

  • CLI 启动器: 通过 uv tool install openhands --python 3.14 安装,然后使用 openhands serve 启动 GUI

  • Docker: 通过单条 docker run 命令直接运行应用容器

  • Agent Canvas: 新的浏览器客户端,可连接本地、自托管、Cloud 或 Enterprise 后端

  • OpenHands Cloud: 托管版本,如果您不想自行运行任何组件

我将使用 Docker 路线配合本地 GUI。OpenHands 文档目前将其列为已弃用的基于 Docker 的浏览器应用,并推荐用 Agent Canvas 替代,但它仍有文档支持,也是最快启动 GUI 的方式。

您需要在 macOS、Linux 或带 WSL 的 Windows 上安装 Docker Desktop。macOS 上,打开 Docker Desktop,前往 Settings > Advanced,启用默认 Docker 套接字。

然后启动应用:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

OpenHands 通过挂载 Docker 套接字来启动一个独立的沙箱容器,代理在该沙箱内执行命令,而不是在您的主机上。

当日志显示服务器已就绪后,在浏览器中打开 http://localhost:3000。

OpenHands welcome page

OpenHands 欢迎页

连接模型

在您提供模型之前,OpenHands 不会执行任何操作。

我使用的是 Devstral Small 2,这是 Mistral 面向代理式编码的 24B 模型。它足够轻,可以在单张 RTX 4090 或 32GB 内存的 Mac 上运行。需要 Ollama 0.13.3 或更高版本。

以更大的上下文窗口启动 Ollama 并拉取模型:

OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 ollama serve &
ollama pull devstral-small-2:24b

不要忽视上下文长度。Ollama 的默认值是 4096 个 token,甚至不足以容纳 OpenHands 的系统提示。文档建议至少 22000。

在 OpenHands 中打开 Settings,进入 LLM 选项卡,开启 Advanced。然后设置:

  1. Custom Model: openai/devstral-small-2:latest

  2. Base URL: http://host.docker.internal:11434/v1

  3. API Key: 任意占位值,如 local-llm

LLM settings for a local Ollama model

本地 Ollama 模型的 LLM 设置

openai/ 前缀告诉 OpenHands 通过 Ollama 的 OpenAI 兼容 API 通信。API key 实际不会使用,但字段不能为空。

打开一个仓库

OpenHands 默认看不到您的文件。您需要将项目挂载到沙箱中。

本示例需要一个名为 budget-tracker/project 的文件夹,内含两个文件。第一个文件按月汇总支出:

# budget.py
def monthly_totals(transactions):
    """Sum spending per month, keyed as 'YYYY-MM'.

    Each transaction is a (date, amount) tuple, for example ("2025-01-15", 42.0).
    """
    totals = {}
    for date, amount in transactions:
        month = date[5:7]
        totals[month] = totals.get(month, 0) + amount
    return totals

Docstring 承诺键为 YYYY-MM,但 date[5:7] 只保留了月份。2025 年 1 月与 2026 年 1 月会落入同一桶。

第二个文件包含两个能捕获该 bug 的测试:

# test_budget.py
from budget import monthly_totals


def test_same_month_in_different_years():
    transactions = [
        ("2025-01-10", 50.0),
        ("2025-01-20", 100.0),
        ("2026-01-12", 60.0),
    ]
    assert monthly_totals(transactions) == {"2025-01": 150.0, "2026-01": 60.0}


def test_single_month():
    transactions = [("2026-03-01", 20.0), ("2026-03-15", 5.5)]
    assert monthly_totals(transactions) == {"2026-03": 25.5}

将该文件夹初始化为 Git 仓库,方便稍后查看代理做了哪些更改:

cd budget-tracker
git init
git add .
git commit -m "Initial commit"

此时若运行 python -m pytest,两个测试都会失败:

Failing tests

失败的测试

为了让 OpenHands 访问,先停止容器,并在 docker run 命令中新增一行:

-e SANDBOX_VOLUMES=$HOME/budget-tracker:/workspace:rw \

完整命令如下:

docker run -it --rm --pull=always \
  -e AGENT_SERVER_IMAGE_REPOSITORY=ghcr.io/openhands/agent-server \
  -e AGENT_SERVER_IMAGE_TAG=1.26.0-python \
  -e LOG_ALL_EVENTS=true \
  -e SANDBOX_VOLUMES=$HOME/Desktop/budget-tracker:/workspace:rw \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v ~/.openhands:/.openhands \
  -p 3000:3000 \
  --add-host host.docker.internal:host-gateway \
  --name openhands-app \
  docker.openhands.dev/openhands/openhands:1.8

格式为 host_path:container_path:mode。您的项目会在沙箱中的 /workspace 下出现,rw 表示允许代理编辑该目录。

只挂载您希望代理修改的项目。凡以读写模式挂载到 /workspace 的内容,都可能被代理更改。

给代理下达任务

开启新的对话,并像撰写缺陷报告一样描述问题:

月度汇总会把不同年份中同一月份的支出合并。

找出原因、修复问题,并运行测试确认通过。

就是这样。您无需指向 budget.py 或指出错误的具体行。

Conversation output

对话输出

接下来由前文提到的代理循环接管。代理会查看 /workspace,读取两个文件,并运行测试查看失败点。随后它会编辑代码并再次运行测试。

The agent running pytest in the sandbox terminal

代理在沙箱终端中运行 pytest

审查更改

代理显示任务已完成。现在您可以打开代码编辑器查看代码差异并检查修改。

正确的修复是在 budget.py 中的一行:

month = date[:7]

Fixed budget.py

已修复的 budget.py

您也可以运行 git diff 查看差异。

建议检查以下内容:

  • 源代码: 修复应位于 budget.py

  • 测试: 确认代理没有为让断言通过而编辑 test_budget.py

  • 测试运行: 请您亲自运行 python -m pytest——不要仅依赖代理的摘要

OpenHands 架构

OpenHands 有六个主要组成部分,每个负责一件事。

How the OpenHands components connect

OpenHands 组件如何连接

AI 模型

模型负责推理。它接收任务与对话历史,并以消息或工具调用进行回应。

模型不会更改您的文件或运行任何东西。它只决定下一步应发生什么。模型调用通过 LiteLLM 进行,因此同一代理既可配合托管提供商,也可配合本文中的 Devstral 本地模型方案。

代理逻辑

代理位于模型与其他一切之间。它运行“推理—行动”循环,即向模型请求下一步行动、运行工具,并处理结果或错误。

它也决定模型能看到什么。代理用压缩器管理对话历史,并在每次模型查询中加入技能与提示。

每一步都会被记录。代理执行操作并获得观察结果,对话保留该事件历史。模型在下一轮会看到这些事件,从而了解已发生的事情。

工具与动作

工具是代理影响模型之外世界的方式。标准集包括终端、文件编辑器与任务跟踪器,您也可以通过 MCP 服务器扩展更多工具。

模型会请求一个动作,例如“运行 pytest”或“在 budget.py 的第 8 行进行替换”。工具执行并返回观察结果,如测试输出或已更新的文件。

在动作执行前,它会经过安全检查。安全分析器会先评估每个动作,并可在需要时暂停代理以等待您的批准。

开发环境

工具不会在您的主机上运行。它们运行在沙箱中。

在 Docker 方案中,OpenHands 会在其自己的 Docker 容器中运行代理服务器。这就是为何本文要挂载 Docker 套接字——应用容器需要它来启动沙箱。

沙箱不一定是本地的。代理也可在临时工作区中运行,例如 Docker 或 Kubernetes;代理服务器通过 REST 与 WebSocket API 暴露执行、工具与工作区。不论沙箱在哪里运行,代理逻辑都保持一致。

代码仓库

仓库是代理的工作对象。它有两种方式进入沙箱:挂载本地文件夹(如本文),或通过 GitHub、GitLab、Bitbucket 集成连接的仓库。

仓库还可以告知代理如何行事。根目录下的 AGENTS.md 会在对话开始时注入系统提示。更聚焦的指令放在 .agents/skills/,代理先看到摘要,只有在需要时才加载全文。

这里适合放置代理无法自行推断的项目规则,例如“用 make test 运行测试,而不是 pytest。”

人工审核

您是架构中的最后一环。

OpenHands 支持三种确认策略:每个动作都需批准、完全无需批准、仅对高风险动作要求批准。最后一种依赖安全分析器,其会将每个动作标为 LOW、MEDIUM、HIGH 或 UNKNOWN 风险。默认是 NeverConfirm,因此除非您修改,代理将不经停顿直接运行。

第二个检查点在任务末尾。只有当您阅读过差异并检查过测试结果后,代理的工作才算完成。

OpenHands 工作流

我演示的是修复一行代码的 bug,但 OpenHands 当然可以处理更大的任务。

这些任务的共同点在于都需要多步完成。以下是六类适合代理循环的工作。

修复缺陷

本文中的缺陷很容易在单个文件中发现,而现实世界中几乎不会如此简单。

例如,应用日志显示生产环境出现 KeyError,堆栈跟踪指向的函数距离问题数据来源有三层调用。您将堆栈跟踪粘贴进 OpenHands 并请求修复。

代理会沿调用链追溯到数据来源,编写能复现错误的测试并确认测试失败。然后修复代码并运行完整测试套件,确保没有引入其它问题。

复现测试是要重点留意的部分。它能证明代理找到了真正的 bug,而不是仅仅定位到错误暴露的位置。

实现功能

功能开发通常会修改比您预期更多的文件。

例如命令行报表脚本需要一个 --since 标志按日期过滤交易。代理需找到参数解析器、添加该标志、将值传递给过滤逻辑并更新帮助信息。随后它会为新行为编写测试并更新 README。

这只是一个小功能就涉及四五个文件。代理会在任务跟踪器中记录这些文件,确保不会在第一个子任务成功后就停止。

重构代码

重构的目标是在不改变行为的前提下调整结构,测试套件是保证行为未变的依据。

例如项目有一个巨大的 utils.py 文件,混杂日期/字符串/文件等辅助函数。您让 OpenHands 将其拆分为三个模块。

代理会创建新模块、移动函数,并更新代码库中的每处 import。它会在每次移动后运行测试,这样一旦出问题,就能知道是哪次移动导致的。

编写测试

无测试代码是代理常见的切入点,因为任务清晰且易于验证。

例如日期解析模块没有测试。代理会阅读函数,为常规输入和空字符串、闰年、非法格式等边界情况编写 pytest 用例并运行。

若新测试失败,代理需要决定是测试有误还是代码有 bug。这一判断应由您来核实。

探索现有代码库

并非每个任务都需要改代码。

您可以向 OpenHands 提问,例如“该应用在哪一步在到达数据库前校验用户输入?”代理会搜索代码库、跨文件追踪函数调用,并给出带文件路径与行号的答案。

当您加入新项目或久未维护的代码时,这非常有用。对于此类只读任务,将仓库以 :ro 模式而非 :rw 挂载,如此即便意外也无法修改内容。

运行与调试应用

有些缺陷只会在应用运行时暴露。

例如某个 API 端点返回 500,测试并未覆盖。代理会在终端启动服务器,使用 curl 发送请求,并从服务器日志中读取回溯信息。

随后它会修复代码、重启服务器并再次发送相同请求。若响应仍不正确,循环将继续。

这与您亲自进行的“编辑—运行—检查”循环相同,只是代理会处理每次重启与重试。

OpenHands 与其他 AI 编码代理对比

OpenHands 不是唯一能接收任务并自行推进完成的工具。Claude Code、Cursor 与 GitHub Copilot 现也具备代理特性,但在一些重要方面有所不同。

OpenHands vs Claude Code

两者最为接近。它们都运行一个代理循环:读取代码、编辑文件、运行命令并检查结果。

第一处差异在于所有权。每个公开的 OpenHands 仓库都有自己的开源许可证,您可以阅读、修改并自托管全部组件。 Claude Code 是 Anthropic 的专有代理式编码工具,可在终端、IDE、桌面应用与浏览器中使用。

这也引出了模型问题。Claude Code 构建在 Anthropic 的 Claude 模型之上。OpenHands 则可配合任何 LiteLLM 支持的提供商与模型,包括本文的本地 Ollama 配置。

日常工作流也不同。Claude Code 起步于终端工具,很多开发者至今仍主要在终端中使用;OpenHands 依赖浏览器 UI,其 CLI 功能完备但主要以稳定性维护为主。

两者都允许您控制代理行为。Claude Code 会从 .claude 目录读取 CLAUDE.md、设置、hooks、skills、commands 与 subagents。OpenHands 则从仓库读取 AGENTS.md 与技能,并且 SDK 允许您用 Python 构建自定义代理。

二者的自主性也不尽相同。Claude Code 通过权限模式、hooks 与允许/拒绝规则控制工具使用,并可对命令进行沙箱化。OpenHands 默认将每个命令在 Docker 沙箱中运行,并在此之上提供确认策略。

简言之,Claude Code 是可即装即用的打磨完善方案,而 OpenHands 需要更多设置,换来更多可控性。二者也并非互斥。Agent Canvas 可以用 Claude Code 替代默认的 OpenHands 代理运行。

OpenHands vs Cursor

Cursor 是一款 AI 代码编辑器。OpenHands 是一个代理平台。这是主要差异,其它差异多由此衍生。

在 Cursor 中,您在编辑器内工作,代理与您并肩协作。您会看到编辑实时出现在文件中,选择接受或拒绝,并继续编码。在 OpenHands 中,您描述任务,代理在沙箱中工作,您再审查结果。GUI 虽然包含指向沙箱的 VS Code 视图,但那并非主要工作发生地。

仓库访问上也类似分野。Cursor 的代理仅在您编辑器中打开的代码上工作。OpenHands 则对您挂载进沙箱或通过 Git 集成连接的任何仓库工作。

随着 Cursor 的 Cloud Agents,这一差距缩小。它们在云端无人值守运行,通过分支与 Pull Request 返回工作结果,并且需要连接 GitHub、GitLab、Azure DevOps 或 Bitbucket 账户及付费方案。这与 OpenHands 的做法相近,但运行于 Cursor 的基础设施上。

扩展性是二者差异最大的方面。Cursor 支持 MCP 服务器与项目规则,但编辑器与代理都是闭源产品。OpenHands 则可改动代理本身、任意部署,并运行在本地模型上。

OpenHands vs GitHub Copilot

GitHub Copilot 起初是编辑器中的自动补全工具,后来发展出代理功能。OpenHands 生来即是代理。

Copilot 的最大优势在于其所在之处。它在 VS Code 与 JetBrains IDE 中运行,其云端代理直接在 GitHub 上工作。OpenHands 并无这类 IDE 级集成。

在仓库级任务上,Copilot 云端代理是最接近的对比项。您将任务分配给某个 issue,它会在由 GitHub Actions 支持的临时开发环境中工作,期间可运行测试与 linter,再推送更改。OpenHands Cloud 在您在 issue 或 PR 评论中提及 @openhands 时也会做类似的事情。

平台是主要差异。Copilot 云端代理向所有付费 Copilot 方案并托管在 GitHub 上的仓库开放。OpenHands 可配合 GitHub、GitLab、Bitbucket 或本地文件夹运行,并且如您所愿可运行在自有硬件上。

Copilot 允许您为任务选择模型,但仅限于 GitHub 提供的模型。OpenHands 不受此限制。

下面快速回顾:

 OpenHandsClaude CodeCursorGitHub Copilot
来源开源专有专有专有
模型任意 LiteLLM 提供商,包括本地Claude 模型多家提供商加自研模型GitHub 提供的模型
主要界面浏览器 UI、SDK终端、IDE、桌面、浏览器AI 代码编辑器IDE 插件、GitHub
代理运行位置Docker 沙箱,本地或远程您的机器或 Anthropic 云您的编辑器或 Cursor 云您的 IDE 或 GitHub Actions
自托管支持不支持仅企业版不支持

OpenHands 与其他 AI 代理对比

面向软件工程团队的 OpenHands

对单个开发者而言,OpenHands 是需要时打开的工具。对团队则不同。

多数团队已有基于 issue 的工作流,OpenHands Cloud 能接入其中。它与 GitHub、GitLab、Bitbucket,以及 Slack、Jira、Linear 集成。您可以在 issue 或 PR 评论中提及 @openhands,代理就会据此接手任务。

还有那些无人明确提出但人人受益的工作。Agent Canvas 自动化可按计划或响应 webhook 事件运行。比如团队可共享一个代理服务器用于代码审查与依赖更新,而每位开发者在自己的笔记本上运行个人代理。

测试流程与本文相同。代理会在沙箱中先运行测试套件再回报结果。但沙箱运行并不替代 CI——您的流水线仍会在每个 PR 上运行,与人工代码相同。

关于 Pull Request:当 OpenHands Cloud 与 GitHub 协同时,它会请求有效期 8 小时的短期令牌,拥有对内容、issue、PR 与 workflow 的读写权限。在自托管的 Enterprise 部署中,代理使用触发它的用户的 GitHub 授权,因此每个更改都能追溯到个人。

这才是责任应有的方式。代理可以发起 PR,但需要开发者批准。分支保护与必需评审对代理的 PR 同样适用。

隔离环境让这一切能规模化运作。每个任务在自己的沙箱中运行,因此两个代理修两个 bug 时既不会覆盖彼此的文件,也不会争用同一端口。

OpenHands 的安全与沙箱

代码补全工具始终只是建议文本,是否采纳取决于您。

代理则不同。它会在您的项目中穿梭,自主执行命令、安装包、编辑文件,且通常无需询问。因此问题从“这段代码是否正确?”变成“代理为达到结果都运行了什么?”

隔离的执行环境

Docker 沙箱可以保护您的主机文件与程序、主机资源,以及其他容器与进程。若代理运行了破坏性命令,其影响被限制在容器内。

本地方案有一处例外需关注。应用容器会挂载主机的 Docker 套接字以便启动沙箱,而访问该套接字意味着能够控制您机器上的 Docker。

仓库权限

沙箱只能保护未被挂载的内容。被挂载的文件与目录都可能被修改或删除。

只挂载当前项目,切勿挂载您的 home 目录。对于代码阅读等只读任务,使用 :ro 模式。对于 Git 集成,仅授予代理所需的特定仓库访问权限,不多不少。

机密与凭据

若您提供了凭据(如 API key 或 token),代理即可使用它们。而能读取机密的代理也能将其打印到日志或发送到其他地方。

因此不要挂载包含生产 key 的 .env 文件所在的文件夹。仅提供作用域受限的测试凭据,并频繁轮换。

网络访问

默认情况下,代理可以从容器内访问互联网。它需要联网来安装软件包,但也因此可以访问任何外部服务。

这为提示注入打开了大门。网页或 issue 评论可能包含代理会遵循的指令。GitHub 为其自家云端代理默认通过防火墙限制互联网访问,值得为您的 OpenHands 部署考虑类似限制。

命令执行

您可以控制哪些命令无需批准即可运行。OpenHands 支持三种确认策略:全部批准、无需批准、仅对高风险动作要求批准。默认是 NeverConfirm。

“高风险动作”选项有个注意点。默认的 LLM 安全分析器使用模型为其自身动作打的风险等级。模型可能将破坏性命令标为 LOW,从而在未征求您同意的情况下运行。分析器仅为策略层提供风险分类——它本身不会阻止任何动作,文档建议将其与 Docker 隔离结合使用。

审查生成的更改

以上措施限制的是代理能做什么。审查阶段同样重要,因为它让您核查代理实际做了什么。

请阅读完整 diff,而不只是您预期会变动的文件。对 CI 配置、依赖文件与脚本格外留意。在 OpenHands Cloud 中,代理的 GitHub token 拥有对 workflow 的写权限,因此 .github/workflows 下的改动可能改变您的流水线运行内容。

OpenHands 的局限性

OpenHands 编写的代码依然可能有缺陷。测试通过仅意味着代码与测试相符,而测试可能也是代理编写的。若测试薄弱,代码可能通过却依然错误。

复杂任务往往需要您在环中。模糊的需求或代理无法做出的设计决策会让其停滞,或更糟的是朝错误方向推进。

在强大的托管模型支持下,OpenHands 能良好处理多文件任务。使用小型本地模型时,您会看到工具调用失败与类似聊天机器人的回答;即便上下文窗口很大,某些本地模型仍难以稳定使用工具。

代理循环也比聊天更昂贵。每一步都会将对话历史再次发送给模型,长任务需要很多步。OpenHands 文档提醒代理会向 LLM 发出大量提示,并建议设置支出上限与用量监控。上下文压缩器有所帮助,但它会摘要较早步骤,长任务中细节可能丢失。

工具访问带来安全风险。拥有终端与网络访问权限的代理,若遵循了错误指令,可能造成实际损害——这正是为何沙箱与您的审查如此重要。

并且每一次更改仍需有人批准。务必牢记这一点。

OpenHands 与 AI 编码代理的未来

AI 编码工具已经从自动补全发展到聊天,再到能完成整块任务的代理。OpenHands 是推动最后一步前进的几个项目之一。

这一趋势在全行业都很明显。Cursor 描述了一个新兴时代:自治云代理将承担更大、周期更长的任务。Copilot 现已能接收来自 GitHub 与 Linear 的 issue。Claude Code 则能在终端、浏览器与 Slack 中运行。

开源平台在这场转变中有其独特角色。借助 OpenHands,您可以检查代理的工作原理、将其运行在自有基础设施上,并自选模型。对有严格数据规范的团队而言,这往往是他们被允许使用代理的唯一方式。

更长的任务也带来新问题。一个运行一小时的代理会做出比运行一分钟的代理更多的决策,而每个决策都可能偏离您的初衷。更好的模型会有所帮助,沙箱、确认策略与审查亦然。

总结

OpenHands 与竞争者的不同在于可控性。您可以阅读源码、在自有硬件上托管、并配合任意模型(包括本地模型)运行。像 Claude Code、Cursor、GitHub Copilot 这类打磨更紧的商用工具能提供更好的体验,但前提也由它们决定。

但一个能访问您终端与仓库的代理,仍需要人来检查其工作。务必记得阅读 diff 并亲自运行测试。

如果您想学习如何从零开始创建代理,请观看我们的Introduction to Creating AI Agents in Python 网络研讨会。

FAQs

什么是 OpenHands?

OpenHands 是一个用于构建与运行代码类 AI 代理的开源平台。其编码代理可以检查仓库、编辑文件、运行命令与测试,并对结果进行迭代直至任务完成。您可以在 Docker 本地运行、通过 SDK 使用,或在 OpenHands Cloud 上运行。

OpenHands 可以免费使用吗?

OpenHands 软件是开源的,您可以无需许可证费用自行托管。您需要支付的是模型费用——如 Anthropic 或 OpenAI 等托管提供商按 token 计费,而代理循环会消耗大量 token。若通过 Ollama 或 LM Studio 运行本地模型,唯一成本是您的硬件。OpenHands Cloud 是单独的商业服务。

OpenHands 与 GitHub Copilot 或 Cursor 有何不同?

Copilot 与 Cursor 围绕编辑器构建,AI 在您编写代码时与您并肩工作。OpenHands 则是“代理优先”——您描述任务,代理在沙箱中完成,您审查结果。它也是开源的,支持任意 LiteLLM 模型,并可运行于自有基础设施上,而 Copilot 与 Cursor 在这方面均不及。

我能用本地模型运行 OpenHands 吗?

可以。OpenHands 可通过 OpenAI 兼容 API 连接 LM Studio、Ollama、vLLM、SGLang 等本地服务器。请选择面向代理式编码的模型,如 Devstral Small 2 或 Qwen3.6-35B-A3B,并将上下文窗口设置为至少 22000 个 token。较小的通用模型往往会在工具调用上失败,且回答更像聊天机器人。

将代码访问权限授予 OpenHands 是否安全?

OpenHands 在 Docker 沙箱中运行代理命令,可保护您的主机系统免受大多数失误影响。但凡挂载进沙箱的内容都可能被修改或删除,且您提供的任何凭据都可能被代理使用。默认情况下,代理在行动前不会请求批准,因此请只挂载必要项目、使用权限受限的测试凭据,并在合并前审查每一个 diff。

主题