项目概述与系统架构

OpenHands 是一个自托管的开发者控制中心（Agent Canvas），用于运行编码代理与自动化任务，能够在本地、远程及云端后端统一调度 OpenHands、Claude Code、Codex、Gemini 以及任何 ACP 兼容的代理。资料来源：README.md:1-15

项目定位与核心目标

OpenHands 将编码代理转变为始终在线的自托管工程团队，核心项目含：

• 灵活自托管：可在本地、Docker、虚拟机或任何能运行代理服务器后端的环境中部署 资料来源：README.md:17-23
• 多后端切换：在本地、远程与云端代理之间无缝切换而不丢失工作上下文 资料来源：README.md:25-29
• 自动化工作流：创建与 Slack、GitHub、Linear 等服务集成的自动化流程 资料来源：README.md:31-35

最新版本 1.8.0（2026-06-10）新增了 LLM 配置文件、子代理委派、沙箱分组策略选择以及最小通用 ACP 代理 UI 等能力。资料来源：releases/tag/1.8.0

系统架构组件

OpenHands 采用模块化分层架构，主要由以下核心组件构成：

1. App Server（应用服务器）

基于 FastAPI 的应用服务器，为 OpenHands V1 集成提供 REST API 端点，统一管理对话、沙箱、事件与用户设置。资料来源：openhands/app_server/README.md:1-10

主要子模块职责：

• app_conversation/：管理沙箱化对话及其生命周期，对应 V1AppConversation、V1AppConversationStartTask 等类型 资料来源：frontend/src/api/conversation-service/v1-conversation-service.types.ts:1-30
• sandbox/：管理代理执行的沙箱环境，对应 V1SandboxStatus 状态枚举（MISSING / STARTING / RUNNING / PAUSED / ERROR）资料来源：frontend/src/api/sandbox-service/sandbox-service.types.ts:1-15
• event/：处理事件存储、检索与流式传输
• event_callback/：管理 webhook 与事件回调 资料来源：openhands/app_server/event_callback/README.md:1-15
• git/ 与 settings/：提供 Git 集成与用户/应用设置端点

2. Frontend（前端）

前端基于 Remix SPA 模式（React + Vite + React Router）构建，使用 TypeScript、Redux、TanStack Query、Tailwind CSS 与 i18next，并通过 WebSocket 实现实时更新。资料来源：frontend/README.md:11-19

测试栈包括 Vitest、React Testing Library、@testing-library/user-event 与 MSW（Mock Service Worker）。资料来源：frontend/README.md:25-35

通用类型集中在 open-hands.types.ts，例如 GitChangeStatus、V1GitChangeStatus 与 Microagent 等。资料来源：frontend/src/api/open-hands.types.ts:1-30

3. Skills / Microagents 技能系统

技能系统为代理注入可重用的专业知识，包含两类代理：

• 知识代理（Knowledge Agents）：存放于 skills/ 目录，可被多项目复用 资料来源：skills/README.md:11-25
• 仓库代理（Repository Agents）：存放于 .openhands/microagents/（V0）或 .openhands/skills/（V1），针对具体项目自动激活 资料来源：skills/README.md:26-35

4. UI 组件库（openhands-ui）

独立的 UI 组件库，遵循 MIT 协议，推荐使用 Bun 进行开发，构建产物可通过 bun pm pack 生成本地包用于其他项目。资料来源：openhands-ui/README.md:1-30

5. Enterprise 部署

企业版提供 Keycloak 认证、外部服务集成（GitHub、Slack、Jira）以及维护任务处理器。资料来源：enterprise/doc/architecture/README.md:1-15

维护任务系统用于运行后台维护操作（如升级用户设置、清理数据），任务设计为短时运行（通常一分钟以内），不会阻塞部署流程。资料来源：enterprise/server/maintenance_task_processor/README.md:1-15

系统数据流架构

