ntfy

事前に必要なもの
Hermes を設定する
設定ウィザードから
環境変数から
本人確認の考え方 — 運用を始める前に読んでください
クイックスタート — スマートフォンからエージェントに話しかける
cron ジョブと組み合わせて使う
ntfy を自分で立てる
Markdown の書式
送信専用の構成（受信なしで通知だけ受け取る）
制限
困ったときは

ntfy は、HTTP を使った簡単な pub-sub 型の通知サービスです。ntfy.sh の無料の公開サーバーでも、自分で立てたサーバーでも動きます。HTTP リクエストを送れるクライアントであれば、スマートフォンでもブラウザーでもスクリプトでも腕時計でも使えます。

ntfy は Hermes への軽量なプッシュ経路として便利です。ntfy のスマートフォンアプリでトピックを購読し、そのトピックにメッセージを送ってエージェントに話しかけると、返事がスマートフォンに届きます。

> hermes gateway setup を実行して ntfy を選ぶと、対話形式で設定を進められます。

事前に必要なもの

トピック名（重複しない文字列なら何でも構いません。hermes-myname-2026 のような形で十分です）
ntfy のスマートフォンアプリをインストールし、そのトピックを購読しておくこと
任意: 自分で立てた ntfy サーバー、または非公開トピック・予約トピックを使うための ntfy.sh のアカウントトークン

必要なものはこれだけです。SDK もデーモンも Node.js も要りません。アダプターは Hermes がもともと使っている httpx で動きます。

Hermes を設定する

設定ウィザードから

hermes gateway setup

ntfy を選んで、表示される質問に答えていきます。

環境変数から

次の内容を ~/.hermes/.env に追記します。

NTFY_TOPIC=hermes-myname-2026
NTFY_ALLOWED_USERS=hermes-myname-2026
NTFY_HOME_CHANNEL=hermes-myname-2026

変数	必須	説明
`NTFY_TOPIC`	はい	購読するトピック（受信するメッセージの経路）
`NTFY_SERVER_URL`	任意	サーバーの URL（既定: `https://ntfy.sh`）。プライバシーを重視するなら自分で立てた ntfy を指定します
`NTFY_TOKEN`	任意	ベアラートークン（例: `tk_xyz`）、または Basic 認証用の `user:pass`
`NTFY_PUBLISH_TOPIC`	任意	返信の送信先を別のトピックにする場合に指定（既定は `NTFY_TOPIC`）
`NTFY_MARKDOWN`	任意	`true` にすると返信に `X-Markdown: true` ヘッダーを付けて送ります
`NTFY_ALLOWED_USERS`	推奨	許可するトピック名をカンマ区切りで指定（ユーザー ID として扱われます。後述）
`NTFY_ALLOW_ALL_USERS`	任意	`true` にすると誰の投稿でも受け付けます。読み取りトークンで保護した非公開トピックでのみ安全です
`NTFY_HOME_CHANNEL`	任意	cron や通知の配信先となる既定のトピック
`NTFY_HOME_CHANNEL_NAME`	任意	ホームチャンネルに付ける人間向けの表示名

本人確認の考え方 — 運用を始める前に読んでください

ntfy には、認証された利用者の識別情報という仕組みがありません。投稿されたメッセージの title フィールドは送信者が自由に決められるもので、中身は何とでも書けます。Hermes のアダプターは title を認可の判断に使いません。使ってしまうと、トピック名を知っている人が誰でも許可済みの利用者になりすませてしまうからです。

代わりに、トピック名そのものが識別情報になります。そのトピックに投稿されたメッセージは、すべて同じ論理的な利用者（そのトピック）からのものとして扱われます。そのため NTFY_ALLOWED_USERS には、たいていトピック名そのものを書きます。1 件だけの許可リストで、その経路全体を制御する形です。

つまり、トピック名を知っている人は誰でもエージェントに話しかけられます。これを本当の意味での信頼境界にするには、次のいずれかを行います。

ntfy を自分で立てて、アクセス制御でトピックを保護します。読み書きのトークンを持つ、認可されたクライアントだけが投稿できるようになります。
あるいは ntfy.sh の非公開トピックを使い（予約トピックにはアカウントが必要です）、NTFY_TOKEN で保護します。
あるいは推測されにくい長いトピック名（hermes-7d4f9c8b-2026 など）を選び、共有の秘密として扱います。いちばん手軽な方法ですが、ログやスクリーンショットからトピック名が漏れる点には注意が必要です。

いずれの場合も、トピック側でアクセス制御をしていないなら、機微なデータを ntfy に流さないでください。

クイックスタート — スマートフォンからエージェントに話しかける

