LocalGPT HTTP API参考：daemon守护进程、SSE流式对话与内嵌Web UI的集成开发指南-开发者社区

【免费下载链接】localgpt

Local AI assistant, dreaming explorable worlds.

项目地址：https://gitcode.com/gh_mirrors/localgp/localgpt

LocalGPT 是一个运行在本地的 AI 助手，它不仅支持聊天，还能生成并探索可交互的 3D 世界。当你以daemon（守护进程）模式启动它时，LocalGPT 会内置一个 HTTP API 服务与浏览器 Web UI，让你可以用curl、脚本或任何语言快速接入：健康检查、会话管理、SSE 流式对话、记忆检索，甚至 OpenAI 兼容接口，一应俱全。本文带你从零启动 daemon，逐个看懂 HTTP API 端点，并掌握 SSE 流式对话与内嵌 Web UI 的集成方法。

为什么用 daemon 模式？

LocalGPT 的默认形态是命令行交互，但如果你希望：

让 AI 助手常驻后台，随时通过 HTTP 调用；
在浏览器中打开一个开箱即用的 Web UI；
把 LocalGPT 当作OpenAI 兼容端点，接入 Cursor、Continue 等工具；

那么 daemon 模式就是正确选择。一条命令即可启动：

localgpt daemon start

启动后服务默认监听http://127.0.0.1:31327，终端会打印 PID 文件、日志文件与服务地址。daemon 通过 Unix 系统的 fork 机制转入后台（Windows 上以前台方式运行），并自动完成三件事：

初始化记忆索引（MemoryManager）并启动文件监听；
注册心跳（heartbeat）定时任务与会话清理；
启动 axum HTTP 服务器，同时服务 REST API 与内嵌 Web UI。

常用 daemon 管理命令

命令	作用
`localgpt daemon start`	后台启动守护进程
`localgpt daemon start --foreground`	前台运行，方便看日志调试
`localgpt daemon status`	查看运行状态（PID、服务地址等）
`localgpt daemon stop`	发送 SIGTERM 优雅停止
`localgpt daemon restart`	先停后启
`localgpt daemon heartbeat`	手动触发一次心跳（测试用）

完整命令定义见 DaemonCommands。如果进程卡死，stop命令会等待 5 秒并清理残留的 PID 文件，基本无需手动干预。

HTTP API 核心端点速览

所有 API 都挂在同一个端口下，按「会话 → 对话 → 记忆 → 系统」四层组织，完整路由注册在 http.rs。

1️⃣ 系统层：健康检查与状态

# 服务是否存活 curl http://localhost:31327/health # 版本、当前模型、记忆分块数、活跃会话数 curl http://localhost:31327/api/status

/api/status的响应示例：

{ "version": "0.1.3", "model": "claude-cli/opus", "memory_chunks": 156, "active_sessions": 3, "is_brand_new": false }

2️⃣ 会话层：多轮对话的生命周期

LocalGPT 的对话基于会话（session），API 会自动创建并缓存会话（上限 100 个，30 分钟不活跃自动过期，每 5 分钟落盘一次，重启后自动恢复）：

# 创建会话 curl -X POST http://localhost:31327/api/sessions # 列出会话 / 删除会话 curl http://localhost:31327/api/sessions curl -X DELETE http://localhost:31327/api/sessions/<id> # 查看历史消息、压缩上下文、清空、切换模型 curl http://localhost:31327/api/sessions/<id>/messages curl -X POST http://localhost:31327/api/sessions/<id>/compact curl -X POST http://localhost:31327/api/sessions/<id>/clear curl -X POST http://localhost:31327/api/sessions/<id>/model

3️⃣ 对话层：一次性回复与流式回复

一次性回复（POST /api/chat）适合简单集成：

curl -X POST http://localhost:31327/api/chat \ -H "Content-Type: application/json" \ -d '{"message": "用一句话解释 Rust 的所有权", "include_memory": true}'

请求参数支持message（必填）、model（覆盖默认模型）、include_memory（默认true，注入记忆上下文）、session_id（复用指定会话）。响应包含完整response、token 用量和tools_used列表。

流式回复（POST /api/chat/stream）则是重点，详见下一节。

4️⃣ 记忆层：搜索与统计

# 全文检索记忆索引（默认返回 10 条） curl "http://localhost:31327/api/memory/search?q=rust%20async&limit=5" # 记忆系统统计：文件数、分块数、索引时间 curl http://localhost:31327/api/memory/stats # 手动重建索引 curl -X POST http://localhost:31327/api/memory/reindex

