설정

ZenCopy는 아무것도 설정하지 않아도 바로 동작합니다. 이 페이지는 앱을 나에게 더 잘 맞추고 싶을 때를 위한 것입니다. 전반부의 설정 창은 모두를 위한 내용이고, 후반부의 설정 파일은 파워 유저를 위한 내용입니다.

설정 창

트레이 아이콘의 메뉴나 팝업의 톱니바퀴 아이콘에서 엽니다. 일반, AI, 액션의 세 탭이 있습니다.

일반

• 팝업 위치 — 결과를 화면의 어느 모서리에 표시할지.
• 테마 — 라이트 / 다크 / 시스템 따르기.
• 언어 — 표시 언어(기본은 OS를 따릅니다).
• 로그인 시 시작 — 컴퓨터가 켜져 있는 동안 항상 ZenCopy가 대기하도록.
• 이미지·파일 전송 전 확인 — 이미지나 파일을 AI로 보내기 전에 한 번 물어볼지.

AI

AI 서비스(제공업체, 모델, API 키)를 바꾸는 곳입니다. 테스트 버튼을 누르면 연결이 되는지 바로 알 수 있습니다.

이 탭에는 나에 대하여 입력란도 있습니다. 자신의 역할과 취향을 어떤 언어로든 평범한 문장 몇 개로 적어 두는 곳입니다.

예: “영업직. 쓰는 글 대부분이 고객 이메일이에요. 정중하되 딱딱하지 않게, 결론부터.”

이 내용을 채워 두면 모든 액션이 결과를 나에게 맞춰 줍니다. 설명은 내 지식 수준에 맞춰 도착하고, 초안은 선호하는 어조로 돌아옵니다. 관련 없는 작업에는 절대 영향을 주지 않으며, 적어 둔 텍스트 자체가 결과에 나타나는 일도 없습니다.

액션

“두 번 복사한 다음 무엇을 할지”의 목록입니다.

• 기본 설치된 액션은 열어서 읽을 수 있습니다 — 잘 만들어진 예제 역할도 겸합니다.
• 새 액션에 필요한 것은 이름과 원하는 작업뿐입니다. 예: 이름 “3줄 요약”, 지시 “3줄로 요약해 주세요”.
• 지시문 작성이 자신 없다면, 원하는 것을 대충 적고 AI로 초안 작성을 누르세요 — 설정된 AI가 제대로 된 지시문으로 다듬어 줍니다.
• 라우팅에서는 내용의 종류(텍스트 / 이미지 / 파일)별로 다른 액션을 지정할 수 있습니다.

만든 액션은 공유할 수 있습니다. 내보내기(.md) 버튼이 액션을 파일 하나로 저장하고, 받는 쪽은 가져오기에 붙여넣거나 파일을 선택하기만 하면 됩니다.

모든 작업을 AI에게 맡기고 싶으신가요? 어떤 AI 채팅이든 바로 가져올 수 있는 액션을 작성해 줄 수 있습니다. 아래 내용을 복사해 붙여넣고 빈칸을 채워보세요:

https://zencopy.app/llms-full.txt 를 읽어보세요. 여기에는 액션 파일 형식, 템플릿 변수, 라우팅 작동 방식을 포함한 ZenCopy의 전체 문서가 포함되어 있습니다. 그런 다음 다음 작업을 수행하는 ZenCopy 액션을 작성해 주세요: [원하는 작업]. ZenCopy의 설정 → 액션 → 가져오기에 바로 붙여넣을 수 있도록 프런트매터(frontmatter)가 포함된 완전한 액션 파일(Markdown)을 하나의 코드 블록으로 출력해 주세요. 이 액션이 특정 앱이나 특정 사이트에서만 작동하는 경우, 어떤 라우팅 규칙을 설정해야 하는지 알려주는 문장을 한 줄 추가해 주세요.

답변의 코드 블록은 설정 → 액션 → 가져오기에 바로 붙여넣을 수 있습니다. 문서에서 답을 찾을 수 없는 질문(“ZenCopy로 이런 것도 가능할까?”)이 있다면, 클릭 한 번으로 관련 소스를 패키징하여 동일한 AI에게 전달해 보세요.

