WinClaw Docs

WinClaw 本地开放接口

WinClaw 在本地 127.0.0.1:9199 暴露 HTTP API，供外部工具和脚本提交任务、流式接收 AI 响应，以编程方式与 WinClaw Agent 交互。

WinClaw 在本地运行一个 HTTP 服务（127.0.0.1:9199），接收来自外部程序的任务提交。CLI 工具、脚本和自动化工作流可以通过这个简单的 HTTP 接口，利用 WinClaw 的 AI 能力 —— 包括电脑管理 Agent、RAG 知识库和直接模型对话。

一个典型的使用场景：agent_cron 定时调度器通过这个 API 按计划向 WinClaw 提交 prompt，实现全自动的 AI 工作流。

API 端点

提交任务并流式接收结果

  • URL: POST http://127.0.0.1:9199/api/external/tasks/stream
  • Content-Type: application/json
  • 响应: text/event-stream（SSE）

取消正在执行的任务

  • URL: POST http://127.0.0.1:9199/api/external/tasks/cancel
  • Content-Type: application/json
  • Body: { "request_id": "..." }

请求参数

{
  "engine": "pc_manager | rag",
  "config_id": "string",
  "prompt": "string",
  "topic_id": "optional string",
  "conversation_id": "optional string",
  "conversation_title": "optional string",
  "model_override": "optional string",
  "request_id": "optional string",
  "metadata": { "optional": "object" },
  "include_history": true,
  "temperature": 0.7,
  "max_tokens": 2000
}

字段说明

字段必填默认值说明
prompt是—发送给 AI 的任务指令
engine否pc_manager使用哪个引擎（见支持的引擎）
config_id否default配置标识（与引擎相关）
topic_id否自动创建用于会话分组的 Topic ID
conversation_id否自动创建用于消息归组的对话 ID
conversation_title否—对话的可读标题
request_id否自动生成 UUID唯一请求 ID，可用于取消任务
metadata否—附加到任务的任意键值对元数据
include_history否true是否注入对话历史（仅对 rag 引擎有效）
temperature否—模型温度参数
max_tokens否—模型最大回复 token 数
model_override否—覆盖默认模型

支持的引擎

引擎说明config_id
pc_manager电脑管理 Agent，可执行命令、读写文件、搜索代码、浏览网页等任意值，如 default
ragRAG 检索增强生成，基于知识库回答问题对应 rag_id

SSE 事件流

响应是一个 Server-Sent Events（SSE）流。事件按以下顺序传输：

事件类型说明关键字段
task第一个事件，包含会话标识topic_id, conversation_id, user_message_id, request_id
connection连接已建立status
content增量响应文本content
reasoning模型推理步骤（如适用）content
tool_callAgent 调用工具工具详情
tool_result工具调用结果结果详情
done任务完成assistant_message_id, content（完整回复）
error任务失败message

SSE 输出示例

event: task
data: {"type": "task", "topic_id": "35978dd8-...", "conversation_id": "6ab5a646-...", "user_message_id": "3e613f07-...", "request_id": "b256c878-..."}

event: connection
data: {"type": "connection", "status": "connected"}

data: {"type": "content", "content": "我"}
data: {"type": "content", "content": "是一"}
data: {"type": "content", "content": "个专业"}
data: {"type": "content", "content": "的AI"}

data: {"type": "done", "content": "完整回复内容...", "assistant_message_id": "xxx"}

历史记录持久化

通过 API 提交的任务会自动保存到 WinClaw 的对话历史中：

  1. 用户消息立即保存（role=user）
  2. 模型事件流式传输给客户端
  3. 收到 done 事件后，保存助手消息（role=assistant）
  4. 出错时，保存错误消息（metadata 中 status=error）

这意味着通过 API 提交的任务会出现在 WinClaw 首页的会话历史中，和通过 UI 发起的任务一样。

快速示例

cURL — 流式提交任务（pc_manager）

curl -N -X POST http://127.0.0.1:9199/api/external/tasks/stream \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "列出当前目录结构",
    "engine": "pc_manager",
    "config_id": "default"
  }'

cURL — 带自定义 metadata 和 conversation_title

