API 与集成

wesclaw 提供本机 HTTP 模式和 JSON-RPC 协议，支持与外部工具和自动化脚本集成。

概述

wesclaw 桌面版内置了两种对外接口：

接口模式	用途	适用场景
`wesclaw serve`	本机 HTTP 服务	自动化脚本、CI/CD 集成、其他应用调用
JSON-RPC (stdio)	Electron 主进程通信	扩展开发、深度集成

wesclaw serve — 本机 HTTP 模式

启动 serve 模式

wesclaw serve

默认监听 http://localhost:8080（端口可配置）。

主要端点

健康检查

GET /health

# 响应
{
  "status": "ok",
  "engine": "ready"
}

发送消息

POST /v1/chat
Content-Type: application/json

{
  "session_id": "my-session",
  "agent_id": "assistant",
  "messages": [
    {
      "role": "user",
      "content": "你好，帮我查看一下今天的待办事项"
    }
  ]
}

响应为 SSE（Server-Sent Events）流：

event: delta
data: {"type": "text", "content": "好"}

event: delta
data: {"type": "text", "content": "的"}

event: done
data: {"reason": "end_turn"}

会话管理

# 列出会话
GET /v1/sessions

# 获取会话消息
GET /v1/sessions/{session_id}/messages?limit=50

# 删除会话
DELETE /v1/sessions/{session_id}

# 中断当前 Run
POST /v1/sessions/{session_id}/interrupt

记忆操作

# 列出记忆
GET /v1/memory?layer=about_me&limit=20

# 搜索记忆
POST /v1/memory/search
{
  "query": "用户偏好",
  "layer": "about_me",
  "limit": 10
}

# 记忆计数
GET /v1/memory/counts

Agent 管理

# 列出 Agent
GET /v1/agents

# 获取单个 Agent
GET /v1/agents/{agent_id}

# 创建/更新 Agent
POST /v1/agents
{
  "id": "my-agent",
  "name": "我的助手",
  "system_prompt": "你是一个友好的 AI 助手。"
}

Provider 管理

# 列出可用模型
GET /v1/providers

# 测试 Provider 连接
POST /v1/providers/test
{
  "provider_name": "openai",
  "mode": "chat"
}

认证

serve 模式默认仅监听 localhost，无需认证。如需开放到局域网，建议：

配置 API Token 认证
使用反向代理（如 nginx）添加 HTTPS 和认证层
限制访问来源 IP

JSON-RPC 协议

协议说明

wesclaw 桌面版的 Electron 主进程与 Go 后端通过 stdio JSON-RPC 通信。这是 wesclaw 内部的主要通信协议。

消息格式

请求：

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "sidebar/listConversations",
  "params": {
    "limit": 20
  }
}

响应：

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "conversations": [...]
  }
}

常用方法

方法名	说明
`chat/send`	发送对话消息
`chat/cancel`	取消当前 Run
`sidebar/listConversations`	列出对话列表
`sidebar/availableModels`	获取可用模型列表
`auth/me`	获取当前登录信息
`settings/get`	获取设置
`settings/update`	更新设置

流式通知

对话流式回复通过 JSON-RPC 通知（notification）推送：

{
  "jsonrpc": "2.0",
  "method": "chat/stream",
  "params": {
    "request_id": "req-123",
    "type": "delta",
    "data": {
      "content": "你好"
    }
  }
}

自动化场景示例

使用 curl 发送消息

# 启动 serve 模式（如果未启动）
wesclaw serve &

# 发送消息并接收 SSE 流
curl -N -X POST http://localhost:8080/v1/chat \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "auto-session-001",
    "agent_id": "assistant",
    "messages": [{"role": "user", "content": "今天天气怎么样？"}]
  }'

Python 脚本集成

import requests
import json

BASE_URL = "http://localhost:8080"

# 发送消息（SSE 流式接收）
def chat(session_id: str, message: str):
    resp = requests.post(
        f"{BASE_URL}/v1/chat",
        json={
            "session_id": session_id,
            "agent_id": "assistant",
            "messages": [{"role": "user", "content": message}],
        },
        stream=True,
    )
    
    full_response = ""
    for line in resp.iter_lines():
        if line:
            line = line.decode("utf-8")
            if line.startswith("data: "):
                data = json.loads(line[6:])
                if data.get("type") == "text":
                    full_response += data["content"]
    
    return full_response

# 使用示例
result = chat("my-session", "帮我总结一下今天的工作")
print(result)

与 Shell 脚本集成

#!/bin/bash
# 每日总结脚本

SESSION_ID="daily-summary-$(date +%Y%m%d)"
MESSAGE="请帮我回顾一下今天的对话，做一个简短的总结。"

# 发送请求
curl -s -X POST http://localhost:8080/v1/chat \
  -H "Content-Type: application/json" \
  -d "{
    \"session_id\": \"$SESSION_ID\",
    \"agent_id\": \"assistant\",
    \"messages\": [{\"role\": \"user\", \"content\": \"$MESSAGE\"}]
  }" | while IFS= read -r line; do
    echo "$line"
  done

与 Alfred / Raycast 集成

可以创建自定义工作流，通过 HTTP API 快速向 wesclaw 发送消息：

创建新的工作流/脚本命令
脚本内容调用 http://localhost:8080/v1/chat
将 AI 回复显示在通知或剪贴板中

与其他工具集成

与 cron / launchd 集成

结合操作系统的定时任务工具，实现自动化 AI 操作：

# cron 示例：每天早上 9 点让 AI 检查邮件
0 9 * * * curl -X POST http://localhost:8080/v1/chat \
  -H "Content-Type: application/json" \
  -d '{"session_id":"morning-check","agent_id":"assistant","messages":[{"role":"user","content":"请检查新邮件并给我一个摘要"}]}'

与 Webhook 集成

可以用 wesclaw 作为 Webhook 消费端：

使用 serve 模式启动
外部服务（如 GitHub、Slack）配置 Webhook 指向 wesclaw
wesclaw 接收 Webhook 事件后触发 AI 处理

与 MCP 服务集成

wesclaw 内置 MCP（Model Context Protocol）客户端，可以连接外部 MCP 服务器扩展 AI 能力。详见 MCP 配置。

注意事项

安全

serve 模式仅应在受信任的网络环境中使用
不要将 serve 端口暴露到公网
如需远程访问，使用 VPN 或 SSH 隧道
API Token 请妥善保管

限制

serve 模式一次只能处理一个活跃 Run（同一 session）
SSE 连接断开不会取消正在进行的 Run
单个请求的超时默认为 24 小时
不支持 WebSocket（使用 SSE 替代）

SaaS 版差异

SaaS 云端版本不提供本机 serve 模式。API 集成通过 WES 平台 API 实现，需要 JWT 认证。

下一步

对话运行周期 — 了解 Run 的完整生命周期和 SSE 事件
人机交互审批 — 了解 AI 如何请求用户确认
MCP 配置 — 连接外部 MCP 服务器