FAQ

プライバシー・ブラウザ対応・データアクセス・対応 OS・トラブルシューティングに関するよくある質問。

これはキーロガーですか？

いいえ。キー入力の内容は、opt-in（text_content = true）しない限り捕捉されません。既定で記録されるのは入力があった事実とフィールド種別だけです。capture.text_content が未設定なら、対話式のバックグラウンド start が記録するかどうかを一度だけ確認します（既定は記録しない。正確な条件は CLI リファレンス）。zanei config set capture.text_content <true|false> でいつでも変更できます。opt-in してもパスワード欄は除外されます。有効な redactor が置換するのはルールに一致する値だけで、氏名・電話番号・FAX 番号・住所は削除しません。露出の制限には capture-time フィルタと保持期間を使ってください。データはマシンの外に出ません。プライバシーモデル参照。

データはどこへ行きますか？

ローカルの SQLite ファイル（~/.local/state/zanei/store.sqlite）だけに保存され、ほかの場所には置かれません。このファイルは暗号化されており、鍵はログインキーチェーンにあります。バイナリにはデータを送信する機能自体がなく、エンドポイントもテレメトリもアカウントもありません。既定では 48 時間で自動削除されます。

スクリーンショットを取りますか？

いいえ。Zanei はスクリーンショット・OCR・画面録画・画面収録 API を使いません。capture.content_snapshot を別途有効にした場合だけ、前面ウィンドウの可視範囲で macOS Accessibility が公開するテキストを読みます。secure field の subtree と単行入力欄の値は読まず、Secure Input 中は snapshot を取りません。プライバシーモデルを参照してください。

どのアプリから content snapshot を取得できますか？

macOS Accessibility で有用なテキストを公開する app だけです。対応範囲は app と UI 実装によって異なります。zanei apps は選択候補を表示しますが、読み取り可能な text の存在を保証しません。snapshot は前面ウィンドウの可視範囲で、document 全体ではありません。private window を確実に判定できないため、Safari・Firefox・Brave・Edge・Vivaldi・Arc は既定で snapshot scope 外です。サイトフィルタはChromeとSafariに適用します。他のbrowserはapp scopeで制御します。

どのブラウザの URL が取れますか？Safari は？

単体利用・組み込み利用の両方でChromeとSafariに対応します。Chromeのwindow modeでincognitoのURLイベントと本文を抑止します。Safariのプライベート状態は不明として扱い、プライベート閲覧の除外は保証しません。FirefoxのURL取得は未実装です。詳細とブラウザ別の表はイベントリファレンスへ。

特定のアプリやサイトを記録から外すには？

zanei filter exclude-app add com.example.app
zanei filter exclude-site add example.com

これらは capture-time フィルタで、該当イベントはストアに書き込まれる前に破棄されます。後から掃除する必要はありません。パスワードマネージャは既定で除外済みです。フィルタ参照。

opt-in すれば Electron や Chromium 系のアプリでも本文は取れますか？

たいてい取れます。Claude / Slack / VS Code などの Electron アプリでも、Electron ではない Chromium 系アプリでも同様です。これらのアプリは支援クライアントから要求があって初めてアクセシビリティツリーを構築するため、そうでなければ入力欄が macOS Accessibility からは「種類不明」に見えます。Zanei は observer を attach する際にアプリ要素の role を読み、これが Chromium にとってツリー構築の合図になります。ツリーは非同期に現れるため、1 秒後にフォーカス要素を読み直します。内容記録の opt-in が有効な間は、その opt-in のフィルタが許可するすべてのアプリに対して AXManualAccessibility の設定も試みます。Electron アプリはこれに応じてツリーを構築し、この属性に対応しないアプリは unsupported を返すだけで影響を受けません。これにより対象の打鍵本文が他と同様に記録されます。Zanei は種類を確認できない欄の本文は記録しないため、パスワード欄は除外されたままです。capture.text_content を変更したら Zanei を再起動してください。

一部の Chromium 系アプリで入力本文や content snapshot が捕捉されないのはなぜですか？

Chromium 系アプリは、外部クライアントからのアクセシビリティ要求を無視するように作ることができ、統合自体を無効にしているアプリもあります。アプリが content tree を公開しない場合、その content の入力本文（ui.value / data.text）と content snapshot（content.snapshot）は欠落し、Zanei が代わりに画面画像を使うこともありません。キー入力があった事実（input.key の回数など）は引き続き記録されます。クリックは AX hit-testing が機能する範囲でのみ記録されます。クリップボードのコピー／ペーストイベントは、本文が省略される場合も記録されます。コピー本文は macOS pasteboard から直接取得し、capture.text_content が有効で、コピー元 window で text capture が許可されている場合にだけ記録できます。この経路に AX tree は不要です。ペースト本文には、貼り付け先 window で同じ text-capture 条件が適用され、さらに AX が貼り付け先を text field と分類できる必要があります。分類できなければ、ペーストイベントの本文は null になります。

ストアを直接読んでもいいですか？

