OpenHands安装教程2026：把83k星编程智能体跑在自己机器上

OpenHands号称全自主编程智能体，但安装文档默认你已经懂Docker、沙盒和模型配置。这里是从零到跑通的完整步骤。

💡 你将学到

OpenHands号称全自主编程智能体，但安装文档默认你已经懂Docker、沙盒和模型配置。这里是从零到跑通的完整步骤。

📜 目录

• OpenHands是什么
• 前置条件
• 安装步骤
• 排错
• FAQ
• 相关文章

OpenHands是什么

OpenHands（GitHub 83,725星，2026-08-12获取）是一个AI软件开发智能体：写代码、在沙盒里执行、迭代直到任务完成。核心循环是——接任务、规划、改文件、跑命令、读输出、再试。这个循环就是它需要Docker的原因：沙盒是代码真正运行的地方。

前置条件

装了Docker的机器（Linux、macOS或Windows的WSL2）、至少8GB内存（16GB更舒服）、一个LLM API密钥（OpenAI、Anthropic、DeepSeek或任何OpenAI兼容端点都行）。

安装步骤

第一步装Docker：Linux用官方脚本，Windows装Docker Desktop并启用WSL2后端，用docker run hello-world验证。

第二步拉镜像并启动：docker pull docker.all-hands.dev/all-hands-ai/openhands:0.37，然后设置LLM_API_KEY环境变量，挂载docker.sock和状态目录，映射3000端口启动容器。浏览器打开localhost:3000就能看到界面。

第三步配模型：设置里选供应商和模型。两个实用默认：DeepSeek（便宜、代码能力强、OpenAI兼容）；Anthropic Claude（预算够就要最强推理）。本地模型就把base URL指向同一台机器的Ollama。

第四步给个真任务：从一个有边界的小任务开始，比如'写一个抓取Hacker News前5条新闻存成markdown的Python脚本'。观察它怎么规划、写码、运行、修复。会自己读报错并改正——这个自纠循环就是它的全部意义。

排错

沙盒起不来：重拉runtime镜像，tag要跟OpenHands版本匹配。连不上模型：查base URL，容器里访问本地Ollama要用host.docker.internal而不是localhost。第一次任务慢：首次使用要下载runtime镜像，之后就快了。

FAQ

免费吗？ 软件开源（MIT），你只付LLM API调用费。 会搞坏仓库吗？ 默认在沙盒里工作，仓库任务用GitHub集成、合并前审查PR。 一个任务烧多少调用？ 小任务20-50次，复杂功能几百次，界面里能看用量。

相关文章

• One API（3.6万星）大模型网关搭建指南2026：一个Key打通OpenAI、Claude、Gemini和DeepSeek
• Windows本地LLM环境搭建完全教程：Ollama / LM Studio / GPT4All 三方案对比
• OpenRouter教程：一个API Key用所有LLM

❓ 常见问题

Is OpenHands free?

The software is open source (MIT license). You pay only for the LLM API calls and your machine's electricity.

Can it damage my repo?

It works in a sandbox by default. For repo work, use the GitHub integration and review pull requests before merging.

How many API calls does a task use?

small task can be 20-50 calls; a complex feature can be several hundred. Track your usage in the UI.