API REST do OpenClaw — Docs com Exemplos em Python, Node.js e cURL
Documentação completa da API REST do OpenClaw: todos os endpoints, autenticação, exemplos prontos em Python, Node.js e cURL. Envie mensagens, consulte status, crie webhooks. Copie e cole.
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.
http://localhost:18789
Nota: A porta pode ser diferente se você alterou em config.
Se configurado, envie o token no header:
Authorization: Bearer seu_token_aqui
Para configurar autenticação, adicione em config.yaml:
gateway:
auth:
token: "seu_token_secreto"
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 | Sim | Canal de destino (telegram, whatsapp, discord) |
to | string | Sim | ID do destinatário |
message | string | Sim | 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!"}'
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.
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
}
]
}
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": "..." }
]
}
Endpoint simples para verificar se o gateway está ativo.
Request:
GET /health
Response (200 OK):
{
"status": "ok"
}
Útil para: Load balancers, Kubernetes probes, monitoramento.
Configure endpoints para receber eventos externos (ex: GitHub, Stripe).
Configuração em config.yaml:
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ê
import requests
response = requests.post(
"http://localhost:18789/api/message",
json={
"channel": "telegram",
"to": "123456789",
"message": "Mensagem via Python!"
}
)
print(response.json())
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());
curl -X GET http://localhost:18789/api/status | jq
- WebSocket API — Para streaming em tempo real
- CLI Reference — Alternativa via linha de comando
- Configuração — Customize a API