用 OpenHands 在本地跑通自主编码智能体：CLI 安装、Ollama 接入与 Docker 沙箱避坑实操

最省事的路线是 uv 临时拉起，不污染全局环境：

# 路线 A：uv 一行起（推荐，无需安装到全局）
uvx --python 3.12 --from openhands-ai openhands

# 路线 B：pip 安装（注意包名带 -ai 后缀）
pip install openhands-ai

# 建议加个 alias
alias oh="uvx --python 3.12 --from openhands-ai openhands"

头一个坑就在包名上：PyPI 上叫 openhands 的是另一个无关项目，装错了自然跑不起来——这是社区反馈里最常见的头回踩坑点，正确包名是 openhands-ai。装完在项目目录里直接运行 openhands（或在项目外用 WORKSPACE_DIR 指定工作区），交互式配置会引导你选模型、填 Key。

命令行够用，但看智能体干活还是 GUI 直观：

# Web GUI：聊天面板 + 文件浏览器 + 实时终端
openhands serve --mount-cwd   # --mount-cwd 把当前目录挂为工作区
# 打开它输出的本地地址（如 http://localhost:3000）

serve 模式会在幕后自动拉起一个 Docker 容器作为沙箱——智能体写的每条命令都在容器里执行，与你的宿主机隔离。浏览器里你能实时看到它改了哪个文件、跑了哪条命令、测试结果如何，出问题时终端输出全部可回看。

OpenHands 底层用 LiteLLM，所以本地 Ollama 就是配一个 OpenAI 兼容端点的事。官方 local-llms 文档给出的 Ollama 启动参数里有一条决定成败：

# 官方 local-llms 文档：上下文长度必须调大
export OLLAMA_CONTEXT_LENGTH=32768
export OLLAMA_HOST=0.0.0.0:11434
export OLLAMA_KEEP_ALIVE=-1
ollama serve        # 前台运行；需要后台用 nohup 或 systemd 托管
ollama pull qwen3.6:35b-a3b

OLLAMA_CONTEXT_LENGTH 是本地跑 OpenHands 的生死线：Ollama 默认 4096 的上下文连 OpenHands 的系统提示都装不下，智能体会表现异常甚至完全不听指挥——官方文档原话是「默认值太小，连系统提示都放不进去」。拉模型前把这行环境变量设好，服务重启才生效。

然后在 GUI 里配连接：Settings 打开 Advanced 开关，Custom Model 填模型 ID（前面必须加 openai/ 前缀），Base URL 填 Ollama 地址，API Key 随便填个非空占位：

# GUI: Settings -> LLM -> 开启 Advanced
#   Custom Model : openai/qwen/qwen3.6-35b-a3b  （前缀 openai/ 必须有）
#   Base URL     : http://host.docker.internal:11434/v1
#   API Key      : local-llm                    （占位即可，非空就行）

本地模型接入的报错大多集中在这三层，按顺序排查：

# 坑 1：容器里访问宿主机不能用 localhost / 127.0.0.1
#        必须用 host.docker.internal
# 坑 2：Linux 上该主机名默认不解析，启动 OpenHands 容器时补：
docker run ... --add-host=host.docker.internal:host-gateway
# 坑 3：UI 设置与环境变量设成同一个值，避免互相覆盖
LLM_MODEL=ollama/qwen2.5-coder:7b
LLM_BASE_URL=http://host.docker.internal:11434
LLM_API_KEY=ollama

这三个坑在社区 issue 里有完整轨迹：症状高度一致——智能体正常启动，头一次模型调用立刻报连接错误。修复顺序永远是：地址改 host.docker.internal、Linux 补 --add-host、UI 与环境变量双写保持一致。第三条是因为历史上 UI 设置曾在某些版本里覆盖环境变量，双写是最稳的姿势。

顺带说清容器架构，后面排查会轻松很多：serve 模式下 OpenHands 本体跑在宿主机，每次会话另起一个 runtime 容器当沙箱，两者通过 Docker API 通信。所以连接问题分属两段——OpenHands 到模型服务的一段（本节的网络三坑），和 OpenHands 到 Docker 的一段（Docker 进程没起、docker.sock 权限不对）。报错信息里带模型名或 HTTP 状态的查前一段，提 docker 或 sandbox 的查后一段，别混在一起猜。

cd 到项目目录启动，把任务描述按「文件 + 症状 + 预期」给足：

# 好提示：文件 + 症状 + 预期行为
Fix the auth bug in src/auth/login.py where JWT tokens
expire immediately. The issue is in the token expiry
calculation. After fixing, run the test suite and make
sure all existing tests pass.

# 差提示：意图模糊，模型只能瞎猜范围
Fix the login.

任务运行时它会自己列计划、改文件、跑测试、看报错、再改——你的角色是审阅每一步的 diff，而不是盯着进度条。发现方向错了立刻打断，用一句话纠正而不是删掉重来。任务完成后先看它的测试是否真的跑过，再人工过一遍关键改动。审阅节奏上建议按「计划批准、中途抽查、收尾细看」三段投入注意力：开始时确认它的计划没有越出任务范围，中途只在关键节点（删文件、改配置、装依赖）介入，收尾时把 diff 从头到尾过一遍——把有限的注意力花在刀刃上，比全程紧盯更可持续。

上下文管理同样影响质量：任务跨多轮推进时，让它在收尾阶段把「做了什么、改了哪些文件、还剩什么没做」写成一段总结存进仓库（或贴进 PR 描述）。这段总结就是你下一次会话的接续点，比翻聊天记录可靠得多。

官方文档在 local-llms 页写得很坦诚：本地模型跑不好，问题多半在模型本身而非配置。社区实测口径如下：

# 现实预期（社区实测口径，随模型迭代更新）
OpenHands + 云 API        内存 8GB    无需 GPU    效果好，按 token 付费
OpenHands + 7B 本地模型   内存 16GB   显存 8GB    能跑，常规划差、循环烧 token
OpenHands + 14B+ 本地     内存 32GB   显存 16GB+  社区报告 qwen2.5-coder-14b-instruct 表现稳定

务实的上线路径是反过来走：先用云 API 把流程跑顺、建立「正常表现」的基准，再切本地模型对比降级程度——而不是一上来就在本地小模型上怀疑配置。官方文档还列了社区验证过工具调用可用的模型（如 qwen2.5-coder-14b-instruct），选型直接从这份清单挑，别凭参数量猜。