@foxden-app/foxclaw 0.5.63 → 0.5.64

package/.env.example

@@ -27,8 +27,19 @@ CODEX_APP_SERVER_STATE_PATH=
 CODEX_APP_SERVER_LOG_PATH=
 CODEX_APP_SYNC_ON_OPEN=true
 CODEX_APP_SYNC_ON_TURN_COMPLETE=false
-STORE_PATH=
-LOG_LEVEL=info
+# Optional OpenAI-compatible model providers for Codex app-server.
+# Keys stay in environment variables; CODEX_API_PROVIDERS only references their names.
+# Codex currently requires Responses-compatible endpoints. If your source URL is
+# /v1/chat/completions, FoxClaw normalizes the base URL for display/injection but
+# the upstream service still needs /v1/responses compatibility or a proxy shim.
+# Compact form: id|url|ENV_KEY|model|display name
+# CODEX_API_PROVIDERS=shop|https://example.com/v1|FOXCLAW_CODEX_API_KEY_SHOP|gpt-5.5|Shop Proxy
+# CODEX_API_DEFAULT_PROVIDER=shop
+# FOXCLAW_CODEX_API_KEY_SHOP=sk-...
+# JSON form:
+# CODEX_API_PROVIDERS=[{"id":"shop","baseUrl":"https://example.com/v1","apiKeyEnv":"FOXCLAW_CODEX_API_KEY_SHOP","model":"gpt-5.5","displayName":"Shop Proxy"}]
+STORE_PATH=
+LOG_LEVEL=info
 DEFAULT_CWD=/absolute/path/to/workspace
 DEFAULT_APPROVAL_POLICY=on-request
 DEFAULT_SANDBOX_MODE=workspace-write

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable FoxClaw changes are listed here. Each release note is bilingual so GitHub Releases and the npm package are useful to both Chinese and English readers.
 
+## 0.5.64 - 2026-06-29
+
+### 中文
+- 新增 OpenAI-compatible API provider 配置支持：`CODEX_API_PROVIDERS` 可声明 provider id、base URL、key 环境变量、默认模型，并在启动 Codex app-server 时注入原生 `model_providers.*` 配置。
+- 新增 `CODEX_API_DEFAULT_PROVIDER`，用于显式把 Codex 默认 `model_provider` 切到已配置的 API provider；未设置时只登记 provider，不会悄悄替换现有 ChatGPT/Codex 登录态。
+- `/config` 现在展示 API provider 摘要、默认 provider、key 环境变量是否存在，并对 `/v1/chat/completions` 来源提示 Codex 当前需要 Responses-compatible 端点；API key 不会出现在面板或 Codex 配置 override 中。
+
+### English
+- Added OpenAI-compatible API provider configuration. `CODEX_API_PROVIDERS` can declare provider id, base URL, API-key environment variable, and default model, then FoxClaw injects native Codex `model_providers.*` app-server config.
+- Added `CODEX_API_DEFAULT_PROVIDER` to explicitly switch Codex's default `model_provider` to a configured API provider. Without it, providers are registered but the existing ChatGPT/Codex auth flow is not silently replaced.
+- `/config` now shows API provider summaries, the default provider, whether each key env var is present, and warns when the source URL was `/v1/chat/completions` because current Codex requires a Responses-compatible endpoint. API keys are not printed in panels or Codex config overrides.
+
 ## 0.5.63 - 2026-06-28
 
 ### 中文

package/dist/config.d.ts

