設定

ChatWalaʻau の設定面は 2 つあり、どちらに属するかは個別判断ではなくルールで決まります。

設定面	保持するもの	変更方法
`.env`	ブートストラップ値（ポート・パス・エンドポイント）、すべてのシークレット、すべての機能有効化ゲート／許可リスト	ファイルを編集して再起動
App Settings（`app_settings.jsonc`）	ランタイム調整値 — 生成、チャット／セッション、メモリ、音声、RAG、上限、スケジュール	アプリ内画面、または CLI

chatwalaau init で .env を生成し、値を編集して再起動します。それ以外は起動中のアプリから調整できます。

v0.129.0 で変更

52 個の変数が .env から App Settings へ移動しました。.env に残った値は 無視されます — サーバは起動しますが、その値はもう適用されません。起動ログが検出したキー名をすべて列挙します。既存の設定を引き継ぐには:

chatwalaau settings migrate           # ドライラン — 何をコピーするか表示
chatwalaau settings migrate --write   # 適用して再起動

必須設定

ChatWalaʻau には少なくとも 1 つのチャットプロバイダー（Azure OpenAI、 Anthropic (Claude)、OpenAI、Microsoft Foundry、またはその組み合わせ）が必要です。利用できるものを設定してください。開始に必要なのは 1 つだけです。設定した全プロバイダーのモデルは同じセレクターに表示され、ターンごとに切り替えられます。

v0.107.0 で変更

チャットモデルは モデルオファリングカタログ（model_offerings.jsonc）でのみ設定します。レガシーのプロバイダ別モデル変数（AZURE_OPENAI_MODELS, ANTHROPIC_MODELS, OPENAI_MODELS, FOUNDRY_MODELS, MODEL_MAX_CONTEXT_TOKENS, ANTHROPIC_HOSTING、およびプロバイダ別のチャット endpoint/key 変数）は 削除されました。chatwalaau init（最初のモデル設定ウィザード）、 chatwalaau models add、またはアプリ内の App Settings 画面で設定してください。

プロバイダーの認証情報を .env に設定します（画像・RAG・音声と共有）:

AZURE_OPENAI_ENDPOINT=https://<your-resource>.openai.azure.com/
AZURE_OPENAI_API_KEY=<your-key>       # または Entra ID で認証（「認証」節を参照）
# 必要に応じて ANTHROPIC_API_KEY / OPENAI_API_KEY -- カタログから NAME で参照

次に model_offerings.jsonc に chat offering を最低 1 つ記述します。各 offering は provider（azure-openai / anthropic / openai / foundry）、model_ref（実際のモデル / デプロイ名）、任意の endpoint / base_url / hosting / context_window、および api_key_env（キーを保持する環境変数の NAME）を自己記述します。1 つのエンドポイントで複数のモデルファミリーを提供でき、direct と Foundry ホストの Claude は offering ごとの hosting で併用できます:

{
  "offerings": [
    { "id": "gpt-5.5", "provider": "azure-openai", "model_ref": "gpt-5.5",
      "endpoint": "${AZURE_OPENAI_ENDPOINT}", "default": true, "context_window": 1050000 },
    { "id": "claude", "provider": "anthropic", "hosting": "direct",
      "model_ref": "claude-sonnet-4-5-20250929", "api_key_env": "ANTHROPIC_API_KEY" },
    { "id": "gpt-5.1", "provider": "openai", "model_ref": "gpt-5.1", "api_key_env": "OPENAI_API_KEY" },
    { "id": "deepseek", "provider": "foundry", "model_ref": "deepseek-v4-pro",
      "endpoint": "https://<resource>.services.ai.azure.com/api/projects/<project>" }
  ]
}

azure-openai の offering は endpoint/api_key_env を省略すると、共有の AZURE_OPENAI_ENDPOINT + Azure 認証レーンにフォールバックします。カタログが無い非 demo デプロイは起動時に警告を出してそのまま起動し（App Settings 画面で修正可能）、チャットは利用できず、実行しようとした時点で案内メッセージを返します。

このファイルは手で編集する必要はありません。最初のモデルは chatwalaau init の任意ステップ（--no-model でスキップ）として、あるいは任意のタイミングで chatwalaau models add で設定でき、以降はチャットサイドバーの App Settings 画面から管理できます -- 保存はホットリロードで即座に適用され、再起動は不要です。

