OpenHands 教程：开源自主 AI 编程 agent 接国产模型（2026）

OpenHands 是一款开源、能自主干活的 AI 编程 agent：你用自然语言描述一个需求，它会自己规划步骤、读整个代码库、跨文件改代码、在终端里跑命令、跑测试、修 bug，尽量把一件事从头做到尾。它的前身叫 OpenDevin——当年那个「开源版 Devin」，后来改名 OpenHands 并持续迭代，是 GitHub 上最火的开源 AI 软件工程 agent 之一。和 Goose、OpenCode、Aider 一样，它模型完全自由，只要几步配置就能接 DeepSeek、GLM、Kimi 这些国产模型，或者本地模型。这篇 OpenHands 教程带你从安装、第一次上手，到接国产模型和无头自动化一次跑通。

OpenHands 是什么

OpenHands 由 All-Hands-AI 开源，定位是「自主 AI 软件开发 agent」——不是给你补全几行代码，而是拿到任务后自己拆解、动手、自我验证。它有两种用法：一种是终端里的 CLI，装完一行命令就能用；另一种是带图形界面的 Web 版（用 Docker 起一个本地服务，浏览器打开操作），界面里集成了聊天面板、代码改动 diff、内置 VS Code、终端和 Jupyter。它底层用 LiteLLM 做模型抽象层，因此对接了几十家模型提供商，也能通过 OpenAI 兼容通道接国产模型。想让 AI 自己跑通一个较完整的任务、又想低成本用国产模型的开发者，OpenHands 很值得一试。

安装方式一：CLI 一行装（推荐）

最轻量的用法是 CLI。它需要 Python 3.12+，推荐用 uv（一个快的 Python 包管理器）来跑，省得自己折腾环境。下面几种任选其一：

# 方式 A：用 uvx 一行直接跑（不常驻安装，最省事）
uvx --python 3.12 --from openhands-ai openhands

# 方式 B：用 uv 常驻安装，之后直接敲 openhands
uv tool install openhands --python 3.12

# 方式 C：官方安装脚本（装独立二进制）
curl -fsSL https://install.openhands.dev/install.sh | sh

# 装好后进入你的项目目录，启动
cd /path/to/your/project
openhands

安装方式二：Docker 图形界面版

如果你更喜欢图形界面，可以用 Docker 起一个本地 Web 服务，浏览器打开 http://localhost:3000 操作。图形版把聊天、代码改动、终端、VS Code 都放在一个界面里，直观、适合新手。注意 Docker 镜像名、标签、挂载卷和所需环境变量会随版本变化，下面是示意，实际请以官方安装页最新命令为准：

# 拉起 OpenHands 图形界面版（示意，实际命令以官网为准）
docker run -it --rm --pull=always \
  -p 3000:3000 \
  -v ~/.openhands:/.openhands \
  -v /var/run/docker.sock:/var/run/docker.sock \
  --name openhands \
  ghcr.io/all-hands-ai/openhands:latest

# 启动后浏览器打开：
# http://localhost:3000

第一次上手：设置模型

不管 CLI 还是图形版，第一次运行都要先配模型。CLI 首次启动会走一个交互式设置，问你用哪个提供商、填 API Key、选模型；图形版则在左下角「设置 / Settings」的 LLM 页里配置。要接非 OpenAI 的第三方模型，记得展开「高级 / Advanced」选项，手动填自定义模型名、Base URL 和 API Key。配置会保存在 ~/.openhands/settings.json，之后可以随时回设置里改。

接 DeepSeek：用 openai/ 前缀走兼容通道

国产模型里 DeepSeek 接入最顺——它提供标准的 OpenAI 兼容接口。OpenHands 的做法是：在 LLM 设置里打开「高级」，自定义模型名用 openai/ 前缀，Base URL 指到 DeepSeek 网关，再填上你的 API Key。openai/ 前缀是给 LiteLLM 看的信号，表示「这个地址走 OpenAI 那套接口协议」，于是任何 OpenAI 兼容服务都能这么接。先到 DeepSeek 开放平台申请 API Key，然后按下面三项填：

# 在 OpenHands 设置（LLM → 高级 / Advanced）里填这三项：

# 自定义模型（Custom Model）：加 openai/ 前缀
openai/deepseek-chat

# Base URL（接口地址）：
https://api.deepseek.com/v1

# API Key：
# 填你在 DeepSeek 开放平台申请的 key

# 小贴士：LiteLLM 对 DeepSeek 也有原生前缀，直接写
#   deepseek/deepseek-chat
# 也能路由到 DeepSeek 官方端点（此时无需另填 Base URL）

接 GLM / Kimi / 本地模型

智谱 GLM、月之暗面 Kimi（Moonshot）也都提供 OpenAI 兼容接口，接法和 DeepSeek 完全一样：把模型名换成 openai/对应模型、Base URL 换成对应厂商网关即可。想零 API 费、纯本地跑，可以用 LM Studio 或 Ollama 在本机起一个模型，再把 Base URL 指到本地服务地址。

# 接 GLM（智谱，OpenAI 兼容；网关/模型名以官方文档为准）
#   Custom Model： openai/glm-4.6
#   Base URL：     https://open.bigmodel.cn/api/paas/v4

# 接 Kimi / Moonshot（同理，改模型名和网关）
#   Custom Model： openai/kimi-k2
#   Base URL：     https://api.moonshot.cn/v1

# 本地零成本：先用 Ollama 在本机拉起模型
ollama run qwen2.5
#   然后在 OpenHands 里：
#   Custom Model： openai/qwen2.5
#   Base URL：     http://localhost:11434/v1

无头模式：跑自动化与 CI

OpenHands 的 CLI 支持无头（headless）用法：不进交互界面，直接把一条任务丢进去，跑完就退出，特别适合写脚本、接 CI/CD。用 -t 直接传任务文本即可。注意具体旗标名可能随版本微调，以 openhands --help 为准。

# 无头执行一条任务，跑完退出（旗标以 openhands --help 为准）
openhands -t "给这个仓库的 README 补一段安装与使用说明，并提交改动"

# 查看全部可用参数
openhands --help

OpenHands 和 Goose、OpenCode、Aider 怎么比

它们都是「用 AI 帮你改代码」的开源工具，并不冲突——完全可以都装、按任务和预算混着用。OpenHands 的差异点在于自主性更强、图形界面功能更全，适合把一个较完整的任务整体交给它跑；追求纯终端轻量的可以配 Goose、OpenCode、Aider。想了解这些工具各自怎么接国产模型、怎么用，站内都有对应实测教程。

OpenHands 把「让 AI 自主跑通一件事」做得很彻底，接国产模型也只是几步配置。但 agent 越自主，越考验你会不会拆需求、审代码、盯住它别跑偏——把 AI 的产出稳定用进真实项目，才是真正拉开差距的地方。想系统掌握用 AI 工具做出能交付产品的方法，欢迎来 IMAI 看看我们的体系化实战课程。