[クラウドゲートウェイ向けBYOKサポート] - Support BYOK (Bring Your Own Key) for Cloud Gateways

このガイドでは、クラウドにデプロイされたOpenClawゲートウェイにBring Your Own Key（BYOK）サポートを追加するための実装要件について説明します。ユーザーは、アプリケーションにバンドルされた認証情報頼る代わりに、独自のAIプロバイダーAPIキー（OpenAI、Anthropic、Google AIなど）を提供できる必要があります。

機能の範囲

クラウドゲートウェイ用のBYOKシステムは、3つのレイヤーでの実装を必要とします：

• クライアントサイドUI: プロバイダーごとにAPIキーを入力、表示、管理するための設定インターフェース
• セキュアストレージ: デスクトップクライアントでのKeychain統合、モバイルでの暗号化ボールト
• ゲートウェイ設定: クラウドにデプロイされたゲートウェイ用の環境変数注入メカニズム

既存の実装参照

ローカルゲートウェイはすでにセットアップウィザードを通じてBYOKを実装しています（PR #221参照）。クラウドゲートウェイの実装は、確立されたパターンに従いながら、クラウド固有の考慮事項に対処する必要があります：

Local Gateway BYOK Architecture:
┌─────────────┐     ┌──────────────┐     ┌─────────────┐
│ Setup Wizard│────▶│ Secure Storage│────▶│ .env.local  │
│   (UI)      │     │   (Keychain)  │     │   (File)    │
└─────────────┘     └──────────────┘     └─────────────┘

Cloud Gateway BYOK Architecture:
┌─────────────┐     ┌──────────────┐     ┌──────────────────┐     ┌─────────────┐
│ Settings UI │────▶│ Secure Vault │────▶│ Config API Patch │────▶│ Env Var     │
│   (Cloud)   │     │  (Encrypted) │     │   (Gateway)      │     │ Injection   │
└─────────────┘     └──────────────┘     └──────────────────┘     └─────────────┘

アーキテクチャコンポーネント

1. API Key Provider Registry

システムは、サポートされているAIプロバイダーとその設定要件のレジストリを維持する必要があります：

// src/providers/registry.ts
export interface ProviderConfig {
  id: string;
  name: string;
  apiKeyEnvVar: string;
  endpoint?: string;
  requiresOrgId?: boolean;
  documentationUrl: string;
}

export const AI_PROVIDERS: Record<string, ProviderConfig> = {
  openai: {
    id: 'openai',
    name: 'OpenAI',
    apiKeyEnvVar: 'OPENAI_API_KEY',
    endpoint: 'https://api.openai.com/v1',
    documentationUrl: 'https://platform.openai.com/docs/api-keys'
  },
  anthropic: {
    id: 'anthropic',
    name: 'Anthropic',
    apiKeyEnvVar: 'ANTHROPIC_API_KEY',
    documentationUrl: 'https://docs.anthropic.com/en/api/getting-started'
  },
  google: {
    id: 'google',
    name: 'Google AI',
    apiKeyEnvVar: 'GOOGLE_API_KEY',
    requiresOrgId: true,
    documentationUrl: 'https://ai.google.dev/tutorials/setup'
  }
};

2. セキュアストレージ仕様

クライアントサイドストレージ（Keychain/Secure Enclave）

// src/storage/secure-keychain.ts
interface SecureKeyStorage {
  // Store API key with provider identifier
  setApiKey(provider: string, key: string): Promise<boolean>;
  
  // Retrieve API key (returns null if not found)
  getApiKey(provider: string): Promise<string | null>;
  
  // List configured providers (without exposing keys)
  listProviders(): Promise<string[]>;
  
  // Remove API key
  deleteApiKey(provider: string): Promise<boolean>;
  
  // Validate key format before storage
  validateKeyFormat(provider: string, key: string): ValidationResult;
}

interface ValidationResult {
  valid: boolean;
  error?: string;
  maskedKey?: string; // e.g., "sk-...xyz"
}

キー形式検証パターン