マルチモデル切り替え、モデルオファリングカタログ、Anthropic の foundry ホスティング、OpenAI / Microsoft Foundry プロバイダー、エージェント単位の生成オプションはモデルと推論を参照。

認証

各プロバイダーへの認証方法を選べます。API キーは（提供されるプロバイダーでは）最も簡単で、Azure CLI もテナントも不要です。Microsoft Entra ID レーンは Azure OpenAI、Foundry 上の Anthropic、そして Microsoft Foundry（Entra 専用）で利用できます。

Azure OpenAI

バックエンドは Azure OpenAI の資格情報を 4 つのレーンで解決し、2 つの変数で選択します。動作環境に合うものを選んでください。

レーン	使う場面	`.env` 設定
api-key	初回 / PoC / CI / コンテナ、テナント跨ぎ	`AZURE_OPENAI_API_KEY=<key>`
cli（既定）	`az login` 可能なローカル開発（Entra ID）	`AZURE_CREDENTIAL_MODE=cli`（未設定可）
managed-identity	Azure App Service / Container Apps / AKS / Functions / VM（Entra ID）	`AZURE_CREDENTIAL_MODE=managed-identity`
default	1 つのイメージを複数環境で（Entra ID 自動判別）	`AZURE_CREDENTIAL_MODE=default`

優先順位: AZURE_OPENAI_API_KEY は常に AZURE_CREDENTIAL_MODE より優先されます。つまり API キーを設定すれば az login は不要です。プロセスごとに、最初の資格情報解決時にアクティブなレーンが INFO ログ 1 行で示されます（キー値は決してログ出力されません）。

クラウドデプロイ

managed-identity では、コンピュートにマネージド ID を割り当て、Azure OpenAI リソースに Cognitive Services OpenAI User ロールを付与します。ユーザー割り当て ID では AZURE_CLIENT_ID も必要です。フェデレーション ID を使う AKS ワークロードは AZURE_CREDENTIAL_MODE=default を使うと SDK の WorkloadIdentityCredential が自動選択されます。chatwalaau CLI は、アクティブなレーンが cli 以外のとき az account show の事前チェックを省略します。

Anthropic (Claude)

Claude モデルは、オファリングごとにホスティングを選ぶカタログのオファリングです:

ホスティング	接続先	認証
direct（Anthropic の公開 API）	任意の `base_url`（プロキシ）	`sk-ant-...` を保持する変数を `api_key_env` で指定
foundry（Microsoft Foundry 上の Anthropic）	必須の `base_url`: `https://<resource>.services.ai.azure.com/anthropic`	`api_key_env`、または省略して Microsoft Entra ID（`AZURE_CREDENTIAL_MODE` + `AZURE_TENANT_ID`）

ANTHROPIC_HOSTING と ANTHROPIC_FOUNDRY_* の変数は廃止されました。モデルと推論 -> Anthropic プロバイダを参照してください。

OpenAI（direct）

OpenAI 公開 API の認証は API キーのみです -- Entra ID レーンはありません。

認証	`.env`
API キー	`OPENAI_API_KEY=sk-...`（OpenAI 互換ゲートウェイ用に任意の `OPENAI_BASE_URL`）

詳細はモデルと推論 -> OpenAI プロバイダーを参照。

Microsoft Foundry

Foundry プロジェクトエンドポイントの認証は Entra ID のみです -- API キーレーンはありません。このプロバイダーは Azure OpenAI の Entra レーン（AZURE_CREDENTIAL_MODE + AZURE_TENANT_ID）を再利用します。 AZURE_OPENAI_API_KEY は適用されません。

認証	`.env`
Microsoft Entra ID	`FOUNDRY_PROJECT_ENDPOINT=https://<resource>.services.ai.azure.com/api/projects/<project>`。`AZURE_CREDENTIAL_MODE` + `AZURE_TENANT_ID` を再利用

サインインする ID にプロジェクトの Foundry データプレーンロール（例: Azure AI User）を付与してください。詳細はモデルと推論 -> Microsoft Foundry プロバイダーを参照。

アプリケーション設定

ランタイム挙動を調整する設定はすべて .env ではなくアプリ内で編集します。サイドバー下部のスライダーアイコンから App Settings を開いてください。左ペインは設定項目リストで、Model Offering Catalog に続いてグループごとに 1 項目が並びます。

