DeepSeek Harness Web UI 打不开怎么排查？

截至 2026 年 8 月 18 日，DeepSeek API 官方錯誤文件列出 7 類常見 HTTP 錯誤狀態，包括認證失敗、參數錯誤、限流與服務端錯誤；因此，DeepSeek Harness Web UI 打不開時，不應先反覆重裝，而應先確認 dsh web 進程和終端機列出的監聽地址，再依序檢查瀏覽器訪問、模型憑據、工作區選擇與操作審批。(api-docs.deepseek.com)

本週建議動作：先在乾淨的 macOS 環境保留一次完整啟動輸出，完成「頁面訪問 → 模型選擇 → 工作區讀取 → 無副作用命令 → 新會話持久化」五項驗收；遠端 Mac 則先透過安全通道驗證，暫時不要把本地監聽地址直接暴露到公網。

這篇文章適合三類讀者：首次啟動 DeepSeek Harness Web UI、但瀏覽器無法訪問的個人開發者；頁面已經打開、模型或工作區卻不可用的 AI Agent 工程師；以及需要維護遠端 Mac 開發節點和訪問鏈路的運維人員。

同樣是「頁面打不開」，實際上可能是四種不同問題：

• dsh 根本未安裝，Shell 找不到命令；
• dsh web 啟動後立即退出，原因可能是依賴、設定或參數錯誤；
• 程式仍在執行，但監聽埠被其他程式占用，或瀏覽器輸入了錯誤地址；
• 本機可以開啟，遠端裝置卻無法連線，這是訪問鏈路和安全邊界問題。

我們建議先保存終端機輸出，不要清除快取、刪除設定檔或直接更新到另一個版本。官方 README、Web UI 說明和 CLI 說明應該作為命令格式的第一依據；若當日文件已更新，則以當前版本的 --help 輸出和實際日誌為準，而不是套用社群貼文中的舊埠號或舊路徑。

可先完成以下檢查：

• [ ] dsh 命令能被目前 Shell 找到；
• [ ] dsh web 執行後沒有立即回到命令提示字元；
• [ ] 終端機有列出完整訪問地址；
• [ ] 瀏覽器地址列沒有遺漏協定、主機名或埠號；
• [ ] 啟動視窗仍然保持開啟，沒有被關閉或進入休眠。

若命令未安裝，先按官方 CLI 文件修正安裝或 PATH；若命令正常但啟動失敗，應記錄最後一段輸出，再針對該錯誤處理。不要用「重裝後能打開」當作恢復標準，因為這可能只是刪除了原本的設定或工作區狀態。

頁面完全無法訪問時，診斷順序應該是「進程存在性 → 監聽地址 → 本機連線 → 埠號衝突」，而不是先調整防火牆。

在啟動終端機中觀察三個信號：

1. 命令是否在啟動後立即結束；
2. 是否輸出本地訪問地址；
3. 點擊或複製地址後，瀏覽器是顯示拒絕連線、找不到主機，還是頁面能開但內容載入失敗。

核驗時可使用系統工具查看目前仍在執行的進程和監聽狀態，但不要臆測具體埠號。任務書已明確要求，端口、錯誤碼和設定路徑必須以當日官方文件與實際日誌為準。若發現埠號被其他程式使用，先停止無關服務或依目前版本的 CLI 選項改用可用埠號，並把新地址完整複製到瀏覽器。

恢復標準：同一台 Mac 上使用終端機輸出的地址能穩定開啟首頁，重新整理不會立即斷線，且關閉瀏覽器後再次開啟仍能回到同一個 Web UI。若只有首頁短暫出現、模型或工作區請求隨即失敗，故障已經從「頁面不可達」轉移到應用設定層，不應繼續排查瀏覽器。

本機可訪問、遠端卻打不開，代表兩個場景不能混為一談：本機回環訪問只需要本機進程和瀏覽器正常；跨設備訪問則還涉及路由、SSH、私有網路、反向代理、認證和防火牆。

遠端 Mac 的安全核驗順序如下：

