PART 5接続・操作・復旧する5.1
Environment — 宣言・Secrets・Agentの使用許可
必要な環境変数名を宣言し、ToolsのSecretsからKeychainまたは.envへ値を登録して、Agentごとに使用を許可する。
Agentが必要な環境変数名をenvironment.yamlに宣言し、人間のownerがTools > Secretsで値を登録してAgentごとに使用を許可する。保存済みの値はWebUIへ表示しない。
| 層 | 場所 | 内容 |
|---|---|---|
| 宣言 | Agent repoのenvironment.yaml | 名前と用途だけ。値のfieldは拒否 |
| 使用許可 | 選択したComputer rootの.state/env.toml | owner・保存先・Agent/名前ごとのbinding |
| 値 | そのComputerのlogin Keychainまたは.env | Agent環境へ注入する値 |
宣言だけでは許可されない。runtimeは宣言とbindingの両方がある名前を、指定された保存先から読む。不足や取得失敗を別保存先の同名値で補わない。利用可能な値はSessionへ渡し、不足・保存先障害は警告する。設定自体が不正な場合は明示的なエラーになる。
既定のlocal rootは~/aachat。AACHAT_HOMEで別の絶対pathを指定できる。
宣言: environment.yaml の契約
環境変数は config.env に書く。
config:
env:
- name: OPENAI_API_KEY
purpose: OpenAI API access- 各項目に書けるのは
name（必須）とpurpose（任意）だけ。valueなど他のキーを書くと エラーで拒否される。agent repoは複製・公開されうるため、値の混入を構造的に防いでいる - 名前は
[A-Z_][A-Z0-9_]*形式。AA_で始まる名前はaachatの予約で宣言できない。同名の重複宣言はエラー - Session processの準備時に読むのは、ローカルに取得したagent repoの
HEADにあるenvironment.yamlである。手元の未pushの編集は反映されない。反映はpush後の次のSession process準備から（agents の反映ルールと同じ）
Toolsで登録・使用許可する
Home/TeamのTools > Secrets、または本人AgentのSet up secretsから開く。本人の接続中PCと、導入済みAgentごとに必要なキーを表示する。休眠中のAgentのセクションは表示しない。休眠にしても保存済みの値や使用許可は保持される。PC名は書込先を示し、ブラウザを開いた端末とは限らない。Agentからのリンクは該当行へfocusし、dialogを自動で開いたり許可したりしない。
.env、Keychain、Agent要求は独立して読む。要求は、そのPCに導入済みのAgent repoから取得する。Refreshはローカル情報の再読取であり、GitHubから取得しない。取得不能なAgentは、そのPCで起動・更新してからRefreshする。取得途中や失敗を「不足なし」とは扱わない。
不足キーのSet value、または名前も入力するAdd secretから保存する。その名前を要求する読取済みの導入Agent全員へ、保存した場所の使用を自動で許可する。別の保存先へのbindingがあれば切り替える。Keychainと.envの両方を利用できる場合はOptionsで保存先を選ぶ。Changeは名前と保存先を固定して値を更新する。dialogには使用を許可するAgentを表示し、許可状態を確認できない場合は値だけを保存する。その後Refreshし、行のAllowで許可する。
Agentごとのチェックリストに必要な名前・purpose・使用状態を表示する。保存済み値や値のCopy操作はない。読取済みAgentが要求していない名前はNot used by any agentへまとめる。行の**…メニューにbindingごとのStop sharing with …**を表示し、取得不能なAgentの既知bindingも解除できる。解除しても値の削除や発行元credentialの失効は行わない。
一括入力はAdd secretのPaste a .env file insteadを使う。既存名はReplaces the saved valueと表示し、既定では未選択にする。置換する名前だけを選ぶ。保存に成功した名前の使用許可は、要求Agent分を一回の操作にまとめる。
名前は[A-Z_][A-Z0-9_]*、最大128文字、AA_*は禁止。新しい値は1〜16,384 UTF-8 bytesで、空白のみ・実CR/LF・NULを拒否する。前後空白・tab・$・=・引用符・バックスラッシュはliteralとして保存する。Value欄は常にliteral入力、Name欄へのNAME=...貼付はPaste a .env fileと同じdotenv parserを通す。一括は50変数・256 KiBまでで、同名重複は保存前に全件拒否し、shell実行や変数展開はしない。
値保存と使用許可は別操作である。許可だけ失敗してもSavedは維持し、現在bindingを確認して許可だけを再操作する。値保存の結果が不明ならRefreshし、存在だけで前回の保存成功を認定しない。新しい明示Update/createには値を再入力する。操作の自動再送や別Computerへの切替は行わない。
保存先とlocal設定
- Keychain: macOSで、そのrootとowner専用serviceをfile-based login keychainへ保存する。他アプリのitemを一覧せず、iCloud同期は使わない。OSの許可は選択したMacで行い、Toolsの自動一覧取得とruntime読取では対話しない。明示的な保存・許可操作ではOSの許可を求める場合がある。ロックや取得失敗時に
.envへ退避しない。 - .env: 採用済みpathまたは既定
.run/.envの平文file。WebUIから任意pathを受けない。対応Unixではowner管理directory・regular file・0600権限を確認し、symlinkや不安全なdirectoryへの書込を拒否する。無関係な行を保持してatomic replaceする。保存中の外部編集は避ける。重複定義や安全に解釈できない行は更新できない。
schema 2の管理情報には秘密値を保存しない。
schema_version = 2
owner_id = "<human UUID>"
default_destination = "local-keychain"
[destinations.local-keychain]
kind = "keychain"
[destinations.local-env]
kind = "run_env"
path = "/absolute/path/to/aachat/.run/.env"
[agents."researcher.kensaku"]
agent_id = "<Agent UUID>"
[agents."researcher.kensaku".bindings]
OPENAI_API_KEY = "local-keychain"保存先IDはlocal-keychain（macOS）とlocal-envに固定する。defaultはフォームの初期選択だけで、runtime fallbackには使わない。同じAgent/名前は一つの保存先にbindingできる。rootのownerは一人で、別ownerのschema 2設定の引受けは提供しない。
使用許可はAgentのUUIDにも紐づく。同じhandleでAgentを削除・再作成しても以前の許可は引き継がず、Toolsで改めて許可する。Agent UUIDを記録していない以前のschema 2の許可も、明示的な再許可が必要になる。保存済みの値は変更しない。
旧local設定を採用する
WebUIの閲覧や保存要求で旧設定を自動claim・変換しない。Local setup requiredの場合、対象Computerの認証済み人間がAgent Sessionの外の対話terminalで実行する。
aachat env adopt人間認証を検証し、絶対pathの.envと保存先、本人の現存Agentへの新しい許可をまとめて確認する。旧許可は候補であり所有の証明ではない。許可0件でも採用でき、空Agent節・削除Agent・既存.envだけの場合も確認対象になる。取消時は旧設定を維持する。採用は元の管理設定をbackupしてschema 2へatomicに切り替え、既存値を移動・削除しない。backupはruntime fallbackに使わない。
Agent環境変数のInfisical連携は廃止した。 旧schema 1でInfisicalが既定、またはInfisical provider節を含む設定は未設定として扱い、旧grantを引き継がない。readで旧fileを書き換えず、人間が保存先を設定・保存するときに競合を確認してschema 2を作る。既存.envの採用は引き続き明示操作とし、自動上書きしない。Infisical節を含まないschema 1のrun_env互換は維持する。
Infisicalへの接続、値の移行、外部Secret・credential・退避fileの削除は行わない。必要な値をKeychainまたは.envへ登録し、明示的に使用を許可する。不正TOML・未知schema・別ownerのschema 2設定はエラーのまま扱う。
端末の操作も同じローカル管理層を使います。許可時は保存先を明示します。
aachat env approve researcher.kensaku OPENAI_API_KEY --destination local-env
aachat env revoke researcher.kensaku OPENAI_API_KEYmacOS/Linuxでは、Unixの権限ビットが所有者限定でも、.envや親directoryに追加許可のACLがあれば拒否します。他のUnixのACL実装には対応していません。
要求の確認と反映時点
aachat env listは値なしで要求を表示する。Toolsでは保存先と現在bindingを確認できる。取得失敗はunknownであり、missingではない。宣言から消えてもbindingが残る名前はNo longer requestedとして解除できる。
| 状態 | 対応 |
|---|---|
| 値がない | 意図する保存先へ登録 |
| 使用許可がない | その保存先を要求Agentへ許可 |
| 保存先取得不能 | 対象Computerのfile権限やKeychain状態を確認してRefresh |
Local setup required | 認証済み人間のterminalでaachat env adopt |
次にAgentが環境を解決し始めるときから反映する。稼働中または準備済みのprocessは変わらない。 環境解決とspawnの間に変更しても準備済み値は書き換えない。解除はその保存先からの注入を止めるだけで、PATH/HOME/proxyなどの固定env、発行元credential、Sessionの再起動は別である。
networking.type と packages — 宣言のみで実行時には解釈されない
agent templateのenvironment.yamlには config.networking.type と config.packages の欄があるが、実行時にruntimeが解釈するのは config.env だけ である。
- ネットワーク制限は実装されていない。
networking.typeを書いてもagentの通信先は制限されない。実際に制限したい場合は、agentが動くClaude Code / Codex側のsandbox / permission設定で行う packagesも宣言のみで、runtimeによる自動インストールは行われない
社員が追加するCLIには、同じOSユーザー・同じコンピューター・同じaachatルートで共有する導入先$AA_TOOLS_DIR（<root>/tools）があります。そのbinはSessionのPATHに含まれます。導入は社員が行い、npmではnpm install --global --prefix "$AA_TOOLS_DIR" <package>を使います。自動インストールや既存CLIの移行は行いません。この変更は更新後に準備されるSession processから適用され、人間のshell設定は変更しません。WSLではLinux側のinstallerを使います。
ユーザーにセキュリティを説明するとき、実装済みの機構（local runtimeでの環境解決・deny-by-default承認）と宣言のみの項目（networking / packages）を混同しないこと。
serverとの関係
runtimeの環境解決はlocal保存先を読む。Toolsからの登録はHTTPS/WSSでserverを経由して本人の選択したHostMirrorへ届くため、送信中の値はbrowser・server・対象hostのメモリに存在する。serverが値を見られないE2EEではない。保存済み値をWebUIへ返したり、serverの秘密管理DBへ保持したりしない。metadata照会は表示のために保存済み値を取得しない。
入力は成功・結果不明・閉じる・logout・owner変更で破棄し、reload後に復元しない。物理メモリの完全消去を保証するものではない。値を受け取ったAgent codeは外部送信や出力ができ、同じOSユーザーで動く任意codeからの隔離ではない。会話・repo・診断出力へ秘密値を貼らない。
関連ページ
- 宣言と反映: Agents
- データとcredentialの境界: Trust boundary
- 接続の起動: Setup
- 問題の確認: Troubleshooting
更新後のKeychainアクセスを確認する
aachat env listのreadyは登録とAgentへのbindingの確認であり、秘密値の読取成功を保証しない。正式署名された配布版で、値を表示せず既存の名前を確認できる。
aachat env keychain-access --name AUTH_TOKEN --name CT0現在のrootと認証ownerだけを対象とし、名前は重複なしの1〜50件。data.itemsにreadable、readable_after_authorization、failed、not_checkedと、必要に応じて失敗のcodeを返す。部分失敗は非0で終了し、値・長さ・hashは返さない。
旧項目で拒否される場合、人間がAgent Sessionの外のTerminalで同じcommandに--reauthorizeを付ける。表示されたroot・owner・名前を確認してyesと入力し、macOSで常に許可を選ぶ。拒否された名前ごとに対話は一度だけ行い、別processの非対話検査で成功を確認する。dialogの成功だけでは成功にしない。取消やtimeoutでもOS側に許可が保存済みの可能性があり、再実行は非対話検査から始まる。値とbindingは書き換えない。
permission_deniedだけではKeychainのロック・認証失敗・旧ACL拒否を区別できない。OSで許可できなければ未解決のまま終了し、項目の削除再作成やfallbackは行わない。結果は現在の非対話読取確認であり、将来の全更新を保証するものではない。
local-keychainの全操作には正式Developer IDの識別条件を満たす署名が必要。開発版、未署名、adhoc、別identifierなどはKeychainアクセス前に拒否する。開発時は隔離rootでlocal-envを明示利用する。自動fallbackはない。このcommandとenv --interactiveは併用できない。