OpenHands 在 Apple Silicon + Colima 出現 SIGILL？先查這條線
如果 OpenHands 的前端可以開啟，畫面卻一直顯示 Disconnected，不一定是瀏覽器、反向代理或 API Key 問題。對 Apple Silicon 搭配 Colima 的環境，OpenHands 官方 issue #17470 記錄了一條更底層的故障路徑：agent server 與 automation server 在啟動後因 SIGILL（Illegal instruction）結束，前端最後只看見連線中斷。
直接答案是：先從 agent server 的 container log 確認是否為 exit 132／Illegal instruction，再用同一個 image 做 import litellm 的最小重現；如果結果與 issue 描述一致，才在隔離環境測試 OPENSSL_armcap=0。 這是 issue 提出的暫時 workaround，不是所有 Apple Silicon、Colima 或 OpenHands 版本都適用的官方修復。
本文整理的是官方 issue report 與 release 狀態，沒有在本機重現。Issue 仍是 open，環境、映像版本和後續修復都可能改變；請先記錄自己的版本，再決定是否套用 workaround。
先確認是不是同一種故障
這條排錯路徑的關鍵不是「你也使用 Mac」，而是多個條件同時接近 issue 的環境：
| 觀察 | 比較接近 issue #17470 的訊號 | 不要直接套用 workaround 的情況 |
|---|---|---|
| 硬體與虛擬化 | Apple Silicon、Colima、Virtualization.framework、原生 aarch64 | Intel Mac、Linux x86、使用 emulation，或不同 container runtime |
| 產品現象 | UI 能載入，但 agent server／automation server 之後退出，畫面變成 Disconnected | 只有登入失敗、API Key 錯誤、workspace 權限錯誤或 proxy 逾時 |
| container log | SIGILL、Illegal instruction、process exit 132 | ECONNREFUSED 沒有伴隨程序崩潰，或是一般 HTTP／網路錯誤 |
| image | Issue 以 ghcr.io/openhands/agent-canvas:1.18.0 為例 | 你實際使用的是不同 tag、自己建置的 image 或更新後的 agent-server |
先保存下列資訊，後面才有辦法把「映像問題」和「環境設定問題」分開：
colima statusdocker versiondocker info --format '{{.Architecture}}'docker ps -a --no-trunc這些命令只讀取目前環境。請把 image tag、CPU architecture、Colima runtime、Docker 版本與完整錯誤時間一起記下，不要先刪除 container 或清空狀態目錄。
用最小命令重現 SIGILL
官方 issue 提供的重現方式不是直接啟動完整 GUI，而是讓同一個 image 只執行 Python import。先替換成你 log 中的實際 tag；以下保留 issue 使用的 1.18.0 作為查證基準：
docker run --rm --entrypoint python ghcr.io/openhands/agent-canvas:1.18.0 -c "import litellm"如果 shell 回傳 132，或 log 明確指出 Illegal instruction，表示程序在 import 階段就遇到非法指令。這比單看瀏覽器的 Disconnected 更接近根因，但仍不能只憑 exit code 推斷一定是 OpenSSL；issue 的 root-cause 說明是報告者的診斷，仍應以後續修復、映像變更和自己的 log 交叉確認。
若要測試 issue 提出的環境變數，可以只在一次性的 container 中加入它：
docker run --rm -e OPENSSL_armcap=0 --entrypoint python ghcr.io/openhands/agent-canvas:1.18.0 -c "import litellm"第二個命令能完成 import，只代表它通過了這個最小檢查；它不等於 Agent Canvas 已經 ready，也不代表每個功能都能正常使用。
OPENSSL_armcap=0 是暫時測試，不是永久設定
Issue 的 workaround 是讓 OpenSSL 不使用它判定可用的 ARM capability，再啟動完整 image。依 issue 中的範例，命令如下：
docker run -it --rm -p 8000:8000 -e OPENSSL_armcap=0 -v "$HOME/.openhands:/home/openhands/.openhands" -v "${PROJECTS_PATH}:/projects" ghcr.io/openhands/agent-canvas:1.18.0套用前先做三個檢查：
PROJECTS_PATH只指向可讓 Agent 讀寫的測試 workspace，不要直接掛載整個家目錄。- image tag 與你的錯誤 log 一致；OpenHands 1.19.0 或後續映像不應盲目沿用 1.18.0 的 workaround。
- 把
OPENSSL_armcap=0當成隔離環境的診斷旗標，記錄效能與功能差異，並追蹤官方 issue 或 release 是否已提供正式修復。
這個旗標改變 OpenSSL 的 CPU capability 判定路徑。它能協助驗證「停用該路徑後服務是否能啟動」，但不是讓所有非法指令、所有 CPU 架構或所有 container crash 都消失的通用解法。
先看服務 ready，再看瀏覽器畫面
workaround container 啟動後，先從服務端留下證據：
curl -i http://localhost:8000/healthdocker ps --no-truncdocker logs --tail=200 <container_id>如果 /health 回應 200、container 沒有立即退出，才回到 OpenHands UI 檢查連線。若 health 仍失敗，依序比對：
- container 是否真的綁定到預期的
8000port。 ~/.openhands掛載資料夾的擁有者與權限是否允許服務讀取。- workspace 路徑是否存在，而且沒有把 secrets 一起掛入。
- log 中是否仍有 SIGILL，或已經變成 API、模型、登入與 proxy 錯誤。
Disconnected 是前端看到的結果，不是根因分類。只有在後端程序持續存活、health 通過後，才值得進一步查 WebSocket、反向代理或瀏覽器網路面板。
什麼時候不要用這條 workaround？
如果你的 log 只有 Launch docker client failed、Permission Denied、模型 provider 連線失敗，或是 workspace 掛載錯誤，請回到 OpenHands 1.19 教學與 workspace 排錯 的一般流程。不要因為裝置是 Apple Silicon 就先關閉 OpenSSL capability。
如果最小 import 在沒有環境變數時成功，但完整服務仍斷線，也不要把問題固定在 OpenSSL。這時應保留乾淨環境的 log，檢查 image 內的 agent-server、automation server、掛載權限與實際 port，再以目前 release notes 和 issue 更新為準。
最後，若 workaround 能讓服務啟動，仍應把它視為可回復的暫時分支：固定 image tag、記錄啟動參數、安排升級測試，並在正式修復確認後移除旗標。不要把 issue 中單一環境的成功結果寫成所有 OpenHands 部署都需要的標準設定。
參考資料：
OpenHands issue #17470：Agent server crashes with SIGILL on Apple Silicon under Colima
回報錯字、失效連結，或告訴我你想看的延伸主題。