DuDuClaw OS 值班機

接上電源和一條網路線，一台小主機就會變成一個無頭（headless）AI 員工：兩分鐘內，儀表板就能在你的區網裡打開，不需要接螢幕或鍵盤。

這是什麼

DuDuClaw 平常是裝在你自己管理的機器上跑的一個二進位檔。值班機站在光譜的另一端：一份可開機的磁碟映像，把一台現成的小型迷你主機變成一台專屬打造的 DuDuClaw 機器。不必設定作業系統，不必安裝相依套件，也不必打開終端機，開機就直接進 DuDuClaw，然後一直待在那裡。開機之後的一切都在瀏覽器裡完成，而且只在你自己的區網上。

它服務的對象跟 DuDuClaw 其他部分一樣：想要一個 AI 員工全天候盯著 Telegram/LINE/Discord/Slack，卻不想撥一台筆電專門給它用，也不想把帳號憑證交給第三方保管的人。

從開機到就緒

安裝。 每個 release 針對每種機型都提供兩種形式。live 安裝器 ISO：燒錄到隨身碟（或燒成光碟），用 UEFI 模式開機，並把 Secure Boot 關閉（已發布的映像沒有經過 Secure Boot 簽署，詳見下方〈版本與桌面〉與信任鏈的說明），在圖形化安裝器裡選擇內建 SSD，然後重開機進入已安裝的系統。整碟映像（.wic.zst）跳過安裝器：解壓縮後直接寫入目標磁碟。透過通路購買、出貨前硬碟已經預先燒錄好的機型，可以完全略過這一步。
首次開機。 機器會先透過 NTP 校時、設定預設時區，這一步排在碰網路之前完成（時鐘不準會讓 OAuth 和 TLS 悄悄壞掉，所以放在最前面），接著透過有線 DHCP 拿到位址，並在區網上以 duduclaw.local 這個名稱宣告自己。儀表板會綁定在你的本地網路上（不限於機器本身），但防火牆只放行儀表板連接埠與探索協定；機器上其他所有東西都連不到，預設也絕不會暴露在公開網際網路上。
連線。 用同一個網路裡的任何一台 Mac、iPhone 或 Windows 機器打開 http://duduclaw.local。Android 沒辦法解析 .local 位址，所以機器另外提供一個小型的輔助探索頁面，直接顯示它的位址。設定完成前誰先連上，誰就負責完成設定，這跟其他自架值班機一樣，遵循先到先得的慣例。
設定一個管理員帳號，接著選擇語言、確認時區。
連接模型帳號與聊天通道。 設定精靈會在機器上執行 claude setup-token，顯示一個連結（附 QR code），你在自己的瀏覽器裡核准後把短碼貼回來，機器會在存下任何東西之前先真的打一次 API，確保失效或過期的 token 不會被誤判成可用。開始之前，精靈會先顯示訂閱帳號的風險說明，要你勾選同意：Anthropic 的規範不允許第三方產品收集或保存 Claude.ai 憑證，也不允許用 Free/Pro/Max 方案的憑證替使用者轉送請求，而且可能不經通知就執行。直接貼 API key 也行，完全不用走 OAuth，這也是 Anthropic 為產品記載的做法。聊天通道方面：Telegram、Discord、Slack 和網頁聊天都是直接對外連線，貼上 token 就好。LINE 跟其他 webhook 型的通道，在一台躲在家用路由器 NAT 後面的機器上收不到任何東西，所以這些通道要透過官方中繼服務轉送；中繼服務只轉送機器自己主動開啟那條連線上的不透明位元組，每個進來的 webhook 真正的簽章檢查仍然在機器本地執行，不在中繼服務裡（詳見下方〈安全設計〉）。
挑一個產業範本，這會建立你的第一個 AI 員工，接著在剛剛連好的通道上傳一則測試訊息。收到回覆才代表機器整條路徑真的跑得通，而非只有儀表板打開而已。
待命。 到這裡機器就只是持續運作。systemd watchdog 會重啟卡死的 gateway 行程，連續開機失敗時會自動退回前一個作業系統版本，不會卡在那裡。

