AIエージェントに調査、実装、PR作成、MCP操作を任せるとき、一番雑に扱われやすいのが秘密情報です。最初は「.env は貼らない」だけで始めても、private package を入れるための token、staging API key、GitHub token、MCP の OAuth token、ブラウザ cookie、CI secret がすぐに絡みます。
この記事では、AIエージェントの 秘密情報 / secret handling を扱います。組織全体の利用ルールは AIコーディングツールの社内ガイドライン、一度許可した権限の棚卸しは AIエージェント権限棚卸し設計ガイド、Codex cloud の setup script と secrets の境界は Codex cloud environment 設計ガイド、外部通信を開ける判断は Codex internet access 安全運用ガイド に分けています。
今回の論点は、秘密情報をどこに置くかではなく、AIエージェントの run に secret をどう入れないか、入れるならどう短命化して消すかです。
先に結論: secret は agent の文脈ではなく実行境界に置く
secret handling で最初に決めるべきことは、どの secret manager を使うかではありません。AIエージェントの文脈、tool、shell、MCP、ログ、成果物のどこから secret が見えるかです。
私なら、最初に次の4段階へ分けます。
| 段階 | 決めること | 失敗例 |
|---|---|---|
| pre-run | そもそも secret が必要な task か | 調査だけなのに production token を渡す |
| runtime | どの process / tool だけが読めるか | agent phase 全体の env に token を残す |
| output | ログ、PR、final answer に出さないか | build log の raw output に token が混ざる |
| post-run | 失効、rotation、証跡をどう扱うか | 一時 token が残り続ける |
この4段階がないと、「AIにsecretを見せていないつもり」でも、実際には shell、MCP server、browser profile、CI log、artifact store のどこかに残ります。
secret handling と権限設計は似ているが同じではない
権限設計は「何ができるか」を決めます。secret handling は「何を知ってしまうか」を決めます。
たとえば、read-only の調査 task でも、環境変数に production credential が見えていれば危険です。逆に、write tool を持つ task でも、短命の staging token だけを専用 process に渡し、ログに出さず、run 後に失効できるならリスクは下げられます。
既存の権限ルールだけで secret を守ろうとすると、次の抜けが出ます。
| ありがちな対策 | 残る問題 |
|---|---|
.env を読ませない | shell command や test output から値が出る |
| token を環境変数に入れる | agent phase 全体から読める |
| PRにログを貼らない | CI artifact や MCP result に残る |
| 承認制にする | 承認画面に secret payload を載せてしまう |
| token を後で消す | どの token が使われたか分からない |
secret は「見えたら終わり」ではありません。見えた場所、用途、保存先、失効条件まで追えないと、事故時に切り分けられません。
まず secret inventory を作る
AIエージェントに渡る可能性がある secret は、API key だけではありません。
| 種類 | 例 | 注意点 |
|---|---|---|
| API token | GitHub token、SaaS API key | scope と owner を分ける |
| package credential | npm / PyPI / private registry token | install 時だけ必要なことが多い |
| cloud credential | AWS / GCP / Azure key | agent に直接渡さない前提から始める |
| database credential | staging / production DB URL | read-only でも顧客データに触れる |
| MCP credential | OAuth token、client secret | server と downstream API の token を混ぜない |
| browser state | cookie、session storage、signed-in profile | 画面操作と credential 利用が一体化しやすい |
| local secret file | .env、private key、credentials file | deny read だけでなく log 出力も見る |
この inventory には、少なくとも owner、purpose、scope、runtime_visibility、expires_at を持たせます。
agent_secret:
id: "sec-20260809-npm-read"
owner: "platform-team"
purpose: "install private packages in setup script"
scope:
registry: "npm-internal"
permission: "read"
runtime_visibility: "setup_only"
allowed_tasks:
- "dependency install"
forbidden_tasks:
- "agent reasoning"
- "PR comment"
- "MCP tool result"
expires_at: "2026-08-16"runtime_visibility が曖昧な secret は、AIエージェントへ渡す前に止めます。「必要そうだから入れておく」は、agent 運用では一番危ない置き方です。
pre-run で secret 不要の lane に落とす
多くの task は、secret なしで進められます。
| task | secret 不要にする方法 |
|---|---|
| docs 調査 | public docs と local fixture だけで行う |
| PR review | diff と test result だけを渡す |
| 設計相談 | 本番ログではなく schema / anonymized sample を渡す |
| 再現調査 | scrub 済み log と local mock を使う |
| 依存確認 | lockfile と registry metadata の read-only view にする |
pre-run の判断で大事なのは、「あれば便利」と「ないと完了しない」を分けることです。AIエージェントが secret を持つと、出力、ログ、tool call、記憶、artifact のすべてで取り扱いが重くなります。便利さだけなら、secret なし lane に落とした方がよいです。
runtime では setup-only と agent-visible を分ける
Codex cloud の公式ドキュメントでは、environment variables は task 全体に設定される一方、secrets は setup script で使われ、security reasons により agent phase 前に削除されると説明されています。これは実務上かなり重要です。
private package の install token は、setup script だけで使えれば十分なことが多いです。逆に、agent が後続の command で使う必要がある値を secret に入れると、agent phase では見えずに失敗します。
| 置き方 | 向くもの | 避けるもの |
|---|---|---|
| setup-only secret | private package install、bootstrap token | agent が後で読む設定値 |
| agent-visible env | public endpoint、feature flag、non-secret config | production token、cookie、private key |
| one-shot token | staging API の短時間 read | 長期運用 token |
| tool-scoped credential | 特定 MCP tool の read 操作 | 複数 server で使い回す token |
判断基準は単純です。agent が文章として reasoning するために必要な値なら、それは secret として渡すべきではありません。実行に必要な credential なら、できるだけ agent の文脈ではなく、限定された process や setup step に閉じます。
ログに出る前提で redaction を設計する
secret は「渡さない」が原則ですが、現実にはログに混ざります。
- package manager が token 付き URL を出す
- test が環境変数一覧を出す
- SDK が request header を debug log に出す
- MCP server が raw API response を返す
- agent が error をそのまま PR に貼る
このため、redaction は後付けではなく run の条件にします。
secret_output_policy:
block_patterns:
- "AKIA[0-9A-Z]{16}"
- "ghp_[A-Za-z0-9_]{30,}"
- "-----BEGIN PRIVATE KEY-----"
output_rules:
final_answer: "summary_only"
pr_body: "no_raw_logs"
tool_result: "redact_before_store"
ci_artifact: "short_retention"
on_match:
action: "stop_and_escalate"
rotate_required: true完璧な正規表現で全 secret を検出するのは無理です。それでも、代表的な token、private key、.env、cookie、Authorization header を止めるだけで、事故の大半は早く見つけられます。
MCP では token passthrough を禁止する
MCP を使う場合、secret handling はさらに難しくなります。MCP server は agent から tool として呼ばれますが、その背後には GitHub、Slack、Notion、DB、社内API がいます。
危ないのは、MCP server が下流 API の token をそのまま受け取り、別の API へ流用できる状態です。MCP の authorization / security best practices では token passthrough を避ける設計が重要になります。
MCP server には、最低限この境界を持たせます。
mcp_secret_boundary:
server_id: "github-read"
token_audience: "mcp-github-read"
downstream_access:
repositories:
- "example/app"
permissions:
issues: "read"
pull_requests: "read"
contents: "read"
forbidden:
- "reuse_user_oauth_token_for_downstream_api"
- "return_authorization_header_to_agent"
- "include_raw_api_response_with_tokens"server を許可するだけでは粗すぎます。token の audience、scope、tool result の redaction、監査ログの粒度まで一緒に決めます。
ブラウザ操作では signed-in profile を secret として扱う
AIエージェントにブラウザ操作を許すと、cookie や signed-in session が secret になります。
これは API key のように見えませんが、実質的には権限です。ログイン済みブラウザで操作できるなら、その agent はそのユーザーとして画面を読み、場合によっては書けます。
ブラウザ操作を許すなら、次を分けます。
| 項目 | 判断 |
|---|---|
| profile | 個人の普段使い profile か、agent 専用 profile か |
| site scope | どの domain だけ許すか |
| action | read、draft、submit を分ける |
| cookie | run 後に残すか、専用 profile ごと破棄するか |
| screenshot | 顧客情報や token が映らないか |
特に「モバイルで承認だけ返す」「remote host 上の Chrome profile を使う」ような運用では、操作端末ではなく host 側の session が副作用を持ちます。便利さだけで signed-in profile を渡さない方がよいです。
secret を含む task の PR には raw log を貼らない
secret が絡む task では、PR 本文や final answer の書き方も変えます。
良い報告は、secret を含まない確認事実だけを返します。
Verification:
- `pnpm run build` passed.
- Private registry install succeeded in setup step.
- No runtime env containing registry token was present in agent phase.
- Work log reviewed for token-like output; no match found.
Risks:
- Staging API token was issued for this run and expires at 2026-08-09T12:00:00Z.悪い報告は、便利そうに見えて危険です。
The command failed with:
TOKEN=...
Authorization: Bearer ...
Full env:
...reviewer に必要なのは、secret の値ではありません。どの secret が、どの用途で、どの期間、どの process にだけ見え、run 後にどう失効するかです。
失効と rotation を完了条件に入れる
secret handling は、task が成功した時点では終わりません。
次のいずれかに該当するなら、失効または rotation を完了条件に入れます。
- one-shot token を発行した
- staging / production API に触れた
- MCP write scope を使った
- browser session を使った
- log に secret らしき値が出た
- agent が secret file へアクセスしようとした
post_run_secret_closeout:
run_id: "agent-run-20260809-004"
secrets_used:
- id: "sec-20260809-staging-api-read"
action: "expired"
evidence: "vault lease ended"
- id: "sec-20260809-browser-profile"
action: "profile_deleted"
evidence: "agent profile removed"
log_review:
token_pattern_match: false
raw_log_retention: "7d"
incident_required: falseここまでを完了条件にしないと、AIエージェントの作業は「実装は終わったが credential が残っている」状態になりがちです。
実務テンプレート
私なら、secret を使う可能性がある task には次のテンプレートを付けます。
Secret handling:
- Do not read `.env`, private keys, browser cookies, or credential files.
- If a credential is required, stop and ask for a task-scoped, short-lived token.
- Use setup-only secrets for package installation; do not expose them to the agent phase.
- Do not paste raw logs, headers, env values, or MCP raw responses into the PR or final answer.
- If token-like output appears, stop, report `secret_exposure_suspected`, and require rotation.
Allowed:
- public docs
- scrubbed logs
- staging fixtures
- read-only metadata
Forbidden:
- production credentials
- personal browser session
- customer data exports
- downstream token passthrough短いですが、これだけでも agent の挙動は変わります。特に「必要なら止まる」と「値を貼らない」を明文化することが効きます。
まとめ
AIエージェントの secret handling は、秘密情報を隠す小技ではありません。task を始める前に secret 不要 lane へ落とし、必要な場合だけ短命・最小 scope・限定 process に閉じ、ログやPRに出さず、run 後に失効する設計です。
.env を貼らない、だけでは足りません。agent は shell、MCP、browser、CI、artifact store をまたいで動きます。secret がどこから見え、どこへ出力され、いつ消えるかを run 単位で固定してください。
最初の標準は、setup-only secret、agent-visible env の禁止、MCP token passthrough 禁止、raw log 非掲載、post-run rotation の5つで十分です。これを守れない task は、AIエージェントに任せる前に作業 lane を分けるべきです。