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

生成时间：2026-06-15 00:44:21 UTC

## 目录

- [Project Overview and Installation](#page-1)
- [Configuration, Running Modes and CLI Surface](#page-2)
- [TUI System: Widgets, Modals, Conversation Runner and Critic](#page-3)
- [ACP Server, Cloud Mode, MCP and Conversation Storage](#page-4)

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

## Project Overview and Installation

### 相关页面

相关主题：[Configuration, Running Modes and CLI Surface](#page-2)

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

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

- [README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)
- [openhands_cli/acp_impl/README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/README.md)
- [openhands_cli/tui/utils/critic/visualization.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/visualization.py)
- [openhands_cli/tui/utils/critic/feedback.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/feedback.py)
- [openhands_cli/tui/utils/critic/__init__.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/__init__.py)
- [openhands_cli/tui/utils/critic/refinement.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/refinement.py)
- [openhands_cli/acp_impl/utils/mcp.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/mcp.py)
- [openhands_cli/acp_impl/utils/convert.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/convert.py)
- [openhands_cli/acp_impl/agent/base_agent.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/base_agent.py)
- [openhands_cli/acp_impl/utils/resources.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/resources.py)
- [openhands_cli/acp_impl/utils/__init__.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/__init__.py)
- [tui_e2e/README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/tui_e2e/README.md)
</details>

# 项目概览与安装指南

## 1. 项目定位与目标

OpenHands CLI（命令行工具）让用户能够在终端、IDE、CI 流水线、本地浏览器或 OpenHands Cloud 沙箱中运行 OpenHands 智能体，是 OpenHands V1 体系下"功能完成、仅做稳定维护"的核心入口组件。根据 [README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md) 的描述，项目当前主要接收重大缺陷修复与兼容性更新，新功能开发请关注上游 [OpenHands](https://github.com/All-Hands-AI/OpenHands) 仓库。

从代码结构上观察，该项目以 `openhands_cli` 作为顶层包，向下划分为若干子系统：

- `tui/`：基于 [Textual](https://textual.textualize.io/) 的终端用户界面，提供 Critic 可视化、对话历史渲染与可折叠面板等功能（参考 [visualization.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/visualization.py)）。
- `acp_impl/`：实现 [Agent Client Protocol](https://agentclientprotocol.com/protocol/overview)，允许在 Zed 等支持 ACP 的编辑器中以标准化 JSON-RPC 2.0 方式接入（参考 [acp_impl/README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/README.md)）。
- `setup/`、`auth/`：负责首次运行时的 LLM 配置与身份令牌持久化。

## 2. 系统架构总览

下图展示了 OpenHands CLI 各核心模块之间的关系：

```mermaid
graph TD
    User[用户] --> CLI[openhands CLI 入口]
    CLI -->|交互模式| TUI[TUI 子系统]
    CLI -->|acp 子命令| ACP[ACP 子系统]
    CLI -->|mcp 子命令| MCP[MCP 配置管理]
    TUI --> Critic[Critic 可视化与反馈]
    TUI --> Conv[对话状态机]
    ACP --> BaseAgent[BaseOpenHandsACPAgent]
    BaseAgent --> SDK[OpenHands SDK]
    Conv --> SDK
    Critic -.PostHog.-> PH[PostHog 分析]
    SDK --> LLM[LLM 提供方]
```

关键说明：

- `TUI` 子系统通过 `openhands_cli.tui.utils.critic` 提供评估结果可视化与用户反馈收集，例如 [`create_critic_collapsible`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/visualization.py) 会根据是否包含潜在问题决定是否展开面板。
- `ACP` 子系统的 [`BaseOpenHandsACPAgent`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/base_agent.py) 是抽象基类，封装了斜杠命令解析、MCP 服务转换、会话生命周期等通用逻辑。
- 用户反馈通过 [`CriticFeedbackWidget`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/feedback.py) 上报至 PostHog，用于持续改进 Critic 预测质量。

## 3. 安装方式

README 提供了两种官方推荐安装途径。

### 3.1 使用 `uv` 工具安装（推荐）

需要 Python 3.12+ 以及 [uv](https://docs.astral.sh/uv/) 0.11.6 或更高版本（[README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)）：

```bash
uv tool install openhands --python 3.12
```

安装完成后，在任意目录执行 `openhands` 即可进入首次配置向导。

### 3.2 通过独立二进制安装

若不便配置 Python 环境，可使用安装脚本拉取预编译的 standalone 二进制（[README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)）：

```bash
curl -fsSL https://install.openhands.dev/install.sh | sh
```

注意：社区在 [Issue #89](https://github.com/OpenHands/OpenHands-CLI/issues/89) 中报告了 macOS 上的 Gatekeeper 安全提示问题，遇到"无法打开，因为 Apple 无法检查其是否包含恶意软件"时需在"系统设置 → 隐私与安全性"中手动放行。

## 4. 首次运行与配置

首次执行 `openhands` 时，CLI 会引导用户完成 LLM 提供方、模型、API Key 等设置。配置数据默认存储在 `~/.openhands/` 目录下（[README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)）：

| 配置文件 | 作用 |
|----------|------|
| `agent_settings.json` | 持久化智能体设置，包括 condenser 配置 |
| `cli_config.json` | CLI/TUI 偏好（如 Critic 开关） |
| `mcp.json` | MCP 服务器配置 |

`LLM_API_KEY`、`LLM_MODEL`、`LLM_BASE_URL` 等环境变量在默认情况下会被忽略；若希望使用环境变量覆盖已保存配置，可加上 `--override-with-envs` 启动参数，但相关值不会被写回磁盘。

社区对 LLM 配置管理仍有持续改进需求，例如 [Issue #68](https://github.com/OpenHands/OpenHands-CLI/issues/68) 提出希望支持多套 LLM 配置文件以便在模型间快速切换；[Issue #673](https://github.com/OpenHands/OpenHands-CLI/issues/673) 则反馈本地 LLM 场景下仍被强制要求填写 API Key，与 GUI 行为不一致。

## 5. 主要使用模式

### 5.1 交互式 TUI 模式

默认运行 `openhands` 即可进入基于 Textual 的 TUI。Critic 模块会针对每一次完成的任务生成 0–1 评分，并按照 [`get_high_probability_issues`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/refinement.py) 提取高概率问题，触发迭代式 refinement 流程，将结果以可折叠面板呈现（参考 [visualization.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/visualization.py)）。

### 5.2 ACP 编辑器集成模式

通过 `openhands acp` 启动 ACP 服务，编辑器（如 Zed）即可通过 JSON-RPC 与之通信。开发者可在 Zed 中配置如下 agent 启动方式（[acp_impl/README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/README.md)）：

```json
"OpenHands-uvx": {
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/All-Hands-AI/OpenHands-CLI.git@<branch>",
    "openhands",
    "acp"
  ],
  "env": {}
}
```

ACP 模式下，提示内容会经由 [`convert_acp_prompt_to_message_content`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/convert.py) 转换为 SDK 可识别的 `TextContent` 与 `ImageContent`，MCP 服务器配置则通过 [`convert_acp_mcp_servers_to_agent_format`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/mcp.py) 完成格式适配。

### 5.3 终端状态清理（已知问题）

[Issue #671](https://github.com/OpenHands/OpenHands-CLI/issues/671) 反映某些命令退出后终端会残留转义序列，需要手动执行 `reset` 或 `stty sane` 才能恢复。在受影响的环境中，建议在脚本里显式调用 `stty sane` 以保证后续命令可正常键入。

## 6. 端到端测试与开发

`tui_e2e/` 目录提供了基于轨迹回放的端到端测试框架，使用 [mock LLM 服务器](https://github.com/OpenHands/OpenHands-CLI/blob/main/tui_e2e/README.md) 按顺序重放 `ActionEvent` 与 `MessageEvent`，让真实 CLI 实际执行工具调用并校验输出。该机制让 TUI 行为变更可被精确回归测试。

## 参见

- [TUI 与 Critic 可视化](tui-and-critic.md)
- [ACP 协议集成](acp-integration.md)
- [MCP 服务器配置](mcp-configuration.md)
- [上游项目 OpenHands](https://github.com/All-Hands-AI/OpenHands)
- [Agent Client Protocol 官方文档](https://agentclientprotocol.com/protocol/overview)

---

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

## Configuration, Running Modes and CLI Surface

### 相关页面

相关主题：[Project Overview and Installation](#page-1), [TUI System: Widgets, Modals, Conversation Runner and Critic](#page-3), [ACP Server, Cloud Mode, MCP and Conversation Storage](#page-4)

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

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

- [README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)
- [openhands_cli/acp_impl/README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/README.md)
- [openhands_cli/acp_impl/agent/base_agent.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/base_agent.py)
- [openhands_cli/acp_impl/utils/convert.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/convert.py)
- [openhands_cli/acp_impl/utils/mcp.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/mcp.py)
- [openhands_cli/acp_impl/utils/resources.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/resources.py)
- [openhands_cli/tui/utils/critic/__init__.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/__init__.py)
- [openhands_cli/tui/utils/critic/visualization.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/visualization.py)
- [openhands_cli/tui/utils/critic/feedback.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/feedback.py)
</details>

# Configuration, Running Modes and CLI Surface

## 1. 概览

OpenHands-CLI 是 OpenHands V1 在终端场景下的入口，它既是一个交互式 TUI（基于 [Textual](https://textual.textualize.io/)）客户端，也可以作为 ACP（Agent Client Protocol）服务器被 Zed 等 IDE 通过 JSON-RPC 2.0 调用，并提供了针对 CI/CD 的 headless 模式与云端执行模式。仓库 README 明确指出："OpenHands V1 CLI is **feature-complete** and primarily maintained for stability."，因此本页所述 CLI Surface 主要用于帮助读者理解当前稳定接口而非新增功能。

资料来源：[README.md:14-16]()

## 2. 安装与启动入口

README 推荐两种分发方式：使用 [uv](https://docs.astral.sh/uv/) 以 `uv tool install openhands --python 3.12` 安装 Python 包，或使用 `curl -fsSL https://install.openhands.dev/install.sh | sh` 下载独立的可执行二进制（[README.md:23-38]()）。首次执行 `openhands` 时会引导用户完成 LLM 配置；之后所有持久化配置都写入 `~/.openhands/` 目录下（[README.md:43-58]()）：

| 文件 | 作用 |
| --- | --- |
| `agent_settings.json` | 持久化的 agent 设置（含 condenser 配置） |
| `cli_config.json` | TUI/CLI 偏好（如是否启用 critic） |
| `mcp.json` | MCP 服务器配置 |

> 默认情况下，`LLM_API_KEY`、`LLM_MODEL`、`LLM_BASE_URL` 等环境变量会被忽略；如需临时覆盖，可传入 `--override-with-envs` 标志，但这些值不会被持久化（[README.md:54-58]()）。

## 3. CLI Surface 与子命令

CLI 的"表面"由若干相互独立的子命令与全局标志组成。基于 README 的命令参考章节可归纳如下：

```mermaid
flowchart LR
  Root[openhands] --> TUI[default: TUI]
  Root --> MCP[mcp]
  Root --> Auth[login / logout]
  Root --> Cloud[cloud -t TASK]
  Root --> ACP[acp]
  Root --> Headless[--headless -t TASK]
  MCP --> List[mcp list]
  MCP --> Add[mcp add NAME --transport stdio ...]
  MCP --> Enable[mcp enable NAME]
  MCP --> Disable[mcp disable NAME]
  Root --> Flags[--always-approve / --yolo / --llm-approve / --override-with-envs]
```

- **交互式 TUI**：默认入口，可视化事件流、status icon 与 critic 评分。
- **Headless 模式**：`openhands --headless -t "..."`，用于 CI 流水线（[README.md:90-95]()）。
- **Confirmation 模式**：`--always-approve`（或 `--yolo`）全量放行，`--llm-approve` 走基于 LLM 的安全分析器（[README.md:72-83]()）。
- **Cloud 模式**：`openhands login` 完成云端认证后，`openhands cloud -t "..."` 将任务提交到 OpenHands Cloud 沙箱。
- **ACP 模式**：`openhands acp` 启动一个 JSON-RPC 服务端，供 Zed 等编辑器通过 Agent Client Protocol 接入（[README.md:84-87]()，配合 [openhands_cli/acp_impl/README.md]() 的配置示例）。

社区关注的 `#101` 提案希望补充"列出历史会话"的子命令，README 当前尚未收录该能力，状态仍属于计划中。

## 4. 配置文件与持久化语义

CLI 严格区分"持久化设置"与"运行时覆盖"。持久化数据通过首次启动的引导流程写入，修改后立即生效；环境变量则是一次性的、非持久的入口，适合 CI 场景（[README.md:54-58]()）。

社区反馈 `#673` 指出，使用本地/ollama 模型时 CLI 仍会强制提示输入 `LLM_API_KEY`，这与 GUI 行为不一致；该问题直接影响 `agent_settings.json` 的字段约束与首次引导逻辑。另一项常见问题 `#671` 反映 CLI 退出后终端状态（ANSI/termcap）未恢复，需要手动 `stty sane`，属于 TUI 清理路径上的已知缺陷。

## 5. ACP 运行模式

ACP 模式由 `openhands_cli/acp_impl/` 子包实现，其抽象基类 `BaseOpenHandsACPAgent` 在 [openhands_cli/acp_impl/agent/base_agent.py]() 中定义，并按 `agent_type` 派生出 local 与 cloud 两种具体 agent。协议层主要职责包括：

- **斜杠命令解析**：`get_available_slash_commands`、`parse_slash_command`、`handle_confirm_argument` 等函数集中实现于 `slash_commands` 模块，并在 base agent 内部复用。
- **Confirmation Mode 桥接**：`apply_confirmation_mode_to_conversation` 将 ACP 客户端的确认模式同步到 `BaseConversation` 上，使 IDE 中的 `/confirm` 类命令与 TUI 行为一致。
- **提示词转换**：`convert_acp_prompt_to_message_content`（[openhands_cli/acp_impl/utils/convert.py]()）将 ACP 的 `TextContentBlock` / `ImageContentBlock` / `ResourceContentBlock` 等统一映射为 SDK 的 `TextContent` / `ImageContent`。
- **MCP 适配**：`convert_acp_mcp_servers_to_agent_format`（[openhands_cli/acp_impl/utils/mcp.py]()）负责把 `McpServerStdio` / `HttpMcpServer` / `SseMcpServer` 列表转换为 Agent 端以 `transport` 字段区分的字典格式，从而复用同一套 MCP 配置。
- **资源嵌入**：`openhands_cli/acp_impl/utils/resources.py` 处理 `EmbeddedResourceContentBlock`，对图像直接返回 `ImageContent`，对非图像或无法转换的二进制写入 `~/.openhands/cache/acp/`（参见同文件 `get_acp_cache_dir()`）。

针对社区强烈关注的 `#66`（ACP 支持）已通过本子包落地；编辑器侧的具体接入步骤可参见 [openhands_cli/acp_impl/README.md:11-39]() 给出的 `uvx` 与 `uv run` 两种配置示例。

## 6. Critic 与 TUI 子模块

TUI 在 `openhands_cli/tui/utils/critic/` 下提供 critic 评分可视化与用户反馈采集：

- [openhands_cli/tui/utils/critic/__init__.py]() 导出 `create_critic_collapsible`、`build_refinement_message`、`get_high_probability_issues`、`should_trigger_refinement`、`send_critic_inference_event` 等公共 API。
- `create_critic_collapsible`（[openhands_cli/tui/utils/critic/visualization.py]()）使用 5 星评分，并以分类方式呈现 "Potential Issues" 与 "Infrastructure" 两类问题；CLI 故意隐藏 SDK 中的 "Likely Follow-up" 与 "Other" 类别以保持界面简洁。
- `CriticFeedbackWidget`（[openhands_cli/tui/utils/critic/feedback.py]()）向 PostHog 上报用户对 critic 准确性的反馈（按键 `[1] Accurate` / `[2] Too high` / `[3] Too low` / `[4] N/A` / `[0] Dismiss`）。

社区 `#641` 报告"critic 按钮渲染时机错位"——按钮行在出现更晚的事件/动作后仍保留，这与 critic 反馈 widget 挂载/卸载的逻辑相关。

## 7. 已知限制与社区反馈

- **历史会话查看**（`#101`）：README 暂未提供 `openhands history` 类命令。
- **终端清理**（`#671`）：退出时未恢复 termcap，需手动 `reset` / `stty sane`。
- **本地模型 API Key 必填**（`#673`）：本地/ollama 场景下 `agent_settings.json` 字段未做可选化。
- **/ 触发 Agent Skills**（`#343`）：用户期望 `/` 唤起下拉菜单列出 skills/triggers，目前仍依赖 `openhands_cli/tui` 内置命令面板。
- **macOS 二进制 Gatekeeper**（`#89`）：未签名的 `openhands-macos` 在 Apple Silicon 上被拦截，需用户手动放行。
- **Critic 按钮时序**（`#641`）：与 TUI 事件流的渲染边界相关，参见 critic 子模块。

## 8. See Also

- [Agent Client Protocol Overview](https://agentclientprotocol.com/protocol/overview)
- [OpenHands Software Agent SDK](https://github.com/OpenHands/software-agent-sdk)
- [CLI Command Reference](https://docs.openhands.dev/openhands/usage/cli/command-reference)
- [MCP Servers](https://docs.openhands.dev/openhands/usage/cli/mcp-servers)
- [Headless Mode](https://docs.openhands.dev/openhands/usage/cli/headless)
- [Cloud Conversations](https://docs.openhands.dev/openhands/usage/cli/cloud)

---

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

## TUI System: Widgets, Modals, Conversation Runner and Critic

### 相关页面

相关主题：[Configuration, Running Modes and CLI Surface](#page-2), [ACP Server, Cloud Mode, MCP and Conversation Storage](#page-4)

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

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

- [openhands_cli/tui/utils/critic/visualization.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/visualization.py)
- [openhands_cli/tui/utils/critic/feedback.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/feedback.py)
- [openhands_cli/tui/utils/critic/refinement.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/refinement.py)
- [openhands_cli/tui/utils/critic/__init__.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/__init__.py)
- [openhands_cli/acp_impl/agent/base_agent.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/base_agent.py)
- [openhands_cli/acp_impl/utils/convert.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/convert.py)
- [openhands_cli/acp_impl/utils/mcp.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/mcp.py)
- [README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)
</details>

# TUI System: Widgets, Modals, Conversation Runner and Critic

## 概述与定位

OpenHands V1 CLI 的 TUI（文本用户界面）系统基于 [Textual](https://textual.textualize.io/) 框架构建，负责将 SDK 生成的对话事件渲染到终端中，并提供交互式控件（Widget）、模态框（Modal）、斜杠命令解析以及可选的 Critic 评分反馈机制。

整个 V1 CLI 处于 **功能完整、仅维护稳定** 阶段，主要接收重大缺陷修复与兼容性更新，新增特性很少 [`README.md`](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)。配置默认存放于 `~/.openhands/` 目录下的 `cli_config.json`、`agent_settings.json` 和 `mcp.json` 等文件中 [`README.md`](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)。

## Critic 评分可视化与反馈系统

Critic 子系统位于 [openhands_cli/tui/utils/critic/](https://github.com/OpenHands/OpenHands-CLI/tree/main/openhands_cli/tui/utils/critic)，由四个模块构成：

| 模块 | 职责 |
|------|------|
| `visualization.py` | 将 SDK 的 `CriticResult` 转换为可折叠的星标评分组件 |
| `feedback.py` | 提供用户对预测准确度的反馈按钮（带 PostHog 埋点） |
| `refinement.py` | 基于评分阈值生成迭代优化提示 |
| `__init__.py` | 对外暴露统一 API |

### 可视化组件

`create_critic_collapsible()` 接收一个 `CriticResult`，构造一个 `Collapsible` 控件：标题部分调用 `_get_star_rating()` 把 0–1 的分数映射成五星字符串；内容部分通过 `_append_features_from_precategorized()` 只展示「Potential Issues」与「Infrastructure」两类信息，明确过滤掉 SDK 默认的「Likely Follow-up」与「Other」分区，因为对 CLI 用户而言价值较低 [`visualization.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/visualization.py)。

如果评分没有附带任何可显示内容，控件会自动折叠 (`collapsed=not has_content`)，并在样式上减小 padding，使终端界面更紧凑。

### 用户反馈埋点

`CriticFeedbackWidget` 在评分展示后弹出五个按钮供用户标注预测质量：`[1] Accurate`、`[2] Too high`、`[3] Too low`、`[4] N/A`、`[0] Dismiss`，对应的语义映射存放在 `FEEDBACK_OPTIONS` 中 [`feedback.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/feedback.py)。`send_critic_inference_event()` 函数在评分首次呈现时即向 PostHog 上报一次「推理事件」，并附带 `conversation_id` 与 `agent_model` 维度，密钥与 Host 硬编码于模块顶部 (`POSTHOG_API_KEY`、`POSTHOG_HOST`)，当 `posthog` 不可用时整体埋点逻辑静默降级 [`feedback.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/feedback.py)。

社区 issue #641 反映「Critic button isn't showing up properly」，提示在历史区段连续出现 Critic 评估事件时，按钮行的渲染顺序与历史轨迹存在竞争条件 [`GitHub #641`](https://github.com/OpenHands/OpenHands-CLI/issues/641)。

### 迭代优化流程

`refinement.py` 实现了 SDK 的 iterative-refinement 模式：

1. `should_trigger_refinement()` 综合「总分低于 critic_threshold」与「特定问题概率 ≥ issue_threshold」两种触发条件。
2. `get_high_probability_issues()` 从 `critic_result.metadata["categorized_features"]` 中抽取 `agent_behavioral_issues`，按概率倒序排列。
3. `build_refinement_message()` 生成给 Agent 的后续 prompt，包含 `iteration/max_iterations` 与具体的「Detected issues」清单 [`refinement.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/tui/utils/critic/refinement.py)。

整体流程可由下表描述：

```mermaid
flowchart LR
    A[Agent 完成任务] --> B[Critic 推理]
    B --> C{CriticResult.score}
    C -- 低于阈值 --> D[should_trigger_refinement]
    C -- 高概率 issue --> D
    D --> E[build_refinement_message]
    E --> F[追加 prompt 再次调用 Agent]
    F --> A
    B --> G[create_critic_collapsible]
    G --> H[CriticFeedbackWidget]
    H --> I[PostHog 埋点]
```

## 对话运行器与斜杠命令

`BaseOpenHandsACPAgent`（同时供 TUI 与 ACP 两种入口复用）承担对话运行器职责：它继承自 `ACPAgent`，在构造时接收 `initial_confirmation_mode` 与可选的 `resume_conversation_id`，并通过 `cloud_api_url` 默认指向 `https://app.all-hands.dev` [`base_agent.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/base_agent.py)。

斜杠命令相关能力由 `openhands_cli.acp_impl.slash_commands` 提供：

- `parse_slash_command()` 解析 `/confirm`、`/help` 等命令；
- `get_available_slash_commands()` 枚举当前可用命令；
- `apply_confirmation_mode_to_conversation()` / `validate_confirmation_mode()` 维护 `VALID_CONFIRMATION_MODE` 白名单；
- `handle_confirm_argument()` 与 `get_unknown_command_text()` 处理参数与未知命令 [`base_agent.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/base_agent.py)。

子类必须实现 `agent_type`、`_setup_conversation()`、`_cleanup_session()`、`_is_authenticated()` 与 `_get_or_create_conversation()`，从而支持本地与云端两种会话模式。

## ACP 适配层与端到端测试

为了让同一套对话运行器能在 Zed、VSCode 等遵循 [Agent Client Protocol](https://agentclientprotocol.com/) 的编辑器中使用，CLI 提供了 ACP 适配层：

- `convert_acp_prompt_to_message_content()` 将 ACP 的文本/图像/资源块转换成 SDK 的 `TextContent`/`ImageContent` [`convert.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/convert.py)。
- `convert_resources_to_content()` 处理 `ACPResourceContentBlock` 与 `ACPEmbeddedResourceContentBlock`，对图片自动尝试转换为受支持 MIME 类型，对失败或非图片资源落盘为嵌入文件 [`resources.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/resources.py)。
- `convert_acp_mcp_servers_to_agent_format()` 把 ACP 的 `McpServerStdio/HttpMcpServer/SseMcpServer` 列表转换为 Agent 使用的 `{name: {transport, env, ...}}` 字典 [`mcp.py`](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/mcp.py)。

社区长期关注的 ACP 支持（issue #66，17 条评论）正是通过这条路径落地的 [`GitHub #66`](https://github.com/OpenHands/OpenHands-CLI/issues/66)。

TUI 的端到端测试使用 [Mock LLM Server](https://github.com/OpenHands/OpenHands-CLI/blob/main/tui_e2e/README.md) 回放真实对话轨迹（trajectory）：将 `MessageEvent`、`ActionEvent` 等 JSON 文件依次注入 OpenAI 兼容的 `/chat/completions` 接口，由真正的 CLI 执行工具调用并校验结果。

## 已知 UX 问题与配置注意

- **终端状态泄漏**：部分命令退出后残留转义序列，用户需要执行 `reset` 或 `stty sane` 才能恢复 [`GitHub #671`](https://github.com/OpenHands/OpenHands-CLI/issues/671)。
- **本地 LLM 的 API Key 提示**：CLI 仍要求输入 API Key，而 GUI 已不再要求，对 Ollama 等本地模型用户造成困扰 [`GitHub #673`](https://github.com/OpenHands/OpenHands-CLI/issues/673)。
- **历史会话回放**：恢复的对话未将历史事件回填到 UI，相关讨论见 [`GitHub #204`](https://github.com/OpenHands/OpenHands-CLI/issues/204)。
- **MCP 服务器测试命令**：社区希望增加 `openhands mcp test <name>` 以验证配置 [`GitHub #694`](https://github.com/OpenHands/OpenHands-CLI/issues/694)。

## See Also

- [README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md) — 安装、配置与项目状态总览
- [openhands_cli/acp_impl/README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/README.md) — ACP 适配层与 Zed 集成指引
- [tui_e2e/README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/tui_e2e/README.md) — TUI 端到端测试与轨迹回放
- [Software Agent SDK 文档](https://docs.openhands.dev/sdk/guides/critic) — Critic 与迭代优化的上游模式

---

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

## ACP Server, Cloud Mode, MCP and Conversation Storage

### 相关页面

相关主题：[Configuration, Running Modes and CLI Surface](#page-2), [TUI System: Widgets, Modals, Conversation Runner and Critic](#page-3)

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

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

- [openhands_cli/acp_impl/README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/README.md)
- [openhands_cli/acp_impl/agent/base_agent.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/base_agent.py)
- [openhands_cli/acp_impl/agent/local_agent.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/local_agent.py)
- [openhands_cli/acp_impl/agent/remote_agent.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/remote_agent.py)
- [openhands_cli/acp_impl/agent/util.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/agent/util.py)
- [openhands_cli/acp_impl/utils/__init__.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/__init__.py)
- [openhands_cli/acp_impl/utils/mcp.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/mcp.py)
- [openhands_cli/acp_impl/utils/convert.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/convert.py)
- [openhands_cli/acp_impl/utils/resources.py](https://github.com/OpenHands/OpenHands-CLI/blob/main/openhands_cli/acp_impl/utils/resources.py)
- [README.md](https://github.com/OpenHands/OpenHands-CLI/blob/main/README.md)
</details>

# ACP Server, Cloud Mode, MCP and Conversation Storage

## 1. 概述与定位

OpenHands CLI 提供多种运行形态，包括本地交互式 TUI、无头模式、Agent Client Protocol (ACP) 服务端模式以及 OpenHands Cloud 云端模式。本页聚焦于 **ACP 服务端、云端模式、MCP 集成与会话存储**这四个紧密关联的能力子集，它们共同支撑 OpenHands CLI 与外部编辑器（如 Zed）或云端沙箱之间的对话编排。

ACP 是基于 JSON-RPC 2.0 的标准化协议，允许客户端（编辑器）与 AI 智能体通过统一接口进行通信。资料来源：[openhands_cli/acp_impl/README.md:1-9]()

OpenHands CLI 通过 `openhands acp` 子命令注册为 ACP 智能体，使其可被 Zed、VSCode 等支持 ACP 的编辑器加载并发起对话。资料来源：[openhands_cli/acp_impl/README.md:11-35]()

## 2. ACP 服务端架构

ACP 实现由 `openhands_cli/acp_impl/` 目录组织，核心入口负责启动 JSON-RPC 连接、注册协议能力并向客户端暴露会话管理接口。客户端通过 `uvx --from <repo> openhands acp` 启动本地实例，或通过 `uv run --project <path> openhands acp` 启动开发版本。资料来源：[openhands_cli/acp_impl/README.md:13-35]()

```mermaid
flowchart LR
  Client[ACP 客户端<br/>如 Zed] -->|JSON-RPC 2.0| Server[OpenHands ACP Server]
  Server --> LocalAgent[BaseOpenHandsACPAgent<br/>本地子]
  Server --> CloudAgent[OpenHandsCloudACPAgent<br/>云端子]
  LocalAgent --> Conversation[Local Conversation]
  CloudAgent --> Workspace[OpenHandsCloudWorkspace]
  Workspace --> Cloud[OpenHands Cloud]
  LocalAgent --> MCP[MCP Servers]
  CloudAgent --> MCP
```

`BaseOpenHandsACPAgent` 是本地与云端智能体的抽象基类，统一实现初始化、斜杠命令处理、确认模式应用以及会话管理。子类只需实现 `agent_type` 属性、`_setup_conversation()`、`_cleanup_session()`、`_is_authenticated()` 等差异点。资料来源：[openhands_cli/acp_impl/agent/base_agent.py:55-89]()

会话模式状态由 `get_session_mode_state()` 集中封装，便于 ACP 客户端查询当前 `ConfirmationMode`（如 `always-approve`、`llm-approve`）以及可用模式列表。资料来源：[openhands_cli/acp_impl/agent/util.py:13-21]()

## 3. 云端模式 (Cloud Mode)

`OpenHandsCloudACPAgent` 继承自 `BaseOpenHandsACPAgent`，其 `agent_type` 属性返回 `"remote"`，并通过 `OpenHandsCloudWorkspace` 与 OpenHands Cloud 服务建立远程对话通道。资料来源：[openhands_cli/acp_impl/agent/remote_agent.py:64-72]()

云端模式需要在启动前完成 OpenHands Cloud 身份认证。`_is_authenticated()` 通过调用 `is_token_valid()` 验证存储的 API Key 有效性。资料来源：[openhands_cli/acp_impl/agent/remote_agent.py:78-85]()

每个会话关联一个独立的 `OpenHandsCloudWorkspace` 实例，由 `_active_workspaces` 字典按 `session_id` 索引；`_cleanup_session()` 负责在会话结束时释放对应的工作区资源。资料来源：[openhands_cli/acp_impl/agent/remote_agent.py:87-95]()

用户通过 `openhands login` 完成认证后，可使用 `openhands cloud -t "..."` 直接在云端运行任务；ACP 场景下，编辑器会复用同一套云端基础设施。资料来源：[README.md:34-44]()

## 4. MCP 服务集成

ACP 与 OpenHands Agent 使用不同的 MCP 服务器配置格式：`convert_acp_mcp_servers_to_agent_format()` 负责将 ACP 列表式 Pydantic 模型转换为 Agent 字典式配置，并按服务器类型（`McpServerStdio` / `HttpMcpServer` / `SseMcpServer`）自动设置 `transport` 字段。资料来源：[openhands_cli/acp_impl/utils/mcp.py:48-80]()

环境变量在两种格式间需做特殊处理：ACP 发送 `[{name, value}, ...]` 数组，Agent 期望 `{name: value}` 字典；`_convert_env_to_dict()` 完成这一扁平化转换。资料来源：[openhands_cli/acp_impl/utils/mcp.py:19-32]()

非 MCP 资源（如图片、嵌入文件）由 `convert_resources_to_content()` 处理，支持的图像 MIME 类型可直接生成 `ImageContent`，否则尝试格式转换或回退到本地缓存目录 (`~/.openhands/cache/acp`) 中的临时文件。资料来源：[openhands_cli/acp_impl/utils/resources.py:25-92]()

CLI 自身提供 `openhands mcp list / add / enable / disable` 等命令管理本地 MCP 配置，社区正在请求新增 `openhands mcp test <name>` 子命令以验证服务器可用性。资料来源：[README.md:5-19](), 社区议题 #694

## 5. 会话存储与恢复

ACP 基类构造函数接受可选的 `resume_conversation_id` 参数，会话历史在云端由 `RemoteConversation` 自然持久化，编辑器可在用户重新打开对话时通过 `LoadSessionResponse` 拉取完整轨迹。资料来源：[openhands_cli/acp_impl/agent/base_agent.py:78-89](), [openhands_cli/acp_impl/agent/remote_agent.py:64-77]()

本地 TUI 模式下，已结束会话需要通过会话 ID 显式恢复；社区提议在会话结束时向用户输出 ID，并新增 `openhands history` 子命令以列出历史会话及其首条用户提示，相关讨论见议题 #101。

为确保向后兼容，1.15.0 版本起为已持久化的 `Delegate` 会话引入兼容性层；批评（critic）评分的可视化与按钮在恢复对话时也会被重新水合，避免出现“按钮错位或重复”这类 UI 缺陷（议题 #641）。资料来源：1.15.0 发布说明

## 6. 常见问题

- **macOS Gatekeeper 阻止运行**：从源码安装的 `openhands-macos` 二进制因未签名会被 macOS 拦截，议题 #89 跟踪此问题。资料来源：社区议题 #89
- **本地 LLM 不应要求 API Key**：CLI 在引导流程中强制要求 API Key，对使用 Ollama 等本地后端的用户造成困扰（议题 #673）。资料来源：社区议题 #673
- **退出后终端状态污染**：TUI 退出后可能残留 ANSI 转义序列，用户需手动执行 `reset` 或 `stty sane`（议题 #671）。资料来源：社区议题 #671

## See Also

- [MCP Servers 配置与子命令（社区文档）](https://docs.openhands.dev/openhands/usage/cli/mcp-servers)
- [Confirmation Modes 与斜杠命令](https://docs.openhands.dev/openhands/usage/cli/command-reference)
- [OpenHands Cloud CLI 使用指南](https://docs.openhands.dev/openhands/usage/cli/cloud)
- [Agent Client Protocol 协议规范](https://agentclientprotocol.com/protocol/overview)

---

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

---

## Doramagic 踩坑日志

项目：OpenHands/OpenHands-CLI

摘要：发现 13 个潜在踩坑项，其中 1 个为 high/blocking；最高优先级：安全/权限坑 - 来源证据：[Feature]: add `openhands mcp test <name>` to validate a configured MCP server。

## 1. 安全/权限坑 · 来源证据：[Feature]: add `openhands mcp test <name>` to validate a configured MCP server

- 严重度：high
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[Feature]: add `openhands mcp test <name>` to validate a configured MCP server
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/694 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

## 2. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `openhands-cli` 与安装入口 `openhands` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`uv tool install openhands`
- 证据：identity.distribution | github_repo:1049343369 | https://github.com/OpenHands/OpenHands-CLI | repo=openhands-cli; install=openhands

## 3. 安装坑 · 来源证据：[Bug]: Critic button isn't showing up properly

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[Bug]: Critic button isn't showing up properly
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/641 | 来源类型 github_issue 暴露的待验证使用条件。

## 4. 配置坑 · 来源证据：[UX] CLI does not clean up terminal state after exit, requiring manual reset

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[UX] CLI does not clean up terminal state after exit, requiring manual reset
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/671 | 来源类型 github_issue 暴露的待验证使用条件。

## 5. 能力坑 · 能力判断依赖假设

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

## 6. 维护坑 · 维护活跃度未知

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

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

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

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

## 9. 安全/权限坑 · 来源证据：[CLI] Feature Request: LLM Profile Management for OpenHands CLI

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[CLI] Feature Request: LLM Profile Management for OpenHands CLI
- 对用户的影响：可能影响升级、迁移或版本选择。
- 证据：community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/68 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

## 10. 安全/权限坑 · 来源证据：[M1] Plugin Loading and Command Invocation

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[M1] Plugin Loading and Command Invocation
- 对用户的影响：可能增加新用户试用和生产接入成本。
- 证据：community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/409 | 来源讨论提到 python 相关条件，需在安装/试用前复核。

## 11. 安全/权限坑 · 来源证据：[UX] API key still required in CLI when not needed for local LLMs

- 严重度：medium
- 证据强度：source_linked
- 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[UX] API key still required in CLI when not needed for local LLMs
- 对用户的影响：可能影响授权、密钥配置或安全边界。
- 证据：community_evidence:github | https://github.com/OpenHands/OpenHands-CLI/issues/673 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

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

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

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

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

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