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）。

入口读取示例

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 临时链接）

references/knowledgebase.md — 知识库管理

• 知识库 CRUD（创建、列出、获取、更新检索配置、删除）
• 文档管理（上传、导入本地文件、列出、下载、重建索引、替换、删除）
• 分块管理（列出、创建、更新内容、删除）
• 知识库检索（hybrid/dense/keyword 模式、相似度阈值、Top K、Rerank 重排序）
• 检索日志（列出、创建、清空）

references/scheduler.md — 定时任务

• 创建定时任务（绑定工作流 + 触发器 + 输入参数）
• 触发器配置（Cron 表达式 / 固定间隔 / 一次性定时）
• 任务 CRUD（创建、列出、获取、更新、删除）
• 任务控制（暂停、恢复、立即触发）
• Webhook 外部触发（Secret 验证、输入覆盖）
• 执行历史（列出执行记录、获取执行详情）
• 执行配置（超时、重试、并发策略）

references/channels.md — 渠道管理

• 渠道 CRUD（创建飞书/钉钉/企微/QQ 渠道，配置 app_id/app_secret、会话模式、绑定工作流）
• 重启渠道 Bot 连接
• 验证渠道凭据（创建前检测配置是否有效）
• 渠道消息日志（全局/单渠道日志列表、按状态筛选、日志统计）

references/traces.md — 追踪与监控

• 追踪摘要（总数、成功/失败/运行中/超时统计、平均耗时）
• 追踪列表（按工作流/状态/时间范围筛选，分页）
• 追踪详情（节点执行日志 NodeLog、LLM 调用日志 LLMLog、输入输出数据）
• 追踪时间线（按时间排序的事件序列，用于可视化）
• 仪表盘统计与趋势（24h/7d/30d）

references/prompts_models.md — 提示词与模型管理

• 提示词列表/获取/更新（热加载，立即生效）/重置为默认值
• 提示词版本历史与回滚到指定版本
• 模型列表（含降级状态 FallbackState）
• 模型配置更新（temperature、max_tokens、timeout）
• 切换工作流节点模型
• 手动降级到备用模型 / 恢复主模型

references/workflow_admin.md — 工作流管理与任务管理

• 工作流列表（含 24h 统计）、详情（节点拓扑、边、输入 Schema、统计）
• 工作流统计与趋势（24h/7d/30d）
• 热加载工作流文件（从文件系统注册/替换工作流）
• 工具配置（启禁用 skills 和 tools）
• 任务管理（列出运行中任务、取消任务、清理已完成任务）