// Validation patterns by provider
const KEY_PATTERNS = {
  openai: /^sk-[A-Za-z0-9_-]{20,}$/,
  anthropic: /^sk-ant-[A-Za-z0-9_-]{20,}$/,
  google: /^[A-Za-z0-9_-]{39}$/,
  azure: /^[A-Za-z0-9]{32}$/
};

3. ゲートウェイ設定API

クラウドゲートウェイには、安全な設定パッチメカニズムが必要です：

// Gateway Config API Endpoint
// POST /api/v1/gateway/config/patch

interface ConfigPatchRequest {
  operation: 'set' | 'remove';
  target: 'env' | 'secret';
  key: string;
  value?: string; // Required for 'set' operation
  metadata?: {
    provider?: string;
    createdAt: string;
    expiresAt?: string;
  };
}

interface ConfigPatchResponse {
  success: boolean;
  appliedAt: string;
  restartRequired: boolean;
  error?: string;
}

フェーズ1: 設定UIコンポーネント

ステップ1.1: API Key Management Panelの作成

// src/components/Settings/ApiKeyManager.tsx

import { useState } from 'react';
import { KeychainStorage } from '@/storage/secure-keychain';
import { AI_PROVIDERS } from '@/providers/registry';
import { BillingDisclaimer } from './BillingDisclaimer';

export function ApiKeyManager() {
  const [selectedProvider, setSelectedProvider] = useState<string | null>(null);
  const [apiKey, setApiKey] = useState('');
  const [isValidating, setIsValidating] = useState(false);
  const [configuredProviders, setConfiguredProviders] = useState<string[]>([]);
  
  // Load configured providers on mount
  useEffect(() => {
    KeychainStorage.listProviders().then(setConfiguredProviders);
  }, []);

  const handleSaveKey = async () => {
    if (!selectedProvider || !apiKey) return;
    
    setIsValidating(true);
    const validation = KeychainStorage.validateKeyFormat(selectedProvider, apiKey);
    
    if (!validation.valid) {
      showError(validation.error);
      setIsValidating(false);
      return;
    }

    // Store securely
    await KeychainStorage.setApiKey(selectedProvider, apiKey);
    
    // Sync to cloud gateway
    await syncKeyToGateway(selectedProvider, apiKey);
    
    // Clear input and refresh list
    setApiKey('');
    setConfiguredProviders(await KeychainStorage.listProviders());
    setIsValidating(false);
  };

  return (
    <div className="api-key-manager">
      <BillingDisclaimer />
      
      <div className="provider-grid">
        {Object.values(AI_PROVIDERS).map(provider => (
          <ProviderCard
            key={provider.id}
            provider={provider}
            isConfigured={configuredProviders.includes(provider.id)}
            onSelect={() => setSelectedProvider(provider.id)}
          />
        ))}
      </div>

      {selectedProvider && (
        <ApiKeyInputForm
          provider={AI_PROVIDERS[selectedProvider]}
          value={apiKey}
          onChange={setApiKey}
          onSubmit={handleSaveKey}
          isLoading={isValidating}
        />
      )}
    </div>
  );
}

ステップ1.2: Billing Disclaimer Componentの作成

// src/components/Settings/BillingDisclaimer.tsx

export function BillingDisclaimer() {
  return (
    <div className="billing-disclaimer">
      <div className="disclaimer-icon">💳</div>
      <div className="disclaimer-content">
        <h4>請求の責任</h4>
        <p>
          独自のAPIキーを提供すると、すべての利用コストはAIプロバイダーのアカウントに直接請求されます。OpenClawは、APIの使用や請求を処理、加算、または可視化することはできません。
        </p>
        <ul>
          <li>プロバイダーの利用制限とクォータの責任はあなたにあります</li>
          <li>APIキーは安全に送信され、サーバー上にプレーンテキストで保存されることはありません</li>
          <li>プロバイダーのダッシュボードからいつでもアクセスを取り消すことができます</li>
        </ul>
        <a href="../../../docs/byok/billing-faq" target="_blank">
          BYOK請求の詳細 →
        </a>
      </div>
    </div>
  );
}

