REST API do OpenClaw
REST API do OpenClaw
A API REST permite integrar o OpenClaw com qualquer sistema que faça requisições HTTP. Ideal para backends, scripts e automações.
🌐 Base URL
http://localhost:18789
Nota: A porta pode ser diferente se você alterou em config.
🔐 Autenticação
Se configurado, envie o token no header:
Authorization: Bearer seu_token_aqui
Para configurar autenticação, adicione em clawdbot.json:
{
"gateway": {
"auth": {
"token": "seu_token_secreto"
}
}
}
📬 Endpoints
POST /api/message — Enviar Mensagem
Envia uma mensagem para um canal específico.
Request:
POST /api/message
Content-Type: application/json
{
"channel": "telegram",
"to": "123456789",
"message": "Olá! Esta é uma mensagem via API."
}
Parâmetros:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
channel | string | ✅ | Canal de destino (telegram, whatsapp, discord) |
to | string | ✅ | ID do destinatário |
message | string | ✅ | Conteúdo da mensagem |
Response (200 OK):
{
"success": true,
"messageId": "abc123"
}
Exemplo com cURL:
curl -X POST http://localhost:18789/api/message \
-H "Content-Type: application/json" \
-d '{"channel": "telegram", "to": "123456789", "message": "Teste!"}'
GET /api/status — Status do Sistema
Retorna o status geral do gateway e canais.
Request:
GET /api/status
Response:
{
"status": "running",
"uptime": 3600,
"channels": {
"telegram": { "status": "connected", "lastMessage": "2025-01-15T10:30:00Z" },
"whatsapp": { "status": "connected", "lastMessage": "2025-01-15T09:15:00Z" }
},
"memory": {
"used": 156000000,
"total": 512000000
}
}
Útil para: Monitoramento, health checks, dashboards.
GET /api/sessions — Listar Sessões
Lista todas as sessões de conversa ativas.
Request:
GET /api/sessions
Response:
{
"sessions": [
{
"key": "telegram:123456789",
"lastActivity": "2025-01-15T10:30:00Z",
"messageCount": 42
}
]
}
GET /api/sessions/:key/history — Histórico de Sessão
Retorna o histórico de uma sessão específica.
Request:
GET /api/sessions/telegram:123456789/history
Query Parameters:
| Param | Tipo | Padrão | Descrição |
|---|---|---|---|
limit | number | 50 | Quantidade de mensagens |
offset | number | 0 | Pular N mensagens |
Response:
{
"messages": [
{ "role": "user", "content": "Olá!", "timestamp": "..." },
{ "role": "assistant", "content": "Oi! Como posso ajudar?", "timestamp": "..." }
]
}
GET /health — Health Check
Endpoint simples para verificar se o gateway está ativo.
Request:
GET /health
Response (200 OK):
{
"status": "ok"
}
Útil para: Load balancers, Kubernetes probes, monitoramento.
🔗 Webhooks (Receber Eventos)
Configure endpoints para receber eventos externos (ex: GitHub, Stripe).
Configuração em clawdbot.json:
{
"webhooks": [
{
"path": "/webhook/github",
"handler": "github-events",
"secret": "seu_webhook_secret"
}
]
}
Como funciona:
- Serviço externo envia POST para
http://seu-servidor:18789/webhook/github - OpenClaw valida o payload
- Handler processa e pode notificar você
💻 Exemplos de Integração
Python
import requests
response = requests.post(
"http://localhost:18789/api/message",
json={
"channel": "telegram",
"to": "123456789",
"message": "Mensagem via Python!"
}
)
print(response.json())
Node.js
const response = await fetch("http://localhost:18789/api/message", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
channel: "telegram",
to: "123456789",
message: "Mensagem via Node.js!"
})
});
console.log(await response.json());
Bash (cURL)
curl -X GET http://localhost:18789/api/status | jq
🔗 Próximos Passos
- WebSocket API — Para streaming em tempo real
- CLI Reference — Alternativa via linha de comando
- Configuração — Customize a API