설정 파일 (파워 유저용)

여기서부터는 텍스트 파일을 직접 편집하는 이야기입니다. 꼭 필요한 것은 모두 설정 창에서 할 수 있으니, 여기서 읽기를 멈춰도 괜찮습니다.

파일은 사용자별 앱 설정 디렉터리에서 읽습니다. 정확한 경로는 시작 시 로그에도 출력됩니다:

Windows

%APPDATA%\app.zencopy

macOS

~/Library/Application Support/app.zencopy

Linux

~/.config/app.zencopy

라우팅 기본값은 앱에 내장되어 있고, routing.json은 이를 덮어쓰기만 합니다. 액션 파일은 추가 전용입니다. 새 액션을 정의할 뿐, 기본 제공 액션은 건드릴 수 없습니다(기본 제공 id를 쓰겠다는 로컬 파일은 무시됩니다). 편집 내용은 다음 트리거부터 적용됩니다 — 재시작이 필요 없습니다.

ai-sdk-catalog.json

제공업체와 역할 → 모델 매핑입니다. 이 파일 형식의 본가는 ai-sdk-catalog입니다 — 모든 필드가 그곳에 문서화되어 있고(에디터의 검증·자동 완성을 위한 $schema 포함), examples/에는 세 가지 규모의 설정이 있습니다. ZenCopy에 맞춘 출발점(설정 UI가 저장하는 내용, 로컬 Ollama, 액션용 역할)은 레시피를 참고하세요.

한 가지 요건은 파일 형식이 아니라 ZenCopy 자체의 것입니다: roles에는 반드시 **default**가 있어야 합니다. frontmatter에서 다른 role을 지정하지 않은 모든 액션이 이 role로 실행되며, 설정 화면의 연결 테스트도 이 role에 ping을 보냅니다.

API 키는 이 로컬 파일에 그대로 들어갑니다(설정 UI도 같은 형식으로 저장합니다). 키는 절대 이 컴퓨터를 떠나지 않습니다. 환경 변수는 읽지 않습니다 — GUI 앱은 셸이 아니라 OS가 실행하므로, .zshrc 등에서 내보낸 변수는 앱에 전달되지 않습니다. 파일은 읽을 때마다 스키마 검증을 거칩니다. 잘못된 편집은 팝업과 설정 편집기에 명확한 메시지로 나타납니다 — 조용히 실패하는 일은 없습니다.

routing.json

어떤 종류의 캡처를 어떤 액션이 처리할지: 평평한 kind → action 맵과, 우선순위가 더 높은 선택적 overrides 목록(먼저 일치하는 규칙이 적용)입니다. 네 가지 종류는 text, rich_text, image, files이고, 기본값은 텍스트가 Zen으로, 이미지와 파일이 설명으로 라우팅됩니다. 평평한 맵은 앱 안(설정 → 액션 → 라우팅)에서 편집할 수 있으므로, 이 파일을 직접 만질 일은 overrides뿐입니다.

{
  "text": "zencopy-zen",
  "rich_text": "zencopy-zen",
  "image": "zencopy-explain",
  "files": "zencopy-explain",
  "overrides": [{ "when": { "app_name": "Slack", "min_chars": 200 }, "action": "summarize" }]
}

when 조건: kind, app_name, exec_name, window_title, url (모두 * 와일드카드 사용 가능), file_name (복사된 모든 파일 이름이 대소문자 구분 없이 일치해야 하는 와일드카드 — 예: *.pdf), 그리고 min_chars / max_chars.