curl -N -X POST http://127.0.0.1:9199/api/external/tasks/stream \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "帮我总结当前项目结构",
    "engine": "pc_manager",
    "config_id": "default",
    "conversation_title": "项目结构总结",
    "metadata": {"source": "external-client", "traceId": "t-001"}
  }'

cURL — 使用 RAG 引擎查询知识库

curl -N -X POST http://127.0.0.1:9199/api/external/tasks/stream \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "项目中如何处理用户认证？",
    "engine": "rag",
    "config_id": "<your-rag-id>",
    "include_history": true
  }'

cURL — 追加消息到已有对话

curl -N -X POST http://127.0.0.1:9199/api/external/tasks/stream \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "继续上面的话题，再详细说说",
    "engine": "pc_manager",
    "config_id": "default",
    "topic_id": "<from-task-event>",
    "conversation_id": "<from-task-event>"
  }'

cURL — 取消正在执行的任务

curl -X POST http://127.0.0.1:9199/api/external/tasks/cancel \
  -H "Content-Type: application/json" \
  -d '{"request_id": "<from-task-event>"}'

响应示例：

{"success": true, "request_id": "xxx", "message": "Task cancelled"}

PowerShell

$body = @{
  engine = "pc_manager"
  config_id = "default"
  prompt = "帮我总结当前项目结构"
  metadata = @{ source = "external-client"; traceId = "t-001" }
} | ConvertTo-Json -Depth 5

Invoke-WebRequest `
  -Uri "http://127.0.0.1:9199/api/external/tasks/stream" `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

Python

import requests
import json

resp = requests.post(
    "http://127.0.0.1:9199/api/external/tasks/stream",
    json={
        "prompt": "你好，请简单介绍一下你自己",
        "engine": "pc_manager",
        "config_id": "default",
    },
    stream=True,
)

for line in resp.iter_lines(decode_unicode=True):
    if not line:
        continue
    if line.startswith("data: "):
        data = json.loads(line[6:])
        evt_type = data.get("type")
        if evt_type == "task":
            print(f"Task started: request_id={data['request_id']}")
        elif evt_type == "content":
            print(data["content"], end="", flush=True)
        elif evt_type == "done":
            print(f"\n\nDone: assistant_message_id={data.get('assistant_message_id')}")
        elif evt_type == "error":
            print(f"\nError: {data['error']}")

与 CLI 工具集成

环境变量

调用此 API 的 CLI 工具应支持 WINCLAW_LOCAL_BASE_URL 环境变量：

func resolveBaseURL() string {
    if v := os.Getenv("WINCLAW_LOCAL_BASE_URL"); v != "" {
        return strings.TrimRight(v, "/")
    }
    return "http://127.0.0.1:9199"
}

当 WinClaw 运行在不同端口时，可以通过这个环境变量自定义 API 地址。

示例：agent_cron 外部任务

agent_cron 工具通过此 API 提交定时 AI 任务。当 external_task 类型的 cron 任务触发时，daemon 会：

  1. 根据任务配置（prompt、engine、config_id、metadata）构建请求体
  2. POST 到 /api/external/tasks/stream
  3. 解析 SSE 流，提取 request_id、内容和 assistant_message_id
  4. 将结果记录到运行记录中，供 agent_cron job logs 查看
# 添加定时外部任务
agent_cron job add --type external_task \
  --name "morning-report" \
  --cron "0 0 9 * * 1-5" \
  --prompt "请总结昨天的工作进展并列出今天的计划"

# daemon 会在每个工作日早上 9 点自动向 WinClaw 本地 API 发送请求

集成工作流

如果你要在自己的工具中集成此 API：

  1. POST /api/external/tasks/stream 发送 prompt
  2. 解析 SSE 行（event: + data:）
  3. 读取第一个 task 事件，缓存 ID（request_id、topic_id、conversation_id）
  4. 增量渲染 content / reasoning / tool_* 事件
  5. 收到 done 后，保存 assistant_message_id 用于追溯
  6. 如需取消，调用 /api/external/tasks/cancel 并传入 request_id
上一篇
Session CLI 工具