---
url: /openhands/introduction.md
description: >-
  OpenHands（前身 OpenDevin）是 MIT 协议开源的 AI 编码智能体平台，2026 年 10 月 6 日发布 v1.25.0。它以
  Agent Canvas 控制台 + Agent Server + 自动化服务三层结构，把 OpenHands、Claude
  Code、Codex、Gemini CLI 等任意 ACP 智能体统一调度到本机、Docker、云沙箱或企业 VPC 里跑，并从
  Slack、Jira、Linear、GitHub 触发定时任务与事件自动化。官方口径 8 万+ GitHub Star、900 万+
  次下载。本文带你从它到底是什么、讲到在本机把它跑起来。
---

# 认识 OpenHands：那个"开源 Devin"，刚刚把自己做成了 coding agent 的控制台

先说一件让我有点意外的事。

2026 年 10 月 6 日凌晨，OpenHands 发布了 v1.25.0。我把那份 Release Notes 从头翻到尾，越翻越觉得不对劲——**几百条改动里，几乎没有一条在讲"我们的 Agent 变聪明了"。**

讲的是这些：设置子页面的返回按钮轮廓、对话抽屉标签条的语义、更新弹窗在手机屏幕上别溢出、WebSocket 前台重连后台干净断开、长回复能不能滚动、插件搜索框在窄屏上还能不能用。

一个 AI 编程 Agent 项目，把精力花在了这些地方。

这说明它已经过了"证明 Agent 能干活"的阶段，正在过第二关：\*\*怎么让一群人在生产环境里天天用它，还不把平台和安全团队逼疯。\*\*这两关之间的距离，比大多数人想的远得多。

而讽刺的是，很多人对 OpenHands 的印象还停在"那个开源版的 Devin"——一个能自己写代码、跑命令、提 PR 的东西。这个印象没错，但现在它是远远不够的。

## 什么是 OpenHands

**OpenHands 是一个开源的 AI 编码智能体平台（前身叫 OpenDevin，2024 年底改名），MIT 协议，当前稳定版 v1.25.0（2026 年 10 月 6 日发布）。它现在的主打形态叫 Agent Canvas，官方给它的定位是"自托管的开发者控制中心"（the self-hosted developer control center for coding agents and automations）。**

先把"它不是什么"说清楚，这比讲它是什么更重要：

* 它**不是**一个模型。它是跑模型、跑 Agent、管 Agent 的那一层。模型你自己带，闭源的、开源的都行，官方明确列了 Kimi、DeepSeek、Qwen 这类开源权重都可以接；
* 它**不是**某一家 Agent 的壳。它默认跑自家的开源 Agent，但**任何实现了 ACP（Agent Client Protocol）的 Agent 都能挂进来**——Claude Code、Codex、Gemini CLI，或者你自己写的；
* 它**不是**一个聊天窗口。它是一个有前端控制台、有后端服务、有调度层、能在你自己的机器或 VPC 里长期跑着的系统。

架构上它现在是**四个仓库分工**，这个划分我觉得挺值得学的：

| 仓库 | 职责 |
|---|---|
| `OpenHands/OpenHands` | Agent Canvas 前端、用户控制中心、后端选择与本地栈编排 |
| `OpenHands/software-agent-sdk` | Python SDK、Agent Server、智能体、工具、会话、工作区、事件流，以及**权威的服务端 API** |
| `OpenHands/typescript-client` | 浏览器可用的 TypeScript 客户端，消费 Agent Server API |
| `OpenHands/automation` | 自动化定义、定时、webhook、运行历史与分发 |

一句话串起来：**自动化服务决定"什么时候跑"，Agent Server / SDK 决定"跑什么"。**

> 我一直觉得这两年 AI 编程工具的叙事跑偏了。所有人都在比"我的 Agent 能不能一次写完一个功能"，但真实世界里卡住团队的从来不是这个——是**谁来管这堆 Agent**：谁能起任务、它能碰哪些仓库、跑在哪台机器、花了多少钱、改了什么东西。
> OpenHands 现在回答的就是后半截问题。它管这个叫 Agent Control Plane，我倒觉得翻译成人话就是：**给 Agent 装一套运维。**

规模这块，官方博客的口径是 **8 万+ GitHub Star、900 万+ 次下载、数百名开发者贡献**，并称被"大型企业与高速成长的创业公司"的工程师使用在真实研发流程里。第三方 GitHub 榜单同期已经把 Star 数记到 9 万上下。**注意：Star 数各家快照时间不同，别拿某个具体数字当精确值。**

## 它有什么特点

