Operit 局域网 External HTTP Chat API 实战指南：从鉴权到同步/SSE/异步回调三种调用模式

AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载本指南以 docs/doc-src/feature-protocol/external_http_chat.md 为核心完整讲解 Operit 内置的局域网 HTTP 聊天接口如何在应用内启用服务、如何配置 Bearer Token 鉴权、如何用curl完成同步调用、SSE 流式调用与异步回调三种模式并深入其底层实现源码说明每个参数的语义与生效条件。读完本文你可以在同一局域网内的电脑、脚本或另一台设备上以标准 HTTP/JSON 方式向 Operit 发送消息并取回 AI 回复为自动化集成、本地工作流或外部控制台提供统一的调用入口。1. 接口定位HTTP 版的外部聊天入口External HTTP Chat API 是 Operit 新增的局域网 HTTP 聊天接口。它与现有的EXTERNAL_CHATIntent 广播接口协议说明见 external_intent_chat.md语义完全一致——复用相同的请求字段与行为规则只是入口从 Android 广播换成了 HTTP 端点。也就是说凡是广播接口能做的事发消息、新建对话、启动浮窗、过滤工具状态等HTTP 接口都能以更通用的方式做到便于任何支持 HTTP 的语言与平台接入。从源码结构看整个能力由三部分组成服务器实现ExternalChatHttpServer.kt基于 NanoHTTPD 监听端口、分发路由请求模型与执行器ExternalChatModels.kt、ExternalChatRequestExecutor.kt负责解析 JSON 请求并调度聊天配置存储ExternalHttpApiPreferences.kt通过 DataStore 持久化开关、端口与 Token。2. 启用方式与监听配置在应用内依次进入设置 → 数据和权限 → 外部 HTTP 调用然后打开启用开关记录页面展示的监听地址与 Bearer Token页面会根据当前设备的局域网 IPv4 地址自动生成形如http://192.168.x.x:8094的访问地址列表见 ExternalHttpChatSettingsScreen.kt如有需要修改端口并保存。默认端口为8094。在源码中该默认值定义于 ExternalHttpApiPreferences.ktDEFAULT_PORT 8094端口合法范围校验为1..65535isValidPort。服务器监听地址为0.0.0.0见ExternalChatHttpServer.kt的LISTEN_HOST因此同一局域网内的其他设备均可访问。启用后服务器以NanoHTTPD启动路由分发逻辑位于serve()方法GET /api/health→ 健康检查POST /api/external-chat→ 聊天调用OPTIONS→ CORS 预检其余/api/*未知路径 →404API endpoint not found此外同一端口还承载了 Web 聊天静态页面与api/web/*接口以及 A2A/a2a与/.well-known/agent-card.json见 external_a2a_server.md。3. 鉴权Bearer Token除OPTIONS预检请求外所有请求都必须携带Authorization: Bearer YOUR_TOKENBearer Token 在首次启用时自动生成也可以在设置页里手动重置。源码中的ensureBearerToken()/resetBearerToken()使用UUID.randomUUID().toString().replace(-, )生成 32 位十六进制串经 DataStore 持久化external_http_api_preferences键external_http_api_bearer_token。服务端的校验逻辑位于requireBearerToken()Token 为空时返回401 Bearer token not configured请求头非Bearer前缀或 Token 不匹配时返回401 Unauthorized。Authorization头解析时对大小写不敏感ignoreCase true。注意该接口为局域网明文 HTTPToken 仅用于避免局域网内随意调用并不提供传输加密。如涉及敏感数据建议仅在可信网络中使用。4. 接口总览接口方法说明/api/healthGET检查服务联通性与鉴权是否正常/api/external-chatPOST发送聊天请求同步 / SSE 流式 / 异步回调4.1 健康检查GET /api/health用于验证服务是否可达、鉴权是否配置正确。对应实现返回ExternalChatHealthResponse其中enabled取自定义配置、service_running固定为true服务器在运行才可能响应、port为当前监听端口、version_name来自BuildConfig.VERSION_NAME。curl -H Authorization: Bearer YOUR_TOKEN http://DEVICE_IP:8094/api/health返回示例{ status: ok, enabled: true, service_running: true, port: 8094, version_name: 1.10.01 }4.2 请求体字段POST /api/external-chat请求体为 JSON字段复用现有 Intent 接口语义与 external_intent_chat.md 的 extras 一一对应完整字段见ExternalChatHttpRequest字段类型默认值说明request_idString自动生成 UUID业务侧请求 ID原样回传便于关联请求/响应messageString必填要发送给 AI 的文本为空则返回400 Missing extra: messagegroupString-create_new_chattrue时用于新对话分组create_new_chatBooleanfalse是否强制创建新对话再发送消息chat_idString-指定发送到某个对话仅create_new_chatfalse时生效create_if_noneBooleantrue未指定chat_id且当前没有对话时是否自动创建false且无对话则失败show_floatingBooleanfalse是否启动/显示悬浮窗服务FloatingChatServicereturn_tool_statusBooleantrue是否返回工具状态相关内容false时移除tool*、tool_result*、status辅助内容initial_modeString沿用上次/WINDOW浮窗初始模式仅show_floatingtrue时有意义auto_exit_after_msLong-1show_floatingtrue时自动退出/关闭浮窗的超时毫秒数timeout_msLong-1聊天超时毫秒数HTTP 接口新增stop_afterBooleanfalse本次请求结束后是否停止聊天服务HTTP 接口新增字段字段类型默认值说明streamBooleanfalsetrue时改为按 SSE 分块返回response_modeStringsyncsync或async_callback解析不区分大小写callback_urlString-response_modeasync_callback时必填且必须为http/https补充说明均有源码支撑return_tool_status默认为true设为false时外部返回中的tool*、tool_result*、status会被过滤减小ai_response与 SSEdelta的传输体积。实现位于 ExternalChatResponseSanitizer.kt通过 XML 流切分识别标签名并剔除上述三类同时压缩多余空行initial_mode仅在show_floatingtrue时有意义可选值WINDOW、BALL、VOICE_BALL、FULLSCREEN、RESULT_DISPLAY、SCREEN_OCR如果show_floatingtrue且未传initial_mode则沿用当前/上次保存的浮窗模式首次默认WINDOWstreamtrue与response_modeasync_callback不能同时使用同时出现返回400 Bad Request错误文案Invalid parameter: streamtrue is not compatible with async_callbackresponse_mode非法值返回400 Invalid parameter: response_mode must be sync/async_callbackasync_callback缺少callback_url返回400 callback_url is required for async_callback非http/https返回400 callback_url must be http/httpsmessage缺失返回400 Missing extra: message。5. 同步调用response_modesync同步模式会阻塞请求直到聊天完成一次性返回完整 JSON。示例curl -X POST http://DEVICE_IP:8094/api/external-chat \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/json; charsetutf-8 \ -d { message: 你好帮我总结今天的待办, response_mode: sync, show_floating: true, return_tool_status: false, initial_mode: WINDOW }返回示例{ request_id: f0fdde0c-3f68-43c1-ae43-9d7736d6fd7d, success: true, chat_id: 1742558116153, ai_response: 这是今天的待办总结…… }如果请求本身格式正确但聊天执行失败也会返回同结构 JSON只是success false且error携带失败原因。从源码看服务端通过runBlocking调用ExternalChatRequestExecutor.execute()后者内部先做prepareRequest校验消息、按需启动浮窗、按需建会话再调用StandardChatManagerTool.sendMessageToAI最后经ExternalChatResponseSanitizer处理返回。6. SSE 流式返回streamtrue当streamtrue时接口返回text/event-stream每个分块都是标准 SSE 格式便于实时展示增量输出。示例curl -N -X POST http://DEVICE_IP:8094/api/external-chat \ -H Authorization: Bearer YOUR_TOKEN \ -H Accept: text/event-stream \ -H Content-Type: application/json; charsetutf-8 \ -d { message: 请一步步解释这个问题, stream: true, show_floating: true, return_tool_status: false, initial_mode: WINDOW }返回事件类型start已接受请求并拿到chat_iddelta本次增量文本done全部完成ai_response为完整结果error处理失败。返回示例event: start data: {event:start,request_id:req-001,chat_id:1742558116153} event: delta data: {event:delta,request_id:req-001,chat_id:1742558116153,delta:你好} event: delta data: {event:delta,request_id:req-001,chat_id:1742558116153,delta:下面我来解释。} event: done data: {event:done,request_id:req-001,chat_id:1742558116153,success:true,ai_response:你好下面我来解释。}错误示例event: error data: {event:error,request_id:req-001,success:false,error:Invalid parameter: streamtrue is not compatible with async_callback}注意事项SSE 模式下建议显式发送Accept: text/event-stream连接关闭后服务端会尝试取消这次 AI 响应。这在源码中有明确实现SSE 响应使用PipedInputStream/PipedOutputStream管道流通过FilterInputStream.close()在客户端断开时调用streamJob.cancel()并取消底层responseStreamSession避免后台继续空跑消耗算力服务端对text/event-stream响应禁用 gzipuseGzipWhenAccepted并附带Cache-Control: no-cache、Connection: keep-alive、X-Accel-Buffering: no头保证流式实时性响应为 chunked 编码start事件在executor.startStreaming()成功返回Started后立即下发delta逐块透传每条data:行内的换行会被拆分为多个data:行以符合 SSE 规范done在流结束后携带完整ai_response。7. 异步回调response_modeasync_callback异步模式立即返回已接受AI 完成后 Operit 主动向callback_url推送结果适合不希望长期占用 HTTP 连接的业务场景。示例curl -X POST http://DEVICE_IP:8094/api/external-chat \ -H Authorization: Bearer YOUR_TOKEN \ -H Content-Type: application/json; charsetutf-8 \ -d { message: 继续刚才的话题, response_mode: async_callback, callback_url: http://YOUR_PC:8080/callback }立即返回{ request_id: dca1a2e0-8f7e-4bf8-9523-a4b7bdf2fd13, accepted: true, status: accepted }AI 完成后Operit 会向callback_url发送一次POST application/json回调请求体仍然是{ request_id: dca1a2e0-8f7e-4bf8-9523-a4b7bdf2fd13, success: true, chat_id: 1742558116153, ai_response: …… }注意JSON 请求体默认按 UTF-8 处理建议显式发送Content-Type: application/json; charsetutf-8。源码中resolveRequestCharset()会从Content-Type中解析charset解析失败或缺失时回退到 UTF-8application/json规范默认 UTF-8v1 不做重试callback 非 2xx 或网络失败只记日志不自动补发。实现见postCallback()使用 OkHttpClientretryOnConnectionFailure(false)即不自动重连执行一次POST非成功响应或异常仅写入AppLogger警告/错误日志。8. 行为语义总表与 Intent 接口保持一致条件行为show_floatingtrue尝试启动FloatingChatServiceManifest 中注册于app/src/main/AndroidManifest.xml的.services.FloatingChatServiceshow_floatingtrueinitial_mode按该模式启动浮窗WINDOW/BALL/VOICE_BALL/FULLSCREEN/RESULT_DISPLAY/SCREEN_OCRshow_floatingtrue未传initial_mode沿用当前/已保存模式首次默认WINDOWcreate_new_chattrue先创建新对话可带group再发送此时忽略chat_idchat_id仅在create_new_chatfalse时生效发送时作为chat_id参数传入create_if_nonefalse且当前无对话返回失败错误No current chat and create_if_nonefalsestop_aftertrue请求结束后尝试停止聊天服务执行器 cleanup 阶段调用stop_chat_servicereturn_tool_statusfalse过滤工具状态相关 XMLtool/tool_result/status减小ai_response/SSEdelta体积streamtrue响应改为 SSE不再返回单个固定 JSON 响应体streamtrueresponse_modeasync_callback返回400 Bad Request这些语义与现有EXTERNAL_CHATIntent 接口保持一致可对照 external_intent_chat.md 中的参数表交叉验证。执行器源码prepareRequest()中的先后顺序为校验message→show_floating时启动聊天服务并注入initial_mode/timeout_ms→create_if_nonefalse且无chat_id时检查当前会话存在性 →create_new_chat时创建新对话 → 组装send_message_to_ai工具参数message、可选chat_id、可选timeout_ms→ 执行 →stop_after时停止服务。9. 设置页内置的快捷示例设置页 ExternalHttpChatSettingsScreen.kt 会根据当前设备 IP 与端口动态生成可直接复制的curl示例syncCurl、asyncCurl、healthCurl并展示 Web 入口/、Web API/api/与 A2A Agent Card/.well-known/agent-card.json地址方便在启用服务后立即本地调试同步示例curl -X POST http://ip:8094/api/external-chat -H Authorization: Bearer token ... -d {message:你好,response_mode:sync,show_floating:true,initial_mode:WINDOW,return_tool_status:false}异步示例... -d {message:你好,response_mode:async_callback,callback_url:http://YOUR_PC:8080/callback}健康检查curl -H Authorization: Bearer token http://ip:8094/api/health另外服务端为所有 API 响应都附加了 CORS 头Access-Control-Allow-Origin: *、Access-Control-Allow-Methods: GET, POST, PATCH, DELETE, OPTIONS、Access-Control-Allow-Headers: Authorization, Content-Type, Accept、Access-Control-Max-Age: 3600因此浏览器端脚本例如自建的 Web 调试页也可以直接跨域调用该接口。10. 常见问题排查401 Unauthorized确认Authorization头格式为Bearer token且 Token 与设置页一致Token 可在设置页重置后更新调用方。400 Missing extra: message请求体缺少或为空message。400 Invalid parameter: response_mode must be sync/async_callbackresponse_mode拼写错误或使用了未支持的值。400 Invalid parameter: callback_url is required...async_callback模式下漏传callback_url。400 Invalid parameter: streamtrue is not compatible with async_callbackstream与异步回调不能共存。404 API endpoint not found路径写错正确路径为/api/health与/api/external-chat。连接超时确认调用方与手机处于同一局域网且设置了正确端口服务器监听0.0.0.0无需额外内网穿透。Content-Length缺失导致请求体读取失败HTTP 客户端需正确设置Content-Lengthcurl -d会自动处理服务端据此读取请求体见readRequestBody()。本文涉及的协议文档与实现源码均位于当前仓库external_http_chat.md、external_intent_chat.md、ExternalChatHttpServer.kt、ExternalChatModels.kt、ExternalChatRequestExecutor.kt、ExternalChatResponseSanitizer.kt、ExternalHttpApiPreferences.kt。赞分享AI Agent人工智能大模型AI 应用工具调用本地部署MCP ClientsAgent 记忆【免费下载链接】OperitThe most powerful AI agent and AI chat software on Android/Operit是一款Android上能力最为强大、发展最久的AI Agent项目地址https://gitcode.com/gh_mirrors/op/Operit点击查看免费下载相关推荐Cog HTTP API 实战指南同步/异步预测、SSE 流式输出、Webhook 回调与文件上传Cog HTTP API 实战指南同步/异步预测、SSE 流式输出、Webhook 回调与文件上传 Cog 构建的 Docker 镜像在启动后会内置一个完整的MLOps容器模型推理服务开发工具CubeSandbox 鉴权配置指南Cube API Server 回调式鉴权与密钥鉴权实战CubeSandbox 鉴权配置指南Cube API Server 回调式鉴权与密钥鉴权实战 导读 本文以 CubeSandbox 项目中 Cube APIAgent 沙箱虚拟化云原生人工智能后端容器运行时SOFARPC调用方式完全掌握同步、异步、回调、泛化调用实战SOFARPC调用方式完全掌握同步、异步、回调、泛化调用实战 SOFARPC是一款高性能、高扩展性的生产级Java RPC框架提供了丰富的服务调用方式包括后端RPC框架微服务服务注册发现负载均衡上一篇Trellis Channel Workers 完整实战指南spawn 派生、Agent Cards、上下文注入与中断控制下一篇RePKG终极指南轻松提取Wallpaper Engine壁纸素材的完整教程 创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考