用途:记录 OpenHands Cloud API V1,并提供极简 Python 客户端(OpenHandsV1API),默认面向 OpenHands Cloud(https://app.all-hands.dev),调用 /api/v1/... 应用服务器 REST 接口,同时也包含少量沙箱内 agent server 接口。
主要能力:校验认证并查看账户(GET /api/v1/users/me);搜索/批量获取/统计对话;启动新对话(会创建沙箱);查询异步启动任务状态;读取与统计对话事件;列出沙箱并暂停/恢复;下载轨迹 zip;通过 agent server 执行 bash、上传下载文件、查询对话事件。
认证:应用服务器用 Bearer 认证,请求头 Authorization: Bearer <OPENHANDS_API_KEY>,读取环境变量 OPENHANDS_API_KEY。沙箱内 agent server 用会话认证,请求头 X-Session-API-Key: <session_api_key>,其地址形如 {agent_server_url}/api/...。获取方式通常是先通过应用服务器启动或获取对话,再从返回 JSON 中查找 sandbox 的 agent_server_url 与会话密钥;若字段缺失,可用 GET /api/v1/sandboxes/search 定位。
常见陷阱:POST /api/v1/app-conversations 通常是异步的,返回 start-task 对象,其 id 是 start_task_id,app_conversation_id 才是对话操作应使用的 id;若初始响应没有它,用 GET /api/v1/app-conversations/start-tasks?ids=<start_task_id> 获取。把 start_task_id 传给 /download 会返回 404。事件 id 为 UUID,并非递增整数,不能用最后一个事件 id 推断事件总数;统计事件推荐用应用服务器或 agent server 的 events/count,也可用轨迹 zip 解压后统计 event_*.json。
用法:把 skills/openhands-api-v1/scripts/openhands_api_v1.py 复制进项目后导入 OpenHandsV1API;CLI 可执行 search-conversations、start-conversation 等命令,例如 python skills/openhands-api-v1/scripts/openhands_api_v1.py search-conversations --limit 5。
限制与建议:优先使用带小 limit 的 search 接口,避免大量 API 调用的循环;仅在确有需要时启动对话,因为可能创建沙箱并产生费用;沙箱文件操作与命令执行走 agent server 接口。资料未提供具体定价、配额或平台支持范围。