SSH를 통한 원격 작업
연결 세부 정보는 프로젝트 폴더의 ssh.md 파일에 있습니다. 원격 세션을 시작하기 전에 항상 이 파일을 읽으세요. 호스트, 사용자, 포트, 키 경로 또는 비밀번호를 임의로 추측하지 마세요.
활성화 시점
- 사용자가 원격 머신에 연결, 로그인, 또는 명령 실행을 요청하는 경우
- 사용자가 원격 프로젝트의 검사, 편집, 빌드, 또는 테스트를 요청하는 경우
- 사용자가 서버, VPS, 또는 원격 호스트를 언급하며 SSH 접근을 기대하는 경우
1단계: ssh.md 찾기
프로젝트 폴더는 git rev-parse --show-toplevel 명령어로 확인하며, 실패할 경우 현재 디렉토리를 사용합니다. ssh.md 파일은 항상 <프로젝트 폴더>/ssh.md에 위치합니다.
파일이 존재하지 않으면 템플릿에서 생성하고 사용자에게 내용을 채우도록 알립니다:
ssh.example.md파일을 찾습니다. 이 파일은 이 스킬의 폴더에 있으며, 에이전트에 따라 위치가 다릅니다. 다음 경로를 순서대로 확인하고 첫 번째로 존재하는 경로를 사용하세요:.agents/skills/remote-work-ssh/,.claude/skills/remote-work-ssh/,.opencode/skills/remote-work-ssh/,~/.agents/skills/remote-work-ssh/,~/.claude/skills/remote-work-ssh/,~/.config/opencode/skills/remote-work-ssh/. 존재하는 경로가 없으면find ~ -path '*remote-work-ssh*' -name ssh.example.md 2>/dev/null | head -n 1을 실행하세요.- 해당 파일을
<프로젝트 폴더>/ssh.md로 복사합니다. - 프로젝트의
.gitignore에ssh.md가 없으면 추가합니다..gitignore가 없으면 생성합니다. - 중단하고 사용자에게
ssh.md를 채우도록 안내합니다.
2단계: 설정 검증
ssh.md에는 하나의 YAML 블록이 포함되어 있습니다. 다음 필드를 확인하세요:
auth는alias,key, 또는password중 하나여야 합니다.remote_project_path는 반드시 설정되어야 합니다.- 선택한 인증 방식에 필요한 필드가 설정되어야 합니다:
auth | 필수 필드 |
|---|---|
alias | alias |
key | host, user, identity_file (port 기본값은 22) |
password | host, user, password_env (port 기본값은 22) |
필수 필드가 누락되었거나 auth 값이 올바르지 않으면 중단하고 정확히 어떤 필드가 잘못되었는지 보고하세요. 다른 방식으로 대체하지 마세요.
3단계: 연결
별칭 (alias)
먼저 별칭을 확인한 후 연결합니다:
ssh -G <alias> | grep -E '^(hostname|user|port) '
ssh -o BatchMode=yes <alias> 'hostname && whoami'
키 (key)
identity_file이 존재하는지 확인합니다. 없으면 중단합니다.- 해당 키만 사용합니다:
ssh -o BatchMode=yes -o IdentitiesOnly=yes -i <identity_file> -p <port> <user>@<host> 'hostname && whoami'
proxy_jump가 설정되어 있으면-J <proxy_jump>를 추가합니다.
비밀번호 (password)
command -v sshpass로sshpass가 설치되어 있는지 확인합니다. 없으면 중단하고 사용자에게 설치하도록 알립니다.password_env가 가리키는 환경 변수가 설정되어 있는지 확인하되, 값을 출력하지는 마세요.SSHPASS환경 변수와-e옵션을 통해sshpass에 값을 전달합니다. 비밀번호를 명령줄 인수나 출력에 절대 넣지 마세요.- 키 기반 시도를 비활성화하여 비밀번호만 사용하도록 합니다:
SSHPASS="$(printenv <password_env>)" sshpass -e ssh -o PubkeyAuthentication=no -o PreferredAuthentications=password -p <port> <user>@<host> 'hostname && whoami'
proxy_jump가 설정되어 있으면-J <proxy_jump>를 추가합니다.- 여기서는
BatchMode=yes를 사용하지 마세요. 비밀번호 인증을 비활성화합니다.
호스트 키 (모든 인증 방식)
- 호스트 키가 알 수 없거나 변경된 경우 중단합니다. 지문을 표시하고 사용자에게 확인을 요청하세요.
StrictHostKeyChecking=no또는 검증을 건너뛰는 유사한 옵션을 절대 설정하지 마세요.
4단계: 원격 프로젝트에서 작업
- 모든 명령은
remote_project_path내에서 실행하세요. 예:ssh ... 'cd <remote_project_path> && <command>'. 경로를 따옴표로 감싸세요. - 원격 머신에 도구가 존재한다고 가정하기 전에 매니페스트를 확인하거나
command -v <tool>을 실행하세요. - 사용자가 요청하지 않는 한
remote_project_path밖에 쓰지 마세요.
안전 규칙
rm -rf, 강제 푸시, 데이터베이스 삭제, 디스크 작업, 서비스 재시작과 같은 파괴적인 명령 전에는 반드시 물어보세요.- 비밀번호, 키 내용 또는 토큰을 출력, 복사, 로그, 커밋하지 마세요.
- 프로젝트의
ssh.md또는 환경 변수 외의 다른 파일에 자격 증명을 저장하지 마세요. - 사용자가 요청하지 않은 명령을 원격 머신에서 실행하지 마세요.
지원되지 않는 작업
- 추적된 파일이나 이 스킬에 비밀번호 저장
- 사용자를 대신한 대화형 MFA 또는 일회용 코드 처리
- 호스트 키 검증 비활성화
ssh.md에 정의되지 않은 호스트에 연결