【2026 最新】openskycam 教學：Claude Code 如何管理天空相機？七步驗收本機偵測與成本

你把相機朝向夜空，希望早上醒來就能看到昨晚飛過的東西。這篇 openskycam 教學先回答一個容易混淆的問題：全天錄影，是否等於 Claude 必須全天逐張看圖、持續消耗 Token？先把錄影、本機偵測與 Agent 操作拆開，才能算出真正的帳。

本文寫給第一次接觸天空攝影系統、願意照著終端機操作的讀者。你會學會盤點設備、接通 MCP、用十分鐘素材驗收，再安排一晚的增量處理。需要相機、自有主機及 Cloudflare 帳號；若還沒備齊，也能先完成容量與驗收規格。

接下來會帶你從設備盤點走到一晚驗收，並用自己的原始錄影核對偵測與覆核是否可靠。容量以明列假設計算；先把成功條件寫清楚，再開始部署。

先說結論：天空相機＝錄影管線＋本機偵測＋按需操作

相機負責看，YOLO 負責找，Claude 負責調度。把它想成倉庫：相機不斷收貨，偵測器把可疑包裹挑出來，Agent 幫你查庫存與安排工作。你請管理員做幾件事，與倉庫全天收了多少貨，是兩本不同的帳。

• 先確認錄影真的持續到達自有硬碟，再評估偵測結果。
• 先測十分鐘，確認抽樣、模型、輸出與覆核都通，再擴成一晚。
• 先用本機模型篩選；需要 Claude 看候選畫面時，再記錄那次模型用量。

一、openskycam 教學先拆開五個零件

RTSP 是相機傳送即時影音的協定，可以把它理解為一條持續流動的影片水管。依 官方架構說明，Linux relay 將串流分段，經 ingest Worker 與 Tunnel 送到自有硬碟；另一個 processor 讀取錄影，抽樣並執行 YOLO 偵測。YOLO 是找出影像中物件與位置的視覺模型，並非語言模型逐字生成答案。

• 相機：提供 H.264／H.265 RTSP 影像；先確認鏡頭、夜間曝光和實際碼率。
• Relay「搬運工」：靠近相機的 Linux 主機，分段錄影並上傳。
• Footage store「倉庫」：macOS／Linux 主機加大硬碟，保存與提供影片。
• Processor「分揀員」：自有 macOS／Linux 主機，解碼、偵測、追蹤並上傳候選影像；可與儲存主機合併。
• Cloudflare 與 MCP「櫃台」：網站、目錄及 API 接受查詢與排程。MCP 是讓 AI 使用外部工具的連接標準；Claude Code 經它操作系統。

「本機偵測」描述的是模型執行位置，不代表整套系統與外網隔離。processor 文件說明它會經 HTTPS 取得工作、下載輸入並回傳結果。若你把候選畫面交給雲端 Claude 解讀，該畫面又多了一條送往模型服務的路徑。先只拍自己的天空範圍，避開鄰居窗戶與可識別人員。

二、先盤點與算容量，再執行部署

第一個痛點是「軟體下載好了，硬碟隔天就滿」。先盤點三種主機角色與網路：對照 官方需求清單，準備相機位址與帳密、Linux relay、儲存與處理主機的 SSH 金鑰登入，以及 Cloudflare 帳號和已接管的網域。開發端需要 Node.js 24；儲存程式與 processor 的 Python 最低版本也不同，逐項核對，別只裝一套後猜測。

碼率是每秒流過多少資料，不是解析度。以固定 4 Mbps、連續 24 小時作算術示例，影片有效負載約為每日 43.2 GB；這裡 GB 採十進位。下圖把預設儲存保留期與空間門檻一起算進去，另須容納檔案系統、縮圖、模型與工作結果。

儲存文件說明，硬碟未掛載時會拒絕上傳，低空間清理則可能刪掉未滿保留期的舊時段。因此「設定保留幾天」不是每段影片都能存到那天的保證。也別為省空間只改 store 保留期：文件要求它高於目錄的保留天數，否則網站可能還列著已不存在的檔案。

第二個痛點是一次裝太多，出錯不知道在哪。照官方分段檢查，在新的私人工作目錄執行下列起步指令；npm install 會安裝專案依賴。這不是把相機功能裝進目前正在工作的其他專案。

