imap-client은(는) 무엇을 하나요?
myl이라는 작은 Python CLI 클라이언트를 사용하여 터미널에서 IMAP을 통해 메일함을 읽습니다. codd-tech에서 유지 관리 및 배포합니다. OpenClaw 및 기타 AgentSkills 호환 런타임(Claude Code, 일반)에 바로 적용할 수 있도록 설계되었습니다.
myl은 읽기 전용이며 의도적으로 최소한의 기능만 제공합니다. 메시지와 첨부 파일을 나열, 검색 및 가져옵니다. 메일을 보내거나, 폴더를 관리하거나, 선택적으로 메시지를 읽음으로 표시하는 것 외에는 상태를 변경하지 않습니다.
이 스킬에 자격 증명이 전달되는 방식
이것이 가장 중요한 섹션입니다. 명령줄에 비밀번호를 입력하지 마십시오. 자격 증명은 런타임이 에이전트 실행당 주입하는 환경 변수에 저장됩니다. 스킬은 이 변수들을 읽고 {baseDir}/scripts/imap.sh에 있는 래퍼를 통해 올바른 myl 플래그를 조합합니다.
래퍼가 예상하는 변수:
| 변수 | 필수 여부 | 용도 |
|---|---|---|
IMAP_USER | 예 | 로그인 (보통 전체 이메일 주소) |
IMAP_PASSWORD | 예 | 앱 비밀번호 (references/authentication.md 참조) |
IMAP_PROVIDER | 아니오 | auto(기본값), gmail, yandex, mailru, manual 중 하나 |
IMAP_SERVER | manual인 경우에만 | IMAP 호스트 |
IMAP_PORT | 아니오 | 기본값 993 |
IMAP_STARTTLS | 아니오 | 1로 설정하면 --starttls 추가 (포트 143에서만 사용) |
한 번 설정하면 모든 세션에서 사용할 수 있습니다. 방법은 런타임에 따라 다릅니다. references/authentication.md에서는 OpenClaw의 skills.entries.imap-client.env, 일반 셸 export, 그리고 ~/.config/imap-client/credentials 대체 파일을 다룹니다. 자신만의 방식을 발명하지 말고, 이 세 가지 중 하나를 사용하십시오.
래퍼가 IMAP_USER 또는 IMAP_PASSWORD가 누락되었음을 감지하면 설정 지침을 출력하고 서버에 연결하지 않고 종료됩니다. 이는 중단하고 자격 증명 설정을 사용자에게 안내한 후 다시 시도하라는 신호입니다.
한눈에 보는 워크플로
myl이 설치되어 있는지 확인합니다. OpenClaw는 이 스킬을requires.bins: ["myl"]에 게이트하므로,myl없이는 로드되지 않습니다. OpenClaw가 아닌 런타임의 경우bash {baseDir}/scripts/check_myl.sh를 실행합니다. 없으면references/installation.md를 따릅니다.- 자격 증명이 구성되었는지 확인합니다.
bash {baseDir}/scripts/imap.sh --count 1 >/dev/null을 한 번 실행합니다. 성공하면 env 변수가 연결되고 연결이 작동한다는 의미입니다. 실패하면references/authentication.md를 통해 사용자를 안내합니다. - 래퍼를 통해 요청된 작업을 실행합니다. 나열, 검색, ID로 가져오기, HTML 가져오기, 원시
.eml저장 또는 첨부 파일 다운로드. - 결과를 요약합니다. 사용자가 요청하지 않는 한 원시 이메일 본문 전체를 채팅에 덤프하지 마십시오.
이 스킬의 모든 myl 예제는 {baseDir}/scripts/imap.sh를 통해 실행되며, 이는 env 변수를 올바른 myl 플래그로 확장합니다. --google 대 --auto 대 --server/--port를 기억할 필요가 없습니다. 래퍼가 IMAP_PROVIDER를 기반으로 선택합니다.
무엇을 언제 읽어야 하는지
| 작업 내용… | 읽을 문서 |
|---|---|
myl 감지 또는 설치, OpenClaw requires.bins 게이트 | references/installation.md |
| 자격 증명 설정, 연결 모드 선택, Gmail / Yandex / Mail.ru / iCloud / Fastmail용 앱 비밀번호 | references/authentication.md |
| 특정 CLI 플래그, 나열, 검색, 가져오기, 첨부 파일, 제공업체별 폴더 이름 | references/operations.md |
| 여러 단계로 구성된 레시피 (예: "지난 달 Acme에서 온 송장을 찾아 PDF 저장") | references/recipes.md |
| SSL 실패, "command not found", 자동 검색 실패, "AUTHENTICATIONFAILED", 래퍼에 표시되지 않는 env 변수와 같은 오류 | references/troubleshooting.md |
원칙
1. 자격 증명이 생성하는 명령에 절대 나타나지 않음
런타임에서 env 변수를 주입하므로 래퍼가 내부적으로 처리합니다. myl -p hunter2 또는 myl -p "$IMAP_PASSWORD"와 같은 명령을 직접 생성하지 마십시오. 둘 다 누출됩니다. 첫 번째는 셸 기록에 남고, 두 번째는 myl이 실행되는 동안 /proc/<pid>/cmdline에 비밀번호를 노출합니다. 래퍼를 사용하면 비밀번호가 자체 프로세스 범위 내에 유지됩니다:
bash {baseDir}/scripts/imap.sh --count 5
래퍼는 지원되는 경우 stdin을 통해, 그렇지 않은 경우 내부적으로 구성하는 플래그를 통해 myl에 자격 증명을 전달합니다. 이는 직접 myl을 사용할 때와 동일한 절충안이지만, 비밀번호 리터럴이 사용자가 작성, 기록 또는 표시한 명령에 절대 나타나지 않습니다.
2. 기본적으로 적은 결과 집합 사용
사용자의 의도가 탐색적인 경우("새 메일 있나요?") --count 5 또는 --count 10을 전달합니다. 명시적인 요청이 있을 때만 더 큰 범위를 가져옵니다. 이렇게 하면 출력을 읽을 수 있게 유지하고 사용자가 보길 원하지 않는 민감한 콘텐츠를 덤프하지 않습니다.
3. 실수로 읽음으로 표시하지 않음
--mark-seen은 서버의 상태를 변경합니다. 사용자가 명시적으로 메시지를 읽음으로 표시하도록 요청한 경우에만 전달합니다. 이 플래그 없이 나열하거나 읽는 것은 비파괴적입니다.
4. 긴 본문은 파일로 렌더링하고 채팅에서는 요약
사용자가 긴 메시지나 HTML 이메일을 가져오는 경우, 원시 출력을 파일(예: /tmp/email-<id>.eml 또는 .html)로 저장하고 2~4문장 요약과 파일 경로를 사용자에게 제공합니다. 500줄짜리 HTML 본문을 대화에 붙여넣지 마십시오.
5. 검색 구문은 Gmail의 웹 UI가 아닌 서버 측 IMAP임
--search "important"는 IMAP SEARCH 명령을 실행합니다. Gmail의 from:, has:attachment, 또는 label: 연산자를 이해하지 못합니다. 복잡한 필터링의 경우 --count로 합리적인 범위를 가져오고 로컬에서 목록을 필터링합니다. IMAP SEARCH가 지원하는 내용은 references/operations.md를 참조하십시오.
6. 비밀번호를 절대 출력, 요약 또는 저장하지 않음
수행한 작업을 요약할 때 자격 증명을 IMAP_PASSWORD 또는 "OpenClaw 구성의 비밀번호"로 언급하고, 실제 값은 절대 언급하지 마십시오. 사용자가 실수로 채팅에 비밀번호를 붙여넣은 경우 손상된 것으로 간주하고, 비밀번호를 변경하고 구성을 업데이트하도록 알리십시오. 어떤 아티팩트에도 기록하지 마십시오.
빠른 의사 결정 트리
사용자가 CLI에서 이메일 관련 작업을 요청함
│
├─ `myl`이 설치되어 있고 PATH에 있습니까? ── 아니오 ──► references/installation.md
│ │
│ 예
│ ▼
├─ 래퍼 연기 테스트가 통과했습니까?
│ bash {baseDir}/scripts/imap.sh --count 1 >/dev/null
│ │ 아니오 ──► references/authentication.md
│ 예
│ ▼
├─ 사용자가 원하는 것은 무엇입니까?
│ ├─ 찾아보기 / 나열 ──► imap.sh --count N [--folder F]
│ ├─ 검색 ──► imap.sh --search "TERM" [--count N]
│ ├─ 하나의 메시지 읽기 ──► imap.sh "$MAILID"
│ ├─ HTML 버전 읽기 ──► imap.sh --html "$MAILID" → 파일로 저장
│ ├─ 원시 .eml 저장 ──► imap.sh --raw "$MAILID" > file.eml
│ ├─ 첨부 파일 가져오기 ──► imap.sh "$MAILID" "$ATT_NAME" > file
│ └─ 여러 단계 작업 ──► references/recipes.md
│
└─ 오류가 있습니까? ─────────────────────► references/troubleshooting.md
출력 스타일
래퍼를 실행한 후 다음과 같은 형식으로 결과를 제시하십시오:
- 한 줄 상태 방금 실행한 작업 (예: "INBOX에서 가장 최근 메시지 10개를 나열했습니다").
- 간결한 표 또는 글머리 기호 목록 메시지 메타데이터 (날짜, 발신자, 제목, ID).
- 파일 경로 더 큰 출력이 저장된 경우.
- 제안된 다음 작업 (예: "#4582를 열거나 첨부 파일을 저장할까요?").
훑어보기 쉽게 유지하십시오.