graph TB
    User[用户] --> Frontend[Frontend<br/>Remix SPA + React]
    Frontend -->|REST/WebSocket| AppServer[App Server<br/>FastAPI]
    AppServer --> Conv[对话管理<br/>app_conversation/]
    AppServer --> Sbx[沙箱管理<br/>sandbox/]
    AppServer --> Evt[事件系统<br/>event/]
    AppServer --> GitSvc[Git 集成<br/>git/]
    Sbx --> Agent[代理后端<br/>Docker/VM/Cloud]
    Agent --> SDK[OpenHands Agent SDK]
    AppServer --> Skills[Skills/Microagents]
    Enterprise[Enterprise] -->|Keycloak| AppServer
    Enterprise -->|Webhook| Integrations[GitHub/Slack/Jira]

扩展机制与配置

OpenHands 通过 get_impl 与 import_from 函数（位于 import_utils.py）提供运行时实现替换能力，允许上层应用通过继承基类并实现所有抽象方法来定制行为。资料来源：openhands/app_server/utils/README.md:1-30

前端关键环境变量包括 VITE_BACKEND_BASE_URL、VITE_USE_TLS 与 VITE_MOCK_API 等。资料来源：frontend/README.md:55-70

已知问题与社区关注

根据社区反馈，以下问题与需求对架构使用影响较大：

• LLM 配置文件覆盖 Bug：编辑一个 LLM 配置文件会覆盖其他配置文件的模型与 api_key 资料来源：issues/14800
• 内置浏览器异常：WebUI 内置浏览器无法正常渲染被测 Web 应用 资料来源：issues/14569
• agent-server 沙箱启动失败：Chromium 缺少 --no-sandbox 导致 Root CDP client not initialized 资料来源：issues/14779
• Cloud API 静默限流：超出最大并发运行时数时静默暂停旧沙箱而非返回 429 资料来源：issues/13126
• Podman 与 Gitea/Forgejo 支持：长期高互动量社区请求 资料来源：issues/5325, issues/9354

部署模式

OpenHands 支持本地开发（npm run dev + MSW 模拟后端）、生产模式（make build 与 make run）、Docker 容器化部署以及 OpenHands Cloud / Enterprise 部署。资料来源：frontend/README.md:40-70

另请参阅

• 前端开发文档
• App Server 模块文档
• 技能系统文档
• 企业版架构文档

概述与定位

Agent Canvas（智能体画布）是 OpenHands 项目的自托管开发者控制中心，将编码智能体（coding agents）转化为"随时在线的工程团队"。它默认在本地机器运行，可对接多种智能体后端（Docker 容器、虚拟机、公司基础设施），并可选择接入 OpenHands Cloud 或 OpenHands Enterprise。资料来源：README.md:1-50

Agent Canvas 既可使用 OpenHands 内置的开源智能体，也能接入 Claude Code、Codex、Gemini 或任何符合 Agent-Client Protocol（ACP）规范的第三方智能体。它支持创建自动化任务（如生成 Slack 报告、自动分解 GitHub Issue），并可与 Slack、GitHub、Notion、Linear 等第三方服务集成。资料来源：README.md:12-30

技术栈与组件库

前端基于 Remix SPA 模式构建，核心技术栈包括 React + Vite + React Router、TypeScript、Redux、TanStack Query、Tailwind CSS 与 i18next，开发和测试分别使用 Bun 与 Vitest。资料来源：frontend/README.md:1-30

UI 组件统一由 @openhands/ui 包提供，该包以 ESM 方式发布，导出 Avatar、Badge、Button、Card、Chip、Divider、Input、Select、Switch、Tooltip、Typography 等基础组件。资料来源：openhands-ui/README.md:1-30, openhands-ui/package.json:1-30

推荐使用 Bun 进行本地开发；Storybook 用于组件调试与可视化。资料来源：openhands-ui/README.md:34-50

graph LR
    A[Agent Canvas Frontend<br/>Remix SPA] --> B[@openhands/ui<br/>组件库]
    A --> C[TanStack Query<br/>数据获取]
    A --> D[Redux<br/>状态管理]
    A --> E[App Server REST API]
    E --> F[Sandbox/Agent Runtime]
    E --> G[Event Callback<br/>Webhooks]
    B --> H[Storybook<br/>组件调试]

