UX 개발 / Claude Code

SSH·tmux의 Claude Code에 로컬 클립보드 이미지 전달하기

claude-codesshtmuxclipboardpngpasteremote-control

로컬 노트북의 이미지가 전송 경로를 거쳐 원격 서버의 터미널과 이미지 파일로 도착하는 개념 일러스트

Mac에서 복사한 스크린샷을 원격 Claude Code에 보여 주려면 이미지가 실행 환경까지 전달되어야 합니다. Remote Control, pngpaste와 scp, Taildrop, VS Code 확장의 차이를 확인하고 실패 처리를 보완한 전송 함수까지 안내합니다.

이 글은 2026년 10월 25일 공식 문서와 제작자 공개 소스를 기준으로 합니다. 전송 함수는 명령을 모의 실행해 성공·실패·임시 파일 정리를 확인했습니다. 실제 사용자 서버 전송, Remote Control 로그인, VS Code 확장의 전체 동작을 직접 검증한 후기는 아닙니다. Claude Code 공식 웹사이트

1. 붙여넣기가 안 되는 이유부터 정확히 이해하기

로컬 Mac에서 캡처한 이미지는 Mac의 클립보드에 있습니다. SSH로 접속한 서버에서 실행하는 Claude Code가 그 클립보드를 자동으로 읽을 수 있는 것은 아닙니다. 원격 서버가 다른 Mac이어도 마찬가지입니다.

다만 “SSH는 텍스트만 전송해서 이미지를 보낼 수 없다”는 설명은 잘못됐습니다. SSH 연결을 이용하는 scp는 이미지 같은 파일도 전송합니다. 문제는 일반 터미널의 붙여넣기가 로컬 클립보드의 이미지 데이터를 원격 파일이나 첨부로 자동 변환하지 않는다는 점입니다. OpenSSH scp 공식 매뉴얼

tmux 공식 프로젝트의 tmux는 원격 터미널 세션을 유지하는 도구입니다. 켜 둔다고 로컬 이미지 클립보드가 원격으로 연결되지는 않습니다. 별도 이미지 브리지가 있는 터미널·확장은 예외이며, 아래 방법들은 그런 연결을 명시적으로 만드는 방식입니다.

로컬 Claude Code에서는 공식 단축키가 Ctrl+V이며 iTerm2의 Cmd+V 등 환경별 차이가 있습니다. 단축키를 바꾸는 것과 서로 다른 컴퓨터 사이로 이미지를 전달하는 것은 구분해야 합니다. 공식 키보드 안내

2. 내 환경에 맞는 방법 고르기

상황사용할 방법필요한 것
브라우저에서 같은 실행 환경에 요청하고 싶음Remote Control지원 구독·로그인·조직 허용
SSH 터미널을 계속 사용하고 싶음파일 전송, 이후 pngpaste + scp로컬 Mac의 pngpaste와 SSH 접속
이미 개인 기기끼리 Tailscale을 사용 중Taildrop양쪽 Tailscale과 파일 수신 절차
VS Code Remote-SSH 통합 터미널을 사용 중Claude Paste 확장지원 VS Code와 확장 설치

설정이 가장 적은 공통 출발점은 이미지 파일을 서버로 복사하고 경로를 알려 주는 방식입니다. 자주 쓴다면 전송 함수나 확장으로 반복을 줄이면 됩니다.

3. 방법 A: Remote Control에서 이미지 첨부하기

Remote Control은 서버에서 실행 중인 Claude Code를 브라우저나 다른 기기에서 이어 쓰는 기능입니다. 코드와 명령은 해당 실행 호스트에서 처리됩니다. 현재 공식 문서는 브라우저·휴대전화에서 이미지 첨부도 지원한다고 안내합니다.

Claude Code 공식 Remote Control 문서에서 브라우저나 휴대전화의 이미지와 파일 첨부를 지원한다고 설명한다

공식 공개 문서의 이미지·파일 첨부 지원 설명 캡처. (출처: Remote Control, 2026-10-25 캡처)

  1. 원격 서버의 기존 Claude Code 대화에서 /rc 또는 /remote-control을 실행합니다.
  2. 표시된 세션 URL을 로컬 Mac 브라우저에서 열고 같은 계정으로 연결합니다.
  3. Mac에서 Control + Shift + Command + 4로 영역을 캡처해 클립보드에 넣습니다.
  4. 브라우저 입력창에 붙여넣습니다. 이미지 첨부가 나타나는지 확인하고, 붙여넣기가 안 되면 첨부 버튼으로 저장된 파일을 선택합니다.
  5. 이미지와 함께 수정할 대상과 기대 결과를 적습니다.

첨부한 화면에서 헤더와 버튼의 세로 정렬이 어긋납니다. 해당 페이지의 코드를 확인해 정렬을 수정하고, 변경 후 같은 화면 크기에서 확인해 주세요.

