1Password Developer ワークフロー

このスキルは 1Password 開発者ツールチェーンをカバーしています。SSHエージェント経由のSSHキー管理、Environments 経由のシークレット注入、および op CLI を含みます。

クイックリファレンス

ツール	目的
1Password Desktop App	SSHエージェント、キーのインポート、環境管理
op CLI (安定版)	アイテム管理、シークレット参照、op run、op inject
op CLI (ベータ版)	op run --environment と op environment read を追加
SSH Agent	1Password のボールトから SSH/Git クライアントにキーを提供
Environments	環境変数をランタイムに保存・注入（ディスク上の平文なし）

SSHキー管理

サポートされているキーの種類

1Password がサポートするのは、これらの SSH キータイプのみです:

• Ed25519（推奨、最速、最も安全）
• RSA: 2048、3072、4096ビットのみ

非対応: ECDSA、DSA、4096ビットを超える RSA キー（例：6096ビット）、PuTTYgen の .ppk 形式

インポート前にキーの種類とサイズを確認します:

ssh-keygen -lf ~/.ssh/your_key
# Output: 256 SHA256:abc... user@host (ED25519)
# Output: 4096 SHA256:xyz... user@host (RSA)

SSHキーのインポート

CLI は既存の SSH キーをインポートできません。これはデスクトップアプリのみの操作です。

公式ドキュメントから: 「既存の SSH キーをインポートするには、1Password デスクトップアプリを使用してください。」

デスクトップアプリでインポートするには:

1. サイドバーのターゲットボールトに移動
2. 新規アイテム > SSH Key を選択
3. 秘密鍵を追加 > キーファイルをインポート を選択
4. キーファイルに移動してインポート
5. キーにパスフレーズがある場合は、1 回入力
6. 保存

CLI は新しいキーを生成することのみ可能です:

op item create --category ssh --ssh-generate-key ed25519 --title "My New Key" --vault Private

SSHキーの Watchtower

1Password Developer Watchtower（Developer > View Watchtower）は ~/.ssh/ をスキャンして表示します:

• Needs Attention: ディスク上の暗号化されていないキー
• Recommendations: インポートまたは管理可能なキー

一部のキーは「Import」ボタンを表示し、他は「Show in Finder」ドロップダウンのインポートオプション付きで表示します。

SSHエージェントのセットアップ

1Password SSHエージェントは、秘密鍵を SSH クライアントに公開することなく、ボールトからキーを提供します。

macOS エージェントソケット: ~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock

アプリで有効化: Settings > Developer > Set Up SSH Agent

SSH クライアントを設定 (~/.ssh/config):

Host *
  IdentityAgent "~/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock"

エージェントがキーを認識することを確認:

SSH_AUTH_SOCK="$HOME/Library/Group Containers/2BUA8C4S2C.com.1password/t/agent.sock" ssh-add -l

カスタムボールト用のエージェント設定

デフォルトでは、エージェントは組み込みの Personal、Private、または Employee ボールトからのみキーを提供します。共有またはカスタムボールトの場合、~/.config/1Password/ssh/agent.toml を作成します:

[[ssh-keys]]
vault = "Private"

[[ssh-keys]]
vault = "Bridge"

[[ssh-keys]]
vault = "Business"

ボール名またはボールト UUID を使用できます。ボールト ID は以下で取得します:

op vault list --format=json | jq -r '.[] | "\(.id) \(.name)"'

重要: このファイルを作成すると、デフォルト動作が完全にオーバーライドされます。作成した場合は、Private/Personal ボールトを明示的に含める必要があります。そうしないと、そのキーは利用できなくなります。

1Password アプリは新しく作成された agent.toml ファイルを検出するために、終了して再起動が必要な場合があります。

キーが 1Password に保存された後の使用

キーが 1Password に保存され、エージェントが設定されたら、~/.ssh/config を更新して IdentityFile が公開鍵（秘密鍵ではなく）を指すようにします。公開鍵はエージェントにどのキーを提供するかを示すヒントとして機能します:

# 前（ディスク上の秘密鍵）
Host github.com
  IdentityFile ~/.ssh/my_key

# 後（公開鍵がエージェントにヒント、秘密鍵は 1Password に保存）
Host github.com
  IdentityFile ~/.ssh/my_key.pub

公開鍵は秘密ではなく、ディスク上に保存できます。このアプローチは SSH サーバーの 6 キー制限も回避します。

1Password Environments

Environments は、キーバリューペア（.env ファイルなど）を 1Password に保存し、ランタイムで利用可能にします。

Environment の作成

デスクトップアプリで実行: Developer > View Environments > New Environment。既存の .env ファイルから変数をインポートするか、手動で追加できます。

op run --environment でシークレットを注入

これが推奨されるアプローチです。ベータ CLI（v2.33.0-beta.02 以降）が必要です:

op run --environment <environment-id> -- npm run dev

動作方法:

1. プロセス開始時に 1 回認証
2. op が Environment からすべての変数をフェッチ
3. 変数は環境変数としてサブプロセスに注入
4. シークレットはプロセスの期間中のみ存在
5. stdout/stderr に表示されるシークレット値は自動的にマスク

