# https://github.com/OpenHands/OpenHands 项目说明书

生成时间：2026-06-21 08:23:52 UTC

## 目录

- [Project Overview & System Architecture](#page-1)
- [Frontend: Agent Canvas UI & Components](#page-2)
- [Backend: App Server, Services & Integrations](#page-3)
- [Deployment, Sandboxes & Runtime Configuration](#page-4)

<a id='page-1'></a>

## Project Overview & System Architecture

### 相关页面

相关主题：[Frontend: Agent Canvas UI & Components](#page-2), [Backend: App Server, Services & Integrations](#page-3), [Deployment, Sandboxes & Runtime Configuration](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OpenHands/OpenHands/blob/main/README.md)
- [frontend/README.md](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md)
- [openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/README.md)
- [openhands/app_server/utils/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/utils/README.md)
- [skills/README.md](https://github.com/OpenHands/OpenHands/blob/main/skills/README.md)
- [enterprise/doc/architecture/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md)
- [openhands-ui/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands-ui/README.md)
- [frontend/src/api/conversation-service/v1-conversation-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/v1-conversation-service.types.ts)
- [frontend/src/api/sandbox-service/sandbox-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/sandbox-service/sandbox-service.types.ts)
- [frontend/src/api/open-hands.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/open-hands.types.ts)
- [enterprise/server/maintenance_task_processor/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/server/maintenance_task_processor/README.md)
</details>

# 项目概述与系统架构

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]()

## 系统数据流架构

```mermaid
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]()

## 另请参阅

- [前端开发文档](frontend_README.md)
- [App Server 模块文档](openhands_app_server_README.md)
- [技能系统文档](skills_README.md)
- [企业版架构文档](enterprise_architecture_README.md)

---

<a id='page-2'></a>

## Frontend: Agent Canvas UI & Components

### 相关页面

相关主题：[Project Overview & System Architecture](#page-1), [Backend: App Server, Services & Integrations](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OpenHands/OpenHands/blob/main/README.md)
- [frontend/README.md](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md)
- [openhands-ui/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands-ui/README.md)
- [openhands-ui/package.json](https://github.com/OpenHands/OpenHands/blob/main/openhands-ui/package.json)
- [frontend/src/api/open-hands.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/open-hands.types.ts)
- [frontend/src/api/integration-service/integration-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/integration-service/integration-service.types.ts)
- [frontend/src/api/conversation-service/v1-conversation-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/v1-conversation-service.types.ts)
- [frontend/src/api/git-service/git-service.api.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/git-service/git-service.api.ts)
- [openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/README.md)
- [openhands/app_server/event_callback/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/event_callback/README.md)
- [enterprise/doc/architecture/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md)
- [skills/README.md](https://github.com/OpenHands/OpenHands/blob/main/skills/README.md)
</details>

# Frontend: Agent Canvas UI & Components

## 概述与定位

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]()

```mermaid
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](https://github.com/OpenHands/OpenHands/issues/14800)）。
- **内置浏览器异常**：WebApp 开发场景下浏览器内嵌视图行为异常，无法真实测试应用（[Issue #14569](https://github.com/OpenHands/OpenHands/issues/14569)）；`agent-server` 镜像中 Chromium 未带 `--no-sandbox`，触发 `BrowserLaunchEvent` 超时（[Issue #14779](https://github.com/OpenHands/OpenHands/issues/14779)）。
- **远程访问 CORS**：1.3.0 起为 Docker 沙箱服务增加 CORS 支持，需配合 `WEB_HOST` 与 `SANDBOX_CONTAINER_URL_PATTERN` 才能在远程服务器上访问浏览器。资料来源：[README.md 中的 1.3.0 发行说明]()

## 开发与构建

```bash
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](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md)）

---

<a id='page-3'></a>

## Backend: App Server, Services & Integrations

### 相关页面

相关主题：[Project Overview & System Architecture](#page-1), [Frontend: Agent Canvas UI & Components](#page-2), [Deployment, Sandboxes & Runtime Configuration](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/README.md)
- [openhands/app_server/app_conversation/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/app_conversation/README.md)
- [openhands/app_server/user/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/user/README.md)
- [openhands/app_server/utils/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/utils/README.md)
- [enterprise/doc/architecture/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md)
- [enterprise/server/maintenance_task_processor/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/server/maintenance_task_processor/README.md)
- [frontend/src/api/README.md](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/README.md)
- [frontend/src/api/integration-service/integration-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/integration-service/integration-service.types.ts)
- [frontend/src/api/git-service/git-service.api.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/git-service/git-service.api.ts)
- [frontend/src/api/sandbox-service/sandbox-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/sandbox-service/sandbox-service.types.ts)
- [frontend/src/api/option-service/option.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/option-service/option.types.ts)
- [skills/README.md](https://github.com/OpenHands/OpenHands/blob/main/skills/README.md)
</details>

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

## 概述与定位

`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](https://github.com/OpenHands/OpenHands/pull/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]()

## 典型调用流程与架构图

```mermaid
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)]
```

## 常见失败模式

| 现象 | 可能原因 | 关联来源 |
| --- | --- | --- |
| 编辑 LLM Profile 后其他 Profile 模型被覆盖 | 写回时未按 profile id 隔离，污染了全局 active 配置 | Issue #14800 |
| 浏览器内嵌无法工作 / Chromium 启动失败 | `agent-server` 镜像中 `browser-use` 未携带 `--no-sandbox` 参数 | Issue #14779、#14569 |
| 沙箱被静默暂停 | Cloud API 在达到并发上限时自动 pause 旧运行时而非返回 429 | Issue #13126 |
| `make docker-dev` 后宿主机出现 root 属主文件 | 开发容器以 root 写入挂载卷 | Issue #13434 |
| 缺少 Gitea/Forgejo / Podman 支持 | 平台集成与运行时仍以 GitHub、GitLab、Docker 为主 | Issue #9354、#5325 |

## See Also

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

---

<a id='page-4'></a>

## Deployment, Sandboxes & Runtime Configuration

### 相关页面

相关主题：[Project Overview & System Architecture](#page-1), [Backend: App Server, Services & Integrations](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/OpenHands/OpenHands/blob/main/README.md)
- [openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/README.md)
- [openhands/app_server/sandbox/README.md](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/sandbox/README.md)
- [frontend/src/api/sandbox-service/sandbox-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/sandbox-service/sandbox-service.types.ts)
- [frontend/src/api/conversation-service/v1-conversation-service.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/v1-conversation-service.types.ts)
- [frontend/src/api/conversation-service/v1-conversation-service.api.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/v1-conversation-service.api.ts)
- [frontend/src/api/option-service/option.types.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/option-service/option.types.ts)
- [frontend/README.md](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md)
- [enterprise/enterprise_local/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/enterprise_local/README.md)
- [enterprise/doc/architecture/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md)
- [enterprise/server/maintenance_task_processor/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/server/maintenance_task_processor/README.md)
</details>

# Deployment, Sandboxes & Runtime Configuration

OpenHands 是一个支持自托管的智能体控制中心，可通过本地、远程或云端多种方式部署运行 coding agent。本页围绕 **部署形态、沙箱机制和运行时配置** 三个维度，整理仓库中与部署和运行相关的主要模块、关键概念与配置点。

## 1. 总体定位与部署形态

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

部署形态主要分为三层：

- **App Server（应用层）**：[openhands/app_server/README.md](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/sandbox/README.md)。
- **Enterprise / SaaS 包装层**：[enterprise/doc/architecture/README.md](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md) 中介绍了 SaaS 部署的 Keycloak 认证以及 GitHub、Slack、Jira 等外部集成；[enterprise/server/maintenance_task_processor/README.md](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/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](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/v1-conversation-service.types.ts) 与 [v1-conversation-service.api.ts](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/conversation-service/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](https://github.com/OpenHands/OpenHands/blob/main/frontend/src/api/option-service/option.types.ts) 与 [frontend/README.md](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md)

## 5. 企业与本地开发

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

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

| 关注点 | 说明 |
|---|---|
| Docker / Podman 兼容 | 社区有大量关于 `podman` 支持（[issue #5325](https://github.com/OpenHands/OpenHands/issues/5325)）和无 Docker 安装（[issue #8632](https://github.com/OpenHands/OpenHands/issues/8632)）的讨论，需关注官方文档演进 |
| `make docker-dev` 权限 | 在已修复的 issue #13434 中，开发容器会以 root 身份在挂载目录中创建文件，可能影响宿主机后续构建 |
| Cloud 并发上限 | 当超过最大并发 runtime 数时，旧 sandbox 会被静默 `PAUSED`（[issue #13126](https://github.com/OpenHands/OpenHands/issues/13126)），需注意 API 行为 |
| 沙箱分组策略 | 1.8.0 引入可由用户选择的 sandbox grouping strategy，以更细粒度控制资源复用 |
| 平台扩展 | Gitea/Forgejo（[issue #9354](https://github.com/OpenHands/OpenHands/issues/9354)）等仍属社区高度关注的扩展方向 |

## See Also

- [OpenHands App Server 总览](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/README.md)
- [Sandbox 模块说明](https://github.com/OpenHands/OpenHands/blob/main/openhands/app_server/sandbox/README.md)
- [Enterprise 架构文档](https://github.com/OpenHands/OpenHands/blob/main/enterprise/doc/architecture/README.md)
- [Maintenance Task 系统](https://github.com/OpenHands/OpenHands/blob/main/enterprise/server/maintenance_task_processor/README.md)
- [前端开发与运行](https://github.com/OpenHands/OpenHands/blob/main/frontend/README.md)
- [Enterprise 本地开发指南](https://github.com/OpenHands/OpenHands/blob/main/enterprise/enterprise_local/README.md)

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: OpenHands/OpenHands; human_manual_source: deepwiki_human_wiki -->