稼働中のストアは SQLCipher（AES-256）で暗号化されています。鍵は「Zanei store key」としてログインキーチェーンにあり、この Mac の外には出ません。そのため、バックアップや同期フォルダ、別のマシンにあるファイルのコピーは、鍵なしでは読めません。

自分のツールで中身を見るには、平文の SQLite スナップショットを書き出します。

zanei export --format sqlite --since 24h --out snapshot.sqlite

稼働中のストアと同じテーブルを持ち、sqlite3、DB Browser for SQLite、各言語の SQLite バインディングで開けます。zanei query --store snapshot.sqlite でも読めます。スナップショットは暗号化されていないので、他のエクスポートと同じように扱ってください。scope 内なら content-snapshot 本文も含みます。共有・外部処理から除くには、たとえば --types app.*,window.*,ui.*,input.*,browser.*,clipboard.* で他の family だけを選びます。多くの用途では引き続き zanei query --format jsonl のほうが簡単で、バージョン間で変わり得る内部テーブル構造ではなく、安定したイベントエンベロープの上に乗れます。

ChatGPT の Computer History と何が違いますか？

発想は同じで、どちらも自分の行動を AI の文脈にします。違うのはアーキテクチャです。Zanei はオープンソースで、保存はローカルのみ、クラウド処理はなく、接続先も特定のアシスタントに縛られません（CLI / skill / MCP）。構造化された LLM-ready データを返すところまでが Zanei の仕事で、解釈は接続した agent が行います。

Windows や Linux では動きますか？

まだです。イベントスキーマは設計上 OS 非依存で、Windows（UI Automation）と Linux（AT-SPI2/evdev、X11 先行）の collector がロードマップにあります。現在は macOS のみです。

会社のマシンで使ってもいいですか？

Zanei は自分のマシン上の自分の操作を記録するツールです。会社管理のマシンであれば、所属組織のポリシーに従ってください。他者の監視は想定外の用途であり、地域によっては違法です。

権限を付与したのに `doctor` が `denied` のままです

権限の切り替えは、対象プロセスの再起動後に正しく反映されることがあります。zanei stop && zanei start してから、もう一度 zanei doctor を実行してください。tccutil reset 後は tccd 側の抑制により、macOS を再起動するまで権限ダイアログが再表示されないことがあります（実機で確認済み）。ソースからビルドした場合は、権限が署名 ID に紐づく点にも注意してください。ビルドし直したバイナリは再付与が必要になることがあります（権限とコード署名）。

`zanei start` が終了コード 3 を返しました。recorder は動いていますか？

動いています。バックグラウンド start は recorder の生存確認後、heartbeat で権限不足が報告された場合に終了コード 3 を返します。アクセシビリティにはバンドル版の Zanei 行が自動追加されますが、入力監視はダイアログでの付与が有効でも行がないことがあります。再起動後は recorder 由来の zanei doctor の結果を正とします。一覧から行を操作する場合は、+ でインストール済みの Zanei.app を選択します。まだ権限不足と報告されている間は、zanei doctor --fix がペインを開いて正確な path をコピーします。詳細は権限ガイドを参照してください。権限を必要とする collector が degraded の間も、デーモンは動作を継続します。初回の権限ダイアログが応答待ちの間は、zanei doctor がオートメーションを not_determined と報告することがあるため、ダイアログに応答してからもう一度実行してください。この権限不足パスでは内容記録の選択を求めません。権限の付与後に zanei stop && zanei start を実行すると、最初に成功した対話式 start が選択を求めます。

Zanei をアンインストールするには？

bundle ID を指定した権限 reset がインストール済み app を解決できるよう、次の順で操作します。

アクセシビリティと入力監視の権限を解除します。システム設定 → プライバシーとセキュリティで Zanei の行を削除するか、Zanei がまだインストールされている間に次を実行します。

tccutil reset Accessibility dev.zanei.recorder
tccutil reset ListenEvent dev.zanei.recorder

recorder を停止します。

zanei stop

Zanei をアンインストールします。

brew uninstall zanei

Homebrew は設定と記録データを残します。これらも削除する場合は次を実行します。

rm -rf ~/.config/zanei ~/.local/state/zanei

ログインキーチェーンからストアの鍵を削除します。これ以降、ストアのバックアップコピーは読めなくなります。

security delete-generic-password -s dev.zanei.store

または、キーチェーンアクセスで「Zanei store key」を削除します。

アンインストール後は、bundle ID を指定する tccutil コマンドが dev.zanei.recorder を解決できません。TCC は bundle ID と署名で付与を照合するため、付与が残っていると同じ app の再インストール時にそのまま復活します。残ったアクセシビリティの判断を完全に消すには、システム設定に Zanei の行が残っていればそこから削除するか、bundle ID を付けずに tccutil reset Accessibility を実行します。後者は全アプリのアクセシビリティ判断を reset します。

アンインストール前に zanei stop を忘れた場合でも、recorder は自身の実行ファイルがなくなったことを検出し、数十秒以内に自動で終了します。

