CSGClaw: HTTP API and configuration

← Back to CSGClaw overview

HTTP API conventions

• Default base: http://127.0.0.1:18080; actual listen address comes from listen_addr in config.toml.
• Content-Type: usually application/json except for SSE.
• Time: RFC3339 / ISO8601.
• Auth: many routes work without a token; /api/bots/* and GET /api/v1/channels/feishu/bots/{id}/events need Authorization: Bearer <token>.
• Errors: failures may return plain text, not always a JSON envelope.

Health

• GET /healthz → example body: ok

Agents

• GET /api/v1/agents: list
• POST /api/v1/agents: create role=worker agent and sync IM user; name required and must not be manager; optional id, profile

Built-in IM (selected endpoints)

Method	Path	Description
GET	/api/v1/im/bootstrap	IM bootstrap payload
GET	/api/v1/im/events	SSE stream
POST	/api/v1/im/messages	Send message
POST	/api/v1/im/conversations	Create room
POST	/api/v1/im/conversations/members	Invite member
GET	/api/v1/rooms	List sessions
POST	/api/v1/rooms	Create session (same body as conversations)
DELETE	/api/v1/rooms/{id}	Delete session
GET	/api/v1/users	List users
DELETE	/api/v1/users/{id}	Delete user; cleans session traces per server rules
GET	/api/v1/messages	History; query room_id
POST	/api/v1/messages	Send message
POST	/api/v1/im/agents/join	Join agent to session

Compatibility aliases

• 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 required)

• GET /api/bots/{bot_id}/events: SSE
• POST /api/bots/{bot_id}/messages/send: bot sends message
• GET /api/bots/{bot_id}/llm/v1/models: OpenAI-compatible model list
• POST /api/bots/{bot_id}/llm/v1/chat/completions: chat completions; server may rewrite model from agent profile and proxy upstream

Feishu

• GET /api/v1/channels/feishu/bots/{id}/events: SSE with Bearer matching [server].access_token

Bot (REST v1)

• GET /api/v1/bots, POST /api/v1/bots, etc. for listing/creating bots bound to agents and channel users; prefer /api/v1/bots for new bots.

Local config.toml

Written by onboard, read by serve. Strings may use ${NAME} / $NAME for env expansion; unset vars become empty.

[server]

Field	Meaning
listen_addr	Bind address, e.g. 0.0.0.0:18080
advertise_base_url	URL workers/manager use to reach this service; if empty, inferred from local IPv4 + port
access_token	Protects authenticated routes; use Authorization: Bearer
no_auth	Default false; true skips bearer checks—only for trusted local/dev

[models] and [models.providers.*]

• default: default profile name, e.g. csghub-lite.Qwen/Qwen3-0.6B-GGUF.
• Each provider: base_url, api_key, models list, etc.

Example with local 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"]

Add [models.providers.<name>] and point [models].default at remote OpenAI-compatible or CLIProxyAPI providers as needed.

[bootstrap]

• manager_image: container image for bootstrap Manager.

[sandbox]

• provider: often boxlite-sdk or boxlite-cli.
• home_dir_name, boxlite_cli_path, debian_registries: BoxLite data dir, CLI path, Debian base image registry priority.
• onboard can set debian_registries via --debian-registries.

Feishu channels.feishu

• See Web UI — Feishu (optional); keep secrets local.

CSGHub Sandbox (advanced)

For SaaS-style platform runs, set [sandbox].provider to csghub and configure the CSGHub Sandbox API URL, tokens, resource limits, and timeouts per your deployment guide.

Repository: https://github.com/OpenCSGs/csgclaw