OpenHands CLI 命令速查表 - 开源自主编码代理全参数
结对编程型助手要求你逐步批准，OpenHands 想做的是另一件事：接到任务后自己规划、自己执行，把一个完整功能写出来再交给你看。这张表按启动与任务、恢复与无头、运行模式、MCP 管理、配置与安装、交互快捷键分组，讲的正是自主代理落地时最容易翻车的地方——跑崩了怎么续、无头跑怎么防止它无限循环、权限口该放到多松。判断依据是任务是否可验证：能用测试或退出码判断成败的任务适合无头批处理，需要看中间结果判断的必须留在交互模式。什么时候翻它：在 CI 里跑批量重构或修复、给仓库补一整套样板代码、或者做基准测试的自动化循环。与其它代理的差别在于它默认配了沙箱与批准策略，配置集中在 ~/.openhands/config.toml，改模型与沙箱策略只动这一处，不必每次在命令行传参。
典型使用场景
面向想用自主 Agent 在真实仓库里改代码、补测试、处理 Issue 的开发者。OpenHands 与普通对话式 AI 的关键差别在于它会真的执行命令和读写文件，因此运行模式与权限控制比提示词技巧更重要：本表把「启动与任务 / 恢复与无头 / 运行模式 / MCP 管理 / 配置安装 / 交互快捷键」六组分开，其中 --always-approve 与 --headless 决定了它会不会自动动手。
启动与任务 5
openhandsopenhands -t "实现用户认证"openhands -f task.txtopenhands --always-approveopenhands --llm-approve恢复与无头 5
openhands --resumeopenhands --resume --lastopenhands --resume <id>openhands --headless -t "任务"openhands --headless --json运行模式（Web/ACP/Cloud） 5
openhands webopenhands serveopenhands acpopenhands loginopenhands cloud -t "任务"MCP 管理 5
openhands mcp listopenhands mcp add tavilyopenhands mcp enable <name>openhands mcp disable <name>openhands --from-issue <url>配置与安装 5
uv tool install openhands --python 3.12pip install openhands-ai==0.45.0docker pull openhands/runtime:0.45-cpuopenhands --override-with-envscat ~/.openhands/config.toml交互快捷键 5
Ctrl+PEscCtrl+Q/exitopenhands --max-iterations 50参数矩阵
| 参数 | 作用 | 示例 |
|---|---|---|
-t "任务" | 带任务直接运行 | openhands -t "实现用户认证" |
-f task.txt | 从文件读取任务说明 | openhands -f task.txt |
--headless | 无头模式，不进交互界面 | openhands --headless -t "任务" |
--headless --json | 无头且输出 JSON，便于脚本解析 | openhands --headless --json -t "任务" |
--always-approve | 自动批准所有操作（含 yolo 同义） | openhands --always-approve -t "任务" |
--llm-approve | 仅自动批准 LLM 发起的操作 | openhands --llm-approve |
--resume --last | 恢复最近一个会话 | openhands --resume --last |
--max-iterations | 限制最大迭代轮次，防止失控 | openhands --max-iterations 50 |
mcp add / enable | 添加并启用 MCP 服务器 | openhands mcp add tavily |
web / serve | 启动 Web UI / 常驻服务 | openhands web |
--override-with-envs | 用环境变量覆盖配置文件 | openhands --override-with-envs |
Ctrl+P / Esc | 命令面板 / 暂停当前任务 | 交互中按 Esc 中止 |
易错点与避坑指南
现象Agent 修改了不该改的文件，或执行了破坏性命令。
原因使用了 --always-approve（yolo），所有操作免确认。
处置默认保留人工确认；确需自动化时改用 --headless 配合受限环境，并先设 --max-iterations 上限。
现象任务反复循环同一操作直到超出预算。
原因没有设置迭代上限，Agent 在失败路径上不断重试。
处置加 --max-iterations 50 之类上限，让它到点停下。
现象会话中断后任务上下文丢失，只能从头再来。
原因未使用会话恢复。
处置openhands --resume --last 恢复最近会话，或用 --resume <id> 指定。
现象CI 里调用一直等待输入或直接失败。
原因进入了交互模式而非无头模式。
处置用 --headless，输出接 --json 供脚本解析。
现象Agent 无法访问外部信息，任务卡在需要查证的步骤。
原因未挂载对应的 MCP 服务器。
处置openhands mcp add tavily 添加，再 mcp enable <name> 启用。
现象改动的源码没有反映到容器里，重启后又消失。
原因运行环境是隔离沙箱，宿主目录未正确挂载。
处置确认工作目录挂载配置，或改用非沙箱模式直接在本机仓库运行。
排障路径
1先无头跑一遍确认行为
openhands --headless --json -t "为 auth 模块补测试"JSON 输出便于脚本消费，也避免误触发交互。
2设置迭代上限防止失控
openhands --max-iterations 50循环类任务必须设上限，否则可能持续消耗资源。
3恢复中断的会话
openhands --resume --last按 ID 恢复指定会话：openhands --resume <id>。
4排查配置与模型设置
cat ~/.openhands/config.toml含 core / llm / sandbox / planner 四段，改动可用 --override-with-envs 用环境变量覆盖。
5查看已挂载的 MCP 服务器
openhands mcp list确认需要的工具已添加并处于启用状态。
命令示例
接手半途而废的会话：先恢复最近一个
openhands --resume --last适合「刚才那个任务还没跑完」的场景；--last 固定选最近一个会话，同时开着多个任务时容易接错，这时改用 openhands --resume 后跟会话 ID 精确恢复。
任务写进文件，避免长提示词被 shell 转义搞坏
openhands -f task.txt与 openhands -t "实现用户认证" 等价，区别是描述不再经过 shell 解析；任务涉及换行、反引号或特殊字符时尤其该用文件方式。
无头 + JSON：CI 里的结构化结果
openhands --headless -t "task" --json--json 让结果可被脚本解析，CI 不再依赖人类可读日志；再叠加 --max-iterations 50 给迭代轮次封顶，防止代理在流水线里无限循环。
接入 MCP：登记、启用、确认，再按需临时禁用
openhands mcp list
openhands mcp add tavily
openhands mcp enable tavily
openhands mcp disable tavilyadd 只登记不生效，enable 才挂载到会话；list 用来确认当前状态，disable 让某个服务器临时退出本机运行而无需删除再重装。
常见坑与注意事项
- --always-approve 与 --yolo 等价：所有沙箱内操作都免确认，代理一旦误判就会直接动你的文件、装依赖或跑破坏性命令；只在干净工作区与可随时重建的环境里使用。
- --from-issue <url> 会把外部 Issue 内容直接变成任务描述执行，等于让第三方文本驱动本机改动；执行前先确认该 Issue 链接可信，重要仓库先开分支。
- --max-iterations 不设上限时，多步任务在无人值守环境里可能长时间空转并持续消耗 API 额度；无头与 CI 场景务必显式给一个轮次上限。
- pip install openhands-ai==0.45.0 锁死了版本，而 docker pull openhands/runtime:0.45-cpu 的运行时镜像需与之匹配；CLI 与 runtime 版本错配会出现沙箱启动失败等难排查的问题。
- cat ~/.openhands/config.toml 里的配置直接决定 LLM、沙箱与审批行为；带 --override-with-envs 启动时环境变量会盖过文件同名字段，改完配置「没反应」通常就是踩了这一层覆盖。
提示
- OpenHands 定位"自主写整个 repo"，比结对编程更激进；首次跑大任务先用
--resume保留断点，崩了能续。 - 无头批处理用
--headless --json接流水线，配合--max-iterations防止 Agent 无限循环。 - 敏感/生产任务别裸开
--always-approve，至少用--llm-approve或先--headless跑小范围验证。 - 配置集中在
~/.openhands/config.toml（llm/sandbox/planner），改模型与沙箱策略一次到位，不用每次传参。 - 给 Agent 的任务描述要包含验收命令（例如必须让某条测试通过），否则它只能按「看起来完成」收尾。
- 限制它能触及的目录范围比限制工具更有效，先在干净分支上跑，确认无异常再合并。
- MCP 接入的外部工具同样有副作用，接入前先确认每个工具的权限范围与是否需要人工确认。
常见问题
OpenHands 停了半天的任务，怎么接着干而不重开一轮？
用 openhands --resume 回到上一个会话继续：它会把工作区状态和上下文一并接回来。想省掉挑选步骤就加 --last 直接恢复最近一个会话；手上已经有具体会话 ID 时，用 openhands --resume 后跟那个 ID 精确续接，别用 --last 免得接到不相干的旧会话上。
--always-approve 和 --llm-approve 到底差在哪，该怎么选？
--always-approve（等价 --yolo）放开全部确认：任何沙箱内的操作都不再问你，包括代理自己判断需要的那部分。--llm-approve 只对 LLM 主动发起的操作放行，范围更窄、留了一层人工闸门。日常交互开发用 --always-approve 最省心；跑在共享机器或接受外部任务（比如 --from-issue 拉来的 Issue）时，保留人工确认更安全。
无头模式跑出来的东西怎么给 CI 或脚本消费？
关键在 --json。无头执行用 openhands --headless 跑单个任务，加 --json 之后输出是可被解析的结构化结果，脚本不必去刨人类可读的日志。配套的 openhands --headless -t "任务" 用来在命令行直接给任务描述，再加 --max-iterations 50 这类上限防止代理在 CI 里跑飞。
MCP 服务器加完了为什么不生效，还要再做什么？
因为 add 和 enable 是两步。openhands mcp add tavily 只是把服务器登记进来，处于未启用状态；必须再执行 openhands mcp enable tavily 才会被挂到会话里。排查时先用 openhands mcp list 看当前清单和启用状态；如果之后要临时关掉某一个，用 openhands mcp disable 加名字，不必删掉重装。
改了 ~/.openhands/config.toml 还没生效，配置到底按什么顺序被覆盖？
用户级配置在 ~/.openhands/config.toml，按 core / llm / sandbox / planner 分块写。默认它就是最终生效值；一旦加了 --override-with-envs，环境变量会盖过文件里的同名项。排查顺序是先 cat ~/.openhands/config.toml 确认文件里写的是什么，再看启动命令有没有带 --override-with-envs——顺序搞反就会出现「文件改了没反应」的错觉。
由 巧匠 维护
公开更新于 2026年8月21日，内容持续校对官方文档。