面向任意 Agent 运行时（自研 Bot、LangChain、AutoGen、Dify、n8n、桌面助手等）：使用标准 HTTPS + JSON 接入记忆写入、检索、知识库、结构化图谱、RAG 对话。机器可读契约以 OpenAPI（Swagger） 为准，本页为叙述性导读。
生产示例根地址：站点 https://xiami.aiznrc.com，
API 前缀 https://xiami.aiznrc.com/api/v1。
若你自托管，请替换为你的公网域名。环境变量 XIAMI_API_BASE 表示站点根（不含 /api/v1），与安装脚本约定一致。
xiami_sk_）：一把密钥对应一个虾觅账户，用于服务端、CI；可通过权限限制可见记忆体。xiami_）：仅能访问该记忆体数据，适合嵌入单一 Agent。/memory/* 时在 body 或 query 传入对应 api_token_id；或先调 GET /third-party/memory/integration-manifest 获取映射表。XIAMI_API_BASE 为可访问的站点根 URL。xiami_sk_ 或 JWT）请求 GET …/third-party/memory/integration-manifest，解析 manifest.agents[]。POST /memory/write（默认返回 202，Neo4j 后台写入）；JWT/平台密钥需在 body 带 api_token_id；纯 xiami_ Token 通常可省略。POST /memory/write-batch 或 POST /third-party/memory/batch-write（≤100 条，默认 202）。POST /search；关键词可用 query、q、search_query 等（见下文「字段兼容」）。write-by-agent、search-by-agent，body 填 xiami_agent_id（或别名 agent_id）。/api/v1/third-party/memory外部系统用一把平台密钥操作账户内多个记忆体。鉴权：接受账号 JWT 或 xiami_sk_，不接受记忆体 xiami_ Bearer（避免与单 Agent 场景混淆）。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /third-party/memory/integration-manifest |
返回套餐记忆上限、平台密钥权限、各可见记忆体的 memory_scope_token_id（在 JWT/平台模式下作为 api_token_id 传入）、常用 /memory/* 相对路径与示例。 |
| POST | /third-party/memory/write-by-agent |
xiami_agent_id、content；默认 ?async=true 返回 202。 |
| POST | /third-party/memory/batch-write |
items[]（≤100）；默认 202，后台 UNWIND 写入。 |
| POST | /third-party/memory/search-by-agent |
xiami_agent_id（或 agent_id）+ 关键词（query/q/search_query 等）；等同 POST /search，额外返回 memories[]。 |
| POST | /third-party/memory/clear |
Body：xiami_agent_id、confirm: true；可选 include_knowledge_graph。 |
curl -sS "https://xiami.aiznrc.com/api/v1/third-party/memory/integration-manifest" \ -H "Authorization: Bearer xiami_sk_你的平台密钥"
GET /openclaw/install.sh（安装脚本路径名）脚本由服务端动态生成。需已安装 bash、curl、python3；Windows 原生环境可使用 GET /openclaw/install.ps1。
XIAMI_API_BASE（公网或 VPN 可达，勿用仅本机回环地址）。xiami_sk_…；脚本会下载 CLI 并执行 install，将凭据写入用户目录（如 ~/.xiami/）。python3 …/xiami_code_cli.py api … 子命令访问与本文一致的 REST。export XIAMI_API_BASE=https://xiami.aiznrc.com curl -fsSL "$XIAMI_API_BASE/openclaw/install.sh" | bash -s -- "xiami_sk_你的密钥"
除登录、注册、验证码等公开接口外，业务接口在 Header 携带：
Authorization: Bearer <凭证>
| 类型 | 形式 | 典型用途 |
|---|---|---|
| 记忆体 API Token | xiami_（非 xiami_sk_） |
单 Agent 长期运行；读写该记忆体范围内记忆、搜索、图谱等。 |
| 平台 API 密钥 | xiami_sk_ |
服务端 / CI；等同账户能力（受密钥权限矩阵约束）。 |
| 账号 JWT | 登录后的 access_token |
浏览器会话、创建记忆体、管理订单与个人资料。 |
使用 JWT 或平台密钥调用 POST /memory/write 时，body 通常需包含 api_token_id（控制台「记忆体」详情中的 token_id）。使用 xiami_ 时服务端已绑定记忆体，一般无需重复传递。
推荐：多记忆体场景先调 GET /auth/whoami 查看 agents[] 与 memory_scope_token_id。
前缀均为 https://<你的域名>/api/v1。完整路径与模型见 OpenAPI。
| 能力 | 方法 | 路径 | 说明摘要 |
|---|---|---|---|
| 鉴权 | GET | /auth/whoami | 当前密钥类型与可见记忆体 |
| 记忆 | POST | /memory/write | 写入一条；默认 202（?async=false 同步） |
| 记忆 | POST | /memory/write-batch | 批量写入（≤100，默认 202） |
| 记忆 | POST | /memory/search | 记忆体检索；关键词字段兼容见「智能搜索」 |
| 搜索 | POST | /search | 记忆体 + 知识图谱统一搜索（推荐） |
| 记忆 | GET | /memory/list | 分页列表（含 total） |
| 记忆 | POST | /memory/clear | 清空 scope（confirm: true） |
| 记忆 | GET | /memory/graph | 合并 Memory 与结构化 KG；支持 api_token_id、xiami_agent_id、max_nodes 等 |
| 记忆 | POST | /memory/timeline | 时间线筛选 |
| 记忆 | POST | /memory/forget | 按 memory_id 删除 |
| 记忆 | PATCH | /memory/update | 编辑名称、标签、摘要、正文 |
| 记忆 | GET | /memory/account-agents | 账号记忆体列表 + memory_count + Token |
| 记忆 | GET/PUT | /memory/forgetting/settings | 遗忘机制配置 |
| 记忆 | POST | /memory/forgetting/dream | 梦境巩固，删除低于阈值记忆 |
| 搜索 | POST | /search/rerank | 重排序 |
| 知识库 | GET/POST/PATCH/DELETE | /ai/knowledge-base/folders|docs | 文件夹与文档 |
| 同步 | POST | /ai/knowledge-base/sync | 触发结构化同步；可用 doc_ids 限定范围 |
| 同步 | POST | /ai/knowledge-base/sync-text | 纯文本片段直接写入图谱 |
| AI 对话 | GET/POST | /ai/chats、/ai/chats/{id}/send | 会话与 SSE 流式对话；可选 RAG |
| 统计 | POST | /ai/memory/stats | 按记忆体统计 Neo4j 规模 |
| 用量 | GET | /ai/token-usage/summary 等 | 对话 Token 用量统计（可选对接账单页） |
部署到公网后，可在任意电脑终端通过固定 URL 下载 xiami_code_cli.py，使用平台密钥完成 install 后调用 api profile、api agents、api memory-* 等子命令（实际请求发往 $XIAMI_API_BASE/api/v1）。
| 资源 | 路径 | 说明 |
|---|---|---|
| 安装脚本 | GET /openclaw/install.sh | bash 管道安装 |
| CLI 本体 | GET /openclaw/xiami_code_cli.py | 保存后长期复用 |
| 部署清单 | GET /api/v1/openclaw/deployment-manifest | 当前 Bearer 可见的接口与记忆体矩阵（JSON） |
完整子命令：python3 xiami_code_cli.py api --help
/api/v1/memory| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /memory/write | 默认 202；JWT/平台密钥需 api_token_id |
| POST | /memory/write-batch | items[]；默认 202 |
| POST | /memory/search | query/q/search_query、limit 或 top_k |
| GET | /memory/list | limit、offset；响应含 total |
| POST | /memory/clear | confirm: true 清空当前 scope |
| GET | /memory/graph | 合并视图；字段 graph_source 说明数据来源 |
| POST | /memory/timeline | 时间范围等筛选 |
| POST | /memory/forget | 删除一条：memory_id |
| PATCH | /memory/update | 编辑 entity_name、tags、summary、正文 |
| GET | /memory/account-agents | 记忆体 + Token + memory_count（平台密钥/JWT） |
| GET/PUT | /memory/forgetting/settings | 遗忘阈值、衰减率、梦境时刻等 |
| POST | /memory/forgetting/dream | 立即梦境巩固 |
写入时元数据按《智能体长期结构化记忆系统 v1.0》自动补全 memory_class、strength、decay_rate 等字段。
环境变量 XIAMI_MEMORY_WRITE_ASYNC_DEFAULT=true（默认）时，POST /memory/write、/memory/write-batch 及第三方 write-by-agent、batch-write 在校验通过后立即返回 HTTP 202，响应含 accepted: true 与 memory_id / memory_ids；Neo4j 落库在后台执行。高并发同步（OpenClaw 等）属正常现象，不代表用户打开网页。
需确认已写入再搜索时：可设 ?async=false（同步 200），或写入后稍候再调 /memory/search。
import requests
BASE = "https://xiami.aiznrc.com/api/v1"
TOKEN = "xiami_xxx"
r = requests.post(f"{BASE}/memory/write", json={
"content": "要记住的内容",
"memory_type": "default",
"api_token_id": "你的_token_uuid",
}, headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}, timeout=30)
print(r.json())
curl -sS -X POST "https://xiami.aiznrc.com/api/v1/memory/write" \
-H "Authorization: Bearer xiami_xxx" \
-H "Content-Type: application/json" \
-d '{"content":"要记住的内容","memory_type":"default","api_token_id":"你的_token_uuid"}'
/api/v1/search推荐入口 POST /search：同时检索记忆体与结构化知识图谱。web 数据源尚未接入。旧路径 POST /search/query 行为相同但标记兼容。
以下字段名可互换，服务端会自动映射为 query / limit：
| 用途 | 可用字段名 |
|---|---|
| 搜索关键词（必填其一） | query、q、search_query、text、keyword、input、prompt；或 messages[] 最后一条 user 的 content |
| 返回条数 | limit 或 top_k（1–100） |
| 限定记忆体 | xiami_agent_id、api_token_id；第三方搜索可用 agent_id 作为 xiami_agent_id 别名 |
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /search | scope：memory / knowledge_graph / all |
| POST | /memory/search | 仅记忆体；可选 include_knowledge_graph |
| POST | /third-party/memory/search-by-agent | 平台密钥 + xiami_agent_id；响应含 memories[] |
| POST | /search/query | 兼容别名 |
| POST | /search/rerank | 对候选结果重排 |
curl -sS -X POST "https://xiami.aiznrc.com/api/v1/search" \
-H "Authorization: Bearer xiami_sk_xxx" \
-H "Content-Type: application/json" \
-d '{"search_query":"产品需求","top_k":5,"xiami_agent_id":"agt_xxx","scope":"all"}'
完整说明与运维建议见 docs/API_REFERENCE.md（v1.3）。
/api/v1/agents鉴权：须为账号 JWT 或平台密钥 xiami_sk_，不可使用记忆体 xiami_。创建后在详情页获取 xiami_ 供运行时调用记忆接口。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /agents | 分页列表 |
| GET | /agents/visible | 当前用户可见记忆体 |
| POST | /agents | multipart 创建 |
| POST | /agents/json | JSON 创建 |
| POST | /agents/delete-preview | 删除前 Neo4j 规模预估 |
| PATCH | /agents/{agent_id} | 更新元数据 |
| POST | /agents/{agent_id}/reset-token | 重置记忆体 Token |
| DELETE | /agents/{agent_id} | 删除并级联清理图谱数据 |
广场相关：/api/v1/agent-plaza/* 见 OpenAPI。
文档入库后可同步到指定记忆体，抽取实体、关系等写入 Neo4j，供图谱与 RAG 使用。需 JWT 或平台密钥。
/ai/knowledge-base/folders、/docs：文件夹与文档 CRUDPOST /ai/knowledge-base/sync：触发同步；doc_ids 可限定仅同步列出的文档POST /ai/knowledge-base/sync-text：文本抽取为知识图谱；默认 raw_storage: true 另存可检索记忆条目GET /ai/knowledge-base/sync/{task_id}：任务状态与明细/ai/knowledge-summary-model/probe：校验总结模型连通性/api/v1/aiGET /ai/models、GET|POST /ai/chats：模型与会话GET /ai/chats/{chat_id}/messages：历史消息POST /ai/chats/{chat_id}/send：发送消息（SSE 流式，请求体 stream: true，客户端 Accept: text/event-stream）；可选 use_ragPOST /ai/chats/{chat_id}/memory/quick-save：从对话快速写入记忆POST /ai/memory/stats：记忆体规模统计GET /ai/token-usage/*：用量统计（可选）/api/v1/public公开预览页与上传接口；上传/保存需平台密钥 xiami_sk_ 或账号 JWT。控制台预览页支持在线编辑（HTML/Markdown）、图片删除/替换、保存与下载。
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /public/pages/{owner}/{slug} | 元数据；含 download_url |
| GET | /public/pages/{owner}/{slug}/render | iframe 渲染 HTML |
| GET | /public/pages/{owner}/{slug}/download | 下载正文（format=html|markdown|auto，智能体可读） |
| PUT | /public/pages/{owner}/{slug}/content | 在线编辑保存 JSON |
| POST | /public/pages/{owner}/{slug}/assets/image | 上传/替换图片 |
| POST | /public/pages/{slug} | multipart 上传/覆盖 |
{"detail": "..."}。请求体字段不合法时返回 HTTP 400（含可读中文说明），请按上文「字段兼容」检查关键词与 xiami_agent_id。401 鉴权失败；403 配额/权限；404 记忆体不可见。REDIS_URL、XIAMI_LIGHT_BOOT=1；MySQL 与 Neo4j 分机部署。POST /agents/delete-preview。For any agent runtime (custom bots, LangChain, Dify, n8n, etc.): use HTTPS + JSON for memory, retrieval, knowledge base, graph, and RAG chat. The machine-readable contract is OpenAPI (Swagger); this page is a human-readable guide.
Example production host: https://xiami.aiznrc.com,
API prefix https://xiami.aiznrc.com/api/v1.
Self-hosted: replace with your public origin. XIAMI_API_BASE is the site root (without /api/v1), same as the install scripts.
xiami_sk_) under API keys — one key per Xiami account for servers and CI; scope visible agents as needed.xiami_) scoped to that memory only.api_token_id on /memory/* or call GET /third-party/memory/integration-manifest first.XIAMI_API_BASE to a reachable site root.GET …/third-party/memory/integration-manifest with xiami_sk_ or JWT; parse manifest.agents[].POST /memory/write — default HTTP 202 (async Neo4j write); use api_token_id with JWT/platform keys./memory/write-batch or /third-party/memory/batch-write (≤100 items, default 202).POST /search; keywords accept query, q, search_query, etc.write-by-agent, search-by-agent with xiami_agent_id (alias agent_id)./api/v1/third-party/memoryIntegrations that use one platform key for many agents under the same account. Accepts JWT or xiami_sk_; does not accept per-agent xiami_ bearer tokens.
| Method | Path | Summary |
|---|---|---|
| GET | /third-party/memory/integration-manifest |
Plan limits, key permissions, memory_scope_token_id per visible agent (use as api_token_id), and example paths. |
| POST | /third-party/memory/write-by-agent |
Default 202; ?async=false for sync. |
| POST | /third-party/memory/batch-write |
Up to 100 items; default 202. |
| POST | /third-party/memory/search-by-agent |
xiami_agent_id or agent_id; keyword aliases as on POST /search. |
curl -sS "https://xiami.aiznrc.com/api/v1/third-party/memory/integration-manifest" \ -H "Authorization: Bearer xiami_sk_YOUR_PLATFORM_KEY"
GET /openclaw/install.sh (install script URL)The script is generated by the server. Requires bash, curl, python3. On Windows without bash, use GET /openclaw/install.ps1.
XIAMI_API_BASE to a publicly reachable origin (not loopback-only).xiami_sk_… platform key; the script downloads the CLI and runs install.python3 …/xiami_code_cli.py api … against the same REST as this guide.export XIAMI_API_BASE=https://xiami.aiznrc.com curl -fsSL "$XIAMI_API_BASE/openclaw/install.sh" | bash -s -- "xiami_sk_YOUR_KEY"
Protected APIs require:
Authorization: Bearer <credential>
| Type | Format | Use |
|---|---|---|
| Agent memory token | xiami_ | Long-lived access for a single agent’s memory APIs. |
| Platform API key | xiami_sk_ | Server/CI; account-level permissions. |
| Account JWT | access_token | Browser session and console flows. |
For POST /memory/write with JWT or a platform key, include api_token_id in the body. With xiami_, the agent is already bound.
All paths are under https://<your-host>/api/v1. See OpenAPI for the full set.
| Area | Method | Path | Notes |
|---|---|---|---|
| Memory | POST | /memory/write | Write one memory item |
| Memory | POST | /memory/search | Keyword search |
| Memory | GET | /memory/list | Paginated list |
| Memory | GET | /memory/graph | Graph merge view |
| Memory | POST | /memory/timeline | Timeline filter |
| Memory | POST | /memory/forget | Delete by memory_id |
| Search | POST | /search/query | Blended search |
| Search | POST | /search/rerank | Rerank candidates |
| Knowledge | REST | /ai/knowledge-base/… | Folders & docs |
| Sync | POST | /ai/knowledge-base/sync | Trigger structured sync |
| AI chat | REST | /ai/chats… | Sessions & SSE send |
| Usage | GET | /ai/token-usage/… | Optional usage stats |
Download xiami_code_cli.py from your deployed site, run install with a platform key, then use api … subcommands.
| Asset | Path | Notes |
|---|---|---|
| Install script | GET /openclaw/install.sh | bash pipe install |
| CLI file | GET /openclaw/xiami_code_cli.py | Save and reuse |
| Manifest | GET /api/v1/openclaw/deployment-manifest | JSON capability matrix |
/api/v1/memory| Method | Path | Summary |
|---|---|---|
| POST | /memory/write | Write |
| POST | /memory/search | Search |
| GET | /memory/list | List |
| GET | /memory/graph | Graph |
| POST | /memory/timeline | Timeline |
| POST | /memory/forget | Forget one |
import requests
BASE = "https://xiami.aiznrc.com/api/v1"
TOKEN = "xiami_xxx"
r = requests.post(f"{BASE}/memory/write", json={
"content": "text to remember",
"memory_type": "default",
"api_token_id": "YOUR_TOKEN_UUID",
}, headers={"Authorization": f"Bearer {TOKEN}", "Content-Type": "application/json"}, timeout=30)
print(r.json())
curl -sS -X POST "https://xiami.aiznrc.com/api/v1/memory/write" \
-H "Authorization: Bearer xiami_xxx" \
-H "Content-Type: application/json" \
-d '{"content":"text to remember","memory_type":"default","api_token_id":"YOUR_TOKEN_UUID"}'
/api/v1/searchPrefer POST /search. Keyword fields: query, q, search_query, etc. Invalid bodies return 400 with detail.
| Method | Path | Summary |
|---|---|---|
| POST | /search | Unified search (recommended) |
| POST | /memory/search | Memory-only search |
| POST | /search/query | Legacy alias |
| POST | /search/rerank | Rerank |
See docs/API_REFERENCE.md (v1.3).
/api/v1/agentsAuth: account JWT or xiami_sk_ only — not xiami_.
| Method | Path | Summary |
|---|---|---|
| GET | /agents | List |
| GET | /agents/visible | Visible agents |
| POST | /agents | Create (multipart) |
| POST | /agents/json | Create (JSON) |
| POST | /agents/delete-preview | Delete impact preview |
| PATCH | /agents/{agent_id} | Update |
| POST | /agents/{agent_id}/reset-token | Reset token |
| DELETE | /agents/{agent_id} | Delete agent + graph cleanup |
Plaza: /api/v1/agent-plaza/* — see OpenAPI.
Ingest documents, sync to an agent, extract entities/relations into Neo4j for graph and RAG. Requires JWT or platform key.
/ai/knowledge-base/folders, /docsPOST /ai/knowledge-base/sync with optional doc_idsPOST /ai/knowledge-base/sync-textGET /ai/knowledge-base/sync/{task_id}/ai/knowledge-summary-model/probe/api/v1/aiGET /ai/models, GET|POST /ai/chatsGET /ai/chats/{chat_id}/messagesPOST /ai/chats/{chat_id}/send — SSE streaming; optional use_ragPOST /ai/chats/{chat_id}/memory/quick-savePOST /ai/memory/statsGET /ai/token-usage/* — optional usage reporting/api/v1/publicPublic previews and uploads authenticated with xiami_sk_. See OpenAPI for /public/pages/….
detail. Validation issues return HTTP 400 (not 422).REDIS_URL, XIAMI_LIGHT_BOOT=1; separate MySQL and Neo4j hosts.POST /agents/delete-preview.