Claude Tag APIでSlackチャンネルの設定をコードから管理する手順

Claude Tag APIは、SlackでClaudeを使うClaude Tagの設定を、自社のシステムから読み書きするためのAPIです。画面では組織オーナーが手で行っている「このチャンネルでClaudeを有効にする」「指示を足す」「バンドルを付ける」を、承認フローやリポジトリの設定ファイルから実行できます。

使えるのはClaude Enterpriseの組織だけで、現在はbetaです。Claude Platform(Console)の組織では使えません。ここでは、必要なキーとヘッダー、5つの設定の扱い、よくある3つの運用パターン、削除やレート制限で踏む落とし穴を順に追います。

使う前に揃える3つの条件

条件は3つあり、どれが欠けても同じ404か403で返ってきます。原因の切り分けが面倒になるので、先に確認しておくと楽です。

スコープの分担は、読み書きで綺麗に分かれています。

write:claude_tagだけのキーでは、チャンネルを探して更新する処理が完結しません。「探してから変える」連携には両方のスコープが要ります。また、Claude Consoleで作ったキーはこのAPIでは動きません。組織全体に属するキーが前提です。

書き込みだけが別に制限される組織もあります。claude_tag_writes_not_enabled(403)は、読み取りはできるが変更は有効化されていない状態を指します。

最初の1本 — ワークスペース一覧で疎通を確かめる

疎通確認には、ワークスペース一覧が最も安全です。何も変更せず、パラメーターも要りません。

curl "https://api.anthropic.com/v1/organizations/claude_tag/slack_workspaces" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: experimental-claude-tag-2026-10-21"

ant CLIなら、ヘッダーなしでant beta:organization:claude-tag:slack-workspaces listと打つだけです。SDKでは、PythonやTypeScriptなど7言語でclient.beta.organization.claude_tag(TypeScriptはclaudeTag)の下にエンドポイントが並びます。

ドキュメントの応答例では、各ワークスペースにslws_で始まるid、Slack自身のTで始まるID、5つのsettings、そしてsourcesが入っています。settingsの値がnullなら、そのワークスペースには何も保存されておらず、上位から継承しているという意味です。

APIで触れる範囲 — 14エンドポイントと、画面に残るもの

APIは4種類のリソースに14本のエンドポイントを持ちます。

触れないものも明確です。次の操作は、引き続きclaude.aiで行います。

• SlackワークスペースやEnterprise Gridの接続と切断
• 組織全体のSlackの既定値(Default Slack access)
• バンドルの作成と編集
• 支出制限
• 後述する5つの設定以外のすべて

つまり、このAPIは「配る側」の自動化です。バンドルの中身を設計する作業や、予算の設定は画面に残ります。バンドルの作り方はClaude Tagのバンドルでチャンネルごとの接続先と指示を決めるに、支出制限はClaude Tag管理者設定にあります。

チャンネルごとに持てる5つの設定

チャンネルにもワークスペースにも、同じ5つの設定が置けます。すべて任意です。

guest_policyは、allowが「Claudeが答える」、restrictが「答えない」、channel_onlyが「そのチャンネル自身に付いたバンドルだけで答える」です。channel_onlyは組織によっては使えず、その場合は400になります。

2つ、書き込み時の注意があります。

1. modelとenvironment_idは書き込み時にだけ検証されます。後からモデルや環境が変わっても、応答は保存した値を返し続けます
2. セルフホストのランナープールがclaude.ai側で設定された設定レベルでは、environment_idがccpool_で始まるIDになります。APIはこれを変更も解除もできず、400を返します

チャンネルのguest_policyを変えると、そのチャンネルで動作中のセッションが終了することがあります。終了はバックグラウンドで進み、応答はそれを待ちません。ゲストの有無が切り替わる運用では、更新のタイミングを選ぶ必要があります。

保存値と実効値 — include_inheritedで何が見えるか

設定は、チャンネル、ワークスペース、組織のSlack既定値という3つのレベルに保存されます。各レベルが持つのは、そのレベルで設定した値だけです。

