openhands本地部署可绕过线上api密钥等障碍，通过docker一键启动（需docker≥24.0且用户加入docker组），挂载持久化路径后访问localhost:3000，配置ollama等免费本地模型，即可执行代码生成、git命令、测试用例等真实开发任务。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
新手直接用 OpenClaw（应为 OpenHands，当前无 OpenClaw 官方项目）上手时，常被线上 API 密钥、付费模型、网络延迟和权限报错卡住，本地部署能绕过这些障碍，快速看到 AI 编程 Agent 的真实行为——比如自动修改代码、执行 git 命令、生成测试用例，而不是只在聊天框里“说”代码。
确认你已具备本地运行前提
先打开终端，执行 docker --version，确保输出 Docker 版本 ≥ 24.0。低于这个版本，【容器沙箱无法挂载宿主机 Docker Socket，后续所有命令执行都会失败】。
再运行 groups，检查输出中是否含 docker。若没有，需先执行 sudo usermod -aG docker $USER → 注销并重新登录，否则 docker run 会因权限拒绝而中断。
拉取并启动 OpenHands 容器
复制粘贴这一行命令，一次性拉取 runtime 和主镜像：
docker pull docker.all-hands.dev/all-hands-ai/runtime:0.39-nikolaik && docker pull docker.all-hands.dev/all-hands-ai/openhands:0.39
接着运行容器（注意：命令中 -v ~/.openhands-state:/.openhands-state 是持久化对话历史的关键路径，删掉会导致每次重启都丢失配置）：
docker run -it --rm --pull=always -e SANDBOX_RUNTIME_CONTAINER_IMAGE=docker.all-hands.dev/all-hands-ai/runtime:0.39-nikolaik -e LOG_ALL_EVENTS=true -v /var/run/docker.sock:/var/run/docker.sock -v ~/.openhands-state:/.openhands-state -p 3000:3000 --add-host host.docker.internal:host-gateway --name openhands-app docker.all-hands.dev/all-hands-ai/openhands:0.39
终端开始滚动日志，出现 INFO: Uvicorn running on http://0.0.0.0:3000 即表示服务就绪。
监控一个或多个 GitCode 仓库的 PR，通过 OpenClaw Gateway 自动执行 AI 审查，发布 PR 评论，并发送钉钉和企业微信通知。
首次访问 Web 界面并配置免费模型
浏览器打开 http://localhost:3000，页面加载后会自动弹出 LLM 配置窗口。
第一步：Provider 下拉菜单里【不要选 OpenAI 或 Anthropic】，这两个需要有效 API Key 且国内直连极不稳定；直接选 Ollama 或 LiteLLM（后者可代理本地 Ollama、vLLM 等）。
第二步：Model 字段填你本地已跑起来的模型名，例如 llama3:8b（前提是已用 ollama pull llama3:8b 下载并运行）；若还没装 Ollama，现在去官网下载安装包，双击安装即可，不用配环境变量。
第三步：API Base URL 填 http://host.docker.internal:11434（Docker 容器内访问宿主机 Ollama 的固定地址），留空 API Key —— Ollama 默认无需密钥。
点击 Save，页面跳转回主界面，左下角状态栏显示 “✅ Connected to LLM” 即配置成功。
发起第一个真实任务验证
点击右上角 “+ New Chat”，输入任务描述，例如：“在当前工作区新建一个 Python 文件 hello.py，内容为 print('Hello, OpenHands!')”。
发送后观察左侧操作流：它会自动创建文件 → 写入内容 → 调用 cat hello.py 验证 → 显示 diff 对比。整个过程不依赖网络请求远程模型，全部在本地完成。
这一步验证了沙箱环境、文件系统读写、命令执行链路全部打通。
