為使用者設定 Hwip。整個設定的核心就是安裝 CLI，然後執行 hwip install — 此技能中其餘內容皆為驗證步驟。
設定步驟
npm install -g @hwip/cli
hwip install
安裝程式是互動式的（瀏覽器登入 + 代理選擇器），因此必須在使用者自己的終端機中執行，而非透過你的 Bash 工具。請要求使用者執行它 — 在 Claude Code 會話中，他們可以使用 ! 前綴來輸入：
! npm install -g @hwip/cli && hwip install
請全域安裝，不要使用 npx。 hwip cc（從手機驅動會話）需要 hwip 在 PATH 中，而且安裝程式寫入的代理掛鉤（如此外掛的掛鉤和 MCP 伺服器）會使用 command -v hwip || npx … — 全域的二進位檔可以跳過每次通知和每次會話啟動時的 npx 冷啟動。npx -y @hwip/cli install 對於僅需通知、不需手機控制的設定仍然可用，但預設情況下請使用全域安裝。
hwip install 的功用：
- 全新機器：開啟瀏覽器登入。網頁應用程式會自動產生一組 API 金鑰和一個互動式 Hook 作為一個配對 — 無需從設定頁面複製金鑰。CLI 會將所有內容（
apiKey、hookId、baseUrl、wsUrl）儲存到~/.hwip/config.json。 - 已登入過：保留已儲存的憑證，僅（重新）安裝代理整合。隨時可以安全地重新執行。
- 為所有偵測到的代理程式（Claude Code、Gemini CLI、Codex CLI、Cursor 等）安裝掛鉤/MCP。
驗證（在使用者回報安裝完成後）
hwip verify（或npx -y @hwip/cli verify）— 必須回報 API 金鑰和 Hook 已設定。永遠不要cat ~/.hwip/config.json：因為裡面包含 API 金鑰，將其列印出來會使金鑰出現在對話記錄中。- 發送測試推播：使用
hwip_notify，或hwip notify --title "Hwip 已連線 ✅"。 - 手機震動 → 完成。告訴使用者重新啟動他們的代理會話，以便 SessionStart 掛鉤注入遠端控制規則。
規則 — 不要重新引入舊的手動流程
- 單一事實來源：
~/.hwip/config.json。 所有 Hwip 元件（CLI、MCP 伺服器、外掛掛鉤）都會讀取它。請勿將HWIP_API_KEY/HWIP_HOOK_ID加入~/.zshrc、~/.bashrc或~/.claude/settings.json— Shell 匯出是不必要的，而且會建立第二個容易漂移的複本。 - 環境變數僅作為進階覆蓋（多帳戶、CI）存在。在正常設定過程中切勿建議使用。
- 除非機器是無頭模式（如下所述），否則永遠不要引導使用者在網頁應用程式中手動建立金鑰或 Hook。
無頭機器（沒有瀏覽器）
在任何有瀏覽器的機器上登入。然後使用者自行從該機器的 ~/.hwip/config.json 中讀取兩個值（apiKey 和 hookId）— 不要將檔案內容列印到會話中，因為它包含 API 金鑰。在無頭機器上，使用者在自己的終端機中執行此命令（若由你執行，金鑰將會落入對話記錄）：
npm install -g @hwip/cli
hwip install --key ak_... --hook hook_...
問題排除
hwip_ask 403 禁止存取 — 金鑰/Hook 配對過期。重新執行 hwip install；新的登入會產生一致的配對。
未收到通知 — command -v jq（掛鉤需要 jq：brew install jq / apt install jq），並確認手機應用程式已使用與瀏覽器登入相同的帳戶登入。
hwip_ask 逾時 — 手機應用程式是否開啟？是否在逾時時間內（預設 300 秒）回覆？hwip verify 可檢查安裝健康狀況。
config.json 遺失或損毀 — 重新執行 hwip install；它會覆寫該檔案。