Hermes Agent와 OpenClaw에서 KwaFlux 쓰는 법(MCP 설정)

핵심 요약

• Hermes Agent는 hermes mcp add 명령 하나, 또는 ~/.hermes/config.yaml의 맨 바깥쪽 키 mcp_servers 아래에 넣는 kwaflux 항목으로 KwaFlux를 추가합니다.
• OpenClaw는 openclaw mcp set으로 KwaFlux를 추가하며, 이 명령은 OpenClaw 구성의 mcp.servers 아래에 항목을 씁니다.
• 두 에이전트 모두 KwaFlux 서버를 로컬 프로그램으로 실행하므로, 에이전트는 원격 서버가 아니라 KwaFlux와 같은 컴퓨터에서 실행되어야 합니다.
• 첫 실제 요청 전에 각 에이전트의 확인 명령인 hermes mcp test나 openclaw mcp show를 실행해 보세요.

Hermes Agent와 OpenClaw는 MCP 도구를 쓸 수 있는 개인 AI 에이전트로, 둘 다 KwaFlux와 함께 설치되는 로컬 MCP 서버를 통해 KwaFlux를 움직일 수 있습니다. 각 에이전트용 구성과 설치 명령은 KwaFlux 설정에서 만들어 줍니다. 가장 중요한 규칙은 하나입니다. 에이전트가 KwaFlux가 실행되는 컴퓨터에서 실행되어야 한다는 것입니다.

이 글에서는 Hermes와 OpenClaw에 KwaFlux를 추가하는 방법, 연결을 확인하는 방법, 사람들이 흔히 틀리는 부분, 그리고 처음에 무엇을 요청할지 알아봅니다.

목차

1. 에이전트가 같은 컴퓨터에 있어야 하는 이유
2. 시작하기 전에
3. Hermes Agent: KwaFlux 추가하기
4. Hermes Agent: 도구 확인과 제한
5. OpenClaw: KwaFlux 추가하기
6. OpenClaw: 항목 확인하기
7. 첫 요청 해 보기
8. 문제 해결
9. 자주 묻는 질문

에이전트가 같은 컴퓨터에 있어야 하는 이유

KwaFlux의 MCP 서버는 stdio 서버입니다. 에이전트가 이 서버를 자식 프로세스로 실행하고 표준 입력과 표준 출력으로 통신합니다. 그런 다음 이 프로세스는 같은 컴퓨터 안에서만 동작하는 채널로 KwaFlux 앱에 연결합니다.

OpenClaw나 Hermes를 VPS나 홈 서버처럼 늘 켜 두는 서버에서 돌리고 휴대폰으로 대화하는 사람이 많습니다. 이런 구성으로는 내 PC의 KwaFlux에 닿을 수 없습니다. KwaFlux를 쓰려면 에이전트를, 적어도 MCP 서버를 실행하는 부분만큼은 KwaFlux가 설치되어 열려 있는 PC나 Mac에서 실행하세요.

시작하기 전에

• KwaFlux 1.0.14 이상, 실행 중.
• PATH에 있는 Node.js 18 이상. node --version으로 확인하세요. KwaFlux 설정 카드도 Node.js를 찾아서 아래 예시처럼 그 전체 경로를 구성에 적어 줍니다. Node.js를 찾지 못하면 그렇다고 알려 주고 대신 node라고 적습니다.
• KwaFlux에서: 설정 › Agent(MCP)를 열고 MCP 호스트에서 Hermes나 OpenClaw를 고릅니다.

Hermes Agent: KwaFlux 추가하기

명령줄로 추가하기. 설치 명령 복사를 클릭하고 실행합니다. Windows 기본 설치라면 다음과 같습니다.

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

Hermes가 서버에 연결해 도구 선택 화면을 보여 줍니다. 쓰려는 도구만 남기세요.

구성 파일을 편집해 추가하기. 구성 복사를 클릭하고 ~/.hermes/config.yaml에 추가합니다.

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

파일에 이미 mcp_servers: 키가 있다면 그 아래에 kwaflux: 블록만 추가하세요. mcp: › servers:처럼 중첩하면 안 됩니다. Hermes는 맨 바깥쪽 키 mcp_servers를 읽습니다. 그다음 세션에서 /reload-mcp를 실행합니다.

Hermes Agent: 도구 확인과 제한

