agentclaw_api

AgentClaw 平台 API 使用指南

Read this file first. Read references/* only when需要操作具体模块时。

何时使用 agentclaw_api

• 用户请求可以由已注册的 AgentClaw workflow/agent 能力完成，例如运行、触发、查询或续传已有工作流。
• 用户要创建、查询、更新、删除、暂停、恢复或立即触发定时任务。
• 用户说“每天/每小时/定期/周期性/cron/自动运行某个工作流或智能体”。
• 用户要把已经创建的工作流接入平台运行能力，例如热注册工作流文件、调用工作流、配置调度、查看执行历史。
• 用户要通过平台 API 管理知识库、渠道、对话、文件、提示词、模型、追踪日志。

定时任务相关操作请读取 references/scheduler.md，创建任务使用 POST /api/scheduler/jobs。

调用方式

• 入口: {BASE_URL} 是服务启动时写入 <project_dir>/.agentclaw/relay.json 的 internal_url。它是独立本机 internal relay 地址，通常不同于主服务端口。
• 备用入口: 环境变量 AGENTCLAW_INTERNAL_URL 也可提供同一个本机 relay 地址。
• 认证: 所有内部 agent/shell 请求通过 /_internal/ 前缀访问，relay 会在服务端完成认证。请求只需要业务 payload 和 Content-Type: application/json。
• 拼接规则: {BASE_URL}/_internal + 文档路径。文档里的 /api/...、/admin/... 是目标路径，不是最终 URL。
• 工具选择: 调用 API 时使用 python 或 shell 工具发送 HTTP 请求（例如 requests.post()、curl）。

文档路径	实际调用路径
/api/workflow/run	{BASE_URL}/_internal/api/workflow/run
/admin/knowledgebases	{BASE_URL}/_internal/admin/knowledgebases
/api/scheduler/jobs	{BASE_URL}/_internal/api/scheduler/jobs

入口读取示例

import json
import os
from pathlib import Path

project_dir = Path(os.getenv("AGENTCLAW_PROJECT_DIR", ".")).resolve()
relay_config = project_dir / ".agentclaw" / "relay.json"
base_url = os.getenv("AGENTCLAW_INTERNAL_URL", "").rstrip("/")
if not base_url and relay_config.exists():
    base_url = json.loads(relay_config.read_text(encoding="utf-8"))["internal_url"].rstrip("/")

url = f"{base_url}/_internal/api/workflow/run"

错误响应

{"error": "错误描述", "code": "ERROR_CODE"}

HTTP 状态码: 400 参数错误, 401 未认证, 404 未找到, 500 内部错误

---

按需读取参考文档

references/workflow.md — 工作流执行与对话

• 列出所有可用工作流
• 执行工作流（blocking 同步 / streaming SSE 流）
• HumanNode 交互续传（等待人工输入后继续）
• 确认危险操作
• SSE 流模式事件序列
• 上下文压缩 / 截断（编辑重试）
• 对话 CRUD（创建、列出、获取详情含消息、更新标题、删除）
• 消息反馈（like / dislike）
• 文件上传 / 下载（multipart 上传、按 ID 下载、Token 临时链接）