Gateway API 参考¶

Echo Agent Gateway 提供 HTTP REST API 和 WebSocket 端点，用于外部系统集成和 Dashboard 通信。

基本信息¶

项目	值
默认地址	`http://127.0.0.1:58123`
默认 API 前缀	`/api/v1`
协议	HTTP/1.1, WebSocket
内容类型	`application/json`
认证方式	Token Header / Pairing

认证¶

认证模式¶

模式	说明	配置值
open	无认证（仅本地使用）	`gateway.auth.mode: open`
allowlist	Token 白名单	`gateway.auth.mode: allowlist`
pairing	配对码认证	`gateway.auth.mode: pairing`

Token 认证¶

请求时在 Header 中携带 Token：

GET /api/sessions HTTP/1.1
Host: localhost:8080
X-Echo-Agent-Token: your-api-token-here

Token Header 名称可通过 gateway.auth.token_header 自定义。

权限级别¶

Token 类型	权限
`api_tokens`	读取 + 会话操作
`admin_tokens`	管理读取与写操作；未单独配置时回退到 `api_tokens`

安全防护¶

Origin 检查: 仅允许 gateway.auth.allowed_origins 中列出的来源
Host 检查: 仅允许 gateway.auth.allowed_hosts 中列出的 Host
Pairing 码过期: 默认 300 秒（gateway.auth.pairing_ttl_seconds）

REST API 端点¶

会话管理¶

GET /api/sessions¶

列出所有会话。

请求参数（Query）:

参数	类型	说明
`status`	string	过滤状态：active / idle / closed
`limit`	int	返回数量限制
`offset`	int	分页偏移

响应示例:

{
  "sessions": [
    {
      "id": "sess_abc123",
      "status": "active",
      "channel": "slack",
      "created_at": "2024-01-15T10:30:00Z",
      "last_message_at": "2024-01-15T11:45:00Z",
      "message_count": 42
    }
  ],
  "total": 15,
  "limit": 10,
  "offset": 0
}

POST /api/sessions¶

创建新会话。

请求体:

{
  "channel": "api",
  "metadata": {
    "user": "admin"
  }
}

响应: 201 Created

{
  "id": "sess_new456",
  "status": "active",
  "channel": "api",
  "created_at": "2024-01-15T12:00:00Z"
}

GET /api/v1/sessions/{key}/turns¶

查询会话的持久化回合状态（需管理权限）。limit 范围为 1–100，默认 20。返回值中的 status 可为 accepted、running、waiting_approval、waiting_clarification、completed、incomplete、failed 或 interrupted。

GET /api/v1/turns/{event_id}¶

按入站事件 ID 查询单个回合。记录包含当前工具、回复文本、终止原因及开始/完成时间；状态账本不可用时返回 503。

记忆管理¶

GET /api/memory¶

查询记忆条目。

参数	类型	说明
`query`	string	搜索关键词
`key`	string	精确键名
`limit`	int	返回数量

POST /api/memory¶

写入记忆。

{
  "key": "user_preference",
  "value": "偏好暗色主题",
  "metadata": {
    "source": "api",
    "ttl": 86400
  }
}

DELETE /api/memory/{key}¶

删除指定记忆条目。需要 admin 权限。

知识库¶

GET /api/knowledge¶

查询知识库。

参数	类型	说明
`query`	string	语义搜索查询
`top_k`	int	返回结果数
`filter`	string	元数据过滤（JSON）

POST /api/knowledge¶

添加知识条目。

{
  "content": "Echo Agent 支持多通道集成...",
  "metadata": {
    "source": "docs",
    "category": "features"
  }
}

DELETE /api/knowledge/{id}¶

删除知识条目。需要 admin 权限。

技能管理¶

GET /api/skills¶

列出所有技能。

参数	类型	说明
`status`	string	active / staged / disabled
`category`	string	按分类过滤

GET /api/skills/{id}¶

获取技能详情。

POST /api/skills/{id}/enable¶

启用技能。

POST /api/skills/{id}/disable¶

禁用技能。

任务管理¶

GET /api/tasks¶

列出任务。

参数	类型	说明
`status`	string	pending / running / completed / failed
`session_id`	string	按会话过滤

POST /api/tasks¶

