Kunkun Docs

Kunkun 提供本地 HTTP 服务，暴露了类型化的 REST API，可用于 RAG 搜索、文件搜索等功能。服务仅绑定到 127.0.0.1，不会监听外网。

启用服务

打开设置 → API Keys

按 Cmd+,（macOS）或 Ctrl+,（Windows/Linux），在设置中打开 API Keys 区域。

启用本地 API

开启 Enable Local API Server。默认端口是 9559，如有冲突可手动修改。

服务会随 Kunkun 自动启动；你也可以在同一页面重启/停止。

创建 API Key

点击 Create API Key，设置名称，并选择可访问的服务：

服务	权限	说明
RAG	`search`, `ask`	检索并提问已索引的知识库
RAG	`admin`	全量权限，包括条目管理与设置
文件搜索	`search`	搜索已索引文件

请妥善保管 API Key，它会授权访问你的本地索引数据。admin 权限允许创建/更新/删除知识库内容，尽量按最小权限原则发放。

创建后请立刻复制到剪贴板，因为后续无法再次查看。

使用 REST API

服务提供 /api/v1 下的接口，所有请求都需带上 Authorization: Bearer <api-key>。

健康检查

curl http://localhost:9559/
# → { "status": "ok", "name": "kunkun-desktop" }

列出知识库

curl -H "Authorization: Bearer kk-xxxx" \
  http://localhost:9559/api/v1/rag/instances

搜索知识库

curl -X POST \
  -H "Authorization: Bearer kk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "query": "what is Kunkun", "topK": 5, "mode": "hybrid" }' \
  http://localhost:9559/api/v1/rag/instances/<instanceId>/search

提交问题

curl -X POST \
  -H "Authorization: Bearer kk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "question": "What does the architecture documentation say?" }' \
  http://localhost:9559/api/v1/rag/instances/<instanceId>/ask

流式回答（SSE）

curl -N -X POST \
  -H "Authorization: Bearer kk-xxxx" \
  -H "Content-Type: application/json" \
  -d '{ "question": "Explain the permission model." }' \
  http://localhost:9559/api/v1/rag/instances/<instanceId>/ask/stream
# event: metadata
# event: text_delta
# event: done

列出知识库中的条目

curl -H "Authorization: Bearer kk-xxxx" \
  http://localhost:9559/api/v1/rag/instances/<instanceId>/items

OpenAPI

服务还会提供 OpenAPI 3.0 规范与 Scalar API 文档页面：

URL	说明
`/openapi.json`	OpenAPI 3.0 规范文件
`/scalar`	可阅读的交互式 API 文档

使用 TypeScript 客户端

npm install @kunkunsh/client

import { createKunkunClient } from "@kunkunsh/client";

const client = createKunkunClient({
  baseUrl: "http://localhost:9559",
  apiKey: "kk-xxxx",
});

// 列出实例
const instances = await client.rag.instances.list();

// 搜索
const results = await client.rag.search(instances[0].id, {
  query: "Kunkun architecture",
  topK: 5,
});

更多 API 方法、类型与流式支持请见开发者文档。

安全

服务只监听 127.0.0.1，不对其他设备暴露
所有请求都必须携带服务端校验的 Bearer token
Token 在存储前会被 哈希化，Kunkun 不会保存明文
Token 可按能力范围进行 scope 配置
过期 token 会自动拒绝

管理 Token

在 设置 → API Keys 你可以：

查看所有有效 token（名称、前缀、创建时间、过期时间）
随时撤销某个 token
查看每个 token 最近的使用时间

本地 API 服务