【忘備録】AIコーディングエージェントにAPIキーを設定して使えるようにする（OpenCode / oimo / Cursor）

AIコーディングエージェント（OpenCode / oimo / Cursor Agent）に外部LLMのAPIキーを入れて、実際にモデルを呼べるまでの手順を忘備録として残します。今回の例は Groq です。

注意: APIキーの実値は記事・チャット・Git に書かないこと。この記事でもプレースホルダのみ使います。

全体の流れ

  • API キーを発行（今回は Groq）
  • 有名所なら auth login -p groq で登録
  • 識別子が無いマイナー系は「Other + 自前 ID」＋設定ファイルで追加
  • モデル一覧で見えることを確認
  • （任意）Cursor Agent からも使えるよう MCP を追加
  • チャットにキーを貼ってしまった場合はローテーション

1. Groq の API キーを発行

  • Groq Console → API Keys で Create API Key
  • 表示されたキー（gsk_...）はその場で控える（再表示できないことが多い）
  • 権限は必要最小限、用途が分かる名前を付ける

2. OpenCode に登録

いちばん簡単です。TUI で /connect → Groq を選び、キーを貼り付けます。または:

opencode auth login -p groq

資格情報の保存先（実体）:

~/.local/share/opencode/auth.json
# 形式のイメージ（値は書かない）
# { "groq": { "type": "api", "key": "gsk_..." } }

確認:

opencode auth list
opencode models groq

起動時にモデル指定する例:

opencode -m groq/llama-3.3-70b-versatile
# または
opencode -m groq/openai/gpt-oss-120b

3. oimo（Open Mimo Code）に登録

OpenCode と同系統なので手順はほぼ同じです。

oimo auth login -p groq
oimo auth list
oimo models groq
oimo -m groq/llama-3.1-8b-instant

保存先:

~/.local/share/oimo/auth.json

設定ファイル（~/.config/opencode/opencode.jsonc / ~/.config/oimo/oimo.jsonc）に apiKey を直書きしない方が安全です。auth 側に置くのが本筋です。

4. 疎通確認（キーをログに出さない）

CLI でモデル一覧が出れば登録は成功です。API を直接叩く場合も、コマンド履歴や画面にキーを残さないよう注意します。

# 例: auth.json から読む（値は表示しない）
# curl の -H に直書きしたコマンドを履歴に残さないこと

# うまくいかないとき
# - 403 / Cloudflare: User-Agent 付きで再試行することがある
# - 401: キー無効・コピペ欠け・ローテ済み

5. Cursor Agent からも使えるようにする（MCP）

Cursor 本体のモデル切替（OpenAI Base URL 上書き）は環境によって不安定なことがあるため、今回は Agent が MCP 経由で Groq を呼ぶ形にしました。既存の Ollama MCP と同じ発想です。

~/.cursor/mcp.json に例えば次を追加（キーはここに書かない）:

{
  "mcpServers": {
    "groq": {
      "command": "node",
      "args": ["/home/あなた/.cursor/groq-mcp/server.mjs"]
    }
  }
}

MCP サーバー側で GROQ_API_KEY、または OpenCode/oimo の auth.json からキーを読むようにしておくと、設定ファイルへの二重管理を避けられます。

用意したツール例:

  • list_models … Groq のモデル一覧
  • chat … チャット補完
  • generate … 単発生成

追加後は Cursor のリロード（または新しい Agent チャット）が必要です。反映後、「Groq の llama-3.3-70b-versatile に聞いて」などと頼めば MCP 経由で呼べます。

6. シェルでも使う場合

対話シェル用に環境変数を載せるなら、ホーム配下の権限付きファイルから読む形が無難です。

# ~/.config/groq/.env  （権限 600）
GROQ_API_KEY=ここにキー

# ~/.bashrc 例
if [ -f "$HOME/.config/groq/.env" ]; then
  set -a
  . "$HOME/.config/groq/.env"
  set +a
fi

7. やってはいけないこと / 漏れたとき

  • チャット・Issue・PR・スクリーンショットにキーを貼る
  • リポジトリの .env をコミットする（.gitignore 必須）
  • mcp.json や設定ファイルに本番キーを平文で共有する

もしチャットに貼ってしまったら:

  1. 発行元コンソールで該当キーを即無効化
  2. 新しいキーを発行
  3. auth login / auth.json / .env を差し替え
  4. 古いキーが残っていないか auth list と設定パスを確認

8. 識別子が無いマイナープロバイダの追加方法

