Pular para o conteúdo principal
O Plugin integrado admin-http-rpc expõe métodos selecionados do plano de controle do Gateway via HTTP para automação de host confiável que não pode usar o cliente RPC WebSocket normal do Gateway. O Plugin está incluído no OpenClaw, mas fica desativado por padrão. Quando desativado, a rota não é registrada. Quando ativado, ele adiciona:
  • POST /api/v1/admin/rpc
  • o mesmo listener que o Gateway: http://<gateway-host>:<port>/api/v1/admin/rpc
Ative-o apenas para ferramentas privadas de host, automação de tailnet ou um ingresso interno confiável. Não exponha esta rota diretamente à internet pública.

​
Antes de ativá-lo

O RPC HTTP administrativo é uma superfície completa do plano de controle do operador. Qualquer chamador que passe pela autenticação HTTP do Gateway pode invocar os métodos permitidos nesta página. Use-o quando todas estas condições forem verdadeiras:
  • O chamador é confiável para operar o Gateway.
  • O chamador não pode usar o cliente RPC WebSocket.
  • A rota só é acessível em loopback, uma tailnet ou um ingresso privado autenticado.
  • Você revisou os métodos permitidos e eles correspondem à automação que pretende executar.
Use o caminho RPC WebSocket para clientes OpenClaw e ferramentas interativas que podem manter uma conexão WebSocket do Gateway aberta.

​
Ativar

Ative o Plugin integrado: 
openclaw plugins enable admin-http-rpc
openclaw gateway restart
A rota é registrada durante a inicialização do Plugin. Reinicie o Gateway depois de alterar a configuração do Plugin. Desative-o quando não precisar mais da superfície HTTP: 
openclaw plugins disable admin-http-rpc
openclaw gateway restart

​
Verificar a rota

Use health como a menor solicitação segura: 
curl -sS http://<gateway-host>:<port>/api/v1/admin/rpc \
  -H 'Authorization: Bearer <gateway-token>' \
  -H 'Content-Type: application/json' \
  -d '{"method":"health","params":{}}'
Uma resposta bem-sucedida tem ok: true: 
{
  "id": "generated-request-id",
  "ok": true,
  "payload": {
    "status": "ok"
  }
}
Quando o Plugin está desativado, a rota retorna 404 porque não está registrada.

​
Autenticação

A rota do Plugin usa autenticação HTTP do Gateway. Caminhos comuns de autenticação:
  • autenticação por segredo compartilhado (gateway.auth.mode="token" ou "password"): Authorization: Bearer <token-or-password>
  • autenticação HTTP confiável com identidade (gateway.auth.mode="trusted-proxy"): encaminhe pela proxy configurada com reconhecimento de identidade e deixe-a injetar os cabeçalhos de identidade necessários
  • autenticação aberta de ingresso privado (gateway.auth.mode="none"): nenhum cabeçalho de autenticação é necessário

​
Modelo de segurança

Trate este Plugin como uma superfície completa de operador do Gateway.
  • Ativar o Plugin oferece intencionalmente acesso aos métodos RPC administrativos permitidos em /api/v1/admin/rpc.
  • O Plugin declara o contrato de manifesto reservado contracts.gatewayMethodDispatch: ["authenticated-request"] para que sua rota HTTP autenticada pelo Gateway possa despachar métodos do plano de controle no processo.
  • A autenticação bearer por segredo compartilhado comprova a posse do segredo de operador do gateway.
  • Para autenticação token e password, cabeçalhos x-openclaw-scopes mais restritos são ignorados, e os padrões normais de operador completo são restaurados.
  • Modos HTTP confiáveis com identidade respeitam x-openclaw-scopes quando presentes.
  • gateway.auth.mode="none" significa que esta rota não é autenticada se o Plugin estiver ativado. Use isso apenas por trás de um ingresso privado em que você confie totalmente.
  • As solicitações são despachadas pelos mesmos manipuladores de métodos do Gateway e verificações de escopo que o RPC WebSocket depois que a autenticação da rota do Plugin passa.
  • Mantenha esta rota em loopback, tailnet ou um ingresso privado confiável. Não a exponha diretamente à internet pública.
  • Contratos de manifesto de Plugin não são uma sandbox. Eles impedem o uso acidental de auxiliares reservados do SDK; Plugins confiáveis ainda são executados no processo do Gateway.
