OpenHands 能运行 Coding Agent，但第一步是限定它能碰什么

OpenHands 能运行 Coding Agent，但第一步是限定它能碰什么

OpenHands 不是“仓库旁边再放一个聊天框”。它更像一个 AI 开发控制面：前端、app server、sandbox service、代码托管集成、skills、agent runtime 都会在这里汇合。

这正是它有价值的地方，也是它需要先设边界的原因。第一次评估 OpenHands 时，不应该先问“用哪个模型更强”，而应该先问：这个 agent 到底被允许碰什么？

Doramagic 项目页：https://doramagic.ai/zh/projects/openhands/

Doramagic 项目说明书：https://doramagic.ai/zh/projects/openhands/manual/

上游项目：https://github.com/OpenHands/OpenHands

先把 OpenHands 当成执行边界，而不是捷径

OpenHands 上游仓库描述的是一个用于运行 coding agent 的平台，支持 local、remote、cloud 等后端。Doramagic manual 把它拆成几个可操作层：React/Remix 前端、FastAPI app server、conversation service、sandbox service、代码托管集成、secrets、settings、event callbacks，以及 skills / microagents。

这套结构意味着一次 agent session 不只是“模型生成代码”。真实运行中可能包含：

• 选择 repository；
• 准备 sandbox；
• 运行 setup script；
• 接入 GitHub、GitLab、Bitbucket；
• 读取或修改文件；
• 调用工具；
• 保存 settings 或 secrets；
• 暴露本地 web app 给浏览器查看。

如果只用“它能不能写代码”来评估 OpenHands，就会漏掉真正的风险面。更实际的评估方式是：它能不能在一个人类可检查的边界里完成任务。

第一次运行要故意小一点

不要一上来就把生产 bug、真实 token、主仓库写权限一起交给 OpenHands。更稳的第一次运行应该很无聊：

1. 使用临时仓库或 disposable branch。
2. 选择一个预期 diff 很清楚的小 issue。
3. 不提供真实生产 secret。
4. 记录 repository、branch、sandbox 和 model profile。
5. 编辑前先要求 plan 和拟修改文件列表。
6. 完成前必须跑 test 或 smoke check。
7. merge 前人工检查最终 diff 和命令记录。

这不是让 agent 变慢，而是让第一次失败可以被定位。

sandbox 状态不是细节

说明书里记录了 sandbox 的几种状态，例如 missing、starting、running、paused、error。它们看起来像基础设施细节，但当一次会话卡住、停住或没有继续执行时，这些状态就是判断依据。

第一天使用时，操作者至少要能回答：

• 当前 active sandbox 是哪一个；
• 它是 local、Docker、remote 还是 cloud-backed；
• setup script 是否跑完；
• 暴露了哪些 URL；
• session 是在等待 sandbox，还是已经开始执行代码；
• runtime/concurrency limit 命中时会发生什么。

一个需要注意的社区风险是：runtime 上限有时可能表现为旧 sandbox 被暂停，而不是清晰的 429/quota 错误。这里的经验很朴素：sandbox state 应该被当成产品证据记录，而不是藏在实现细节里。

secrets 和集成权限不能只写“请小心”

OpenHands 会接入代码托管资源，也会涉及 user context、settings、secrets 和 event callbacks。这些能力很有用，但第一次使用时必须给出明确权限策略。

一个更稳的初始策略是：

• 第一次 session 不放个人 token 或生产 secret；
• 只读 run 通过前，不给主仓库写权限；
• webhook / callback 配置必须人工确认；
• 没看到 repository 和 branch 证据，不允许说 ready；
• 探索性 run 不负责 merge 或 deploy。

这不是反对 agent，而是让 agent 用证据逐步获得更多权限。

别跳过那些无聊的失败模式

Doramagic 的 OpenHands pitfall log 记录了 installation、configuration、permission 相关风险。manual 里也保留了几个具体操作问题：self-hosted UI 启动卡住、容器里的 browser launch flag、dev container 生成 root-owned 文件、LLM profile 编辑状态、runtime cap 行为等。

这些不是“别用 OpenHands”的理由，而是要求第一轮 workflow 足够窄，让失败原因能被看见。

如果第一次失败，不要只问“OpenHands 行不行”。更应该查：

• sandbox 有没有启动；
• repository preparation 有没有完成；
• setup script 是不是用预期用户跑的；
• browser 或 exposed URL 是否需要额外 flag；
• model profile / API key 设置有没有意外被改；
• session 是否因为 runtime limit 被暂停；
• 最终 diff 是否匹配原始 issue。

这比泛泛说“AI coding agent 有风险”有用得多。

Doramagic 在这里提供什么

Doramagic 的 OpenHands pack 不是上游官方文档，也不代表官方背书。它是一个独立的 project context pack：quick start、prompt preview、human manual、pitfall log、boundary card 和 eval checks。

它适合被装进 Claude Code、Codex、Cursor、Aider 或其他 AI coding host，让 agent 在安装或改文件前先问对问题。

有用的 prompt 不是“使用 OpenHands”。更像是：

行动前先复述任务，识别需要哪些工具权限，把只读检查和写操作拆开，任何命令、安装、API 调用或文件写入都先标成需要确认；证据缺失时直接说证据缺失。

这样第一轮交互才不是宣传，而是控制。

一个实用验收清单

真正信任一次 OpenHands session 前，至少要拿到这些证据：

• 选中的 repository 和 branch；
• sandbox id 或状态；
• 使用的 model / LLM profile；
• 可用工具和集成面；
• agent 准备读取或修改的文件；
• agent 准备运行的命令；
• rollback 路径；
• 最终 diff；
• test 或 smoke check 结果；
• 未解决风险。

如果 agent 展示不了这些，它仍然可能有用，但还没有获得无人监督权限的资格。

实用判断

OpenHands 最适合被当成 agent control plane，而不是“魔法开发者”。先给它小而可检查的任务，把 sandbox、repository、integration、secret 和 rollback 边界摆到台面上。只有当证据变好时，再逐步扩大权限。

这就是“让 AI 写代码”和“运营一个 AI coding system”的区别。