Open API（非 Agent 直调）

用普通 HTTP 请求驱动语言驱动平台的 RPA 能力——适合没有 AI Agent 在环的调用方：

调用方	场景
业务系统 / 后端服务	订单触发自动化、夜间数据同步等系统级联动
脚本 / 定时任务	cron、Shell、Python 脚本直接跑现成应用
客户自建系统	把平台的自动化能力嵌入自己的产品

如果你是AI Agent 平台（Claude Code / 扣子 / WorkBuddy 等）接入，请用 AI 集成的 MCP 方式——本页接口与 MCP 运行视图的工具一一对应（URL 即工具名，参数键名、返回结构完全一致），两边文档可互相参照。

认证

Open API 使用 API 密钥认证（与 MCP 相同的密钥）：

打开 langdriver-pc 客户端，点击右上角用户名 → API 密钥
输入名称（建议按用途命名，如 订单系统）→ 新建密钥
弹窗展示完整密钥（ldk_ 开头）→ 立即复制保存——关闭后无法再次查看

所有请求携带（推荐 Authorization 头；X-API-Key 头在部分网关/转发环境会被丢弃导致 401）：

bash

-H "Authorization: Bearer ldk_你的密钥"

密钥长期有效、可随时吊销（吊销后该密钥的所有调用立即 401）
控制台登录 JWT 也可用（调试方便），但 API 密钥是服务器间集成的推荐方式
完整密钥仅创建时展示一次，遗忘只能吊销后重建

快速开始

三步跑通一个应用任务（环境变量 BASE 为服务端地址）：

bash

BASE="https://langdriver.com"
KEY="ldk_你的密钥"

# 1. 确认目标在线（android 设备 / web 浏览器账号 / desktop 客户端）
curl -s "$BASE/api/open/v1/list_online_devices" -H "Authorization: Bearer $KEY"

# 2. 查应用清单，拿到 app_id 和参数定义（param_schema）
curl -s "$BASE/api/open/v1/list_apps?platform=web" -H "Authorization: Bearer $KEY"

# 3. 启动任务（一步创建+派发）
curl -s -X POST "$BASE/api/open/v1/start_task" \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"app_id": 123, "params": {"targetAppAccount": "我的抖音账号", "keyword": "RPA"}}'

# 4. 轮询状态（约每 15 秒一次，直到终态 completed/failed/stopped）
curl -s "$BASE/api/open/v1/get_task_status?task_instance_id=456" -H "Authorization: Bearer $KEY"

# 5. 拉取结构化输出
curl -s "$BASE/api/open/v1/get_task_output?task_instance_id=456" -H "Authorization: Bearer $KEY"

接口清单

接口	方法 + 路径	对应 MCP 工具
应用清单	`GET /api/open/v1/list_apps`	list_apps
在线设备	`GET /api/open/v1/list_online_devices`	list_online_devices
启动任务	`POST /api/open/v1/start_task`	start_task
任务状态	`GET /api/open/v1/get_task_status`	get_task_status
任务输出	`GET /api/open/v1/get_task_output`	get_task_output
停止任务	`POST /api/open/v1/stop_task`	stop_task

应用清单

GET /api/open/v1/list_apps?platform=android（platform 可选：android / web / desktop / multi，缺省返回全部）

返回每个应用的 id、name、platform、task_type、site、description 与 param_schema（运行参数的 JSON Schema 定义——启动任务前照它填 params）。

在线设备

GET /api/open/v1/list_online_devices

返回当前在线的 Android 设备、Web 浏览器账号（站点:账号 名单）与桌面客户端。启动任务前先确认目标就绪；账号/设备名必须与返回值一字不差。

启动任务

POST /api/open/v1/start_task，JSON body：

字段	必填	说明
`app_id`	是	应用 ID（number）
`params`	否	运行参数对象，按 `param_schema` 填写；web 任务须含 `targetAppAccount`（浏览器账号名）
`device_udid`	视平台	android 任务必填；web/desktop 不需要

json

{
  "app_id": 123,
  "params": { "targetAppAccount": "我的抖音账号", "keyword": "RPA" },
  "device_udid": "Android 设备UDID"
}

json

{
  "task_instance_id": 456,
  "status": "running",
  "task_type": "app",
  "device_udid": "web",
  "created_at": "2026-09-28T10:00:00Z",
  "dispatched": true
}

dispatched: true 才代表任务已真正推送到客户端执行。创建+派发是同步一步完成：客户端不在线、设备不在线、账号名不匹配时直接返回错误（任务即时置为 failed 并带真实原因），不会留下"显示运行中却无人执行"的僵尸任务。

任务状态

GET /api/open/v1/get_task_status?task_instance_id=456

返回 status / error_message。状态流转：pending → running → stopping → 终态（completed / failed / stopped）。约每 15 秒轮询一次即可。

任务输出

GET /api/open/v1/get_task_output?task_instance_id=456&page=1&page_size=50

分页返回输出列表，每条含 entity_type（实体类型）与 data（JSON 数据）。终态后再拉取。

停止任务

POST /api/open/v1/stop_task，body {"task_instance_id": 456}。仅 running / pending 状态可停止。

错误形态

非 2xx 时返回 HTTP 状态码 + 错误信息：

状态码	含义
400	参数缺失/类型错误（如缺 `app_id`、`params` 填错）
401	凭证缺失、密钥无效或已吊销
404	应用/任务不存在（含查他人任务——所有权校验）
409	冲突（设备被其他任务占用、分发失败、状态不允许停止等）

运行前提

客户端在线：任务由服务端推送给 langdriver-pc 客户端执行，客户端须已登录在线
设备/账号就绪：Android 任务需设备已连接；Web 任务需浏览器账号已添加且名称精确匹配
Token 余额充足：任务执行消耗 Token，余额不足任务会自动停止

常见问题

报 401？ 确认 Authorization: Bearer ldk_... 完整（含 Bearer 前缀，整段粘贴）；密钥未被吊销。用 JWT 调试时注意改密后旧 JWT 失效。

启动任务返回"分发失败"？ 客户端不在线、设备不在线或账号名不匹配。先调 list_online_devices 核对目标名，一字不差后重试。

web 任务必填什么参数？ params.targetAppAccount（浏览器账号名），按站点:账号精确路由；运行期可用 params.targetSite 覆盖应用登记的站点。

和 MCP 怎么选？ 有 LLM Agent 在环（要模型自己决策编排）用 MCP；固定流程的系统/脚本调用用本页 Open API。两者能力同源、互不冲突，也可混用。

Open API（非 Agent 直调） ​

认证 ​

快速开始 ​

接口清单 ​

应用清单 ​

在线设备 ​

启动任务 ​

任务状态 ​

任务输出 ​

停止任务 ​

错误形态 ​

运行前提 ​

常见问题 ​