1. 先登入遠端 Mac，直接在該節點本機開啟 Web UI；
2. 確認本機訪問地址和頁面內容正常；
3. 透過受控 SSH 通道或私有網路建立轉送；
4. 在客戶端瀏覽器測試轉送後的地址；
5. 只在已配置身份驗證、來源限制和網路邊界後，才評估其他暴露方式。

若本機本身也打不開，問題仍在 dsh web、模型初始化或工作區設定；若本機正常、通道後失敗，則應檢查 SSH 轉送、代理規則或防火牆，而不是修改 Web UI 的預設監聽方式。

這裡的風險不只是「別人看得到頁面」。工作區可能包含原始碼、憑據檔和可執行命令；沒有認證的公開監聽地址，可能把檔案操作與 Agent 工具一併暴露。需要遠端 Mac 部署時，可先參考 JEXCLOUD 的 Mac 部署入口，但實際暴露策略仍應由運維環境的身份與防火牆政策決定。

恢復標準：遠端用戶能透過受控通道載入頁面，且未授權來源無法訪問；通道中斷時，Web UI 不應被誤認為程式崩潰。

頁面打開但模型不可用，常見誤判是「API Key 已貼上，所以模型一定能用」。實際上，憑據保存、提供方識別、模型名稱、Base URL 和模型目錄載入是不同環節。

我們建議按以下順序核驗：

• [ ] Web UI 中的 API Key 保存後，重新載入頁面仍存在有效設定；
• [ ] 模型選擇器有實際可選項，而不是只有空白或載入狀態；
• [ ] 自訂提供方的名稱、Base URL 和模型識別字串完全匹配；
• [ ] 沒有把本地模型名稱、舊模型名稱和 DeepSeek API 的現行模型名稱混用；
• [ ] 測試任務使用最小輸入，不先加入工具、長文件或多輪上下文。

DeepSeek API 官方錯誤文件可用來區分故障類型：401 是認證失敗，402 是餘額不足，422 是參數無效，429 是請求過快或超過限制，500 和 503 則分別指向服務端錯誤及過載。這些狀態不能被統一解讀成「模型沒有載入」。(api-docs.deepseek.com)

若任務長時間沒有回應，也不要立即判斷為 Web UI 崩潰。官方文件說明，請求在推理前可能維持連線；若 10 分鐘內仍未開始推理，服務端可能關閉連線。(api-docs.deepseek.com)

恢復標準：模型選擇器顯示可用模型，最小文字任務能得到回應，並且日誌中沒有新的認證、參數或限流錯誤。若 API 回應為 429，應降低併發或等待，而不是連續重試造成更多請求。

DeepSeek Harness 選不了工作區時，最容易犯的錯是把「啟動目錄」當作「已選定工作區」。Web UI 可能要求先新增、確認並選擇工作區；啟動命令所在位置只是預設的檔案系統上下文，兩者不必然相同。

請在實際執行 dsh web 的 Mac 節點上核對：

• 目錄是否真的存在，而不是只在本機電腦上存在；
• 執行使用者是否有讀取、寫入和建立暫存檔的權限；
• 路徑是否位於外接硬碟、網路掛載、沙盒或已失效的符號連結；
• 遠端 Mac 的路徑是否與本機認知一致；
• 工作區內是否有需要額外授權才能讀取的檔案。

建議先建立一個沒有敏感資料的測試工作區，完成選擇後只執行讀取專案結構的任務。若測試目錄可用、原始專案不可用，原因多半是路徑或權限，而不是模型故障。

恢復標準：工作區能被選中，頁面可以列出基本檔案結構，且 Agent 不會因無法建立會話檔或暫存資料而立即停止。

任務卡住時，先觀察最後一個可見事件，而不是只看畫面是否轉圈：

• 若畫面等待使用者確認，可能是在等待操作批准；
• 若已送出 API 請求但沒有回應，應核對請求時間、模型和 HTTP 狀態；
• 若收到 429，應視為限流；
• 若頁面顯示會話狀態異常，則先建立新會話，避免沿用損壞的多輪上下文；
• 若工作區命令未回傳，需另外檢查 Shell 權限、命令本身和子進程。