@@ -31,6 +31,8 @@ export interface AppConfig {
     codexAppServerLogPath: string;
     codexAuthDir: string | null;
     codexHome: string | null;
+    codexApiProviders: CodexApiProviderConfig[];
+    codexApiDefaultProvider: string | null;
     codexAppSyncOnOpen: boolean;
     codexAppSyncOnTurnComplete: boolean;
     storePath: string;
@@ -79,6 +81,18 @@ export interface AppConfig {
     voiceTextLimit: number;
     voiceTtsTimeoutMs: number;
 }
+export interface CodexApiProviderConfig {
+    id: string;
+    name: string;
+    baseUrl: string;
+    apiKeyEnv: string;
+    model: string | null;
+    wireApi: 'responses';
+    sourceEndpoint: string | null;
+    chatCompletionsOnly: boolean;
+}
 export declare function loadConfig(): AppConfig;
+export declare function buildCodexApiProviderOverrides(providers: readonly CodexApiProviderConfig[], defaultProviderId?: string | null): string[];
+export declare function parseCodexApiProviders(raw: string | undefined): CodexApiProviderConfig[];
 export declare function selectDefaultRuntimeBotToken(configuredTokens: string[], legacyToken: string | null): string | null;
 export declare function ensureAppDirs(config: AppConfig): void;

package/dist/config.js

@@ -68,6 +68,8 @@ export function loadConfig() {
         codexAppServerLogPath: process.env.CODEX_APP_SERVER_LOG_PATH || DEFAULT_CODEX_APP_SERVER_LOG_PATH,
         codexAuthDir: process.env.CODEX_AUTH_DIR?.trim() || null,
         codexHome: process.env.CODEX_HOME?.trim() || null,
+        codexApiProviders: parseCodexApiProviders(process.env.CODEX_API_PROVIDERS),
+        codexApiDefaultProvider: optionalSanitizedProviderId(process.env.CODEX_API_DEFAULT_PROVIDER),
         codexAppSyncOnOpen: boolEnv('CODEX_APP_SYNC_ON_OPEN', true),
         codexAppSyncOnTurnComplete: boolEnv('CODEX_APP_SYNC_ON_TURN_COMPLETE', false),
         storePath: process.env.STORE_PATH || DEFAULT_STORE_PATH,
@@ -116,6 +118,124 @@ export function loadConfig() {
     ensureAppDirs(config);
     return config;
 }
+export function buildCodexApiProviderOverrides(providers, defaultProviderId = null) {
+    const overrides = [];
+    for (const provider of providers) {
+        overrides.push(`model_providers.${provider.id}=${tomlInlineTable({
+            name: provider.name,
+            base_url: provider.baseUrl,
+            env_key: provider.apiKeyEnv,
+            wire_api: provider.wireApi,
+        })}`);
+    }
+    if (defaultProviderId) {
+        const selected = providers.find(provider => provider.id === defaultProviderId);
+        if (!selected) {
+            throw new Error(`CODEX_API_DEFAULT_PROVIDER does not match any configured provider: ${defaultProviderId}`);
+        }
+        overrides.push(`model_provider=${tomlString(selected.id)}`);
+        if (selected.model) {
+            overrides.push(`model=${tomlString(selected.model)}`);
+        }
+    }
+    return overrides;
+}
+export function parseCodexApiProviders(raw) {
+    if (!raw?.trim())
+        return [];
+    const trimmed = raw.trim();
+    if (trimmed.startsWith('[')) {
+        const parsed = JSON.parse(trimmed);
+        if (!Array.isArray(parsed)) {
+            throw new Error('CODEX_API_PROVIDERS JSON must be an array');
+        }
+        return parsed.map((entry, index) => normalizeCodexApiProvider(entry, index));
+    }
+    return trimmed
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry, index) => {
+        const parts = entry.split('|').map((part) => part.trim());
+        if (parts.length < 3 || parts.length > 5) {
+            throw new Error('CODEX_API_PROVIDERS entries must use id|url|env_key[|model][|name]');
+        }
+        const [id, url, apiKeyEnv, model, name] = parts;
+        return normalizeCodexApiProvider({ id, url, apiKeyEnv, model, displayName: name }, index);
+    });
+}
+function normalizeCodexApiProvider(entry, index) {
+    if (!entry || typeof entry !== 'object') {
+        throw new Error(`CODEX_API_PROVIDERS[${index}] must be an object`);
+    }
+    const record = entry;
+    const id = sanitizeCodexProviderId(stringField(record, ['id'], index));
+    const sourceEndpoint = optionalStringField(record, ['endpoint', 'api', 'url', 'baseUrl', 'base_url']);
+    if (!sourceEndpoint) {
+        throw new Error(`CODEX_API_PROVIDERS[${index}] is missing url/baseUrl`);
+    }
+    const normalized = normalizeOpenAiCompatibleBaseUrl(sourceEndpoint);
+    const apiKeyEnv = stringField(record, ['apiKeyEnv', 'api_key_env', 'envKey', 'env_key'], index);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(apiKeyEnv)) {
+        throw new Error(`CODEX_API_PROVIDERS[${index}] env key is not a valid environment variable name`);
+    }
+    const displayName = optionalStringField(record, ['displayName', 'display_name', 'label']) ?? id;
+    return {
+        id,
+        name: displayName,
+        baseUrl: normalized.baseUrl,
+        apiKeyEnv,
+        model: optionalStringField(record, ['model']),
+        wireApi: 'responses',
+        sourceEndpoint,
+        chatCompletionsOnly: normalized.chatCompletionsEndpoint,
+    };
+}
+function normalizeOpenAiCompatibleBaseUrl(input) {
+    const trimmed = input.trim().replace(/\/+$/, '');
+    if (!trimmed) {
+        throw new Error('CODEX_API_PROVIDERS contains an empty URL');
+    }
+    const chatSuffix = '/chat/completions';
+    if (trimmed.endsWith(chatSuffix)) {
+        return { baseUrl: trimmed.slice(0, -chatSuffix.length), chatCompletionsEndpoint: true };
+    }
+    return { baseUrl: trimmed, chatCompletionsEndpoint: false };
+}
+function stringField(record, keys, index) {
+    const value = optionalStringField(record, keys);
+    if (!value) {
+        throw new Error(`CODEX_API_PROVIDERS[${index}] is missing ${keys[0]}`);
+    }
+    return value;
+}
+function optionalStringField(record, keys) {
+    for (const key of keys) {
+        const value = record[key];
+        if (typeof value === 'string' && value.trim()) {
+            return value.trim();
+        }
+    }
+    return null;
+}
+function sanitizeCodexProviderId(value) {
+    const sanitized = value.trim().toLowerCase().replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '');
+    if (!sanitized) {
+        throw new Error('CODEX_API_PROVIDERS contains an invalid provider id');
+    }
+    return sanitized;
+}
+function optionalSanitizedProviderId(value) {
+    if (!value?.trim())
+        return null;
+    return sanitizeCodexProviderId(value);
+}
+function tomlInlineTable(values) {
+    return `{ ${Object.entries(values).map(([key, value]) => `${key} = ${tomlString(value)}`).join(', ')} }`;
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
 export function selectDefaultRuntimeBotToken(configuredTokens, legacyToken) {
     if (configuredTokens.length === 0 || !legacyToken)
         return null;

package/dist/controller/controller.js

@@ -9471,8 +9471,29 @@ function formatConfigMessage(locale, result, appConfig, authPoolStats) {
     lines.push(t(locale, 'config_panel_ttl', { value: formatDurationMs(locale, appConfig.telegramPanelTtlMs) }));
     lines.push(`TELEGRAM_PANEL_TTL_MS=${appConfig.telegramPanelTtlMs}`);
     lines.push(formatCodexAuthPoolSummary(locale, authPoolStats));
+    lines.push(...formatCodexApiProviderConfigLines(locale, appConfig));
     return lines.join('\n');
 }
+function formatCodexApiProviderConfigLines(locale, appConfig) {
+    if (appConfig.codexApiProviders.length === 0) {
+        return [t(locale, 'config_api_providers_none')];
+    }
+    const lines = [t(locale, 'config_api_providers_title')];
+    lines.push(t(locale, 'config_api_default_provider', { value: appConfig.codexApiDefaultProvider ?? '-' }));
+    for (const provider of appConfig.codexApiProviders) {
+        lines.push(t(locale, 'config_api_provider_line', {
+            id: provider.id,
+            model: provider.model ?? '-',
+            base: provider.baseUrl,
+            env: provider.apiKeyEnv,
+            key: process.env[provider.apiKeyEnv]?.trim() ? t(locale, 'yes') : t(locale, 'no'),
+        }));
+        if (provider.chatCompletionsOnly) {
+            lines.push(t(locale, 'config_api_provider_chat_warning', { id: provider.id }));
+        }
+    }
+    return lines;
+}
 function formatCodexAuthPoolSummary(locale, stats) {
     return t(locale, 'auth_pool_summary', {
         total: stats.totalSeen,

package/dist/i18n.d.ts

@@ -623,6 +623,11 @@ declare const MESSAGES: {
         readonly config_delete_tool_details_updated: "Delete operation details after final reply set to: {value}";
         readonly config_delete_tool_details_usage: "Usage: /config delete_tool_details <on|off>";
         readonly config_panel_ttl: "Interactive panel cleanup: {value}";
+        readonly config_api_providers_none: "API providers: none configured";
+        readonly config_api_providers_title: "API providers:";
+        readonly config_api_default_provider: "Default API provider: {value}";
+        readonly config_api_provider_line: "- {id}: model {model}, base {base}, key env {env} present {key}";
+        readonly config_api_provider_chat_warning: "  {id}: source was /chat/completions; Codex requires a Responses-compatible endpoint.";
         readonly config_env_update_failed: "Runtime setting changed, but updating {value} failed: {error}";
         readonly requirements_title: "Config requirements";
         readonly requirements_empty: "No config requirements are configured.";
@@ -1329,6 +1334,11 @@ declare const MESSAGES: {
         readonly config_delete_tool_details_updated: "最终回复后删除操作明细已设置为：{value}";
         readonly config_delete_tool_details_usage: "用法：/config delete_tool_details <on|off>";
         readonly config_panel_ttl: "交互面板自动清理：{value}";
+        readonly config_api_providers_none: "API Provider：未配置";
+        readonly config_api_providers_title: "API Provider：";
+        readonly config_api_default_provider: "默认 API Provider：{value}";
+        readonly config_api_provider_line: "- {id}：模型 {model}，base {base}，key 环境变量 {env} 存在 {key}";
+        readonly config_api_provider_chat_warning: "  {id}：来源是 /chat/completions；Codex 需要兼容 Responses 的端点。";
         readonly config_env_update_failed: "运行时设置已改变，但更新 {value} 失败：{error}";
         readonly requirements_title: "配置要求";
         readonly requirements_empty: "当前没有配置要求。";

package/dist/i18n.js

@@ -621,6 +621,11 @@ const MESSAGES = {
         config_delete_tool_details_updated: 'Delete operation details after final reply set to: {value}',
         config_delete_tool_details_usage: 'Usage: /config delete_tool_details <on|off>',
         config_panel_ttl: 'Interactive panel cleanup: {value}',
+        config_api_providers_none: 'API providers: none configured',
+        config_api_providers_title: 'API providers:',
+        config_api_default_provider: 'Default API provider: {value}',
+        config_api_provider_line: '- {id}: model {model}, base {base}, key env {env} present {key}',
+        config_api_provider_chat_warning: '  {id}: source was /chat/completions; Codex requires a Responses-compatible endpoint.',
         config_env_update_failed: 'Runtime setting changed, but updating {value} failed: {error}',
         requirements_title: 'Config requirements',
         requirements_empty: 'No config requirements are configured.',
@@ -1327,6 +1332,11 @@ const MESSAGES = {
         config_delete_tool_details_updated: '最终回复后删除操作明细已设置为：{value}',
         config_delete_tool_details_usage: '用法：/config delete_tool_details <on|off>',
         config_panel_ttl: '交互面板自动清理：{value}',
+        config_api_providers_none: 'API Provider：未配置',
+        config_api_providers_title: 'API Provider：',
+        config_api_default_provider: '默认 API Provider：{value}',
+        config_api_provider_line: '- {id}：模型 {model}，base {base}，key 环境变量 {env} 存在 {key}',
+        config_api_provider_chat_warning: '  {id}：来源是 /chat/completions；Codex 需要兼容 Responses 的端点。',
         config_env_update_failed: '运行时设置已改变，但更新 {value} 失败：{error}',
         requirements_title: '配置要求',
         requirements_empty: '当前没有配置要求。',

package/dist/main.js

@@ -7,7 +7,7 @@ import process from 'node:process';
 import { createInterface } from 'node:readline/promises';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
-import { APP_HOME, DEFAULT_CODEX_TELEGRAM_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, getLoadedEnvPath, loadConfig, loadEnv, } from './config.js';
+import { APP_HOME, buildCodexApiProviderOverrides, DEFAULT_CODEX_TELEGRAM_HOME, DEFAULT_ENV_PATH, DEFAULT_LOG_PATH, DEFAULT_STATUS_PATH, getLoadedEnvPath, loadConfig, loadEnv, } from './config.js';
 import { createAuthRefreshNotificationAggregator, } from './auth/notifications.js';
 import { installBundledCodexSkills } from './codex_skills.js';
 import { acquireProcessLock, LockHeldError } from './lock.js';
@@ -448,6 +448,7 @@ async function runServeCli() {
     ]);
     const config = loadConfig();
     const logger = new Logger(config.logLevel, config.logPath);
+    const codexApiProviderOverrides = buildCodexApiProviderOverrides(config.codexApiProviders, config.codexApiDefaultProvider);
     const authNotificationAggregator = createAuthRefreshNotificationAggregator(logger);
     attachIlinkRuntimeFromBridgeLogger(logger, config.wxIlinkRouteTag);
     const processLock = acquireProcessLock(config.lockPath);
@@ -496,7 +497,10 @@ async function runServeCli() {
                 const childEnv = sharedDefaultRuntime
                     ? (config.codexHome ? { CODEX_HOME: config.codexHome } : null)
                     : { CODEX_HOME: home };
-                const app = new CodexAppClient(runtimeConfig.codexCliBin, runtimeConfig.codexAppLaunchCmd, runtimeConfig.codexAppAutolaunch, runtimeConfig.codexAppServerStatePath, runtimeConfig.codexAppServerLogPath, logger, childEnv, sharedDefaultRuntime ? [] : ['cli_auth_credentials_store="file"']);
+                const app = new CodexAppClient(runtimeConfig.codexCliBin, runtimeConfig.codexAppLaunchCmd, runtimeConfig.codexAppAutolaunch, runtimeConfig.codexAppServerStatePath, runtimeConfig.codexAppServerLogPath, logger, childEnv, [
+                    ...codexApiProviderOverrides,
+                    ...(sharedDefaultRuntime ? [] : ['cli_auth_credentials_store="file"']),
+                ]);
                 seeds.push({ id, home, authDir, sharedDefaultRuntime, config: runtimeConfig, bot, app });
             }
             let authSync = null;
@@ -670,7 +674,7 @@ async function runServeCli() {
                 runtimes.push({ ...seed, core, telegram: new TelegramChannelAdapter(core) });
             }
             if (config.wxEnabled) {
-                const weixinApp = new CodexAppClient(config.codexCliBin, config.codexAppLaunchCmd, config.codexAppAutolaunch, config.codexAppServerStatePath, config.codexAppServerLogPath, logger);
+                const weixinApp = new CodexAppClient(config.codexCliBin, config.codexAppLaunchCmd, config.codexAppAutolaunch, config.codexAppServerStatePath, config.codexAppServerLogPath, logger, null, codexApiProviderOverrides);
                 const outbound = new BridgeMessagingRouter(new TelegramMessagingPort(seeds[0].bot), new WeixinMessagingPort(store, (id) => loadWeixinAccount(config.weixinAccountsDir, id)));
                 activeWeixinCore = new BridgeSessionCore(config, store, logger, seeds[0].bot, weixinApp, outbound, selfUpdater, coordinator, false);
                 managedApps.push(weixinApp);
@@ -764,7 +768,7 @@ async function runServeCli() {
         const singleCodexHome = config.codexHome ?? path.join(os.homedir(), '.codex');
         installBundledCodexSkills(packageRoot, singleCodexHome);
         const bot = new TelegramGateway(config.tgBotToken, config.tgAllowedUserId, config.tgAllowedChatId, config.telegramPollIntervalMs, store, logger);
-        const app = new CodexAppClient(config.codexCliBin, config.codexAppLaunchCmd, config.codexAppAutolaunch, config.codexAppServerStatePath, config.codexAppServerLogPath, logger);
+        const app = new CodexAppClient(config.codexCliBin, config.codexAppLaunchCmd, config.codexAppAutolaunch, config.codexAppServerStatePath, config.codexAppServerLogPath, logger, config.codexHome ? { CODEX_HOME: config.codexHome } : null, codexApiProviderOverrides);
         const telegramMessaging = new TelegramMessagingPort(bot);
         const weixinMessaging = config.wxEnabled
             ? new WeixinMessagingPort(store, (id) => loadWeixinAccount(config.weixinAccountsDir, id))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foxden-app/foxclaw",
-  "version": "0.5.63",
+  "version": "0.5.64",
   "description": "Foxden local execution claw for controlling Codex from trusted chat interfaces.",
   "type": "module",
   "main": "dist/main.js",