環境 ID を取得: アプリで Environment を選択 > Manage environment > Copy environment ID。

その他のツールチェーンのラップ

op run は npm だけでなく、任意のコマンドで機能します。環境変数をサブプロセスに注入するため、他のツールチェーンとスタック可能です:

# Node.js
op run --environment <env-id> -- npm run dev

# Python with uv
op run --environment <env-id> -- uv run python my_script.py

# Python with venv
op run --environment <env-id> -- python my_script.py

# Docker
op run --environment <env-id> -- docker compose up

# 任意のコマンド
op run --environment <env-id> -- <your-command>

これは長時間実行されるサーバーのないリポジトリ（スタンドアロンスクリプト、データパイプライン、自動化ジョブ）にも機能します。スクリプトが load_dotenv() と os.getenv() を使用している場合、ディスク上の平文の .env ファイルを削除すれば、op run がシークレットの唯一のソースになります。コード変更は不要です。

マスキングの問題

op run は stdout/stderr テキストのうち、シークレット値と一致するものをマスクします。環境変数に短い一般的な文字列（/sign-in、info、true、root、3306 など）が含まれている場合、通常のログ出力に表示されるため問題が生じます。

解決策: 変数を 2 つのグループに分割:

• 1Password Environment: 実際のシークレット（API キー、パスワード、トークン、接続文字列、認証情報）
• ディスク上の .env.local: 非シークレット設定（URL パス、ログレベル、機能フラグ、ポート番号、データベース名）

op run は両方のソースをマージします。Environment からの変数はシェル/.env ファイルのものをオーバーライドします。

Environments の他の使用方法

マウント済み .env ファイル（macOS/Linux のみ）: 1Password は指定されたパスに仮想ファイル（UNIX 名前付きパイプ）を作成します。ファイルが読み込まれるたびに Touch ID が必要です。アプリで設定: Environment > Destinations > Local .env file。

プログラムアクセス:

op environment read <environment-id>

サービスアカウント（CI/CD）: ヘッドレス環境でバイオメトリック認証の代わりにサービスアカウントトークンを使用。同じ op run --environment コマンドが機能します。

CLI リファレンス

インストール

安定版（Homebrew）:

brew install 1password-cli

ベータ版（直接ダウンロード、--environment フラグに必要）:

curl -sS -o /tmp/op_beta.pkg "https://cache.agilebits.com/dist/1P/op2/pkg/v2.34.1-beta.01/op_apple_universal_v2.34.1-beta.01.pkg"
sudo installer -pkg /tmp/op_beta.pkg -target /

ベータ版は /usr/local/bin/op にインストールされます。Homebrew の安定版が PATH で優先される場合はエイリアスを設定します:

alias op=/usr/local/bin/op

リリースノートとベータ版を確認: https://app-updates.agilebits.com/product_history/CLI2

便利なコマンド

# バージョンを確認
op --version

# ボールトを一覧表示
op vault list

# すべてのボールト間の SSH キーを一覧表示
op item list --categories 'SSH Key'

# アイテムの詳細を取得
op item get "Item Name" --vault "Vault" --format json

# 環境注入でを実行
op run --environment <env-id> -- <command>

# シークレット参照を読み取り
op read "op://Vault/Item/Field"

# テンプレートファイルにシークレットを注入
op inject -i config.template -o config.yml

# シークレット参照を含む env ファイルで実行
op run --env-file=.env -- <command>

よくある落とし穴

1. CLI は SSH キーをインポートできません。 新しいキーを生成するだけです。既存のキーはデスクトップアプリでインポートします。

2. agent.toml はデフォルトをオーバーライドします。 設定ファイルを作成する場合、デフォルトの Private ボールトを含む、すべてのボールトを一覧表示する必要があります。

3. agent.toml はアプリの再起動が必要です。 新しく作成された設定ファイルは、再起動するまでアプリが検出しない場合があります。

4. 6096ビット RSA キーはサポートされていません。 1Password の上限は 4096ビット RSA です。インポートを試みる前に ssh-keygen -lf でキーサイズを確認します。

5. ECDSA キーはサポートされていません。 SSH エージェントで機能するのは Ed25519 と RSA のみです。

6. op run のマスキングは積極的です。 ログの破損を避けるため、短い一般的な文字列を 1Password Environments から除外します。シークレットと設定を分割します。

7. ベータ版と安定版 CLI。 op run の --environment フラグはベータチャネルが必要です。安定版 CLI にはまだありません。

ドキュメントリンク

• SSH キー管理: https://developer.1password.com/docs/ssh/manage-keys/
• SSH エージェントのセットアップ: https://developer.1password.com/docs/ssh/agent
• SSH エージェント設定（agent.toml）: https://developer.1password.com/docs/ssh/agent/config/
• Environments: https://developer.1password.com/docs/environments/
• ローカル .env ファイル: https://developer.1password.com/docs/environments/local-env-file/
• op run（シークレット注入）: https://developer.1password.com/docs/cli/secrets-environment-variables/
• シークレット参照: https://developer.1password.com/docs/cli/secret-references/
• CLI リリースノート: https://app-updates.agilebits.com/product_history/CLI2
• フル開発者ドキュメント（LLM対応）: https://developer.1password.com/llms-full.txt