Agent 推播設定

收件匣由 duckterm-hookd 驅動。在 Agent 主機執行一條平台指令，再用 DuckTerm 掃描配對 QR Code，即可完成安裝、Hook 設定與服務啟動。

1. 1

   在 DuckTerm 開啟 Agent 通知

   安裝或開啟 DuckTerm，然後進入「設定 → Agent 通知」。不需要複製 Token 或帳戶 ID。

   配對前先安裝 DuckTerm

   QR Code 掃描器位於「設定 → Agent 通知」。執行下方主機指令前，請先在手機安裝或開啟 DuckTerm。

   App Store

   掃碼前往 App Store

   Google Play

   掃碼前往 Google Play
2. 2

   執行一條指令並掃描 QR Code

   執行該機器對應的指令。它會安裝附帶本機 Web UI 的 hookd 並顯示配對 QR Code；用 DuckTerm 掃描後會設定受支援 Agent 的 Hook 並啟動背景服務。

   下方是可直接執行的完整指令。安裝包附帶本機 Web UI，配對憑證不會出現在指令或 Shell 歷史記錄中。

   

   macOS

   Homebrew · Apple 晶片與 Intel

   hookd setup zsh

   brew install ducksee/tap/duckterm-hookd && \
   "$(brew --prefix duckterm-hookd)/bin/duckterm-hookd" setup --qr

   

   Windows

   原生 PowerShell / CMD · Windows 10 / 11 · x64 / arm64

   PowerShell powershell

   irm https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.ps1 | iex

   Command Prompt cmd

   curl.exe -fsSL https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.cmd -o install.cmd && install.cmd

   

   Linux

   Ubuntu、Debian 等常見 systemd 發行版 · arm64 / x86_64

   hookd setup sh

   curl -fsSL https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.sh \
     | DUCKTERM_PAIR_QR=1 sh

   

   Windows WSL

   Windows 內的 Ubuntu · WSL1 / WSL2 · 自動服務化

   hookd setup sh

   curl -fsSL https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.sh \
     | DUCKTERM_PAIR_QR=1 sh

3. 3

   驗證

   執行 duckterm-hookd status，再到「設定 → Agent 通知」分別測試本機推播與平台推播。日後升級 hookd 或重新啟動服務都會保留這次配對。

   查看說明

   $ duckterm-hookd status
   DuckTerm Agent connection · vX.Y.Z
   [ok] Connected to DuckTerm: <this host>
   [ok] Background service is running
   [ok] Cloud connection is online
   [ok] Membership: Pro
   [ok] Coding agents connected: Claude Code, Codex
   
   # End-to-end Hookd → cloud → APN / Inbox test
   $ duckterm-hookd test-push --note "Setup verification"
   test push accepted by local Hookd
   source=<this host>
   time=<current RFC3339 time>
   cwd=<current directory>
   Cloud/APN delivery is asynchronous; verify it on the device or in local send records.

   接著在「設定 → Agent 通知 → 驗證」分別傳送本機測試與平台推播測試。手機都能收到，就表示設定完成。

4. 4

   升級或移除 Hookd

   升級 hookd 與 Web UI、解除 Agent hooks，或在主機不再使用 DuckTerm 時完整移除 Homebrew 服務。

   查看說明

   # Homebrew / native Windows: verify, upgrade, and restart Hookd
   duckterm-hookd upgrade
   
   # Linux / WSL: upgrade binary, bundled UI, and service
   curl -fsSL https://raw.githubusercontent.com/ducksee/duckterm-hookd-releases/main/install.sh | sh
   
   # Upgrade only the independently versioned Web UI
   duckterm-hookd ui upgrade
   
   # Disconnect Agent hooks; keep the daemon installed
   duckterm-hookd hook uninstall
   
   # Homebrew: remove the service and binary completely
   brew services stop duckterm-hookd && brew uninstall duckterm-hookd

   duckterm-hookd hook uninstall 只會刪除支援的 Agent 設定中的 DuckTerm 項目，並保留守護程序、配對資訊和其他第三方 hooks。

