项目概览与安装指南

1. 项目定位与目标

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

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

• tui/：基于 Textual 的终端用户界面，提供 Critic 可视化、对话历史渲染与可折叠面板等功能（参考 visualization.py）。
• acp_impl/：实现 Agent Client Protocol，允许在 Zed 等支持 ACP 的编辑器中以标准化 JSON-RPC 2.0 方式接入（参考 acp_impl/README.md）。
• setup/、auth/：负责首次运行时的 LLM 配置与身份令牌持久化。

2. 系统架构总览

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

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 会根据是否包含潜在问题决定是否展开面板。
• ACP 子系统的 BaseOpenHandsACPAgent 是抽象基类，封装了斜杠命令解析、MCP 服务转换、会话生命周期等通用逻辑。
• 用户反馈通过 CriticFeedbackWidget 上报至 PostHog，用于持续改进 Critic 预测质量。

3. 安装方式

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

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

需要 Python 3.12+ 以及 uv 0.11.6 或更高版本（README.md）：

uv tool install openhands --python 3.12

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

3.2 通过独立二进制安装

若不便配置 Python 环境，可使用安装脚本拉取预编译的 standalone 二进制（README.md）：

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

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

4. 首次运行与配置

首次执行 openhands 时，CLI 会引导用户完成 LLM 提供方、模型、API Key 等设置。配置数据默认存储在 ~/.openhands/ 目录下（README.md）：

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

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

5. 主要使用模式

5.1 交互式 TUI 模式

默认运行 openhands 即可进入基于 Textual 的 TUI。Critic 模块会针对每一次完成的任务生成 0–1 评分，并按照 get_high_probability_issues 提取高概率问题，触发迭代式 refinement 流程，将结果以可折叠面板呈现（参考 visualization.py）。

5.2 ACP 编辑器集成模式

通过 openhands acp 启动 ACP 服务，编辑器（如 Zed）即可通过 JSON-RPC 与之通信。开发者可在 Zed 中配置如下 agent 启动方式（acp_impl/README.md）：

"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 转换为 SDK 可识别的 TextContent 与 ImageContent，MCP 服务器配置则通过 convert_acp_mcp_servers_to_agent_format 完成格式适配。

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

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

6. 端到端测试与开发

tui_e2e/ 目录提供了基于轨迹回放的端到端测试框架，使用 mock LLM 服务器 按顺序重放 ActionEvent 与 MessageEvent，让真实 CLI 实际执行工具调用并校验输出。该机制让 TUI 行为变更可被精确回归测试。

参见

• TUI 与 Critic 可视化
• ACP 协议集成
• MCP 服务器配置
• 上游项目 OpenHands
• Agent Client Protocol 官方文档

1. 概览

OpenHands-CLI 是 OpenHands V1 在终端场景下的入口，它既是一个交互式 TUI（基于 Textual）客户端，也可以作为 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 以 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）：

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

3. CLI Surface 与子命令

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

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
• OpenHands Software Agent SDK
• CLI Command Reference
• MCP Servers
• Headless Mode
• Cloud Conversations

概述与定位

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

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

Critic 评分可视化与反馈系统

Critic 子系统位于 openhands_cli/tui/utils/critic/，由四个模块构成：

可视化组件

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。

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

用户反馈埋点

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

社区 issue #641 反映「Critic button isn't showing up properly」，提示在历史区段连续出现 Critic 评估事件时，按钮行的渲染顺序与历史轨迹存在竞争条件 GitHub #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。

整体流程可由下表描述：

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。

斜杠命令相关能力由 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。

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

ACP 适配层与端到端测试

为了让同一套对话运行器能在 Zed、VSCode 等遵循 Agent Client Protocol 的编辑器中使用，CLI 提供了 ACP 适配层：

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

社区长期关注的 ACP 支持（issue #66，17 条评论）正是通过这条路径落地的 GitHub #66。

TUI 的端到端测试使用 Mock LLM Server 回放真实对话轨迹（trajectory）：将 MessageEvent、ActionEvent 等 JSON 文件依次注入 OpenAI 兼容的 /chat/completions 接口，由真正的 CLI 执行工具调用并校验结果。

已知 UX 问题与配置注意

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

See Also

• README.md — 安装、配置与项目状态总览
• openhands_cli/acp_impl/README.md — ACP 适配层与 Zed 集成指引
• tui_e2e/README.md — TUI 端到端测试与轨迹回放
• Software Agent SDK 文档 — Critic 与迭代优化的上游模式

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

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 配置与子命令（社区文档）
• Confirmation Modes 与斜杠命令
• OpenHands Cloud CLI 使用指南
• Agent Client Protocol 协议规范

Pitfall Log / 踩坑日志

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