> ## Documentation Index
> Fetch the complete documentation index at: https://comfyui-mcp.artokun.io/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 문제 해결

> 사용자들이 실제로 겪는 문제에 대한 해결책 모음입니다: ComfyUI-Manager 버전 불일치(405 오류), git URL 설치가 조용히 건너뛰어지는 문제, 원격 브라우저에서 패널에 접속되지 않는 문제, 오래된 npx 캐시, 포트 포워딩된 원격 서버가 로컬로 잘못 감지되는 문제까지 다룹니다.

이 페이지의 모든 항목은 실제 버그 리포트에서 시작되었습니다. 겪고 계신 문제가 여기 없다면
[이슈를 등록해 주세요](https://github.com/artokun/comfyui-mcp/issues) — 아마 이
페이지에 추가될 것입니다.

## `install_custom_node`가 `/v2/manager/queue/task`에서 `405 Method Not Allowed`로 실패함

**원인:** ComfyUI-Manager에는 두 세대가 존재합니다. `/v2/manager/*` API는 **v4 계열**
(pip 패키지 `comfyui_manager` ≥ 4.x)이며, ComfyUI-Manager가 기본으로 설치하는
**출시된 Manager 3.x**는 같은 대기열을 다른 라우트로 제공합니다.

**해결:** `comfyui-mcp`를 **0.24.3** 이상으로 업데이트하세요 — 대상별로 Manager
세대를 자동 감지해 두 방식을 모두 지원합니다. Manager를 변경할 필요는 없습니다.

**선택 사항이지만 권장 — Manager v4로 업그레이드**하면 3.x가 원격으로 할 수 없는
기능(특히 3.x가 화이트리스트로 제한하는 **임의 URL 모델 다운로드**)을 사용할 수
있습니다:

```bash theme={null}
# in your ComfyUI python environment
pip install -U comfyui_manager
# then remove/disable the old custom_nodes/ComfyUI-Manager clone and restart
```

[RunPod 이미지](/docs/docs/cloud-deployment)에는 이미 Manager v4가 포함되어 있습니다.

**`useCmCli: true`에 대한 참고:** cm-cli 폴백은 Manager의 CLI를 서브프로세스로
실행하므로 **로컬 파일시스템**이 필요합니다 — 원격/`--tunnel` 대상에는 사용할 수
없으며, `python`이 PATH에 없을 때는 `COMFYUI_PYTHON`이 ComfyUI venv의 인터프리터를
가리키도록 설정해야 합니다. 원격 대상에는 Manager HTTP 경로(기본값)가 적절한
방식입니다.

## git URL로 설치한 커스텀 노드가 나타나지 않음

레지스트리 ID로 설치하면 정상 동작하지만, GitHub URL을 직접 사용한 설치는
성공했다고 표시되면서도 팩이 전혀 나타나지 않습니다.

**원인:** Manager는 임의의 git URL 설치를 고위험으로 간주해, 허용 수준의 보안
등급보다 낮으면 **조용히 건너뜁니다**(그럼에도 대기열 작업은 "완료"로 표시됩니다).
Manager 3.x에는 추가로 전용 `allow_git_url_install` 설정 플래그가 있습니다.

**해결:** Manager의 `config.ini`(ComfyUI 사용자 디렉터리 아래)에서:

```ini theme={null}
[default]
security_level = weak          ; Manager v4: allows git-URL installs
allow_git_url_install = True   ; Manager 3.x: additionally required
```

이후 ComfyUI를 다시 시작하세요. RunPod 이미지에서는 `1.6` 이미지부터 이 값이
기본값입니다(`COMFY_SECURITY_LEVEL` 환경 변수가 이를 덮어쓰며, 부팅할 때마다 값이
다시 적용됩니다). `1.4`/`1.5` 이미지는 이렇게 동작하도록 *의도*되었지만, 내장된
`COMFY_SECURITY_LEVEL=normal-` 환경 변수가 부팅 스크립트의 기본값을 덮어썼습니다 —
해당 이미지에서는 파드의 환경 변수에 `COMFY_SECURITY_LEVEL=weak`를 직접
설정하세요. 이 설정은 본인이 관리하는 머신에서만 완화하세요 — Manager의 설치
안전장치를 제거하는 것이기 때문입니다.

## RunPod: 에이전트 패널 탭이 비어 있음 — 파일은 존재하지만 모두 0바이트

ComfyUI에 `comfyui-mcp-panel`이 표시되지만 사이드바 탭이 전혀 로드되지 않습니다.
`ls -la /workspace/custom_nodes/comfyui-mcp-panel`을 실행하면 모든 파일이
**0바이트**로 나타납니다. 사용자가 설치한 다른 노드도 같은 방식으로 비어 있을 수
있습니다.

**원인:** 네트워크 볼륨이 어느 시점에 **공간 부족**이 된 것입니다(작은 볼륨에서
최초 부팅 시 약 7GB의 스팟체크 모델 복사가 실행되거나, 대용량 모델을 다운로드할 때
흔히 발생합니다). ENOSPC 상태에서도 `cp`/`git`은 각 파일을 *생성*은 하지만 내용은
전혀 쓰지 못합니다 — 볼륨은 계속 유지되므로, 이 빈 껍데기 파일들은 재배포할 때마다
그대로 남습니다.

**해결:** 볼륨 공간을 확보하거나 늘린 뒤 파드를 다시 시작하세요. `1.6` 이미지부터는
부팅 스크립트가 볼륨이 부족하거나 가득 찼을 때 경고를 표시하고, 공간이 부족하면
스팟체크 모델 복사를 건너뛰며, 0바이트 패널을 자동으로 **스스로 복구**합니다
(GitHub에서 다시 클론하거나, 오프라인이면 이미지에 포함된 시드를 사용합니다). 또한
다른 손상된 노드가 있으면 `WARN: custom nodes with 0-byte __init__.py` 로그로
이름을 남깁니다 — 이런 노드는 Manager를 통해 다시 설치하세요. `<= 1.5`
이미지에서는 패널 폴더를 삭제한 뒤 다시 시작하세요:
`rm -rf /workspace/custom_nodes/comfyui-mcp-panel`.

## 패널에 "브리지(ws\://127.0.0.1:9180)에서 대기 중인 에이전트가 없습니다"라는 메시지가 표시됨

오케스트레이터가 실행 중인 머신과 **다른 머신의 브라우저**에서 ComfyUI를 열고 있는
것입니다. 브리지는 설계상 루프백 전용이며, 브라우저에서의 `127.0.0.1`은 서버가
아니라 브라우저가 실행 중인 머신을 가리킵니다.

**해결 — 브라우저가 있는 머신에서 오케스트레이터를 실행하세요** (이것이 지원되는
구성입니다 — 에이전트는 *사용자*의 머신에서 실행되며 원격 ComfyUI를 제어합니다):

```bash theme={null}
npx -y comfyui-mcp@latest connect http://<comfyui-host>:8188
```

그런 다음 패널에서 연결을 클릭하세요. ComfyUI 박스에는 ComfyUI와 패널 커스텀 노드
외에는 아무것도 실행할 필요가 없습니다. **https** ComfyUI(RunPod 프록시)의 경우
오케스트레이터가 브리지를 보안 `wss://` 터널로 자동 업그레이드합니다 — 명령어는
동일합니다.

**또는 서버 측에서 오케스트레이터를 실행하세요 (0.24.5 이상)** — 에이전트가
ComfyUI 옆에서 상시 실행되고 LAN의 어디서든 브라우저가 연결할 수 있어야 하는
24/7 헤드리스 박스(예: 독립형 Ollama/OpenClaw 서버)에 적합합니다:

```bash theme={null}
# on the SERVER — bind the bridge on the LAN, token-gated (mandatory)
COMFYUI_MCP_BRIDGE_HOST=0.0.0.0 \
COMFYUI_MCP_BRIDGE_TOKEN=<pick-a-long-secret> \
npx -y comfyui-mcp@latest --panel-orchestrator
```

바로 붙여넣을 수 있는 `ws://<server-ip>:9180/?token=…`가 출력됩니다 — 이 값을 아무
머신에서나 패널의 **설정 → 고급 → 브리지 URL**에 입력하고 연결을 클릭하세요.
루프백이 아닌 바인딩은 토큰 없이는 **시작 자체가 거부**되며, 모든 연결은 WebSocket
업그레이드 시점에 검사됩니다(상수 시간 비교). 이 URL은 비밀번호처럼 다루세요 —
이를 가진 사람은 누구나 에이전트를 조작할 수 있습니다.

## 새 릴리스가 나왔는데 여전히 예전 동작이 보임

`npx`는 패키지를 적극적으로 캐싱합니다 — `npx -y comfyui-mcp@latest`가
`~/.npm/_npx`에 있는 몇 주 전 빌드를 그대로 제공할 수 있습니다.

```bash theme={null}
# clear it, then relaunch
npx clear-npx-cache
# or on Windows:
#   Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx"
```

패널 커스텀 노드도 확인하세요: 이전 설치에서 남은 것이 **네트워크 볼륨**(RunPod의
`/workspace`)에 있다면, 그 사본이 이미지의 자동 업데이트본을 가려버립니다.
`git -C <panel-dir> fetch && git -C <panel-dir> reset --hard origin/main`을
실행하거나 ComfyUI-Manager에서 `comfyui-agent-panel`을 다시 설치한 뒤, ComfyUI를
재시작하고 브라우저 탭을 강력 새로고침하세요(Ctrl+Shift+R).

## 포트 포워딩된 원격 ComfyUI가 로컬로 잘못 감지됨 (dstack, SSH 터널)

`localhost:8188`으로 접근 가능한 원격 ComfyUI(dstack, `ssh -L`, kubectl
port-forward)는 루프백 휴리스틱을 오작동시킵니다: comfyui-mcp가 로컬 설치라고
판단해, ComfyUI가 실제로 없는 파일시스템에 대해 로컬 전용 도구를 활성화합니다.

**해결 (0.24.1 이상):** `--force-remote`(또는 `COMFYUI_MCP_FORCE_REMOTE=1`)를
전달하세요:

```bash theme={null}
npx -y comfyui-mcp@latest connect http://localhost:8188 --force-remote
```

원격 대상의 생성 기록은 `~/.comfyui-mcp/instances/<host_port>/`에 저장됩니다
(`COMFYUI_MCP_DATA_DIR`로 재정의 가능).

## Docker: HTTP 모드에서 컨테이너가 즉시 종료됨

인증 없이 루프백이 아닌 호스트에 바인딩하면 **설계상 무조건 실패**합니다
(`0.0.0.0`에 열린 `/mcp` 엔드포인트가 노출되기 때문입니다). 토큰을 전달하거나,
명시적으로 이 검사를 해제하세요:

```bash theme={null}
docker run --rm -p 9100:9100 -e COMFYUI_MCP_HTTP_TOKEN=changeme comfyui-mcp \
  --http --host 0.0.0.0 --port 9100
# or (trusted networks only):
#   ... --http --host 0.0.0.0 --port 9100 --allow-unauthenticated-non-loopback
```

stdio 모드(기본값이며 MCP 클라이언트가 사용하는 방식)에는 이런 설정이 전혀
필요 없습니다.

## 에이전트가 도구를 전혀 호출하지 않음 — 오류 없이 그냥 말만 함

워크플로우를 읽는 대신 설명만 하거나, 스크립트를 대신 작성해 주겠다고 제안합니다.
아무것도 실패하지 않았기 때문에 오류는 나타나지 않습니다: 도구 목록이 클라이언트에
전달되지 않았거나, 클라이언트가 호출을 막고 있거나, 해당 기능이 한 번도 언급되지
않은 이름으로 존재하는 경우 중 하나입니다. 이 세 가지는 겉으로는 똑같아 보이지만
해결 방법은 정반대이므로, 추측하기보다는 확인하는 편이 낫습니다.

에이전트에게 두 가지 질문을 던져보면 구분할 수 있습니다 —
[아무 말도 하지 않을 때](/docs/docs/using-tools#when-it-says-nothing)를 참고하세요.
클라이언트 측 권한 차단은 이 서버에 전혀 도달하지 않으므로, 아래 로그 어디에도
나타나지 않는다는 점을 유의하세요.

## 로컬 모델: 도구 호출이 실패하거나 모델이 도구를 "인식하지 못함"

* **가장 먼저 시도할 것: [자체 파인튜닝 모델](/docs/docs/local-llms#our-fine-tuned-local-models-free-recommended)을
  사용하세요** — `ollama pull artokun/gemma4-comfyui-mcp:e4b`(패널의 Ollama
  기본값입니다). comfyui-mcp 도구 모음 자체로 학습된 Gemma 4로, "잘못된 도구
  선택 / 잘못된 형식의 인자" 실패 대부분을 기본 상태에서 없애줍니다(VRAM 약
  2GB면 `:e2b`, 약 8GB면 `:12b` — 모든 단계가 아레나에서 기본 베이스 모델을
  능가하며, `:e4b`가 최적점입니다).
* **gemma3는 Ollama에서 네이티브 도구 호출을 지원하지 않습니다** — 지원되지
  않으니, 위의 자체 파인튜닝 모델이나 기본 `gemma4`(e4b 이상), `qwen3`,
  `llama3.1+`을 사용하세요.
* 소형 모델에는 [컴팩트 도구 모드](/docs/docs/local-llms)를 켜세요 — 이는
  **기본값이 아니므로**, 서버를 시작할 때 `--compact`(또는
  `COMFYUI_MCP_TOOL_MODE=compact`)를 지정해야 합니다. 켜지 않으면 전체
  스키마가 작은 컨텍스트를 넘쳐, 모델이 도구 이름을 지어내기 시작합니다.
* 콜드 상태에서 모델을 불러올 때는 첫 토큰이 나오기까지 30초 이상 걸릴 수
  있습니다 — 패널의 워치독은 이를 감안하지만, 요청이 즉시 실패한다면 대개
  해당 모델 태그를 아직 받지 않은 것입니다(`ollama pull <tag>`).
* **모든 요청이 갑자기 실패함 / 11434 포트에서 연결 거부됨** — Ollama
  앱/데몬이 실행되고 있지 않은 것입니다. 트레이 앱을 종료하면 API도 함께
  죽는데, 에이전트가 실행되는 도중에 실수로 이렇게 하기 쉽습니다(패널은
  로컬 백엔드가 사용 중이라는 경고를 표시하지 않습니다). 앱을 다시
  실행하거나(또는 `ollama serve`) 재연결하세요 — 세션은 이어지며 패널을
  재시작할 필요는 없습니다.

## 로그를 확인할 위치

* **오케스트레이터**: `connect` / `--panel-orchestrator`를 실행 중인
  터미널입니다.
* **ComfyUI 측**: `get_system_stats (action:"logs")` MCP 도구, 또는
  RunPod에서는 파드의 로그 스트림입니다.
* **패널 JS**: 브라우저 devtools 콘솔입니다(브리지 클라이언트가
  연결/재연결 전환을 로그로 남깁니다).
* **한 번의 호출로 확인하는 상태**: `get_system_stats (action:"health")`
  도구가 버전/GPU/VRAM/대기열/모델 디렉터리/최근 오류를 종합해 보여줍니다.