Plugin de RPC HTTP administrativo

O plugin admin-http-rpc incluído expõe um conjunto de métodos do plano de controle do Gateway definido em uma lista de permissões por HTTP, para automações confiáveis do host que não conseguem manter aberta uma conexão WebSocket com o Gateway.

Ele é fornecido com o OpenClaw, mas fica desativado por padrão; quando desativado, a rota não é registrada. Quando ativado, adiciona POST /api/v1/admin/rpc ao mesmo listener do Gateway (http://<gateway-host>:<port>/api/v1/admin/rpc).

Ative-o somente para ferramentas privadas do host, automações na tailnet ou um ingresso interno confiável. Nunca exponha essa rota diretamente à internet pública.

Antes de ativá-lo

O RPC HTTP administrativo é uma superfície completa do plano de controle do operador: qualquer cliente que passe pela autenticação HTTP do Gateway pode invocar os métodos da lista de permissões abaixo. Ative-o somente quando todas estas condições forem verdadeiras:

• O cliente é confiável para operar o Gateway.
• O cliente não pode usar o cliente RPC WebSocket.
• A rota pode ser acessada somente por local loopback, uma tailnet ou um ingresso privado autenticado.
• Você revisou os métodos permitidos e eles correspondem à automação que pretende executar.

Para clientes do OpenClaw e ferramentas interativas que conseguem manter aberta uma conexão WebSocket com o Gateway, use RPC WebSocket.

Ativar

Ative o plugin incluído:

openclaw plugins enable admin-http-rpcopenclaw gateway restart

{  plugins: {    entries: {      "admin-http-rpc": { enabled: true },    },  },}

A rota é registrada durante a inicialização do plugin; portanto, reinicie o Gateway após alterar a configuração do plugin.

Desative-o quando não precisar mais da superfície HTTP:

openclaw plugins disable admin-http-rpcopenclaw 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 contém ok: true:

{  "id": "generated-request-id",  "ok": true,  "payload": {    "status": "ok"  }}

Quando o plugin está desativado, a rota retorna 404, pois não está registrada.

Autenticação

A rota do plugin usa a autenticação HTTP do Gateway.

Formas 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 a rota pelo proxy configurado com reconhecimento de identidade e permita que ele injete os cabeçalhos de identidade necessários
• autenticação aberta em 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 operação do Gateway.

• A ativação do plugin disponibiliza intencionalmente o acesso aos métodos RPC administrativos da lista de permissões em /api/v1/admin/rpc.
• O plugin declara o contrato reservado de manifesto contracts.gatewayMethodDispatch: ["authenticated-request"], que permite à sua rota HTTP autenticada pelo Gateway despachar métodos do plano de controle dentro do processo. Isso não é um sandbox: o contrato impede o uso acidental de auxiliares reservados do SDK, mas plugins confiáveis ainda são executados no processo do Gateway.
• A autenticação bearer por segredo compartilhado (modos token/password) comprova a posse do segredo do operador do Gateway; cabeçalhos x-openclaw-scopes mais restritos são ignorados nesse caminho, e os padrões normais de operador completo são restaurados.
• A autenticação HTTP confiável com identidade (modo trusted-proxy) respeita x-openclaw-scopes quando presente.
• gateway.auth.mode="none" significa que essa rota não exige autenticação quando o plugin está ativado. Use essa opção somente atrás de um ingresso privado em que você confia plenamente.
• Depois que a autenticação da rota do plugin é aprovada, as solicitações são despachadas pelos mesmos manipuladores de métodos e verificações de escopo do Gateway usados pelo RPC WebSocket.
• A rota permanece acessível durante uma concessão de suspensão preparada. A validação limitada de solicitações e a resposta de descoberta local de commands.list permanecem disponíveis. Entre os métodos despachados para o Gateway, somente gateway.suspend.prepare, gateway.suspend.status e gateway.suspend.resume podem ser executados enquanto a admissão está fechada; os outros métodos da lista de permissões retornam a resposta normal e repetível UNAVAILABLE do Gateway.
• Mantenha essa rota em local loopback, na tailnet ou em um ingresso privado confiável. Não a exponha diretamente à internet pública. Use gateways separados quando os clientes estiverem em limites de confiança distintos.

Solicitação

POST /api/v1/admin/rpcAuthorization: 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 permitido do Gateway.
• params (qualquer tipo, opcional): parâmetros específicos do método.

O tamanho máximo padrão do corpo da solicitação é 1 MB.

Resposta

As respostas bem-sucedidas usam o formato RPC do Gateway:

{  "id": "optional-request-id",  "ok": true,  "payload": {}}

Os erros dos métodos do Gateway usam:

{  "id": "optional-request-id",  "ok": false,  "error": {    "code": "INVALID_REQUEST",    "message": "bad params"  }}

O status HTTP corresponde ao código do erro:

Métodos permitidos

• descoberta: commands.list Retorna os nomes dos métodos RPC HTTP permitidos por este plugin.
• gateway: health, status, logs.tail, usage.status, usage.cost, gateway.restart.request, gateway.suspend.prepare, gateway.suspend.status, gateway.suspend.resume
• 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 ficam bloqueados até serem adicionados intencionalmente.

Comparação com WebSocket

O caminho RPC WebSocket normal do Gateway continua sendo a API preferencial do plano de controle para clientes do OpenClaw. Use RPC HTTP administrativo somente para ferramentas do host que precisam de uma superfície HTTP de solicitação e resposta.

Clientes WebSocket com token compartilhado e sem uma identidade confiável de dispositivo não podem declarar por conta própria escopos administrativos durante a conexão. O RPC HTTP administrativo segue deliberadamente o modelo existente de operador HTTP confiável: quando o plugin está ativado, a autenticação bearer por segredo compartilhado é tratada como acesso completo de operador para essa superfície administrativa.

Solução de problemas

404 Not Found

: O plugin está desativado, o Gateway não foi reiniciado desde a ativação ou a solicitação está sendo enviada para outro processo 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 proxy confiável.

405 Method Not Allowed

: A solicitação usou um método diferente de POST.

413 Payload Too Large

: O corpo da solicitação excedeu o limite de 1 MB.

400 INVALID_REQUEST

: O corpo da solicitação não é um JSON válido, o campo method está ausente, o método não está na lista de permissões do plugin ou um ID de retomada da suspensão não corresponde à concessão ativa.

503 UNAVAILABLE

: O método do Gateway está sendo iniciado, sofreu limitação de taxa, está suspenso ou aguarda uma operação concorrente de suspensão ou retomada. Inspecione error.details quando presente e respeite error.retryAfterMs antes de tentar novamente.

Relacionado

• Escopos do operador
• Segurança do Gateway
• Acesso remoto
• Manifesto do plugin
• Subcaminhos do SDK