feat(config): add proxy configuration types and schema

- add ProxyRemoteConfig, ProxyFallbackConfig, ProxyLocalConfig interfaces

- add ProxyConfig composite type with remote/fallback/local sections

- add ResolvedProxyConfig interface for runtime config

- bump UNIFIED_CONFIG_VERSION to 5

- add DEFAULT_PROXY_CONFIG constant

src/cliproxy/types.ts

@@ -187,3 +187,28 @@ export interface ProviderConfig {
   /** Whether OAuth is required */
   requiresOAuth: boolean;
 }
+
+/**
+ * Resolved proxy configuration after merging CLI > ENV > config.yaml > defaults.
+ * Used by executor to determine local vs remote proxy mode.
+ */
+export interface ResolvedProxyConfig {
+  /** Proxy mode: 'local' spawns CLIProxyAPI locally, 'remote' connects to external server */
+  mode: 'local' | 'remote';
+  /** Remote proxy hostname/IP (only for remote mode) */
+  host?: string;
+  /** Proxy port (default: 8317) */
+  port: number;
+  /** Protocol for remote connection (default: http) */
+  protocol: 'http' | 'https';
+  /** Auth token for remote proxy authentication */
+  authToken?: string;
+  /** Enable fallback to local when remote unreachable (default: true) */
+  fallbackEnabled: boolean;
+  /** Auto-start local proxy if not running (default: true) */
+  autoStartLocal: boolean;
+  /** --remote-only flag: fail if remote unreachable, no fallback */
+  remoteOnly: boolean;
+  /** --local-proxy flag: force local mode, ignore remote config */
+  forceLocal: boolean;
+}

src/config/unified-config-types.ts

@@ -14,8 +14,9 @@
  * Version 2 = YAML unified format
  * Version 3 = WebSearch config with model configuration for Gemini/OpenCode
  * Version 4 = Copilot API integration (GitHub Copilot proxy)
+ * Version 5 = Remote proxy configuration (connect to remote CLIProxyAPI)
  */
-export const UNIFIED_CONFIG_VERSION = 4;
+export const UNIFIED_CONFIG_VERSION = 5;
 
 /**
  * Account configuration (formerly in profiles.json).
@@ -185,6 +186,56 @@ export interface CopilotConfig {
   haiku_model?: string;
 }
 
+/**
+ * Remote proxy configuration.
+ * Connect to a remote CLIProxyAPI instance instead of spawning local binary.
+ */
+export interface ProxyRemoteConfig {
+  /** Enable remote proxy mode (default: false = local mode) */
+  enabled: boolean;
+  /** Remote proxy hostname or IP (empty = not configured) */
+  host: string;
+  /** Remote proxy port (default: 8317) */
+  port: number;
+  /** Protocol for remote connection */
+  protocol: 'http' | 'https';
+  /** Auth token for remote proxy (optional, sent as header) */
+  auth_token: string;
+}
+
+/**
+ * Fallback configuration when remote proxy is unreachable.
+ */
+export interface ProxyFallbackConfig {
+  /** Enable fallback to local proxy (default: true) */
+  enabled: boolean;
+  /** Auto-start local proxy without prompting (default: false = prompt user) */
+  auto_start: boolean;
+}
+
+/**
+ * Local proxy configuration.
+ */
+export interface ProxyLocalConfig {
+  /** Local proxy port (default: 8317) */
+  port: number;
+  /** Auto-start local binary (default: true) */
+  auto_start: boolean;
+}
+
+/**
+ * Proxy configuration section.
+ * Controls whether CCS uses local or remote CLIProxyAPI instance.
+ */
+export interface ProxyConfig {
+  /** Remote proxy settings */
+  remote: ProxyRemoteConfig;
+  /** Fallback behavior when remote is unreachable */
+  fallback: ProxyFallbackConfig;
+  /** Local proxy settings */
+  local: ProxyLocalConfig;
+}
+
 /**
  * Global environment variables configuration.
  * These env vars are injected into ALL non-Claude subscription profiles.
@@ -242,7 +293,7 @@ export interface WebSearchConfig {
  * Stored in ~/.ccs/config.yaml
  */
 export interface UnifiedConfig {
-  /** Config version (4 for copilot support) */
+  /** Config version (5 for remote proxy support) */
   version: number;
   /** Default profile name to use when none specified */
   default?: string;
@@ -260,6 +311,8 @@ export interface UnifiedConfig {
   global_env?: GlobalEnvConfig;
   /** Copilot API configuration (GitHub Copilot proxy) */
   copilot?: CopilotConfig;
+  /** Proxy configuration for remote/local CLIProxyAPI */
+  proxy?: ProxyConfig;
 }
 
 /**
@@ -289,6 +342,28 @@ export const DEFAULT_COPILOT_CONFIG: CopilotConfig = {
   model: 'gpt-4.1', // Free tier compatible
 };
 
+/**
+ * Default proxy configuration.
+ * Local mode by default - remote must be explicitly enabled.
+ */
+export const DEFAULT_PROXY_CONFIG: ProxyConfig = {
+  remote: {
+    enabled: false,
+    host: '',
+    port: 8317,
+    protocol: 'http',
+    auth_token: '',
+  },
+  fallback: {
+    enabled: true,
+    auto_start: false,
+  },
+  local: {
+    port: 8317,
+    auto_start: true,
+  },
+};
+
 /**
  * Create an empty unified config with defaults.
  */
@@ -336,6 +411,7 @@ export function createEmptyUnifiedConfig(): UnifiedConfig {
       env: { ...DEFAULT_GLOBAL_ENV },
     },
     copilot: { ...DEFAULT_COPILOT_CONFIG },
+    proxy: { ...DEFAULT_PROXY_CONFIG },
   };
 }