裝置頁面

值班機安裝會多一個裝置頁面，只有值班機看得到：一般桌面版或伺服器版安裝在導覽列裡完全看不到這個項目，而且這個頁面本身在非值班機環境下會拒絕渲染，不會顯示出誤導性的內容。

狀態：即時的 CPU/記憶體/硬碟/溫度/網路快照。
更新中心：作業系統本身的更新跟 DuDuClaw 應用程式是分開的，走 A/B 分割方案：套用更新後，如果機器開機失敗，會自動退回先前跑的版本。使用者主動要求的一鍵回滾（相對於失敗時自動觸發的那種）目前刻意標示為尚未提供，而不是隨口保證：底層的更新工具本身沒有內建的「undo」指令，在不確定機制的情況下亂選開機槽位，可能會把一台沒接螢幕、沒辦法現場除錯的機器直接弄成磚。
網路：目前只是唯讀檢視機器的網路介面；從儀表板編輯靜態 IP 這個功能還沒接上。
備份：把機器學到、存下的所有東西（agent 記憶、對話紀錄、設定）打包成一個可以下載的檔案。
危險區：恢復原廠設定（需要打字輸入「RESET」確認，不能只按一個按鈕）、重新啟動、關機，各自都有自己的確認關卡。

這頁上的每一項也都有另外兩個入口：AI 員工可以當成工具呼叫，操作者也可以在機器自己的終端機下指令。三條路走的是同一份實作（crates/duduclaw-gateway/src/os_ops.rs），所以答案不會因為你從哪個門進來而不同；只有權限檢查不一樣，因為每個門認人的方式本來就不同。細節見 33-os-native-perception.md。

版本與桌面

DuDuClaw OS 的每一份映像開機後都會進入 DuDuClaw 自己的桌面：一套自有的 compositor 與 shell，附鎖定畫面、首次啟動精靈，還有一個能從任何 app 把工作交給 AI 員工的 Cmd+K 快捷列。人與 AI 共用同一台機器，compositor 保證人永遠贏得輸入權：只要碰鍵盤或滑鼠，AI 當下在畫面上操作的一切就會立刻凍結。這套機制實際怎麼運作、AI 在你的桌面上可以做什麼、不可以做什麼，另有專文說明： 52-desktop-edition.md。

每個 release 會發布兩份映像，差別在於桌面之上疊了什麼：

映像	是什麼	出貨形式
桌面版（`duduclaw-image-appliance`）	完整機器：桌面加上離線預載的 Chromium／LibreOffice（Steam 從 Flathub 安裝）、app 相容層（Bottles、Windows VM、Waydroid）、唯讀 root、防火牆、首次開機 provision，以及登入硬化。	整碟 `.wic.zst`，以及自己的 live 安裝器 ISO（`installer-desktop`，自 v0.1.0（2026-09-04）起出貨）。
基礎版（`duduclaw-image-ab`）	同樣的 A/B 架構、桌面殼層與 gateway，但沒有 app 相容層或唯讀 root（防火牆從 v0.4.0 起與桌面版相同，v0.3.0 以前沒有）。是一份 bring-up 產物，而非產品。	純安裝器 ISO（`installer`）打包的內容。

沒接螢幕時桌面會怎麼表現，例如是否會退回成純儀表板的無頭模式，這件事還沒有在真實硬體上定案，仍是一個待解的 bring-up 項目。上面說明的「儀表板在區網上打開」這條路徑，不管有沒有接螢幕都一樣能用，因為服務它的是 gateway，不是桌面。

安全設計

