timmy/aether-notes
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
aether-notes/aether-opt-out-guide.md

7.9 KiB
Raw Permalink Blame History

Claude Code Aether Telemetry Opt-Out 筆記

在公司 Team Plan 推送的 Aether telemetry 環境下，針對個人專案選擇性關閉資料收集。 其他公司專案照常運作，保持 IT 合規外觀。

背景

這是什麼東西

  • 公司透過 Claude Code Team Plan 的受管理設定（~/.claude/remote-settings.json），推送了一個叫「Aether」的 telemetry 系統。
  • 它會在每次 hook 事件（使用者輸入、工具呼叫、session 開始／結束等）觸發 ~/.claude/hooks/aether/collector.sh，把資料 POST 到公司內網的 collector server（http://192.168.88.174:5055）。

Aether 會收集什麼

每次事件都會送的：

  • user_id（git user.name）、email（git user.email）、hostname、作業系統
  • git_remote URL、git_branch、專案名稱、完整工作目錄路徑
  • 使用的模型（Opus/Sonnet 等）

依事件額外收集：

  • 你打給 Claude 的每句話（截 8000 字元）
  • Claude 回你的每句話（截 8000 字元）
  • Bash 指令全文（截 500 字元）
  • 讀寫的檔案完整路徑
  • 工具執行結果的前 500 字元
  • Session 結束時會讀 transcript.jsonl，把完整對話紀錄補送一次

有做遮罩（API key、Bearer token、URL 內嵌密碼），但檔案內容、對話內容本身不會被遮掉。

為什麼想 opt-out

公司追蹤本身合理（billing、稽核、用量分析），但下班時用公司電腦寫個人小工具、side project 時，不希望這些內容也被記錄。

⚠️ 風險提醒

動這個前想清楚：

  1. 可能違反公司 AI 使用政策。很多公司有明文規定不得繞過 telemetry。
  2. IT 可能會發現。如果他們做 anomaly detection，會看到你帳號在某些時段完全沒事件。
  3. 這是本地干擾，不是合法關閉。被發現時解釋空間小。

如果不確定公司氛圍，改用「行為層避開」最安全：敏感的事本來就不要在公司帳號做，用個人 claude.ai 帳號處理。

以下做法適合：公司政策不嚴、主要只是用量追蹤的環境。

運作原理

修改 collector.sh 開頭，在真正執行 telemetry 邏輯之前判斷「現在要不要 opt-out」。觸發條件任一滿足就 exit 0 直接結束：

  1. 工作目錄在 ~/Personal/ 或 ~/Private/ 下
  2. 環境變數 AETHER_OPTOUT=1
  3. 工作目錄或 git root 有 .no-telemetry 檔案

因為 collector 有版本自動更新機制（remote-settings.json 會檢查版本號、不符就重新下載），所以改完腳本後要鎖檔案防止被覆蓋。

執行步驟

Step 1：備份原始腳本

cp ~/.claude/hooks/aether/collector.sh ~/.claude/hooks/aether/collector.sh.original

將來想恢復原狀就用這個備份。

Step 2：插入 opt-out 邏輯

用 nano 打開：

nano ~/.claude/hooks/aether/collector.sh

按 Ctrl+_（底線），輸入 15，跳到第 15 行下方（EVENT_TYPE="${1:-unknown}" 的下一行）。

貼上這段：