フェーズ2: セキュアストレージの実装

ステップ2.1: Keychain Storage Service

// src/storage/secure-keychain.ts

export class KeychainStorage implements SecureKeyStorage {
  private static readonly SERVICE_PREFIX = 'openclaw.byok';
  
  static async setApiKey(provider: string, key: string): Promise<boolean> {
    const service = `${this.SERVICE_PREFIX}.${provider}`;
    
    // Platform-specific implementation
    if (Platform.OS === 'ios' || Platform.OS === 'android') {
      return this.setSecureItem(service, key);
    }
    
    // Desktop: Use electron-store with encryption or native Keychain
    if (process.env.ELECTRON === 'true') {
      return this.setElectronKeychain(service, key);
    }
    
    throw new Error(`Platform ${Platform.OS} does not support secure storage`);
  }

  static async getApiKey(provider: string): Promise<string | null> {
    const service = `${this.SERVICE_PREFIX}.${provider}`;
    
    if (Platform.OS === 'ios') {
      return this.getIOSKeychain(service);
    }
    if (Platform.OS === 'android') {
      return this.getAndroidKeystore(service);
    }
    if (process.env.ELECTRON === 'true') {
      return this.getElectronKeychain(service);
    }
    
    return null;
  }

  static async listProviders(): Promise<string[]> {
    // Return list of providers with stored keys (without exposing the keys)
    const prefix = `${this.SERVICE_PREFIX}.`;
    const services = await this.listSecureServices(prefix);
    return services.map(s => s.replace(prefix, ''));
  }

  static validateKeyFormat(provider: string, key: string): ValidationResult {
    const pattern = KEY_PATTERNS[provider];
    
    if (!pattern) {
      return { valid: false, error: `Unknown provider: ${provider}` };
    }

    const trimmedKey = key.trim();
    
    if (!pattern.test(trimmedKey)) {
      return {
        valid: false,
        error: `Invalid key format for ${provider}. Expected format: ${pattern.description}`
      };
    }

    return {
      valid: true,
      maskedKey: this.maskKey(trimmedKey)
    };
  }

  private static maskKey(key: string): string {
    // Show first 3 and last 4 characters
    if (key.length <= 10) return '***';
    return `${key.slice(0, 3)}...${key.slice(-4)}`;
  }
}

フェーズ3: ゲートウェイ設定の同期

ステップ3.1: クラウドゲートウェイAPIクライアント

// src/services/gateway-config-sync.ts

export class GatewayConfigSync {
  private readonly gatewayApiBase: string;

  constructor(gatewayId: string) {
    this.gatewayApiBase = `https://${gatewayId}.gateways.openclaw.io`;
  }

  async syncApiKey(provider: string, apiKey: string): Promise<ConfigPatchResponse> {
    const providerConfig = AI_PROVIDERS[provider];
    
    if (!providerConfig) {
      throw new Error(`Unknown provider: ${provider}`);
    }

    const response = await fetch(`${this.gatewayApiBase}/api/v1/config/patch`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${await this.getGatewayToken()}`
      },
      body: JSON.stringify({
        operation: 'set',
        target: 'secret', // Use secret, not env, for API keys
        key: providerConfig.apiKeyEnvVar,
        value: apiKey,
        metadata: {
          provider,
          createdAt: new Date().toISOString()
        }
      })
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`Failed to sync API key: ${error.message}`);
    }

    return response.json();
  }

  async removeApiKey(provider: string): Promise<ConfigPatchResponse> {
    const providerConfig = AI_PROVIDERS[provider];
    
    const response = await fetch(`${this.gatewayApiBase}/api/v1/config/patch`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${await this.getGatewayToken()}`
      },
      body: JSON.stringify({
        operation: 'remove',
        target: 'secret',
        key: providerConfig.apiKeyEnvVar
      })
    });

    return response.json();
  }
}

ステップ3.2: ゲートウェイ側のシークレット管理

クラウドゲートウェイ側では、シークレットのローテーションと安全な注入を実装します：

# gateway/src/middleware/secrets-injector.ts

