server-auto-mode-listsでauto modeの追加ルールを絞る — セルフホストRunner
server-auto-mode-listsは、コントロールプレーンが送るauto modeの3つのルール一覧のうち、Runnerが通す範囲を決めるフラグです。all・no-allow・noneの違いと、効いているかの確かめ方です。
セルフホストRunnerの--server-auto-mode-listsは、Anthropicのコントロールプレーンがセッションと一緒に送ってくるauto modeの分類器ルールのうち、どの一覧を自分のRunnerで有効にするかを決めるフラグです。値はall・no-allow・noneの3つで、何も指定しなければno-allowになります。
既定のままでも動きますが、no-allowは「外から来たルールが分類器を緩める余地」を完全には消しません。Runnerを運用する側がその余地をどこまで許すかを、起動時に自分で決める。このフラグはそのためにあります。
--server-auto-mode-listsが決めること
Runnerには、自分のホストで動くセッションの分類器ルールがどこから来るかを選べない部分があります。コントロールプレーンは、セッションにルールの一覧を添えて、Runnerに「適用してほしい」と頼めます。送られるルールには組織の管理者が書いたものが含まれることがあり、Runner運用者から見れば自分で書いた覚えのないルールです。どこまで通すかをフラグで選べるのはそのためです。
auto modeは、定型の許可プロンプトを出さない代わりに、別の分類器モデルが操作を実行前に審査し、却下したものを止める仕組みです。askルールを明示した操作には、引き続きプロンプトが出ます。
その一覧は3種類です。
コントロールプレーンが送る3つの一覧
environment
分類器に「ここは信頼できる環境だ」と教える文脈です。1件で分類器が許す範囲を広げることも、狭めることもあります。
soft_deny
ユーザーが明示的に頼んだときか、
allowの例外に当たるときを除いて、その操作を止めるルールです。allow
soft_denyに対する例外です。止めるルールを、特定の条件でだけ通します。
--server-auto-mode-listsは、この3つのうちどれをセッションまで通すかを選びます。環境変数ならSELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTSです。フラグと環境変数の両方を指定したときはフラグが優先されます。
3つの名前は、ローカルのautoMode設定にある配列と同じ区分です。ローカル側の書き方はClaude CodeのautoModeに独自ルールを追加する方法で扱っています。ただし、このフラグが対象にするのは「外から来る」一覧だけです。リポジトリや各ホストの設定との関係は、リファレンスのこの節に記載がありません。
3つの値は何を通して何を止めるか
| 値 | 通る一覧 | 性質 |
|---|---|---|
all | 通る一覧environment・soft_deny・allow | 性質3つすべてを適用する |
no-allow | 通る一覧environment・soft_deny | 性質allowだけ止める。既定値 |
none | 通る一覧なし | 性質どの一覧も適用しない |
no-allowが既定になっているのは、allowが「止めるルールに穴をあける」一覧だからだと読めます。allowを外せば、soft_denyの例外が効きません。外から来たルールで分類器が緩む経路のうち、いちばん分かりやすい1本を閉じる設計です。
ただし、分かれ目は緩みを断つことと制限を保つことが両立しない点です。
no-allowとnoneの分かれ目
no-allow
soft_denyの制限は保たれます。そのかわり、environmentの1件で分類器が許す範囲が広がる余地が残ります。
none
外から来る一覧による緩みは出ません。そのかわり、soft_denyによる追加の制限も届かなくなります。
allを選ぶ場面は、コントロールプレーン側でallowの例外まで含めて運用する前提があるときです。その前提がないなら、allowを通す理由は自分のRunnerの側にありません。
起動時に指定する
フラグで指定する場合は次のようになります。他の必須フラグは省略した例です。
claude self-hosted-runner \
--server-auto-mode-lists none \
--log-level debug環境変数で渡すなら、Runnerを動かすコンテナやサービスの定義に1行足します。
# systemdのEnvironmentやコンテナのenvに書く値
SELF_HOSTED_RUNNER_SERVER_AUTO_MODE_LISTS=no-allow指定できるのは3つの値だけです。上のどれにも当たらない値を渡すと、Runnerは起動時に停止します。タイプミスで黙って別の挙動になることはなく、起動に失敗するので気づけます。共通のテンプレートに環境変数を書き、手元の検証だけフラグで上書きする使い方も、フラグが優先されるので衝突しません。必要なバージョンはClaude Code v2.1.295以降です。
オンデマンドRunnerで使う場合、オーケストレーターのフラグ一覧には--server-auto-mode-listsが載っていません。オーケストレーターが受け付けるのは、--api-url・--environment-secret-file・--hooks-dir・--health-port・--log-levelと、独自のフラグです。Runnerを起動するspawn-runnerフック側で環境変数を渡す形が考えられます。フックの扱いはClaude Codeセルフホスト環境でオンデマンドRunnerを起動するにあります。
設定しても一覧が届くとは限らない
Runnerの設定で、コントロールプレーンに適用を頼ませることはできません。コントロールプレーンが頼まなければ、どの値を指定してもセッションに一覧は届きません。allにしたからルールが増える、というものではありません。
つまりこのフラグは、届いた一覧を絞る「受け取り側のフィルター」です。送るかどうかは、あくまで相手が決めます。
フラグを変えたのに挙動が変わらないとき
- 後輩
noneにしたのに、前と同じようにブロックされるんです。フラグが効いていないんでしょうか。 - 先輩
その可能性より前に、そもそも一覧が届いていないことを疑います。コントロールプレーンが頼んでこなければ、
allでもnoneでも、セッションが受け取るルールは同じです。 - 後輩
じゃあ、どっちなのかはどう見分けるんですか。
- 先輩
Runnerを
--log-level debugで起動します。セッションごとにログへ1行出るので、そこで分かります。
効いているかをデバッグログで確かめる
--log-level debugで起動すると、Runnerはセッションごとに次のどちらかを含む行を出します。
| ログに含まれる文 | 意味 |
|---|---|
the server asked this runner to apply | 意味コントロールプレーンが適用を頼んできた |
the server did not ask this runner to apply the auto mode lists it sends | 意味頼まれなかった。一覧は適用されない |
後者が出ているなら、--server-auto-mode-listsの値を変えても結果は同じです。--log-levelはinfoかdebugのどちらかで、既定はinfoです。infoのままだと上の行は出ないので、切り分けるときだけdebugにします。
確かめる順番は次のとおりです。
意図どおりに絞れているかの確認手順
- 1
値を決める
all・no-allow・noneのどれにするかを決め、フラグか環境変数で指定します。 - 2
debugで起動する
--log-level debugを付けてRunnerを再起動します。 - 3
セッションを1本流す
実際にセッションを動かし、ログの該当行を探します。
- 4
頼まれたかを読む
askedの行なら絞りが効く状況です。did not askの行なら、フラグ以前に一覧が来ていません。
確認が済んだら、--log-levelをinfoに戻して構いません。
値の選び方と、他の設定との関係
どの値を選ぶかは、「外から来るルールをどこまで信用するか」と「制限を保ちたいか」の二軸で決まります。
- 制限は保ちたいが、
allowの例外は受け入れない: 既定のno-allow - 外から来るルールで分類器を動かしたくない:
none - コントロールプレーン側の例外運用まで含めて受け入れる:
all
noneを選ぶときは、soft_denyの制限も一緒に外れることを前提にします。分類器が何を止めるかの全体像はClaude Codeのauto mode分類器は何を止めるかにまとまっています。
似た設計は管理設定にもあります。autoModeのsoft_denyかhard_denyが読めなかったり、無効なエントリが取り除かれたとき、Claude Codeはallowとenvironmentを適用しません。制限が壊れたまま許可だけが残る状態を避ける動きで、v2.1.282以降です。外から来る一覧でも「許可を先に落とす」という考え方が、no-allowが既定になっている理由と同じ向きにあります。
このフラグと関係しない設定もあります。auto modeの判定をサーバー側に頼むかどうかを決めるCLAUDE_CODE_AUTO_MODE_SERVERは、別の話です。CLAUDE_CODE_AUTO_MODE_SERVER=0でUnavailableを回避する記事で扱っています。
Runnerのフラグ全体を眺めたいときは、セルフホスト環境のCLIフラグ・メトリクスリファレンスが一覧になっています。Runner自体の役割はClaude Code self-hosted-runnerとはに書かれています。
まとめ
--server-auto-mode-listsは、外から来るauto modeのルールを自分のRunnerでどこまで通すかを決める受け取り側のフィルターです。既定のno-allowでもenvironmentの1件が分類器を緩める余地は残り、noneならその余地を断てる代わりにsoft_denyの制限も落ちます。値を決めたら、--log-level debugでaskedの行が出ているかを確かめてください。出ていなければ、変えた値は何も絞っていません。
参照した一次ソース
この記事の記述は、次の一次ソースと照合しています。更新時に参照先が変わった場合は一覧も更新します。