平时做技术实践时,很多问题不是概念不会,而是细节没串起来。拿“OpenHands实践教程:从安装到自动化详细操作步骤”来说,它看着像小点,放到项目里常会牵出环境、配置、兼容性和维护成本。下面按实际采用顺序,把思路、关键写法和容易踩坑的地方讲清楚,便于大家直接对照操作。
实际处理时,OpenHands(原名 OpenDevin)是目前 GitHub 上 Star 数最高的开源 AI 软件工程代理框架,截至 2026 年 11 月 16 日已累积 93,537 颗 Star,最新版本 v1.40.0 于 2026 年 11 月 12 日发布。它已不只是一个"让模型帮你写代码"的工具——新版重新定位为自托管开发者控制中心(Agent Canvas),可统一调度 OpenHands 原生 Agent、Claude Code、Codex、Gemini CLI、Pi、OpenCode 等任意 ACP 兼容 Agent,在 Docker 沙箱里执行代码、修改文件、调用 API、跑测试、提 PR,同时兼容接入 Slack、GitHub、Linear、Notion 完成自动化工作流。本文从"你适合哪种安装方式"出发,覆盖模型设置、自动化功能搭建和两个高频踩坑的完整解决方案,帮助开发者用一份教程把 OpenHands 从零跑通。
OpenHands 是什么,和你熟悉的 AI 编程工具有什么不同
实际处理时,OpenHands 的核心思路是把大模型放进一个可执行环境,而不是只让它在对话框里回答问题。
理解这一步时,它在 Docker 沙箱里运行一个 Agent Server,Agent 能够:
- 读取你的代码仓库,理解项目结构
- 修改文件、执行终端命令、安装依赖
- 运行测试,根据失败结果自动修正代码
- 借助 GitHub API 提 PR
从实现思路看,前端 UI 叫 Agent Canvas,是你和 Agent 交互的控制台。你在这里下发任务、查看每一步的思考链和操作记录,也能够在任意步骤介入、纠正方向。
和 Cursor 或 IDE 插件的本质区别在于:OpenHands 的 Agent 在容器里动手,你在容器外看结果落到代码里,。Agent 对沙箱内的一切有完整权限,对宿主机的访问则由你决定挂载哪些目录。
理解这一步时,v1.40.0 还兼容作为多 Agent 编排平台——同一个 Canvas 能够同时连接本地 Docker、远端 VM、OpenHands Cloud 多个后端,不同任务分配给不同后端,不关闭当前会话就能够切换。
先判断你适合哪种安装方式
四种方式对应四类场景,选错了会带来不必要的麻烦。
只是想更快试一下?→ 方式一(npm,无沙箱)
在这个场景下,Agent 直接在你的机器上运行,有完整的文件系统访问权。速度最快,但风险也最高——Agent 如果误操作,会直接影响你的本地文件。只建议在干净的测试机或虚拟机里用,不要在日常工作机上用这种方式。
正式采用 / 生产环境?→ 方式二(Docker 沙箱)
理解这一步时,Agent 在容器里运行,只能访问你挂载进去的 $PROJECTS_PATH 目录。宿主机其他文件安全。这是官方建议的首选方式,状态借助 Docker 卷持久化,重启容器不丢数据。
需同时跑多个 Agent 任务?→ 方式三(多 Docker 沙箱)
从实现思路看,每个会话独立一个容器,互不干扰,适合同时发调试多个 PR 或同时处理多个项目。
需改 OpenHands 本身的代码?→ 方式四(源码编译)
贡献者或需定制化改造的团队用。
方式一:npm 更快安装
npm install -g @openhands/agent-canvas
agent-canvas
前提:Node.js 24 或更高版本,uv(Python 包管理工具)。
安装完成后访问 (链接已移除)。
再次提醒:Agent 有完整文件系统访问权,只在测试场景采用。
方式二:Docker 沙箱(建议)
第一步:准备工作区
export PROJECTS_PATH="$HOME/projects"
mkdir -p "$PROJECTS_PATH"
Linux Docker Engine(非 Docker Desktop)需额外授权容器内 uid 10001 的读写权限:
find "$PROJECTS_PATH" -type d -exec chmod a+rwX {} +
find "$PROJECTS_PATH" -type f -exec chmod a+rw {} +
结合项目来看,macOS 和 Windows 的 Docker Desktop 不需这一步。
第二步:启动容器
docker run -it --rm \
-p 127.0.0.1:8000:8000 \
-e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
-v openhands-state:/home/openhands/.openhands \
-v "${PROJECTS_PATH}:/projects" \
ghcr.io/openhands/agent-canvas:1.40.0
打开 (链接已移除)。
关于 openhands-state 卷:它保存你的设置、API Key 和对话历史。用 --rm 参数每次重启容器时不会丢失这些数据,因为数据在卷里而不在容器里。
生产环境建议:用 --restart unless-stopped 替代 --rm,这样 Agent 崩溃后容器会自动重启:
docker run -d \
--restart unless-stopped \
-p 127.0.0.1:8000:8000 \
-v openhands-state:/home/openhands/.openhands \
-v "${PROJECTS_PATH}:/projects" \
ghcr.io/openhands/agent-canvas:1.40.0
注意去掉了 AGENT_CANVAS_ALLOW_LAN_SESSION_KEY——对外网暴露时不开这个参数,改在 UI 里手动输入 API Key。
方式三:多 Docker 沙箱(并发任务)
npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas
理解这一步时,每开一个新会话,Canvas 自动起一个独立的 Docker 容器。多个任务互不干扰。
前提:Node.js 24+,uv,以及运行中的 Docker Desktop(macOS)或 Docker Engine(Linux)。
设置模型:填三个字段搞定
OpenHands 不绑定任何特定模型,兼容任意 LLM。设置路径:设置 → 模型 → LLM Profiles,填写:
- API Base URL:模型服务的 API 地址
- Model:模型 ID
- API Key:对应的密钥
从实现思路看,以七牛云大模型广场为例,它兼容多款主流大模型,兼容 OpenAI 协议,API 地址填 (链接已移除),模型 ID 在七牛云控制台「模型广场」查询,API Key 在控制台拿到后粘贴进去,保存即可用(官网:qiniu.com/ai/models)。
生产环境建议:固定 Docker 镜像版本号(比如 1.40.0,不要用 latest),模型设置单独管理,这样升级 OpenHands 版本时不会意外覆盖模型设置。
自动化功能:让 Agent 在你不在时继续工作
在这个场景下,Agent Canvas 的 Automations 功能让你能够把重复性任务交给 Agent 自动处理。
两种触发方式:
- 定时任务:设置 Cron 表达式,Agent 按计划自动运行
- Webhook 事件:GitHub、Slack、Linear、Notion 等服务推送事件后触发 Agent
一个典型设置:
GitHub 仓库收到新 Issue → Webhook 触发 → OpenHands Agent 分析 Issue → 自动拆解成任务清单 → 新建对应的 PR 草稿 → 发 Slack 消息通知团队
结合项目来看,这个流程完全在你不盯着的情况下运行,适合把"处理新 Issue 的第一步"自动化,让工程师只需在 PR 草稿上做最后 Review。
在这个场景下,Automations 设置在 Canvas UI 左侧边栏的 Automations 菜单里,不需写代码,可视化设置触发条件和 Agent 要执行的指令。
两个高频踩坑
坑 1:macOS 安装后提示"已损坏,无法打开"
落到代码里,这不是文件真的损坏。OpenHands Agent Canvas 的 macOS 应用包目前还没有借助 Apple Developer ID 签名,macOS Gatekeeper 会自动隔离未签名的应用同时报"已损坏"。
解决方法:把应用移到 /Applications 后,在终端执行一次:
xattr -dr com.apple.quarantine "/Applications/OpenHands Agent Canvas.app"
实际处理时,这条命令清除 Gatekeeper 的隔离标记,之后正常双击打开即可。这个限制是 macOS 的系统行为,不是 OpenHands 的 bug,官方正在推进签名流程(issue #16774)。
坑 2:方式一(无沙箱)下 Agent 删了不该删的文件
实际处理时,无沙箱模式的 Agent 对整个文件系统有写权限。Agent 在执行复杂任务时有时会误判路径,把不在目标范围内的文件也当成"需清理"的内容处理。
解决方案:生产环境始终用方式二(Docker 沙箱)。如果必须用方式一测试,提前备份工作区,或把工作区放在一个独立的空目录里再挂给 Agent,不要直接指向包含重要文件的路径。
版本选择:用固定版本号,不用 latest
理解这一步时,OpenHands 迭代很快——仅过去两个月就从 v1.36 迭代到 v1.40,平均每周发一个版本。
Docker 镜像用 latest 标签在生产环境是高风险行为,一次 docker pull 可能拉到行为有变化的新版本,导致已有自动化任务出现意外结果。
建议做法:
# 明确指定版本号
ghcr.io/openhands/agent-canvas:1.40.0
# 升级时:先在测试环境验证新版本,再更新生产
升级前三件事:备份 openhands-state 卷、记录当前版本号、在测试环境跑一遍现有自动化任务验证行为没有变化。
总结
从实现思路看,OpenHands v1.40.0 已经从一个 AI 编程代理工具,成长为能够统一调度多个 Agent 后端的开发者控制中心。MIT 协议、93k+ Star 的社区规模和每周迭代的节奏,使它成为目前开源 Agent 框架里最活跃的选择之一。按场景选安装方式(个人测试用 npm、生产用 Docker 沙箱、多任务同时发用多沙箱),配好模型 API,就能直接开始把重复性开发任务交给 Agent 跑。
从实现思路看,以上内容基于 OpenHands v1.40.0(2026-11-12 发布)和官方文档,框架迭代频繁,采用前请以 github.com/All-Hands-AI/OpenHands 最新 Release 为准。
落到代码里,总的来说,OpenHands适合结合实际项目边做边理解。先抓住核心思路,再逐步补上细节和边界处理,最后效果会更稳定,也更容易复用。

