設定

ZenCopy は、入れたその日から何も設定せずに使えます。このページは「もっと自分に合わせたい」と思ったときのガイドです。前半の設定画面の話は全員向け、後半の設定ファイルの話は上級者向けです。

設定画面でできること

設定画面は、常駐アイコンのメニュー、またはポップアップの歯車アイコンから開けます。 一般・AI・アクションの 3 つのタブがあります。

一般

ポップアップの位置 — 結果を画面のどの隅に出すか。
テーマ — ライト / ダーク / システムに合わせる。
言語 — 表示言語（標準では OS に合わせます）。
ログイン時に起動 — パソコンを付けたら ZenCopy も待機。
送信前の確認 — 画像やファイルを AI に送る前に、ひと言たずねるかどうか。

AI

AI サービスの接続先（プロバイダー・モデル・API キー）をここで変えられます。接続できているかはテストボタンですぐ確かめられます。

このタブにはあなたについてという欄もあります。自分の役割や好みを、普段の言葉で数行書いておく場所です。

例: 「営業職。お客様へのメールが多い。丁寧すぎない敬語で、結論を先に。」

書いておくと、すべてのアクションの結果があなた向けに調整されます。説明はあなたの知識に合った深さになり、文章はあなたの好みの調子になります。関係のないタスクには影響せず、内容が結果にそのまま現れることもありません。

アクション

「コピー 2 回のあとに何をするか」の一覧です。

最初から入っているアクションは、開いて中身を見られます（書き方の実例になります）。
新しいアクションは、名前とやってほしいことを書くだけで作れます。例: 名前「3 行まとめ」、指示「3 行で要約してください」。
指示をうまく書く自信がなくても大丈夫です。やりたいことを雑に書いて AI で下書きを押すと、設定済みの AI が整った指示に仕上げてくれます。
ルーティングでは、コピーした内容の種類（テキスト / 画像 / ファイルなど）ごとに、どのアクションを動かすかを変えられます。

作ったアクションはエクスポートでファイルとして書き出して人に渡せます。受け取る側はインポートに貼り付けるか、ファイルを選ぶだけです。

作業全体をAIに任せたいですか？どのAIチャットでも、インポート可能なアクションを作成できます。以下を貼り付けて、空欄を埋めてください：

https://zencopy.app/llms-full.txt を読んでください。これは、アクションのファイル形式、テンプレート変数、ルーティングの仕組みを含むZenCopyの完全なドキュメントです。その後、次の処理を行うZenCopyアクションを作成してください：[やりたいこと]。ZenCopyの「設定 → アクション → インポート」にそのまま貼り付けられるように、フロントマター付きの完全なアクションファイル（Markdown）を1つのコードブロックで出力してください。そのアクションが特定のアプリや特定のサイトでのみ機能する場合は、どのルーティングルールを設定すべきかを説明する文章を1文追加してください。

返信内のコードブロックは、そのまま設定 → アクション → インポートに貼り付けられます。ドキュメントでは解決できない疑問（「ZenCopyでこんなことできる？」など）がある場合は、ワンクリックで関連ソースをパックして、その結果を同じAIに渡してください。

設定ファイル（上級者向け）

ここから先は、テキストファイルを直接編集する話です。 画面の設定だけで主要な機能はすべて使えるので、興味がなければ読み飛ばしてかまいません。

ファイルはユーザーごとのアプリ設定ディレクトリから読み込まれます。正確なパスは起動時のログにも出力されます:

%APPDATA%\app.zencopy

~/Library/Application Support/app.zencopy

~/.config/app.zencopy

ルーティングの既定値はアプリに埋め込まれており、routing.json は常にその上書きとしてだけ働きます。アクションのファイルは追加専用です: 新しいアクションを定義するもので、組み込みのアクションは不可侵です（同じ id を名乗るローカルファイルは無視されます）。編集は次のトリガーから反映され、再起動は不要です。

`ai-sdk-catalog.json`

プロバイダーと role → モデル の対応。ファイル形式の本家は ai-sdk-catalog です。全フィールドの説明（エディタで検証・補完が効く $schema を含む）はそちらにあり、examples/ には 3 サイズの設定例が揃っています。 ZenCopy 向けの出発点（設定 UI が書く形、ローカル Ollama、アクション用の role）はレシピ集を見てください。

1 点だけ、ファイル形式ではなく ZenCopy 側の要件があります: roles には必ず default を含めてください。 frontmatter で別の role を指定しないアクションはすべて default で実行され、設定画面の接続テストも default に ping します。