创建任务。需要 admin 权限。成功返回 201 与 {"task": {...}}。

{
  "title": "整理本周会议纪要",
  "description": "按项目分组，输出到知识库",
  "priority": 5,
  "labels": ["weekly"],
  "assignee": "",
  "source": "human",
  "board_id": "default",
  "parent_task_id": "",
  "metadata": {}
}

只有 title 必填，为空返回 400。priority 必须是整数（默认 5，布尔值不接受），labels 必须是字符串数组，metadata 必须是对象，否则均返回 400。parent_task_id 用于挂到父任务下。

同样的字段校验也适用于 PATCH /api/tasks/{id}，其中只校验请求里实际出现的字段。

定时任务¶

GET /api/cron¶

列出定时任务。

POST /api/cron¶

创建定时任务。

{
  "schedule": "0 9 * * 1-5",
  "task": "发送每日工作摘要",
  "enabled": true
}

PUT /api/cron/{id}¶

更新定时任务。

DELETE /api/cron/{id}¶

删除定时任务。需要 admin 权限。

通道管理¶

GET /api/channels¶

列出所有通道及其状态。

响应示例:

{
  "channels": [
    {
      "name": "slack",
      "status": "connected",
      "connected_at": "2024-01-15T08:00:00Z",
      "message_count": 1234
    },
    {
      "name": "telegram",
      "status": "disconnected",
      "last_error": "Connection timeout"
    }
  ]
}

POST /api/channels/{name}/reconnect¶

触发通道重连。

分析统计¶

GET /api/analytics¶

获取使用统计数据。

参数	类型	说明
`period`	string	today / week / month
`group_by`	string	model / tool / channel

响应示例:

{
  "period": "today",
  "total_messages": 156,
  "total_tokens": 234567,
  "total_cost_usd": 2.34,
  "by_model": {
    "claude-sonnet-4-20250514": {
      "requests": 89,
      "tokens": 156000,
      "cost_usd": 1.87
    }
  },
  "by_tool": {
    "search": 45,
    "memory": 23,
    "filesystem": 12
  }
}

配置¶

GET /api/config¶

获取当前配置（脱敏）。需要 admin 权限。

PATCH /api/config¶

运行时修改配置。需要 admin 权限。

{
  "models.primary.temperature": 0.5,
  "tools.approval_mode": "auto"
}

运行时配置

通过 API 修改的配置仅在当前运行期间生效，不会持久化到配置文件。重启后恢复文件配置。

日志¶

GET /api/logs¶

获取系统日志。

参数	类型	说明
`level`	string	最低级别过滤
`since`	string	起始时间（ISO 8601）
`limit`	int	返回行数，默认 100
`follow`	bool	SSE 模式持续推送

健康检查¶

GET `{api_prefix}/health`¶

健康检查端点，默认路径为 /api/v1/health，无需认证。

响应:

{
  "status": "healthy",
  "server_running": true,
  "active_channels": {"telegram": "active"},
  "ws_clients": 1,
  "provider": "ok",
  "media_cache_mb": 2.4,
  "active_sessions": 1,
  "total_sessions": 8
}

状态	HTTP 码	说明
healthy	200	所有组件正常
degraded	200	部分组件异常但可服务
unhealthy	503	无法正常服务

通用响应格式¶

成功响应¶

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T12:00:00Z"
  }
}

错误响应¶

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "details": {}
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2024-01-15T12:00:00Z"
  }
}

错误码¶

HTTP 状态码	错误码	说明
400	BAD_REQUEST	请求参数无效
401	UNAUTHORIZED	未认证或 Token 无效
403	FORBIDDEN	权限不足
404	NOT_FOUND	资源不存在
409	CONFLICT	资源冲突（幂等键被改内容复用）
429	RATE_LIMITED	请求频率超限
500	INTERNAL_ERROR	服务器内部错误
503	UNAVAILABLE	服务不可用

幂等重试¶

投递消息的接口支持幂等键，用于在网络抖动、超时重连后安全重试，而不会让同一条消息被处理两次。

携带幂等键¶

入口	传递方式
`POST {api_prefix}/message`	`Idempotency-Key` 或 `X-Idempotency-Key` 请求头
Webhook 通道	同上两个请求头，或请求体的 `idempotency_key` 字段
WebSocket `message` 帧	帧内的 `idempotency_key` 字段