git clone https://github.com/Deibler/openskycam.git
cd openskycam
git rev-parse HEAD
cp .env.example .env
npm install
npm run setup

把 git rev-parse HEAD 的輸出留在自己的部署紀錄，並依 官方部署步驟完成設定。精靈會處理可自動化的工作；Cloudflare 首次登入、Tunnel／Access／API 主機規則，以及網站 API key，仍有需要你在已登入介面完成的步驟。相機密碼與金鑰放在私人設定，別貼進公開 issue 或截圖。

部署後在同一目錄執行 npm run setup -- --check。它檢查部署步驟，不修改設定；失敗時先修那一層。若調整過程式，另執行官方的 make check。再在網站挑一段影片，確認可播放、時間正確、儲存磁碟有新增檔案。驗收標準是「資料到了、能讀回」，而不只是終端機印出完成。

三、接上 MCP：先查健康，再取一張畫面

第三個痛點是把「可以連線」當成「權限很小」。先限定相機與期限：在網站 API access 建立 Purpose 為 Agent: MCP and full API 的專用 key，複製介面產生的 Claude Code 連線指令到自己的終端機。這個指令含秘密，不要截圖分享；其結構如下，範例中的位址與 key 必須替換。

claude mcp add --transport http openskycam https://YOUR-API-HOST/v1/mcp \
  --header "Authorization: Bearer YOUR-AGENT-KEY" --scope user

API 權限文件把 footage:read 與 agent 分開：MCP 使用 Agent key，並非唯讀 key。限定攝影機與到期日能縮小範圍；在提示裡寫「只查詢」並不會把它變成伺服器強制唯讀。這與 Agent 權限閘門談的批准邊界是同一個原則。

重新啟動 Claude Code，讓新連線載入，再請它依 MCP 工具說明執行下面的窄任務。footage cameras 這類文字是工具與 action 的稱呼，不是要在 shell 直接輸入的命令。

先讀 guide 的 overview、footage 與 runs。
只查詢，不建立、修改、刪除或啟動工作。
用 footage cameras、days、list，及 runs runtimes，
回報指定相機的最近錄影時間、可用日期、目錄所記錄的儲存總量與 processor 最近回報時間。
footage list 若有 next_cursor，讀完分頁再判斷缺口。
保留 UTC 時間與查到的識別碼；查不到就說缺什麼。

接著挑一段已存在的錄影，明確允許用 footage photo 取一個 UTC 時刻的畫面。依 取圖機制，這會建立單幀暫存工作、需要 processor，不能把它當成純查目錄。核對畫面內容與時間；只看到工具連上、卻取不到圖，仍需查 processor、縮圖及原片是否可讀。

四、十分鐘驗收：先讓一條短管線完整走通

第四個痛點是直接選「昨晚全部」，工作卻遭拒。先縮到十分鐘：挑同一 UTC 日期中已有錄影的時段，例如 02:00–02:10；這只是格式示例，請換成你的素材。網站用 UTC，先把當地夜間換算成 UTC；跨 UTC 午夜時拆成兩個日期窗口。

新部署先看 模型登錄說明，把模型補齊。若清單為空，可使用 repository 隨附的夜間 detector：在網站另建 Publish trained models key，存到只有自己可讀的私人檔案；下例需要 Python 3.11 以上，請替換 API 位址及金鑰檔案路徑。

python3 -m venv .venv-publish
.venv-publish/bin/pip install ./processor
chmod 600 /absolute/private/publish.key
.venv-publish/bin/skyvision-processor publish-model \
  --base-url https://YOUR-API-HOST \
  --key-file /absolute/private/publish.key \
  --metadata models/night-detector/model.json \
  --artifact models/night-detector/night-yolo26s-1920.pt

依 官方模型卡，這組權重來自單一場址的夜間素材，採 AGPL-3.0，與其餘程式碼的 MIT 授權分開。它的類別有 Plane 與 Meteorite；請保留這些精確名稱，但不要把後者的標籤直接當作隕石落地證據。發布後用 models list 確認 workflow_ready: true。

在 Workshop 建立專用輸出 bucket，再建立流程：Camera archive → 抽樣 → 已登錄的偵測模型 → 條件 → 輸出。從 models list 選自己已安裝的模型，記下 model key、權重版本與類別名稱，別把文件的示例名稱當作自己已有的模型。每個條件的 yes／no 都接到明確輸出或 Do nothing。

