ツールのドキュメント

Bluesky のドメインハンドルが無効になる理由と直し方

Bluesky がドメインハンドルを確認する仕組み:_atproto の TXT レコード、atproto-did ファイル、DID ドキュメント、ツールの各確認項目とよくある誤りを解説します。

Bluesky がドメインハンドルを確認する仕組み

ハンドルはドメイン名です。Bluesky は、リンクを双方向で確認できたときに alice.example.com をハンドルとして受け入れます。

  1. ドメインがアカウントを指していること。 値が did= と DID である _atproto.alice.example.com という DNS の TXT レコード、または DID だけを 内容とするファイル https://alice.example.com/.well-known/atproto-did の どちらかです。どちらか一方で十分です。
  2. アカウントがドメインを指し返していること。 DID ドキュメントの alsoKnownAs に、ハンドルが at://alice.example.com として記載されています。 アプリでハンドルを変更すると、Bluesky がそこに書き込みます。

ルールは AT Protocol のハンドル仕様にあります。 ハンドルを手に入れるほかの方法は、ガイド Bluesky で独自のハンドルを手に入れる方法をご覧ください。

追加するレコード

ハンドルホスト / 名前タイプ値
example.com_atprotoTXTdid=did:plc:ewvi7nxzyoun6zhxrhs64oiz
alice.example.com(ゾーン example.com)_atproto.aliceTXTdid=did:plc:ewvi7nxzyoun6zhxrhs64oiz

DNS 管理画面は名前にゾーンを自動で付け足します。完全な名前ではなく、 _atproto.<ハンドル> のうちゾーンより前の部分を入力してください。チェッカーは SOA の問い合わせでゾーンを見つけ、正確なホスト名を表示します。値は did= で 始め、引用符も空白も入れません。Bluesky は did= で始まる値をちょうど 1 つ、 何も削らずにそのまま読みます。

ファイルはもうひとつの方法で、DNS の管理画面がないホスティング向けです。 プレーンテキストで、ステータス 200 で提供します。

text
did:plc:ewvi7nxzyoun6zhxrhs64oiz

チェッカーが確認すること

ツールは 7 つの項目を順に確認します。それぞれ合格、失敗、警告、未確認の いずれかで、理由コードがつきます(API と MCP の応答では checks[].reason にこのコードが入ります)。

項目失敗する場合(理由)
syntaxドメインが有効なハンドルでない:253 文字を超える(too_long)、部分がひとつだけ(single_label)、空の部分や 63 文字を超える部分がある(label_length)、a–z・0–9・- 以外の文字がある(characters)、部分の先頭か末尾にハイフンがある(hyphen)、トップレベルドメインが数字で始まる(tld_digit)、.local や .example のような予約済みのトップレベルドメイン(disallowed_tld)
dnsレコードがない(missing)、did= の前に空白があり Bluesky がレコードなしと読む(leading_space)、did= のない DID(no_prefix)、did= と有効な DID の形でない値(invalid_value)、間違った名前にあるレコード(wrong_host:ゾーンの二重付加、ゾーン自体の _atproto、ドメインそのもの)、did= で始まる値が 2 つ以上(同じ値でも)ある(conflict)
httpsファイルがない(missing:404 または 410)、DID ではなくウェブページ(html)、DID 以外の内容(extra_content)、1 KB を超える内容(too_large)、その他のステータス(status)。サーバーが応答しない場合は警告(unreachable)
agreementレコードとファイルが別々の DID を示している(disagree)
documentDID ドキュメントが別のハンドルを宣言しているか何も宣言していない(claims_other)、または存在しない(not_found)
expectedドメインが指定したものとは別のアカウントを指している(mismatch)
appviewBluesky に handle.invalid(invalid)や以前のハンドル(old_handle)が表示されている、またはまだドメインをアカウントに結びつけていない(unresolved)

もう一方の方法が機能していれば、片方がなくても問題ありません。その行は not_needed で合格になります。Bluesky が使わない方法の問題は警告です。 ただし、did= で始まる 2 つの DNS の値は、Bluesky のリゾルバーが失敗として扱います。 仕様どおり DNS が優先されます。DNS が示す DID を DID ドキュメントが宣言し返していれば、 ウェブサーバーの応答にかかわらずハンドルは確認済みです。

よくある誤り

  • ゾーンの二重付加。 DNS 管理画面は名前にゾーンを付け足します。完全な名前 _atproto.alice.example.com を入力すると _atproto.alice.example.com.example.com になってしまいます。チェッカーが表示するホスト(ゾーン example.com なら _atproto.alice)だけを入力してください。
  • ゾーンの名前にあるレコード。 alice.example.com の場合、 _atproto.example.com のレコードはあなたのハンドルではなく example.com を 指します。チェッカーはそこと、ゾーンの二重付加、ドメインそのものに did= レコードがないかを探します。
  • did= のない DID。 値は接頭辞を含めて did=did:plc:… にします。
  • did= の前の空白。 Bluesky は値をそのまま読むため、 did=… は レコードなしとして扱われます。
  • 古いレコードの消し忘れ。 Bluesky は did= で始まる値をちょうど 1 つだけ 読みます。同じ DID でも 2 つあるとハンドルは無効になります。自分のものだけを 残してください。
  • ファイルの代わりにウェブページ。 多くのホスティングは、未知のアドレスに ステータス 200 でトップページを返します。ファイルには DID だけを入れます。
  • ハンドルがまだ切り替わっていない。 レコードは正しいのに、DID ドキュメントがまだ以前のハンドルを宣言しています。Bluesky アプリの 「設定」→「アカウント」→「ハンドル」 でハンドルをもう一度設定してください。
  • DNS の反映待ち。 変更がすべてのリゾルバーに届くまで最大 1 時間ほど かかります。ツールは応答をキャッシュしないので、もう一度実行してください。

ボットなら DNS 不要

ボットは代わりに name.bluesky.bot のハンドルを使えます。Bluesky.bot が ファイルを提供し、ハンドルを切り替えます。 ハンドルを取得するをご覧いただくか、 ハンドルの空き状況チェッカーで名前が空いているかを 確認してください。

コードから使う

チェッカーは無料の API ルートであり、MCP ツール check_custom_handle でも あります。

bash
curl "https://bluesky.bot/api/v1/tools/custom-handle-checker?domain=alice.example.com"

1 回の呼び出しは制限に対して 2 回分として数えられます。 ツール API と MCP サーバーをご覧ください。

独自ドメインのハンドルチェッカー

ハンドルが無効になる理由と、その直し方がわかります。