OpenHands 1.0 搭建指南：开源自主编程 Agent 从安装到实战

1# 验证 Docker 是否安装且版本 ≥ 20.10
2docker --version
3# 期望输出：Docker version 24.0.x 或更高
4
5# 验证 Docker Compose（v2 已内置在 Docker Desktop 中）
6docker compose version
7# 期望输出：Docker Compose version v2.20+
8
9# 验证 Docker 守护进程运行正常
10docker info

1# Linux：将当前用户加入 docker 组（需重新登录生效）
2sudo usermod -aG docker $USER
3
4# 验证免 sudo
5docker ps

1# 一键启动（Docker run 方式，最简形式）
2docker run -it \
3  --pull=always \
4  -e OPENHANDS_API_KEY="sk-your-anthropic-key" \
5  -e OPENHANDS_MODEL="anthropic/claude-sonnet-4-5" \
6  -v /var/run/docker.sock:/var/run/docker.sock \
7  -v /path/to/workspace:/workspace \
8  -p 3000:3000 \
9  --add-host host.docker.internal:host-gateway \
10  --name openhands-app \
11  ghcr.io/opendevin/openhands:1.0

1# 创建工作目录
2mkdir -p ~/openhands && cd ~/openhands
3
4# 写入 .env（注意权限 600）
5cat > .env <<EOF
6# ============ LLM 配置 ============
7OPENHANDS_API_KEY=sk-your-anthropic-key
8OPENHANDS_MODEL=anthropic/claude-sonnet-4-5
9OPENHANDS_BASE_URL=https://api.anthropic.com
10OPENHANDS_MAX_TOKENS=8192
11
12# ============ Agent 行为 ============
13OPENHANDS_MAX_ITERATIONS=500
14OPENHANDS_TIMEOUT=1200
15
16# ============ 沙箱安全 ============
17SANDBOX_TIMEOUT=60
18SANDBOX_MEMORY_LIMIT_MB=2048
19SANDBAX_CPU_LIMIT=1.0
20SANDBOX_NETWORK_ISOLATED=false
21
22# ============ Web UI ============
23OPENHANDS_HOST=0.0.0.0
24OPENHANDS_PORT=3000
25EOF
26
27chmod 600 .env

1docker run -d \
2  --pull=always \
3  --env-file ~/openhands/.env \
4  -v /var/run/docker.sock:/var/run/docker.sock \
5  -v ~/openhands/workspace:/workspace \
6  -v ~/openhands/.openhands:/app/.openhands \
7  -p 3000:3000 \
8  --add-host host.docker.internal:host-gateway \
9  --name openhands-app \
10  --restart unless-stopped \
11  ghcr.io/opendevin/openhands:1.0