键的约束：非空字符串，最长 200 字符，不含控制字符。同时提供请求头和请求体且两者不一致时返回 400。

curl -X POST http://127.0.0.1:58123/api/v1/message \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-2026-0829-001" \
  -d '{"platform":"api","user_id":"u1","chat_id":"c1","text":"生成周报"}'

重试语义¶

相同键 + 相同请求内容 → 复用首次的事件与响应，不会重复投递：

{"status": "accepted", "event_id": "38919935...", "session_key": "gateway:api:c1"}

相同键 + 不同请求内容 → 409，请求被拒绝，不产生新事件：

{"error": "idempotency key was already used for a different request"}

409 只表示键冲突

409 专用于「同一个键被用于不同内容」这一种情况，客户端不应重试——应换新键或修回原内容。任务未完成（incomplete / interrupted）返回的是 200，语义由响应体的 status 字段承载，这类请求是可以重试的。

作用域与有效期¶

键的作用域包含调用方身份，不同 token 之间互不干扰：

入口	作用域组成
HTTP	token 派生的 principal + `session_key`
WebSocket	同上（按连接握手身份）
Webhook	`sender_id` + `chat_id`

参数	值
记录有效期	3600 秒（1 小时）
进程内缓存条数	Gateway 4096 / Webhook 2048
持久化记录上限	100000 条

记录同时写入 SQLite，因此跨进程重启的重试仍可去重并重放结果，不受单会话回合裁剪影响。存储不可用、或未过期记录已达容量上限时，接口 fail closed 返回 503 而不是放行可能重复执行的请求。

与 `wait` 的配合¶

wait=false（默认）时缓存的是投递回执（accepted）；wait=true 时缓存的是回合最终结果。若首个请求仍在处理中，并发的重试会等待同一结果而非重复触发，超时返回 504。

频率限制¶

API 请求受频率限制控制。限制信息通过响应头返回：

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1705312800

分页¶

分页统一为 offset-based，通过 limit 与 offset 查询参数控制，没有 cursor 分页。

各端点的默认 limit 并不统一，需按端点查阅：

端点	默认 `limit`	支持 `offset`
`/api/logs`	200	是
`/api/memory`	50	是
`/api/sessions`	100	否
`/api/sessions/{key}/history`	100	否
cron 执行历史	10	否

未提供 offset 的端点只能取首屏，无法翻页。

/api/sessions/{key}/history 的 limit 取值范围是 1–500，越界返回 400。响应里 total 是整段可见历史的条数（用于判断是否还有更早的记录），returned 才是本次返回的条数——两者不要混用。

Gateway API 参考¶

基本信息¶

认证¶

认证模式¶

Token 认证¶

权限级别¶

安全防护¶

REST API 端点¶

会话管理¶

GET /api/sessions¶

POST /api/sessions¶

GET /api/v1/sessions/{key}/turns¶

GET /api/v1/turns/{event_id}¶

记忆管理¶

GET /api/memory¶

POST /api/memory¶

DELETE /api/memory/{key}¶

知识库¶

GET /api/knowledge¶

POST /api/knowledge¶

DELETE /api/knowledge/{id}¶

技能管理¶

GET /api/skills¶

GET /api/skills/{id}¶

POST /api/skills/{id}/enable¶

POST /api/skills/{id}/disable¶

任务管理¶

GET /api/tasks¶

POST /api/tasks¶

定时任务¶

GET /api/cron¶

POST /api/cron¶

PUT /api/cron/{id}¶

DELETE /api/cron/{id}¶

通道管理¶

GET /api/channels¶

POST /api/channels/{name}/reconnect¶

分析统计¶

GET /api/analytics¶

配置¶

GET /api/config¶

PATCH /api/config¶

日志¶

GET /api/logs¶

健康检查¶

GET {api_prefix}/health¶

通用响应格式¶

成功响应¶

错误响应¶

错误码¶

幂等重试¶

携带幂等键¶

重试语义¶

作用域与有效期¶

与 wait 的配合¶

频率限制¶

分页¶

GET `{api_prefix}/health`¶

与 `wait` 的配合¶