グループ	例
Generation & inference	Anthropic トークン下限、プロンプトキャッシュ、Web 検索の国
Chat & session	チャットタイトル方式、PDF 添付の扱い、インポート上限、履歴圧縮
Memory	Identity / User / Agent メモリのトグルと文字数上限
Speech	STT / TTS のデプロイ、ボイス、サンプルレート、Live の声と上限
RAG	ベクトルコレクション、検索件数
Limits	シェルタイムアウト、ファイルエクスプローラ上限、パイプライン並列数、ワークフロー上限、返信上限
Schedule	Cron の tick、猶予ウィンドウ、実行タイムアウト、タイムゾーン
Agent Skills	スキル導入スイッチ、カタログ/台帳パス、ソース表、GitHub トークン、導入上限

反映タイミング

各コントロールにバッジが付きます。保存済みだがまだ有効になっていない設定が、反映済みに見えてはならないためです。

バッジ	意味
Applies immediately	保存した時点で有効（50 項目）
Rebuilds agents	保存時にモデル別エージェントをその場で再構築。再起動は不要（13 項目）
Restart required	値は保存されるが、サーバ再起動後に有効（13 項目 — 音声のデプロイ、パイプラインのワーカー数、スキル台帳のパス）

ChatWalaʻau が自分自身を再起動することはありません。restart の変更では、再起動待ちのキー名を画面が明示します。

他の設定に依存する設定

一部の設定は、別の設定がオンのときにしか読まれません。そうした行は disabled で描画され、どのスイッチに従っているかを示す Needs <親項目> チップが付きます。たとえば履歴 compaction の 3 つの予算は、History compaction がオフの間グレーアウトします。依存関係はバックエンドが宣言するため、画面がグレーアウトする範囲は、サーバが実際に無視する範囲と常に一致します。

実運用上重要な点が 2 つあります。

親をオフにしても子の値は失われません。 値は app_settings.jsonc に残り、検証も受け続け、親を再びオンにすれば調整したままの状態で戻ります。トグルはリセットではありません。
保存が拒否されたときに名指しされた設定は、親の状態に関わらず編集できます。 2 つの設定が矛盾して保存が拒否された場合でも、拒否したその画面で必ず修正できます。

compaction 設定について

履歴 compaction の設定には Rebuilds agents バッジが付いていますが、0.148.0 より前は再構築時にプロセス起動時の compaction 戦略をそのまま再利用していたため、保存は成功と報告されるのに実行中のエージェントは前の値を保持していました。0.148.0 からは再構築が再解決するのでバッジは正確です。現在はすべての経路で次のターンから反映されます。

0.149.0 以降、戦略の選択肢はありません。COMPACTION_STRATEGY は削除され、オン/オフスイッチと 2 つの予算 -- ツールコールグループ (12) とメッセージグループ (25) -- に置き換わりました。この 2 つは 2 x K < N を満たす必要があります。アップグレード時の作業は不要です。詳細は会話の圧縮を参照してください。

0.150.0 以降、オン/オフスイッチがオフの間は 2 つの予算とシステムプロンプト除外が画面上で無効化されます。パイプラインがそれらを読まないためです。値は保持されるので、 compaction を再びオンにすれば設定した予算がそのまま戻ります。

CLI から

chatwalaau settings list            # 全設定の値・グループ・scope
chatwalaau settings list --json     # 機械可読
chatwalaau settings migrate         # ドライラン: .env から移動する対象
chatwalaau settings migrate --write # 適用

アップグレードとロールバック

このビルドが知らないキーは削除されず保持されます。 新しいリリースが書いた設定ファイルが、古いリリースの起動を妨げることはありません。未知キーは Unknown / deprecated settings に削除操作付きで表示されます。
無効になった値は起動を止めません。 警告付きで既定値にフォールバックし、該当フィールドにチップが表示されます。
APP_SETTINGS_FILE（既定 app_settings.jsonc、作業ディレクトリ基準）が、この設定面が .env に追加する唯一のキーです。空にするとストアは無効になり、組み込みの既定値で動作します。

.env の構成

テンプレートは設定を機能ごとにまとめています。ほとんどの機能は オプトインで既定オフのため、必須の Azure 設定だけでサーバは動作します。各機能ページに使用する設定が記載されており、本ページはその入口です（全変数表ではありません）。