image와 files 캡처에서는 내용 자체가 모델로 전송됩니다(캡처당 총 10 MB까지). 파일 형식은 이름이 아니라 내용으로 판별합니다. 이미지, PDF, 오디오는 그대로 첨부되고, 텍스트 파일(Markdown, 소스 코드, CSV, …)은 캡처의 텍스트({{ text }})가 되어 그 내용을 직접 복사한 것과 똑같이 동작합니다. Office 문서(Word, Excel, PowerPoint)도 텍스트가 됩니다. 내용이 추출되어 전송되지만, 레이아웃과 이미지는 전송되지 않습니다. 문자 인코딩은 자동 감지되어 EUC-KR이나 UTF-16 같은 레거시 형식도 변환됩니다. 그 밖의 형식은 명확한 메시지와 함께 거절됩니다. 모델이 파일을 구별하고 위치를 알 수 있도록, 전체 경로가 내용과 함께 전달됩니다. 바이너리 첨부는 텍스트보다 비용이 더 들 수 있어서 팝업이 전송 전에 확인을 요청합니다(텍스트 파일은 확인 없이 실행됩니다) — 확인은 그 자리에서 또는 설정에서 끌 수 있습니다.

actions/*.md

파일 하나 = 액션 하나. YAML frontmatter + Liquid 프롬프트 본문입니다. 이 파일 하나가 그대로 공유 형식이기도 합니다 — 설정 → 액션 → 가져오기에서 텍스트로 붙여넣거나 파일을 선택해 받을 수 있습니다.

---
id: summarize
label: 요약
role: default
instructions: 당신은 간결한 어시스턴트입니다.
---

다음 내용을 {{ locale }}로 3줄로 요약해 주세요:

{{ text }}

Frontmatter	의미
id	routing.json에서 참조하는 이름(기본값: 파일 이름) — 접두사 zencopy-는 사전 설치 액션 전용
label	팝업에 표시되는 이름
role	실행에 사용할 카탈로그 역할(기본값: default)
instructions	시스템 프롬프트(Liquid 템플릿)

템플릿 변수와, 브라우저에서 문단을 복사했을 때의 값 예시:

변수	예
{{ text }}	복사한 텍스트(HTML 리치 복사는 Markdown으로 변환)
{{ markup }}	리치 복사의 HTML/RTF 원본
{{ format }}	html(또는 rtf, 일반 복사에서는 비어 있음)
{{ file_name }}	report.pdf (첫 번째로 복사된 파일의 이름)
{{ file_names }}	복사된 모든 파일의 이름, 줄당 하나씩
{{ file_paths }}	복사된 모든 파일의 전체 경로, 줄당 하나씩
{{ app_name }}	Safari
{{ exec_name }}	Safari / chrome.exe
{{ exec_path }}	/Applications/Safari.app/Contents/MacOS/Safari
{{ window_title }}	요금 안내 – Example
{{ url }}	https://example.com/pricing(브라우저에서만)
{{ process_id }}	8123
{{ now }}	2026-07-08 20:15:00
{{ locale }}	ko

ZenCopy 전용 language_name 필터도 있습니다. {{ locale | language_name }}은 “ko”가 아니라 “Korean”으로 전개되어 프롬프트에서 자연스럽게 읽힙니다. 실제 값을 확인하려면 설정에서 개발자 모드를 켜세요 — 캡처마다 템플릿 변수가 팝업에 JSON으로 표시됩니다.

단순한 액션(이름과 지시만)은 설정 창에서도 만들 수 있으며, 그때 저장되는 것이 바로 이 형식의 파일입니다.

고급 템플릿

instructions frontmatter와 본문은 모두 완전한 LiquidJS 템플릿입니다. 조건문, 반복문, 필터가 모두 동작합니다. 하나의 액션이 복사한 출처에 맞춰 달라질 수 있습니다:

---
id: context-aware
label: 상황에 맞게
---

{% if url contains "github.com" %}
이 코드를 리뷰하고 가장 큰 위험 요소 하나를 지적해 주세요:
{% elsif app_name == "Slack" %}
이 채팅 스레드를 2줄로 요약해 주세요:
{% else %}
다음 내용을 {{ locale }}로 설명해 주세요:
{% endif %}

{{ text | truncate: 8000 }}

로그

구조화된 로그(비밀 정보와 복사한 내용은 마스킹)는 개발 시에는 터미널로, 릴리스에서는 순환되는 파일로 기록됩니다:

Windows

%LOCALAPPDATA%\app.zencopy\logs

macOS

~/Library/Logs/app.zencopy/

Linux

~/.local/share/app.zencopy/logs