Community程式設計與開發github.com

steipete/ssh-doctor

SSH 診斷工具:遠端登入、launchd sshd、認證前關閉、連線卡住等問題。

ssh-doctor 是什麼?

SSH Doctor 是一個專門為 macOS 設計的 SSH 連線診斷工具,可協助開發者與 AI 代理程式診斷並修復 SSH 連線問題,例如連線在認證前關閉、遠端登入看似啟用卻無法使用,或 local/remote Mac SSH 需要除錯等場景。此技能支援 Claude Code、Cursor、Codex 等 AI 代理平台,透過標準的 bash 指令與日誌分析,提供從本地驗證、設定審查、防火牆檢查,到修復卡住的 sshd-session 程序等完整的工作流程。其核心優勢在於其結構化的診斷規則:先本地環回測試以區分伺服器端與網路端問題;報告可疑設定行後再進行變更;並針對 macOS 特有的 launchd 與 sshd 互動問題(如 copy count 過高)提供明確的修復步驟。此外,它也包含安全的 OP Service Account Token 複製功能,確保敏感資訊不會被意外揭露。

相容平台~Claude Code✓Codex CLI~Cursor
npx skills add https://github.com/steipete/agent-scripts/tree/main/skills/ssh-doctor

Installed? Explore more 程式設計與開發 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

SSH Doctor

當 SSH 連線在認證前關閉、遠端登入看似啟用卻無法使用,或需要診斷本地/遠端 Mac SSH 問題時使用。

規則

  • 不要輸出密碼、令牌、完整環境變數或廣泛的 secret grep 結果。
  • 先在本機驗證:環回失敗代表伺服器端的 sshd/launchd/設定問題;環回成功但遠端失敗代表網路/防火牆/過濾器/監聽路徑問題。
  • 在修改 /etc/ssh/sshd_config 之前,先回報可疑的設定行。
  • 優先使用非互動式 SSH:
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'hostname; id -un'

基本檢查

hostname; id -un; sw_vers
ipconfig getifaddr en0
ipconfig getifaddr en1 2>/dev/null || true
ipconfig getifaddr en7 2>/dev/null || true
sudo systemsetup -getremotelogin
sudo systemsetup -setremotelogin on
sudo launchctl print system/com.openssh.sshd 2>&1 | head -80
sudo launchctl kickstart -k system/com.openssh.sshd
sudo lsof -nP -iTCP:22 -sTCP:LISTEN
nc -vz 127.0.0.1 22
ssh -4 -F /dev/null -o RequestTTY=no -o RemoteCommand=none [email protected] 'hostname; id -un'

僅在密碼備援會導致停滯或提示時,才使用 BatchMode=yes。

設定檢查