Groq のようにエージェント側が最初から知っているプロバイダなら auth login -p groq で済みます。一方、Models.dev / 内蔵リストに無いゲートウェイや自前 APIだと、プロバイダ ID 自体が存在しません。このときは「自分で ID を決める → 資格情報を紐づける → 設定でエンドポイントとモデルを宣言する」の三セットが必要です。

前提はだいたい次のどちらかです。

  • OpenAI 互換（/v1/chat/completions）→ npm: "@ai-sdk/openai-compatible"
  • Responses API 系 → npm: "@ai-sdk/openai"

8.1 資格情報: Other で自前 ID を作る

TUI なら /connect、CLI なら opencode auth login（oimo も同様）で、一覧に無いときは Other を選びます。

$ /connect
┌  Add credential
│◆  Select provider
│  ...
│  ● Other
└

┌  Enter provider id
│  myprovider          ← 好きな英数字 ID（後で設定と一致させる）
└

▲  This only stores a credential for myprovider
   - you will need to configure it in opencode.json
◇  Enter your API key
│  sk-...              ← 実値はここに貼るだけ。記事や Git には書かない
└

これで ~/.local/share/opencode/auth.json（oimo なら ~/.local/share/oimo/auth.json）に、例えば次の形で入ります（値は出さない）:

{
  "myprovider": {
    "type": "api",
    "key": "（APIキー）"
  }
}

手で書く場合も同じ JSON で足せます。権限は 0600 推奨です。

8.2 設定: baseURL と models を宣言する

資格情報だけではモデルは出てきません。カスタム ID にはカタログが無いので、~/.config/opencode/opencode.jsonc（oimo は ~/.config/oimo/oimo.jsonc）側でエンドポイントとモデル ID を明示します。auth のキー名（provider ID）と設定のキー名は完全一致させます。

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "myprovider": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "My AI Provider",
      "options": {
        "baseURL": "https://api.myprovider.com/v1"
      },
      "models": {
        "my-model-id": {
          "name": "My Model Display Name",
          "tool_call": true,
          "limit": { "context": 128000, "output": 8192 }
        }
      }
    }
  }
}

ポイント:

  • models のキーは、API が受け付ける 実モデル ID（表示名ではない）
  • baseURL は多くの場合 /v1 まで含める（足りないと 404 になりがち）
  • キーを設定に直書きしたくないときは auth / 環境変数側に置き、options.apiKey は使わない
  • どうしても設定に書くなら "apiKey": "{env:MYPROVIDER_API_KEY}" の参照形にする

8.3 実例: 既存の Ollama（LAN）も同じパターン

ローカル／LAN の Ollama も、実質「識別子を自分で定義するカスタムプロバイダ」です。キーが不要でも、互換アダプタ用にダミー文字列を入れることがあります。

{
  "$schema": "https://opencode.ai/config.json",
  "model": "ollama/qwen2.5-coder:14b",
  "provider": {
    "ollama": {
      "name": "Ollama (192.168.0.234)",
      "npm": "@ai-sdk/openai-compatible",
      "only_configured_models": true,
      "models": {
        "qwen2.5-coder:14b": {
          "name": "Qwen2.5 Coder 14B",
          "tool_call": true,
          "limit": { "context": 32768, "output": 8192 }
        }
      },
      "options": {
        "baseURL": "http://192.168.0.234:11434/v1",
        "apiKey": "ollama"
      }
    }
  }
}

8.4 確認とハマりどころ

opencode auth list
opencode models myprovider
opencode -m myprovider/my-model-id

oimo auth list
oimo models myprovider
oimo -m myprovider/my-model-id
  • auth の ID と config の ID が違う → いちばん多いミス
  • npm パッケージ違い → chat completions なら openai-compatible、responses なら openai
  • baseURL が短い／長い → ドキュメントの例どおり .../v1 を疑う
  • モデル ID 不一致 → プロバイダ側の /v1/models で実名を確認
  • Cursor Agent 側は、マイナー系も「OpenAI 互換 MCP」や自前 MCP で同じ baseURL を叩く形にすると揃いやすい

まとめ（自分用チェックリスト）

  • [ ] API キー発行（有名所例: Groq）
  • [ ] 有名所: auth login -p groq → models groq
  • [ ] マイナー: /connect → Other → 自前 ID → opencode.jsonc / oimo.jsonc に baseURL + models
  • [ ] auth の provider ID と設定キーが一致している
  • [ ] （任意）Cursor MCP を追加してリロード
  • [ ] キーは auth / 600 の env のみ。記事・Git・チャットに出さない

以上、次回同じことをやるときの手順メモでした。

スポンサーリンク

コメント

タイトルとURLをコピーしました