保存三項資料很重要：錯誤碼、發生時間點、最小可重現任務。例如只提交「列出專案根目錄」這類無副作用操作，能幫助我們區分模型回應、工作區讀取和工具審批是哪一層失敗。

若模型使用工具呼叫，還要注意 DeepSeek API 的請求格式和工具參數是否符合目前文件；官方 Chat Completion 文件列明工具呼叫、模型參數與請求欄位的使用方式，應以當前 API 參考為準。(api-docs.deepseek.com)

dsh web 啟動後瀏覽器為什麼仍然打不開？

先確認進程是否仍在執行、終端機是否輸出訪問地址，再檢查地址是否完整，以及本機是否有其他程式占用監聽埠。若本機能開啟、遠端不能開啟，應轉向 SSH、私有網路或防火牆診斷，不要直接把服務改成公開監聽。

DeepSeek Harness 選不了工作區怎麼辦？

請在遠端 Mac 上確認目錄存在、執行使用者具備讀寫權限，並重新新增與選擇工作區。啟動目錄只是預設檔案位置，不代表 Web UI 已經完成工作區初始化；先用乾淨測試目錄驗證，能避免把路徑問題誤判為模型問題。

Web UI 儲存 API Key 後模型仍然不可用怎麼處理？

保存 Key 後要再核對提供方、Base URL 和模型名稱，並查看模型選擇器是否真的載入可選模型。401、402、422 和 429 分別代表不同故障方向；請保留完整回應，不要用多次換 Key 取代設定檢查。

遠端 Mac 要怎樣安全訪問 DeepSeek Harness Web UI？

先在遠端節點本機確認 Web UI 正常，再使用受控 SSH 通道或私有網路轉送。沒有認證、來源限制和防火牆規則時，不應把預設本地地址直接暴露到公網；測試完成後也應恢復最小網路暴露範圍。

恢復後不要直接投入長時間、多工具、多輪任務，建議按照以下順序：

1. 備份目前設定、API Key 保存方式和工作區清單；敏感憑據應以安全方式保存，不要把明文貼進工單。
2. 重新啟動 dsh web，保存啟動輸出與當日版本資訊。
3. 從本機或安全遠端通道開啟頁面，確認重新整理後仍可訪問。
4. 選擇已核驗的模型，執行最小文字請求。
5. 讀取工作區根目錄，確認 Agent 能看到正確的遠端檔案。
6. 執行不修改檔案、不安裝套件的命令，確認審批流程正常。
7. 建立新會話，重新載入頁面後確認會話狀態仍可恢復。

若在第 3 步失敗，回到訪問鏈路；第 4 步失敗，回到憑據和 API；第 5 步失敗，回到工作區路徑與權限；第 6 步失敗，回到審批或 Shell 權限；第 7 步失敗，則應暫停升級並保存會話與設定資料。

下表可作為恢復決策工具：

若設定路徑、模型名稱或預設端口在升級後改變，回退到已驗證的版本通常比盲目修改多個環境變數更容易定位。DeepSeek API 的模型與價格文件也會更新，模型名稱和相容性不應長期依賴舊文章；請直接核對官方模型與 API 定價文件及官方更新記錄。(api-docs.deepseek.com)

我們的經驗是，這類故障最昂貴的部分通常不是某一個命令，而是把「本機可用」誤認為「遠端可運維」，又把 API 限流、工作區權限和審批等待混成同一個無法解釋的畫面。自購 Mac 適合長期固定負載與需要實體介面的團隊，但會增加硬體折舊、維護、異地訪問和環境重建成本；一般雲端主機則未必提供合適的 macOS 工具鏈。若只是短期測試、遠端驗收或需要一個可回退的 Mac 開發節點，使用 JEXCLOUD 的遠端 Mac 方案可以把硬體採購與節點維護從本次故障中分離出來；但若工作負載長期穩定且需要固定實體周邊，自購設備仍可能更合理。

完成定位後，我們建議保存一份可回滾的遠端 Mac 環境快照或交付記錄，至少包括版本、啟動輸出、模型設定、工作區路徑、訪問通道和驗收結果。下一次升級若再次出現 DeepSeek Harness Web UI 打不開，就能從已驗證狀態比較差異，而不是只能依靠重裝恢復。