這一輪先用每五秒一張的抽樣設定，不加移動判斷，以便排查。十分鐘約有 120 個抽樣位置；先用 runs test 測 20 張並追蹤完成。官方 Runs 文件明確區分：test 是限量預覽，結果不能直接覆核或凍結成資料集；要驗收人工標記，還需執行一次短時段 full run，將結果存進 bucket。

請 Agent 先執行 workflows check，讀回設定，再測試、追蹤並回報 run ID、預期與完成張數、錯誤及輸出位置。測試通過後，才授權那個十分鐘窗口的 full run。抽樣間隔會影響能否看到短暫事件；這一輪只是驗接線，正式驗漏報時仍須回看原始影片。

五、擴成一晚：增量排程與人工覆核分開驗

第五個痛點是小測試成功，整晚卻超出單次上限。官方夜間範例使用 arrival，也就是「新錄影到達時」增量觸發。它每十五分鐘檢查新上傳資料；初次則會取窗口內已有素材。在夜間窗口開始前加入排程，避免第一次就吃到累積數小時的資料。

截至 2026 年 10 月 31 日的官方文件，單次 full run 最多處理 100 段錄影、2,000 個抽樣位置。假設每段一分鐘，八小時就是 480 段；只把抽樣調稀，仍解決不了錄影段數上限。增量處理也要監看上傳延遲與積壓，不能把它當作永遠不會超限的保證。arrival 的日期使用 run-day，窗口結束不得晚於 23:35 UTC；其餘時段照官方範例分窗後再 check。

需要排除固定亮點時，再加追蹤與 motion 條件。它是把同一物件跨幀連成軌跡，再分 moving、stationary 或 brief；須使用具備 tracking 能力的 runtime。不要把 stationary 直接等同星星，也不要把模型框出的類別當成天文鑑定。先查看幾段原片，再決定要保留哪些候選。

人工覆核請先訂規則：確認目標、錯誤類別、純誤報，以及畫面不足以判斷。依 Buckets 與資料集文件在 review 介面接受、拒絕或修正類別與框，必要時保留原片。相鄰畫面裡同一架飛機連出十張，應另外記為一個事件，避免把十張圖誤算成十次獨立發現。

把調整用的一晚與驗收用的另一晚分開。這是本文建議的評估設計：先用第一晚改閾值、標註或訓練，再鎖住模型、抽樣與規則，用沒參與調整的第二晚驗收。同一事件的相鄰幀不要分到兩邊。官方資料集依攝影機與 UTC 日期分組；小資料集仍要核對實際 split，確保驗收夜晚沒有進入調整流程。凍結 version 也不會延長影像壽命；長留圖片先 Save，原始錄影則另行保存。

驗收時留三種分母：錄影是否完整、候選裡多少是真目標，以及原片中人工找到的目標有多少被漏掉。只審候選圖，可以估候選正確比例，卻看不到完全沒被選出的事件。若只抽查部分原片，就把漏報觀察限定在那些時段；光害、雲層與不同鏡頭另分組記錄。

六、openskycam 教學成本帳：Token 只是其中一欄

第六個痛點是只問「一晚幾個 Token」。改記四本帳：硬體與用電、儲存與網路、Cloudflare 使用量、模型與人工覆核。YOLO 在本機跑的時間，與 Claude 收到多少提示、工具結果和圖片，是不同的計量單位。另接小型本機視覺模型逐張覆核時，也要另量延遲、記憶體、誤判與新增維護工時。

• 硬體／電力：記設備成本、預期使用月數、平均功耗與開機時數；電費用你的每度價格重算。
• 影片／網路：用實際檔案量校正碼率估算；relay 上傳、store 接收、processor 讀取與遠端播放各看自己的網路帳。
• 雲端：Workers 請求與 CPU、D1 讀寫／容量、R2 模型與候選影像，以及即時進度用的 Durable Objects 分開看。原始影片在自有硬碟，不應拿整晚影片量直接算成 R2 用量。
• 模型／人工：記 Claude 每次任務與圖像覆核用量，再記審圖分鐘數、返工與待確認事件。

雲端先看 Workers、D1 與 R2 價目及計量方式，不要從「有免費額度」推導整套永遠免費。帳號內其他專案也可能共用額度；本篇不把作者單一相機的用量當作你的帳單。

