1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@taka_yayoi(Takaaki Yayoi)inデータブリックス・ジャパン株式会社

WindowsでClaude Code + Databricks連携を設定する際の落とし穴4つ

Last updated at Posted at 2026-02-02

はじめに

Claude Code for VS CodeをWindows環境にインストールし、Databricks経由で利用するまでの手順をまとめます。「拡張機能を入れるだけ」と思っていたら意外とハマりどころが多かったので、手順と併せて実際に遭遇した問題と解決策も記録します。

Databricks CLIのインストール手順は別記事にまとめているので、ここではClaude Code固有の話に絞ります。

前提

  • Windows 10/11
  • VS Code
  • Databricksワークスペースへのアクセス権限

Step 1: VS Codeのインストール

Visual Studio Code公式サイトからWindows用のインストーラーをダウンロードして実行します。

スクリーンショット 2026-02-02 091404.png
スクリーンショット 2026-02-02 091601.png
スクリーンショット 2026-02-02 091633.png
スクリーンショット 2026-02-02 091800.png

インストール時のオプションはデフォルトのままで問題ありません。「PATHへの追加」にチェックが入っていることだけ確認してください。

Step 2: Git for Windowsのインストール

これが最初のハマりポイントでした。 VS Code拡張機能をインストールしてチャットパネルを開くと、いきなり以下のエラーが出ます。

