首次调用 API

wesgine 提供 REST + SSE 接口，所有业务端点挂在 /cells/{cellID}/* 路径下。

基本信息

参数值
基础 URLhttp://localhost:9091（默认）
认证Authorization: Bearer <token>
Content-Typeapplication/json
流式响应text/event-stream（SSE）

两种部署模式

模式URL 结构适用场景
单 Cell/*（无 cellID 前缀）桌面应用（wescode / wesclaw）
多 Cell/cells/{cellID}/*企业多租户部署

本文档所有示例均使用多 Cell 模式（/cells/{cellID}/...）。单 Cell 模式去掉 /cells/{cellID} 前缀即可。

快速体验：发送第一条消息

1. 获取 Token

启动引擎时自动生成 Admin Token（首次启动会输出到 stderr）：

./bin/wesgine serve --data-dir ./data --addr :9091
# 输出: bootstrap admin token: wes_xxxxxxxxxxxx

或通过 API 签发：

curl -X POST http://localhost:9091/admin/tokens \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ttl": "24h"}'

2. 创建 Cell

curl -X POST http://localhost:9091/admin/cells \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "my-first-cell",
    "timezone": "Asia/Shanghai",
    "locale": "zh-CN"
  }'

3. 配置 Provider

curl -X POST http://localhost:9091/admin/shared-providers \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "providers": [{
      "name": "openai",
      "type": "openai",
      "base_url": "https://api.openai.com/v1",
      "api_key_ref": {"source": "inline", "value": "sk-xxx"},
      "models": [
        {"id": "gpt-4o", "context_window": 128000, "supports_vision": true}
      ]
    }]
  }'

4. 发起对话（SSE 流式）

curl -N -X POST http://localhost:9091/cells/my-first-cell/run \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "user-001",
    "model": "gpt-4o",
    "session_id": "s-001",
    "messages": [
      {
        "role": "user",
        "content": [{"type": "text", "text": "你好，请介绍一下自己"}]
      }
    ]
  }'

响应为 SSE 流：

data: {"type":"run_start","run_id":"run-abc123","timestamp":"2026-09-21T06:00:00Z"}

data: {"type":"stream_delta","content":"你好"}

data: {"type":"stream_delta","content":"！我是"}

data: {"type":"stream_delta","content":"你的 AI 助手。"}

data: {"type":"done","reason":"end_turn","run_id":"run-abc123"}

5. 同步对话（非流式）

如果不需要流式，使用 /chat 端点：

curl -X POST http://localhost:9091/cells/my-first-cell/chat \
  -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "actor": "user-001",
    "model": "gpt-4o",
    "messages": [
      {"role": "user", "content": [{"type": "text", "text": "1+1等于几？"}]}
    ]
  }'

响应 JSON：

{
  "response": "1+1等于2。",
  "run_id": "run-def456",
  "model": "gpt-4o",
  "usage": {
    "input_tokens": 12,
    "output_tokens": 8
  }
}

下一步