本文へスキップ
Ankole

環境変数

AI Agent 向け: このページの Markdown 版は https://ankole.agentbull.com/ja-JP/docs/worker-env/index.md、ドキュメント索引は https://ankole.agentbull.com/ja-JP/llms.txt にあります。

Agent Computer Worker 上でコマンドを実行したり、MCP サーバーを呼び出したり、Background Agent Job を動かしたりする際に、外部サービス向けの環境変数が必要になることがあります。API キー、トークン、サービス URL などの設定には、Console の Environment variables を使用してください。

認証情報(credential)の生値を Skill 本文、Agent の定義ドキュメント、またはチャットメッセージに直接書き込まないでください。

ここに登録した変数は、Agent 自身および Agent が起動する子プログラムから参照できます。実行される各コマンドはこれらの変数をセットしたクリーンな環境で立ち上がり、Worker デーモンプロセス自身の内部環境変数を引き継ぐことはありません。ここには Agent の業務実行に必要な認証情報だけを保存し、LLM Provider、Identity Provider、チャットチャネル自体の認証情報はそれぞれの専用 Console ページで設定してください。

リモート HTTP MCP の認証情報は制御プレーンのプロキシが読み取ります。bearer_token_env_var が参照する値は Worker の環境スナップショットから除外し、Worker は内部 Turn トークンでプロキシを利用します。組み込み Connector の認証情報と個人 OAuth は Pod の接続ページで管理します。その他のコマンド用変数は以下の規則で渡されます。

先にスコープを選ぶ

変数を必要とする対象範囲に合わせて、設定先のスコープを選択します。

変数を必要とする対象 設定場所 スコープ
サイト内のすべての Agent Console → Environment variables → New site variable サイト既定値
特定テナント内のすべての Agent Console → 対象テナントを選択 → Environment variables → New tenant variable そのテナント内でサイト既定値を上書き
特定の 1 体の Agent Console → Agents → 対象 Agent を選択 → Environment variables その Agent でテナント値・サイト既定値を上書き

実行時には「Agent 単位の上書き → テナント値 → サイト既定値」の優先順で値が解決されます。上書き設定をクリアすると 1 つ上のスコープの値が使われ、どのスコープにも値が登録されていない変数は環境に渡されません。

site または tenant の変数を追加する

  1. Console → Environment variables を開いて対象テナントを選択し、設定したいスコープに応じて New site variable または New tenant variable をクリックします。
  2. 変数名を入力します。英字、数字、アンダースコアを使用できますが、先頭を数字にすることはできません(例:MY_API_KEY)。
  3. 値を入力します。API キー、トークン、パスワードなどの機密値では、Store as secret をオンのままにしてください。
  4. 任意で、どのツールや外部サービスで使う変数かをメモ欄に記入します(このメモが Agent 側に渡されることはありません)。
  5. 変数を保存します。

なお、PATH、HOME、SHELL、TERM、LANG、BASH_ENV、ENV、WORKER_ID、DATABASE_URL、CODEX_UNSAFE_ALLOW_NO_SANDBOX、および ANKOLE_ で始まる変数名はランタイム側で予約されているため、この画面からは設定できません。

1 つの Agent に変数を設定する

  1. Console → Agents を開き、対象の Agent を選択します。
  2. Environment variables セクションを開きます。
  3. 新規変数を追加するか、既存変数の行で Override を選択します。
  4. 値を入力して保存します。

この一覧にはサイト、テナント、Agent の各スコープの変数がまとめて表示され、Source 列で現在有効な値がどのスコープに由来するかを確認できます。Clear を実行すると Agent 単位の上書きだけが削除され、テナント値またはサイト既定値へ戻ります。

変数のタイプを理解する

WorkerEnv に並ぶ項目はすべて、運用者が明示的に登録したカスタム変数です。Ankole 本体や Plugin が AppConfigure の設定キーを WorkerEnv へ自動エクスポートすることはありません。ランタイムの予約変数やチャネル連携の認証情報は、それぞれの所有ドメインが個別に管理します。

値の暗号化、表示、ローテーション

新規変数の作成時は、既定で Store as secret がオンになっています。暗号化された値は Console の一覧上ではマスク表示されますが、実行時の Agent 環境には復号された元の値が渡されます。

暗号化済みの変数を編集する際、マスク表示に触れずにそのまま保存すれば既存の値が維持されます。認証情報をローテーションするときは、古い値をわざわざ再表示せず、新しい値をそのまま入力して保存してください。

Reveal(値の表示)を使うのは、障害調査などで現在保存されている値をどうしても確認しなければならない場面だけに限定してください。また、Store as secret をオフに切り替えると平文保存の確認ダイアログが表示されますが、API キー、トークン、パスワードでは暗号化をオフにしないでください。

変更が有効になるタイミング

環境変数の変更は、保存後に新しく開始される Worker 作業から反映されます。すでに環境変数を取得して稼働中の実行や開いているワークスペースは、開始時点の古い値をそのまま保持します。なお、メイン Agent のモデル推論ループ自体はコントロールプレーン上で動くため、コントロールプレーンのプロセス環境変数として WorkerEnv が読み込まれることはありません。

もし Agent 側で期待した環境変数が参照できない場合は、次の項目を上から順に確認してください。

  1. 変数名が Skill、スクリプト、または bearer_token_env_var の宣言と大文字・小文字まで完全に一致しているか。
  2. サイト既定値を見る前に、Agent 単位やテナント単位の上書き設定が入っていないか。
  3. いずれかのスコープに値が実際に保存されているか。
  4. 設定変更後に新しい Worker 作業を開始したか(すでに開いているワークスペースでは開始時点の環境変数が使われます)。

なお、MCP 連携を使う Skill では、openai.yaml の bearer_token_env_var には環境変数名だけを記述し、トークンの実体はここで登録します。宣言スキーマの詳細は MCP を参照してください。