Error: Claude Code on Windows requires git-bash (https://git-scm.com/downloads/win).
If installed but not in PATH, set environment variable pointing to your bash.exe,
similar to: CLAUDE_CODE_GIT_BASH_PATH=C:\Program Files\Git\bin\bash.exe

スクリーンショット 2026-02-02 095440.png

Claude Codeは内部的にbashシェルでコマンドを実行する設計になっています。macOS/Linuxにはbashが標準搭載されていますが、Windowsにはないため、Git for Windowsに同梱されているGit Bashが必要です。Gitのバージョン管理機能が必要なわけではなく、bash環境の提供元としてGit for Windowsが前提になっています。

Git for Windows からダウンロードしてインストールしてください。既にインストール済みでPATHに通っていない場合は、後述のVS Code設定で CLAUDE_CODE_GIT_BASH_PATH を指定することでも対応できます。

スクリーンショット 2026-02-02 100204.png
スクリーンショット 2026-02-02 100310.png
スクリーンショット 2026-02-02 100339.png
スクリーンショット 2026-02-02 100353.png
スクリーンショット 2026-02-02 100558.png
スクリーンショット 2026-02-02 100650.png

Step 3: Claude Code for VS Codeのインストール

  1. VS Codeを開く
  2. Ctrl+Shift+X で拡張機能ビューを開く
  3. 検索ボックスに「Claude Code」と入力
  4. 発行元が「Anthropic」 の公式拡張機能を選択してインストール

スクリーンショット 2026-02-02 091934.png
スクリーンショット 2026-02-02 091950.png
スクリーンショット 2026-02-02 092151.png
スクリーンショット 2026-02-02 092246.png

インストール後に拡張機能が表示されない場合は、コマンドパレット(Ctrl+Shift+P)から「Developer: Reload Window」を実行してください。

インストールが完了すると、エディタ右上に Sparkアイコン(✱)が表示されます。これをクリックするとチャットパネルが開きます。初回起動時にはAnthropicアカウントの認証画面が表示されるので、画面の指示に従って完了してください。

スクリーンショット 2026-02-02 092316.png

Anthropicに直接接続する場合(Claude Pro/Maxプランなど)はこの時点で使い始められます。Databricks経由で使う場合は次のステップに進んでください。

補足: CLIの別途インストールは不要です。 VS Code拡張機能にCLIが同梱されているため、チャットパネルから使う分にはこれだけでOKです。VS Code外のターミナル(Windows TerminalやPowerShell単体)からもClaude Codeを使いたい場合のみ、別途CLIをインストールします。

Step 4: Databricks連携の設定

Databricksのモデルサービング経由でClaude Codeを使うための設定です。

Databricksでパーソナルアクセストークン(PAT)を発行

  1. Databricksワークスペースにログイン
  2. サイドメニューのサービングにアクセス
  3. コーディングー絵ジェント連携のGet Startedをクリック
  4. Other Integrationsタブをクリックし、Claude Codeを選択
  5. Defalut Anthropic Modelでdatabricks-claude-opus-4-5を選択
  6. Default Sonnet Model (Optional) でdatabricks-claude-sonnet-4-5を選択
  7. APIキーを生成をクリックし、表示されたJSONの設定情報をコピーして保管(一度しか表示されません)

設定ファイルの場所に注意(ハマりポイント)

Databricksのモデルサービング画面にある「コーディングエージェントを統合(Integrate Coding Agents)」パネルには、以下のような設定が表示されます。

Screenshot 2026-02-02 at 11.09.27.png

この画面で提示される設定は ~/.claude/settings.json に書く形式、つまりCLI前提の書き方です。

{
  "env": {
    "ANTHROPIC_MODEL": "databricks-claude-sonnet-4-5",
    "ANTHROPIC_BASE_URL": "https://<ワークスペースURL>/serving-endpoints/anthropic",
    "ANTHROPIC_AUTH_TOKEN": "<パーソナルアクセストークン>"
  }
}

VS Code拡張機能を使う場合はこの設定場所ではダメです。 VS Code拡張はClaude Codeプロセスを起動する前に環境変数を渡す必要があるため、VS Codeの User Settings に claudeCode.environmentVariables として書く必要があります。

使い方 設定場所 形式
ターミナルからCLIで使う ~/.claude/settings.json の env { "env": { "KEY": "VALUE" } }
VS Code拡張で使う VS Codeの settings.json { "claudeCode.environmentVariables": [...] }

VS Codeの設定を編集

Ctrl+Shift+P → 「Preferences: Open User Settings (JSON)」で設定ファイルを開き、以下を追加します。

{
  "claudeCode.preferredLocation": "panel",
  "claudeCode.environmentVariables": [
    { "name": "ANTHROPIC_BASE_URL", "value": "https://<ワークスペースURL>/serving-endpoints/anthropic" },
    { "name": "ANTHROPIC_AUTH_TOKEN", "value": "<パーソナルアクセストークン>" },
    { "name": "ANTHROPIC_CUSTOM_HEADERS", "value": "x-databricks-use-coding-agent-mode: true" },
    { "name": "ANTHROPIC_MODEL", "value": "databricks-claude-sonnet-4-5" },
    { "name": "ANTHROPIC_DEFAULT_SONNET_MODEL", "value": "databricks-claude-sonnet-4-5" }
  ]
}

各環境変数の役割は以下のとおりです。

環境変数 役割
ANTHROPIC_BASE_URL Databricksのプロキシエンドポイント
ANTHROPIC_AUTH_TOKEN Databricksのパーソナルアクセストークン
ANTHROPIC_CUSTOM_HEADERS コーディングエージェントモードの有効化
ANTHROPIC_MODEL メインで使用するモデル
ANTHROPIC_DEFAULT_SONNET_MODEL Sonnetモデルのデフォルト指定(後述の404対策)

Git for WindowsがPATHに通っていない場合は、以下も追加してください。

{ "name": "CLAUDE_CODE_GIT_BASH_PATH", "value": "C:\\Program Files\\Git\\bin\\bash.exe" }

ANTHROPIC_DEFAULT_SONNET_MODEL が必要な理由(ハマりポイント)

上記の設定で ANTHROPIC_DEFAULT_SONNET_MODEL を省略すると、以下の404エラーが発生します。

API Error: 404 The given endpoint does not exist, please retry after
checking the specified model and version deployment exists.

厄介なのは、curl でエンドポイントを直接叩くと正常に応答が返ることです。エンドポイント自体は問題ないのに、Claude Codeからだと404になります。

切り分けの結果、原因は ANTHROPIC_DEFAULT_SONNET_MODEL の未指定でした。ANTHROPIC_MODEL にモデルを指定していても、Claude Codeは内部処理の一部で必ず ANTHROPIC_DEFAULT_SONNET_MODEL を参照するパスがあります。この値が未指定だと、Anthropic APIのデフォルトモデル名(例: claude-sonnet-4-5-20250929)で呼び出すため、Databricksのエンドポイントには存在せず404になります。

ANTHROPIC_MODEL の値がSonnetでもOpusでも関係なく発生するので、Databricks経由で使う場合は ANTHROPIC_DEFAULT_SONNET_MODEL の指定が必須です。

Step 5: 動作確認

設定後、VS Codeを再起動します。

  1. エディタ右上のSparkアイコン(✱)をクリックしてチャットパネルを開く
  2. 初回はAnthropicアカウントの認証画面が表示されるので、画面の指示に従って完了する
  3. チャットパネルでメッセージを送信し、応答が返ることを確認

スクリーンショット 2026-02-02 102100.png

接続先のモデルを確認するには、チャットパネルで /model と入力します。Databricks経由であれば databricks-claude-sonnet-4-5 のようなモデルIDが表示されます。

トラブルシューティング: curlでの接続確認

404エラーが出た場合、curl でエンドポイントの疎通確認をすると原因の切り分けに役立ちます。

curl -X POST "https://<ワークスペースURL>/serving-endpoints/anthropic/v1/messages" ^
  -H "Authorization: Bearer <パーソナルアクセストークン>" ^
  -H "Content-Type: application/json" ^
  -d "{\"model\":\"databricks-claude-sonnet-4-5\",\"max_tokens\":100,\"messages\":[{\"role\":\"user\",\"content\":\"hello\"}]}"

これで正常に応答が返るならエンドポイント自体は問題なく、Claude Code側の設定(モデル名の指定漏れなど)が原因です。curl でも404になる場合は、ワークスペースURL、トークン、モデル名が正しいか確認してください。

Step 6: Databricks Appsのローカル実行環境(オプション)

Databricks Appsをローカルで開発・テストする場合、追加の準備が必要です。

uvのインストール

databricks apps run-local コマンドはPythonパッケージマネージャーの uv を内部的に使用します。PowerShellで以下を実行します。

winget install astral-sh.uv

.python-version の作成(ハマりポイント)

uvのインストール後に databricks apps run-local を実行すると、以下のようなビルドエラーが出ることがあります。

Failed to build `pillow==10.4.0`
The headers or library files could not be found for zlib,
a required dependency when compiling Pillow from source.

Pillow 10.4.0 does not support Python 3.14 and does not provide prebuilt Windows binaries.
We do not recommend building from source on Windows.

原因は、uvがデフォルトで最新のPython(現時点では3.14)をインストール・使用することです。Pillowなどのパッケージはまだ Python 3.14向けのプリビルトバイナリ(wheel)をWindows向けに提供していないため、ソースからのビルドが走り、zlibが見つからず失敗します。

解決策は、プロジェクトルートに .python-version ファイルを置いてPythonバージョンを固定することです。uvはこのファイルを自動で読むため、databricks apps run-local の内部動作にも効きます。

注意: PowerShellの echo はUTF-16で出力するため、uvが読み取れずエラーになります。

error: failed to read from file `.python-version`: stream did not contain valid UTF-8

UTF-8で書き出す必要があります。

[System.IO.File]::WriteAllText("$PWD\.python-version", "3.12`n")

これでPython 3.12が使われ、プリビルトwheelが利用されるためビルドエラーは発生しなくなります。

この問題はWindows固有です(macOS/Linuxではプリビルトwheelが提供されているため発生しません)が、.python-version をリポジトリに含めておけばPythonバージョンの統一にもなるので、他のOSでも害はありません。

まとめ

Windows環境でClaude Code for VS Code + Databricks連携を動かすまでのポイントです。

  • Git for Windowsが必須: Claude Codeの内部動作にbashが必要なため
  • CLIと拡張機能は別物: VS Code拡張だけで使うならCLIの別途インストールは不要
  • 設定ファイルの場所が違う: Databricksが提示する ~/.claude/settings.json はCLI用。VS Code拡張では claudeCode.environmentVariables に書く
  • ANTHROPIC_DEFAULT_SONNET_MODEL の指定が必須: ANTHROPIC_MODEL だけでは不十分で、これがないと404エラーになる
  • Databricks Appsのローカル実行にはuvと .python-version が必要: uvがデフォルトで最新Python(3.14)を使い、Windows向けプリビルトwheelがないパッケージでビルドエラーになる。Python 3.12を指定して回避

参考リンク

はじめてのDatabricks

はじめてのDatabricks

Databricks無料トライアル

Databricks無料トライアル

1
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
1
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?