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。更稳的第一次运行应该很无聊：
- 使用临时仓库或 disposable branch。
- 选择一个预期 diff 很清楚的小 issue。
- 不提供真实生产 secret。
- 记录 repository、branch、sandbox 和 model profile。
- 编辑前先要求 plan 和拟修改文件列表。
- 完成前必须跑 test 或 smoke check。
- 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”的区别。
浙公网安备 33010602011771号