---
title: "給 Mac 應用補遙測能力"
description: "基於官方 Codex macOS telemetry 場景教程，面向新手講清什麼時候加 OSLog、怎麼控制範圍、怎麼從日誌證明問題。"
verifiedAt: "2026-05-06"
---

import { Cards, Card } from 'fumadocs-ui/components/card';

Mac app 裡很多問題只看程式碼很難判斷。“something happened” 這種描述太模糊。更穩的做法是讓 Codex 給一個具體 feature 加少量高訊號 unified logs，然後執行 app、觸發路徑、從 Console 或 `log stream` 驗證事件是否按預期出現。

這類任務的重點不是“加幾行 Logger”，而是建立可觀察性：讓你知道某個 action boundary 或 state transition 真的發生了。

> [!WARNING]
> Telemetry 不是把使用者行為全部打出來。只記錄高訊號邊界，避免 secrets、token、個人資料和原始文件內容，並在交付時說明 filter 或 predicate。

## 先理解：什麼時候該加 telemetry

適合加 telemetry 的場景包括 window opening、sidebar selection、menu commands、sync flows、匯入流程、fallback path、間歇性 bug。

這些問題通常不是程式碼一眼能看出來，而是需要知道使用者動作、狀態變化和生命週期事件的順序。

不適合一上來全域性加日誌。整庫一牆 log 會製造噪音，也會增加隱私風險。

## 怎麼判斷範圍

一次只 instrument 一個 feature。比如一個 sidebar、一個 window、一個 command、一個 sync path。

只記錄重要邊界：開始、結束、失敗、fallback、狀態切換。

長期保留的 `info` logs 要穩定、高訊號；臨時除錯細節用 `debug`，完成前移除或降低階別。

不要記錄 secrets、auth tokens、personal data 或 raw document contents。需要記錄 identifier 時，使用最安全的 privacy annotation，並說明原因。

## 為什麼用 OSLog Logger

macOS unified logging 能按 subsystem 和 category 過濾，也能和 Console.app、`log stream` 配合。

相比 `print`，`Logger` 更適合長期診斷，因為它能表達 category、privacy、level，並且能在系統工具裡過濾。

新手不要把 telemetry 做成隨手 print。那會汙染輸出，也不適合定位間歇性問題。

## Codex 應該怎麼做

先找目標 feature 的真實 control path，不要盲目在外圍加 log。

再為這個 feature 選擇清楚的 subsystem 和 category。

然後新增少量事件，執行 app，觸發路徑，用 Console filter 或 `log stream` predicate 證明事件出現。

如果預期事件沒出現，說明 log 放錯位置或路徑沒走到。讓 Codex 把 log 移到更接近可疑 control path 的位置，而不是繼續猜。

## 長流程怎麼處理

對長流程或間歇性 bug，可以讓 Codex 儲存一個聚焦的小型 trace file。你手動復現，Codex 讀取 trace，再整理 timeline。

這種方式比讓 Codex 猜 UI 狀態可靠，也比把全部系統日誌交給它更安全。

## 新手常見坑

- 一次給全專案加日誌：噪音比資訊多。
- 用 `print` 代替 unified logging。
- 記錄使用者內容、token、document raw text。
- 只寫 Logger，不執行 app 驗證。
- 只給代表性 log line，不給 filter 或 predicate。
- event 沒出現時繼續改業務程式碼，而不是先移動 instrumentation。

## 怎麼驗收

最終交付應說明新增了哪個 logger setup，哪些 events 被記錄，為什麼這些 events 足夠解釋目標 flow。

應提供使用的 Console filter 或 `log stream` predicate。

應說明實際執行 app 後是否看到了預期事件順序。

如果儲存了 trace file，應給出 timeline summary。

如果無法復現，應說明已確認事實、未確認假設和下一步最小驗證。

## 官方資料

- [Codex macOS telemetry logs use case](https://developers.openai.com/codex/use-cases/macos-telemetry-logs)
- [Build macOS Apps plugin](https://github.com/openai/plugins/tree/main/plugins/build-macos-apps)
- [Agent skills](https://developers.openai.com/codex/skills)
- [Apple OSLog Logger](https://developer.apple.com/documentation/os/logger)

## 接下來去哪

<Cards>
  <Card title="構建 macOS 應用" description="需要從 app shell、build、run 和 debug 建立更完整的 macOS 工作流。" href="/zh-Hant/docs/codex/official/08-scenarios/110-macos-app" />
  <Card title="Mac App 基礎殼" description="如果還沒有清晰結構，先建立 sidebar、detail 和 inspector 基礎形態。" href="/zh-Hant/docs/codex/official/08-scenarios/105-mac-app-skeleton" />
  <Card title="Computer Use QA" description="需要透過 GUI 觸發流程和收集證據時，看 Computer Use 驗收場景。" href="/zh-Hant/docs/codex/official/08-scenarios/113-computer-use-qa" />
  <Card title="官方 telemetry use case" description="最新外掛和 OSLog 場景說明以官方頁面為準。" href="https://developers.openai.com/codex/use-cases/macos-telemetry-logs" />
</Cards>