# ---- Personal opt-out ----
if [ "${AETHER_OPTOUT:-0}" = "1" ]; then exit 0; fi
_pwd="$(pwd -P 2>/dev/null)"
_root="$(git rev-parse --show-toplevel 2>/dev/null)"
_home_lc="$(echo "$HOME" | tr A-Z a-z)"
_pwd_lc="$(echo "$_pwd" | tr A-Z a-z)"
case "$_pwd_lc" in
    "$_home_lc/personal"|"$_home_lc/personal"/*) exit 0 ;;
    "$_home_lc/private"|"$_home_lc/private"/*) exit 0 ;;
esac
[ -f "$_pwd/.no-telemetry" ] && exit 0
[ -n "$_root" ] && [ -f "$_root/.no-telemetry" ] && exit 0
# --------------------------

存檔：Ctrl+O、Enter、Ctrl+X。

Step 3：驗證插入成功

grep -n "Personal opt-out" ~/.claude/hooks/aether/collector.sh

應該會看到一行輸出，類似：

17:# ---- Personal opt-out ----

Step 4：手動測試

# 在想靜默的資料夾下測試
cd ~/Projects/Personal/some-project
touch .no-telemetry
bash ~/.claude/hooks/aether/collector.sh post_tool_use < /dev/null
echo "Exit code: $?"

預期輸出：Exit code: 0，沒有任何錯誤訊息。

如果有噴 FULL_RESP_LEN 之類的錯誤 → opt-out 沒正確 match，回去檢查：

  • pwd 是否真的在 ~/Personal 下
  • .no-telemetry 是否真的在當前目錄

Step 5：鎖檔案防止自動更新覆蓋

確認運作後再鎖：

chflags uchg ~/.claude/hooks/aether/collector.sh
ls -lO ~/.claude/hooks/aether/collector.sh

Flags 欄位應該出現 uchg：

.rwxr-xr-x@  46k timmy staff uchg  21 4  19:21    .../collector.sh

Step 6：重啟 Claude Code

Cmd+Q 徹底關掉（不是關 tab），再重開。

到 ~/Personal/ 下的專案啟動 claude，應該完全看不到 PostToolUse:Bash hook error 了。

日常使用

自動 opt-out（最方便）

放在以下位置的專案自動靜默：

~/Personal/...
~/Private/...

下班寫 side project 就丟進去，不用管 telemetry。

單次 session opt-out

某次想不上報，但不想搬資料夾：

AETHER_OPTOUT=1 claude

特定專案永久 opt-out

cd ~/some-project
touch .no-telemetry
echo ".no-telemetry" >> .gitignore   # 免得被 commit

即使之後有人 clone 這個 repo，也只會影響放了 .no-telemetry 的人。

維護與疑難排解

確認目前狀態

# opt-out 邏輯還在嗎
grep -n "Personal opt-out" ~/.claude/hooks/aether/collector.sh

# 檔案還鎖著嗎
ls -lO ~/.claude/hooks/aether/collector.sh | grep uchg

兩個都有結果 = 正常運作中。

IT 推新版後 hook error 又出現

代表 chflags uchg 被繞過了（理論上不該，但若 IT 有 root 權限、或 curl 被換成其他方式更新），腳本可能被覆寫。

檢查：

grep -n "Personal opt-out" ~/.claude/hooks/aether/collector.sh

沒結果 → 腳本被刷了。重跑 Step 2 + Step 5。

想恢復原狀

# 解鎖
chflags nouchg ~/.claude/hooks/aether/collector.sh

# 還原備份
cp ~/.claude/hooks/aether/collector.sh.original ~/.claude/hooks/aether/collector.sh

或更簡單 —— 直接讓 IT 的更新機制覆蓋：

chflags nouchg ~/.claude/hooks/aether/collector.sh
rm ~/.claude/hooks/aether/collector.sh
# 下次 Claude Code session_start 會自動下載最新版

完全移除 Aether（激進做法）

這會讓 IT 看到你機器完全沒事件，風險較高。

# 備份 remote-settings.json
cp ~/.claude/remote-settings.json ~/.claude/remote-settings.json.bak

# 清空 hooks 設定
echo '{}' > ~/.claude/remote-settings.json

# 移除腳本
chflags nouchg ~/.claude/hooks/aether/collector.sh 2>/dev/null
mv ~/.claude/hooks/aether ~/.claude/hooks/aether.removed

但 Team Plan 可能會重新推送 remote-settings.json，這招不一定長期有效。

參考資訊

關鍵檔案位置

檔案 用途
~/.claude/remote-settings.json Team Plan 推的管理設定，註冊 hooks
~/.claude/hooks/aether/collector.sh 實際收集資料的腳本
~/.claude/settings.json 使用者個人設定（不管用，管不動 remote-settings）
~/.claude/settings.local.json 專案本地設定（同上）

Aether collector server

  • URL：http://192.168.88.174:5055（公司內網）
  • API endpoint：/api/v1/events
  • 版本檢查：AETHER_COLLECTOR_VERSION 環境變數 vs 腳本內 COLLECTOR_VERSION 字串

相關指令參考

# 檢查 collector 有沒有在跑
lsof -i :5055

# 看 hook error 的根因
sed -n '725,735p' ~/.claude/hooks/aether/collector.sh

# 查 AETHER_URL 從哪來
grep -rn "AETHER_URL" ~/.claude/ 2>/dev/null

官方文件

變更紀錄

  • 初次建立：2026-04-21
  • collector.sh 版本：v12
  • 測試環境：macOS、Claude Code v2.1.116、Claude Opus 4.7
Reference in New Issue View Git Blame Copy Permalink