需要 root 的操作走一個指令清單固定的小 helper。 需要 root 權限的操作（重開機、關機、套用或回滾 OS 更新、恢復原廠設定、網路與時間設定）交給獨立的 helper duduclaw-sysd 處理。它只透過本機 Unix socket 接受 20 個固定指令（平台 v1.74.0 以前是 18 個），動手之前先檢查呼叫端的使用者 id；沒有設定允許的呼叫端時，所有請求一律拒絕。從 DuDuClaw OS v0.4.0（內嵌平台 v1.73.4）起， gateway 以自己的非 root 帳號（duduclaw，uid 1000）執行，helper 只接受 gateway 主行程的請求，安裝 OS 更新前自己驗證簽章、雜湊與版本，也拒絕回滾到比 v0.4.0 舊的映像。AI 員工和 gateway 是同一個帳號，所以這擋住的是員工拿到 root，擋不住員工使用 gateway 本身的權力（見安全防禦）。v0.3.0 以前的映像，gateway 仍以 root 執行、helper 也接受 root，這層拆分在那些映像上還沒有真正限制 gateway 能做的事。
預設擋掉連入連線，SSH 預設關閉。 從 DuDuClaw OS v0.4.0 起，桌面版和基礎版（用一般 installer ISO 寫入）都有防火牆，只放行儀表板連接埠（18789）、本地網路探索用的 mDNS（UDP 5353），以及 ping 之類的基本 ICMP，其餘連入一律丟棄。映像裡有 dropbear SSH 伺服器，但預設不啟用。儀表板維護模式裡的 SSH 開關（平台 v1.73.3 以上；v0.4.0 內嵌 v1.73.4）由 duduclaw-sysd 啟動 dropbear.socket，並把 22 埠加進防火牆的 maintenance_tcp_ports 集合；維護視窗關閉時停掉 dropbear、結束所有連線行程並移除 22 埠。目前映像上還沒有能經由 SSH 登入的帳號（root 已鎖定，dropbear 也禁止 root 登入），所以這個開關目前只能控制連接埠。尚未發版的平台程式碼（CHANGELOG [Unreleased]）加入維修登入的 helper 端：專用帳號 duduclaw-maint（uid 4800）加上每個視窗一把公鑰，由 helper 檢查、安裝，視窗關閉時移除，並有自己的期限與稽核檔（見安全防禦）。要等 OS 映像帶上這個帳號才會生效；在那樣的映像上，helper 會拒絕舊的只開埠開關。尚未發版的 gateway 端在同一個請求裡收技術人員的公開金鑰、輸入確認字與重新輸入的密碼（連續錯 5 次會鎖 15 分鐘），先記下視窗再請 helper 開啟，且不會退回只開埠：在 v0.4.0 以前或只更新一部分的映像上，SSH 選項會顯示為不支援。gateway 啟動時另開一個背景工作，負責到期關閉、關掉 helper 手上沒有對應視窗的金鑰、把 helper 的登入紀錄抄進維護歷史，並在開窗時把金鑰指紋與本機指紋推播給所有管理員。關閉時連不到 helper 一律記成「關閉未確認」，不會記成已關閉。 v0.3.0 以前的映像，dropbear 開機就在 22 埠監聽。桌面版防火牆沒有放行它，從網路連不到 SSH；基礎版沒有防火牆，dropbear 與儀表板連接埠在區網上都連得到。這些映像內嵌平台 v1.73.1 以前的版本，而平台 v1.73.2 以前的 SSH 開關改變不了這兩種情況：它啟動和停止的是名為 ssh.service 的單元（早期 Debian 版映像用的名稱），這些映像裡沒有這個單元，而且它也不會加防火牆規則。在這些映像上跑 v1.73.3 以上的 gateway 也開不了 SSH：桌面版的防火牆沒有維護埠集合，開啟會被拒絕，拒絕後補做的關閉會停掉原本就開著的 dropbear；基礎版關閉時一樣會停掉它。兩者重開機後 dropbear 都會再啟動。
webhook 中繼服務永遠看不到你的通道密鑰。 對需要它的 webhook 型通道來說，中繼服務的工作僅限於把收到的請求原始位元組，轉送到機器自己先開啟、並用自己的金鑰驗證過的連線上；中繼服務本身從不驗證簽章、不儲存通道密鑰，也不解析 payload。就算中繼服務被入侵，裡面也沒有任何有用的東西能洩漏。
鎖定畫面驗證密碼時不需要知道你的信箱。（DuDuClaw OS v0.3.0 起提供，內含 duduclaw-shell 1.65.3 與平台 v1.73.1；v0.2.0 以前的映像，鎖定畫面仍以 admin@local 驗證密碼。）它呼叫 gateway 的 POST /api/owner/verify，內容是 {"password": "..."}。gateway 依擁有者標記找出擁有者帳號，所以你把 admin@local 換成自己的信箱之後，照樣解得開鎖。這個端點只回答對（{"ok": true}）或錯（401），不發登入 token，也不回傳信箱。它只接受本機呼叫，經過反向代理的請求一律拒絕。所有本機呼叫端共用同一個嘗試上限，也和本機對擁有者帳號的 /api/login 共用（15 分鐘 5 次），不會變成另一條猜密碼的路。代價是：機器上任何程式都能把這 5 次用完。15 分鐘的時間窗是固定的，持續在跑的程式可以在每次時間窗重置後再用完一次，所以只要它還在跑，鎖定畫面就會一直拒絕解鎖。我們接受這個取捨，因為機器上已經跑著惡意程式，問題比鎖定畫面打不開嚴重得多；解法是找出那支程式並停掉它。
這份映像不是「相信我們就好」。 產生這份映像的建置腳本是公開的（見下方〈自行建置〉），任何人在燒錄之前都能讀完每一行進到機器裡的程式碼，不必只憑廠商的一面之詞。

