290 lines
7.9 KiB
Markdown
290 lines
7.9 KiB
Markdown
# 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：備份原始腳本
|
||
|
||
```bash
|
||
cp ~/.claude/hooks/aether/collector.sh ~/.claude/hooks/aether/collector.sh.original
|
||
```
|
||
|
||
將來想恢復原狀就用這個備份。
|
||
|
||
### Step 2：插入 opt-out 邏輯
|
||
|
||
用 `nano` 打開：
|
||
|
||
```bash
|
||
nano ~/.claude/hooks/aether/collector.sh
|
||
```
|
||
|
||
按 `Ctrl+_`（底線），輸入 `15`，跳到第 15 行下方（`EVENT_TYPE="${1:-unknown}"` 的下一行）。
|
||
|
||
貼上這段：
|
||
|
||
```bash
|
||
# ---- 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：驗證插入成功
|
||
|
||
```bash
|
||
grep -n "Personal opt-out" ~/.claude/hooks/aether/collector.sh
|
||
```
|
||
|
||
應該會看到一行輸出，類似：
|
||
```
|
||
17:# ---- Personal opt-out ----
|
||
```
|
||
|
||
### Step 4：手動測試
|
||
|
||
```bash
|
||
# 在想靜默的資料夾下測試
|
||
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：鎖檔案防止自動更新覆蓋
|
||
|
||
確認運作後再鎖：
|
||
|
||
```bash
|
||
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
|
||
|
||
某次想不上報，但不想搬資料夾：
|
||
|
||
```bash
|
||
AETHER_OPTOUT=1 claude
|
||
```
|
||
|
||
### 特定專案永久 opt-out
|
||
|
||
```bash
|
||
cd ~/some-project
|
||
touch .no-telemetry
|
||
echo ".no-telemetry" >> .gitignore # 免得被 commit
|
||
```
|
||
|
||
即使之後有人 clone 這個 repo，也只會影響放了 `.no-telemetry` 的人。
|
||
|
||
---
|
||
|
||
## 維護與疑難排解
|
||
|
||
### 確認目前狀態
|
||
|
||
```bash
|
||
# 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 被換成其他方式更新），腳本可能被覆寫。
|
||
|
||
檢查：
|
||
```bash
|
||
grep -n "Personal opt-out" ~/.claude/hooks/aether/collector.sh
|
||
```
|
||
|
||
沒結果 → 腳本被刷了。重跑 Step 2 + Step 5。
|
||
|
||
### 想恢復原狀
|
||
|
||
```bash
|
||
# 解鎖
|
||
chflags nouchg ~/.claude/hooks/aether/collector.sh
|
||
|
||
# 還原備份
|
||
cp ~/.claude/hooks/aether/collector.sh.original ~/.claude/hooks/aether/collector.sh
|
||
```
|
||
|
||
或更簡單 —— 直接讓 IT 的更新機制覆蓋：
|
||
```bash
|
||
chflags nouchg ~/.claude/hooks/aether/collector.sh
|
||
rm ~/.claude/hooks/aether/collector.sh
|
||
# 下次 Claude Code session_start 會自動下載最新版
|
||
```
|
||
|
||
### 完全移除 Aether（激進做法）
|
||
|
||
> 這會讓 IT 看到你機器完全沒事件，風險較高。
|
||
|
||
```bash
|
||
# 備份 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` 字串
|
||
|
||
### 相關指令參考
|
||
|
||
```bash
|
||
# 檢查 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
|
||
```
|
||
|
||
### 官方文件
|
||
|
||
- Claude Code Hooks 參考：<https://code.claude.com/docs/zh-TW/hooks>
|
||
- `disableAllHooks` 無法關掉受管理的 hooks（本身就是本筆記存在的原因）
|
||
|
||
---
|
||
|
||
## 變更紀錄
|
||
|
||
- 初次建立：2026-04-21
|
||
- collector.sh 版本：v12
|
||
- 測試環境：macOS、Claude Code v2.1.116、Claude Opus 4.7
|