核心功能模块

对话与消息系统

V1 对话协议定义了标准化的消息内容与启动请求格式。消息内容支持 V1TextContent（纯文本）与 V1ImageContent（多图片）两种类型，角色涵盖 user / system / assistant / tool。V1AppConversationStartRequest 携带 sandbox_id、initial_message、llm_model、selected_repository、plugins 等参数，完整描述一次会话的启动上下文。资料来源：frontend/src/api/conversation-service/v1-conversation-service.types.ts:1-60

会话启动任务 V1AppConversationStartTask 暴露完整状态机：WORKING → WAITING_FOR_SANDBOX → PREPARING_REPOSITORY → RUNNING_SETUP_SCRIPT → SETTING_UP_GIT_HOOKS → SETTING_UP_SKILLS → STARTING_CONVERSATION → READY（或 ERROR），前端可据此驱动进度 UI。资料来源：frontend/src/api/conversation-service/v1-conversation-service.types.ts:60-80

集成服务（Git Providers）

前端通过 integration-service 统一管理 GitHub、GitLab、Bitbucket Data Center 等代码托管平台的资源、webhook 与连接。GitLabResource、BitbucketDCResource 等类型描述每个集成资源的同步状态、webhook 安装情况和最近同步时间。资料来源：frontend/src/api/integration-service/integration-service.types.ts:1-60

git-service.api.ts 提供 retrieveUserGitRepositories 与 retrieveInstallationRepositories 两个分页接口，支持按 provider、installation_id、cursor 分页，便于在 UI 中浏览远端仓库列表。资料来源：frontend/src/api/git-service/git-service.api.ts:1-50

应用服务器（App Server）支撑

前端所有请求最终落到 openhands/app_server 的 FastAPI 服务。它按领域划分为 app_conversation/、sandbox/、event/、event_callback/、settings/、user/、secrets/ 等模块，分别管理会话、沙箱、事件流、webhook、用户设置、密钥等能力。资料来源：openhands/app_server/README.md:1-20

event_callback 模块为外部系统提供 webhook 注册、事件过滤、回调结果跟踪与失败重试能力，是 Agent Canvas 自动化与第三方集成的关键支撑。资料来源：openhands/app_server/event_callback/README.md:1-15

技能（Skills）与微代理

前端运行时还会加载 skills/ 目录下的"知识代理"与"仓库代理"：前者由关键词触发，提供语言/框架最佳实践；后者从仓库内 .openhands/skills/ 加载，提供仓库专属约定。V0 兼容路径为 .openhands/microagents/。资料来源：skills/README.md:1-40

已知问题与社区关注点

社区反馈中与前端 UI 强相关的缺陷包括：

• LLM Profile 编辑串扰：编辑一个 LLM Profile 时，其 model（有时含 api_key）会覆盖其他 Profile，导致全部坍塌为当前 Profile 的模型（Issue #14800）。
• 内置浏览器异常：WebApp 开发场景下浏览器内嵌视图行为异常，无法真实测试应用（Issue #14569）；agent-server 镜像中 Chromium 未带 --no-sandbox，触发 BrowserLaunchEvent 超时（Issue #14779）。
• 远程访问 CORS：1.3.0 起为 Docker 沙箱服务增加 CORS 支持，需配合 WEB_HOST 与 SANDBOX_CONTAINER_URL_PATTERN 才能在远程服务器上访问浏览器。资料来源：README.md 中的 1.3.0 发行说明

开发与构建

cd frontend
npm install
npm run dev         # 使用 MSW mock 后端
make build          # 从仓库根目录构建生产版本
make run            # 启动生产构建

测试使用 Vitest + React Testing Library + MSW（Mock Service Worker），并配套 V8 覆盖率报告。资料来源：frontend/README.md:60-90

See Also

• App Server REST API 详细模块
• ACP 智能体对接规范
• OpenHands Enterprise / SaaS 认证与集成架构（enterprise/doc/architecture/README.md）

后端：应用服务器、服务与集成

概述与定位