* **一个控制台管多个后端，切着用。** 这是 v1.24.0 引入 Agent Canvas 之后最有价值的变化。Agent Server 是一台机器上跑多个 Agent 的 REST 服务，Canvas 可以同时连多个 Agent Server 并在它们之间切换。

  实际用法很具体：你和团队共用一个服务器跑代码审查和依赖更新，同时你自己的私人 Agent 跑在笔记本上。一个界面，两个后端，互不干扰。

* **Agent 随便换，靠 ACP 协议。** 官方原话是"Use OpenHands, Claude Code, Codex, Gemini, or any agent with Agent Client Protocol"。这不是营销话术，架构上是真解耦——Canvas 只认协议，不认厂商。

  > 这个设计我挺服气的。它等于承认了一件不太体面的事：\*\*没人知道半年后哪个 coding agent 最强。\*\*既然赌不准，那就别赌，做那个"不管谁赢都能接进来"的层。这个姿态比"我们的 Agent 天下第一"诚实得多。

* **运行时也随便换：本机、Docker、虚拟机、云沙箱、企业 VPC。** 你可以把 Agent Server 跑在笔记本上（官方自己加了警告：Agent 会拿到你整个文件系统）、跑在一台专门的 Mac Mini 上、跑在云上的虚拟机里，或者跑在 OpenHands Cloud / Enterprise 的基础设施里。

  想在 Docker 沙箱里跑，官方给的方式是装好 Docker 后起容器；想让**每次开一个新会话就新起一个隔离容器**，用环境变量切：

  ```bash
  OH_CONVERSATION_RUNTIME=docker agent-canvas
  ```

  这种模式下每个容器挂载自己会话的工作区和持久化状态，文件和历史都能活过容器替换。**但要注意：同一份宿主机目录还是会被多个会话共享**，想避免冲突就给不同会话分不同目录或 git worktree。

* **自动化才是它现在真正的重心。** 官网一口气列了六类模板：Slack 频道监听（有人 @openhands 就开一个带上下文的会话，跑完回来回复）、Slack 站会摘要、PR 评审、Linear issue 分类、Jira 故障分级分派、CI 失败自动修、安全告警修复、事故复盘草稿。

  触发源是 **GitHub、Slack、Jira、Linear、定时、webhook**，再加 **MCP** 接你公司内部的工具和数据源。

  官方把一条自动化拆成六步：Signal → Plan → Execute → Validate → Ship → Monitor。听着很流程化，但这套东西确实对应着真实需求——**"让工程活在没人手动点开始的情况下继续往前走"。**

* **v1.25.0 的具体更新，能看出他们现在关心什么。**

  * **LLM Profiles 批量添加**：按 provider 批量把模型加成 LLM profile（#16426），也支持按单个连接批量加（#17723）；
  * **Model Router 可用直连提示词**：新增 direct-prompt 设置（#16147），还加了"在会话开始时运行"的开关（#17797），并且创建第一个 router 时自动打开这个开关（#17840）；维护项里还把默认 router 改名为 **OpenHands Router Pro / Flash**（#17782）；
  * **Agent Profiles 能从服务端目录里挑全部工具**（#17516，同时把 SDK 钉到 1.53.0），还能给单个 profile 配自己的 persona 或额外指令（#17843）；
  * **聊天输入支持语音转写**（#17804）；
  * **自动化的模板与 Git 集成**：云端后端也显示模板、并提供原生 Git 集成（#17830），仪表盘可以按创建者筛选（#17814）；
  * **Canvas Apps 支持更新操作**（#17736），Canvas 扩展支持渲染 manifest 里声明的 SVG 图标（#17877）；
  * **Canvas 事件流重构**：按 event id 回收流式槽位、删掉原来的文本匹配协调器（#17465）。这条看着枯燥，其实是把前端状态同步从"猜"改成了"认 id"，属于那种做过的人才知道有多痛的活。

* **企业侧的那套控制面，是它跟纯开源工具拉开差距的地方。** 官方把这块叫 Agent Control Plane：谁能跑 Agent、能访问什么、在哪执行、花多少、改了什么，集中管。Enterprise 形态部署在你自己的 VPC（官方支持 AWS / GCP / Azure），配组织级密钥、预算看板、OAuth MCP、自动化 Git 同步这些能力。

  这里有个坑必须提：\*\*核心框架（含 `openhands` 与 `agent-server` 镜像）是 MIT，但 `enterprise/` 目录是"源码可见"而非开源——要用超过一个月需要购买授权。\*\*别一看 MIT 就以为整仓都能白嫖。

## 用在哪儿

**Slack 里接需求。** 官网首页第一个模板就是这个：监听频道里的 @openhands，带着消息上下文开会话，跑完回来回复。对很多团队来说，这比"让人去某个网页里提任务"顺手得多——需求本来就发生在聊天里。