brew upgrade の後は、新しいバージョンへ切り替えるため zanei stop && zanei start を実行してください。旧 recorder がすでに自動終了し、stop が停止中と報告した場合は、代わりに zanei start を実行してください。

アップグレード後、データはどうなりますか？

Zanei 0.3.0 以降はストアを暗号化します。0.2.x 以前が書いたストアは平文の SQLite で、recorder はこのファイルを書き換えません。アップグレード後に最初に zanei start したとき、旧ストアを store.sqlite.plaintext-<日時> という名前に変えて新しい暗号化ストア store.sqlite の隣に残し、新しい store を schema version 7 で作成して、zanei: kept the previous plaintext store as … とログに出します。zanei query・zanei timeline・zanei export・MCP サーバーのすべての読み取りは、両方のファイルのイベントを一つの履歴として返すので、アップグレード前に記録したものがタイムラインから消えることはありません。zanei status は退避したファイルを store.retired_plaintext に表示します。

退避したファイルは平文のままです。中身は退避した時点より前のイベントだけなので、その時点が保持期間（output.retention_hours、既定 48 時間）を外れた時点で recorder がファイルごと削除します。保持期間が長ければ長く残り、短ければ早く消えます。それまでの間も、保持期間を外れたイベントは稼働中のストアと同じタイミングでファイル内から削除されます。zanei pause 中であればその状態とイベント数のカウンタは新しいストアに引き継がれます。zanei purge --all はすぐに削除し、ファイルを自分で削除しても構いません。暗号化済みの 0.3.x store を 0.4.0 へ upgrade すると schema version 7 へ in-place migration し、event と daemon state を保持して、recorder が再取得できる permission snapshot だけを破棄します。

store migration は forward-only です。rollback が必要になり得る場合は upgrade 前の backup を残してください。rollback 時はその backup を restore し、schema version metadata を手作業で書き換えてはいけません。

`zanei start` で `Bootstrap failed: 5: Input/output error` が表示されます

zanei start で error: daemon operation failed: /bin/launchctl failed while attempting to bootstrap the Zanei launch agent with exit status: 5: Bootstrap failed: 5: Input/output error が表示された場合は、zanei stop を実行して完了を待ってから、改めて zanei start を実行してください。

タイムラインが空です

次の順で確認してください。

zanei status — running ですか？違うなら zanei start。
zanei doctor — 権限は揃っていますか？（権限不足は終了コード 3）
範囲は合っていますか？timeline の既定は直近 1 時間です。--since 24h を試してください。
フィルタが許可リストモードになっていませんか？zanei filter show が現在のモードを表示します。

`status` が `store_corrupt` を返します

記録を停止し、破損ファイルを別名で退避してから、新しいストアで開始します。

zanei stop
mv ~/.local/state/zanei/store.sqlite ~/.local/state/zanei/store.sqlite.corrupt
zanei start

--store を使っている場合は、そのパスに読み替えてください。退避したファイルは修復も削除もされず、新しい空のストアで記録を開始します。

store_locked は、ストアが暗号化されているのに、ログインキーチェーンの鍵が見つからないか、このストアを復号できない状態です。復旧手順は同じです。新しいストアは既存の鍵を使い、鍵がなければ新しい鍵を生成します。鍵を失って消えるデータは、最大でも保持期間（既定 48 時間）分です。メッセージがログインキーチェーンのロックを指している場合は、ストアを退避せず、キーチェーンをロック解除して（たとえばキーチェーンアクセスを開く）再試行してください。zanei doctor は Store key: 行に鍵の状態を表示します。

テキスト本文が捕捉されません

テキスト本文が記録されるのは、opt-in が有効な間だけです。zanei status を確認し、TEXT CONTENT が off なら、明示的に有効化して記録を再起動します。

zanei config set capture.text_content true
zanei stop && zanei start

0.3.0 では、upgrade 済みの config でも Safari・Firefox・Brave・Edge・Vivaldi・Arc は既定の text-content scope 外です。これらの本文 field は null のままですが、event と内容以外の事実は残ります。既定値を変える前に zanei filter show を確認してください。

Chrome の本文 field が null のままで content capture が有効な場合は、zanei doctor を実行して COLLECTOR HEALTH を確認します。現在の chrome reason は collector で進行中の問題を示しますが、COLLECTOR FAILURES だけなら累積履歴です。永続 daemon log と回復条件はrecorder の不調を診断するを参照してください。

有効なのに本文が取れない場合は、プライバシーに配慮した診断を有効にして、短時間のフォアグラウンドセッションを実行します。

zanei stop
ZANEI_TRACE=1 zanei start --foreground 2> ~/zanei-trace.log

数十秒入力してから Ctrl-C を押し、~/zanei-trace.log を確認してください。trace にテキスト本文は含まれず、フィールド種別、値の長さ、捕捉判断などの診断メタデータだけが記録されます。

その他の質問

Issue を開いてください。インターフェースを確定させている今の段階では、バグ報告も設計議論も歓迎です。