Claude CodeのVS Codeでファイルリンクが開かない — 日本語・スペースのパス
VS Code拡張のチャットで、スペースや日本語を含むパスのファイルリンクがクリックしても開かない不具合は2.1.284で修正されています。原因と確かめ方、更新できない環境での回避策を載せます。
Claude CodeのVS Code拡張で、チャットに出たファイルリンクをクリックしても何も起きない。そのパスにスペースや日本語が含まれているなら、拡張側の不具合で、2.1.284で修正されています。拡張を更新すれば、回避策は要りません。
更新できない環境向けに、issueで報告された回避策も後半に載せます。
症状: 英数字だけのパスは開き、日本語やスペース入りだけ開かない
anthropics/claude-codeのissue 96612が報告している症状は次のとおりです。
- チャットのMarkdownリンクのうち、ワークスペース相対パスにスペースか非ASCII文字(日本語やアクセント付き文字)を含むものが、クリックしても開かない
- エラーは表示されない
- 英数字だけでスペースのないパスなら、同じ拡張で開く
拡張は、回答中のファイルを [name.md](path/name.md) 形式のリンクで示すようモデルに指示しています。そのため 設計書/概要.md のような名前が多いワークスペースでは、リンクの大半が反応しない状態になります。
issueの起票者は、docs/My Folder/Übersicht.md を再現用のファイルに選んでいます。フォルダ名にスペース、ファイル名に非ASCII文字がある例です。docs/MyFolder/Uebersicht.md に改名すると開いた、とも書かれています。
症状の出る範囲
issueの記述から、症状が出る条件は次の表のとおりです。
| リンク先のパス | 開くか |
|---|---|
docs/overview.md(英数字のみ) | 開くか開く |
docs/My Folder/notes.md(スペースあり) | 開くか開かない |
docs/設計書/概要.md(日本語あり) | 開くか開かない |
docs/Übersicht.md(アクセント付き文字) | 開くか開かない |
日本語の2行目は、issueの条件(非ASCII文字を含むパス)を当てはめた例です。issue自体に日本語パスの再現は載っていません。ただ、コメントには繁体字中国語のフォルダ名で同じ症状が出る報告と、イタリア語のアクセント付き文字で出る報告があります。
原因: エンコード済みのパスがデコードされないまま探される
issueは、2.1.280の同梱ファイルを読んだ結果として、三段階の原因を書いています。
クリックしてから開かないまでの流れ
- 1
チャットの描画
Markdownの変換処理が、リンク先のスペースや非ASCII文字をパーセントエンコードします。
My FolderはMy%20Folder、Üは%C3%9Cになります。 - 2
クリック時の送信
リンクのクリック処理が、エンコードされたままのパスを拡張本体に
open_fileとして送ります。 - 3
拡張本体の検索
拡張本体はそのパス文字列をそのままファイルシステムで探し、見つからないとワークスペース内のあいまい検索にも同じ文字列を渡します。デコード処理がどこにもないので、
My%20Folderという名前のフォルダを探して失敗します。
スペースを含むパスをそのまま書いたリンクは、Markdownの仕様上リンクとして認識されず、ただの文字列として表示されます。%20 で書き直すとリンクにはなりますが、結局上の流れで開けません。
issueの起票者は、file:// 形式のリンクも、command: 形式のリンクも、スペース入りの絶対パスも代替にならないと調べています。VS Codeのwebviewは http、https、mailto、vscode 以外のスキームを開き先に渡さないためです。
過去の報告が直らなかった理由
起票者は、同じ症状の過去の報告を6件挙げています(#10846、#44713、#49218、#50452、#68718、#76328)。いずれも修正されないまま、重複か放置で自動クローズされました。
issue 96612は、それらに足りなかった情報を2つ加える形で立てられています。修正すべき箇所と、利用者側の回避策です。起票者は、自動クローズされないよう、コメントでもこの2点を強調しています。
利用者への影響の大きさも、コメントに残っています。Dev Container上のモノレポで使っていた人は、チャットのリンクを使えるように、約6,400個のファイルとフォルダを改名したと書いています。
2.1.284で修正済み: 更新して確かめる
issueには、2026年10月21日にメンテナーから「2.1.284で修正(9月28日)」とコメントがつき、クローズされています。Claude Codeの変更履歴も、2.1.284(2026年9月28日付)の項に次の行を載せています。
[VSCode] Fixed chat links to files with non-ASCII characters, spaces or brackets in their path not opening
issueが扱ったスペースと非ASCII文字に加えて、角括弧を含むパスも同じ修正の対象です。issueの本文には角括弧の記載がありません。
issueへの追記コメントでは、2.1.282でも症状が続いていた報告(9月27日)があります。この報告は2.1.284の前日で、修正の時期と矛盾しません。
更新後の確かめ方
拡張のバージョンは、VS Codeの拡張機能ビューで Claude Code を開くと確認できます。2.1.284より前なら更新します。更新後は、スペースか日本語を含むパスで次を試します。
docs/設計書/概要.md へのリンクを、相対パスで示してください返ってきたリンクをクリックして、エディタで該当ファイルが開けば解消しています。行番号つきの #L12 や #L12-L20 の形も、issueは「期待する動作」に挙げています。
更新しても開かないときは、次の切り分けへ進んでください。
更新できない環境の回避策: リンク先を ? と * に置き換える
組織の都合で拡張を固定している環境のために、issueは回避策を載せています。起票者が2.1.280、VS Code 1.135.0、macOSで確認した方法です。
仕組みは、拡張本体のあいまい検索にあります。パスに * ? { } [ ] が含まれていると、検索側がそれをグロブパターンとして扱います。この文字はチャットの描画でエンコードされないので、そのまま届きます。リンク先だけを次の規則で書き換えます。
| 書き換える文字 | 置き換え先 | 理由 |
|---|---|---|
| スペース | 置き換え先?(1文字につき1つ) | 理由グロブの1文字ワイルドカード |
| カンマ | 置き換え先? | 理由VS Codeの検索がカンマで条件を区切るため |
| 非ASCII文字 | 置き換え先*(1文字につき1つ) | 理由ripgrepとVS Codeの内部でバイト数と文字数の数え方が違い、* だけが両方を満たすため |
issueの例は次のとおりです。
[Übersicht.md](docs/My?Folder/*bersicht.md)
[notes.md](docs/My?Folder/notes.md#L12)同じ規則を日本語のパスに当てはめると、docs/設計書/概要.md は docs/***/**.md になります(日本語への当てはめは、issueにない書き換え例です)。
この回避策の限界
issueは、回避策の限界を3つ挙げています。
- ワークスペース内の相対パスだけが対象。
../で上の階層へ出るパスと、フォルダへのリンクは開かない - 内部のあいまい検索に頼る方法で、拡張の更新で動かなくなる可能性がある
- 修正の代わりにはならない
ワイルドカードで書くため、条件に合うファイルが複数あるときにどれが開くかは、issueに記載がありません。同名に近いファイルが多いフォルダでは、開いたファイルが意図と合っているか確かめてください。
Claudeにこの形式でリンクを書かせる
リンク先は、Claudeが回答中に自動で組み立てます。更新できない環境では、プロジェクトのCLAUDE.mdに規則を書いておく方法が考えられます。次は、上の回避策を指示文にした例です。
## ファイルリンクの書き方(VS Code拡張が2.1.283以前の場合のみ)
- チャットでファイルを示すときは `[表示名](相対パス)` の形にする
- リンク先のスペースとカンマは `?` に、日本語などの非ASCII文字は1文字ずつ `*` に置き換える
- 表示名は元のファイル名のまま書くこの指示でClaudeが規則どおりに書く保証はありません。リンクが生成されたら、実際にクリックして開くかを毎回確かめる運用になります。拡張を更新できたら、この節は削除します。2.1.284以降で残しておくと、読みにくいリンクを増やすだけです。
更新しても開かないときの切り分け
ファイルリンクが開かない原因は、パスの文字だけではありません。変更履歴とdocsから、別の原因を並べます。
| 状況 | 確かめること |
|---|---|
Windowsで C:\repo\file.ts や file:///C:/repo/file.ts の形のリンクが開かない | 確かめること変更履歴では2.1.296で「フルパスのリンクが開かない」不具合が修正されている。2.1.296以降か確認する |
\\server\share\report.md のようなネットワークパス | 確かめることリンクにならず、クリックできないフルパスで表示される。ネットワークホストへの接続や認証情報の送信を避けるための仕様で、不具合ではない |
| 端末側(ターミナル)でパスが開かない | 確かめることVS Code拡張のチャットとは別の問題。Warpターミナルのパスがクリックできない報告のように、端末ごとに事情が違う |
| チャット欄全体が反応しない | 確かめること拡張が応答していない可能性がある。応答しないときの切り分け手順で確認する |
ファイル名の一部を打ってClaudeに渡す @ メンションは、別の仕組みです。ただし、スペースを含むパスの @ メンションも、2.1.267で「スペースを含むパスのファイルが落ちる」不具合が修正されています。変更履歴の記述は短く、詳細までは載っていません。@メンションの使い方はVS Code拡張の@メンション解説にまとめています。
原因の箇所まで書いたissueは4日で直った
この不具合は、issueに書かれた範囲でも、9月24日の起票より前から続いていました。コメントには、2.1.178あたりから壊れていたと思う、という報告もありますが、そこで根拠に挙げられているのは別のissueです。起票者は、2.1.267から2.1.280の複数のバージョンで再現したと書いています。
過去の報告が自動クローズされたまま直らなかったのに、今回は起票から4日で修正版が出ています。違いは、起票者が原因の箇所と回避策まで調べて書いた点にあります。拡張の挙動を報告するときは、再現手順に加えて、どの層(描画か、クリック処理か、拡張本体か)で起きているかまで書くと、修正が早まる例といえます。
日本語のフォルダ名で作業する開発者にとっては、更新すれば解決する問題です。VS Code拡張を固定する運用がある組織では、拡張のバージョン固定を外す判断材料になります。
同じVS Code拡張でも、症状ごとに原因は別です。回答のコピーが効かない報告はコピーできない報告と代替手段に、仮想ワークスペースで起動しない問題はlibcエラーの原因にまとめています。
まとめ
スペースや日本語を含むパスのファイルリンクが開かない不具合は、パーセントエンコードされたパスがデコードされないまま探されるのが原因で、2.1.284で直りました。拡張を2.1.284以降にすれば、パスの書き換えは要りません。
更新できない環境でだけ、リンク先のスペースを ? に、非ASCII文字を * に置き換える方法が使えます。ただし内部のあいまい検索に頼るため、バージョンが変わると動かなくなる可能性があります。更新後も開かないリンクは、Windowsのフルパス(2.1.296で修正)、ネットワークパス(リンクにならない仕様)の順に疑ってください。