ZedでClaude Agentを使う手順 — Zed Agentとの認証・課金の違い

ZedでClaudeを使う経路は3つあります。Zed AgentにAnthropic APIキーを設定する方法、ACP経由のExternal AgentとしてClaude Agentを入れる方法、Terminal ThreadsでClaude Code CLIをそのまま動かす方法です。3つは認証も課金も別々で、Zed Agentに入れたAPIキーはClaude Agentには効きません。

Claude Agentは、Zedとは別プロセスのExternal Agentです。以下では、ACP Registryから入れる手順と、認証・課金が3経路でどう分かれるかを扱います。

Claude AgentはZedのExternal Agentとして動く

Claude Agentは、Agent Client Protocol(ACP)でZedにつながるExternal Agentです。Zedはスレッドの表示先(Agent PanelとThreads Sidebar)を提供します。実行環境・認証・モデル選択・ツール・ネイティブ設定は、多くの場合External Agent側が持ちます。

つまりClaude Agentのスレッドは、Zed組み込みのZed Agentとは別プロセスです。Zedは通信の窓口になるだけで、Claudeとの契約関係には入りません。課金・法的条件・データの保持と扱いは、利用者とエージェント提供元の間の話です。ZedはExternal Agentに課金しません。

ACP RegistryからClaude Agentを入れる手順

導入はACP Registry経由が基本です。Zedのコマンドパレットで zed: acp registry を実行すると、レジストリが開きます。

設定画面から入る場合は次の順です。

1. コマンドパレットで agent: open settings を実行してAgent Settingsを開く
2. External Agentsページへ移る
3. Add Agent を押し、Install from Registry を選ぶ
4. 一覧からClaudeを選んでインストールする

インストール後、Claude AgentはAgent PanelとThreads Sidebarの新規スレッドメニューに並びます。メニューまたはエージェントセレクターから選べば、Claude Agentのスレッドが始まります。特定のエージェント用のキーバインドを作りたいときは、agent: new external agent thread アクションが使えます。

レジストリの一覧は絞り込まれたもので、網羅ではありません。Claudeのほか、Codex、OpenCode、Copilot、Cursor、Pi Coding Agentなどが「よく使われるExternal Agent」として挙がっています。最新の一覧はZed内のACP Registryで確認します。

Zed Agentに入れたAPIキーは引き継がれない

ここが最も混同しやすい点です。Zed Agentの設定にAnthropic APIキーを入れても、Claude Agentには自動で設定されません。Claude Agentは自前の認証と課金を持つためです。

Zed Agent側でAPIキーを使う手順は、Agent SettingsのAnthropic欄にキーを入れる形です。AnthropicアカウントにAPIクレジットがあることが前提で、Zedはローカルのプロセス環境変数 ANTHROPIC_API_KEY も読みます。この経路の請求はAnthropic APIの従量課金です。

Claude Agentの認証は、これとは独立して行います。Claude Agentのスレッドを開き、/login を実行します。選べるのはAPIキーでの認証か、対応している環境でのClaude Code認証です。どちらを選ぶかが、そのまま課金方法の選択になります。

リモートプロジェクトでは、さらに注意が要ります。External Agentは資格情報をローカル、リモート、または自前のサインインフローのどれかで読みます。Zedのキーチェーンに保存したLLMプロバイダーのAPIキーが、External Agentの資格情報と同じになるわけではありません。SSHや開発コンテナで使うときは、Claude Agent側でどこに資格情報を置くかを確かめておくと、認証エラーの切り分けが早くなります。

Claudeのログイン方法そのもの(claude.ai、APIキー、OAuthトークン)の違いは、Claude Codeログイン方法3種の使い分けで扱っています。

3つの経路を認証・課金で並べる

Zedの公式ドキュメントは、Claude関連の経路を次の3つに分けています。

Claude ProとMaxのサブスクリプションは、Anthropic APIクレジットとは別物です。ZedのドキュメントはClaudeのProとMaxについて「Zedに直接のLLMプロバイダー経路はない」と書き、サブスクリプションの上限に沿った挙動が欲しいときはClaude AgentかClaude Codeを使う、と案内しています。

Zed ProやZed Businessのサブスクリプションは、Zedがホストするモデルにだけ使えます。ここにClaude Agentは含まれません。

Terminal ThreadsでClaude Code CLIを動かす方式との選び分け

Terminal Threadsは、ACPを通さずに、CLIやTUIをそのままターミナルで動かすスレッドです。Threads Sidebarに並ぶ点はExternal Agentと同じですが、中身はネイティブのコマンドラインツールです。

Terminal ThreadでClaude Codeを毎回起動するなら、agent.terminal_init_command が使えます。Terminal Threadのシェルが作られるたびに、指定したコマンドを自動で流す設定です。

{
  "agent": {
    "terminal_init_command": "claude"
  }
}

コマンドは、自分で打ったかのようにシェルへ送られます。実行後もターミナルは通常の対話シェルのままです。設定画面の「Terminal Thread Init Command」欄からも同じことができます。

