tailscale claude codeの設定と使い方｜APIキー管理を安全に
TailscaleでClaude Codeを安全に使いたいけれど、単にVPNをつなぐだけでよいのか、APIキーをどこに置くべきか分からない人に向けた記事です。Apertureを中継する構成と、個人利用・チーム利用・GitHub Actionsでの違いを整理し、設定から動作確認までの流れを紹介します。
tailscale claude codeは、TailscaleのWireGuardネットワーク上でApertureを中継点にし、APIキーを端末やCIへ配らずClaude Codeを使う構成です。settings.jsonと環境変数、権限設定を整えれば、利用状況を追跡しながら接続できるとわかる。
目次 (9)
tailscale claude codeとは？単なるVPN接続との違い
「tailscale claude code」で検索すると、現在の上位結果はTailscaleのApertureをClaude Codeの接続先にする公式手順が中心です。Tailscaleは端末同士をWireGuardでつなぐネットワークを作り、Apertureはそのネットワーク内でAIプロバイダーへのリクエストを受ける中継点になります。Claude Codeから見ると、Anthropicへ直接アクセスする代わりにApertureへリクエストを送り、Apertureが認証・モデル選択・ログ記録を担当する形です。
この構成の利点は、チームのAPIキーを各PCやリポジトリへ配らずに済むことです。利用者やCIの識別、モデルごとのアクセス権、トークン数や費用、セッションの記録をAperture側へ集約できます。TailscaleをインストールするだけでClaude Codeの接続先が切り替わるわけではなく、Apertureのプロバイダー設定と ANTHROPIC_BASE_URL の指定が必要です。
なお、自宅PCで動くClaude CodeをiPadやスマートフォンから操作したい場合は、TailscaleとSSH、tmuxなどを組み合わせる別の構成もあります。こちらは「ネットワーク越しに端末を操作する」方法であり、ApertureによるAPIキー管理とは目的が異なります。今回の検索意図に合う中心解は、Claude CodeのリクエストをApertureへルーティングする構成です。
出典URL: https://tailscale.com/docs/aperture/how-to/use-claude-code
接続前に必要なものと全体の流れ
Aperture経由でClaude Codeを動かすには、先に管理側の準備が必要です。Apertureは2026年8月時点でベータ提供のため、業務で使う場合は機能範囲と運用条件を確認してから導入してください。公式ドキュメントが示す前提は、Apertureの稼働、少なくとも1つのAIプロバイダー、端末から到達できるホストURL、そしてインストール済みのClaude Codeです。
設定の順番は次のとおりです。
- Tailscale上でApertureのホストへ到達できることを確認する。
- ApertureにAnthropic API、Amazon Bedrock、またはGoogle Vertexのプロバイダーを登録し、利用するモデルを有効にする。
- Claude Codeの接続先をApertureへ向け、クライアント側には実際のAPIキーを置かない。
- Claude Codeでテストメッセージを送り、Apertureのログ画面でリクエストを確認する。
ApertureのホストURLは、公式手順では http:// を使います。これはインターネット上へ平文で公開するという意味ではありません。TailscaleのWireGuardトンネル上を通るため、Tailscaleネットワーク内の通信は暗号化されます。ただし、ApertureをTailscaleの外から公開する構成では条件が変わるため、公開範囲とTLS設定を別途設計してください。
settings.jsonでClaude Codeを接続する手順
手動設定では、Claude Codeのグローバル設定ファイルにApertureのURLを登録します。公式の基本例は次のJSONです。
{
"apiKeyHelper": "echo '-'",
"env": {
"ANTHROPIC_BASE_URL": "http://<aperture-hostname>"
}
}
作業は次の順で進めます。
~/.claude/settings.jsonを開く。Windowsでは通常、ユーザープロファイル配下の.claude\\settings.jsonを確認する。ANTHROPIC_BASE_URLの<aperture-hostname>を、自分のApertureホスト名へ置き換える。apiKeyHelperのecho '-'は残す。Apertureが認証情報を注入するため、ここに本物のキーを書かない。- Claude Codeを起動し、短いテスト依頼を送る。
- 管理者権限でApertureの
http://<aperture-hostname>/ui/を開き、Logsにリクエストが表示されるか確認する。
apiKeyHelper が返すハイフンは、Claude Code側の入力チェックを通すためのプレースホルダーです。Anthropic APIプロバイダーの実キーはAperture側で管理し、端末のシェル履歴、設定ファイル、CIログへ残さない運用にします。テストが成功しても、利用者に過剰なモデル権限を与えていないか、Apertureのアクセス制御を見直してください。
Claude Codeの古いv1系では apiKeyHelper が使えない場合があります。その場合は公式例のように ANTHROPIC_AUTH_TOKEN にプレースホルダーを置き、ANTHROPIC_BASE_URL とモデル名を明示します。設定キーの対応はバージョンで変わるため、エラーが出たときは使用中のClaude CodeのバージョンとAperture公式手順を照合するのが安全です。
出典URL: https://tailscale.com/docs/aperture/how-to/use-claude-code
Aperture CLIなら環境変数をまとめて設定できる
設定ファイルを手で編集したくない場合は、Aperture CLIからClaude Codeを起動できます。CLIはApertureのエンドポイントとプロバイダーを選び、選択内容に応じた環境変数を設定してからClaude Codeを立ち上げる仕組みです。まずターミナルで aperture を実行し、初回はAperture URLを登録します。保存済みのエンドポイントがあれば、次回から自動的に接続できます。
プロバイダーごとに設定される主な変数は次のとおりです。
| 接続先 | 主な環境変数 | 用途 |
|---|---|---|
| Anthropic API | ANTHROPIC_BASE_URL、ANTHROPIC_AUTH_TOKEN、ANTHROPIC_MODEL |
ApertureでAPIキーを集約する |
| Amazon Bedrock | ANTHROPIC_BEDROCK_BASE_URL、CLAUDE_CODE_USE_BEDROCK |
AWS側のモデルを使う |
| Google Vertex | CLOUD_ML_REGION、ANTHROPIC_VERTEX_PROJECT_ID、ANTHROPIC_VERTEX_BASE_URL |
Google Cloud側のモデルを使う |
CLI経由では、Anthropic API向けの認証トークンに - が設定され、実際の認証はApertureが行います。モデルを選択したときは ANTHROPIC_MODEL も設定されます。環境変数を表示する診断コマンドを共有すると、値の取り扱いに注意が必要です。ログやスクリーンショットへトークンを含めないでください。
Tailscaleが端末にインストールされていないCIやコンテナでは、Aperture CLIのブリッジ機能を使える場合があります。ブリッジはプロセス内のTailscaleノードを起動し、ローカルのプロキシを通してApertureへ接続する方式です。すでに端末のTailscale接続が動いているなら、通常は直接接続で足ります。
出典URL: https://tailscale.com/docs/aperture/cli
Claude Pro・Maxを使う場合のパススルー設定
Apertureでは、Anthropic APIの集中管理と、Claude ProやMaxなどのサブスクリプションをそのまま通すパススルーを分けて考えます。パススルーでは、Claude Code自身のOAuthトークンをApertureがAnthropicへ転送します。そのため、APIキー方式の設定を混ぜないことが重要です。
パススルーを使う場合の要点は次のとおりです。
- Aperture側でAnthropicプロバイダーをパススルーモードにする。
- Claude Code側には
ANTHROPIC_BASE_URLだけを設定する。 ANTHROPIC_API_KEYとANTHROPIC_AUTH_TOKENは設定しない。- Claude CodeをClaudeアカウントのOAuth認証で起動する。
APIキーまたは認証トークンを設定すると、Claude Codeが本来転送すべきOAuthトークンの代わりに、その値を送ろうとします。ログインできない、想定と違う課金先になる、Apertureのログに出ないといった問題は、認証方式の混在から起きやすい症状です。会社の共通APIキーを使うのか、個人のサブスクリプションを使うのかを先に決め、不要な環境変数を削除してから接続してください。
BedrockやVertexを使う場合も、Anthropic API向けの変数をそのまま流用しません。公式ページにはバックエンド別の settings.json 例が掲載されているため、プロバイダーに合う接頭辞と認証スキップ設定を選びます。
GitHub ActionsからClaude Codeを経由させる方法
プルリクエストのコードレビューを自動化する場合は、CIランナーを一時的なTailscaleノードとしてtailnetへ参加させ、Apertureで呼び出し元を識別します。個々のリポジトリにAnthropic APIキーを置かず、TailscaleのアイデンティティとApertureの権限で制御できるのがポイントです。
基本的な作業手順は次のとおりです。
- tailnetポリシーに
tag:ciを定義し、CIノードがApertureへ接続できるネットワーク許可と、利用可能なモデルの許可を追加する。 - GitHub Actions用のフェデレーションID、またはOAuthクライアントを作成し、リポジトリにはTailscale接続用の
TS_OAUTH_CLIENT_IDとTS_AUDIENCEなどだけを登録する。 - ワークフローで
tailscale/github-action@v4を先に実行し、tags: tag:ciとping: <aperture-hostname>を指定する。 - 続くClaude Code Actionで
ANTHROPIC_BASE_URLをApertureへ向け、必要な最小権限だけを与える。 - テスト用のプルリクエストを開き、Tailscale接続、Claude Codeの応答、Apertureの利用ログを順番に確認する。
name: AI code review
on:
pull_request:
permissions:
id-token: write
pull-requests: write
contents: read
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: tailscale/github-action@v4
with:
oauth-client-id: ${{ secrets.TS_OAUTH_CLIENT_ID }}
audience: ${{ secrets.TS_AUDIENCE }}
tags: tag:ci
ping: <aperture-hostname>
- uses: anthropics/claude-code-action@v1
with:
anthropic_api_key: "-"
env:
ANTHROPIC_BASE_URL: "http://<aperture-hostname>"
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1"
anthropic_api_key: "-" はActionの空欄チェックを通すための値で、実際のAnthropicキーではありません。Tailscaleのアクションが一時ノードを作成し、Apertureがそのノードのタグと許可を確認してから中央管理のキーでAnthropicへ転送します。ping は接続が成立するまで待つ指定なので、ネットワーク接続前にClaude Codeの処理が始まる問題も防げます。
出典URL: https://tailscale.com/docs/solutions/route-ai-code-reviews-through-aperture
つながらないときに確認するポイント
接続失敗時は、Claude Codeの認証だけを疑うと原因を見失います。次の順番で、ネットワーク、権限、接続先、プロバイダーを切り分けます。
- Tailscaleの端末一覧で、実行端末とApertureホストが同じtailnetに参加しているか確認する。
tailscale ping <aperture-hostname>相当の疎通確認を行い、名前解決と到達性を確認する。ANTHROPIC_BASE_URLのホスト名とプロトコルを確認し、公式手順どおりhttp://を使う。- Apertureのポリシーで利用者、
tag:ci、対象ホスト、対象モデルの許可がそろっているか確認する。 - パススルーならAPIキー変数を、API方式ならプロバイダー設定とキーの有効性を確認する。
- Claude Codeのリクエストを送り、ApertureのLogsに届いているかを管理者画面で確認する。
ログに何も出ない場合は、Claude CodeがApertureへ到達する前に止まっています。逆にログへ出ているのに応答が失敗する場合は、Apertureのモデル許可、プロバイダー認証、モデル名を調べます。GitHub Actionsだけ失敗する場合は、id-token: write の権限、Tailscale接続用シークレット、ping のホスト名を確認してください。診断のためにAPIキーをチャットやIssueへ貼り付けるのは避けます。
Tailscale経由が向く人と、向かない使い方
複数人でClaude Codeを使い、APIキーの配布、利用量の可視化、費用上限、CIの認証をまとめて管理したい組織には、TailscaleとApertureの組み合わせが向いています。ネットワーク上の呼び出し元をTailscaleのタグで識別できるため、リポジトリごとに同じ秘密情報を複製する運用から移行しやすくなります。
一方、個人が1台のPCでClaude Codeを使うだけなら、Apertureの導入・ポリシー・プロバイダー管理が余分な作業になることがあります。スマートフォンから自宅PCのセッションを操作したいだけなら、Remote ControlやSSHのほうが目的に合う場合もあります。また、Apertureはベータ提供のため、重要な開発環境ではログの保持、障害時の迂回経路、権限変更の承認者を決めておくと安心です。
最初はテスト用のモデルとリポジトリで、端末からApertureへ届くこと、認証方式が一つに定まること、ログで利用者と費用を追えることを順番に確認します。問題がなければ対象ユーザーやCIへ広げ、tailnetポリシーは必要なホスト・ポート・モデルだけに絞るのが現実的です。
まとめ
tailscale claude codeの中心的な設定は、Claude Codeの ANTHROPIC_BASE_URL をTailscaleネットワーク内のApertureへ向けることです。APIキー方式ではApertureに認証を集約し、Pro・MaxのパススルーではAPIキー変数を設定しません。GitHub ActionsではTailscaleの一時ノードとApertureの許可を組み合わせることで、秘密情報を各リポジトリへ配らずコードレビューを実行できます。
まずは公式手順の settings.json で単発の接続とログを確認し、その後にAperture CLIやGitHub Actionsへ拡張すると、原因を追いやすく安全に運用できます。
