# 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