壁紙アプリの新しい書き出しを WebP でまとめ、命名規則の揺れを拾ってもらうつもりでエージェントに添付しました。返ってきたのは沈黙です。エラーも出ず、添付そのものが無かったことになっていました。
同じ週に、癒し系アプリの効果音を .opus で渡したときは、扱えない形式だという返答が来ました。ファイルはどちらも手元のプレイヤーで問題なく開けます。
症状は違いますが、原因の層は同じでした。ファイルの中身ではなく、送り出す側がそのファイルに何の MIME を貼ったか、です。
8月20日のハブ 2.9.1 で WebP の添付が加わり、同じ日の CLI 1.1.17 では .ogg / .opus / .ogv が汎用の application/ogg として送られてモデルに拒否される問題が修正されました。そのあともハブ側で添付の受け口は何度か広がっています。直ったこと自体より、なぜそうなっていたのかを掴んでおくほうが、次に別の拡張子で詰まったときに効くのだと思います。
この記事が答えたいのは、「添付したファイルがエージェントに届かない、または届いても使われないときに、どこから疑えばよいか」という一点です。
最初に、症状から層を決めます
添付が届かないと分かった時点で、いきなりファイルを変換し直すのは遠回りです。まず、どの層で落ちているかを決めます。
| 層 | 表に出る症状 | 最初に見るもの |
|---|---|---|
| ①クライアントと版 | 添付しても無反応、または形式・サイズのエラー通知が出る | ハブ / IDE / CLI の版と、その版で対応した形式・上限 |
| ②MIME の決定 | 添付は通るが、モデルの側が扱えないと返す | 手元での判定結果(下記の2通り) |
| ③受け渡しの経路 | 会話が重くなる、参照だけが残る | 直接添付か、MCP サーバーの戻り値か |
①と②は外から見るとよく似ていますが、見分け方はひとつです。会話に何かが残ったかどうか。エージェントがファイルを受け取ったうえで使えないと返すなら、受け口は動いていて型が違います。会話に何も残らないなら、受け口そのものが働いていません。この観察だけで、読むべき節が半分に絞れます。
私がつまずいた2件は、それぞれ①と②でした。WebP は 2.9.1 より前のハブでは受け口そのものが無く、Opus は受け口はあるのに貼られた MIME が粗すぎたわけです。Windows で画像やメディアの添付が失敗していた問題も①の側で、IDE 2.5.5(8月13日)で直っています。
症状ごとの切り分け表
ここ3か月の変更履歴で、添付まわりの修正はかなりの数にのぼります。私が実際に当たったもの、または当たりかけたものを、確かめ方と一緒に並べました(版と日付は 2026年11月時点・公式の変更履歴で確認したものです)。
| 症状 | 原因の候補 | 確かめ方 | 直し方 |
|---|---|---|---|
| WebP を添付しても会話に何も残らない | ハブ 2.9.1 より前で WebP の受け口が無い | 設定画面で版を確認する | 2.9.1 以降へ更新する |
| 添付したのに何も起きず、エラー表示も無い | 2.9.1 より前は、サイズ・件数・形式の失敗に通知が出なかった | 版を確認し、更新後に同じ操作で通知が出るか見る | 更新して、通知の文言どおりに対処する |
.opus や .ogv を渡すと、モデルが扱えないと返す | 汎用の application/ogg で送られている(CLI 1.1.17・ハブ 2.11.0 で修正) | CLI とハブの版を両方見る | 両方を更新する。急ぐなら Opus を M4A などへ書き出す |
| 空のテキストや JSON を添付したら、その後の会話がすべて失敗する | 空ファイル添付の不具合(ハブ 2.33.0 で修正) | 添付したファイルのサイズが 0 バイトでないか見る | 更新するか、新しい会話でやり直す |
| 大きな WebP をエージェントが開くと上限で落ちる | PNG・JPEG と違い縮小されていなかった(CLI 1.2.15 で修正) | CLI の版と画像の画素数を見る | 更新する。急ぐなら長辺を縮めて渡す |
| MCP の画像や PDF が本文に見えず、参照だけが残る | 不具合ではなく、大きなバイナリをファイルへ保存する方式(ハブ 2.9.1〜) | 参照先のファイルが実在するか見る | 何もしない。必要なら参照先を開く |
①は版を上げれば終わります。厄介なのは②で、こちらは版を上げても、環境によっては再発します。理由は次の節で測ります。
手元の判定を2通り並べると、食い違いが見えます
MIME の決め方には、中身の先頭バイトを見る方法と、拡張子の対応表を引く方法の2通りがあります。同じファイルに両方を当てて、結果を並べてみました。
# 中身から判定する(マジックバイト)
for f in sample.png sample.webp sample.ogg sample.opus sample.ogv; do
printf '%-13s %s\n' "$f" "$(file -b --mime-type "$f")"
doneUbuntu 22.04・file 5.41 での出力です。
sample.png image/png
sample.webp image/webp
sample.ogg audio/ogg
sample.opus audio/ogg
sample.ogv audio/ogg
次に、拡張子の表を引く側です。
import mimetypes
for name in ["sample.png", "sample.webp", "sample.ogg", "sample.opus", "sample.ogv"]:
print(f"{name:<13} {mimetypes.guess_type(name)[0]}")Python 3.10.12 での出力です。
sample.png image/png
sample.webp None
sample.ogg audio/ogg
sample.opus audio/ogg
sample.ogv video/ogg
並べると、二重の穴が見えてきます。
| ファイル | 中身から | 拡張子から | 起きること |
|---|---|---|---|
sample.webp | image/webp | (決まらない) | 表を引く実装では型が付かず、汎用のバイト列として送られる |
sample.opus | audio/ogg | audio/ogg | 両方一致するが、Opus であることが落ちている |
sample.ogv | audio/ogg | video/ogg | 音声と映像で判定が割れる |
.ogg / .opus / .ogv の3つは、先頭4バイトがいずれも 4f676753(OggS)でした。同じコンテナに包まれている以上、中身を覗く方法では区別のしようがありません。中身から判定する実装が Ogg 系をまとめて粗い型で送っていた、という挙動には、こういう素直な理由があります。
WebP のほうは逆で、拡張子の表に行が無いために型が決まりません。決まらないものを送る側は、たいてい汎用のバイト列として扱います。受け取ったモデルからすれば、画像として渡されていないわけですから、見ないという判断は筋が通っています。
Opus が汎用の Ogg になるのは、機械側の表が勝つからです
ここがいちばん引っかかった点でした。Python の内蔵テーブルは、.opus に対して audio/opus を持っています。ところが初期化を通すと、値が入れ替わります。
import mimetypes
print(mimetypes.types_map.get(".opus")) # 初期化前: audio/opus
mimetypes.init()
print(mimetypes.types_map.get(".opus")) # 初期化後: audio/ogg上書きしているのは、その機械に置かれている対応表です。手元の /etc/mime.types を見ると、こう書かれていました。
audio/ogg oga ogg opus spx
audio/opus
opus が audio/ogg の行に同居し、すぐ下の audio/opus の行には拡張子がひとつも付いていません。内蔵の値より、機械に置かれた表のほうが後から読まれる分だけ強い、という順序です。
この構造が意味するのは、同じコードでも機械が変われば結果が変わる、ということです。手元では通っていた添付が、対応表を持たない小さなコンテナや CI の中では別の型になります。個人開発で作業機とビルド環境を行き来していると、この差はまとまった時間を溶かします。
私が遠回りした順番と、いまの線引き
最初のうち、私はファイルの側ばかりを疑っていました。書き出し設定を何度も見直し、別の設定で書き出し直しています。結果は芳しくありませんでした。どれも手元のプレイヤーでは開けるので、比べても違いが出ないのです。
原因がファイルの外にあると気づいたのは、作業機とビルド環境で判定が食い違うのを見たあとでした。ファイルは1バイトも変わっていません。変わったのは、それを読む機械の対応表だけです。
いまは、添付で詰まったら変換より先に版と判定を見ることにしています。ファイルを疑うのは、機械の判定を2通り並べたあと。 この順番にしてから、書き出し直しに手を取られることはほとんどなくなりました。
よくある誤解を3つ正しておきます
「file コマンドで一致すれば、その型で送られる」わけではありません。 file が見ているのは中身だけで、クライアントが実際に貼る型は、その実装が拡張子・中身・自前の表のどれを優先するかで決まります。手元の判定は「自分の機械がどう見ているか」の確認であって、送信内容の保証ではありません。
「Python の版は関係ない」わけでもありません。 CPython の内蔵表に .webp が image/webp として入ったのは 3.11 からで、3.10 までは機械側の表に行が無ければ None になります。上の出力で WebP が決まらなかったのは、3.10 を使っていたからでもあります。同じスクリプトを 3.11 以降で動かせば、WebP の行は image/webp と出るはずです。
「何でも添付できるようになったから、形式は気にしなくてよい」とも言い切れません。 ハブ 2.28.0(10月27日)で、20 MB までなら任意の形式を添付できるようになり、以前は形式で弾かれていたファイルも「ファイルとして」添付され、エージェントが保存先から読む形になりました。弾かれなくなった代わりに、画像や音声として直接モデルに渡るのか、ファイルとして置かれてツールで読まれるのかの違いが、表からは見えにくくなっています。後者だと、画像の中身を見てほしかったのにファイル名だけが扱われる、ということが起こり得ます。
変換するか、型を指定するか、更新を待つか
手元の判定で引っかかったファイルには、取れる手が3つあります。どれを選ぶかは、急ぎかどうかと、その形式をこれからも使うかどうかで決まります。
| 手 | 向いているとき | 代償 |
|---|---|---|
| 対応の確かな形式へ書き出し直す(WebP→PNG、Opus→M4A など) | 今日中に渡したい。その形式に思い入れが無い | ファイルが大きくなる。元の形式の検証にはならない |
| 自分のスクリプトや MCP サーバーで型を明示する | 自前の経路で同じ形式を繰り返し送る | 経路ごとに直す必要がある。直接添付には効かない |
| クライアントを更新して待つ | 変更履歴に該当の修正が載っている | 新しい版は順に配られるため、届くまで数日かかることがある |
私自身は、変更履歴に修正が載っているものは更新を待ち、そのあいだだけ書き出し直した版を渡しています。自前の経路だけで起きるものは、型の明示で直します。直接添付は更新で、自前の経路は型の明示で。 迷ったときはこの一文で振り分けています。
MCP 経由で来るファイルは、判定する主体が違います
三つ目の層です。エージェントにファイルが渡る経路は、人が添付するものだけではありません。MCP サーバーが画像や PDF を返してくることもあります。
この経路では、型を決めるのは手元のクライアントではなく、サーバー側の宣言です。手元でいくら判定を揃えても届きません。切り分けの順序としては、まず「そのファイルは自分が添付したのか、ツールが返したのか」を確かめる必要があります。
ハブ 2.9.1 では、接続済みの MCP ツールが返す大きなバイナリ(画像・PDF・音声)は会話へ展開されず、ファイルへ保存されて参照される形になりました。以前は会話の中で展開され、そのターンごと壊れることがあった部分です。会話に本文が見えず参照だけが残っている場合、それは不具合ではなく、この保存方式が働いた結果です。
MCP サーバーの起動段階で落ちている場合は、型の話に入る前の問題です。そちらはMCP サーバーが1本も起動しない原因は、起動前の 60 行足らずで特定できますでまとめています。
添付する前に通しておく短い確認
②の層は、渡す前に手元で潰せます。2通りの判定を突き合わせ、食い違いと欠落を先に出すだけの短いスクリプトです。
#!/usr/bin/env python3
"""添付予定のファイルについて、中身と拡張子それぞれの MIME 判定を突き合わせる。"""
import mimetypes
import subprocess
import sys
# 中身からは区別できず、判定が揃っていても粗いままになる拡張子
COARSE = {".opus": "audio/opus", ".ogv": "video/ogg", ".oga": "audio/ogg"}
def by_content(path):
try:
r = subprocess.run(["file", "-b", "--mime-type", path],
capture_output=True, text=True, check=True)
return r.stdout.strip()
except (subprocess.CalledProcessError, FileNotFoundError):
return None
def main(paths):
flagged = 0
for p in paths:
ext = "." + p.rsplit(".", 1)[-1].lower() if "." in p else ""
by_ext = mimetypes.guess_type(p)[0]
by_con = by_content(p)
if by_ext is None:
print(f"[表に無い] {p}: 拡張子から決まりません(中身は {by_con})")
flagged += 1
elif by_con and by_ext != by_con:
print(f"[食い違い] {p}: 拡張子 {by_ext} / 中身 {by_con}")
flagged += 1
elif ext in COARSE and by_ext != COARSE[ext]:
print(f"[粗い] {p}: {by_ext} と出ますが、本来は {COARSE[ext]} です")
flagged += 1
else:
print(f"[一致] {p}: {by_ext}")
print(f"--- 要確認 {flagged} 件 / 全 {len(paths)} 件 ---")
return 1 if flagged else 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))先ほどの5ファイルに通した結果です(Python 3.10.12)。
[一致] sample.png: image/png
[表に無い] sample.webp: 拡張子から決まりません(中身は image/webp)
[一致] sample.ogg: audio/ogg
[粗い] sample.opus: audio/ogg と出ますが、本来は audio/opus です
[食い違い] sample.ogv: 拡張子 video/ogg / 中身 audio/ogg
--- 要確認 3 件 / 全 5 件 ---
COARSE の3行を足したのは、判定が一致していることと、その値が正しいことが別だと分かったからです。.opus は両方が audio/ogg で揃います。揃っているのに、Opus であるという情報は落ちています。一致だけを合格条件にすると、この一件を素通りさせてしまいます。
範囲についてひと言添えます。このスクリプトが確かめられるのは、自分の機械がどう見ているかまでです。クライアントが最終的に何を送るかも、MCP サーバー経由のファイルの型も、ここからは分かりません。何も出なかったときは「②の層は、いまは原因ではなさそうだ」と読むのが正しい使い方なのだと思います。
終了コードを非ゼロで返しているのは、添付を伴う自動処理の手前に置けるようにするためです。App Store 提出前のアセット確認のように、まとめて機械へ渡す工程では、通す前に止まってくれるほうが助かります。
次に詰まりやすいのは、渡したあとのコストです
型の問題が片付くと、次に当たるのは「渡せるようになったものを、どこまで渡すか」かもしれません。20 MB まで何でも渡せるようになった日に、私が何を渡さないと決めたかは任意ファイルを 20MB まで渡せるようになった日に、エージェントへ渡すものと渡さないものを線引きしましたに書き残しています。CSV や JSON を添付したときに、どの列がいちばんトークンを食っていたかを測った記録は売上CSVを添付したら、いちばん高くついていたのは日付の列でしたにあります。
複数の機械を行き来する構成そのものをどう決めるかは、Remote Control をホスト機に入れる判断は、daemon の生存条件と遮断経路で決まりますで、資格情報の置き場所と併せて掘り下げました。今回の話は、その構成の上を実際に流れるファイルの側です。
次に確かめる一手
手元で添付する予定のファイルを、まずこのスクリプトに通していただければと思います。[表に無い] や [粗い] が出た拡張子だけが、対応表の違う環境で型を失う候補です。そこだけを、上の3つの手のどれかに振り分ければ済みます。
小さな引っかかりでしたが、掴んでみると同じ形の問題を先回りできるようになりました。書き出し直しに使った時間は戻りませんが、その分だけ、次の拡張子では迷わずに済むと感じています。