Agent 推送接入

Inbox 由 duckterm-hookd 驱动。在 agent 主机运行一条平台命令，再用 DuckTerm 扫描配对二维码，即可完成安装、挂接和服务启动。

1. 1

   在 DuckTerm 打开 Agent 通知

   安装或打开 DuckTerm，然后进入 设置 → Agent 通知。不需要复制 token 或账号 id。

   配对前先安装 DuckTerm

   二维码扫描器位于 设置 → Agent 通知。运行下面的主机命令前，请先在手机安装或打开 DuckTerm。

   App Store

   扫码前往 App Store

   Google Play

   扫码前往 Google Play
2. 2

   运行一条命令并扫码

   运行这台机器对应的命令。它会安装带本地 Web UI 的 hookd 并显示配对二维码；用 DuckTerm 扫码后会挂接受支持的 agent 并启动后台服务。

   下方是可直接运行的完整命令。安装包自带本地 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。它会按当前 LAN 端口重建一条适用于所有网络配置文件的 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 应该能实时看到这个会话的画面。