Claude 這一欄，依 官方成本文件先查登入計費方式，再用 /usage 保留任務前後的 Session 累計讀數並取差額。API 記一般輸入、輸出、快取寫入與快取讀取，按 對應模型價目各自計算；訂閱方案的用量條則另記，不能把本機美元估算直接當成加收費用。最有效的起點，是限制送入模型的候選張數與工具回傳量，再比較完成一次有效覆核花了多少。

紙上練習：假設一晚有 100 個候選事件，每個人工看 12 秒，單純審圖就是 20 分鐘，尚未含回放與改標。這是假設乘法，不是本次量到的速度。將它換成自己的實際分鐘數；若降低閾值多抓到目標，卻讓待審工作堆積，也要把這個代價算進去。

七、停止也要驗收：排程、工作、錄影與金鑰各有開關

最後一個痛點是關掉 Claude 視窗，誤以為所有工作已停止。先移除該 workflow 的 schedule 節點與它到 input 的連線，再儲存、讀回，再用 runs schedules 查排程、runs cancel 取消尚在排隊或執行的 run，檢查後續沒有新排程啟動。這個移除方法由官方節點與版本修訂機制推導；修改前先 get 目前 revision，保存後再 get 核對。依 取消工作規則，已完成的結果會保留；processor 會在後續 heartbeat 或上傳時發現租約失效並停下，這不等於撤回已產生的結果。

若要停止收片，另外停止 relay 的錄影與上傳服務，確認新片不再到達；需要斷開處理主機時，另停 processor。在 Claude Code 執行 claude mcp remove openskycam --scope user，只是拆掉上述 user 範圍的連線設定。到網站 API access 撤銷測試用 Agent key，並驗證它再連線被拒絕；若也停用 processor，另處理它自己的 Workshop key。撤銷 Agent key 不會自動撤銷其他角色的憑證。

# 在 relay 主機執行，停止錄影與上傳並停用自動啟動
systemctl --user disable --now skyvision-record skyvision-upload
# 預期顯示 inactive；非零退出碼亦是停止狀態的回報
systemctl --user is-active skyvision-record skyvision-upload

服務名稱取自 官方 relay 部署腳本；停止後另核對最近錄影時間不再前進。只停 relay 仍不會清掉既有排程或磁碟內容。

常見問題：八個先講答案的判讀

1. openskycam 就是 Claude 全天看攝影機嗎？

不是這個分工。錄影與本機偵測由管線執行；Claude 按你交代的操作使用 MCP。若另外安排逐圖 LLM 覆核，那是新增的模型工作。

2. 任何 RTSP 相機都能調整曝光設定嗎？

先分開錄影與控制。官方需求接受相容影音串流；另外的 camera_mcp.py 則針對 Dahua HTTP API，不能從錄得到影像推論其他品牌的控制也相容。

3. MCP 連上，就算唯讀嗎？

不算。這裡用的是可操作系統的 Agent key；先限相機與期限，再限制允許的工具動作。

4. test 的預覽可以直接拿去訓練嗎？

不能沿用那批 test 預覽做覆核與凍結。先做短 full run，讓結果進 bucket，再按資料集流程整理。

5. 只檢查偵測到的圖，能知道漏掉多少嗎？

還不夠。必須另外回看原片，找候選清單之外的目標；只抽看部分時段，就保留抽查範圍。

6. 網路斷線後影片一定完整嗎？

要查積壓與磁碟。relay 有暫存與重試，但空間保護可能清掉舊積壓；恢復後逐段核對缺口，別只看最新上傳時間。

7. 換一本機視覺模型覆核就一定省錢嗎？

不一定。雲端用量可能改變，但自有算力、誤判、人工與維護也要一起量。先拿相同獨立夜晚比較。

8. 第一晚應該交出什麼成果？

一份有 UTC 起訖、錄影缺口、模型／規則版本、候選覆核、原片抽查、用量與停止結果的紀錄。先讓一晚可對帳，再談擴充。

給新手的三個重點

• 先驗錄影完整，再驗模型選出的候選；兩者合格條件不同。
• 先用十分鐘完成測試與 full run，再在空窗口啟用夜間增量排程。
• 先留另一晚當考卷，將漏報、人工時間與總成本放在同一份驗收紀錄。