claude remote-control은 셸에서 서버 모드로 시작하는 별도 사용법입니다. 이미 진행 중인 대화를 이어 쓰려면 그 대화 안에서 /rc를 실행하는 흐름부터 사용하세요.

지원되는 Claude 구독과 claude.ai 로그인이 필요하며 API 키 인증만으로는 사용할 수 없습니다. Team·Enterprise는 조직 허용 설정도 확인해야 합니다. 서버 프로세스와 네트워크가 살아 있어야 하므로 원격 tmux가 프로세스 유지에 도움이 됩니다. 다만 첨부 사진을 모델이 보는 것과 원격 디스크에 재사용할 이미지 파일을 저장하는 것은 다릅니다. 파일 자체가 필요하면 다음 전송 방식을 씁니다. 공식 사용 조건과 동작

4. 방법 B의 첫 단계: 저장된 PNG를 scp로 보내기

먼저 로컬 Mac 터미널에서 서버에 접속할 수 있는지 확인합니다. 아래 devbox는 자신이 사용하는 SSH 호스트 별칭입니다. 별칭이 없다면 실제 사용자명@서버주소로 바꿉니다. Tailscale 주소는 필수가 아닙니다.

ssh devbox

접속을 확인하고 로컬 터미널로 돌아옵니다. Mac에서 Shift + Command + 4로 캡처를 파일로 저장하고, 아래 예제에서는 파일을 ~/Desktop/shot.png로 준비합니다. 저장 위치나 포맷은 Mac의 스크린샷 옵션에 따라 다릅니다. HDR·HEIF로 저장되는 환경에서는 호환 가능한 PNG로 준비하세요. Apple 공식 캡처 안내

다음 두 명령은 로컬 Mac에서 실행합니다.

ssh devbox 'umask 077; mkdir -p "$HOME/.cache/claude-images"'
scp "$HOME/Desktop/shot.png" devbox:.cache/claude-images/shot.png

이 첫 예제는 이해를 위해 고정 이름을 쓰며, 같은 경로의 파일을 다시 보내면 바뀔 수 있습니다. 반복 사용에는 다음 절의 고유 파일명 함수를 사용하세요.

원격 서버에서 도착한 파일을 확인합니다.

ls -l "$HOME/.cache/claude-images/shot.png"
file "$HOME/.cache/claude-images/shot.png"

그다음 원격 Claude Code 대화에 요청합니다.

~/.cache/claude-images/shot.png를 읽고 화면의 정렬 문제를 설명해 줘. 아직 코드는 고치지 말고 어느 요소를 확인해야 하는지 먼저 알려 줘.

이미지를 읽은 것이 확인되면 수정 요청을 이어 갑니다. 로컬 파일 경로를 원격 대화에 적는 것만으로 파일이 전송되지는 않습니다.

5. 반복할 때: 클립보드에서 바로 전송하는 함수

로컬 Mac에 pngpaste를 설치합니다. 클립보드 이미지를 파일로 쓰는 도구이며 서버에 설치할 필요는 없습니다. Homebrew 공식 패키지

brew install pngpaste

로컬 Mac의 ~/.zshrc에 다음 함수를 추가합니다. 처음에는 로컬 터미널에 그대로 붙여 넣어 시험해도 됩니다. 이 코드는 zsh용으로 확인했으며, 원격 셸의 설정 파일에 넣는 코드가 아닙니다.

cpshot() (
  local host="${1:-devbox}"
  local local_png remote_name
  command -v pngpaste >/dev/null 2>&1 || {
    printf 'Install pngpaste on this Mac first.\n' >&2
    exit 127
  }
  local_png="$(mktemp "${TMPDIR:-/tmp}/claude-shot.XXXXXX")" || exit 1
  trap 'rm -f "$local_png"' EXIT
  pngpaste "$local_png" || exit 1
  remote_name="$(basename "$local_png").png"
  ssh "$host" 'umask 077; mkdir -p "$HOME/.cache/claude-images"' || exit 1
  scp "$local_png" "$host:.cache/claude-images/$remote_name" || exit 1
  printf 'Uploaded to %s: ~/.cache/claude-images/%s\n' "$host" "$remote_name"
)

새 로컬 터미널을 열거나 source ~/.zshrc로 반영한 뒤, 클립보드에 화면을 캡처하고 실행합니다.

cpshot devbox

함수가 출력한 이번 파일 경로를 원격 Claude Code에 전달합니다. devbox를 기본값으로 바꾸어 두었다면 인자 없이 cpshot으로 실행할 수 있습니다.

이 함수는 매번 고유한 이름을 쓰고, 읽기나 전송에 실패하면 중단하며, 전송 성공 뒤에만 성공 문구를 출력합니다. 로컬 임시 파일은 종료 시 정리하고 원격 파일은 남깁니다. 모의 명령으로 이 흐름을 확인했지만 실제 SSH 인증과 파일 전송은 자신의 서버에서 한 번 확인해야 합니다.

6. 방법 C: Tailscale Taildrop으로 파일 보내기

