設定

設定ファイルの探索

Claudex は figment を使用してレイヤード設定を行います。以下の順序でソースがマージされます（後のソースが前のソースを上書き）:

プログラムデフォルト（組み込みフォールバック）
グローバル設定（~/.config/claudex/config.toml または config.yaml）
プロジェクト設定（カレントディレクトリまたは最大 10 階層上の親ディレクトリにある claudex.toml または claudex.yaml、もしくは $CLAUDEX_CONFIG）
環境変数（CLAUDEX_ プレフィックス、__ をセパレータとして使用）

TOML と YAML の両フォーマットに対応しています。ファイルフォーマットは拡張子（.toml または .yaml/.yml）で判別されます。

# 読み込まれた設定パスと全探索場所を表示
claudex config show

# 設定ファイルパスのみ表示
claudex config path

# カレントディレクトリに新しい設定ファイルを作成
claudex config init

# config.example.toml から設定を再作成
claudex config recreate

# $EDITOR で設定ファイルを開く
claudex config edit

# 設定の構文とプロファイル参照を検証
claudex config validate

# 特定の設定値を取得
claudex config get proxy_port

# 特定の設定値を設定
claudex config set proxy_port 8080

# 現在の設定を標準出力にエクスポート
claudex config export

グローバル設定

# claude バイナリのパス（デフォルト: PATH から "claude"）
# claude_binary = "/usr/local/bin/claude"

# プロキシ設定
proxy_port = 13456
proxy_host = "127.0.0.1"

# ログレベル: trace, debug, info, warn, error
log_level = "info"

# ターミナルハイパーリンク（OSC 8）: "auto" | true | false
# "auto" はターミナルのサポートを自動検出、true/false で強制オン/オフ
hyperlinks = "auto"

# モデルエイリアス（短縮名 → 完全モデル名）
[model_aliases]
grok3 = "grok-3-beta"
gpt4o = "gpt-4o"
ds3 = "deepseek-chat"

プロファイル

各プロファイルは AI プロバイダーへの接続を表します。3 種類のプロバイダータイプがあります:

DirectAnthropic

Anthropic Messages API をネイティブにサポートするプロバイダー向けです。リクエストは最小限の変更で転送されます。

[[profiles]]
name = "anthropic"
provider_type = "DirectAnthropic"
base_url = "https://api.anthropic.com"
api_key = "sk-ant-..."
default_model = "claude-sonnet-4-20250514"
priority = 100
enabled = true

互換プロバイダー: Anthropic、MiniMax、Google Vertex AI

OpenAICompatible

OpenAI Chat Completions API を使用するプロバイダー向けです。Claudex が Anthropic と OpenAI のプロトコル間を自動翻訳します。

[[profiles]]
name = "grok"
provider_type = "OpenAICompatible"
base_url = "https://api.x.ai/v1"
api_key = "xai-..."
default_model = "grok-3-beta"
backup_providers = ["deepseek"]
priority = 100
enabled = true

互換プロバイダー: Grok (xAI)、OpenAI、DeepSeek、Kimi/Moonshot、GLM (Zhipu)、OpenRouter、Groq、Mistral、Together AI、Perplexity、Cerebras、Azure OpenAI、GitHub Copilot、GitLab Duo、Ollama、vLLM、LM Studio

OpenAIResponses

OpenAI Responses API を使用するプロバイダー（例: ChatGPT/Codex サブスクリプション）向けです。Claudex が Anthropic Messages API と OpenAI Responses API の間を翻訳します。

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.3-codex"
auth_type = "oauth"
oauth_provider = "openai"

互換プロバイダー: ChatGPT/Codex サブスクリプション（Codex CLI 経由）

プロファイルフィールド

フィールド	デフォルト	説明
`name`	必須	プロファイルの一意な識別子
`provider_type`	`DirectAnthropic`	`DirectAnthropic`、`OpenAICompatible`、または `OpenAIResponses`
`base_url`	必須	プロバイダー API エンドポイント
`api_key`	`""`	API キー（プレーンテキスト）
`api_key_keyring`	—	OS キーチェーンから API キーを読み取り
`default_model`	必須	使用するデフォルトモデル
`auth_type`	`"api-key"`	`"api-key"` または `"oauth"`
`oauth_provider`	—	OAuth プロバイダー（`claude`、`openai`、`google`、`qwen`、`kimi`、`github`、`gitlab`）。`auth_type = "oauth"` の場合に必須
`backup_providers`	`[]`	フェイルオーバー先のプロファイル名
`custom_headers`	`{}`	追加 HTTP ヘッダー
`extra_env`	`{}`	Claude 起動時の追加環境変数
`priority`	`100`	スマートルーティングの優先度
`enabled`	`true`	このプロファイルが有効かどうか
`max_tokens`	—	プロバイダーに送信する最大出力トークン数の上限（オプション）
`strip_params`	`"auto"`	`"auto"`、`"none"`、または `["temperature", "top_p"]`。未対応パラメータを自動検出（例: ChatGPT Codex エンドポイント）
`[profiles.query_params]`	`{}`	URL クエリパラメータ（例: Azure の `api-version`）
`[profiles.models]`	—	モデルスロットマッピングテーブル（`haiku`、`sonnet`、`opus` フィールド）

対話型セットアップ

プロファイルを追加する最も簡単な方法は対話型ウィザードです:

claudex profile add

プロバイダー選択、API キー入力（オプションでキーリング保存）、モデル選択、接続テストをガイドします。

キーリング連携

API キーをプレーンテキストの設定ファイルではなく、OS キーチェーンに安全に保存できます:

[[profiles]]
name = "grok"
api_key_keyring = "grok-api-key"   # OS キーチェーンから読み取り

対応バックエンド:

macOS: Keychain
Linux: Secret Service (GNOME Keyring / KDE Wallet)

OAuth サブスクリプション認証

API キーの代わりに、OAuth を使用して既存のプロバイダーサブスクリプションで認証できます。Claude Pro/Team、ChatGPT Plus などのサブスクリプションプランをお持ちの場合に便利です。

セットアップ

プロファイルの auth_type を "oauth" に設定し、oauth_provider を指定します:

[[profiles]]
name = "codex-sub"
provider_type = "OpenAIResponses"
base_url = "https://chatgpt.com/backend-api/codex"
default_model = "gpt-5.3-codex"
auth_type = "oauth"
oauth_provider = "openai"

auth コマンドでログインします:

claudex auth login openai

認証ステータスを確認します:

claudex auth status

対応プロバイダー

プロバイダー	`oauth_provider`	トークンソース
Claude	`claude`	`~/.claude/.credentials.json`（Claude Code のネイティブ設定）から読み取り
ChatGPT	`openai`	ブラウザ PKCE またはデバイスコード、`~/.codex/auth.json`（Codex CLI）にフォールバック
Google	`google`	Gemini CLI のクレデンシャルから読み取り
Qwen	`qwen`	デバイスコードフロー
Kimi	`kimi`	Kimi CLI のクレデンシャルから読み取り
GitHub	`github`	デバイスコードフロー、`~/.config/github-copilot/` にフォールバック
GitLab	`gitlab`	`GITLAB_TOKEN` 環境変数

各プロバイダーの OAuth フローの詳細は OAuth サブスクリプションを参照してください。

ゲートウェイ認証モード

OAuth プロファイル使用時、Claudex は Claude Code 起動時に ANTHROPIC_API_KEY ではなく ANTHROPIC_AUTH_TOKEN を設定します。これにより、ANTHROPIC_API_KEY を内部的に使用する Claude Code 自体のサブスクリプションログイン機構との競合を防ぎます。

プロキシは OAuth トークンの有効期限切れ前に自動リフレッシュを行います。手動でリフレッシュすることも可能です:

claudex auth refresh openai

クエリパラメータ

一部のプロバイダーは URL クエリパラメータを必要とします（例: Azure OpenAI の api-version）。[profiles.query_params] テーブルを使用します:

[[profiles]]
name = "azure-openai"
provider_type = "OpenAICompatible"
base_url = "https://YOUR_RESOURCE.openai.azure.com/openai/deployments/YOUR_DEPLOYMENT"
api_key = "YOUR_AZURE_KEY"
default_model = "gpt-4o"

[profiles.query_params]
api-version = "2024-12-01-preview"

Claudex はこれらのパラメータをプロファイルのすべてのリクエスト URL に付加します。Azure OpenAI は base_url に openai.azure.com が含まれることで自動検出され、Authorization: Bearer の代わりに api-key ヘッダーが認証に使用されます。

パラメータストリッピング

一部のプロバイダーは特定のパラメータをサポートしていません（例: ChatGPT Codex エンドポイントは temperature、top_p を拒否します）。strip_params フィールドで送信前に除去するパラメータを制御します:

strip_params = "auto"       # 未対応パラメータを自動検出して除去（デフォルト）
strip_params = "none"       # すべてのパラメータをそのまま送信
strip_params = ["temperature", "top_p", "top_k"]  # 指定パラメータを除去

"auto" に設定すると、Claudex は既知のエンドポイント（例: chatgpt.com）を検出し、エラーの原因となるパラメータを除去します。

モデルスロットマッピング

Claude Code には haiku、sonnet、opus の 3 つのスロットを持つ /model スイッチャーが組み込まれています。詳細はモデルスロットマッピングを参照してください。

ツール名互換性

一部のプロバイダー（特に OpenAI）はツール（関数）名に 64 文字の制限を課しています。Claude Code はこの制限を超えるツール名を生成することがあります。

Claudex は OpenAI 互換プロバイダーへのリクエスト送信時に 64 文字を超えるツール名を自動的に短縮し、レスポンス処理時に元の名前を透過的に復元します。このラウンドトリップは完全に透過的です。

非対話モード

Claudex は CI/CD パイプライン、スクリプト、自動化で使用するためのワンショット（非対話）実行をサポートしています:

# レスポンスを出力して終了
claudex run grok "Explain this codebase" --print

# すべての権限プロンプトをスキップ（完全自動化パイプライン用）
claudex run grok "Fix lint errors" --print --dangerously-skip-permissions

非対話モードでは、ログは stderr ではなくインスタンスごとのログファイル ~/Library/Caches/claudex/proxy-{timestamp}-{pid}.log に書き込まれ、パイプラインや自動化のための stdout 出力をクリーンに保ちます。

ターミナルハイパーリンク

Claudex はターミナル出力で OSC 8 クリック可能なハイパーリンクをサポートしています。詳細はターミナルハイパーリンクを参照してください。

# "auto" はターミナルのサポートを自動検出、true/false で強制オン/オフ
hyperlinks = "auto"

コンフィギュレーションセット

ルール、スキル、MCP サーバーの再利用可能なバンドルをインストールできます。詳細はコンフィギュレーションセットを参照してください。

claudex sets add ./my-set
claudex sets list

完全な設定例

すべてのプロバイダーとオプションを含む完全な設定ファイルは config.example.toml を参照してください。

各プロバイダーのステップバイステップのセットアップ手順（API キーリンクや OAuth フローを含む）は、プロバイダーセットアップガイドを参照してください。