OpenHands
通过 Agent Canvas 管理编程代理会话、文件与终端，并连接执行任务的后端。
OpenHands 的 Agent Canvas 是管理代理会话、文件、终端、模型配置和自动任务的浏览器界面，实际执行发生在它连接的后端。
OpenHands 能做什么
当前上手入口以 Agent Canvas 为主。界面、后端和工作区各有职责：界面用于操作，后端运行代理，工作区决定可处理的项目文件。
编辑建议：先决定任务在哪台机器或容器运行，再选择模型和文件目录。旧教程中的 Local GUI 与当前 Agent Canvas 启动方式需要区分。
把浏览器界面与执行后端分开
Agent Canvas 可以连接本机、Docker、虚拟机或托管云后端。切换后端会切换代理的执行环境，不只是改变一个界面设置。
围绕指定工作区处理文件
后端关联的文件夹、仓库、容器挂载或云沙箱决定代理能读写哪些文件；会话则保存自己的历史与代理配置。
分别配置模型访问路径
支持提供方密钥、兼容服务、本地模型以及适用的 ACP 代理登录方式。选择后端时也要考虑凭证实际位于哪台机器。
用项目规则与工具扩展任务
可以通过 AGENTS.md、Skills、MCP 和插件提供项目说明或工具；也有定时和事件触发的自动任务入口。
- 核心用途
- 在浏览器管理代理会话、文件和终端
- 可完成的工作
- 项目修复、独立工作区实验与可复用代理任务
- 如何开始
- 按官方指南安装 Agent Canvas 并连接后端
- 使用条件
- 核对后端文件范围、模型访问和运行环境
如何使用 OpenHands
- 选择当前 Agent Canvas 入口
从官方快速开始选择本地安装、Docker 或托管使用路径。不要把旧 Local GUI 的启动命令直接套用过来。
- 先决定执行边界
本机后端可操作本机文件；Docker 后端通过挂载限定文件可见范围。只连接本次任务需要的目录与服务。
- 配置模型并建立会话
选择可用的模型访问方式，确认凭证与后端环境匹配，再建立针对具体工作区的会话。
- 执行一个小任务并检查产物
给出目标和检查命令，查看文件变更与终端输出。先确认后端和工作区正确，再扩大任务范围。
在明确工作区里修复一个问题
适合：能管理开发环境的个人开发者
- 准备输入
- 仓库副本、问题复现、允许访问的目录与测试命令。
- 操作方法
- 编辑建议：先确定后端和工作区范围，再创建会话，让代理定位并修改目标问题，最后在该环境执行检查。
- 预期交付物
- 属于指定工作区的修复补丁。
- 人工检查
- 核对变化实际发生在哪个后端、哪个目录，检查代码差异和测试结果。
把持续任务放到专用机器
适合：已有虚拟机或专用开发环境的团队
- 准备输入
- 专用后端、仓库、模型访问方式和必要凭证。
- 操作方法
- 编辑建议：让浏览器连接专用后端，先用小任务确认文件与命令所在位置，再处理耗时任务。
- 预期交付物
- 在专用环境中持续推进的项目会话。
- 人工检查
- 检查连接状态、资源占用和输出位置；关闭界面后是否继续执行取决于后端是否仍运行。
让重复任务遵循仓库规则
适合：维护多个相似任务的开发团队
- 准备输入
- 明确的 AGENTS.md、任务说明与已有检查方法。
- 操作方法
- 编辑建议：先写入可执行的项目规则，完成一次人工核对的任务，再考虑使用 Skills 或自动任务复用。
- 预期交付物
- 带项目约束的代理工作流程。
- 人工检查
- 检查规则能否被实际执行，自动任务应保留可检查的产物和失败结果。
界面与参考图片
开始前需要了解
旧 Local GUI 已是旧版入口
官方将 Local GUI 标为 Legacy；agent-canvas 与 openhands serve 对应不同入口。照搬旧命令可能启动不到当前界面。
直接本机运行不是自动沙箱
本机后端可以操作本机文件。Docker、虚拟机和托管环境各有不同边界，需要按实际挂载、凭证与网络设置理解权限。
关闭终端可能停止本地后端
使用本地 npm 或 npx 启动时，关闭终端会停止相应进程；Docker、虚拟机或云后端则取决于它们自身是否继续运行。
本地和 Individual 层可免费使用软件；模型 Key 或提供商用量另计，企业部署/支持按商业方案。
账号权限、费用与可用功能请以官方入口的当前说明为准。重要结果应先检查，再用于实际工作。
常见问题
浏览器里打开页面，任务就运行在云端吗？
不一定。浏览器只是客户端，执行位置由连接的后端决定，可以是自己的机器或独立服务器。
新用户应该继续使用旧 Local GUI 教程吗？
官方当前优先介绍 Agent Canvas。旧 Local GUI 属于 Legacy，启动方式和界面不能直接混用。
切换后端会发生什么？
代理所使用的执行环境会改变；会话历史与状态归对应后端管理，工作区也需要按所连环境确认。
能否连接本地模型？
Agent Canvas 支持本地或 OpenAI 兼容的模型服务，但需要先准备可访问的服务和相应模型配置。
