常用 tailscale CLI 指令速查

tailscale 指令是操作本機 Tailscale 的主要工具：Linux 伺服器、NAS、LXC 這類沒有圖形介面的環境幾乎都靠它，macOS 與 Windows 的圖形介面背後也有同一套指令可用。本文按用途整理最常用的指令，每個附上用途與常用旗標，並連到本站的詳細文章。

本文以 Tailscale v1.102（2026 年 10 月）為準，指令與旗標依 v1.102.4 的 tailscale --help 與官方 CLI 參考整理。官方說明 CLI 仍在持續調整，指令與旗標可能隨版本變動，遇到不一致時以你手上版本的 tailscale <指令> --help 為準。

使用前須知

• Linux 要 root：tailscaled 預設只接受 root 操作，看到 Access denied 就加 sudo。不想每次都打 sudo，可以執行一次 sudo tailscale set --operator=$USER，讓目前的使用者也能操作。
• 每個指令都有說明：tailscale <指令> --help 會列出所有旗標與預設值，例如 tailscale up --help。
• 布林旗標的寫法：--ssh 等同 --ssh=true，要關掉就寫 --ssh=false；字串旗標給空字串代表清除，例如 --exit-node=。
• macOS：三種版本都有 CLI，但功能不完全相同，例如 App Store 版沒有 tailscale ssh 指令，差異見 macOS 上安裝 Tailscale 的三種方法。

連線與狀態

常用旗標與用法：

• tailscale up --auth-key=<key>：用 auth key 登入，不用開瀏覽器，適合腳本或沒有螢幕的機器。--auth-key=file:/path/to/key 可以從檔案讀取，避免金鑰留在 shell 歷史紀錄。
• tailscale up --qr：把登入網址印成 QR code，用手機掃描登入，適合只有序列埠或 console 的機器。
• down 和 logout 的差別：down 只是暫時離線，裝置還留在 tailnet；logout 會讓 node key 失效，下次 up 要重新登入。只是想暫停連線就用 down。
• tailscale status --active：只列出目前有連線往來的裝置。--json 輸出完整資料，但官方提醒格式可能隨版本改變，寫腳本時要留意。
• tailscale ip -4：只印 IPv4，-6 只印 IPv6；tailscale ip -4 nas 查名為 nas 的裝置。
• tailscale ping：預設最多送 10 次，一旦建立直連就停（--until-direct）。回應裡的 via DERP(tok) 表示經由東京的 DERP 中繼，via peer-relay(...) 表示經由 Peer Relay，via 203.0.113.5:41641 這種 IP 加連接埠則是直連。--c 0 會一直 ping 下去。

tailscale ping 通、一般的 ping 不通，表示是某一端作業系統的防火牆擋掉了封包，因為 tailscale ping 不經過兩端的 TUN 介面。直連與 DERP 的觀念見 Tailscale 是什麼。

設定：set 與 up 的差別

這是 CLI 最常踩的坑。兩個指令都能改設定，但行為不同：

• tailscale set：只改你寫出來的設定，沒寫到的維持原狀。
• tailscale up：帶了任何設定旗標時，那組旗標要是完整的設定。只要有一個沒寫到的設定會因此回到預設值，up 就會拒絕執行。

舉例來說，一台裝置原本以 tailscale up --advertise-exit-node --accept-routes 啟動，現在想加開 Tailscale SSH：

# 會失敗：沒寫到 --advertise-exit-node 與 --accept-routes
sudo tailscale up --ssh

# 可以：只開 SSH，其他設定不動
sudo tailscale set --ssh

up 失敗時會印出類似這段錯誤，下方附上一行把目前所有非預設設定都寫齊的指令，複製那一行再加上新旗標即可：

Error: changing settings via 'tailscale up' requires mentioning all
non-default flags. To proceed, either re-run your command with --reset or
use the command below to explicitly mention the current value of
all non-default settings:

幾個細節：

• 沒有旗標的 tailscale up 不會改任何設定，只是把網路連上，等同 down 的反向操作。
• up --reset 會把沒寫到的設定全部改回預設值，要確定這是你要的才用，不要拿它來繞過錯誤訊息。
• 第一次登入前沒有既有設定可比較，up 不做這項檢查，帶任何旗標都可以。
• --auth-key、--force-reauth、--qr 不算設定，改設定時不用重複寫。
• set 沒有的旗標：--advertise-tags、--login-server、--auth-key 只有 up 與 login 有，--reset 則只有 up 有。要改 tag 就得用 up，並把其他設定寫齊。
• 查目前的設定：tailscale get 列出所有設定值；tailscale get --set-flags 直接印成 tailscale set 的旗標格式，方便記錄或搬到另一台機器。

set 常用的旗標：

功能指令

常用旗標與用法：

• Serve／Funnel：--bg 背景執行，重開機後自動恢復；status 看目前的分享，reset 清除全部設定。要移除單一分享，用原本的旗標加上 off，例如 tailscale serve --https=443 off。
• tailscale cert：網域就是裝置的完整名稱，例如 tailscale cert nas.tailxxxxx.ts.net。預設在目前目錄存成 <網域>.crt 與 <網域>.key，可用 --cert-file、--key-file 指定輸出路徑（給 - 代表輸出到 stdout）。tailnet 要先在 Admin console 啟用 HTTPS。
• tailscale ssh：連線的是對方用 tailscale set --ssh 開啟的 Tailscale SSH 伺服器，或對方本來就有的 SSH 伺服器。它只是系統 ssh 的包裝，會用 MagicDNS 解析名稱（即使本機 --accept-dns=false），並自動核對對方的 host key。平常直接用 ssh 也可以。
• Taildrop：tailscale file cp photo.jpg my-laptop:，目標裝置名稱後面要加冒號。tailscale file cp --targets 列出可傳送的裝置。Linux 上收到的檔案會先放在收件匣，要用 tailscale file get ~/Downloads 取出；--wait 等檔案進來，--loop 持續接收。
• Exit Node：tailscale exit-node list --filter=Japan 依國家篩選；tailscale exit-node suggest 建議目前最適合的 Exit Node。選好後用 tailscale set --exit-node=<名稱> 套用，清除則是 tailscale set --exit-node=。

除錯

幾個重點：

• bugreport 印出的識別碼本身不含日誌內容，而是讓 Tailscale 支援人員找到本機對應時間點的日誌。加上 --diagnose 會多跑一些深入檢查。開 GitHub issue 或聯絡支援時附上這組識別碼，能省下很多來回。
• debug 不是穩定介面：官方說明它的子指令與輸出隨時可能改變，適合臨時查問題，不要寫進腳本。
• 連不上時的排查順序：先 tailscale status 看對方是否在線，再 tailscale ping <主機> 看是否走 DERP，最後用 tailscale netcheck 檢查本機的 UDP 與 NAT 狀況。

參考資料

• Tailscale CLI 參考（官方）
• Tailscale 原始碼：tailscale up 的設定檢查（cmd/tailscale/cli/up.go）
• Tailscale 原始碼：tailscale set（cmd/tailscale/cli/set.go）
• Taildrop（官方）
• Tailscale SSH（官方）