自行建置

這份映像不是一份來路不明的二進位檔——它是從一個公開的 Yocto layer 建置出來的，你可以自己稽核，也能在自己的機器上重現，而且每一個 release 產物都附上 SHA-256 與 minisign 簽章。自 2026-09 起，這個 layer 與它的 release 流水線搬到獨立的 DuDuClaw-OS repo；下載已簽署的 release 或從原始碼建置的方法，見建置指南。官網 os.duduclaw.dudustudio.monster 的 /docs/ 底下同步了完整的 OS 文件——包含這頁、OS 的 README、CHANGELOG 與 SECURITY 說明。

目前狀態

這是平台裡還很年輕的一塊，老實講清楚它目前站在哪裡，比往好處說更重要。截至 DuDuClaw OS v0.4.0（2026-10-16，內嵌平台 v1.73.4；先前的 v0.3.0、 v0.2.0 與 v0.1.0 仍留在 Releases 頁面，但成功開機過 v0.4.0 的裝置回不去）：

x86-64 映像已經存在，兩種機型、每種機型三種形式（桌面版整碟映像、桌面版 live 安裝器 ISO、基礎版 live 安裝器 ISO）都有發布，而且都附上 SHA-256 與 minisign 簽章（整碟映像另外附一份僅供溯源的 .manifest.json）。 v0.4.0 的 QEMU 機型整碟映像在 QEMU（軟體模擬，沒有 KVM）上通過發版前的開機煙霧測試，大約 65 秒開到登入提示；QEMU 機型的兩個安裝器 ISO 也各在約 125 秒內開到 live 環境的 root 自動登入。安裝精靈沒有完整跑過。真實硬體機型（duduclaw-genericx86-64）有建置，但沒有做開機測試，也還沒有在真實硬體上開機過。
非 root gateway 用 QEMU 機型桌面版的測試映像，在建置主機的同一套無頭 QEMU 上跑了兩輪驗證。第二輪 36 項過了 35 項，沒過的那一項是 duduclaw doctor 的標題：容器功能已經正確停用，標題還寫 PASS。這段文字在平台 main 分支修好了（#132），晚於 v1.73.4。v0.4.0 還沒驗證的部分：既有的 v0.3.0 裝置經 A/B 更新升上來（資料擁有權的搬移、舊開機項目的清理）、需要 LLM 憑證的任務沙箱／電腦操作／Discovery 完整流程、 Windows VM（需要 KVM）、真機上的 Wi-Fi 與音訊，以及 duduclaw-genericx86-64 開機。
升到 v0.4.0 是單向的。duduclaw-sysd 拒絕回滾到比 v0.4.0 舊的映像，第一次 v0.4.0 開機被標記成功後，舊的開機項目會被刪掉，開機載入器也退不回去（那些映像的 gateway 以 root 執行）。之後的版本出問題，只能裝更新的映像或用救援項目。
完整的真實硬體驗證（燒錄媒介、開機、安裝、走一遍設定流程、在聊天通道來回一則訊息、套用一次 OS 更新、強制觸發一次回滾、跑一次恢復原廠設定，而且全部要在真正拿到認證的硬體上做）還沒有發生過。這是目前最重要的待辦事項。
信任鏈已經接進建置層，但已發布的映像只開啟了其中一部分。自 v0.1.0 出貨、v0.4.0 仍在的部分：A/B 原子更新與回滾（從 v0.4.0 起最多只能回滾到 v0.4.0）、桌面版裡的唯讀 root，以及每個 release 產物上的 minisign 簽章。截至 v0.4.0 仍然沒有 啟用的建置期選項：UKI 的 Secure Boot 簽署與 dm-verity root 驗證（兩者都來自 sb-signing 建置 overlay），以及 TPM2 + LUKS 金鑰封裝（tpm-luks overlay；它的自動註冊仍是一個待解的缺陷，需要真實硬體上的 TPM 才能收尾）。到目前為止沒有任何一版串連過這兩個 overlay： release-os.sh 每次建置只疊一個 release overlay（預設 serial1.yml； v0.3.0 用的是 release-linux-builder.yml，只調整建置並行度並關掉 SPDX 輸出）。拆開已發布的 v0.3.0 整碟映像查過，沒有 verity 分割區，UKI 與開機載入器也沒有簽章，所以開機時仍要關閉 Secure Boot；v0.4.0 的發版說明也寫明 Secure Boot、dm-verity、TPM2 在發布映像上仍未啟用。
OS 的版本號跟平台本身是分開算的（0.x 代表 bring-up 階段；1.0.0 才會是第一個 GA）。逐版狀態記在 DuDuClaw-OS 的 CHANGELOG 裡。