**PR 评审和 CI 失败自愈。** 这是我觉得 ROI 最实在的一类。监听 PR 上你配的 label，读完整 PR 上下文，发一条评审意见；或者检测失败的 workflow，读日志，判断原因，开一个带修复方案的 PR。这类任务边界清楚、判定标准明确，正好是 Agent 擅长的形状。

**Jira / Linear 的分诊。** 官方 2026 年 8 月 26 日的博客专门写了 **Jira Cloud 在 Enterprise 组织级的接入**：连一次，整个组织的团队都能直接从 Jira issue 触发开发流程，从规划、查 bug 一直到提 PR。Linear 那条则是分类新 issue、建议标签、找重复、开工前先问澄清问题。

**安全告警修复。** 定时扫仓库的已知漏洞、过期依赖和不安全写法，产出带优先级的修复摘要，必要时直接开 PR 修掉。**提醒一句：涉及认证、加密、支付这类代码，别让它自动合并，让它开 PR 交给人工审。**

**硬件与模型厂商的生态位。** 这部分有明确的公开动作可以查：

* **AMD**：官网首页挂着 AMD 的署名评价，Lemonade Server 与 OpenHands 的集成主打本地 coding agent 的隐私、成本与模型选择自由，并在 Ryzen AI PC 上利用硬件加速；
* **NVIDIA**：2026 年 8 月 11 日官方博客宣布支持 **Nemotron 3.5 Lightning**（面向常驻 Agent 的可定制开源模型）；2026 年 8 月 10 日，OpenHands 加入 **NVIDIA 牵头的 Open Secure AI Alliance**，做开放可审计的安全 Agent 基础设施。

这两条合起来看很有意思：\*\*一边是让 Agent 能在本地 PC 上跑（隐私与成本），一边是让它在企业里可审计、可治理。\*\*中间那层就是 OpenHands 自己。

**不适合的地方也说清楚：**

* 想要"装完就白嫖全套"的同学——**开源部分是免费的，但模型费用是你自己的**；Enterprise 目录要商用得买授权；
* 只有一台笔记本、还指望 Agent 24 小时干活的同学——**笔记本合上它就停了**。官方自己说"把 Agent 跑在云服务器上才是威力最大的用法"，也正是这条让 Slack、GitHub、Datadog 这类外部触发能真正闭环；
* 想直接在本机无沙箱跑的同学——官方 README 里那句警告写得很直白：**Agent 会拥有你整个文件系统的访问权限**。这不是吓唬人，是字面意思。

## 初体验

官方给了四条路，我按"从省事到折腾"排。

**路线 A：Docker 沙箱一条命令（推荐第一次试）。**

```bash
export PROJECTS_PATH="$HOME/projects"   # 你希望 Agent 能访问的项目目录，先建好
mkdir -p "$PROJECTS_PATH" "$HOME/.openhands"

docker run -it --rm \
  -p 127.0.0.1:8000:8000 \
  -e AGENT_CANVAS_ALLOW_LAN_SESSION_KEY=true \
  -v "$HOME/.openhands:/home/openhands/.openhands" \
  -v "${PROJECTS_PATH}:/projects" \
  ghcr.io/openhands/agent-canvas:1.25.0
```

然后打开浏览器访问 `http://localhost:8000/canvas`。前置条件是 Docker（macOS/Windows 用 Docker Desktop，Linux 用 Docker Engine）。Windows 的命令官方单独写在 `README.windows.md` 里。

**路线 B：不带沙箱，直接本机起。**

```bash
npm install -g @openhands/agent-canvas
agent-canvas
```

前置条件是 **Node.js 24 或更高版本** 加 **`uv`**。这个命令默认起完整本地栈，也可以拆开跑：

```bash
agent-canvas --frontend-only   # 只起静态前端 + ingress
agent-canvas --backend-only    # 只起 agent server + 自动化后端 + ingress
```

UI 在 `http://localhost:8000`。

**路线 C：每个会话一个 Docker 容器（想并行跑多个 Agent 时用）。**

```bash
npm install -g @openhands/agent-canvas
OH_CONVERSATION_RUNTIME=docker agent-canvas
```

前置是 Node.js 24+、`uv` 和能用的 Docker，且**启动 Canvas 的那个用户得能执行 `docker` 命令**。已存在的本地会话不会自动转换过去。

**路线 D：从源码跑。**

```bash
git clone https://github.com/OpenHands/OpenHands.git
cd OpenHands
npm install
npm run dev
```

同样需要 Node.js 24+ 和 `uv`（agent server 走 `uvx` 启动）。这条路的警告和路线 B 一样：**Agent 直接跑在你的机器上，有完整文件系统权限。**

