DomPaw API 快速入门

这份指南带你用大约十分钟跑通 DomPaw 的完整调用链路：开通租户、创建智能体、拿到 API Key、发起第一次对话，然后依次加上上下文记忆、流式输出和官方 SDK。每一步都给出可直接复制的命令和你会看到的真实响应。

开始前只需要一个 DomPaw 账号。新用户可享 7 天免费试用，无需信用卡。

先理解两件事

DomPaw 的接口兼容 OpenAI Chat Completions，所以你已经会写的那套代码基本能直接用。但有两处语义差别必须先说清楚，否则后面很容易困惑：

• 你调用的不是模型，而是智能体。 每个请求通过 X-Agent-Slug 指定一个你在控制台创建的智能体，它自带人设、技能、记忆和安全围栏。请求体里的 model 字段会被忽略（但为了兼容 SDK 仍需填写），实际使用哪个模型由智能体配置决定。
• 上下文保存在服务端。 你不需要每轮都把历史消息重新发一遍。服务端用 session_id 记住对话，messages 里只有最后一条 user 消息会被执行。

第 1 步：注册并等待实例开通

1. 打开注册页创建账号并登录。
2. 登录后平台会为你的租户开通一套独享的智能体运行时，首次开通通常需要 2-5 分钟。
3. 开通期间调用对话接口会收到 503 和 instance_provisioning，这是预期行为，等一会儿再试即可。

第 2 步：创建你的第一个智能体

1. 进入控制台的「智能体」页面，新建一个智能体。
2. 填写名称与人设，例如「你是酒店前台助理，负责处理客人的预约、入住与投诉」，然后选择一个模型。
3. 记下这个智能体的 slug（列表页可见，形如 front-desk）。后面每一个请求都要用到它。

技能和安全围栏可以等链路跑通之后再慢慢调，第一步不必纠结。

第 3 步：创建 API Key

1. 在控制台打开「API Keys」页面，新建一个 Key。
2. 复制并保存它——完整内容只显示一次，关闭弹窗后无法再次查看。
3. 把它放进环境变量，后文的示例都直接引用：

export DOMPAW_API_KEY=sk-xxxxxxxxxxxxxxxx

Key 归属一个租户，请求会依据它自动路由到你的独享实例。请不要把 Key 写进代码仓库或客户端包体；生产环境交给密钥管理服务托管；一旦怀疑泄露，立即在控制台吊销。

第 4 步：发起第一次对话

curl -sS https://paw.domai.fun/v1/chat/completions \
  -H "Authorization: Bearer $DOMPAW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Slug: front-desk" \
  -d '{
    "model": "dompaw",
    "messages": [
      {"role": "user", "content": "帮我把今天的到店预约汇总一下"}
    ]
  }'

你会看到类似这样的响应：

{
  "id": "1f0c1e7a-6d3b-4a19-9c62-2b7a4d0f3a11",
  "object": "chat.completion",
  "created": 1767225600,
  "model": "qwen-plus",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "今天共有 3 位客人预约到店，最早一位是 14:00 的林一……"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": null,
  "session_id": "1f0c1e7a-6d3b-4a19-9c62-2b7a4d0f3a11",
  "agent_id": "front-desk"
}

四个要点：

• 回复文本在 choices[0].message.content。
• session_id 是这段对话的键，下一轮沿用它就能接上上下文。
• model 是智能体当前配置的模型，与你请求里填的 model 无关。
• usage 目前恒为 null，token 用量请在控制台「用量与账单」查看。

第 5 步：让它记住上下文

自己指定一个 session_id，然后连续问两轮：

SESSION=$(uuidgen)

curl -sS https://paw.domai.fun/v1/chat/completions \
  -H "Authorization: Bearer $DOMPAW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Slug: front-desk" \
  -d "{\"model\": \"dompaw\", \"session_id\": \"$SESSION\", \"messages\": [{\"role\": \"user\", \"content\": \"我叫林一，住 1208 房\"}]}"

curl -sS https://paw.domai.fun/v1/chat/completions \
  -H "Authorization: Bearer $DOMPAW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Slug: front-desk" \
  -d "{\"model\": \"dompaw\", \"session_id\": \"$SESSION\", \"messages\": [{\"role\": \"user\", \"content\": \"我住哪个房间？\"}]}"

