跳到主要内容

CSGClaw：API 与配置说明

← 返回 CSGClaw 概览

HTTP API 约定​

  • 默认基址：http://127.0.0.1:18080，实际以 config.toml 中 listen_addr 为准。
  • 内容类型：除 SSE 外，一般为 application/json。
  • 时间：RFC3339 / ISO8601。
  • 认证：多数接口可不携带 Token；/api/bots/* 与 GET /api/v1/channels/feishu/bots/{id}/events 需要 Authorization: Bearer <token>。
  • 错误：失败时常见为纯文本错误信息，未必是统一 JSON 结构。

健康检查​

  • GET /healthz → 响应体示例：ok

Agent​

  • GET /api/v1/agents：列表
  • POST /api/v1/agents：创建 role=worker 的 agent，并同步 IM 用户；name 必填且不能为 manager；id 可选；profile 可选

内置 IM（节选）​

方法路径说明
GET/api/v1/im/bootstrapIM 初始化数据
GET/api/v1/im/eventsSSE 事件流
POST/api/v1/im/messages发消息
POST/api/v1/im/conversations创建房间
POST/api/v1/im/conversations/members邀请成员
GET/api/v1/rooms会话列表
POST/api/v1/rooms创建会话（请求体同 conversations）
DELETE/api/v1/rooms/{id}删除会话
GET/api/v1/users用户列表
DELETE/api/v1/users/{id}删除用户；会清理其在各会话中的痕迹，规则以服务端实现为准
GET/api/v1/messages消息历史，查询参数 room_id
POST/api/v1/messages发消息
POST/api/v1/im/agents/join将 agent 加入会话

兼容别名（与上文等价）​

  • GET /api/v1/bootstrap
  • GET /api/v1/events
  • POST /api/v1/rooms/invite
  • POST /api/v1/im/rooms
  • POST /api/v1/im/rooms/invite

PicoClaw Bot（需 Bearer）​

  • GET /api/bots/{bot_id}/events：SSE
  • POST /api/bots/{bot_id}/messages/send：Bot 发消息
  • GET /api/bots/{bot_id}/llm/v1/models：OpenAI 兼容模型列表
  • POST /api/bots/{bot_id}/llm/v1/chat/completions：聊天补全；服务端按 agent profile 改写 model 并转发上游

Feishu​

  • GET /api/v1/channels/feishu/bots/{id}/events：SSE，需 Bearer（与 [server].access_token 一致）

Bot（REST v1）​

  • GET /api/v1/bots、POST /api/v1/bots 等用于 Bot 列表与创建，与 Agent、渠道用户绑定；新建 Bot 建议统一走 /api/v1/bots 相关路由。

本地配置 config.toml​

由 onboard 写入、serve 读取。字符串可用 ${NAME} / $NAME 引用环境变量；未设置时展开为空字符串。

[server]​

字段含义
listen_addr监听地址，如 0.0.0.0:18080
advertise_base_urlManager / Worker 回连本服务的地址；为空时由本机 IPv4 与端口推断
access_token保护需鉴权路由；请求头使用 Authorization: Bearer
no_auth默认 false；true 时跳过 bearer 校验，仅建议在可信本地或开发环境使用

[models] 与 [models.providers.*]​

  • default：默认 profile 名，例如 csghub-lite.Qwen/Qwen3-0.6B-GGUF。
  • 每个 provider 配置 base_url、api_key、models 列表等。

本地 CSGHub-lite 示例：

[server]
listen_addr = "0.0.0.0:18080"
advertise_base_url = "http://127.0.0.1:18080"
access_token = "your_access_token"
no_auth = false

[models]
default = "csghub-lite.Qwen/Qwen3-0.6B-GGUF"

[models.providers.csghub-lite]
base_url = "http://127.0.0.1:11435/v1"
api_key = "local"
models = ["Qwen/Qwen3-0.6B-GGUF"]

[bootstrap]
manager_image = "opencsg-registry.cn-beijing.cr.aliyuncs.com/opencsghq/picoclaw:2026.4.24.0"

[sandbox]
provider = "boxlite-sdk"
home_dir_name = "boxlite"
boxlite_cli_path = "boxlite"
debian_registries = ["harbor.opencsg.com", "docker.io"]

远程 OpenAI 兼容 API、CLIProxyAPI 等其它 provider，按同样结构增加 [models.providers.<name>] 并调整 [models].default 即可。

[bootstrap]​

  • manager_image：引导 Manager 使用的容器镜像。

[sandbox]​

  • provider：常见为 boxlite-sdk；也可为 boxlite-cli。
  • home_dir_name、boxlite_cli_path、debian_registries：BoxLite 数据目录、CLI 路径、Debian 基础镜像 registry 优先级等。
  • 可在 onboard 时使用 --debian-registries 写入 debian_registries。

飞书 channels.feishu​

CSGHub Sandbox 部署（进阶）​

在平台侧以 SaaS 方式运行时，可将 [sandbox].provider 设为 csghub，并配置 CSGHub Sandbox API 地址、令牌以及沙箱资源、超时等环境变量；具体变量名与挂载约定随部署方案而定，需与平台运维文档对齐。

项目主页： https://github.com/OpenCSGs/csgclaw