GETにはデフォルトで「そのチャンネルに保存された値」が返ります。include_inherited=trueを付けると「結局そのチャンネルで効いている値」に変わります。前者は設定ファイルとの比較に、後者は監査や「なぜここでClaudeがこう動くのか」の調査に使います。

レベルをまたぐ解決ルールは、設定ごとに違います。

ここで注意したいのは、enabledの既定がtrueであることです。組織側で何も止めていなければ、何も設定していないチャンネルでもClaudeは有効です。承認したチャンネルだけで動かしたいなら、先に組織のSlack既定値でenabledをfalseにしておく必要があります。この設定はAPIからは変えられず、組織オーナーが画面で行います。

sourcesには、各設定の値がどのレベルから来たかが入ります。値がnullかどうかで「自分で持っているか、継承か」を判断してはいけません。include_inherited=trueのときは、sourcesの側を見ます。

継承にはもう少し例外があります。コードチャンネル(別のチャンネルから始めたチャンネル)は、親が同じワークスペースの公開チャンネルなら、親がチャンネルとワークスペースの間に入り、instructionsとenvironment_idだけを提供します。Enterprise Gridで同じチャンネルが別のワークスペース名義で登録されている場合は、enabledだけが上乗せされます。

設定を変えるときの4つの約束

更新の挙動は単純で、スクリプトに落としやすい設計です。

• 送らなかった設定は変わらない: {"settings": {"enabled": false}}は、ほかの4つに触れません
• nullを送ると解除される: そのレベルの値が消え、継承に戻ります
• 全部通るか、全部通らない: 1つでも拒否されたら、リクエスト内のどの設定も保存されません
• 同じリクエストを繰り返してよい: Idempotency-Keyは不要で、何も変わらない要求は何も書かず、Activity Feedにも残りません

一方、書き込みの競合には保護がありません。前提条件を付ける仕組みはなく、同じ設定を2か所から読んでから書くと、後から書いたほうが勝ちます。409が返るのは、リクエストの実行中に別の変更が重なった場合だけです。

パターン1: 承認されたチャンネルだけでClaudeを有効にする

Slackでは、誰でも公開チャンネルにClaudeを招待できます。承認制にしたいときの流れは、次の3段です。

1. 組織オーナーが、claude.aiの「Default Slack access」で「Enable Claude Tag in Slack」をオフにする。これで組織の既定値にenabled: falseが保存される
2. 承認システムが承認を出したら、そのチャンネルを"settings": {"enabled": true}付きでセットアップする
3. 同じ処理の中で、承認されたバンドルを付ける。最初のセッションから道具がそろう

セットアップはPOST /v1/organizations/claude_tag/slack_channelsで、Slack自身のワークスペースIDとチャンネルIDを渡します。すでにセットアップ済みなら既存のチャンネルを返し、設定だけを適用します。応答はどちらも200です。

curl -X POST \
  "https://api.anthropic.com/v1/organizations/claude_tag/slack_channels" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: experimental-claude-tag-2026-10-21" \
  -d '{
    "slack": {"workspace_id": "T01ABCD2EFG", "channel_id": "C05HJKL6MNP"},
    "settings": {"enabled": true}
  }'

応答のid(slch_で始まる)を使って、バンドルを付けます。バンドルのIDはcapp_で始まります。