import { SecretManager } from '@gateway/secrets';

export class SecretsInjector {
  private secrets: Map<string, string> = new Map();
  private secretManager: SecretManager;

  constructor() {
    this.secretManager = new SecretManager();
  }

  async loadSecrets(): Promise<void> {
    // Load all BYOK secrets from secure storage
    const userSecrets = await this.secretManager.listUserSecrets();
    
    for (const secret of userSecrets) {
      this.secrets.set(secret.key, secret.value);
    }
  }

  getSecret(key: string): string | undefined {
    return this.secrets.get(key);
  }

  // Called when AI provider is invoked
  injectProviderCredentials(provider: string): Record<string, string> {
    const envVars: Record<string, string> = {};
    
    switch (provider) {
      case 'openai':
        envVars.OPENAI_API_KEY = this.getSecret('OPENAI_API_KEY') ?? '';
        break;
      case 'anthropic':
        envVars.ANTHROPIC_API_KEY = this.getSecret('ANTHROPIC_API_KEY') ?? '';
        break;
      case 'google':
        envVars.GOOGLE_API_KEY = this.getSecret('GOOGLE_API_KEY') ?? '';
        break;
    }

    return envVars;
  }
}

フェーズ4: 設定の移行

移行前（バンドルされた認証情報を使用）

# gateway/.env (managed by OpenClaw)
AI_PROVIDER=openai
OPENAI_API_KEY=sk-org-managed-key-12345
ANTHROPIC_API_KEY=sk-ant-org-managed-key-67890

移行後（BYOKとフォールバック付き）

# gateway/.env (partial, non-sensitive)
AI_PROVIDER=openai
USE_BUNDLED_CREDENTIALS=false
BYOK_ENABLED=true

# Secrets stored separately (never committed to repo)
# Loaded from secure secret manager at runtime
# OPENAI_API_KEY=sk-user-provided-key (injected from secrets)

検証チェックリスト

BYOK実装を検証するために、以下のテストを実行してください：

テスト1: キーストレージの検証

// Unit test: Keychain storage operations
describe('KeychainStorage', () => {
  it('should store and retrieve API key', async () => {
    const testKey = 'sk-test-1234567890abcdefghijklmnop';
    await KeychainStorage.setApiKey('openai', testKey);
    const retrieved = await KeychainStorage.getApiKey('openai');
    expect(retrieved).toBe(testKey);
  });

  it('should reject invalid key format', async () => {
    const result = KeychainStorage.validateKeyFormat('openai', 'invalid-key');
    expect(result.valid).toBe(false);
    expect(result.error).toContain('Invalid key format');
  });

  it('should mask keys correctly', async () => {
    const result = KeychainStorage.validateKeyFormat(
      'openai', 
      'sk-1234567890abcdefghijklmnopqrstuvwxyz'
    );
    expect(result.maskedKey).toBe('sk-...qrst');
  });
});

テスト2: ゲートウェイ設定の同期

// Integration test: Gateway configuration sync
describe('GatewayConfigSync', () => {
  it('should sync API key to cloud gateway', async () => {
    const sync = new GatewayConfigSync('test-gateway-123');
    
    const response = await sync.syncApiKey('openai', 'sk-test-key');
    
    expect(response.success).toBe(true);
    expect(response.restartRequired).toBe(true);
    expect(response.appliedAt).toBeDefined();
  });

  it('should handle unauthorized gateway access', async () => {
    // Set up with invalid token
    const sync = new GatewayConfigSync('unauthorized-gateway');
    
    await expect(sync.syncApiKey('openai', 'sk-test'))
      .rejects.toThrow('Failed to sync API key');
  });
});

テスト3: エンドツーエンドBYOKフロー

# E2E Test Script
#!/bin/bash

GATEWAY_ID="test-e2e-gateway"
PROVIDER="openai"
TEST_KEY="sk-test-$(date +%s)"

echo "=== BYOK End-to-End Test ==="

# 1. Store key locally
echo "1. Storing key in Keychain..."
# Client-side operation (pseudocode)
client.setApiKey --provider $PROVIDER --key $TEST_KEY

