Como usar o KwaFlux no Hermes Agent e no OpenClaw (configuração do MCP)

O essencial

• O Hermes Agent adiciona o KwaFlux com um único comando hermes mcp add ou com uma entrada kwaflux sob a chave de primeiro nível mcp_servers no ~/.hermes/config.yaml.
• O OpenClaw adiciona o KwaFlux com openclaw mcp set, que grava a entrada em mcp.servers na configuração do OpenClaw.
• Os dois agentes iniciam o servidor do KwaFlux como um programa local, então o agente precisa rodar no mesmo computador que o KwaFlux, e não em um servidor remoto.
• Use a verificação de cada agente, hermes mcp test ou openclaw mcp show, antes do primeiro pedido de verdade.

O Hermes Agent e o OpenClaw são agentes de IA pessoais que podem usar ferramentas MCP, e os dois conseguem controlar o KwaFlux pelo servidor MCP local que vem instalado com o app. As configurações do KwaFlux geram a configuração e o comando de instalação para cada um. A regra que mais importa: o agente precisa rodar no computador em que o KwaFlux roda.

Neste guia, você vai ver como adicionar o KwaFlux ao Hermes e ao OpenClaw, como testar a conexão, onde as pessoas costumam errar e o que pedir primeiro.

Conteúdo

1. Por que o agente precisa estar no mesmo computador
2. Antes de começar
3. Hermes Agent: adicionar o KwaFlux
4. Hermes Agent: testar e limitar as ferramentas
5. OpenClaw: adicionar o KwaFlux
6. OpenClaw: conferir a entrada
7. Seus primeiros pedidos
8. Solução de problemas
9. Perguntas frequentes

Por que o agente precisa estar no mesmo computador

O servidor MCP do KwaFlux é um servidor stdio: o agente o inicia como um processo filho e se comunica com ele pela entrada e saída padrão. Esse processo, por sua vez, se conecta ao app KwaFlux por um canal que só funciona no mesmo computador.

Muita gente roda o OpenClaw ou o Hermes em um servidor que fica ligado o tempo todo, como uma VPS ou um servidor doméstico, e conversa com ele pelo celular. Essa configuração não alcança o KwaFlux no seu PC. Para usar o KwaFlux, rode o agente, ou pelo menos a parte que inicia os servidores MCP, no PC ou Mac em que o KwaFlux está instalado e aberto.

Antes de começar

• KwaFlux 1.0.14 ou mais recente, aberto.
• Node.js 18 ou mais recente, no PATH. Confira com node --version. O cartão nas configurações do KwaFlux também procura o Node.js e grava o caminho completo dele na configuração, como nos exemplos abaixo; se não encontrar o Node.js, o cartão avisa e grava node no lugar.
• No KwaFlux: abra Configurações › Agent (MCP) e escolha Hermes ou OpenClaw em Host MCP.

Hermes Agent: adicionar o KwaFlux

Pela linha de comando. Clique em Copiar comando de instalação e rode o comando. Em uma instalação padrão no Windows:

hermes mcp add kwaflux --command "C:\Program Files\nodejs\node.exe" --args "C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs"

O Hermes se conecta ao servidor e mostra uma lista das ferramentas dele para você escolher; mantenha as que quiser.

Editando a configuração. Clique em Copiar config e adicione o trecho ao ~/.hermes/config.yaml:

mcp_servers:
  kwaflux:
    command: 'C:\Program Files\nodejs\node.exe'
    args:
      - 'C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs'

Se o arquivo já tiver uma chave mcp_servers:, adicione só o bloco kwaflux: embaixo dela. Não aninhe como mcp: › servers:; o Hermes lê a chave mcp_servers de primeiro nível. Depois, execute /reload-mcp em uma sessão.

Hermes Agent: testar e limitar as ferramentas

• hermes mcp test kwaflux mostra o que o servidor realmente respondeu.
• No chat, o Hermes chama as ferramentas do KwaFlux de mcp_kwaflux_<tool>, como mcp_kwaflux_kwaflux_get_app_status.
• Para carregar só algumas ferramentas, adicione sob o servidor um bloco tools: com include: ou exclude:. O Hermes registra apenas as ferramentas incluídas, e include prevalece se os dois estiverem definidos.
• O Hermes tem um campo timeout para as chamadas de ferramenta. A ferramenta de espera do KwaFlux pode esperar até 300 segundos em uma única chamada, então, se as esperas longas forem cortadas, defina um valor acima disso.

