ssh-keychain-unlock

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

SSH Keychain Unlock for Claude Code on macOS

macOS上Claude Code的SSH钥匙串解锁方案

Overview

概述

Claude Code stores credentials in the macOS Keychain (

Claude Code-credentials

service). When accessing a Mac via SSH (no GUI session), the login keychain is locked, causing Claude Code to appear unauthenticated.

Claude Code将凭据存储在macOS钥匙串（

Claude Code-credentials

服务）中。当通过SSH访问Mac（无GUI会话）时，登录钥匙串处于锁定状态，导致Claude Code显示未认证。

When to Use

适用场景

Claude Code says it's not logged in when accessed via SSH

security show-keychain-info ~/Library/Keychains/login.keychain-db

shows the keychain is locked

Setting up a Mac Mini or headless Mac for remote Claude Code usage

通过SSH访问时Claude Code提示未登录

security show-keychain-info ~/Library/Keychains/login.keychain-db

命令显示钥匙串处于锁定状态

为远程使用Claude Code设置Mac Mini或无头Mac

Solutions

解决方案

Option 1: Interactive Unlock on SSH Login

方案1：SSH登录时交互式解锁

Add to

~/.zshrc

bash

undefined

将以下内容添加到

~/.zshrc

：

bash

undefined

Unlock macOS keychain for SSH sessions (needed for Claude Code auth)

if [[ -n "$SSH_CONNECTION" ]]; then security unlock-keychain ~/Library/Keychains/login.keychain-db 2>/dev/null fi


Prompts for macOS login password each SSH session. Simple but requires manual input.

if [[ -n "$SSH_CONNECTION" ]]; then security unlock-keychain ~/Library/Keychains/login.keychain-db 2>/dev/null fi


每次SSH会话都会提示输入macOS登录密码。操作简单但需要手动输入。

Option 2: Auto-Unlock at Boot (Headless)

方案2：开机自动解锁（无头模式）

For fully headless operation with no password prompt:

1. Create password file (

~/.claude/.keychain-password

, permissions

bash

echo 'YOUR_MACOS_PASSWORD' > ~/.claude/.keychain-password
chmod 600 ~/.claude/.keychain-password

2. Create unlock script (

~/.claude/unlock-keychain.sh

, permissions

bash

cat > ~/.claude/unlock-keychain.sh << 'SCRIPT'
#!/bin/bash
security unlock-keychain -p "$(cat ~/.claude/.keychain-password)" ~/Library/Keychains/login.keychain-db
SCRIPT
chmod 700 ~/.claude/unlock-keychain.sh

3. Create LaunchAgent (

~/Library/LaunchAgents/com.claude.unlock-keychain.plist

bash

cat > ~/Library/LaunchAgents/com.claude.unlock-keychain.plist << 'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.claude.unlock-keychain</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>__HOME__/.claude/unlock-keychain.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
PLIST

适用于无需密码提示的完全无头操作：

1. 创建密码文件（

~/.claude/.keychain-password

，权限设置为

）：

bash

echo 'YOUR_MACOS_PASSWORD' > ~/.claude/.keychain-password
chmod 600 ~/.claude/.keychain-password

2. 创建解锁脚本（

~/.claude/unlock-keychain.sh

，权限设置为

）：

bash

cat > ~/.claude/unlock-keychain.sh << 'SCRIPT'
#!/bin/bash
security unlock-keychain -p "$(cat ~/.claude/.keychain-password)" ~/Library/Keychains/login.keychain-db
SCRIPT
chmod 700 ~/.claude/unlock-keychain.sh

3. 创建LaunchAgent（

~/Library/LaunchAgents/com.claude.unlock-keychain.plist

）：

bash

cat > ~/Library/LaunchAgents/com.claude.unlock-keychain.plist << 'PLIST'
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.claude.unlock-keychain</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>__HOME__/.claude/unlock-keychain.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>
PLIST

Fix path

sed -i '' "s|HOME|$HOME|g" ~/Library/LaunchAgents/com.claude.unlock-keychain.plist


**4. Load the agent:**
```bash
launchctl load ~/Library/LaunchAgents/com.claude.unlock-keychain.plist

sed -i '' "s|HOME|$HOME|g" ~/Library/LaunchAgents/com.claude.unlock-keychain.plist


**4. 加载Agent：**
```bash
launchctl load ~/Library/LaunchAgents/com.claude.unlock-keychain.plist

Quick Reference

快速参考

Command	Purpose
`security show-keychain-info ~/Library/Keychains/login.keychain-db`	Check keychain lock status
`security unlock-keychain ~/Library/Keychains/login.keychain-db`	Manually unlock (interactive)
`bash ~/.claude/unlock-keychain.sh`	Test auto-unlock script
`launchctl load ~/Library/LaunchAgents/com.claude.unlock-keychain.plist`	Load LaunchAgent
`launchctl unload ~/Library/LaunchAgents/com.claude.unlock-keychain.plist`	Unload LaunchAgent

命令	用途
`security show-keychain-info ~/Library/Keychains/login.keychain-db`	检查钥匙串锁定状态
`security unlock-keychain ~/Library/Keychains/login.keychain-db`	手动解锁（交互式）
`bash ~/.claude/unlock-keychain.sh`	测试自动解锁脚本
`launchctl load ~/Library/LaunchAgents/com.claude.unlock-keychain.plist`	加载LaunchAgent
`launchctl unload ~/Library/LaunchAgents/com.claude.unlock-keychain.plist`	卸载LaunchAgent

Common Mistakes

常见错误

Wrong permissions on password file - Must be
```
600
```
(owner-only). Others can read your macOS password otherwise.
Forgetting to load the LaunchAgent - Creating the plist isn't enough; run
```
launchctl load
```
to activate it.
Password file out of sync - If you change your macOS password, update
```
~/.claude/.keychain-password
```
too.

密码文件权限错误 - 必须设置为
```
600
```
（仅所有者可访问），否则其他人可能读取你的macOS密码。
忘记加载LaunchAgent - 仅创建plist文件不够，需运行
```
launchctl load
```
命令激活它。
密码文件不同步 - 如果你修改了macOS密码，也要更新
```
~/.claude/.keychain-password
```
文件。