curl -X POST \
  "https://api.anthropic.com/v1/organizations/claude_tag/bundles/$BUNDLE_ID/targets" \
  -H "content-type: application/json" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: experimental-claude-tag-2026-10-21" \
  -d "{\"type\": \"slack_channel\", \"slack_channel_id\": \"$CHANNEL_ID\"}"

付与は、チャンネルかワークスペースがセットアップ済みでなければ成立しません。付与がチャンネルを新しく作ることはないため、順番はセットアップ、付与です。同じ組み合わせをもう一度付与すると、200と既存のターゲットが返ります。

セットアップと設定の適用は、内部では2段階です。セットアップ後にsettingsが拒否されると、応答は拒否のエラーですが、チャンネルはセットアップされたまま、設定は何も保存されません。slack_channel_set_up_settings_refused(400)、slack_channel_set_up_environment_not_found(404)、slack_channel_set_up_settings_conflict(409)がこの型で、details.slack_channel_idにそのチャンネルのIDが入ります。リトライ処理では、「失敗したが作成は済んでいる」ケースを想定しておくと、二重のセットアップや待ちぼうけを避けられます。

パターン2: 設定をバージョン管理する

リポジトリを設定の正にするときの手順は4つです。

1. チャンネルを、Slackが表示するIDで管理する(設定ファイルのキーはSlackのチャンネルID)
2. include_inheritedを付けずに各チャンネルを読み、リポジトリの宣言とsettingsを比べる
3. 違う設定だけを送り、リポジトリから消えた設定はnullを送って解除する
4. 組織オーナーに、API/Terraformの読み取り専用モードをオンにしてもらう

2番目でinclude_inheritedを付けない理由は、付けると継承された値が混ざり、リポジトリの宣言との比較が崩れるためです。

チャンネルのidは、Slack IDから一度引いて保存します。引くには、チャンネル一覧にslack_workspace_idとslack_channel_idをクエリで渡します。セットアップされていないチャンネルは、dataが空で返ります。

BASE="https://api.anthropic.com/v1/organizations/claude_tag"
curl -s "$BASE/slack_channels?slack_workspace_id=T01ABCD2EFG&slack_channel_id=C05HJKL6MNP" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "anthropic-beta: experimental-claude-tag-2026-10-21" \
  | jq '.data[0] | {id, settings}'

この問い合わせの先頭要素のsettingsを、channels/C05HJKL6MNP.jsonのようなファイルと比べて、差分を送る形にします。ここまでは説明用の組み立て例です。差分計算のコードそのものは、ドキュメントにはありません。

読み取り専用モードは何を止めるか

「API/Terraform read-only mode」は、組織オーナーがclaude.aiで切り替える設定です。名前に反して、APIが読み取り専用になるわけではありません。モードがオンの間は、claude.aiとSlack側が、APIが管理する項目への人の変更を拒否します。止まるのは次の操作です。

• 5つの設定の変更(チャンネル、ワークスペース、Slack既定値のすべて)
• チャンネルのセットアップと削除、Gridのワークスペースの追加、ワークスペースやGridの切断
• バンドルの付与、取り外し、付与中のバンドルの削除

APIの応答はモードのオンオフで変わらず、APIからもモードは読めません。「パイプラインだけが変更元になる」状態を作るためのものです。オフの間は、人とキーが同じ設定を触れて、後から書いたほうが前の変更を置き換えます。

モードがオンでも、オーナーは新しいワークスペースの接続、バンドルの作成と編集、APIが管理しない設定の変更を続けられます。

パターン3: 全チャンネルで何が効いているかを監査する

監査の流れは次のとおりです。

1. ワークスペースの一覧を、include_inherited=true付きで取る
2. ワークスペースごとにチャンネル一覧を、同じくinclude_inherited=true付きで取る。Gridを使っているなら、GridのEで始まるIDで保存されたチャンネルも一覧する
3. 方針に反するものを拾う。例えば、承認記録のないenabled: trueや、guest_policyがallowのチャンネル
4. バンドルの一覧と、各バンドルのターゲット一覧を取り、機微な接続先がどこに付いているかを見る

ただし、ターゲット一覧で見えるのは、チャンネルとワークスペースへの直接の付与だけです。次のものはターゲットとして出てきません。

• claude.aiで「Default Slack access」に付けたバンドル
• チャンネル名のパターンで一括して付けるルール

また、あるチャンネルに付いているバンドルを直接返すエンドポイントはありません。そのため、「このチャンネルで使えるバンドル」は、ターゲット一覧に出る数より多いことがあります。API監査だけで「機微なバンドルは3チャンネルにしか付いていない」とは言い切れません。全体像は、claude.aiの画面で確かめます。

ページ送りにも注意が要ります。リストは新しい順で、limitは1〜100(既定20)です。チャンネル一覧は、limitより少ない件数や0件のページを返しながらnext_pageが残ることがあります。next_pageがnullになるまで読み続けます。SDKのイテレーターとant CLIはこれを自動で行いますが、PHPとcurlでは自分でカーソルを渡します。カーソルは加工せず、そのまま次のpageに渡します。

include_inherited=trueでは、読めないレベルがあると、そのレベル抜きで答えず503を返します。監査の途中で503が出たときは、欠けたまま集計せずに再試行します。

チャンネルの削除はClaudeを止めてから

DELETE /v1/organizations/claude_tag/slack_channels/{id}は、claude.aiでオーナーが行う削除と同じ効果です。Slack上のチャンネルやメッセージには触れません。

削除できるのは、Claudeがそのチャンネルでオフのときだけです。enabledが実効値でtrueなら、slack_channel_enabled(400)で拒否されます。先にenabled: falseを設定してから、もう一度送ります。

削除の後に注意したいのは、削除されるのが「チャンネル自身のenabled: false」も含むことです。その後は、継承した値だけでClaudeの有効無効が決まります。継承がtrueなら、次のメンションでClaudeはまた答え、その利用でチャンネルが新しいid・空の設定・空のメモリーで作り直されます。「止めたいから削除する」は成立せず、止めたいならenabled: falseを残す設計にします。

削除そのものができないものもあります。グループDMと、APIが管理しない設定(ランナープールなど、claude.ai側だけにある設定)を持つチャンネルです。どちらもerror_codeなしの400で、後者はオーナーが画面で削除します。グループDMへの設定の更新、バンドルの付与、セットアップも400です。ただしバンドルの取り外しは許されます。

レート制限とエラー処理

制限は組織単位で、組織内のすべてのキーが共有します。ほかのAdmin APIとは別枠です。

超えると429がretry-afterヘッダー付きで返ります。秒数だけ待って、同じリクエストを送ります。数百チャンネルを一括で作る処理は、毎秒1件の補充に縛られるため、バースト60件を使い切った後は1件ずつの流れになります。

主なステータスの扱いは次のとおりです。

503の後にDELETEを再送して404が返ったら、すでに消えています。取り外しも同じです。

403のcompliance_configuration_restrictedは、ゼロデータ保持のように「Claude Tagが新しいものを保存しない」構成の組織に出ます。この場合、セットアップ、設定の更新(解除でさえも)、バンドルの付与は拒否されます。取り外しと削除は許され、削除はenabledがオンでも通ります。

エラー応答のrequest_idは、サポートに問い合わせるときに使います。未知のステータスやerror_code、guest_policy.typeの新しい値が増えることがあるため、知らない値は未知の文字列として扱い、処理を落とさない実装にします。

変更の記録はActivity Feedに残る

APIによる変更は、Compliance APIのActivity Feedに記録されます。操作主体はAPIキー(apikey_で始まるID)として入ります。チャンネルのセットアップはccr_agent_created、設定の変更はccr_agent_updatedです。画面から同じ変更をしたときと同じ種類のイベントなので、一つの検索で、どちらの経路で行われた変更かを横断して追えます。何も変えない要求はイベントを残しません。

APIキーは組織に属するため、作成者が退職しても動き続けます。共有したり、ソース管理に入れたりしないことが前提です。

画面とAPIのどちらで設定するか

画面とAPIを混ぜるときは、読み取り専用モードを使うかどうかを最初に決めます。オフのままだと、画面の変更とパイプラインの変更が互いを上書きします。ワークスペース単位の設定とチャンネル単位の設定の違いは、ClaudeとSlackの連携の解説にある画面操作と見比べると分かりやすくなります。

まとめ

このAPIで自動化できるのは、チャンネルとワークスペースの5つの設定と、バンドルの付け外しです。バンドルの設計、予算、Slackの接続は画面に残ります。

運用に入れるときの勘所は3つです。ヘッダーの付け忘れは404として現れること。enabledの既定がtrueなので、承認制にするなら組織の既定値を先にオフにすること。そして削除は設定ごと消えて取り消せない一方、継承でtrueならClaudeが戻ってくることです。止めたいチャンネルには、削除ではなくenabled: falseを残します。