openhands/app_server 是 OpenHands V1 集成体系中的 FastAPI 应用服务器，它对外暴露 REST API 端点，用于管理会话、沙箱、事件、用户设置以及与外部服务的集成。资料来源：openhands/app_server/README.md:1-9

它的核心职责是封装 OpenHands Software Agent SDK，向前端（frontend/src/api/*）以及第三方代理（如 Claude Code、Codex、ACP 兼容代理）提供统一的接口层。资料来源：README.md:1-20、frontend/src/api/README.md:1-9

后端服务按域拆分为多个模块，每个模块都包含 FastAPI 路由、抽象服务接口以及一个或多个运行时实现。资料来源：openhands/app_server/README.md:11-28

主要服务模块

1. 应用会话（App Conversation）

app_conversation 模块负责管理沙箱化会话的完整生命周期，包括创建、检索、状态跟踪与销毁。关键组件如下：

• AppConversationService：会话 CRUD 操作的抽象服务接口。
• LiveStatusAppConversationService：基于事件的实时状态跟踪实现。
• AppConversationRouter：FastAPI 路由层。

该模块还支持按标题、日期、状态等条件进行搜索、分页以及与沙箱环境的协同。资料来源：openhands/app_server/app_conversation/README.md:1-17

2. 沙箱管理（Sandbox）

沙箱服务负责承载代理执行环境，向前端暴露 V1SandboxInfo、V1ExposedUrl 等结构。沙箱状态机包含 MISSING → STARTING → RUNNING → PAUSED → ERROR 五个状态。资料来源：frontend/src/api/sandbox-service/sandbox-service.types.ts:3-21

值得注意的是，社区在 1.8.0 版本中引入了「用户可选择沙箱分组策略」的能力；在更早的版本中，开发者还增加了 SANDBOX_KVM_ENABLED 环境变量以将 /dev/kvm 透传给沙箱容器，从而支持 KVM 加速的虚拟机。资料来源：1.7.0 release notes、1.8.0 release notes

3. 用户与认证

user 模块提供 UserContext、AuthUserContext、UserRouter 以及基于 FastAPI 依赖注入的 UserContextInjector，统一处理用户身份与会话作用域内的服务解析。资料来源：openhands/app_server/user/README.md:1-15

4. 集成服务（Git / Issue Tracker）

集成服务通过统一的 openHands axios 实例与后端通信。前端定义了多套资源模型：

• GitLabResource、ReinstallWebhookRequest、ResourceInstallationResult：覆盖 GitLab 项目/组及其 Webhook 管理。资料来源：frontend/src/api/integration-service/integration-service.types.ts:1-37
• BitbucketDCResource、EnrollBitbucketDCWebhookRequest：Bitbucket Data Center 的仓库与 Webhook 接入。
• RepositoryPage / retrieveUserGitRepositories：通用 Git 仓库分页检索接口，支持 installation_id、page_id 等参数。资料来源：frontend/src/api/git-service/git-service.api.ts:5-34

后端已实现 GitHub、GitLab、Bitbucket DC 集成；社区已多次请求支持 Gitea/Forgejo（#9354）以及 Podman 替代 Docker（#5325），但截至当前版本官方仍以 Docker 作为主运行时。资料来源：Top community issues。

5. 设置、配置与 LLM Profiles

config_api、settings、secrets 等子模块负责用户与系统级配置；option-service 暴露 ModelsResponse 等结构，由后端作为「单一事实来源」返回可用模型与已验证模型列表，从而避免前端硬编码模型清单。资料来源：frontend/src/api/option-service/option.types.ts:5-25

1.8.0 引入的 LLM Profiles（PR #14149）允许用户在多个模型配置之间切换；社区报告 #14800 中编辑某 LLM Profile 时会覆盖其他 Profile 的 model 与 api_key，表明在写回持久化时存在全局状态污染的回归。

扩展性与企业特性

应用服务器通过 utils/import_utils.py 中的 get_impl / import_from 函数实现「运行时实现替换」：基类声明抽象方法，OpenHands 提供默认实现，部署方可以继承并通过配置注入自定义实现。资料来源：openhands/app_server/utils/README.md:21-37

企业部署在此基础上增加：

• 维护任务系统（maintenance_task_processor）：基于 MaintenanceTask 数据库模型 + MaintenanceTaskProcessor 抽象基类，在每次部署时触发但不阻塞部署，用于短时后台升级与清理。任务状态包含 INACTIVE / PENDING / WORKING / COMPLETED / ERROR。资料来源：enterprise/server/maintenance_task_processor/README.md:3-43
• 认证流程：基于 Keycloak 的 SaaS 认证。资料来源：enterprise/doc/architecture/README.md:5-7
• 外部集成编排：与 GitHub、Slack、Jira 等企业服务对接。资料来源：enterprise/doc/architecture/README.md:9-13

典型调用流程与架构图

flowchart LR
  UI[Frontend (Remix/React)] -->|axios openHands| API[/"App Server (FastAPI)"/]
  API --> Conv[app_conversation]
  API --> Sbx[sandbox]
  API --> Set[settings / LLM Profiles]
  API --> Int[integration / git / webhooks]
  API --> User[user / JWT]
  Conv --> SDK[Software Agent SDK]
  Sbx --> SDK
  SDK --> Agent[OpenHands / Claude Code / Codex / ACP]
  Agent -. events .-> API
  API -. callbacks .-> CB[event_callback / webhooks]
  API --> DB[(Database / Maintenance Tasks)]

常见失败模式

See Also

• skills/README.md — 知识代理与仓库级微代理体系
• frontend/README.md — 前端开发与环境变量
• openhands-ui/README.md — UI 组件库与发布流程
• enterprise/doc/architecture/README.md — 企业级认证与外部集成架构

1. 总体定位与部署形态

项目主入口 README.md 将 OpenHands Agent Canvas 描述为"自托管、始终在线"的工程师协作控制平面。它默认在本地运行，但可以连接到多种 agent backend，包括 Docker 容器、远端虚拟机或 OpenHands Cloud / Enterprise 基础设施，并支持 Claude Code、Codex、Gemini 或任意 ACP 兼容的 agent。

部署形态主要分为三层：

• App Server（应用层）：openhands/app_server/README.md 描述了一个基于 FastAPI 的应用服务器，提供 REST API 端点用于管理 conversations、sandboxes、events 和 user settings，模块化拆分为 app_conversation/、sandbox/、settings/、event/ 等子包。
• Sandbox（沙箱层）：负责安全执行 agent，详见 openhands/app_server/sandbox/README.md。
• Enterprise / SaaS 包装层：enterprise/doc/architecture/README.md 中介绍了 SaaS 部署的 Keycloak 认证以及 GitHub、Slack、Jira 等外部集成；enterprise/server/maintenance_task_processor/README.md 描述了每次发布时运行的后台维护任务系统。

2. 沙箱（Sandbox）机制

沙箱是 OpenHands 隔离 agent 执行环境的核心抽象。

2.1 抽象与实现

SandboxService 是抽象服务接口，用于管理沙箱生命周期；DockerSandboxService 是基于 Docker 的具体实现；SandboxSpecService 管理沙箱规格和模板；SandboxRouter 提供 FastAPI 路由。沙箱同时支持多种后端：Docker、Remote、Local。

资料来源：openhands/app_server/sandbox/README.md

2.2 沙箱状态模型

V1SandboxStatus 定义了沙箱在生命周期中的五种状态：MISSING、STARTING、RUNNING、PAUSED、ERROR。每个 V1SandboxInfo 还包含 sandbox_spec_id、session_api_key、exposed_urls 等字段，用于将沙箱实例与具体规格、对外暴露的 URL 关联起来。

资料来源：frontend/src/api/sandbox-service/sandbox-service.types.ts

2.3 已知运行时问题

社区中报告的若干 bug 与沙箱运行时密切相关：

• 在 ghcr.io/openhands/agent-server 镜像中，browser-use 启动 Chromium 时未传入 --no-sandbox，导致 BrowserLaunchEvent 超时和 "Root CDP client not initialized" 错误。
• 内置 Web 浏览器对 WebApp 开发场景的支持不完整，开发者难以在浏览器中验证应用。
• 1.7.0 版本新增 SANDBOX_KVM_ENABLED 环境变量，用于在沙箱中暴露 /dev/kvm，以便运行 KVM 加速的虚拟机。
• 1.3.0 版本为 Docker sandbox service 增加 CORS 支持，配合 WEB_HOST 与 SANDBOX_CONTAINER_URL_PATTERN 实现远程浏览器访问。

3. App Server 启动流程

V1 conversation 启动并不是一个同步过程，而是一组带状态的异步任务。V1AppConversationStartTask 描述了这个过程，其状态机依次经历：STARTING → BUILDING → WAITING_FOR_SANDBOX → PREPARING_REPOSITORY → RUNNING_SETUP_SCRIPT → SETTING_UP_GIT_HOOKS → SETTING_UP_SKILLS → STARTING_CONVERSATION → READY（或 ERROR）。前端通过 getStartTask(taskId) 轮询该任务直到 READY，再取得 app_conversation_id。

资料来源：frontend/src/api/conversation-service/v1-conversation-service.types.ts 与 v1-conversation-service.api.ts

4. 前端与运行时配置

V1AppConversation 中包含 sandbox_id、selected_repository、selected_branch、llm_model 等字段，表明一次对话总是与具体沙箱实例、代码仓库以及 LLM 模型绑定。前端通过 option.types.ts 中的 ModelsResponse 从后端获取可选模型与已验证模型清单，将模型选择权交给后端，避免在前端硬编码。

环境变量方面，前端使用 VITE_BACKEND_BASE_URL、VITE_BACKEND_HOST、VITE_USE_TLS、VITE_FRONTEND_PORT 等变量配置后端连接、协议与端口；可通过 VITE_MOCK_API=true 启用 MSW 模拟接口，便于无后端环境开发。

资料来源：frontend/src/api/option-service/option.types.ts 与 frontend/README.md

5. 企业与本地开发

enterprise/enterprise_local/README.md 描述了 Enterprise 包装的本地开发模式，依赖 gcloud CLI 与 sops 进行认证与密钥解密，源码位于 ../OpenHands 兄弟目录中；提供三档复杂度：简单本地、含 Redis、含 GitHub Webhook。配套的 maintenance_task_processor 在每次发布时自动执行短时维护任务（如用户设置升级、数据清理），通过 MaintenanceTask.status 跟踪 INACTIVE → PENDING → WORKING → COMPLETED/ERROR，不会阻塞发布流程。

6. 部署与运行常见注意事项

See Also

• OpenHands App Server 总览
• Sandbox 模块说明
• Enterprise 架构文档
• Maintenance Task 系统
• 前端开发与运行
• Enterprise 本地开发指南

Pitfall Log / 踩坑日志

项目：OpenHands/OpenHands

摘要：发现 33 个潜在踩坑项，其中 6 个为 high/blocking；最高优先级：安装坑 - 来源证据：Self-hosting OpenHands。

1. 安装坑 · 来源证据：Self-hosting OpenHands

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Self-hosting OpenHands
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/13827 | 来源类型 github_issue 暴露的待验证使用条件。

2. 安装坑 · 来源证据：[Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even though app-conversation start task is READY and b…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even though app-conversation start task is READY and backend conversation is IDLE
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/13647 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

3. 安全/权限坑 · 失败模式：security_permissions: [Bug] Conversation polling fails with ValidationError when secrets contain null values

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: [Bug] Conversation polling fails with ValidationError when secrets contain null values
• 对用户的影响：Developers may expose sensitive permissions or credentials: [Bug] Conversation polling fails with ValidationError when secrets contain null values
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/12714 | [Bug] Conversation polling fails with ValidationError when secrets contain null values

4. 安全/权限坑 · 失败模式：security_permissions: [Feature]: Docker / Docker Compose Instructions

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: [Feature]: Docker / Docker Compose Instructions
• 对用户的影响：Developers may expose sensitive permissions or credentials: [Feature]: Docker / Docker Compose Instructions
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/14882 | [Feature]: Docker / Docker Compose Instructions

5. 安全/权限坑 · 来源证据：API keys carry full user privileges — add scoped (reduced-privilege) credentials

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：API keys carry full user privileges — add scoped (reduced-privilege) credentials
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/14912 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

6. 安全/权限坑 · 来源证据：[Feature]: Docker / Docker Compose Instructions

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: Docker / Docker Compose Instructions
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/14882 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

7. 安装坑 · 依赖 Docker 环境

• 严重度：medium
• 证据强度：runtime_trace
• 发现：安装/运行入口包含 Docker 命令：docker run -it --rm -p 8000:8000 -v "$HOME/.openhands:/home/openhands/.openhands" -v "${PROJECTS_PATH}:/projects" ghcr.io/openhands/agent-canvas:1.0.0-rc.11
• 对用户的影响：非工程用户可能没有 Docker，启动成本明显增加。
• 复现命令：docker run -it --rm -p 8000:8000 -v "$HOME/.openhands:/home/openhands/.openhands" -v "${PROJECTS_PATH}:/projects" ghcr.io/openhands/agent-canvas:1.0.0-rc.11
• 证据：identity.distribution | https://github.com/OpenHands/OpenHands | docker run -it --rm -p 8000:8000 -v "$HOME/.openhands:/home/openhands/.openhands" -v "${PROJECTS_PATH}:/projects" ghcr.io/openhands/agent-canvas:1.0.0-rc.11

8. 安装坑 · 失败模式：installation: 1.5.0 - 2026-03-11

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: 1.5.0 - 2026-03-11
• 对用户的影响：Upgrade or migration may change expected behavior: 1.5.0 - 2026-03-11
• 证据：failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.5.0 | 1.5.0 - 2026-03-11

9. 安装坑 · 失败模式：installation: 1.6.0 - 2026-03-30

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: 1.6.0 - 2026-03-30
• 对用户的影响：Upgrade or migration may change expected behavior: 1.6.0 - 2026-03-30
• 证据：failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.6.0 | 1.6.0 - 2026-03-30

10. 安装坑 · 失败模式：installation: 1.7.0 - 2026-05-01

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: 1.7.0 - 2026-05-01
• 对用户的影响：Upgrade or migration may change expected behavior: 1.7.0 - 2026-05-01
• 证据：failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.7.0 | 1.7.0 - 2026-05-01

11. 安装坑 · 失败模式：installation: Improve timeout handling and feedback for slow local LLMs

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Improve timeout handling and feedback for slow local LLMs
• 对用户的影响：Developers may fail before the first successful local run: Improve timeout handling and feedback for slow local LLMs
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/8768 | Improve timeout handling and feedback for slow local LLMs

12. 安装坑 · 失败模式：installation: Self-hosting OpenHands

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: Self-hosting OpenHands
• 对用户的影响：Developers may fail before the first successful local run: Self-hosting OpenHands
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/13827 | Self-hosting OpenHands

13. 安装坑 · 失败模式：installation: [Bug]: Pending Messages Not Sent After Conversation Is Ready

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [Bug]: Pending Messages Not Sent After Conversation Is Ready
• 对用户的影响：Developers may fail before the first successful local run: [Bug]: Pending Messages Not Sent After Conversation Is Ready
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/13716 | [Bug]: Pending Messages Not Sent After Conversation Is Ready

14. 安装坑 · 失败模式：installation: [Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even though app-conversation...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even though app-conversation start task is READY and backend conversation is IDLE
• 对用户的影响：Developers may fail before the first successful local run: [Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even though app-conversation start task is READY and backend conversation is IDLE
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/13647 | [Bug]: Self-hosted UI remains stuck on “Starting” / “Loading...” even though app-conversation start task is READY and backend conversation is IDLE

15. 安装坑 · 来源证据：Improve timeout handling and feedback for slow local LLMs

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Improve timeout handling and feedback for slow local LLMs
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/8768 | 来源讨论提到 docker 相关条件，需在安装/试用前复核。

16. 安装坑 · 来源证据：[Bug]: Pending Messages Not Sent After Conversation Is Ready

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Pending Messages Not Sent After Conversation Is Ready
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/13716 | 来源类型 github_issue 暴露的待验证使用条件。

17. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/OpenHands/OpenHands | host_targets=claude, chatgpt, claude_code

18. 配置坑 · 失败模式：configuration: 1.2.0 - 2026-01-15

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 1.2.0 - 2026-01-15
• 对用户的影响：Upgrade or migration may change expected behavior: 1.2.0 - 2026-01-15
• 证据：failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.2.0 | 1.2.0 - 2026-01-15

19. 配置坑 · 失败模式：configuration: 1.3.0 - 2026-02-02

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: 1.3.0 - 2026-02-02
• 对用户的影响：Upgrade or migration may change expected behavior: 1.3.0 - 2026-02-02
• 证据：failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.3.0 | 1.3.0 - 2026-02-02

20. 配置坑 · 失败模式：configuration: Port Jira Data Center Integration to Plugin Architecture

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Port Jira Data Center Integration to Plugin Architecture
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Port Jira Data Center Integration to Plugin Architecture
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/12976 | Port Jira Data Center Integration to Plugin Architecture

21. 配置坑 · 失败模式：configuration: [Enterprise] Admin setting for auto-delete of inactive user data after X days

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [Enterprise] Admin setting for auto-delete of inactive user data after X days
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Enterprise] Admin setting for auto-delete of inactive user data after X days
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/12656 | [Enterprise] Admin setting for auto-delete of inactive user data after X days

22. 配置坑 · 失败模式：configuration: [Feature]: option to send message when pressing enter, not create a new line

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [Feature]: option to send message when pressing enter, not create a new line
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [Feature]: option to send message when pressing enter, not create a new line
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/14861 | [Feature]: option to send message when pressing enter, not create a new line

23. 配置坑 · 来源证据：Negative time values displayed in UI due to timezone mismatch

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Negative time values displayed in UI due to timezone mismatch
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/14148 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

24. 配置坑 · 来源证据：Port Jira Data Center Integration to Plugin Architecture

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Port Jira Data Center Integration to Plugin Architecture
• 对用户的影响：可能影响升级、迁移或版本选择。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/12976 | 来源类型 github_issue 暴露的待验证使用条件。

25. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/OpenHands/OpenHands | README/documentation is current enough for a first validation pass.

26. 维护坑 · 失败模式：migration: 1.8.0 - 2026-06-10

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: 1.8.0 - 2026-06-10
• 对用户的影响：Upgrade or migration may change expected behavior: 1.8.0 - 2026-06-10
• 证据：failure_mode_cluster:github_release | https://github.com/OpenHands/OpenHands/releases/tag/1.8.0 | 1.8.0 - 2026-06-10

27. 维护坑 · 失败模式：migration: [Feature]: Introduce support for displaying queued messages in the conversation UI

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: [Feature]: Introduce support for displaying queued messages in the conversation UI
• 对用户的影响：Developers may hit a documented source-backed failure mode: [Feature]: Introduce support for displaying queued messages in the conversation UI
• 证据：failure_mode_cluster:github_issue | https://github.com/OpenHands/OpenHands/issues/14181 | [Feature]: Introduce support for displaying queued messages in the conversation UI

28. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/OpenHands/OpenHands | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/OpenHands/OpenHands | no_demo; severity=medium

30. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/OpenHands/OpenHands | no_demo; severity=medium

31. 安全/权限坑 · 来源证据：[Bug] Conversation polling fails with ValidationError when secrets contain null values

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Bug] Conversation polling fails with ValidationError when secrets contain null values
• 对用户的影响：可能阻塞安装或首次运行。
• 证据：community_evidence:github | https://github.com/OpenHands/OpenHands/issues/12714 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

32. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/OpenHands/OpenHands | issue_or_pr_quality=unknown

33. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/OpenHands/OpenHands | release_recency=unknown