Use gateways separados quando os chamadores cruzarem limites de confiança.

​
Solicitação

POST /api/v1/admin/rpc
Authorization: Bearer <gateway-token>
Content-Type: application/json

{
  "id": "optional-request-id",
  "method": "health",
  "params": {}
}
Campos:
  • id (string, opcional): copiado para a resposta. Um UUID é gerado quando omitido.
  • method (string, obrigatório): nome de método do Gateway permitido.
  • params (any, opcional): parâmetros específicos do método.
O tamanho máximo padrão do corpo da solicitação é 1 MB.

​
Resposta

Respostas de sucesso usam o formato RPC do Gateway: 
{
  "id": "optional-request-id",
  "ok": true,
  "payload": {}
}
Erros de método do Gateway usam: 
{
  "id": "optional-request-id",
  "ok": false,
  "error": {
    "code": "INVALID_REQUEST",
    "message": "bad params"
  }
}
O status HTTP segue o erro do Gateway quando possível. Por exemplo, INVALID_REQUEST retorna 400, e UNAVAILABLE retorna 503.

​
Métodos permitidos

  • descoberta: commands.list Retorna os nomes de métodos RPC HTTP permitidos por este Plugin.
  • gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request
  • configuração: config.get, config.schema, config.schema.lookup, config.set, config.patch, config.apply
  • canais: channels.status, channels.start, channels.stop, channels.logout
  • web: web.login.start, web.login.wait
  • modelos: models.list, models.authStatus
  • agentes: agents.list, agents.create, agents.update, agents.delete
  • aprovações: exec.approvals.get, exec.approvals.set, exec.approvals.node.get, exec.approvals.node.set
  • Cron: cron.status, cron.list, cron.get, cron.runs, cron.add, cron.update, cron.remove, cron.run
  • dispositivos: device.pair.list, device.pair.approve, device.pair.reject, device.pair.remove
  • nós: node.list, node.describe, node.pair.list, node.pair.approve, node.pair.reject, node.pair.remove, node.rename
  • tarefas: tasks.list, tasks.get, tasks.cancel
  • diagnósticos: doctor.memory.status, update.status
Outros métodos do Gateway são bloqueados até serem adicionados intencionalmente.

​
Comparação com WebSocket

O caminho RPC WebSocket normal do Gateway continua sendo a API preferida do plano de controle para clientes OpenClaw. Use o RPC HTTP administrativo apenas para ferramentas de host que precisam de uma superfície HTTP de solicitação/resposta. Clientes WebSocket com token compartilhado sem uma identidade de dispositivo confiável não podem autodeclarar escopos administrativos durante a conexão. O RPC HTTP administrativo segue deliberadamente o modelo de operador HTTP confiável existente: quando o Plugin está ativado, a autenticação bearer por segredo compartilhado é tratada como acesso de operador completo para esta superfície administrativa.

​
Solução de problemas

404 Not Found : O Plugin está desativado, o Gateway não foi reiniciado desde que ele foi ativado, ou a solicitação está indo para um processo diferente do Gateway. 401 Unauthorized : A solicitação não satisfez a autenticação HTTP do Gateway. Verifique o token bearer ou os cabeçalhos de identidade do trusted-proxy. 400 INVALID_REQUEST : O corpo da solicitação não é JSON válido, o campo method está ausente, ou o método não está na lista de permissões do Plugin. 503 UNAVAILABLE : O manipulador de método do Gateway está indisponível. Verifique os logs do Gateway e tente novamente depois que o Gateway terminar a inicialização.

​
Relacionados