トピック名を決めます: hermes-myname-2026
スマートフォンで ntfy アプリを入れ、+ をタップして hermes-myname-2026 を入力します
ホスト側で次を実行します:

echo 'NTFY_TOPIC=hermes-myname-2026' >> ~/.hermes/.env
echo 'NTFY_ALLOWED_USERS=hermes-myname-2026' >> ~/.hermes/.env
hermes gateway restart

ntfy アプリからそのトピックにメッセージを送ります。エージェントの返事がプッシュ通知として届きます。

cron ジョブと組み合わせて使う

NTFY_HOME_CHANNEL を設定しておくと、cron ジョブの結果を ntfy に届けられます。

cronjob(
    action="create",
    schedule="every 1h",
    deliver="ntfy",          # uses NTFY_HOME_CHANNEL
    prompt="Check for alerts and summarise."
)

cron ジョブの deliver: フィールドで送り先のトピックを個別に指定することもできますし、シェルスクリプトからは hermes send コマンドで送れます。

hermes send ntfy:alerts-channel "Done!"

これは cron がゲートウェイとは別のプロセスで動いている場合でも機能します。プラグインが standalone_sender_fn を登録し、自前の HTTP 接続を開くためです。

ntfy を自分で立てる

すべてを自分で管理したい場合は、次のようにします。

# Docker
docker run -p 80:80 -it binwiederhier/ntfy serve

# Native
go install heckel.io/ntfy/v2@latest
ntfy serve

そのうえで、Hermes の向き先をそのサーバーにします。

NTFY_SERVER_URL=https://ntfy.mydomain.com
NTFY_TOPIC=hermes
NTFY_TOKEN=tk_abc123  # if you've set up access control

自分で立てると、トピックのアクセス制御、メッセージの保存期間の方針、添付ファイル、絵文字タグが使えるようになります。ntfy のサーバー向けドキュメントを参照してください。

Markdown の書式

ntfy のクライアントは、送信側が X-Markdown: true ヘッダーを付けたときに markdown を整形して表示します。Hermes から送る返信で有効にするには、次のように設定します。

NTFY_MARKDOWN=true

config.yaml に書く場合は次のとおりです。

platforms:
  ntfy:
    extra:
      markdown: true

スマートフォンアプリが対応しているのは CommonMark の一部で、太字・斜体・箇条書き・リンク・コードブロックです。対応範囲の詳細は ntfy の markdown ドキュメントを参照してください。

送信専用の構成（受信なしで通知だけ受け取る）

Hermes から ntfy へ通知を*送る*だけにして（cron のまとめやアラートなど）、こちらからのメッセージは一切受け付けたくない場合は、NTFY_TOPIC と NTFY_PUBLISH_TOPIC に同じ値を設定し、NTFY_ALLOWED_USERS は設定しないでおきます。許可リストが空だと、エージェントは受信したメッセージに応答しません。スマートフォンにはプッシュが届きますが、やり取りは一方通行になります。

制限

メッセージの長さ: ntfy は本文を 4096 文字までに制限しています。これを超えると Hermes は警告を出して切り詰めます。
入力中の表示がない: プロトコルにその仕組みがないため、send_typing は何もしません。
スレッドも添付もない: ntfy は素のプッシュ通知です。長い返信も本文にそのまま入り、スレッドに分かれることはありません。
本人確認の仕組みがない: 前述の識別情報の節を参照してください。

困ったときは

認証に失敗する / 401 — NTFY_TOKEN が間違っているか、そのトークンにこのトピックへの投稿・購読の権限がありません。401 を受け取るとアダプターは再接続の繰り返しを止め、ゲートウェイの実行状態には fatal: ntfy_unauthorized が表示されます。トークンを直してゲートウェイを再起動してください。

トピックが見つからない / 404 — 設定したサーバーに NTFY_TOPIC が存在しません。ntfy.sh では最初の投稿でトピックが自動作成されるので、404 が返るということは、そのトピックが用意されていない自前サーバーを指していることになります。アダプターは fatal: ntfy_topic_not_found を出して再接続の繰り返しを止めます。

接続はできているのにメッセージが届かない — NTFY_ALLOWED_USERS にトピック名そのものが入っているか確認してください。ntfy の識別情報の仕組みでは、トピックが利用者そのものです。許可リストを空のままにすると、すべて拒否されます。

60 秒ごとに再接続する — ストリームのキープアライブは既定で 55 秒です。ntfy 側で一時的なネットワークの不調が起きることもあります。アダプターは再接続の間隔を段階的に広げ（2 → 5 → 10 → 30 → 60 秒）、ストリームが 60 秒以上続いたら 0 に戻します。