Codex에서 KwaFlux 쓰는 법: MCP 설정, 타임아웃, 승인

핵심 요약

• Codex는 codex mcp add 명령 하나, 또는 ~/.codex/config.toml의 [mcp_servers.kwaflux] 테이블 하나로 KwaFlux에 연결됩니다. 둘 다 KwaFlux가 만들어 줍니다.
• Codex는 MCP 도구 호출 한 번에 기본 60초를 주지만, KwaFlux의 대기 도구는 최대 300초까지 기다릴 수 있습니다. 긴 영상 작업이 중간에 끊기지 않도록 tool_timeout_sec을 더 크게 잡으세요.
• 명령줄로 추가하면 KwaFlux가 만든 TOML에 들어 있는 20초 시작 타임아웃이 빠집니다. 서버가 늦게 시작된다면 직접 넣어 주세요.
• Codex의 승인 모드를 쓰면 읽기 전용 KwaFlux 도구는 자유롭게 실행하고, 파일을 쓰는 작업 전에는 계속 확인을 받을 수 있습니다.

OpenAI의 Codex는 KwaFlux와 함께 설치되는 로컬 MCP 서버를 통해 KwaFlux를 움직일 수 있습니다. KwaFlux 설정에서 Codex를 고르고 설치 명령이나 TOML 테이블을 복사해 Codex에 추가한 뒤, KwaFlux를 열어 두면 됩니다. 영상 작업이라면 바꿔 둘 만한 설정이 두 가지 있습니다. 도구 타임아웃과 승인 모드입니다.

이 글에서는 Codex에 KwaFlux를 추가하는 두 가지 방법, 긴 작업에서 중요한 타임아웃 설정, 승인을 제어하는 방법, 그리고 처음에 무엇을 요청할지 알아봅니다.

목차

1. Codex가 MCP 서버를 실행하는 방식
2. 시작하기 전에
3. 방법 1. codex mcp add
4. 방법 2. config.toml 편집
5. 긴 영상 작업의 타임아웃
6. 승인과 도구 목록
7. 첫 요청 해 보기
8. 문제 해결
9. 자주 묻는 질문

Codex가 MCP 서버를 실행하는 방식

Codex는 세션이 시작될 때 구성에 등록된 로컬 MCP 서버를 하나씩 실행하고, 표준 입력과 표준 출력으로 통신합니다. 그러면 서버의 도구가 Codex 자체 도구와 나란히 모델에 표시됩니다. Codex CLI와 Codex 데스크톱 앱은 같은 구성을 씁니다.

KwaFlux 서버는 앱과 함께 설치되는 Node.js 스크립트입니다. 서버가 직접 처리하는 것은 없습니다. 요청을 실행 중인 KwaFlux 앱에 넘기면, 앱이 요청을 확인하고 작업을 실행합니다.

시작하기 전에

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

방법 1. codex mcp add

설치 명령 복사를 클릭하고 터미널에서 실행합니다. Windows 기본 설치라면 다음과 같습니다.

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

Codex CLI 0.118.0에서 실행해 보니 Added global MCP server 'kwaflux'.가 출력되었습니다. 이어서 확인합니다.

codex mcp list

KwaFlux가 활성화된 상태로 표시되어야 합니다. 이 명령은 ~/.codex/config.toml에 command와 args만 있는 테이블을 씁니다. 직접 추가해 둘 만한 두 줄은 아래에서 설명합니다.

방법 2. config.toml 편집

대신 구성 복사를 클릭하고, 복사한 테이블을 ~/.codex/config.toml 끝이나 신뢰된 프로젝트의 .codex/config.toml 끝에 붙여 넣습니다.

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

KwaFlux 안내 문구에도 "키는 mcp_servers(밑줄)입니다."라고 나옵니다. 저장한 뒤 Codex를 다시 시작하거나, 세션에서 /mcp를 실행해 서버가 보이는지 확인하세요.

참고: 경로를 작은따옴표로 감싼 데는 이유가 있습니다. TOML에서 작은따옴표 문자열은 리터럴 문자열이라 Windows 백슬래시를 이스케이프할 필요가 없습니다. 큰따옴표를 쓰면 백슬래시마다 \\로 적어야 합니다.

긴 영상 작업의 타임아웃

Codex의 MCP 문서에는 서버마다 두 가지 타임아웃이 있습니다.

중요한 쪽은 두 번째입니다. Codex가 KwaFlux에 내보내기가 끝날 때까지 기다려 달라고 하면, 대기 도구는 작업이 끝나거나 자체 한도에 이를 때까지 최대 300초 동안 응답을 붙잡고 있습니다. Codex 기본값인 60초로는 그보다 긴 대기가 Codex 쪽에서 끊기고, 모델은 이를 실패로 받아들일 수 있습니다. 다음과 같이 설정하세요.

[mcp_servers.kwaflux]
command = 'C:\Program Files\nodejs\node.exe'
args = ['C:\Program Files\KwaFlux\Tools\kwaflux-mcp\kwaflux_mcp.mjs']
startup_timeout_sec = 20
tool_timeout_sec = 330

어느 경우든 작업은 KwaFlux에서 계속 실행됩니다. 타임아웃은 그 대기 한 번을 끝낼 뿐이고, Codex는 작업 상태를 다시 확인할 수 있습니다.

승인과 도구 목록

Codex에서는 도구를 실행하기 전에 언제 물어볼지 서버별로 정할 수 있습니다. 문서에는 default_tools_approval_mode 값으로 auto, prompt, writes, approve가 나오며, 그중 writes는 "읽기 전용으로 표시되지 않은 도구에 대해 확인을 요청"합니다. KwaFlux에 잘 맞는 설정입니다. 상태 확인과 작업 목록 호출은 그대로 통과하고, 파일을 쓰는 작업은 여전히 확인을 받습니다.

허용 목록인 enabled_tools나 거부 목록인 disabled_tools로 Codex가 불러올 도구를 줄일 수도 있습니다. 예를 들어 Codex를 변환과 복구에만 쓴다면 작업, 변환, 복구 도구만 나열하세요. 도구 설계 글에서 설명했듯이 도구가 적을수록 모델 컨텍스트에도 여유가 생깁니다.

첫 요청 해 보기

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

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

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

문제 해결

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

마치며

KwaFlux가 복사해 주는 명령이나 TOML로 KwaFlux를 추가한 다음, 두 줄을 더하세요. 20초 시작 타임아웃과 330초 도구 타임아웃입니다. 파일을 만드는 작업 전에만 Codex가 묻게 하려면 writes 승인 모드를 고르세요. 그런 다음 KwaFlux를 열어 두고 상태 확인부터 시작하면 됩니다.

Codex로 KwaFlux를 움직여 보세요

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

KwaFlux 받기 · 플랜 보기