**几个你几乎一定会碰到的坑：**

**第一，端口和监听地址别乱改。** `npx` 和 `npm run dev` 起的服务**默认只绑 127.0.0.1**，所以本地会话密钥不会被局域网里别的机器够到。想监听全部网卡就传 `--host 0.0.0.0`（或设 `OH_BIND_HOST`），但**此时不再自动注入会话密钥**，UI 会退回让你手填 API key 的那个界面——这是设计，不是 bug。

Docker 那边相反：容器内部监听全部网卡以便端口映射，但**默认不把会话密钥注入 HTML**。上面那条命令里显式开了 `AGENT_CANVAS_ALLOW_LAN_SESSION_KEY`，同时把宿主端口只发在 `127.0.0.1` 上，两头才安全。**如果你要把 Docker 端口发到局域网或公网，请务必去掉这个环境变量**，并设一个够强的 `LOCAL_BACKEND_API_KEY`；忘了的话可以用

```bash
docker exec <container> sh -c 'cat "$STATE_DIR/api-key.txt"'
```

把自动生成的那个捞出来。真要放到公网上，老老实实去读官方的 self-hosting 文档做安全加固。

**第二，`PROJECTS_PATH` 要先建。** 没建目录就起容器，挂载会出问题。这个坑很小但很常见。

**第三，别一上来就给满权限。** 尤其是你接了第三方 MCP server、或者把 Canvas 放到了能被别人访问的地址上。官方在文档里反复强调访问边界和审批，不是凑字数。

**第四，`uv` 这个依赖容易漏。** 官方文档里凡是走本机跑的路径，前置条件都写了 Node.js 24+ 和 `uv`。只装了 Node 的同学会在起 agent server 那一步卡住。

## 进阶

如果这篇文章你只记住一句话，我希望是这句：

**AI 编程 Agent 的下半场，比的不只是"它能不能写出来"，而是"一群人怎么管住一堆它"。**

我们看着 coding agent 的能力一路狂飙：读文件、写文件、跑命令、动 Git、开浏览器、连远程主机、进 CI、接 Jira。能力每加一项，治理的难度就加一档。到今天，一个团队里有十几个 Agent 在后台跑，是已经发生的事，不是未来。

这时候真正卡人的问题变成了：谁起的任务？它能碰哪些仓库？在哪台机器上跑的？这个月烧了多少 token？它改的东西进主干前谁签的字？——\*\*这些问题，Agent 本身一个都答不了。\*\*它们属于平台层。

OpenHands 押的就是这一层，而且押法挺聪明：不赌模型（你带你的），不赌 Agent（ACP 接任意家的），只赌"总得有个地方管它们"。

冷水照例要泼三盆。

**第一，别把 Star 数当成熟度。** 8 万 Star 和 900 万下载说明它被大量下载和关注，不说明它在你的场景里跑得顺。v1.25.0 那份 Release Notes 里 **Bug Fixes 的条数明显多于 Features**，而且大量集中在前端交互、移动端、WebSocket 重连这些地方——这是一个正在快速长身体、边跑边修的项目。

**第二，迭代太快，文档和版本会打架。** 光 v1.25.0 这一个版本的维护项里，就把 TypeScript 客户端和 agent server 提到 1.50.1、Extensions 从 0.26.0 吃到 0.27.0 又到 0.29.0、Automation 从 1.17.0 到 1.19.0。这意味着**你今天搜到的教程，很可能对不上你装的版本**。以官方 README 和 docs.openhands.dev 为准。

**第三，成本在模型侧，不在许可证。** MIT 让你免费拿到整套框架，但跑 Agent 的每一轮都是 token。上自动化之前，先把预算和审批设好，别让它半夜三点帮你烧掉一个月的额度。

我的建议很具体：\*\*今天花四十分钟，用路线 A 那条 docker 命令起一个 Canvas，挂一个你不怕它乱动的项目目录，只做一件事——配一条"PR 评审"或者"每日依赖检查"的自动化，然后看两件事：它给的评审意见你认可几条，以及它在界面上留下的执行记录够不够你回溯。\*\*这两件事决定 OpenHands 值不值得进你的工具箱，比任何宣传页都准。

再往深一层，我建议你去读三个地方：**仓库 README 里的 Architecture 一节**（四仓分工讲得很清楚）、**`AGENTS.md`**（贡献边界和代码审查要求）、以及 **官方 docs 里的 self-hosting 文档**（安全加固那一节）。尤其是最后一份——一个愿意花整页篇幅教你怎么把它锁好的项目，值得你在放开权限之前先读完。

更多开源技术干货和学习资料，关注公众号「遇码」，领取专属福利。