• hermes mcp test kwaflux를 실행하면 서버가 실제로 어떻게 응답했는지 볼 수 있습니다.
• 채팅에서 Hermes는 KwaFlux 도구를 mcp_kwaflux_kwaflux_get_app_status처럼 mcp_kwaflux_<tool> 형태의 이름으로 부릅니다.
• 일부 도구만 불러오려면 서버 아래에 include:나 exclude:가 든 tools: 블록을 추가합니다. Hermes는 포함된 도구만 등록하며, 둘 다 설정하면 include가 우선합니다.
• Hermes에는 도구 호출용 timeout 필드가 있습니다. KwaFlux의 대기 도구는 호출 한 번에 최대 300초까지 기다릴 수 있으므로, 긴 대기가 끊긴다면 그보다 크게 설정하세요.

OpenClaw: KwaFlux 추가하기

명령줄로 추가하기. 설치 명령 복사를 클릭합니다. Windows에서는 KwaFlux가 다음과 같은 형식으로 만들어 줍니다.

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

이스케이프한 따옴표는 명령 프롬프트 기준으로 작성되어 있습니다. PowerShell처럼 셸이 따옴표를 망가뜨린다면 구성 파일을 직접 편집하세요. Mac에서는 KwaFlux가 JSON을 작은따옴표로 감쌉니다.

구성 파일을 편집해 추가하기. 구성 복사를 클릭하고 ~/.openclaw/openclaw.json에 병합합니다.

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

백슬래시 두 개는 그대로 두세요. JSON에서는 이렇게 적어야 합니다. 일부 제3자 가이드는 서버를 mcpServers 아래에 넣지만, OpenClaw의 공식 CLI 문서는 mcp.servers를 씁니다.

OpenClaw: 항목 확인하기

• openclaw mcp list와 openclaw mcp show kwaflux로 저장된 내용을 볼 수 있습니다.
• OpenClaw 문서에 따르면 set과 show는 구성을 읽고 쓰기만 하며 "실제로 MCP 서버에 연결하지는 않습니다". 그러니 항목이 저장됐다고 해서 서버가 시작된다는 뜻은 아닙니다. 확실히 하려면 에이전트에게 KwaFlux 도구를 호출해 달라고 하세요.
• 에이전트가 새 도구를 인식하지 못하면 OpenClaw의 MCP 서버를 다시 불러오거나 게이트웨이를 다시 시작하세요.

첫 요청 해 보기

먼저 이렇게 요청해 보세요.

KwaFlux 도구로 KwaFlux가 실행 중인지 확인하고 최근 작업 목록을 보여 주세요.

그다음에는 이런 요청을 해 볼 수 있습니다.

개인 에이전트는 여러 단계를 이어서 처리하는 데 강합니다. "매일 저녁 이 폴더에 새로 들어온 클립을 YouTube용으로 변환해 주세요" 같은 요청도 가능합니다. 단, 에이전트가 같은 PC에서 실행되고 그 시간에 KwaFlux가 열려 있어야 합니다.

프레임 보간과 매팅, 교체 도구는 앱에 남아 있으며, 이런 요청이 오면 어시스턴트는 사용자를 앱으로 안내하라는 응답을 받습니다. 에이전트 다운로드는 에이전트 권한의 에이전트의 다운로드 허용을 매번 확인으로 바꾸지 않는 한 꺼져 있습니다. 이렇게 설정하면 KwaFlux가 다운로드마다 팝업을 띄우고, 어시스턴트도 그 콘텐츠를 내려받을 권리가 있는지 채팅에서 확인을 요청합니다.

문제 해결

모든 호스트에 공통된 문제는 KwaFlux MCP 문제 해결 가이드를 참고하세요.

마치며

Hermes에서는 hermes mcp add 명령을 실행하거나 mcp_servers 아래에 kwaflux 블록을 추가한 뒤 /reload-mcp를 실행하세요. OpenClaw에서는 명령 프롬프트에서 openclaw mcp set을 실행하거나 openclaw.json의 mcp.servers를 편집하세요. 어느 쪽이든 에이전트와 KwaFlux를 같은 컴퓨터에 두고, 상태 확인부터 시작하면 됩니다.

내 개인 에이전트로 KwaFlux를 움직여 보세요

KwaFlux에는 Hermes Agent, OpenClaw를 비롯한 MCP 앱에서 쓸 수 있는 로컬 MCP 서버가 들어 있습니다. AI 처리는 사용자 GPU에서 실행되며 미디어 파일이 처리를 위해 업로드되지 않습니다. Windows 10(64비트, 버전 1809 이상), Windows 11, Apple Silicon 탑재 macOS 12 이상에서 실행됩니다. 파일 가져오기와 앱 둘러보기에는 계정이 필요 없습니다. 내보내기, 변환, 파일 복구, 링크에서 파일 다운로드에만 로그인과 유료 플랜이 필요합니다.

KwaFlux 받기 · 플랜 보기