這些都不妨礙你今天就燒一份 release 來試用；但要讓值班機變成一個可以放心交給不熟悉自行排查開機故障的人使用的東西，這些正是還沒做完的部分。

維修 SSH 儀表板（尚未發版）

到「裝置 → 維修模式」，由管理員選期限與功能、重新輸入密碼，再輸入 MAINTENANCE。勾選 SSH 還需要貼上一把技術人員的 OpenSSH 公開金鑰。畫面先檢查格式；誤貼私鑰會立即清空，不會送出。閘道與裝置輔助程式仍會各自驗證。RSA 須為 3072–8192 位元。無法確認支援、舊版或更新不完整的映像會停用 SSH 選項，診斷詳情仍可使用。密碼連錯 5 次後，15 分鐘內不能開啟。

視窗開啟後會顯示 ssh duduclaw-maint@duduclaw.local、可用的私有 IPv4 位址、技術人員與本機指紋、到期時間、連線與登入失敗次數。登入前請核對管理員推播中的兩個指紋；沒有推播通道時，到裝置本機螢幕核對，無法只靠此儀表板確認裝置身分。已設定通道不代表推播已送達。22 埠只接受私有／連結本機來源與 VPN CGNAT 100.64.0.0/10，不接受全域 IPv6；來源位址符合範圍不代表可信。維修選單可查指定診斷資料、重啟本地模型或閘道；重啟閘道會關窗並中斷 SSH。

關閉未獲裝置確認時會持續顯示警告。展開「維修紀錄」可查最近的視窗金鑰指紋與連線事件。畫面每 30 秒讀取一次狀態，到期或裝置自行關閉可能要等下次讀取才顯示。完整 OS 映像、真實 SSH 與推播流程尚未驗證；這是尚未發版的介面，不代表整機已驗收。