Claude Codeの完了通知をZedで受け取りたいときは、Claude Codeのユーザー設定で preferredNotifChannel を "terminal_bell" にします。Claude Code内で /config を開き、Local Notifications から Terminal Bell を選んでも同じです。tmuxの中でClaude Codeを動かすと、ベルが外側のターミナルまで届かないことがあります。その場合は ~/.tmux.conf に set -g allow-passthrough on を足します。

{
  "preferredNotifChannel": "terminal_bell"
}

サブスクリプションで使いたいとき、どちらを選ぶか

現状、Claude Agent(ACP)でもサブスクリプションの上限で使えます。Claude Agentのスレッドで /login を実行し、Claude Code認証を選べばサブスクリプション側の扱いになり、Terminal ThreadでCLIを動かす場合も同じです。ZedのドキュメントもClaude Pro / Maxの対応先として、Claude AgentとClaude Codeの両方を挙げています。別枠のAgent SDKクレジットは存在せず、サブスクリプションの上限も変わっていません。

分かれ目になるのは、Anthropicが予告した請求変更です。Zedのブログによると、ACP経由のClaude Code利用をサブスクリプションの上限から切り離し、プランごとの月次クレジット(Proは20ドル、Max 5xは100ドル、Max 20xは200ドル)で扱う計画でした。ただしブログ冒頭の注記のとおり、Anthropicはこの変更がまだ有効になっていないと購読者に伝えています。計画は改訂中で、有効にする前に事前告知があるとされています。

この変更が有効になった場合に限り、公式CLIをTerminal Threadの中で動かす方式が、サブスクリプションの上限に残る経路になります。ブログはCLIの利用分を、新クレジットではなくサブスクリプションの上限から引かれると説明しています。

判断の軸は次のとおりです。

• 従量のAPI課金で使うなら、Zed AgentにAPIキーを入れるか、Claude Agentの /login でAPIキーを選ぶ
• サブスクリプションの上限で使うなら、今はClaude Agent(/login でClaude Code認証)もTerminal ThreadのCLIも選べる。請求変更が有効になったら、CLI方式に寄せる選択肢が出てくる
• Zedのエディター機能(差分レビューUI、Agent Panelでの操作)に寄せたいなら、Claude Agent

請求の扱いは変わる可能性があるので、実際の消費は自分のClaude側の使用量画面で確かめるのが確実です。「サブスクリプションが有効なのに使用量クレジットを求められる」ときの切り分けは、Usage credits requiredが出る原因と対処にあります。

CLAUDE.mdはClaude Agentが直接読む

Zedのドキュメントによると、CLAUDE.md のようなClaude固有のファイルは、Claude Agentが直接読むことがあります。つまりZedの「Instructions」機能にルールを重複して書かなくても、リポジトリの CLAUDE.md が効く構成にできます。

ここでZed側の設定との境界を押さえておきます。External Agentの設定の持ち主は次のように分かれます。

Claude Agentに守らせたい規約は、CLAUDE.md に置きます。次はその一例です。

# プロジェクト規約
 
- テストは `pnpm test` で実行し、失敗したら修正してから報告する
- 型エラーは `pnpm typecheck` で確認する
- 公開APIの変更は必ずCHANGELOG.mdに追記する

このように、実行コマンドと完了条件を書いておく形です。Claude Code側の CLAUDE.md の読み込み順や置き場所は、Claude Code全体像から辿れます。

MCPを使うときは、ツールが見えないと感じたら両方を疑います。Zedで設定したMCPサーバーがACP経由で転送されているか、Claude Agent側のネイティブなMCP設定が読まれているか、の2か所です。

つまずいたときの確認先

Claude Agentのスレッドで想定と違う挙動が出たときは、Zedとエージェントのやり取りを直接見られます。コマンドパレットで dev: open acp logs を実行すると、ZedとExternal Agentの間のACPメッセージが開きます。不具合を報告するときも、このログを添えるよう案内されています。

過去のスレッドをZedに取り込むこともできます。Threads Sidebarを cmd-alt-j(WindowsとLinuxは ctrl-alt-j)で開き、Thread HistoryのImport Threadsから、設定済みのExternal Agentを選びます。作業ディレクトリのないセッションは飛ばされ、すでに履歴にあるスレッドは重複して入りません。取り込まれたスレッドはアーカイブ扱いで、開くと復元されて続きから作業できます。

まとめ

Claude AgentはZedのExternal Agentで、認証と課金を自前で持ちます。Zed Agentに設定したAnthropic APIキーは引き継がれず、Claude Agentのスレッドで /login を実行して、APIキーかClaude Code認証を選び直します。従量のAPI課金ならAPIキー、サブスクリプションの上限で使うなら、今のところClaude Agent(Claude Code認証)でもTerminal ThreadのCLIでも可能です。予告された請求変更が有効になった場合は、CLI方式が上限に残る経路になります。Zedのスレッド画面で使うならClaude Agentです。

Terminal ThreadsでCLIを使う場合の詳しい認証は、CLI側の話になります。VS Codeでの使い方はClaude Code VS Code拡張機能の使い方、JetBrainsでの使い方はClaude Code JetBrainsプラグインの導入と設定で扱っています。