多模型配置：省钱又灵活
OpenHands 通过 LiteLLM 支持几乎所有 LLM 提供商。核心思路：主任务用强模型，子任务用便宜模型。
# config.toml — 多模型配置示例
[llm]
model = "anthropic/claude-sonnet-4-20250514"
api_key = "sk-ant-xxx"
temperature = 0.0
[llm.cheap]
model = "openai/gpt-4o-mini"
api_key = "sk-xxx"
[llm.local]
model = "openai/qwen3-coder:30b"
api_key = "dummy"
base_url = "http://host.docker.internal:11434/v1"
# 指定不同 Agent 用不同模型
[agent.RepoExplorerAgent]
llm_config = "cheap"这样主 Agent 用 Claude Sonnet 做复杂推理，代码搜索子任务用 GPT-4o-mini 省钱。
接入本地模型（Ollama）
不想付 API 费用？本地跑也行：
# 1. 启动 Ollama，设置足够大的上下文窗口
OLLAMA_CONTEXT_LENGTH=32768 OLLAMA_HOST=0.0.0.0:11434 ollama serve
# 2. 拉模型（推荐 Qwen3-Coder 或 Devstral）
ollama pull qwen3-coder:30b
# 3. config.toml 配置
# model = "openai/qwen3-coder:30b"
# base_url = "http://host.docker.internal:11434/v1"
# api_key = "dummy"⚠️ 踩坑点：Ollama 默认 context 只有 4096 token，OpenHands 需要至少 32K。不设 OLLAMA_CONTEXT_LENGTH 会导致各种诡异报错。
Headless 模式：集成到 CI/CD
这是 OpenHands 区别于所有 IDE 工具的杀手级功能——它能在无人值守的环境里跑。
# 在 CI 管道里自动执行任务
openhands --headless -t "分析最近 3 个 commit 的代码质量，输出报告"
# JSON 输出，方便解析
openhands --headless --json -t "检查是否有安全漏洞" > report.json
# 设置预算上限（CI 里必须加）
openhands --headless --max-iterations 30 -t "修复 lint 错误"实战案例——自动修 lint 的 GitHub Action：
name: Auto-fix Lint
on:
push:
branches: [main]
jobs:
lint-fix:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run OpenHands to fix lint
run: |
pip install openhands-ai
openhands --headless --always-approve \
--max-iterations 20 \
-t "运行 eslint，修复所有 auto-fixable 问题，提交修改"
env:
LLM_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
LLM_MODEL: anthropic/claude-sonnet-4-20250514MicroAgent 和扩展生态
OpenHands 有一个扩展仓库（github.com/OpenHands/extensions），包含 38 个 Skills 和 9 个 Plugins：
常用 Skills：
code-review— 自动代码审查docker— Docker 容器管理kubernetes— K8s 操作security— 安全扫描release-notes— 自动生成发版说明frontend-design— 前端设计建议
自定义 MicroAgent：
在项目根目录创建 .openhands_instructions 文件，给 Agent 定制指令：
# 项目规范
- 使用 TypeScript strict 模式
- 所有函数必须有 JSDoc 注释
- 测试覆盖率不得低于 80%
- commit message 遵循 Conventional Commits
- 不使用 any 类型Agent 每次启动都会读这个文件，按照你的规范行事。
安全最佳实践
确认模式
[security]
confirmation_mode = true # 每步操作都要你确认
# 或
security_analyzer = "llm" # 用 LLM 判断操作是否安全三档选择：
- 确认模式：每步手动批准（最安全，适合新手）
- LLM 审查：自动用另一个 LLM 判断操作安全性（推荐）
- 全自动：
--always-approve（仅在你完全信任场景时使用）
Docker 隔离要点
# ✅ 只挂载项目目录
-e SANDBOX_VOLUMES="/home/user/project:/workspace:rw"
# ❌ 永远不要挂载这些
# /home/user/.ssh
# /home/user/.aws
# /etc/passwd
# /var/run/docker.sock（除非是 Docker-in-Docker 场景）Token 预算控制
CI 环境里必须设置硬上限：
[core]
max_iterations = 50 # 最多 50 步
[llm]
num_retries = 3 # API 重试上限
retry_min_wait = 5 # 重试间隔（秒）
retry_max_wait = 60没有上限的 Agent 在遇到解不了的问题时会反复尝试，一晚上能烧掉几十美元 API 费。
团队协作模式（Cloud）
OpenHands Cloud 的 Team 版本支持：
- 多用户共享项目
- RBAC 权限控制
- 集中计费和用量报表
- Slack 集成——在 Slack 里 @Agent 就能触发任务
- Jira/Linear 集成——Issue 自动同步
对于 5 人以上的团队，Cloud Team（$500/月）比每人各自配置 API Key 更划算，也更可控。
