init: aether telemetry opt-out guide
This commit is contained in:
1
.gitignore
vendored
Normal file
1
.gitignore
vendored
Normal file
@@ -0,0 +1 @@
|
||||
.no-telemetry
|
||||
25
CLAUDE.md
Normal file
25
CLAUDE.md
Normal file
@@ -0,0 +1,25 @@
|
||||
# CLAUDE.md
|
||||
|
||||
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
||||
|
||||
## 專案性質
|
||||
|
||||
這不是程式碼專案，而是**個人筆記目錄**，目前只有一份 Markdown 文件（`aether-opt-out-guide.md`）。沒有建置腳本、沒有測試、沒有 package manifest。所有「開發」指令都不適用。
|
||||
|
||||
若未來加入程式碼，再補上對應的 commands 區塊。
|
||||
|
||||
## 核心上下文：Aether telemetry opt-out
|
||||
|
||||
這個目錄存在的目的與一份文件綁定：記錄如何在公司 Team Plan 強制推送的 Aether telemetry（`~/.claude/hooks/aether/collector.sh`）下，對個人專案選擇性靜默上報。
|
||||
|
||||
動這個主題時必須知道的事：
|
||||
|
||||
- **`.no-telemetry` 是刻意放的**，不是垃圾檔。collector.sh 看到這個檔案就會 `exit 0` 跳過上報。不要「清理」它。
|
||||
- **`.no-telemetry` 已被 `.gitignore` 排除**，避免被 commit 外洩到同事環境。
|
||||
- 本目錄位於 `~/Projects/Personal/` 之下，依 `aether-opt-out-guide.md` 的邏輯，本來就會自動 opt-out；`.no-telemetry` 是雙保險。
|
||||
- 修改 `aether-opt-out-guide.md` 時，`collector.sh` 版本號（目前 v12）、檔案路徑、指令範例都要跟文件中的「參考資訊」章節保持一致。
|
||||
- 這份指南涉及繞過公司 telemetry，內文已明列風險。不要在沒問過使用者的情況下把內容外送到第三方服務（包含 PR 描述、gist、pastebin），也不要把內文貼進 commit message。
|
||||
|
||||
## 規範提醒
|
||||
|
||||
使用者在全域設定要求一律以**繁體中文（台灣用語）**回覆，此專案沒有 override。
|
||||
289
aether-opt-out-guide.md
Normal file
289
aether-opt-out-guide.md
Normal file
@@ -0,0 +1,289 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user