Tailscale 공식 웹사이트의 Taildrop을 이미 사용하는 개인 기기라면 파일을 공유할 수 있습니다. 현재 공식 문서상 Taildrop은 활성화가 필요한 alpha 기능이며, 같은 사용자의 개인 기기 사이에서 사용합니다. 다른 사용자 소유 기기나 태그가 붙은 노드에는 제한이 있습니다.

Mac에서 PNG 파일을 준비한 뒤 Finder의 공유 메뉴에서 Tailscale을 선택하고 대상 기기로 보냅니다. 수신 완료와 Claude Code가 읽을 수 있는 파일 경로 확보를 구분해야 합니다.

Linux 서버에서는 공식 문서가 별도 수신 명령을 안내합니다. 원격 Linux에서 다음처럼 수신 폴더를 정하고 가져옵니다.

mkdir -p "$HOME/.cache/claude-images"
sudo tailscale file get "$HOME/.cache/claude-images"
ls -l "$HOME/.cache/claude-images"

파일 이름과 권한을 확인합니다. 수신 파일이 root 소유여서 Claude 실행 사용자가 읽지 못하면, 실제 받은 파일 하나를 지정해 소유권을 맞춥니다. 다음은 파일 이름이 shot.png인 경우입니다.

sudo chown "$(id -u):$(id -g)" "$HOME/.cache/claude-images/shot.png"

원격 Mac의 저장 위치도 앱과 설정에 따라 확인해야 합니다. 모든 서버에 자동으로 ~/Downloads에 저장된다고 가정하지 마세요. 파일을 확인한 뒤 그 실제 원격 경로를 Claude Code에 전달합니다. Taildrop 공식 전송·수신 안내

7. 방법 D: VS Code Remote-SSH와 Claude Paste

VS Code 공식 웹사이트의 Remote-SSH 안내에 따라 서버에 연결했다면, 통합 터미널에서 원격 tmux와 Claude Code를 사용할 수 있습니다. 이것만으로 로컬 이미지 클립보드가 자동 전송되는 것은 아닙니다.

Claude Paste 제작자의 Marketplace 페이지는 로컬 이미지를 원격 파일로 만들고 그 경로를 터미널에 넣는 기능을 안내합니다. Anthropic이나 Microsoft의 기본 기능이 아닌 별도 제작자의 확장입니다.

  1. Remote-SSH로 연결된 VS Code 창에서 해당 Marketplace 항목을 확인하고 설치 안내를 따릅니다.
  2. 원격 통합 터미널의 Claude Code를 열거나 기존 tmux에 연결합니다.
  3. 로컬 Mac에서 이미지를 클립보드에 복사합니다.
  4. 통합 터미널에서 Cmd+V를 누릅니다. 제작자의 현재 안내는 붙여넣기 대상이 나타나면 다시 Cmd+V를 눌러 캡처하도록 설명합니다.
  5. 주입된 원격 경로를 확인하고 작업 내용을 보냅니다.

Claude Paste 제작자의 공개 사용 안내에서 첫 붙여넣기 뒤 대상 창에 다시 붙여넣고 파일 경로를 받는 절차를 설명한다

확장 제작자의 공개 README에 있는 사용 절차 캡처. (출처: Claude Paste 사용법, 2026-10-25 캡처)

현재 문서에는 임시 이미지 보존 시간 설정도 있습니다. 나중에 같은 경로를 재사용하려면 파일이 남아 있는지 확인하세요. 단축키 충돌이나 지원 환경은 설치 버전의 안내를 따릅니다. 문서의 설치 CLI 식별자와 Marketplace 항목 표기가 달라, 이 글에서는 검증한 Marketplace 페이지를 통해 설치하도록 안내했습니다.

8. 안 될 때는 세 단계로 나눠 확인하기

단계확인할 것흔한 원인
로컬 캡처이미지가 클립보드나 PNG 파일에 있는가이미지 대신 파일 이름·텍스트를 복사함
전달원격 사용자에게 읽히는 파일이 도착했는가인증 실패, 다른 호스트, 잘못된 경로·권한
Claude 입력실제 첨부 또는 원격 이미지 읽기가 확인되는가로컬 경로만 전달, 만료된 임시 파일, 형식 문제

긴 Base64 문자열을 대화창에 붙이기보다 이미지 첨부나 파일 읽기 기능을 사용하세요. pbpaste로 이미지 바이너리를 출력하는 것도 이 흐름의 대체 방법이 아닙니다.

우선 저장된 PNG를 한 번 전송해 원격 Claude가 읽는지 확인하고, 자주 쓴다면 전송 함수를 붙이세요. 브라우저가 편하고 계정 조건을 만족하면 Remote Control을, 이미 쓰는 환경이 있다면 Taildrop이나 VS Code 확장을 선택하면 됩니다. tmux의 역할은 세션 유지이며, 이미지 전달은 선택한 전송 경로가 담당합니다.

Related