OpenClaw: adicionar o KwaFlux

Pela linha de comando. Clique em Copiar comando de instalação. No Windows, o KwaFlux formata o comando assim:

openclaw mcp set kwaflux "{\"command\":\"C:\\Program Files\\nodejs\\node.exe\",\"args\":[\"C:\\Program Files\\KwaFlux\\Tools\\kwaflux-mcp\\kwaflux_mcp.mjs\"]}"

As aspas com escape estão no formato do Prompt de Comando (Command Prompt). Se o seu shell estragar as aspas, o que pode acontecer no PowerShell, edite o arquivo de configuração em vez disso. No Mac, o KwaFlux coloca o JSON entre aspas simples.

Editando a configuração. Clique em Copiar config e mescle o trecho no ~/.openclaw/openclaw.json:

{
  "mcp": {
    "servers": {
      "kwaflux": {
        "command": "C:\\Program Files\\nodejs\\node.exe",
        "args": [
          "C:\\Program Files\\KwaFlux\\Tools\\kwaflux-mcp\\kwaflux_mcp.mjs"
        ]
      }
    }
  }
}

Mantenha as barras invertidas duplas; o JSON precisa delas. Alguns guias de terceiros colocam os servidores em mcpServers; a documentação da própria CLI do OpenClaw usa mcp.servers.

OpenClaw: conferir a entrada

• openclaw mcp list e openclaw mcp show kwaflux mostram o que foi salvo.
• A documentação do OpenClaw observa que set e show só leem e gravam a configuração; eles “não se conectam de fato ao servidor MCP”. Ou seja, uma entrada salva não prova que o servidor inicia. Para ter certeza, peça ao agente que chame uma ferramenta do KwaFlux.
• Se o agente não enxergar as ferramentas novas, recarregue os servidores MCP do OpenClaw ou reinicie o gateway dele.

Seus primeiros pedidos

Comece com:

Use as ferramentas do KwaFlux para ver se o KwaFlux está aberto e liste minhas tarefas recentes.

Depois:

Agentes pessoais são bons em encadear etapas. “Toda noite, converta os clipes novos desta pasta para o YouTube” pode funcionar, desde que o agente rode no mesmo PC e o KwaFlux esteja aberto nesse horário.

A interpolação de quadros e as ferramentas de recorte e de substituição ficam no app; o assistente é instruído a mandar você para lá nesses casos. Os downloads feitos por agentes ficam desativados, a menos que você mude Permitir que agentes iniciem downloads, em Autorização de agentes, para a opção que pergunta a cada download. Aí o KwaFlux mostra uma janela para cada download, e o assistente também pede que você confirme no chat que tem o direito de baixar aquele conteúdo.

Solução de problemas

Para problemas comuns a todos os hosts, veja o guia de solução de problemas do MCP do KwaFlux.

Conclusão

No Hermes, rode a linha do hermes mcp add ou adicione um bloco kwaflux sob mcp_servers e depois execute /reload-mcp. No OpenClaw, rode o openclaw mcp set no Prompt de Comando ou edite mcp.servers no openclaw.json. Nos dois casos, mantenha o agente e o KwaFlux no mesmo computador e comece com uma verificação de status.

Controle o KwaFlux pelo seu agente pessoal

O KwaFlux inclui um servidor MCP local para o Hermes Agent, o OpenClaw e outros apps compatíveis com MCP. O processamento de IA roda na sua própria GPU e os seus arquivos de mídia não são enviados para processamento. Roda no Windows 10 (64 bits, versão 1809 ou mais recente), no Windows 11 e no macOS 12 ou mais recente em Apple Silicon. Importar arquivos e explorar o app não exigem conta. O login com um plano pago só é necessário para exportar, converter, reparar um arquivo ou baixar um arquivo de um link.

Baixar o KwaFlux · Ver planos