第二轮智能体会答出 1208——你并没有重传历史，上下文由服务端接续。

如果不传 session_id，平台会按「租户 + 调用方 + 智能体」派生一个默认键，于是同一个 Key 调用同一个智能体时永远在续接同一段对话。想开一段全新对话，换一个新的 session_id 即可。

第 6 步：改成流式输出

加上 "stream": true，并给 curl 加 -N 关闭缓冲：

curl -N https://paw.domai.fun/v1/chat/completions \
  -H "Authorization: Bearer $DOMPAW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Agent-Slug: front-desk" \
  -d '{
    "model": "dompaw",
    "stream": true,
    "messages": [{"role": "user", "content": "用三句话介绍 DomPaw"}]
  }'

原始输出长这样，每块以 data: 开头，块之间空一行：

data: {"id":"msg_01","object":"chat.completion.chunk","created":1767225600,"model":"default","choices":[{"index":0,"delta":{"content":"DomPaw "},"finish_reason":null}]}

data: {"id":"msg_01","object":"chat.completion.chunk","created":1767225600,"model":"default","choices":[{"index":0,"delta":{"content":"是一个云原生的"},"finish_reason":null}]}

data: [DONE]

把所有 delta.content 拼接起来就是完整回复。解析时有三点与 OpenAI 不同：

• 首块的 delta 不含 role 字段，不要靠它判断消息开始。
• 没有 finish_reason: "stop" 的收尾块，data: [DONE] 就是终点。
• HTTP 200 在连接实例之前就已发出，因此失败会以 data: {"type":"error","message":"..."} 的形式出现在流里，客户端必须检查这种事件。

第 7 步：换回你熟悉的 SDK

任何 OpenAI 兼容 SDK 都能接入，只需替换 base_url 与 api_key，并用 extra_headers 传智能体标识。

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://paw.domai.fun/v1",
    api_key=os.environ["DOMPAW_API_KEY"],
)

resp = client.chat.completions.create(
    model="dompaw",
    messages=[{"role": "user", "content": "帮我把今天的到店预约汇总一下"}],
    extra_headers={"X-Agent-Slug": "front-desk"},
    extra_body={"session_id": "order-desk-2026-01-01"},
)
print(resp.choices[0].message.content)

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: 'https://paw.domai.fun/v1',
  apiKey: process.env.DOMPAW_API_KEY,
});

const resp = await client.chat.completions.create(
  {
    model: 'dompaw',
    messages: [{ role: 'user', content: '帮我把今天的到店预约汇总一下' }],
    session_id: 'order-desk-2026-01-01',
  },
  { headers: { 'X-Agent-Slug': 'front-desk' } }
);

console.log(resp.choices[0].message.content);

SDK 会把 session_id、agent_id、credits_warning 这些 DomPaw 附加字段当作未知字段处理，需要用到它们时请直接调 HTTP 接口。

第 8 步：查看与清理会话

列出最近的会话（响应是裸数组，按更新时间倒序）：

curl -sS "https://paw.domai.fun/v1/chat/sessions?limit=5" \
  -H "Authorization: Bearer $DOMPAW_API_KEY"

[
  {
    "chat_id": "c-9f21",
    "session_id": "1f0c1e7a-6d3b-4a19-9c62-2b7a4d0f3a11",
    "name": "今日到店预约",
    "agent_name": "前台小 Dom",
    "agent_slug": "front-desk",
    "status": "idle",
    "created_at": "2026-01-01T02:11:00Z",
    "updated_at": "2026-01-01T02:19:30Z"
  }
]

用列表里的 chat_id 读取历史或删除会话：

curl -sS https://paw.domai.fun/v1/chat/sessions/c-9f21/messages \
  -H "Authorization: Bearer $DOMPAW_API_KEY"

curl -sS -X DELETE https://paw.domai.fun/v1/chat/sessions/c-9f21 \
  -H "Authorization: Bearer $DOMPAW_API_KEY"

删除会移除运行时里的会话记录，不可恢复。

遇到问题

完整错误码、限流规则和更多排错场景见 API 参考手册的「错误处理」与「排错指南」两节。

下一步

• API 参考手册：全部字段、流式细节、错误码与计费规则
• Swagger 交互式文档：在浏览器里直接试调用
• OpenAPI 规范：导入 Postman 或生成客户端代码
• 平台状态：实时健康检查（JSON）