Plugin de RPC HTTP de administração

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-rpcopenclaw gateway restart

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

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-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 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/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 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

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