指南 · SSH 代理程式

你的 SSH 金鑰，
放在保險庫裡。

Triwarden 能像 ssh-agent 一樣回應 ssh 與 git，金鑰來自保險庫中的 SSH 金鑰項目。私密金鑰永遠不會離開 App，每一次簽署都會先問你。

ssh 請代理程式簽署。Triwarden 先問你（Touch ID 或 Mac 密碼），在 App 內完成簽署，只把簽章送回去。

設定

四個步驟，
大約兩分鐘。

01
開啟代理程式
打開 Triwarden › 設定 › 開發者，開啟 使用 Triwarden 作為 SSH 代理程式。App 開著時它就會運作，而且只在保險庫解鎖時提供金鑰。
02
加入金鑰
新增一個 SSH 金鑰項目。按 產生 Ed25519 金鑰建立新的，或貼上你已有的私密金鑰 — 未加密的 OpenSSH 金鑰（-----BEGIN OPENSSH PRIVATE KEY-----）。Ed25519、ECDSA（P-256、P-384、P-521）與 RSA 都支援，其他 Bitwarden App 存的 SSH 金鑰也會出現。
金鑰有密語？代理程式無法使用加密的金鑰。先做一份未加密的副本，貼進項目後刪除副本 — 之後由保險庫替它加密。
Remove a passphrase (on a copy)
```
$ cp ~/.ssh/id_ed25519 /tmp/key
$ ssh-keygen -p -N "" -f /tmp/key
# paste /tmp/key into the item, then:
$ rm /tmp/key
```
03
讓 ssh 找到它
把代理程式加入 ~/.ssh/config — 設定 › 開發者 › SSH 設定有個拷貝按鈕，路徑已幫你填好。也可以只對單一 Shell 設定。
建議用設定檔：從 Dock 開啟的 App（VS Code、Tower、Fork、Xcode）讀不到 Shell 的變數，但每個 ssh 都會讀設定檔。
~/.ssh/config
```
Host *
  IdentityAgent "~/Library/Group Containers/…/agent.sock"
```
zsh
```
$ export SSH_AUTH_SOCK="$HOME/Library/Group Containers/…/agent.sock"
```
04
確認可以用
ssh-add -L 會列出代理程式提供的公開金鑰。什麼都沒有？請看下方的解決方法。
Terminal
```
$ ssh-add -L
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKx…Qx9 GitHub
ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIM2…7mK homelab
```

日常使用

所有用到 ssh
的地方。

GitHub 與 GitLab

把項目的公開金鑰貼到 GitHub › Settings › SSH and GPG keys，類型選 Authentication key（GitLab：User settings › SSH keys）。然後測試：

Terminal

$ ssh -T git@github.com
# Triwarden asks: allow “ssh” to sign with “GitHub”
Hi alexchen! You've successfully authenticated, but GitHub does not provide shell access.

你的伺服器

把公開金鑰放進伺服器上的 ~/.ssh/authorized_keys，然後照常 ssh 登入。網路上傳的只有簽章。

Terminal

$ ssh alex@nas.home.arpa 'cat >> ~/.ssh/authorized_keys' < homelab.pub
$ ssh alex@nas.home.arpa

簽署的 git commit

在金鑰頁面上，Git 簽署 › 拷貝設定會給你這三行。把同一把公開金鑰加到 GitHub 作為 Signing key，你的 commit 就會顯示 Verified。

Git signing › Copy Setup

$ git config --global gpg.format ssh
$ git config --global user.signingkey "key::ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKx…Qx9 GitHub"
$ git config --global commit.gpgsign true

也想在本機驗證簽章，就列出你信任的金鑰：

Terminal

$ echo "alex@example.com ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIKx…Qx9" >> ~/.ssh/allowed_signers
$ git config --global gpg.ssh.allowedSignersFile ~/.ssh/allowed_signers
$ git log --show-signature -1
Good "git" signature for alex@example.com with ED25519 key SHA256:…

多把金鑰

金鑰很多時，伺服器可能在試到正確那把之前就回報「Too many authentication failures」。把那把金鑰的公開部分存成檔案，並指定給該主機：

~/.ssh/config

Host github.com
  IdentityFile ~/.ssh/github.pub
  IdentitiesOnly yes

只用於部分主機

其他主機想繼續用別的代理程式？只讓指定的主機使用 Triwarden：

~/.ssh/config

Host github.com gitlab.com nas.home.arpa
  IdentityAgent "~/Library/Group Containers/…/agent.sock"

Git App 與編輯器

VS Code、Tower、Fork、Xcode 以及任何使用系統 ssh 的 App 都會讀 ~/.ssh/config，完成第 3 步後就能用，核准提示也一樣會出現。

核准

沒有你，
什麼都不會簽署。

每個請求都會寫明程式與金鑰 —「允許 ssh 以 SSH 金鑰 GitHub 簽署」。在設定 › 開發者 › 簽署前詢問 選擇多久問一次：

每次: 預設：每次簽署都會詢問
每個 App 每分鐘一次: 適合連續好幾次 git fetch
每個 App 每 10 分鐘一次: 適合長時間工作；鎖定後就會忘記

沒有 Touch ID — Mac mini、Mac Studio，或闔上螢幕？macOS 會改為詢問 Mac 密碼，按拒絕即可拒絕。設定 › 開發者會列出最近幾次的請求，無論允許或拒絕。

解決方法

如果它
不能用。

「The agent has no identities.」

保險庫已鎖定、代理程式沒開、沒有 SSH 金鑰項目，或項目裡的金鑰有密語（加密的金鑰不會被提供）。

「Could not open a connection to your authentication agent」

這個 Shell 不知道代理程式在哪。把 IdentityAgent 那行加入 ~/.ssh/config，或在該 Shell 執行第 3 步的 export。

「agent refused operation」

請求被拒絕，或提示放著直到逾時。重新執行指令並核准即可。

「Too many authentication failures」

伺服器在試到正確的金鑰前就放棄了。把金鑰指定給該主機（見上方「多把金鑰」）。

隨時可以開始。

所有功能免費試用，包括 SSH 代理程式。

下載 Mac 版

四個步驟，大約兩分鐘。

開啟代理程式

加入金鑰

讓 ssh 找到它

確認可以用

所有用到 ssh的地方。

GitHub 與 GitLab

你的伺服器

簽署的 git commit

多把金鑰

只用於部分主機

Git App 與編輯器

沒有你，什麼都不會簽署。

如果它不能用。

隨時可以開始。

四個步驟，
大約兩分鐘。

所有用到 ssh
的地方。

沒有你，
什麼都不會簽署。

如果它
不能用。