sudo sshd -T 2>&1 | egrep -i '^(allowusers|denyusers|allowgroups|denygroups|listenaddress|maxstartups|logingracetime|usepam|passwordauthentication|pubkeyauthentication|authenticationmethods)'
sudo egrep -n '^[[:space:]]*(AllowUsers|DenyUsers|AllowGroups|DenyGroups|Match|MaxStartups|LoginGraceTime|ListenAddress|AuthenticationMethods|UsePAM|PasswordAuthentication|PubkeyAuthentication)\b' /etc/ssh/sshd_config /etc/ssh/sshd_config.d/* 2>/dev/null || true

可疑項目:

  • DenyUsers 包含目標使用者
  • 限制性的 AllowUsers / AllowGroups
  • Match 區塊意外套用
  • MaxStartups 數值過小
  • LoginGraceTime 數值過小
  • ListenAddress 缺少目標介面

日誌

sudo log show --last 30m --predicate 'process == "sshd" OR process == "launchd"' --style compact | tail -160

重要的 Mac 症狀:

  • 客戶端:kex_exchange_identification: Connection closed by remote host
  • 伺服器日誌:Could not create new instance of inetd service: 67: Too many processes
  • launchctl print system/com.openssh.sshd:copy count 數值很高
  • 許多 sshd-session: USER 行程的父行程 PID 為 1

這表示 launchd 接受了 TCP 連線,但拒絕產生更多 sshd inetd 實例。

卡住的 sshd-session 修復

先檢查:

sudo launchctl print system/com.openssh.sshd 2>&1 | egrep 'active count|copy count|state =|last exit code|runs ='
ps -axo pid,ppid,uid,user,state,lstart,etime,comm,args | awk '/sshd-session:/ && !/awk/ {print}'
sudo lsof -nP -c sshd-session -iTCP 2>/dev/null | head -120

如果卡住的 session 明顯是孤立且阻擋新的 SSH 連線,可依選定的指令行匹配終止:

ps -axo pid=,args= | awk '/sshd-session: / && !/awk/ {print $1}' | xargs sudo kill -TERM
sleep 2
ps -axo pid=,args= | awk '/sshd-session: / && !/awk/ {print}'

如果 TERM 無法清除阻擋者,請先重新檢查所有權與活躍的 shell,再使用 KILL。

防火牆

僅在環回測試成功但遠端失敗時使用:

sudo /usr/libexec/ApplicationFirewall/socketfilterfw --getglobalstate
sudo /usr/libexec/ApplicationFirewall/socketfilterfw --listapps | grep -i ssh -A2 -B2 || true
sudo pfctl -sr 2>/dev/null | head -80
sudo pfctl -si 2>/dev/null | head -80

也請檢查監聽位址與目標介面:

ifconfig | awk '/^[a-z0-9]+:/{iface=$1; sub(":","",iface)} iface ~ /^en[0-9]+$/ && /inet / {print iface, $2}'
sudo lsof -nP -iTCP:22 -sTCP:LISTEN

OP Profile 區塊

如果被要求確保 ~/.profile 中有一個從其他主機複製的 Codex 管理的 OP_SERVICE_ACCOUNT_TOKEN:

  • 驗證確切的變數名稱與標記,但不要輸出數值
  • 僅複製相符的那一行/區塊
  • 透過 chmod 600 暫存檔重新導向
  • 絕不要 echo 該令牌

存在性檢查:

awk 'BEGIN{b=0;e=0;x=0} /BEGIN Codex-managed OP_SERVICE_ACCOUNT_TOKEN/ {b=1} /END Codex-managed OP_SERVICE_ACCOUNT_TOKEN/ {e=1} /^[[:space:]]*(export[[:space:]]+)?OP_SERVICE_ACCOUNT_TOKEN=/ {x=1} END{print "marker_begin", b; print "marker_end", e; print "exact_var", x}' ~/.profile

從遠端主機附加:

tmpfile=$(mktemp /tmp/codex-op-token.XXXXXX)
chmod 600 "$tmpfile"
ssh -o RequestTTY=no -o RemoteCommand=none HOST 'awk '\''/^[[:space:]]*(export[[:space:]]+)?OP_SERVICE_ACCOUNT_TOKEN=/ {print; exit}'\'' ~/.profile' > "$tmpfile"
if [ -s "$tmpfile" ]; then
  {
    printf '\n# BEGIN Codex-managed OP_SERVICE_ACCOUNT_TOKEN\n'
    sed -n '1p' "$tmpfile"
    printf '# END Codex-managed OP_SERVICE_ACCOUNT_TOKEN\n'
  } >> ~/.profile
fi
rm -f "$tmpfile"

結案報告

回報:

  • 根本原因
  • 實際變更的指令
  • 驗證輸出(如有需要請遮罩處理)
  • 是否需要遠端重試

Individual skills in this repo

This repo contains 20 individual skills — each has its own dedicated page.

steipete/agent-transcript

GitHub PR/issue agent transcripts: redact, preview, and insert safely.

steipete/beeper

Beeper cache: contact hints, room lookup, WhatsApp/iMessage traces, FTS.

steipete/browser-use

Existing Chrome automation: Chrome plugin first, mcporter fallback.

steipete/clawsweeper-status

ClawSweeper status: URLs, workflow health, active workers, ops snapshot.

steipete/clickclack

ClickClack ops: chat app, Hetzner deploy, DNS/docs/app, Docker rollout.

steipete/cloudflare-registrar

Cloudflare Registrar: domain availability, prices, registration via mcporter.

steipete/codex-debugging

Codex debugging: codex-rs core/tui/exec/cli/app-server/config.

steipete/create-cli

CLI UX/spec: args, flags, help, output, errors, config, dry-run.

steipete/discord-clawd

Discord-backed OpenClaw agent/session relay; not archive search.

steipete/domain-dns-ops

DNS/domain ops: registrars, zones, redirects, DNS/HTTP verify, manager truth.

steipete/frontend-design

Frontend UI: pages, apps, components, polished non-generic design.

steipete/github-author-context

GitHub contributor context: identity, activity, trust, company/team signal.

steipete/github-cache-hygiene

GitHub quota/cache hygiene: gh, ghx, xcache, gitcrawl, mirrors, limits.

steipete/github-deep-review

GitHub deep review: bugs, PRs, best fix, stale-or-real, read code first.

steipete/github-project-triage

GitHub issue/PR triage: queues, CI, blockers, risk, proof, next actions.

steipete/hopper-debugger

Hopper debugging: macOS/iOS binaries, ObjC/Swift symbols, dyld, LLDB.

steipete/instruments-profiling

Instruments/xctrace profiling: macOS/iOS traces, binaries, args, exports.

steipete/mac-maintenance

Mac upkeep: brew update/upgrade, pull clean repos, empty Trash.

steipete/maintainer-orchestrator

Open-source maintainer orchestration: Codex app workers, work recovery, dependencies, vision, releases.

steipete/markdown-converter

Markdown conversion: PDF, Office, HTML, data, OCR, audio, ZIP, YouTube.

相關技能