5. 5

   LAN Direct 與主機防火牆

   為了讓手機透過區域網路或 VPN 直連，hookd 會在所有網卡監聽 TCP 11434（0.0.0.0 / [::]）。這不等於暴露到公網；不需要路由器連接埠轉送，連線仍需 DuckTerm 配對金鑰。

   查看說明

   Windows（原生）

   setup 會把安裝目錄加入使用者 PATH；開啟新終端後可直接使用 duckterm-hookd，或使用短指令 dhook。TCP 連接埠規則會套用至所有網路設定檔。需要權限時，請在系統管理員 PowerShell 執行：

   duckterm-hookd firewall install
   duckterm-hookd firewall status

   macOS

   Homebrew 會同時安裝 duckterm-hookd 和短指令 dhook。首次出現防火牆提示時選擇「允許」。若先前拒絕，可執行下列指令，只放行 Homebrew 安裝的 hookd：

   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --add \
     "$(brew --prefix duckterm-hookd)/bin/duckterm-hookd"
   sudo /usr/libexec/ApplicationFirewall/socketfilterfw --unblockapp \
     "$(brew --prefix duckterm-hookd)/bin/duckterm-hookd"

   Linux / WSL

   安裝腳本會把 duckterm-hookd 和短指令 dhook 安裝至 /usr/local/bin。若啟用 UFW，請開放 TCP 11434；不要設定路由器公網連接埠轉送：

   sudo ufw allow 11434/tcp
   duckterm-hookd firewall status

6. 6

   Public Direct

   選用 · 進階

   hookd 可以在 127.0.0.1:11435 開啟僅監聽回環的入口，交給你自己執行的 HTTPS/WSS 通道發佈——Cloudflare Tunnel、frp 或反向代理皆可。它不會放寬 LAN 位址閘門，也永遠不包含 Web 控制台的 20080 連接埠；routeSecret 只用於隔離掃描器，不是應用金鑰，配對驗證維持不變。任何變更後都需要重新啟動 hookd。

   查看說明

   # 1 · Enable the loopback ingress (default port 11435) and register the origin
   duckterm-hookd access enable
   duckterm-hookd access add https://hookd.example.com
   duckterm-hookd access list
   
   # 2a · Cloudflare Tunnel — shortest form
   cloudflared tunnel --url http://127.0.0.1:11435
   
   # 2b · frp — shortest frpc.toml
   # serverAddr = "frps.example.com"
   # serverPort = 7000
   # [[proxies]]
   # name = "hookd"
   # type = "https"
   # localIP = "127.0.0.1"
   # localPort = 11435
   # customDomains = ["hookd.example.com"]
   
   # 3 · Public Direct changes only take effect after a restart
   duckterm-hookd restart

各 Agent 的接入細節

安裝 hookd 會替所有支援的 Agent 接上線。有些 Agent 還有一步首次執行的動作，決定事件到底能不能到你手機——下面這幾個就是。完成後，把 Agent 跑在 tmux（或 Herdr）裡再送一句話；Live Preview 需要有一個工作階段可以掛上去。

OpenCode

OpenCode 不需要確認：安裝程式會把 DuckTerm 外掛寫進它的外掛目錄。如果你是在這台機器上還沒有 OpenCode 時安裝 hookd 的，請重新執行一次安裝程式，外掛才會就位。

試一下

cd tmp
tmux new -s op-prod-main
opencode

輸入 你是什麼模型 然後看手機：訊息應該進 Inbox，Live Preview 應該能即時看到這個工作階段的畫面。

Codex

Codex 首次啟動會問是否信任 hook，請選擇全部信任——未被信任的 hook 根本不會執行，hookd 也就沒有東西可以轉發，Inbox 會一直是空的。

試一下

cd tmp
tmux new -s cx-prod-main
codex

輸入 你是什麼模型 然後看手機：訊息應該進 Inbox，Live Preview 應該能即時看到這個工作階段的畫面。

Claude Code

Claude Code 從 ~/.claude/settings.json 讀取 hook，該檔案由安裝程式寫入。Claude Code 只在啟動時讀取它，並會把 hook 變更標記出來讓你確認，所以已經在跑的工作階段要重新啟動一次、提示確認時選通過，事件才會開始上報。

試一下

cd tmp
tmux new -s cc-prod-main
claude

輸入 你是什麼模型 然後看手機：訊息應該進 Inbox，Live Preview 應該能即時看到這個工作階段的畫面。

DeepSeek Harness

DeepSeek Harness 透過一個樹外的 hooks bridge 接到 hookd，該 bridge 由 hookd 代為安裝。若這一步失敗，dsh 的 web 介面會顯示錯誤——請自行執行 dsh plugin add @deepseek-ai/dsh-hooks-claude-code，再重跑一次 hookd 安裝程式，然後重新啟動 dsh web 介面。bridge 要重啟之後才會生效。

試一下

cd tmp
tmux new -s dsh-prod-main
dsh

輸入 你是什麼模型 然後看手機：訊息應該進 Inbox，Live Preview 應該能即時看到這個工作階段的畫面。