ae-system

ae-system

エージェントのシステム管理には、system ドメインを使用します。

ae-cli system +<command> [options]
ae-cli system <resource> <action> [options]

必須ルール

• これらのコマンドは、Agent のロールが root または agent_admin のユーザーのみが使用できます。
• te-agent の /api/admin/** および /api/cli/channel/v1/** エンドポイントが、最終的な認可境界です。メンバーは権限エラー（HTTP 403）を受け取ります。403 の後にログインを再試行したり、別のエンドポイントを試したりしないでください。
• このドメインを使用する前に、ae-cli auth login --host <host> を実行してください。システム管理には、有効なユーザーの CLI トークンセッションが必要です。サンドボックスの ID ヘッダーは認可の代わりにはなりません。
• +npm-install は、インストール済みの Linux ファイルをパッケージ化するため、Linux の te-agent サンドボックス内でも実行する必要がある例外です。これも、ログイン済みユーザーが root または agent_admin である必要があります。
• 更新や削除を行う前に、一覧表示コマンドで実際の ID を確認してください。ユーザー、サンドボックス、モデル、クォータルール、チャネルの ID を決して推測しないでください。
• 書き込みを行う前に必ず --dry-run を実行し、対象と影響を提示して、ユーザーから明示的な確認を得てください。CLI がプロンプトを表示するのは high-risk-write の場合のみです。--yes でそのプロンプトを回避できますが、セキュリティ境界ではありません。
• --dry-run を使用すると、実行せずにメソッド、パス、クエリ、マスキングされた本文を確認できます。
• JSON 入力には、インライン JSON、@file、または標準入力を表す - を使用できます。チャネルの認証情報などの機密情報には、@file を使用してください。
• 成功時の出力は、デフォルトで JSON です。人が読みやすい表のほうが便利な場合に限り、--format table を使用してください。
• 各コマンドの実行後に、標準エラー出力と _notice.host_compat を確認してください。存在する場合は、業務結果より先にバージョン警告と更新コマンドを提示してください。
• ae-cli コマンドが存在しないことを、HTTP エンドポイントに到達できない証拠として扱わないでください。Bash／ネットワークアクセスがある Agent は、リクエストを直接構築できます。実際の制御は、サーバー認証、ロールチェック、会社の分離、リソースの所有権です。
• DELETE /api/admin/members?openId=... または /api/internal/sandboxes/** を、独自の HTTP リクエストで呼び出さないでください。これらの連携契約は他のシステムが管理しているため、この Skill では意図的に除外されています。

コマンドグループ

メンバー

コマンド	リスク	目的
+list-member-candidates	読み取り	追加可能な AE 会社ユーザーを一覧表示します。
+list-members	読み取り	現在の会社の Agent メンバーを一覧表示します。
+add-members	書き込み	AE ユーザーを 1 人以上追加し、必要に応じてクォータルールを割り当てるか、サンドボックスを作成します。
+set-member-status	書き込み	メンバーを有効または無効にします。
+set-member-role	書き込み	root 以外のメンバーを agent_admin と member の間で変更します。
+remove-member	高リスクの書き込み	root 以外のメンバーを削除します。
+get-member-stats	読み取り	1 人のメンバーのトークン使用量と直近の会話数を取得します。

例：

ae-cli system +list-members --status enabled --page 1 --page-size 20

ae-cli system +add-members \
  --members '[{"openId":"ou_x","loginName":"alice","displayName":"Alice"}]' \
  --create-sandbox true

ae-cli system +set-member-role --user-id <user-id> --role agent_admin

+list-members のフィルター：

• --q：ログイン名／表示名で検索します。
• --status：all | enabled | disabled。
• --page、--page-size：ページサイズは 1～100 です。
• --all：一致するすべての項目を返します。
• --sort-field periodUsedAmount、--sort-dir asc|desc：全体の使用量で並べ替えます。

+add-members --members のスキーマ：

[
  {
    "openId": "required",
    "loginName": "optional",
    "displayName": "optional"
  }
]

任意のフラグは --rule-id と --create-sandbox true|false です。

サンドボックス

コマンド	リスク	目的
+list-sandboxes	読み取り	会社のサンドボックスを一覧表示します。
+get-sandbox-config	読み取り	機能の状態と、作成数／アクティブ数のシート上限を確認します。
+batch-create-sandboxes	書き込み	1～100 人のユーザー用に個人サンドボックスを作成します。
+update-sandbox	書き込み	サンドボックスの説明を更新します。
+set-sandbox-enabled	書き込み	サンドボックスを有効または無効にします。
+start-sandbox	書き込み	サンドボックスのコンテナを起動します。
+stop-sandbox	書き込み	サンドボックスのコンテナを停止します。
+list-sandbox-users	読み取り	サンドボックスに紐付けられたユーザーを一覧表示します。
+bind-sandbox-user	書き込み	メンバーをサンドボックスに紐付けます。
+unbind-sandbox-user	高リスク書き込み	サンドボックスのユーザー紐付けを解除します。
+remove-sandbox	高リスク書き込み	サンドボックスとその紐付けを削除します。

例：

ae-cli system +batch-create-sandboxes \
  --user-ids '["<user-id-1>","<user-id-2>"]' \
  --description "Data team"

ae-cli system +set-sandbox-enabled --id <sandbox-id> --enabled true
ae-cli system +bind-sandbox-user --id <sandbox-id> --user-id <user-id>

サンドボックスコマンドでは、AE openIds ではなく、+list-members で取得した Agent のデータベースユーザー ID を使用してください。

共有サンドボックスツール

コマンド	リスク	目的
+upload-sandbox-tool	書き込み	既存のツールディレクトリを検証、ZIP 化してアップロードします。
+npm-install	書き込み	一時サンドボックスディレクトリに指定したバージョンの npm CLI をインストールし、tool.json を生成してアップロードします。
+list-sandbox-tools	読み取り	現在の会社のプリセットツールとカスタムツールを一覧表示します。
+sync-sandbox-tools	書き込み	サーバーマニフェストからプリセットツールを同期します。
+get-sandbox-tool-distribution	読み取り	現在、1 つのツールを受け取っているサンドボックスを確認します。
+set-sandbox-tool-enabled	書き込み	登録済みツールを有効または無効にします。
+remove-sandbox-tool	高リスク書き込み	完全に再利用可能になったツール登録を削除します。
+activate-sandbox-tools	書き込み	選択したコマンドを、選択したサンドボックスまたは実行中のすべてのサンドボックスで有効化します。
+deactivate-sandbox-tools	書き込み	選択したサンドボックスまたは実行中のすべてのサンドボックスから、管理対象のコマンドシムを削除します。
+refresh-sandbox-tool-status	書き込み	対象サンドボックスでツールの観測状態を更新します。
+list-sandbox-tool-operations	読み取り	有効化／無効化の履歴を一覧表示します。

アップロードしたツールは、enabled=false の状態で現在の会社に登録されます。アップロードしても、実行中のサンドボックスでツールが有効になることはありません。アップロード後、サンドボックスツール管理で確認してから有効化してください。

有効化／無効化／状態確認の操作では、次のとおりです。

ae-cli system +activate-sandbox-tools \
  --target-mode selected \
  --sandbox-ids '["<sandbox-id>"]' \
  --tool-ids '["<tool-id>"]'

• --target-mode selected では --sandbox-ids が 1～50 個必要です。all-running では指定できません。
• --tool-ids には、+list-sandbox-tools から取得した実際の ID を 1～20 個指定します。
• --command-names-by-tool-id を指定すると、名前付きコマンドに操作対象を絞れます。
• --expected-tool-snapshots-by-id には、楽観的同時実行制御のチェックに使用する、サーバーから返されたバージョン／パッケージ／コマンドのスナップショットを指定します。
• JSON マップは、インライン JSON、@file、または標準入力を受け付けます。配布内容を変更する前に、ドライランを行い、ユーザーの確認を得てください。

推奨 npm フロー

対象の Linux te-agent サンドボックス内で実行します。

ae-cli auth login --host <host>
ae-cli system +npm-install --package [email protected]

スコープ付きパッケージ、またはカスタムの共有ツール識別子の場合：

ae-cli system +npm-install \
  --package @scope/[email protected] \
  --name example-cli

要件と動作：

• --package には、レジストリ上の正確なパッケージバージョンを指定する必要があります。タグ、範囲、URL、Git ソース、npm エイリアス、ローカルパスは拒否されます。
• インストールするパッケージは、少なくとも 1 つの package.json の bin エントリを公開している必要があります。各 bin は 1 つのツールコマンドになります。
• デフォルトのツール名はスコープのないパッケージ名です。別の有効な小文字のツール識別子が必要な場合にのみ、--name を使用してください。
• npm のライフサイクルスクリプトは、デフォルトで --ignore-scripts によって無効化されます。パッケージとすべての推移的依存関係を確認し、信頼できると判断した場合にのみ、--allow-scripts true を使用してください。
• コマンドは npm の実行開始前に、管理者用のアップロードポリシーエンドポイントを呼び出します。機能が無効、セッションの期限切れ、または管理者以外のロールの場合は、インストール前に失敗します。
• インストールには、一時的なプレフィックスを使用し、開発用依存関係を除外します。一時インストールファイルと ZIP ファイルは、アップロードの成否にかかわらず削除されます。
• npm が作成した node_modules/.bin のシンボリックリンクは、ZIP 内で通常の実行可能なラッパーに変換されます。それ以外のすべてのシンボリックリンク、特殊ファイル、およびパッケージルート外を指すリンクは拒否されます。
• 純粋な JavaScript の Node.js CLI がサポート対象の基準です。ネイティブアドオン、ダウンロードしたプラットフォームバイナリ、ビルドツール、システムライブラリ、またはライフサイクルセットアップを必要とするパッケージは、スクリプトが無効な場合や、異なるランタイムイメージで有効化した場合に失敗することがあります。
• ライフサイクルスクリプトが必要な場合は、ツールの実行に使用するものと同じ Linux サンドボックスイメージファミリーからインストールしてアップロードしてください。アップロードによって、互換性のないネイティブ成果物が移植可能になることはありません。

既存ディレクトリのフロー

ツールがすでにインストールまたは組み立て済みの場合は、低レベルコマンドを使用します。

ae-cli system +upload-sandbox-tool --path /absolute/path/to/tool-root

ディレクトリのルートには、tool.json が正確に 1 つ含まれている必要があります。ルートに tool.json がない場合に限り、外部マニフェストを使用できます。

ae-cli system +upload-sandbox-tool \
  --path /absolute/path/to/tool-root \
  --manifest /absolute/path/to/tool.json

最小限のマニフェスト：

{
  "schemaVersion": 1,
  "name": "example-cli",
  "displayName": "Example CLI",
  "description": "Optional description",
  "version": "1.2.3",
  "commands": [
    {
      "name": "example",
      "entry": "node_modules/example-cli/bin/example.js",
      "runtime": "node"
    }
  ]
}

アップロードの条件：

• name とコマンド名は小文字で始まり、小文字、数字、., _, - のみを含む必要があります。長さは最大 64 文字です。
• コマンド名で、node、npm、npx、bash、python、git、curl、sudo などの予約済みランタイムコマンドを置き換えることはできません。
• 各コマンドの entry は、アップロードルート内の通常ファイルである必要があります。JavaScript のエントリファイルには runtime: "node" を使用し、サンドボックスの Linux イメージと互換性のある実行可能ファイルに限り runtime: "native" を使用してください。
• パスは相対パスで、正規化されている必要があります。絶対パス、..、バックスラッシュ、制御文字、空のセグメント、および current パスセグメントは拒否されます。
• ZIP の上限は、圧縮後 50 MB、展開後 500 MB、ファイルごとに 50 MB、ファイル数 10,000 件です。サーバーは、同じ境界を独立して検証した後にのみ公開します。
• サンドボックスから /data/app/te_agent_ta/share/tools を事前に作成したり、書き込んだりしないでください。サンドボックスではこのディレクトリは読み取り専用です。最終的な書き込みと登録は、認証済みの te-agent アップロードエンドポイントが行います。
• この最初の静的バージョンのフローでは、ツール名は会社ごとに 1 回のみ登録できます。アップロード前に最終的な名前とバージョンを決定してください。

モデル

コマンド	リスク	目的
+list-system-models	読み取り	システムモデルと企業ごとの表示設定を一覧表示します。
+set-system-model-enabled	書き込み	現在の企業でシステムモデルの有効・無効を切り替えます。
+get-model-sync-settings	読み取り	新たに同期されるシステムモデルのデフォルトの表示ポリシーを読み取ります。
+set-model-sync-settings	書き込み	新しいシステムモデルの表示ポリシーを更新します。
+get-system-model-price-rules	読み取り	管理対象のシステムモデル1つについて、保存されている価格スナップショットを読み取ります。
+list-company-models	読み取り	無効なモデルを含め、企業モデルを一覧表示します。
+set-company-model-enabled	書き込み	企業のすべてのユーザーに対して、企業モデルの有効・無効を切り替えます。
+get-default-models	読み取り	AE_AGENT と AI_QA のデフォルトスロットを読み取ります。
+set-default-model	書き込み	デフォルトモデルのスロットを1つ設定します。
+clear-default-model	高リスクの書き込み	デフォルトモデルのスロットを1つクリアします。

例：

ae-cli system +list-system-models
ae-cli system +set-system-model-enabled --model-id <model-id> --enabled false
ae-cli system +set-default-model --model-id <model-id> --biz-type AE_AGENT

--biz-type は AE_AGENT | AI_QA で、デフォルトは AE_AGENT です。プロバイダーモデル名ではなく、モデル一覧で返されるデータベースの id を使用してください。

使用状況

コマンド	リスク	目的
+get-usage-summary	読み取り	相対または絶対の期間について、トークン数とコストの概要を取得します。
+get-usage-details	読み取り	ユーザー、モデル、日付、またはアプリケーション種別ごとにグループ化された使用状況を、ページ単位で取得します。
+get-agent-tool-calls	読み取り	必要に応じてキャッシュを更新し、指定期間のエージェントのツール呼び出し回数を取得します。
+get-usage-combinations	読み取り	1つの親グループを、残りのディメンションで詳細に確認します。
+export-usage	読み取り	フィルターされた1ディメンションの使用状況グループを CSV にストリーミング出力します。
+export-usage-details	読み取り	全件または複数ディメンションの詳細なドリルダウン結果を CSV にストリーミング出力します。

例：

ae-cli system +get-usage-summary --days 30
ae-cli system +get-usage-summary --days 30 --refresh true

ae-cli system +get-usage-details \
  --start-date 2026-07-01 \
  --end-date 2026-07-24 \
  --group-by user \
  --page 1 \
  --page-size 20

ae-cli system +get-usage-combinations \
  --start-date 2026-07-01 \
  --end-date 2026-07-24 \
  --parent-dimension user \
  --open-id <open-id>

ae-cli system +export-usage \
  --start-date 2026-07-01 \
  --end-date 2026-07-24 \
  --group-by user \
  --output ./system-usage.csv

概要の期間：

• --days 1..365 を使用するか、--start-date と --end-date の両方を指定します。
• 日付の形式は YYYY-MM-DD です。
• --days と絶対日付のペアは同時に指定しないでください。
• --refresh true は +get-usage-summary と +get-agent-tool-calls で使用でき、概要キャッシュをバイパスします。

詳細のフラグ：

• --start-date と --end-date は必須です。
• --group-by：user | model | date | app_type。
• 任意のフィルター：--search、--open-id、--model-id、--model-scope、--app-type。
• --model-scope を指定するには、--model-id が必要です。
• --sort-by：totalTokens | cost | share | requestCount。
• --sort-dir：asc | desc。

組み合わせのドリルダウンでは、親セレクターを必ず1つだけ指定してください。

• user → --open-id のみ。
• model → --model-id と --model-scope のみ。
• app_type → --app-type のみ。
• date → 選択した期間内の日付を指定する --date のみ。

CSV のエクスポートでは、--output の指定が必須です。出力先は排他的に作成されます。既存のファイルが上書きされることはなく、HTTP またはストリームのエラーが発生した場合は未完成のファイルが削除されます。JSON の結果には、ローカルの絶対パス、書き込みバイト数、サーバー側のファイル名、コンテンツタイプが含まれます。

コスト管理

コマンド	リスク	目的
+get-cost-summary	読み取り	会社のコスト、クォータ、使用状況の概要を取得します。
+get-balance	読み取り	現在のモデルアカウントの残高と通貨を取得します。
+list-over-limit-users	読み取り	コストまたはトークンのクォータ上限を超過しているメンバーを一覧表示します。
+get-balance-alert	読み取り	残高アラートの設定と現在の状態を取得します。
+set-balance-alert	書き込み	残高アラートを有効化、更新、または無効化します。
+list-quota-rules	読み取り	コスト／トークンのクォータルールを一覧表示します。
+create-quota-rule	書き込み	会社またはユーザーのクォータルールを作成します。
+update-quota-rule	書き込み	クォータルールを更新します。
+remove-quota-rule	高リスクの書き込み	クォータルールを削除します。
+bind-quota-rule-user	書き込み	クォータルールを AE ユーザーの openId に紐付けます。

例：

ae-cli system +set-balance-alert --enabled true --threshold 100

ae-cli system +create-quota-rule --rule @quota-rule.json
ae-cli system +bind-quota-rule-user --id <rule-id> --open-id <open-id>

クォータルールの JSON：

{
  "name": "Daily user quota",
  "subjectType": "USER",
  "periodType": "DAY",
  "quotaType": "TOKEN",
  "totalTokens": "10",
  "allowedModels": ["<model-id>"],
  "modelLimits": [
    {
      "modelId": "<model-id>",
      "limitTokens": "5"
    }
  ],
  "openIds": ["<open-id>"]
}

ルール：

• subjectType：USER | COMPANY。
• periodType：DAY | WEEK | MONTH。
• quotaType：COST | TOKEN。
• COST では budgetAmount を、TOKEN では totalTokens を使用します。トークン値は百万単位で指定します。
• allowedModels と modelLimits は、サーバールールの種類に応じて任意です。
• 更新では、部分的なルールオブジェクトを指定できます。

チャネル

チャネルの設定、ルーティング、WhatsApp Web のリンク、または Feishu ユーザーの紐付けを行う前に、references/channel-management.md をお読みください。ここでは、2 段階の確認手順と、ae-cli と Feishu OpenAPI MCP を組み合わせたワークフローを定義しています。

コマンド	リスク	目的
+list-channels	読み取り	設定済みのすべてのチャネルを一覧表示します。
channel get	読み取り	1 つのチャネル、その検証状態、エンドポイントを読み取ります。
+create-channel	書き込み	チャネルを 1 つ作成します。
+update-channel	書き込み	チャネルの設定、認証情報、モデル、プロンプト、または有効状態を更新します。
+remove-channel	高リスクの書き込み	チャネルを削除し、ユーザーの紐付けを解除して、接続を停止します。
channel verify	書き込み	認証情報を検証し、エンドポイントを検出します。
channel routing get	読み取り	1 つのエンドポイントのグループメッセージルーティングを読み取ります。
channel routing set	書き込み	1 つのエンドポイントのグループメッセージルーティングを置き換えます。
channel whatsapp-web status	読み取り	WhatsApp Web のリンク状態と QR データを読み取ります。
channel whatsapp-web start	書き込み	WhatsApp Web の QR リンクを開始または再開します。
channel whatsapp-web unlink	高リスクの書き込み	WhatsApp Web のリンクを解除し、保存済みの認証情報を削除します。
channel binding list	読み取り	チャネルのユーザー紐付けを一覧表示します。
channel binding bind-feishu	書き込み	Feishu ユーザーを 1 人紐付けます。
+bind-feishu-users	書き込み	Feishu ユーザーを 1〜100 人紐付け、必要に応じて Agent を割り当てます。
channel binding unbind	高リスクの書き込み	チャネルのユーザー紐付けを 1 件削除します。
channel binding set-agent	書き込み	1 つの紐付けのプライベートチャット用デフォルト Agent を設定または解除します。

正規の snake_case リクエストフィールドを使用してください。互換性のため、元の 4 つのコマンドでは従来の camelCase JSON フィールドも使用できます。認証情報と一括登録リストには、必ず @file を使用してください。

ae-cli system +create-channel --channel @channel.json
ae-cli system +update-channel --id <channel-id> --channel @channel-update.json
ae-cli system +bind-feishu-users \
  --channel-id <channel-id> \
  --endpoint-id <endpoint-id> \
  --bindings @bindings.json

権限エラー

権限エラーのレスポンスは次のようになります。

{
  "ok": false,
  "error": {
    "type": "permission",
    "message": "..."
  }
}

このレスポンスが返された場合：

1. 別の管理者用経路で再試行しないでください。
2. サーバーが 401 を返した場合を除き、再ログインを勧めないでください。
3. root または agent_admin が必要であることをユーザーに伝えてください。

認証済みの root または agent_admin であっても、自社の範囲に制限されます。現在のサービスでは、セッションに対してデータベース上のロールと会社を確認し、監査対象のメンバー、チャネル、サンドボックスツール、サンドボックス管理の各ルートでは、会社／リソースの所有権を確認します。この記述を、未確認の管理者用ルートがすべて安全であるという主張として使用しないでください。

トランスポートのステータス

これは、te-agent /api/admin/** および /api/cli/channel/v1/** を基盤とする移行期のドメインです。

• メンテナー：te-agent の管理／チャネル管理ルートおよび src/commands/te-system/**。
• 移行先：システムおよびチャネルの Capability Gateway。
• レビュー日：2026-10-24。
• 移行条件：同等のゲートウェイのスキーマ、認証、リスク、ドライラン、および出力の契約が安定した後に移行します。