5️⃣ 运维层：日志与配置

# 直接读取 daemon 最近 200 行日志 curl "http://localhost:31327/api/logs/daemon?lines=200" # 读取 / 修改运行时配置（如默认模型、端口、心跳间隔） curl http://localhost:31327/api/config curl -X POST http://localhost:31327/api/config \ -d '{"agent.default_model": "claude-cli/opus"}'

SSE 流式对话：事件类型全解析

POST /api/chat/stream返回标准的Server-Sent Events（SSE）流，是构建聊天界面的最佳方式。实现位于 chat_stream，浏览器里甚至可以直接用fetch逐行解析（Web UI 本身就是这么做的，见 app.js）。

流中依次会出现以下 JSON 事件：

事件类型	含义	关键字段
`session`	流的第一个事件，告知会话 ID	`session_id`
`content`	模型输出的文本增量	`delta`
`tool_start`	AI 开始调用工具	`name`、`id`、`detail`
`tool_end`	工具执行完毕	`name`、`id`、`output`、`warnings`
`approval_required`	危险操作需要人工审批	`request_id`、`tool_name`、`level`
`done`	本轮回复结束	—
`[DONE]`	SSE 流的结束哨兵	—

用curl实测一条流（注意-N禁用缓冲）：

curl -N -X POST http://localhost:31327/api/chat/stream \ -H "Content-Type: application/json" \ -d '{"session_id": "my-session-1", "message": "列出当前目录的文件"}'

你会看到类似这样的输出：

data: {"type":"session","session_id":"my-session-1"} data: {"type":"tool_start","name":"bash","id":"t1","detail":"ls ~/project"} data: {"type":"tool_end","name":"bash","id":"t1","output":"..."} data: {"type":"content","delta":"目录下共有 3 个文件..."} data: {"type":"done"} data: [DONE]

💡集成提示：收到approval_required时，可以通过POST /api/sessions/<id>/approve审批该工具调用，这在把 LocalGPT 接入自动化流水线时非常有用。除了 SSE，服务端还提供GET /api/wsWebSocket 端点，适合需要双向通信的场景。

内嵌 Web UI：浏览器里的完整控制台

Web UI 以静态资源形式编译进二进制（rust-embed嵌入 ui/ 目录），不依赖任何额外部署。启动 daemon 后，直接访问：

http://127.0.0.1:31327/

页面提供四个核心面板：

聊天主界面：底部输入框 + 消息流，支持/help等命令，实时渲染 SSE 事件（包括工具调用过程）；
Sessions 面板：查看已保存的历史会话、回看完整消息记录；
Logs 面板：实时拉取 daemon 日志，支持自动刷新；
Settings 面板：在线修改默认模型、服务端口、心跳间隔、日志级别，走POST /api/config即时生效；
Status 面板：聚合展示版本、模型、会话数、心跳状态与 Bridge 通道健康度。

整个 UI 由三个文件构成：index.html、app.js、style.css，逻辑轻、零依赖，非常适合作为「最小化 Web 控制台」的参考实现。

配置与安全：内网暴露的正确姿势

服务器参数集中在配置文件[server]段（样例见 config.example.toml）：

[server] enabled = true # 是否启用 HTTP 服务 port = 31327 # 监听端口 bind = "127.0.0.1" # 绑定地址

几个安全要点：

默认只绑定127.0.0.1，仅本机可访问——这是无鉴权设计下的第一道防线；如需跨设备访问，改为0.0.0.0并务必配置 token；
可选 Bearer Token 鉴权：设置auth_token后，所有/api/*与/v1/*请求必须携带Authorization: Bearer <token>（采用常量时间比较防时序攻击，见 auth_middleware）；
CORS 默认只放行 localhost 来源，可通过cors_origins白名单扩展；
每 IP 限流：内置 RateLimiter，超限返回429 Too Many Requests；
TLS 支持：开启tls_enabled后自动签发自签证书，并在port+1提供/ca.pem下载端点供客户端信任（见 tls 启动逻辑）。

附赠：OpenAI 兼容接口

除了原生 API，LocalGPT 还提供一套OpenAI 兼容端点（openai_compat.rs），意味着任何支持自定义 base_url 的工具都能直接接入：

# 对话补全（支持 stream、tools、temperature 等标准字段） curl http://localhost:31327/v1/chat/completions \ -H "Content-Type: application/json" \ -d '{"model": "localgpt", "messages": [{"role": "user", "content": "你好"}]}' # 模型列表 curl http://localhost:31327/v1/models