1# ~/openhands/compose.yaml
2services:
3  openhands:
4    image: ghcr.io/opendevin/openhands:1.0
5    pull_policy: always
6    container_name: openhands-app
7    restart: unless-stopped
8    environment:
9      - OPENHANDS_API_KEY=${OPENHANDS_API_KEY}
10      - OPENHANDS_MODEL=${OPENHANDS_MODEL}
11      - OPENHANDS_BASE_URL=${OPENHANDS_BASE_URL:-https://api.anthropic.com}
12      - OPENHANDS_MAX_ITERATIONS=500
13      - SANDBOX_TIMEOUT=60
14      - SANDBOX_MEMORY_LIMIT_MB=2048
15      - SANDBOX_CPU_LIMIT=1.0
16      - SANDBOX_NETWORK_ISOLATED=false
17    volumes:
18      - /var/run/docker.sock:/var/run/docker.sock
19      - ./workspace:/workspace
20      - ./.openhands:/app/.openhands
21    ports:
22      - "3000:3000"
23    extra_hosts:
24      - "host.docker.internal:host-gateway"
25    healthcheck:
26      test: ["CMD", "curl", "-f", "http://localhost:3000/health"]
27      interval: 30s
28      timeout: 10s
29      retries: 3

1cd ~/openhands
2docker compose up -d
3
4# 查看启动日志
5docker compose logs -f openhands
6# 看到 "Uvicorn running on http://0.0.0.0:3000" 表示启动成功
7
8# 健康检查
9curl http://localhost:3000/health
10# 期望：{"status":"ok"}

1# Compose 方式
2cd ~/openhands
3docker compose pull
4docker compose up -d
5
6# docker run 方式
7docker stop openhands-app && docker rm openhands-app
8docker pull ghcr.io/opendevin/openhands:1.0
9# 重新执行之前的 docker run 命令

1git clone https://github.com/All-Hands-AI/OpenHands.git
2cd OpenHands
3git checkout v1.0.0   # 切到 1.0 稳定 tag
4
5# 查看当前版本
6cat VERSION
7# 期望输出：1.0.0

1brew install python@3.12 node@20 pnpm
2curl -sSL https://install.python-poetry.org | python3 -
3echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
4source ~/.zshrc
5
6# 验证
7python3 --version        # Python 3.12.x
8poetry --version         # Poetry (version 1.8.x)
9node --version           # v20.x
10pnpm --version           # 9.x

1# Python 3.12
2sudo add-apt-repository ppa:deadsnakes/ppa -y
3sudo apt update && sudo apt install -y python3.12 python3.12-venv python3.12-dev
4
5# Poetry
6curl -sSL https://install.python-poetry.org | python3.12 -
7
8# Node.js 20
9curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
10sudo apt install -y nodejs
11sudo npm install -g pnpm
12
13# 验证
14python3.12 --version && poetry --version && node --version && pnpm --version

1# 在 WSL2 Ubuntu 中
2sudo apt update && sudo apt install -y python3.12 python3-pip
3curl -sSL https://install.python-poetry.org | python3 -
4curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
5sudo apt install -y nodejs
6sudo npm install -g pnpm

1cd OpenHands
2
3# 配置 Poetry 用 Python 3.12
4poetry env use python3.12
5
6# 安装依赖（含开发依赖，方便后续跑测试和构建插件）
7poetry install
8
9# 验证安装
10poetry run python -c "import openhands; print(openhands.__version__)"
11# 期望输出：1.0.0

1poetry source add -p default tuna https://pypi.tuna.tsinghua.edu.cn/simple
2poetry install

1cd frontend
2pnpm install
3pnpm run build:fe
4# 产物输出到 frontend/dist/
5
6cd ..

1# ========================================
2# OpenHands 1.0 配置文件
3# ========================================
4
5# ---------- LLM 配置 ----------
6[llm]
7model = "anthropic/claude-sonnet-4-5"
8api_key = "sk-your-anthropic-key"
9base_url = "https://api.anthropic.com"
10max_tokens = 8192
11temperature = 0.0
12timeout = 600
13
14# 多供应商配置（按需启用）
15[llm.openai]
16model = "gpt-5"
17api_key = "sk-your-openai-key"
18base_url = "https://api.openai.com/v1"
19
20[llm.deepseek]
21model = "deepseek/deepseek-chat"
22api_key = "sk-your-deepseek-key"
23base_url = "https://api.deepseek.com/v1"
24
25[llm.ollama]
26model = "ollama/qwen3-32b"
27api_base = "http://localhost:11434/v1"
28api_key = "ollama-no-key-needed"
29
30# ---------- Agent 行为 ----------
31[agent]
32max_iterations = 500
33max_steps_per_iter = 50
34timeout_seconds = 1200
35retry_delay_seconds = 5
36
37# 自定义系统提示词
38system_prompt = """
39You are OpenHands, an autonomous coding agent.
40When solving tasks:
411. Always explore the repo structure before making changes.
422. Write tests for new features.
433. Run tests after every change to verify.
444. Prefer minimal, surgical edits over large rewrites.
45"""
46
47# ---------- 沙箱安全策略 ----------
48[sandbox]
49timeout_seconds = 60
50memory_limit_mb = 2048
51cpu_limit = 1.0
52network_isolated = false    # true 时禁用容器外网
53use_sysbox = false          # true 时用 Sysbox runtime，更安全
54
55# 命令白名单（仅允许列表内的 shell 命令执行）
56# 留空 = 全部允许
57allowed_commands = [
58  "ls", "cat", "grep", "find", "pwd", "echo", "head", "tail", "wc",
59  "git", "npm", "pnpm", "yarn", "python", "python3", "pip", "poetry",
60  "go", "cargo", "make", "cmake", "gcc", "g++", "rustc",
61  "node", "tsc", "eslint", "prettier", "jest", "pytest", "ruff",
62  "curl", "wget", "ssh-keygen"
63]
64
65# 禁止执行的命令（黑名单优先级高于白名单）
66blocked_commands = [
67  "rm -rf /", "mkfs", "dd if=", ":(){:|:&};:",
68  "shutdown", "reboot", "halt", "poweroff"
69]
70
71# ---------- Web UI ----------
72[web]
73host = "0.0.0.0"
74port = 3000
75# 启用身份认证（生产环境强烈建议开启）
76enable_auth = true
77auth_type = "token"   # token | oidc | basic
78jwt_secret = "your-random-32-byte-secret-here"
79
80# ---------- 文件存储 ----------
81[storage]
82# 对话历史、Agent 状态持久化目录
83base_dir = "~/.openhands/storage"
84# 单个会话最大保留天数
85max_session_age_days = 30
86
87# ---------- 插件系统 ----------
88[plugins]
89enabled = true
90search_paths = [
91  "./plugins",
92  "~/.openhands/plugins"
93]
94# 默认启用的插件
95auto_load = [
96  "filesystem-tools",
97  "git-helper",
98  "browser-automation"
99]

1# 1) 启动后端 API + WebSocket 服务
2poetry run openhands serve \
3  --config ./config.toml \
4  --port 3000 \
5  --host 0.0.0.0
6
7# 2) 另起一个终端，启动前端开发服务器（开发模式，热重载）
8cd frontend
9pnpm run dev
10# 开发服务器跑在 http://localhost:3001，会代理到后端 3000

1# 一条命令同时起后端 + 提供前端静态文件
2poetry run openhands serve \
3  --config ./config.toml \
4  --port 3000 \
5  --host 0.0.0.0 \
6  --static-frontend ./frontend/dist

1# 单次任务：让 Agent 修复一个 issue
2poetry run openhands run \
3  --task "Fix the failing test in tests/test_auth.py::test_login_invalid_password. The test expects a 401 but the endpoint returns 200." \
4  --workspace ./my-project \
5  --max-iterations 100 \
6  --model "anthropic/claude-sonnet-4-5" \
7  --no-interactive
8
9# 头对头模式（Human + Agent 交互，适合人工接管）
10poetry run openhands run \
11  --task "Refactor the user service to use dependency injection" \
12  --workspace ./my-project \
13  --interactive

1# Docker 方式
2curl -fsS http://localhost:3000/health
3# 期望：{"status":"ok"}
4
5# 源码方式
6curl -fsS http://localhost:3000/api/health
7# 期望：{"status":"healthy","version":"1.0.0"}

1# Docker
2docker logs openhands-app --tail 100
3
4# 源码
5poetry run openhands logs --tail 100

1# 测试 LLM 连通性（源码方式提供，Docker 方式进容器执行）
2poetry run openhands doctor
3# 会输出 LLM ping、Docker ping、磁盘空间、内存等检查结果

1cat ~/openhands/workspace/hello.txt
2# 期望：Hello from OpenHands 1.0

1# 在 Agent 会话里发消息：
2请在终端执行 hostname && cat /etc/os-release | head -5

1docker ps --filter "name=openhands-runtime"
2# 期望看到一个名为 openhands-runtime-xxxxx 的容器在运行

1# Docker 方式：进容器执行
2docker exec -it openhands-app openhands plugins list
3
4# 源码方式
5poetry run openhands plugins list
6
7# 期望输出：
8# Loaded plugins:
9#   - filesystem-tools (v1.0.0) [loaded from /app/plugins/filesystem-tools]
10#   - git-helper (v1.0.0) [loaded from /app/plugins/git-helper]
11#   - browser-automation (v1.0.0) [loaded from /app/plugins/browser-automation]

1任务：修复 issue #142
2
3仓库根目录 /workspace/my-flask-app，下面是 issue 描述：
4
5"POST /api/users 返回 201 但响应体里缺少 Location header，
6导致前端拿不到新创建资源的 URI。期望行为：响应带 Location: /api/users/<id>。"
7
8要求：
91. 先阅读 app/routes/users.py 和 tests/test_users.py，理解现状
102. 复现问题：写一个失败测试
113. 修复代码
124. 跑 pytest 验证测试通过
135. 用 git 提交（commit message 用 conventional commits 格式）

1任务：从零搭建一个 Express + TypeScript 的待办事项 REST API
2
3要求：
41. 工作目录 /workspace/todo-api，目前为空
52. 技术栈：Express 5 + TypeScript 5 + Prisma + SQLite + Zod
63. 实现 5 个端点：GET /tasks, POST /tasks, GET /tasks/:id, PATCH /tasks/:id, DELETE /tasks/:id
74. 用 Zod 做请求体校验
85. 用 Prisma 做 ORM，SQLite 文件存储
96. 写 Vitest 单元测试覆盖所有端点
107. 在 README.md 写启动说明
118. 最后跑 npm test 验证全部通过

1任务：审查并重构 /workspace/legacy/app.py
2
3要求：
41. 阅读 app.py 全文，找出代码坏味道
52. 列出 3-5 个最严重的问题（用 markdown 列表）
63. 按问题严重度从高到低重构，每改一处就跑一次测试
74. 重构后跑 flake8 和 mypy，确保 0 错误 0 警告
85. 写一个 REFACTORING.md 说明每处改动的 before/after

1任务：为 /workspace/my-service 补充单元测试，目标行覆盖率 80%
2
3要求：
41. 跑 coverage 报告，找出当前覆盖率低于 60% 的模块
52. 优先补 3 个最关键模块的测试：auth、payment、notification
63. 每个模块写 5+ 测试用例，覆盖正常路径 + 边界 + 异常
74. 用 pytest + pytest-mock，避免依赖外部服务
85. 跑 pytest --cov=my_service，确认总覆盖率 ≥ 80%
96. 把测试结果写到 TEST_REPORT.md

1[sandbox]
2network_isolated = true
3# Agent 无法访问外网，只能操作沙箱内文件
4# 适合处理含敏感数据的私有代码库

1[sandbox]
2memory_limit_mb = 2048   # 单会话内存上限 2GB
3cpu_limit = 1.0          # 单会话最多用 1 核
4timeout_seconds = 60      # 单条命令最长执行 60 秒

1[sandbox]
2# 只允许 Agent 执行这些命令，其他一律拒绝
3allowed_commands = [
4  "ls", "cat", "grep", "find", "pwd",
5  "git", "python", "pytest", "ruff",
6  "npm", "node", "tsc", "jest"
7]
8blocked_commands = [
9  "rm -rf /", "mkfs", "dd",
10  "curl", "wget",   # 禁止外发请求
11  "shutdown", "reboot"
12]

1# 安装 Sysbox
2wget https://downloads.nestybox.com/sysbox/releases/v0.6.x/sysbox-ce-v0.6.x-linux.tar.gz
3tar -xzf sysbox-ce-v0.6.x-linux.tar.gz
4cd sysbox-ce-v0.6.x && sudo ./install.sh
5
6# 注册 sysbox runtime
7docker info | grep -i runtime
8# 应能看到 sysbox-runc
9
10# 启动 OpenHands 时用 sysbox runtime
11docker run -d \
12  --runtime=sysbox \
13  --env-file ~/openhands/.env \
14  -v ~/openhands/workspace:/workspace \
15  -p 3000:3000 \
16  --name openhands-app \
17  ghcr.io/opendevin/openhands:1.0

1plugins/
2  browser-automation/
3    __init__.py
4    plugin.py          # 插件主入口
5    manifest.toml      # 元信息
6    tools/
7      __init__.py
8      browser.py

1from openhands.plugins import Plugin, tool
2
3class BrowserAutomationPlugin(Plugin):
4    """浏览器自动化插件，让 Agent 能驱动 headless Chrome"""
5
6    name = "browser-automation"
7    version = "1.0.0"
8
9    @tool(description="Open a URL in headless Chrome and return the page HTML")
10    def open_url(self, url: str, wait: int = 5) -> str:
11        """
12        :param url: The URL to navigate to
13        :param wait: Seconds to wait for page to load
14        :return: Page HTML content
15        """
16        from selenium import webdriver
17        from selenium.webdriver.chrome.options import Options
18
19        options = Options()
20        options.add_argument("--headless")
21        options.add_argument("--no-sandbox")
22        driver = webdriver.Chrome(options=options)
23        driver.get(url)
24        driver.implicitly_wait(wait)
25        html = driver.page_source
26        driver.quit()
27        return html
28
29    @tool(description="Take a screenshot of a URL")
30    def screenshot(self, url: str, output_path: str) -> str:
31        """Save a screenshot of the URL to output_path"""
32        # ... 实现
33        return f"Screenshot saved to {output_path}"

1[plugin]
2name = "browser-automation"
3version = "1.0.0"
4description = "Browser automation tools for OpenHands agents"
5author = "AIToolSchool"
6license = "MIT"
7
8[dependencies]
9python = ["selenium>=4.0", "webdriver-manager>=4.0"]

1[plugins]
2enabled = true
3search_paths = ["./plugins", "~/.openhands/plugins"]
4auto_load = ["filesystem-tools", "git-helper", "browser-automation"]

1[resource_management]
2# 单会话上限
3max_sessions_per_user = 3
4max_concurrent_sessions = 10
5session_timeout_minutes = 60
6
7# 单会话配额
8session_token_budget = 500_000        # 单会话最多消耗 50 万 token
9session_token_budget_action = "stop"  # 超额后停止 Agent

1[agent]
2# 主 Agent 负责任务分解和调度
3default_agent = "codeact"
4
5[agent.subagents]
6# 子 Agent 配置
7planner = { model = "anthropic/claude-opus-4", max_iterations = 50 }
8coder = { model = "anthropic/claude-sonnet-4-5", max_iterations = 200 }
9reviewer = { model = "openai/gpt-5", max_iterations = 100 }

1@planner 请把这个需求拆成 3 个子任务
2@coder 实现第二个子任务
3@reviewer 审查刚才的改动

1[agent]
2system_prompt = """
3You are OpenHands, an autonomous coding agent working in a sandboxed Docker container.
4
5# 行为准则
6- 始终先探索代码库结构再动手
7- 写代码必须配测试
8- 每次改动后立即跑测试验证
9- 优先用最小改动解决问题，避免大规模重构
10- 不确定时主动提问，不要瞎猜
11
12# 安全边界
13- 绝不删除未在 git 中的文件
14- 不修改 .env / secrets / credentials 类文件
15- 不执行 rm -rf 或类似危险命令
16- 不向外部 API 发送项目源码
17
18# 输出规范
19- 每个改动说明 before/after
20- 用 conventional commits 格式
21- 测试失败必须修复，不能跳过
22"""

1[agent.context]
2# 启用自动压缩历史
3compress_enabled = true
4# 超过 50% 上下文窗口时触发压缩
5compress_threshold_ratio = 0.5
6# 压缩后保留最近 20 轮对话原文
7keep_recent_turns = 20

1[llm.cache]
2enabled = true
3backend = "redis"   # redis | sqlite | memory
4redis_url = "redis://localhost:6379/0"
5ttl_seconds = 86400

1[agent]
2parallel_tool_calls = true
3max_parallel_tools = 4

1[router]
2enabled = true
3rules = [
4  { if = "complexity == 'high'", model = "anthropic/claude-opus-4" },
5  { if = "complexity == 'medium'", model = "anthropic/claude-sonnet-4-5" },
6  { if = "complexity == 'low'", model = "deepseek/deepseek-chat" }
7]

1curl http://localhost:3000/metrics
2# openhands_sessions_total{status="active"} 3
3# openhands_llm_tokens_total{provider="anthropic",type="input"} 124532
4# openhands_llm_cost_usd_total{provider="anthropic"} 1.87
5# openhands_sandbox_memory_usage_bytes{session="abc123"} 536870912

1services:
2  prometheus:
3    image: prom/prometheus:latest
4    ports:
5      - "9090:9090"
6    volumes:
7      - ./prometheus.yml:/etc/prometheus/prometheus.yml

1# prometheus.yml
2scrape_configs:
3  - job_name: "openhands"
4    static_configs:
5      - targets: ["openhands:3000"]
6    metrics_path: /metrics

1[logging]
2level = "INFO"
3format = "json"
4output = ["stdout", "file"]
5file_path = "/var/log/openhands/openhands.log"
6max_file_size_mb = 100
7max_files = 7

1[audit]
2enabled = true
3log_path = "/var/log/openhands/audit.log"
4# 记录每一次文件操作、命令执行、网络请求
5log_tool_calls = true
6log_llm_calls = true

1[sandbox]
2# 网络默认隔离
3network_isolated = true
4
5# 命令白名单（生产环境强约束）
6allowed_commands = ["ls", "cat", "grep", "find", "git", "python", "pytest"]
7
8# 资源上限
9memory_limit_mb = 1024
10cpu_limit = 0.5
11timeout_seconds = 30
12
13[agent]
14# 限制单会话最多执行 100 步，防止失控
15max_iterations = 100
16# 单会话最多花 $5
17cost_budget_usd = 5.0
18cost_budget_action = "stop"

1[agent.file_guard]
2protected_paths = [
3  ".env",
4  ".env.*",
5  "secrets/**",
6  "**/*.pem",
7  "**/*.key",
8  "credentials.json",
9  "**/id_rsa"
10]
11action = "deny"   # deny | ask

1[sandbox.network]
2allowed_domains = [
3  "api.anthropic.com",
4  "api.openai.com",
5  "pypi.org",
6  "registry.npmjs.org",
7  "github.com"
8]

1[web]
2enable_auth = true
3auth_type = "oidc"   # 接企业 SSO
4oidc_client_id = "openhands"
5oidc_client_secret = "${OIDC_CLIENT_SECRET}"
6oidc_discovery_url = "https://sso.example.com/.well-known/openid-configuration"

1# .github/workflows/openhands-review.yml
2name: OpenHands Code Review
3
4on:
5  pull_request:
6    types: [opened, synchronize]
7
8jobs:
9  review:
10    runs-on: ubuntu-latest
11    steps:
12      - uses: actions/checkout@v4
13        with:
14          fetch-depth: 0
15
16      - name: Run OpenHands review
17        env:
18          OPENHANDS_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
19        run: |
20          docker run --rm \
21            -e OPENHANDS_API_KEY \
22            -e OPENHANDS_MODEL="anthropic/claude-sonnet-4-5" \
23            -v ${{ github.workspace }}:/workspace \
24            -v /var/run/docker.sock:/var/run/docker.sock \
25            ghcr.io/opendevin/openhands:1.0 \
26            openhands run \
27              --task "Review the changes in this PR. Check for: bugs, security issues, performance, style. Output a markdown review comment." \
28              --workspace /workspace \
29              --no-interactive \
30              --max-iterations 50 \
31              --output-format markdown > review.md
32
33      - name: Post review as PR comment
34        uses: marocchino/sticky-pull-request-comment@v2
35        with:
36          path: review.md

1[mcp.servers.filesystem]
2command = "npx"
3args = ["-y", "@modelcontextprotocol/server-filesystem", "/workspace"]
4
5[mcp.servers.github]
6command = "npx"
7args = ["-y", "@modelcontextprotocol/server-github"]
8env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

1[notifications.slack]
2enabled = true
3webhook_url = "${SLACK_WEBHOOK_URL}"
4events = ["task_completed", "task_failed", "cost_threshold_reached"]
5
6[notifications.feishu]
7enabled = true
8webhook_url = "${FEISHU_WEBHOOK_URL}"
9events = ["task_completed"]

1# Dockerfile.runtime
2FROM ghcr.io/opendevin/openhands-runtime:1.0
3
4# 烤入项目常用依赖
5RUN apt-get update && apt-get install -y \
6    libpq-dev gdal-bin \
7    && rm -rf /var/lib/apt/lists/*
8
9# 预装 Python 包
10COPY requirements.txt /tmp/
11RUN pip install --no-cache-dir -r /tmp/requirements.txt
12
13# 预装 npm 全局包
14RUN npm install -g typescript tsx vitest @types/node

1docker build -t my-openhands-runtime:1.0 -f Dockerfile.runtime .
2
3# 启动 OpenHands 时指定
4docker run -d \
5  -e OPENHANDS_RUNTIME_IMAGE=my-openhands-runtime:1.0 \
6  ...其他参数