2026 DeepSeek Harness 怎麼用 launchd 開機自啟？

官方 README 目前列出 DeepSeek Harness 的 4 種 wrapper 執行形式，包括 Python 套件、命令列工具、MCP 伺服器與 Skill；但截至 2026 年 8 月 19 日，尚未確認它內建 macOS 服務安裝器。這代表我們的建議很明確：先用普通運行帳戶的 LaunchAgent 管理 DeepSeek Harness launchd 開機自啟，不要一開始就建立 root LaunchDaemon；完成後必須驗證進程、監聽位址、模型任務與重啟恢復四個閉環。執行入口與套件形式可先參考官方 README 的安裝與執行說明。(github.com)

本週建議動作：先固定一個托管對象、運行帳戶、絕對路徑與日志位置，再建立最小 LaunchAgent；不要把 Web、Headless 和一次性批次任務混在同一個 plist 內。

這篇適合三類讀者：
遠端 Mac 使用者：希望機器重啟或重新登入後自動恢復 DeepSeek Harness。
平台工程師：需要統一進程身份、日誌位置與停止方法。
交付負責人：需要把「能啟動」轉化為可重複的持續運行驗收。

DeepSeek Harness launchd 開機自啟最常見的錯誤，不是 plist 語法，而是沒有先定義「到底要恢復什麼」。我們建議把服務拆成以下其中一種：

• Web UI：長時間運行，重點是登入後可啟動、監聽位址固定、遠端連線可達。
• Headless 入口：由命令列接收工作，重點是退出狀態、產物位置與錯誤碼。
• 自動化任務：可能只應在排程、佇列或外部觸發時執行，不適合用一個永久存活的進程代替任務管理器。

在開始前，建立一份不含敏感值的部署記錄，至少寫下：

• DeepSeek Harness 的實際可執行檔絕對路徑；
• 使用中的 Profile 或設定檔名稱；
• 固定工作目錄與狀態目錄；
• 預期運行帳戶；
• Web 模式的監聽位址與端口來源；
• 正常停止命令，以及異常時的人工處理方式。

macOS 會以不同的工作階段管理 Agent 與 Daemon；使用者專用的 LaunchAgent 通常放在 ~/Library/LaunchAgents，只對已登入的該帳戶生效。進程管理原則可參考macOS 官方 launchd 角色與目錄說明。(support.apple.com)

注意：「進程重新出現」不代表原本的模型任務、互動工作階段或未寫入磁碟的上下文也會恢復。launchd 負責進程生命週期，不負責替 DeepSeek Harness 保存任務語意。

只要 Web 工作流需要使用者家目錄、登入 Keychain、互動設定或使用者專用工作區，普通帳戶的 LaunchAgent 通常比 root 服務更合適。官方文件將 per-user agent 定義為特定登入使用者的背景進程，並說明它會在該使用者登入時啟動。(developer.apple.com)

root 方案的隱性成本包括：

• 設定檔與狀態資料可能被 root 建立，之後普通帳戶無法正常修改；
• 使用者 Keychain、GUI 權限與工作區權限可能不在同一個安全範圍；
• 維運人員容易為了「先跑起來」而把 API Key 放在 root 可讀的啟動檔；
• Web UI 若實際需要使用者會話，改成 LaunchDaemon 反而增加權限與除錯邊界。

我們建議先把 plist 放在目標帳戶的：

~/Library/LaunchAgents/<自訂標籤>.plist

以下只是結構示意，不能直接複製到所有環境。<使用者家目錄>、<dsh 絕對路徑>、<工作目錄>、<Profile> 與日志路徑都必須按現場替換：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>com.example.deepseek-harness</string>

  <key>ProgramArguments</key>
  <array>
    <string>&lt;dsh 絕對路徑或啟動腳本&gt;</string>
    <string>&lt;Web 或 Headless 參數&gt;</string>
    <string>--profile</string>
    <string>&lt;Profile&gt;</string>
  </array>

  <key>WorkingDirectory</key>
  <string>&lt;工作目錄絕對路徑&gt;</string>

  <key>StandardOutPath</key>
  <string>&lt;可維護的標準輸出日志&gt;</string>

  <key>StandardErrorPath</key>
  <string>&lt;可維護的錯誤日志&gt;</string>

  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

ProgramArguments、WorkingDirectory、StandardOutPath 和 StandardErrorPath 都是 launchd 配置進程環境的重要欄位；KeepAlive 只表示希望工作持續存在，不表示任務會續跑。欄位用途可核對官方 launchd 工作配置說明。(developer.apple.com)

配置檔完成後，先在目標帳戶下執行：

chmod 600 "$HOME/Library/LaunchAgents/<自訂標籤>.plist"
plutil -lint "$HOME/Library/LaunchAgents/<自訂標籤>.plist"

不要在 plist 的 EnvironmentVariables 內硬編碼真實 API Key。可讓啟動腳本從同一帳戶的 Keychain 讀取，或讀取權限為 600 的環境檔；Keychain 本身用於保存密碼、登入資料與金鑰等敏感內容，相關保護機制可參考官方 Keychain 資料保護說明。(support.apple.com)

首次托管不要立刻把問題擴大成「服務穩不穩」。我們先驗證三件事：是否由預期帳戶啟動、是否使用正確工作目錄、錯誤是否能被日志捕捉。

在已登入的目標帳戶中，執行：

UID_VALUE="$(id -u)"
AGENT="$HOME/Library/LaunchAgents/<自訂標籤>.plist"