機能のゲートと上限が意図的に分離されている点に注意してください。 CODING_ENABLED は .env に残り、CODING_BASH_TIMEOUT はアプリケーション設定です。ゲートはその機能が存在するかどうかを決め、上限は既に有効な機能ができることを狭めるだけです。セキュリティ判断なのは前者だけなので、画面からは編集できません。

スキルと、残すべき 1 つのディレクトリ

SKILLS_DIR（既定 .skills）は Agent Skills の置き場所であり、v0.151.0 からは製品がスキルについて書き込むすべての場所でもあります。スキルカタログ、何をどこから導入したかの記録、有効/無効の選択のいずれもこのディレクトリ配下の隠しファイルとして保存されるため、このディレクトリ 1 つをマウントすれば機能全体が対象になります。

コンテナ環境で導入済みスキルを再起動後も残したい場合は、SKILLS_DIR に永続ストレージをマウントしてください。マウントしない場合はリサイクル時に失われます。製品はその損失を隠さず報告しますが、防ぐことはできません。

.env にあるスキル関連の設定は SKILLS_DIR だけです。これは規則によるものです。カタログファイルと台帳ファイルはその配下に解決されるため、ルートが読めなければ残りを見つけられません。それ以外はすべて App Settings の Agent Skills グループにあり、ファイル編集も再起動も不要です。

設定	内容
Skill installation	書き込み側の主スイッチ（カタログ更新・導入・再導入・削除）。OFF でも閲覧は可能。
Catalog file / Install ledger file	スナップショットと台帳の書き込み先。相対パスは `SKILLS_DIR` 配下に解決。
Source table file	組込の 5 取得元を置き換える独自 JSON ソース表のパス。
GitHub token	任意。匿名呼び出しの 60 リクエスト/時の上限を引き上げます。
Source request timeout / Install size cap / Install file-count cap	1 回の取得と 1 スキルの上限。

スイッチ配下の 5 行は Skill installation が OFF の間グレーアウトします。バックエンドが読まなくなるのがその 5 つだからです。2 つのファイルパスはグレーアウトしません。カタログの閲覧と有効/無効の選択は、導入が OFF でも動き続けるためです。

デモ配備ではスイッチの値にかかわらず導入機能は常に利用できません。DEMO_MODE は .env にあり、このスイッチより優先します。スイッチ自体を画面から編集可能にできるのは、この床があるからです。

GitHub トークンは保存されますが、返されません

App Settings が保持する最初のクレデンシャルです。画面にはマスクされたパスワード入力が表示されます。他の設定を保存するときにマスクをそのままにしておくことがトークンを保つ操作で、フィールドを空にするとトークンが削除されます。app_settings.jsonc がクレデンシャルを含み得るようになったため、.env と同等のファイル権限を設定してください。

リリース間で .env を最新に保つ

新しいリリースは多くの場合、既定オフの新設定で価値を追加するため、pip install -U 後もサーバは動き続けます。しかし、どの設定が増えたかは自分の .env からは分からず、古いキーも溜まります。2 つのオフラインコマンドが、インストール済みリリース同梱のテンプレートに対して .env を突き合わせます:

chatwalaau env diff           # 生成時以降に追加 / 削除された設定
chatwalaau env diff --json    # 機械可読

chatwalaau env sync           # 突き合わせのプレビュー（ドライラン）
chatwalaau env sync --write   # タイムスタンプ付きバックアップ後に適用

値はそのまま保持 -- 更新されるのはレイアウトとキーごとのコメントのみ。
何も削除しない -- テンプレートにないキーは Unmanaged keys セクションへ移動。
--write の前に必ず タイムスタンプ付きバックアップ（.env.<UTC>.bak）を作成。

起動時、追加された新キーが .env に不足していると 1 行ログで通知します。

次のステップ

機能 -- 各機能を設定する。
デプロイと運用 -- ソースから実行・ビルド・デプロイ。

必須設定​

認証​

Azure OpenAI​

Anthropic (Claude)​

OpenAI（direct）​

Microsoft Foundry​

アプリケーション設定​

反映タイミング​

他の設定に依存する設定​

CLI から​

アップグレードとロールバック​

.env の構成​

スキルと、残すべき 1 つのディレクトリ​

リリース間で .env を最新に保つ​

次のステップ​