# AI エージェントとの接続

いつもどおり `claude` と打つだけで、そのリポジトリで読める鍵が環境変数として渡ります。ファイルは作りません。

## 仕込む

端末ごとに 1 回です。

```sh
aikagi hook install
```

これで 2 つのことが起きます。`~/.aikagi/bin` が PATH の先頭に入ること、そしてディレクトリを移るたびに `.aikagi.toml` を探すしくみがシェルに入ることです。既定では `claude` と `codex` が対象になります。

ほかのコマンドも同じように扱いたいときは、名前を足してください。

```sh
aikagi hook install --command claude --command codex --command <コマンド名>
```

シェルは `$SHELL` から判断します。違うものを設定したいときは `--shell` で指定してください。やめるときは `aikagi hook uninstall` です。

## 仕込みをエージェントに任せる

ここまでの手順は、ふだん使っている AI エージェントに任せられます。下の在り処をそのまま渡してください。エージェントが読むための手引き（英語）です。

```sh
https://aikagi.dev/guide/agent-setup.md
```

途中で 2 か所だけ、あなたの手が要ります。ブラウザでのサインインと、鍵を入れるところです。

## 使う

あとは変わりません。

```sh
cd repo && claude
```

起こっているのはこういうことです。

1. PATH の先頭にいる aikagi が呼ばれ、`.aikagi.toml` からワークスペース・プロジェクト・環境を読みます。
2. サーバに問い合わせ、あなたがそこで読める鍵を受け取ります。
3. それを環境変数に載せて、本物の `claude` を起動します。aikagi 自身はそこで役目を終えます。

設定が見つからないディレクトリでは、aikagi は何もせずそのまま本物を起動します。

## 鍵はどんな名前で届くか

環境変数の名前は、キーの名前から作られます。`openai/api_key` なら `OPENAI_API_KEY`、`database/url` なら `DATABASE_URL` です。フォルダもふくめて大文字にし、スラッシュをアンダースコアに変えた形です。

渡る範囲は、**あなたの**役割とフォルダの範囲で決まります。手元で動かす AI ツールはあなたとして動くので、あなたが読める鍵がそのまま渡ります。

人の手が入らないところ（CI や常駐の処理）では、代わりに[エージェント](https://aikagi.dev/guide/members.md)を作って、その鍵で動かします。

`.env` のようなファイルは作りません。値はその子プロセスの中にしかありません。

## フックを使わずに渡す

PATH に手を入れたくない、1 回だけ試したい、という場合はこちらです。

```sh
aikagi run -- claude
aikagi run -- npm test
```

通る経路も、記録の残りかたも、フックの場合と同じです。

## エージェント自身に取りに行かせる

起動のときにまとめて渡すほかに、必要になった瞬間に 1 本だけ取る道もあります。

```sh
aikagi get stripe/secret_key
```

1 回の取得が[記録](https://aikagi.dev/guide/audit.md)の 1 行です。

エージェントにこの使いかたを教えたいときは、説明書きを生成できます。リポジトリに `AIKAGI.md` ができるので、そのままエージェントに読ませてください。

```sh
aikagi agent-docs
```

## うまくいかないとき

サーバに届かない、ログインが切れている、といったときは、注意を 1 行出したうえで鍵なしで本物を起動します。**エージェントの起動そのものは止めません。**鍵が無いなら起動してほしくない、という場合は `AIKAGI_STRICT=1` を立ててください。

鍵が渡っていないように見えるときは、順に確かめてください。

- `aikagi doctor` を打つ。PATH の並びとシェルの設定はここで分かります。
- そのディレクトリに `.aikagi.toml` があるか。無ければ `aikagi init`。
- 起動したコマンドが `[commands.…]` に書かれているか。
- そのキーがあなたの範囲に入っているか。`aikagi ls` に出なければ、渡ってもいません。

---

出典: https://aikagi.dev/guide/agents/