launchctl bootstrap "gui/$UID_VALUE" "$AGENT"
launchctl kickstart -k "gui/$UID_VALUE/com.example.deepseek-harness"
launchctl print "gui/$UID_VALUE/com.example.deepseek-harness"

接著用系統工具確認進程身份與命令列：

ps -axo user,pid,ppid,command | grep '[d]sh'

若出現 npx: command not found、node: command not found 或找不到 dsh，不要先增加 KeepAlive。LaunchAgent 的環境不等同於互動式 Terminal，應該先用目標帳戶找出絕對路徑：

command -v node
command -v npx
command -v dsh

若 dsh 是由專案啟動，則優先使用固定版本的啟動腳本，而不是依賴會變動的全域 PATH。把查到的結果填入 plist 後，先停用再重新載入，避免舊進程仍以舊環境運作。

日志至少要能回答以下問題：

• 啟動命令是否被真正執行；
• 工作目錄是否存在且可寫；
• Profile 是否被讀取；
• API Key 缺失時是否只輸出錯誤類型而非真實值；
• 進程是正常退出、參數錯誤，還是因權限被拒絕。

進程存在後，才進入可用性驗收。Web 模式至少要完成：

1. 確認實際監聽位址，而不是只檢查本機瀏覽器；
2. 從遠端 Mac 的連線路徑測試 Web UI；
3. 確認工作區能讀取與寫入；
4. 執行一項低風險模型任務；
5. 檢查任務結果、錯誤日志與狀態檔是否一致。

如果 Web UI 只能繫結在本機回環位址，遠端使用者可能看到進程正常，卻無法從外部連線；如果直接改成公開監聽，又可能把未完成驗證的管理介面暴露到網路。實務上應先使用受控的 SSH 轉發或內部網路，再按需求配置防火牆與存取控制。遠端 Mac 的交付與連線規劃，可先參考JEXCLOUD 遠端 Mac 方案。

Headless 模式則不應以「一直不退出」作為成功標準。最小驗收應包括：

• 命令正常返回；
• 退出狀態符合預期；
• 產物寫入指定目錄；
• 失敗時日志可定位到參數、憑據、工作區或模型端點；
• 重啟後不會因殘留鎖檔或狀態目錄而啟動兩份實例。

這一階段要測的是恢復行為，而不是單純重複執行 launchctl kickstart。我們建議按照下列順序記錄結果：

• [ ] 主動停止進程，確認 LaunchAgent 是否按預期再次啟動；
• [ ] 模擬一次非正常退出，確認日志是否留下退出原因；
• [ ] 登出後重新登入，確認 Web UI、工作區與憑據仍可用；
• [ ] 重新啟動遠端 Mac，確認登入後進程、端口與日志都恢復；
• [ ] 執行一項新的低風險模型任務，確認不是只有空殼 Web UI；
• [ ] 記錄每個階段的恢復時間點與需要人工介入的條件。

KeepAlive 可以讓 launchd 嘗試維持工作，但持續崩潰時，它可能只會製造大量重啟與日志噪音；因此我們不把它等同於任務恢復，也不把進程恢復時間寫成未經測試的固定承諾。對於需要保存任務進度的工作，應另行設計可重入狀態、產物檢查與去重機制。

經驗：如果重啟後 Web UI 能開啟，但模型任務失敗，優先檢查非互動環境中的 API Key、工作目錄與 Node 路徑；不要先刪除狀態目錄，因為那可能讓真正的恢復問題變成資料遺失問題。

正式交付前，至少要保留一份不含敏感值的 plist、啟動命令、版本資訊與日志位置。停用目前服務時，可先使用：

UID_VALUE="$(id -u)"
launchctl bootout "gui/$UID_VALUE/com.example.deepseek-harness"

確認進程已停止後，再移走 plist。若需要重新載入：

launchctl bootstrap "gui/$UID_VALUE" \
  "$HOME/Library/LaunchAgents/<自訂標籤>.plist"

升級候選版本時，先停止舊進程，再確認新版本的絕對路徑、Profile、工作目錄與狀態格式；不要在未清理舊服務的情況下直接載入第二個 plist，否則兩個實例可能爭用同一個端口或狀態目錄。必要時可把新版本放到獨立目錄，先完成一次 Headless 任務，再切換 Web 入口。

最後的簽收證據不應只是「重啟後 Activity Monitor 看得到進程」，而應是：

• 重新登入後進程由預期帳戶啟動；
• 日誌能持續寫入並沒有暴露密鑰；
• Web UI 從指定連線路徑可達；
• 一項低風險模型任務成功；
• 主動停止與異常退出的行為符合記錄；
• 升級失敗時可以回退到上一個啟動命令。

若目前的 Mac 需要長時間穩定佔用、必須保留實體介面，或任務本身是持續高負載工作，租用遠端環境未必比自購設備合適；但若現有方案依賴個人電腦不定期登入、環境變數散落、端口容易被其他服務佔用，並且重啟後需要人工重新開啟 Web UI，長期維運成本會很快轉化為交付風險。完成上述重啟測試後，如果本機沒有穩定的持續佔用窗口，可以再查看JEXCLOUD 遠端 Mac 交付方案，按預期使用時間與驗收責任規劃租期，而不是先把 root 權限和 API Key 都交給一個未驗證的常駐服務。

• Web UI 無法開啟時的排查方法
• macOS launchd 重啟與健康檢查：雲端 Mac 服務維護指南
• 用 LaunchAgent 讓遠端 Mac 節點持續運作：設定與驗證指南