# 2. Sync to gateway
echo "2. Syncing to cloud gateway..."
curl -X POST "https://${GATEWAY_ID}.gateways.openclaw.io/api/v1/config/patch" \
  -H "Authorization: Bearer $GATEWAY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operation": "set",
    "target": "secret",
    "key": "OPENAI_API_KEY",
    "value": "'"$TEST_KEY"'"
  }'

# 3. Verify gateway has key
echo "3. Verifying gateway configuration..."
RESPONSE=$(curl -s "https://${GATEWAY_ID}.gateways.openclaw.io/api/v1/config/status" \
  -H "Authorization: Bearer $GATEWAY_TOKEN")

echo $RESPONSE | jq '.secrets.OPENAI_API_KEY.configured'
# Expected: true

# 4. Test AI request uses user key
echo "4. Testing AI request with BYOK credentials..."
curl -X POST "https://${GATEWAY_ID}.gateways.openclaw.io/api/v1/chat/completions" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4", "messages": [{"role": "user", "content": "test"}]}'

# Verify X-Billing-Mode header indicates BYOK
# Expected: X-Billing-Mode: byok

echo "=== Test Complete ==="

期待されるテスト出力

セキュリティ上の落とし穴

• シークレットのログ出力: APIキーを部分的であっても決してログ出力しないでください。すべてのログStatementが機密値を編集することを確認してください。

  // ❌ Incorrect
  logger.info(`Using API key: ${apiKey}`);
  // ✅ Correct
  logger.debug(Using API key for provider: ${provider});
  

• エラーメッセージからの情報漏洩: 検証エラーはキーの構造を露呈する可能性があります。すべてのエラー応答でキーをマスキングしてください。

  // ❌ Incorrect
  throw new Error(`Invalid key: ${providedKey}`);
  // ✅ Correct
  throw new Error(Invalid key format. Key must match pattern for ${provider});
  

• メモリへの残留: メモリのAPIキーは可能な限り使用後にクリアする必要があります。セキュアな文字列パターンの使用を検討してください。

プラットフォーム固有の問題

UXの落とし穴

• 請求責任の不分明: ユーザーはAIプロバイダーから直接請求されることを理解する必要があります。請求に関する免責事項は必須です。
• キーローテーションの警告がない: APIキーを変更するとゲートウェイの再起動が必要であることをユーザーに警告してください。
• キーの有効期限処理の欠如: 一部のプロバイダー（Azureなど）にはキーの有効期限があります。プロアクティブな警告を実装してください。

設定の落とし穴

// ❌ Pitfall: Overwriting bundled credentials
// If gateway has bundled credentials AND BYOK, which takes precedence?

// ✅ Solution: Explicit priority
const getEffectiveApiKey = (provider, byokKey, bundledKey) => {
  if (byokKey) {
    return { source: 'byok', key: byokKey };
  }
  if (bundledKey) {
    return { source: 'bundled', key: bundledKey };
  }
  throw new Error('No API key configured');
};

関連する実装

• #221 - ローカルゲートウェイBYOK: セットアップウィザードを介したBYOKの既存実装。クラウドゲートウェイBYOKは、コアコンポーネントを共有しながら、クラウド固有のセキュリティ要件を処理する必要があります。
• シークレットローテーションシステム: 自動化されたAPIキーローテーションの計画中の強化（ロードマップ参照）。
• マルチプロバイダーフォールバック: 複数のプロバイダーの構成と自動フェイルオーバーを許可。

関連する設定オプション

関連するドキュメント

• BYOK機能の概要
• シークレットストレージアーキテクチャ
• OpenAIプロバイダー設定
• Anthropicプロバイダー設定
• BYOK請求FAQ

将来の考慮事項

• スコープ付きキー: プロバイダースコープキー（例：Azureエンドポイント固有のキー）のサポートと強化された検証。
• チームBYOK: 監査ログを備えたチーム共有APIキー管理のエンタープライズ機能。
• コスト見積もり: リクエスト前の使用見積もりを提供するためにプロバイダーAPIとの統合。