虾觅 Xiami — 智能体 HTTP API（摘要）

本文面向任意 Agent 运行时，使用标准 HTTPS + JSON 接入记忆、检索、知识库、图谱、RAG。完整叙述、多语言示例与更新以线上为准。

线上完整接口文档 OpenAPI（Swagger） 打开产品控制台

概述

生产环境站点根为 https://xiami.aiznrc.com，API 根为 https://xiami.aiznrc.com/api/v1。 环境变量 XIAMI_API_BASE 表示站点根（不含 /api/v1），与 curl …/openclaw/install.sh 脚本约定一致。若自托管，请在实际请求中替换为你的公网域名。

生产 Base URL

用途地址
站点根 XIAMI_API_BASEhttps://xiami.aiznrc.com
REST API 前缀https://xiami.aiznrc.com/api/v1

鉴权

除登录、注册等公开接口外，业务接口在 Header 中携带：

Authorization: Bearer <凭证>

三种凭证

类型形式典型用途
记忆体 API Tokenxiami_ 开头（非 xiami_sk_）单智能体长期运行，仅访问该记忆体范围内能力；泄露面最小。
平台 API 密钥xiami_sk_ 开头自动化 / CI / 运维；可管理多个记忆体、知识库同步等。不适合嵌入终端用户设备。
账号 JWT登录后 access_token浏览器会话、创建记忆体、导出、订单与资料等。

使用 JWT 或 平台密钥 调用 POST /api/v1/memory/write 时，请求体通常需包含 api_token_id（控制台记忆体详情中的 token_id）。使用 记忆体 Token 时服务端已绑定该记忆体，一般无需在 body 重复传递。

第三方记忆 API（/api/v1/third-party/memory）

面向「一把平台密钥操作账户下多个记忆体」。鉴权仅接受账号 JWT 或 xiami_sk_，不接受记忆体 xiami_ Bearer。

方法路径说明
GET/third-party/memory/integration-manifest返回可见记忆体、memory_scope_token_id、路径模板与示例。
POST/third-party/memory/write-by-agentBody 含 xiami_agent_id、content 等；自建记忆体可写。
POST/third-party/memory/search-by-agent按 xiami_agent_id 检索；自建与租用（只读）均可。
curl 
curl -sS "https://xiami.aiznrc.com/api/v1/third-party/memory/integration-manifest" \
  -H "Authorization: Bearer xiami_sk_你的平台密钥"

CLI 一键安装（install.sh）

Linux / macOS / WSL / Git Bash：需 bash、curl、python3。原生 Windows CMD 无 bash 时请使用 GET /openclaw/install.ps1（详见线上文档 §6）。

bash 
export XIAMI_API_BASE=https://xiami.aiznrc.com
curl -fsSL "$XIAMI_API_BASE/openclaw/install.sh" | bash -s -- "xiami_sk_你的密钥"

安装完成后，CLI api manifest 对应 GET /api/v1/openclaw/deployment-manifest；记忆相关与 /api/v1/memory/* 一致。

智能体通用 API 矩阵（节选）

下列路径均相对于 https://xiami.aiznrc.com/api/v1。完整模型以 OpenAPI 为准。

能力方法路径常用凭证
记忆写入POST/memory/writeJWT / 平台 / 记忆体
记忆检索POST/memory/search三者皆可
记忆列表GET/memory/list三者皆可
图谱合并视图GET/memory/graph三者皆可
融合搜索POST/search/query三者皆可
知识库同步POST/ai/knowledge-base/syncJWT / 平台
AI 对话GET/POST/ai/chats…依接口
记忆体管理GET/POST…/agents…JWT 或平台密钥（不可用 xiami_）

记忆系统（/api/v1/memory）

方法路径说明
POST/memory/write写入一条记忆
POST/memory/search关键词检索：query、limit
GET/memory/list分页：limit、offset
GET/memory/graphMemory 与结构化 KG 合并视图；含 graph_source
POST/memory/timeline时间线筛选
POST/memory/forget按 memory_id 删除

调用示例：写入记忆（curl）

将 xiami_xxx_你的Token 与 api_token_id 替换为控制台实际值。

curl 
curl -sS -X POST "https://xiami.aiznrc.com/api/v1/memory/write" \
  -H "Authorization: Bearer xiami_xxx_你的Token" \
  -H "Content-Type: application/json" \
  -d '{"content":"要记住的内容","memory_type":"default","api_token_id":"你的token_id_UUID"}'

记忆体生命周期（/api/v1/agents）

须为 账号 JWT 或 平台密钥 xiami_sk_，不可使用记忆体 Token 调用本组接口。创建后在详情页获取 xiami_ Token 供运行时调用记忆/搜索等接口。

  • GET /agents、GET /agents/visible — 列表与可见记忆体
  • POST /agents/json、POST /memory-body — JSON 创建（脚本友好）
  • POST /agents/delete-preview — 删除前 Neo4j 清理预估
  • GET /agents/{agent_id}/export-claw — OpenClaw / EasyClaw 导出（需 JWT，策略以部署为准）

知识库与结构化同步（节选）

路径前缀 /api/v1/ai/knowledge-base：文件夹与文档 folders|docs、触发同步 POST …/sync（可提供 doc_ids 限定本次范围）、纯文本 POST …/sync-text、任务查询与取消等。需 JWT 或平台密钥。字段与权限以 OpenAPI 为准。

更多

智能搜索、AI 对话与 RAG、公共预览页 /api/v1/public、错误与限流、OpenClaw 可选导出等，请阅读线上完整文档与 Swagger。

https://xiami.aiznrc.com/api-guide