API キーはこのローカルファイルに直接書きます（設定 UI が書くのもこの形式）。キーが端末の外に出ることはありません。環境変数は読み込みません。GUI アプリはシェルではなく OS から起動されるため、.zshrc などで export した変数はそもそも届かないからです。このファイルは読み込みのたびにスキーマ検証されます。壊れた編集は、ポップアップと設定エディタに明確なメッセージとして表示され、黙って失敗することはありません。

`routing.json`

どの種類のキャプチャをどのアクションが処理するか: フラットな kind → action の対応と、より優先される任意の overrides リスト（先勝ち）。 kind は text、rich_text、image、files の 4 種類で、初期状態ではテキストが 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 のキャプチャでは、内容そのものがモデルに送信されます（1 回あたり合計 10 MB まで）。ファイルの種類は名前ではなく中身から判定されます: 画像・PDF・音声はそのまま添付され、テキストファイル（Markdown、ソースコード、CSV など）はキャプチャのテキストそのもの（{{ text }}）になり、内容をコピーした場合とまったく同じように扱われます。 Office ドキュメント（Word、Excel、PowerPoint）もテキストになります。内容は抽出されて送信されますが、レイアウトや画像は送信されません。文字コードは自動判定され、Shift_JIS や UTF-16 のようなレガシーな形式も変換されます。どちらでもないものは明確なメッセージつきでお断りします。モデルがファイルを区別し場所を把握できるように、内容と一緒にフルパスも送信されます。バイナリの添付はテキストより料金がかかりうるため、送信前にポップアップが確認します（テキストファイルは確認なしで実行されます）。確認はその場または設定でオフにできます。

`actions/*.md`

1 ファイル = 1 アクション: YAML フロントマター + Liquid のプロンプト本文。この 1 ファイルがそのまま共有形式でもあります — 設定 → アクション → インポートで、本文の貼り付けかファイル選択で受け取れます。

---
id: summarize
label: 要約
role: default
instructions: あなたは簡潔なアシスタントです。
---

次の内容を {{ locale }} で3行に要約してください:

{{ text }}

フロントマター	意味
`id`	`routing.json` から参照される名前（省略時はファイル名） — 接頭辞 `zencopy-` はプリインストールアクション専用
`label`	ポップアップに表示
`role`	実行に使う catalog の role（省略時は `default`）
`instructions`	システムプロンプト（Liquid テンプレート）

テンプレート変数と、ブラウザで段落をコピーした場合の値の例:

変数	例
`{{ text }}`	コピーした本文（HTML のリッチコピーは Markdown に変換）
`{{ markup }}`	リッチコピー時の HTML/RTF ソース
`{{ format }}`	`html`（または `rtf`。プレーンコピーでは空）
`{{ file_name }}`	`report.pdf`（コピーした最初のファイル名）
`{{ file_names }}`	コピーしたすべてのファイル名（1 行に 1 つ）
`{{ file_paths }}`	コピーしたすべてのファイルのフルパス（1 行に 1 つ）
`{{ 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 }}`	`ja`

さらに ZenCopy 独自の language_name フィルタがあります。 {{ locale | language_name }} は「ja」ではなく「Japanese」と展開され、プロンプトとして自然に読めます。実際にどんな値が入るかは、設定で開発者モードを有効にすると確認できます。キャプチャごとのテンプレート変数が、ポップアップに JSON で表示されます。

シンプルなアクション（名前と指示だけ）は設定ウィンドウからも作成できます。書き出されるのはまさにこの形式のファイルです。

高度なテンプレート

instructions フロントマターと本文は、どちらも完全な LiquidJS テンプレートです: 条件分岐・ループ・フィルターがすべて使えます。 1つのアクションを、コピー元に応じて振る舞い分けることもできます:

---
id: context-aware
label: 文脈で切り替え
---

{% if url contains "github.com" %}
このコードをレビューして、最大のリスクを1つ指摘してください:
{% elsif app_name == "Slack" %}
このチャットのスレッドを2行で要約してください:
{% else %}
これを {{ locale }} で説明してください:
{% endif %}

{{ text | truncate: 8000 }}

ログ

構造化ログ（秘密情報とコピー内容は redact 済み）は、dev ではターミナル、release ではローテーション付きファイルに出力されます:

%LOCALAPPDATA%\app.zencopy\logs

~/Library/Logs/app.zencopy/

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