@kkmila/cpc 1.0.4 → 1.0.5

package/README.md

@@ -58,6 +58,29 @@ cpc add
 cpc install openai --agent pi
 ```
 
+### 安装到 Codex Agent（全局默认 provider）
+
+Codex 一次只能使用一个模型（写入 `~/.codex/config.toml` 顶层的 `model` + `model_provider`）。
+`cpc install` 会把 API key 跨平台落地到一个环境变量，并在 `[model_providers.<name>]` 段用 `env_key` 引用它，
+装完直接 `codex` 即走该 provider，无需 `--profile`。
+
+```bash
+# 非交互：直接指定单模型 + wire_api
+cpc install tele_home --agent codex --model qwen3.6-plus --wire-api responses
+
+# 交互：多模型时会弹单选让你挑一个作为默认
+# 并询问 wire_api（responses = Codex Responses 原生协议；chat_completions = 标准 OpenAI 兼容）
+cpc install tele_home --agent codex
+```
+
+可选 `--reasoning-effort minimal|low|medium|high` 一并写入 `model_reasoning_effort`。
+
+行为说明：
+- 原始 `config.toml` 会先备份为 `config.toml.cpc.bak`。
+- 只 upsert 顶层 `model_provider` / `model`（及可选 `model_reasoning_effort`）和 `[model_providers.<name>]` 段内字段，
+  不会误伤 `model_personality` 等同前缀 key，也不会破坏 `[features]` / `[mcp_servers.*]` / `[desktop]` 等段。
+- `cpc list-installed --agent codex` 可查看当前 provider、model、wire_api、env_key。
+
 ### 测试连接
 
 ```bash
@@ -76,6 +99,17 @@ cpc test openai
 - cursor
 - opencode
 
+### Codex 的特殊性
+
+- 一次只能用一个模型：`cpc install --agent codex` 会把选中的模型设为全局默认，
+  多模型时强制让用户挑一个；不像 pi/openclaw 能一次装多个。
+- provider 的 API key 通过 **环境变量** 引用（`env_key`），cpc 跨平台落地：
+  - Linux / macOS：按 `$SHELL` 写入 `~/.zshrc` 或 `~/.bashrc`（幂等，已存在则替换值）
+  - Windows：用 `setx` 写入用户环境变量
+  - 环境变量名规范为 `CPC_<NAME>_API_KEY`（大写、非字母数字转 `_`）
+- 装完新开终端自动加载；当前终端需 `source ~/.bashrc`（或对应 rc 文件）。
+  `cpc install` 输出会明确提示该路径。
+
 ## 配置文件
 
 - `~/.config/cpc/providers.json` - 提供商配置

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkmila/cpc",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Custom Provider CLI for managing model providers",
   "type": "module",
   "bin": {

package/registry.yaml

@@ -20,6 +20,7 @@ agents:
   codex:
     name: Codex
     home: ~/.codex
+    home_env: CODEX_HOME
     description: "OpenAI Codex agent"
 
   openclaw:

package/src/commands/provider.mjs

@@ -4,8 +4,10 @@ import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
 import { resolve, join } from "node:path";
 import { homedir } from "node:os";
 import yaml from "js-yaml";
-import { loadRegistry, getAgents, resolveAgentPaths } from "../lib/agents.mjs";
+import { loadRegistry, getAgents, resolveAgentPaths, detectCurrentAgent } from "../lib/agents.mjs";
 import { enrichModelWithBaseline } from "../lib/baseline-models.mjs";
+import { persistEnvVar, envKeyNameForProvider } from "../lib/env.mjs";
+import { writeCodexProviderConfig, readCodexProviderInfo } from "../lib/codex-toml.mjs";
 
 /**
  * Get the config directory path (~/.config/cpc)
@@ -121,10 +123,10 @@ const MODEL_DEFAULTS = {
 	"gpt-4o": { contextWindow: 128000, maxTokens: 16384, reasoning: false },
 	"gpt-4o-mini": { contextWindow: 128000, maxTokens: 16384, reasoning: false },
 	"gpt-3.5-turbo": { contextWindow: 16385, maxTokens: 4096, reasoning: false },
-	o1: { contextWindow: 200000, maxTokens: 100000, reasoning: true },
-	"o1-mini": { contextWindow: 128000, maxTokens: 65536, reasoning: true },
-	"o1-preview": { contextWindow: 128000, maxTokens: 32768, reasoning: true },
-	"o3-mini": { contextWindow: 200000, maxTokens: 100000, reasoning: true },
+	o1: { contextWindow: 200000, maxTokens: 100000, reasoning: false },
+	"o1-mini": { contextWindow: 128000, maxTokens: 65536, reasoning: false },
+	"o1-preview": { contextWindow: 128000, maxTokens: 32768, reasoning: false },
+	"o3-mini": { contextWindow: 200000, maxTokens: 100000, reasoning: false },
 
 	// Anthropic
 	"claude-3-opus-20240229": {
@@ -159,7 +161,7 @@ const MODEL_DEFAULTS = {
 	"deepseek-reasoner": {
 		contextWindow: 65536,
 		maxTokens: 8192,
-		reasoning: true,
+		reasoning: false,
 	},
 
 	// Qwen
@@ -167,6 +169,10 @@ const MODEL_DEFAULTS = {
 	"qwen-plus": { contextWindow: 32768, maxTokens: 8192, reasoning: false },
 	"qwen-max": { contextWindow: 32768, maxTokens: 8192, reasoning: false },
 
+	// 智谱 GLM-5.2
+	"glm-5.2": { contextWindow: 1000000, maxTokens: 131072, reasoning: false },
+	"glm-5.2-anthropic": { contextWindow: 1000000, maxTokens: 131072, reasoning: false },
+
 	// 通用默认值
 	default: { contextWindow: 32768, maxTokens: 4096, reasoning: false },
 };
@@ -188,16 +194,9 @@ function getModelDefaults(modelId) {
 		}
 	}
 
-	// 检测是否是推理模型
-	const isReasoning =
-		lowerId.includes("reason") ||
-		lowerId.includes("o1") ||
-		lowerId.includes("o3") ||
-		lowerId.includes("think");
-
 	return {
 		...MODEL_DEFAULTS["default"],
-		reasoning: isReasoning,
+		reasoning: false,
 	};
 }
 
@@ -323,24 +322,26 @@ function getAgentProviderConfig(agentId, provider) {
 				},
 			};
 
-		case "codex":
+		case "codex": {
+			// codex 一次只能用一个模型（顶层 model + model_provider）。
+			// provider 段用 env_key 引用环境变量，key 本身由 cpc 跨平台落地。
+			const envKey = envKeyNameForProvider(provider.name);
 			return {
-				configToml: {
-					model_provider: provider.name,
+				codex: {
+					providerName: provider.name,
+					baseUrl: provider.baseUrl,
+					wireApi:
+						provider.api === "anthropic-messages"
+							? "chat_completions"
+							: provider.api === "openai-completions"
+								? "chat_completions"
+								: "responses",
+					envKey,
 					model: provider.models[0]?.id || "default",
-					model_providers: {
-						[provider.name]: {
-							name: provider.name,
-							base_url: provider.baseUrl,
-							wire_api:
-								provider.api === "anthropic-messages"
-									? "chat_completions"
-									: "responses",
-							requires_openai_auth: false,
-						},
-					},
+					apiKey: provider.apiKey,
 				},
 			};
+		}
 
 		case "openclaw":
 			return {
@@ -417,7 +418,7 @@ function getAgentProviderConfig(agentId, provider) {
 /**
  * Install provider configuration to agent
  */
-function installProviderToAgent(agentId, provider, agentHome) {
+function installProviderToAgent(agentId, provider, agentHome, opts = {}) {
 	const config = getAgentProviderConfig(agentId, provider);
 	if (!config) {
 		console.log(chalk.yellow(`  ⚠ 未知 agent: ${agentId}`));
@@ -442,7 +443,13 @@ function installProviderToAgent(agentId, provider, agentHome) {
 				const modelsPath = join(agentHome, "models.json");
 				let models = { providers: {} };
 				if (existsSync(modelsPath)) {
-					models = JSON.parse(readFileSync(modelsPath, "utf8"));
+					try {
+						const content = readFileSync(modelsPath, "utf8").trim();
+						if (content) models = JSON.parse(content);
+					} catch {
+						// 空文件或损坏的 JSON，重置为默认值
+						models = { providers: {} };
+					}
 				}
 				models.providers = {
 					...models.providers,
@@ -467,38 +474,55 @@ function installProviderToAgent(agentId, provider, agentHome) {
 
 			case "codex": {
 				const configPath = join(agentHome, "config.toml");
-				let configContent = "";
-				if (existsSync(configPath)) {
-					configContent = readFileSync(configPath, "utf8");
-				}
-
-				const providerSection = `\n[model_providers.${provider.name}]\nname = "${provider.name}"\nbase_url = "${provider.baseUrl}"\nwire_api = "${provider.api === "anthropic-messages" ? "chat_completions" : "responses"}"\nrequires_openai_auth = false\n`;
-
-				const modelLine = `model_provider = "${provider.name}"\n`;
-				const modelIdLine = `model = "${provider.models[0]?.id || "default"}"\n`;
+				const c = config.codex;
 
-				if (configContent.includes("model_provider =")) {
-					configContent = configContent.replace(
-						/model_provider = .*\n/,
-						modelLine,
+				// 1) 跨平台落地 API key 到环境变量
+				let envResult;
+				try {
+					envResult = persistEnvVar(c.envKey, c.apiKey);
+				} catch (err) {
+					console.error(
+						chalk.red(`  ✗ 落地环境变量 ${c.envKey} 失败: ${err.message}`),
 					);
-				} else {
-					configContent = modelLine + configContent;
+					return false;
 				}
 
-				if (configContent.includes("model =")) {
-					configContent = configContent.replace(/model = .*\n/, modelIdLine);
-				} else {
-					configContent = modelIdLine + configContent;
-				}
-
-				if (!configContent.includes(`[model_providers.${provider.name}]`)) {
-					configContent += providerSection;
+				// 2) 稳健写入 config.toml（顶层 + provider 段，备份原文件）
+				try {
+					const { backed } = writeCodexProviderConfig(configPath, {
+						providerName: c.providerName,
+						baseUrl: c.baseUrl,
+						wireApi: opts.wireApi || c.wireApi,
+						envKey: c.envKey,
+						model: c.model,
+						modelReasoningEffort: opts.modelReasoningEffort,
+					});
+					console.log(chalk.green(`  ✓ 更新 Codex config.toml`));
+					if (backed) {
+						console.log(chalk.dim(`  • 备份: ${backed}`));
+					}
+					console.log(
+						chalk.dim(
+							`  • env_key=$${c.envKey}  (${envResult.method}${envResult.target ? ": " + envResult.target : ""}${envResult.created ? ", 新增" : ", 已存在"})`,
+						),
+					);
+					if (process.platform !== "win32") {
+						console.log(
+							chalk.dim(
+								`  • 新终端自动加载; 当前终端需执行: source ${envResult.target}`,
+							),
+						);
+					}
+					console.log(
+						chalk.dim(`  • 启动: codex  (全局默认即 ${c.providerName}/${c.model})`),
+					);
+					return true;
+				} catch (err) {
+					console.error(
+						chalk.red(`  ✗ 更新 ${agentId} 失败: ${err.message}`),
+					);
+					return false;
 				}
-
-				writeFileSync(configPath, configContent);
-				console.log(chalk.green(`  ✓ 更新 Codex config.toml`));
-				return true;
 			}
 
 			case "openclaw": {
@@ -563,15 +587,9 @@ function installProviderToAgent(agentId, provider, agentHome) {
  * Check if an agent is installed by looking at its home directory
  */
 function isAgentInstalled(agentId, agents) {
-	const agent = agents[agentId];
+	const agent = resolveAgentPaths(agents[agentId]);
 	if (!agent || !agent.home) return false;
-
-	// Expand ~ to home directory
-	const home = agent.home.replace(
-		/^~/,
-		process.env.HOME || process.env.USERPROFILE,
-	);
-	return existsSync(home);
+	return existsSync(agent.home);
 }
 
 export function registerProvider(program, repoRoot) {
@@ -1076,6 +1094,192 @@ export function registerProvider(program, repoRoot) {
 			);
 		});
 
+	// ── cpc update ───────────────────────────────────────────────
+	program
+		.command("update [providerName]")
+		.description("重新从 API 拉取模型并更新 providers.json + 已安装的 agent")
+		.option("--all", "选择全部模型")
+		.option("--agent <agent>", "指定目标 agent")
+		.action(async (providerName, opts) => {
+			const providersData = loadProviders();
+			const providers = Object.entries(providersData.providers);
+
+			if (providers.length === 0) {
+				console.log(chalk.yellow("No providers configured."));
+				console.log(chalk.dim("Use `cpc add` to add a new provider first."));
+				return;
+			}
+
+			// Step 1: 选择 provider
+			if (!providerName) {
+				providerName = await select({
+					message: "Select provider to update:",
+					choices: providers.map(([name, config]) => ({
+						name: `${name.padEnd(20)} (${config.models?.length || 0} models)`,
+						value: name,
+					})),
+				});
+			}
+
+			const provider = providersData.providers[providerName];
+			if (!provider) {
+				console.error(chalk.red(`Provider "${providerName}" not found.`));
+				process.exit(1);
+			}
+
+			// Step 2: 从 API 拉取模型
+			console.log(chalk.dim(`\nFetching models from ${provider.baseUrl}...`));
+			const result = await fetchModelsFromAPI(provider.baseUrl, provider.apiKey, provider.api);
+
+			if (!result.success) {
+				console.log(chalk.red(`✗ Failed to fetch models: ${result.error}`));
+				return;
+			}
+
+			console.log(chalk.green(`✓ Found ${result.models.length} models from API`));
+
+			// Step 3: 选择模型
+			const oldIds = (provider.models || []).map((m) => m.id);
+			const newIds = result.models.map((m) => m.id);
+
+			// 报告新增和移除的模型
+			const addedIds = newIds.filter((id) => !oldIds.includes(id));
+			const removedIds = oldIds.filter((id) => !newIds.includes(id));
+			const keptIds = oldIds.filter((id) => newIds.includes(id));
+
+			if (addedIds.length > 0) {
+				console.log(chalk.cyan(`  + ${addedIds.length} new model(s): ${addedIds.join(", ")}`));
+			}
+			if (removedIds.length > 0) {
+				console.log(chalk.yellow(`  - ${removedIds.length} removed model(s): ${removedIds.join(", ")}`));
+			}
+			if (keptIds.length > 0) {
+				console.log(chalk.dim(`  = ${keptIds.length} kept model(s): ${keptIds.join(", ")}`));
+			}
+
+			// 让用户选择要安装的模型
+			let selectedIds;
+			if (opts.all) {
+				selectedIds = result.models.map((m) => m.id);
+				console.log(chalk.dim(`Auto-selected all ${selectedIds.length} models`));
+			} else {
+				selectedIds = await checkbox({
+					message: "Select models to install:",
+					choices: result.models.map((m) => {
+						const isNew = !oldIds.includes(m.id);
+						return {
+							name: `${isNew ? chalk.cyan("+ ") : chalk.dim("  ")}${m.id.padEnd(40)} ctx:${m.contextWindow || "?"}`,
+							value: m.id,
+							checked: true,
+						};
+					}),
+					instructions: {
+						navigator: "↑↓ navigate",
+						select: "space select",
+						all: "a toggle all",
+						},
+				});
+			}
+
+			if (selectedIds.length === 0) {
+				console.log(chalk.yellow("No models selected. Cancelled."));
+				return;
+			}
+
+			// Step 4: 用 baseline + MODEL_DEFAULTS 补全模型属性
+			const updatedModels = [];
+			for (const modelId of selectedIds) {
+				const apiModel = result.models.find((m) => m.id === modelId);
+				const defaults = getModelDefaults(modelId);
+				const configured = enrichModelWithBaseline({
+					id: modelId,
+					name: apiModel?.name || modelId,
+					contextWindow: apiModel?.contextWindow || defaults.contextWindow,
+					maxTokens: apiModel?.maxTokens || defaults.maxTokens,
+					reasoning: false,
+					input: apiModel?.input || defaults.input || ["text"],
+				});
+				if (configured.description) {
+					console.log(chalk.dim(`  ↪ ${modelId}: baseline 命中, contextWindow=${configured.contextWindow}, input=[${configured.input.join(",")}]`));
+				}
+				updatedModels.push(configured);
+			}
+
+			// Step 5: 更新 providers.json
+			provider.models = updatedModels;
+			provider.updatedAt = new Date().toISOString();
+			saveProviders(providersData);
+			console.log(chalk.green(`\n✓ Provider "${providerName}" updated: ${updatedModels.length} model(s)`));
+
+			// Step 6: 更新已安装的 agent
+			const registry = loadRegistry(repoRoot);
+			const agents = getAgents(registry);
+			const resolvedAgents = Object.fromEntries(
+				Object.entries(agents).map(([id, a]) => [id, resolveAgentPaths(a)]),
+			);
+			const installProvider = { ...provider, models: updatedModels };
+
+			// 找出哪些 agent 之前安装过这个 provider
+			let agentIds;
+			if (opts.agent) {
+				agentIds = opts.agent === "all" ? Object.keys(agents) : [opts.agent];
+			} else {
+				// 只显示 pi 和 opencode，默认不勾选
+				const visibleAgentIds = Object.keys(resolvedAgents)
+					.filter((id) => id === "pi" || id === "opencode");
+
+				if (visibleAgentIds.length === 0) {
+					console.log(chalk.dim("\nNo pi or opencode agents found. Skipping agent update."));
+					return;
+				}
+
+				agentIds = await checkbox({
+					message: "Select target agents to update:",
+					choices: visibleAgentIds.map((id) => {
+						const a = resolvedAgents[id];
+						const installed = isAgentInstalled(id, resolvedAgents);
+						const mark = installed ? " (installed)" : "";
+						return {
+							name: `${id.padEnd(14)} ${a.description || ""}${mark}`,
+							value: id,
+							checked: false,
+						};
+					}),
+					instructions: {
+						navigator: "↑↓ navigate",
+						select: "space select",
+						all: "a toggle all",
+						},
+				});
+			}
+
+			if (agentIds.length === 0) {
+				console.log(chalk.yellow("No agents selected. Skipping agent update."));
+				return;
+			}
+
+			console.log();
+			let successCount = 0;
+			for (const aid of agentIds) {
+				const agent = resolvedAgents[aid];
+				if (!agent) {
+					console.log(chalk.red(`Unknown agent: ${aid}`));
+					continue;
+				}
+				console.log(chalk.bold(`→ ${aid}`));
+				console.log(chalk.dim(`  ${updatedModels.length} model(s)`));
+				const success = installProviderToAgent(aid, installProvider, agent.home);
+				if (success) successCount++;
+				console.log();
+			}
+
+			if (successCount > 0) {
+				console.log(chalk.green.bold(`✓ Provider updated in ${successCount} agent(s)!`));
+				} else {
+				console.log(chalk.yellow("No agents were updated."));
+				}
+			});
+
 	// ── cpc remove ───────────────────────────────────────────────
 	program
 		.command("remove [name]")
@@ -1128,6 +1332,8 @@ export function registerProvider(program, repoRoot) {
 		.option("--model <model>", "Install only specific model")
 		.option("--all", "Install all models")
 		.option("--first", "Install only first model")
+		.option("--wire-api <api>", "Codex wire_api (responses | chat_completions)")
+		.option("--reasoning-effort <level>", "Codex model_reasoning_effort (minimal|low|medium|high)")
 		.action(async (providerName, opts) => {
 			const registry = loadRegistry(repoRoot);
 			const agents = getAgents(registry);
@@ -1209,16 +1415,20 @@ export function registerProvider(program, repoRoot) {
 			if (opts.agent) {
 				agentIds = opts.agent === "all" ? Object.keys(agents) : [opts.agent];
 			} else {
-				// Auto-detect installed agents
+				// Auto-detect: 只显示 pi 和 opencode，默认不勾选
+				const visibleAgentIds = Object.keys(agents)
+					.filter((id) => id === "pi" || id === "opencode");
+				const currentAgent = detectCurrentAgent(agents);
 				const selected = await checkbox({
-					message: "Select target agents (installed agents are pre-selected):",
+					message: "Select target agents:",
 					choices: [
-						...Object.entries(agents).map(([id, a]) => {
-							const installed = isAgentInstalled(id, agents);
+						...visibleAgentIds.map((id) => {
+							const a = agents[id];
+							const mark = id === currentAgent ? " ← current" : "";
 							return {
-								name: `${id.padEnd(14)} ${a.description || ""}${installed ? " ✓" : ""}`,
+								name: `${id.padEnd(14)} ${a.description || ""}${mark}`,
 								value: id,
-								checked: installed,
+								checked: false,
 							};
 						}),
 					],
@@ -1241,21 +1451,92 @@ export function registerProvider(program, repoRoot) {
 			console.log();
 			let successCount = 0;
 
+			// codex 特殊处理：全局只能用一个 model，需确定 wire_api（协议）。
+			// 如果目标含 codex 且选了多个模型，先让用户挑一个作为默认。
+			const hasCodex = agentIds.includes("codex");
+			let codexDefaultModel = null;
+			let codexWireApi = opts.wireApi || null;
+			let codexReasoningEffort = opts.reasoningEffort || null;
+			if (hasCodex) {
+				let codexModels = installProvider.models;
+				if (codexModels.length > 1) {
+					console.log(
+						chalk.yellow(
+							`⚠ codex 一次只能用一个模型（顶层 model），多模型时仅生效默认这一个`,
+						),
+					);
+					const picked = await select({
+						message: "选择 codex 的默认 model:",
+						choices: codexModels.map((m) => ({
+							name: `${m.id}${m.description ? " — " + m.description : ""}`,
+							value: m.id,
+						})),
+					});
+					codexDefaultModel = picked;
+				} else {
+					codexDefaultModel = codexModels[0]?.id;
+				}
+				// wire_api 选择（未传 --wire-api 时交互确认）
+				if (!codexWireApi) {
+					const inferred =
+						installProvider.api === "responses"
+							? "responses"
+							: installProvider.api === "anthropic-messages"
+								? "chat_completions"
+								: "chat_completions";
+					codexWireApi = await select({
+						message: `codex wire_api（与 ${installProvider.name} 通信协议）:`,
+						choices: [
+							{
+								name: `responses  — Codex Responses 原生协议（CCX 网关用这个）${inferred === "responses" ? "  [推断]" : ""}`,
+								value: "responses",
+							},
+							{
+								name: `chat_completions  — 标准 OpenAI 兼容协议（多数网关用这个）${inferred === "chat_completions" ? "  [推断]" : ""}`,
+								value: "chat_completions",
+							},
+						],
+					});
+				}
+			}
+
 			for (const aid of agentIds) {
 				const agentDef = agents[aid];
 				if (!agentDef) {
 					console.log(chalk.red(`Unknown agent: ${aid}`));
 					continue;
-				}
+			}
 
 				const agent = resolveAgentPaths(agentDef);
 				console.log(chalk.bold(`→ ${aid}`));
-				console.log(chalk.dim(`  ${installProvider.models.length} model(s)`));
+
+				let targetProvider = installProvider;
+				let targetOpts = {};
+				if (aid === "codex") {
+					const picked =
+						installProvider.models.find(
+							(m) => m.id === codexDefaultModel,
+						) || installProvider.models[0];
+					targetProvider = { ...installProvider, models: [picked] };
+					targetOpts = {
+						wireApi: codexWireApi,
+						modelReasoningEffort: codexReasoningEffort,
+					};
+					console.log(
+						chalk.dim(`  model: ${picked.id}  (codex 全局默认, 单模型)`),
+					);
+					console.log(chalk.dim(`  wire_api: ${codexWireApi}`));
+				} else {
+					console.log(
+						chalk.dim(`  ${targetProvider.models.length} model(s)`),
+					);
+				}
 
 				const success = installProviderToAgent(
 					aid,
-					installProvider,
+					targetProvider,
 					agent.home,
+					targetOpts,
 				);
 				if (success) successCount++;
 				console.log();
@@ -1529,7 +1810,13 @@ export function registerProvider(program, repoRoot) {
 						case "pi": {
 							const modelsPath = join(agent.home, "models.json");
 							if (existsSync(modelsPath)) {
-								const models = JSON.parse(readFileSync(modelsPath, "utf8"));
+								let models = { providers: {} };
+								try {
+									const content = readFileSync(modelsPath, "utf8").trim();
+									if (content) models = JSON.parse(content);
+								} catch {
+									models = { providers: {} };
+								}
 								if (
 									models.providers &&
 									Object.keys(models.providers).length > 0
@@ -1578,20 +1865,15 @@ export function registerProvider(program, repoRoot) {
 
 						case "codex": {
 							const configPath = join(agent.home, "config.toml");
-							if (existsSync(configPath)) {
-								const content = readFileSync(configPath, "utf8");
-								const providerMatch = content.match(/model_provider = "(.*?)"/);
-								const modelMatch = content.match(/model = "(.*?)"/);
-								if (providerMatch) {
-									console.log(`  Provider: ${chalk.dim(providerMatch[1])}`);
-									console.log(
-										`  Model:    ${chalk.dim(modelMatch ? modelMatch[1] : "not set")}`,
-									);
-								} else {
-									console.log(chalk.dim("  No provider configured"));
-								}
+							const info = readCodexProviderInfo(configPath);
+							if (info.provider) {
+								console.log(`  Provider: ${chalk.dim(info.provider)}`);
+								console.log(`  Model:    ${chalk.dim(info.model || "not set")}`);
+								console.log(`  Base URL: ${chalk.dim(info.baseUrl || "not set")}`);
+								console.log(`  Wire API: ${chalk.dim(info.wireApi || "not set")}`);
+								console.log(`  Env Key:  ${chalk.dim(info.envKey || "(none)")}`);
 							} else {
-								console.log(chalk.dim("  Config file not found"));
+								console.log(chalk.dim("  No provider configured"));
 							}
 							break;
 						}

package/src/lib/agents.mjs

@@ -1,5 +1,6 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
+import { execSync } from "node:child_process";
 import yaml from "js-yaml";
 import { expandHome } from "./fs.mjs";
 
@@ -27,10 +28,102 @@ export function getAgent(registry, agentId) {
 
 /**
  * Resolve ~ paths in agent definition.
+ *
+ * 如果 agent 声明了 home_env（如 codex 的 CODEX_HOME），且该环境变量已设置，
+ * 优先用它覆盖 home —— 因为 agent 运行时（如 orca 托管的 codex）会用这个
+ * 隔离的 home，而不是 registry 里的默认路径。否则 agent 会读到错误目录。
  */
 export function resolveAgentPaths(agent) {
+	const resolvedHome =
+		agent.home_env && process.env[agent.home_env]
+			? process.env[agent.home_env]
+			: expandHome(agent.home);
 	return {
 		...agent,
-		home: expandHome(agent.home),
+		home: resolvedHome,
 	};
 }
+
+// ── 当前 agent 检测 ───────────────────────────────────────────
+// 用于 install 时默认预选 cpc 自己跑在哪个 agent 内。
+// 注意：orca 会把 CODEX_HOME / OPENCODE_CONFIG_DIR 等「workspace 级」env 注入
+// 到工作区所有 shell（即便当前在 pi 内也会设 CODEX_HOME），所以 env 存在性
+// 不能用来判断「当前在哪个 agent」。只有 PPID 链里的 agent 进程名才是 ground
+// truth。env 信号仅作 PPID 不可用（非 Linux）时的兜底，且只用 agent 自身注入、
+// 非 orca 注入的变量（如 PI_CODING_AGENT）。
+
+// PPID 链里能识别的进程名前缀 → registry agentId
+const COMM_TO_AGENT = [
+	["pi", "pi"],
+	["codex", "codex"],
+	["claude", "claude-code"],
+	["opencode", "opencode"],
+	["hermes", "hermes"],
+	["omp", "omp"],
+	["openclaw", "openclaw"],
+];
+
+// agent 自身注入（非 orca）的存在性 env —— 仅 PPID 不可用时兜底
+const SELF_PRESENCE_ENV = {
+	pi: ["PI_CODING_AGENT"],
+};
+
+function readProcComm(pid) {
+	// Linux: /proc/<pid>/status
+	try {
+		const status = readFileSync(`/proc/${pid}/status`, "utf8");
+		const c = status.match(/^Name:\s*(\S+)/m);
+		const p = status.match(/^PPid:\s*(\d+)/m);
+		return { comm: c ? c[1] : null, ppid: p ? p[1] : null };
+	} catch {
+		return { comm: null, ppid: null };
+	}
+}
+
+function readCommViaPs(pid) {
+	// macOS / 其他 Unix 兜底
+	try {
+		const out = execSync(`ps -p ${pid} -o ppid=,comm=`, {
+			encoding: "utf8",
+			stdio: ["ignore", "pipe", "ignore"],
+			timeout: 1000,
+		}).trim();
+		const m = out.match(/^(\d+)\s+(.*)$/);
+		if (!m) return { comm: null, ppid: null };
+		return { comm: m[2].trim(), ppid: m[1] };
+	} catch {
+		return { comm: null, ppid: null };
+	}
+}
+
+/**
+ * 探测 cpc 当前跑在哪个 agent 内（用于 install 时默认预选）。
+ * 返回 agentId（registry key）或 null。
+ *
+ * 优先级：PPID 链进程名（ground truth）→ agent 自身注入 env（兜底）。
+ * 不使用 home_env / ORCA_* 存在性（orca 会 workspace 级注入，会误判）。
+ */
+export function detectCurrentAgent(agents) {
+	const ids = Object.keys(agents || {});
+
+	// 1) PPID 链进程名匹配（最可靠）
+	const reader = process.platform === "linux" ? readProcComm : readCommViaPs;
+	let pid = process.ppid;
+	for (let i = 0; i < 8 && pid; i++) {
+		const { comm, ppid } = reader(pid);
+		if (!comm) break;
+		const hit = COMM_TO_AGENT.find(
+			([c]) => comm === c || comm.startsWith(c),
+		);
+		if (hit) return hit[1];
+		if (!ppid || ppid === "0" || ppid === "1") break;
+		pid = Number(ppid);
+	}
+
+	// 2) 兜底：agent 自身注入的 env（非 orca 注入）
+	for (const id of ids) {
+		const vars = SELF_PRESENCE_ENV[id];
+		if (vars?.some((v) => process.env[v])) return id;
+	}
+	return null;
+}

package/src/lib/baseline-models.mjs

@@ -6,9 +6,10 @@
  *       - contextWindow: 模型上下文窗口
  *       - input:         模型支持的输入类型 (text / image / ...)
  *       - description:   模型中文描述
+ *       - reasoning:     是否为推理模型 (boolean)
  * 然后随 model 一起持久化到 ~/.config/cpc/providers.json
  *
- * 注意: 本字典不包含 maxTokens / reasoning, 仍由 src/commands/provider.mjs
+ * 注意: 本字典不包含 maxTokens, 仍由 src/commands/provider.mjs
  *       中的 MODEL_DEFAULTS 处理. 安装到 Agent 时, 各 agent schema 不消费
  *       description, 该字段仅作为 provider.json 内的元信息保留.
  */
@@ -19,54 +20,63 @@ export const BASELINE_MODELS = [
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2 全模态旗舰，文本/图像/音频/视频统一理解与生成。",
+		reasoning: false,
 	},
 	{
 		modelId: "mimo-v2-pro",
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2 推理增强版，强项为复杂推理与长程任务。",
+		reasoning: false,
 	},
 	{
 		modelId: "mimo-v2-tts",
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2 文本转语音合成模型，多音色/多语种。",
+		reasoning: false,
 	},
 	{
 		modelId: "mimo-v2.5",
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2.5 通用对话基座，性价比首选。",
+		reasoning: false,
 	},
 	{
 		modelId: "mimo-v2.5-asr",
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2.5 语音识别模型，音频转文字。",
+		reasoning: false,
 	},
 	{
 		modelId: "mimo-v2.5-pro",
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2.5 推理增强版，复杂任务与编程。",
+		reasoning: false,
 	},
 	{
 		modelId: "mimo-v2.5-tts",
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2.5 文本转语音合成模型。",
+		reasoning: false,
 	},
 	{
 		modelId: "mimo-v2.5-tts-voiceclone",
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2.5 声音克隆 TTS，参考音频复刻音色。",
+		reasoning: false,
 	},
 	{
 		modelId: "mimo-v2.5-tts-voicedesign",
 		contextWindow: 32768,
 		input: ["text"],
 		description: "小米 MiMo V2.5 声音设计 TTS，按描述/特征生成新音色。",
+		reasoning: false,
 	},
 	{
 		modelId: "gemma4:e4b",
@@ -74,6 +84,7 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"Google Gemma 4 边缘端模型（4.5B effective / 8B with embeddings），128K 上下文，支持文本+图像+音频。",
+		reasoning: false,
 	},
 	{
 		modelId: "qwen3.6:27b",
@@ -81,6 +92,7 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"Qwen3.5 架构的 27.8B dense 本地模型（Q4_K_M 17GB），本地多用途对话与编程。",
+		reasoning: false,
 	},
 	{
 		modelId: "qwen3.6-plus",
@@ -88,6 +100,7 @@ export const BASELINE_MODELS = [
 		input: ["text", "image"],
 		description:
 			"阿里 Qwen3.6 旗舰 VL 模型，主打 Agentic Coding、Vibe Coding 与 1M 多模态长上下文。",
+		reasoning: false,
 	},
 	{
 		modelId: "qwen3-vl-plus",
@@ -95,6 +108,7 @@ export const BASELINE_MODELS = [
 		input: ["text", "image"],
 		description:
 			"通义千问视觉旗舰，OS World 视觉 Agent SOTA，文档/视频/OCR 全能理解。",
+		reasoning: false,
 	},
 	{
 		modelId: "qwen3.5-122b-a10b",
@@ -102,6 +116,7 @@ export const BASELINE_MODELS = [
 		input: ["text", "image"],
 		description:
 			"Qwen3.5 开源 MoE 旗舰（122B 总参/10B 激活），262K 上下文，原生视觉语言模型。",
+		reasoning: false,
 	},
 	{
 		modelId: "qwen3-coder-plus",
@@ -109,6 +124,7 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"通义千问编码专项旗舰，1M 仓库级上下文，强工具调用与多文件重构。",
+		reasoning: false,
 	},
 	{
 		modelId: "text-embedding-v4",
@@ -116,6 +132,7 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"阿里 Qwen3-Embedding 旗舰，MTEB 多语言榜单领先，支持 8 种向量维度的语义检索首选。",
+		reasoning: false,
 	},
 	{
 		modelId: "GLM-5.0",
@@ -123,12 +140,14 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"智谱基座旗舰 744B MoE，编程对齐 Claude Opus 4.5，复杂系统工程与长程 Agent 基座。",
+		reasoning: false,
 	},
 	{
 		modelId: "GLM-5.0-anthropic",
 		contextWindow: 200000,
 		input: ["text"],
 		description: "GLM-5.0 的 Anthropic 协议兼容封装。",
+		reasoning: false,
 	},
 	{
 		modelId: "glm-5.1",
@@ -136,12 +155,29 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"智谱长程任务旗舰，可单任务持续自主工作 8 小时，编程对齐 Claude Opus 4.6。",
+		reasoning: false,
 	},
 	{
 		modelId: "glm-5.1-anthropic",
 		contextWindow: 200000,
 		input: ["text"],
 		description: "glm-5.1 的 Anthropic 协议兼容封装。",
+		reasoning: false,
+	},
+	{
+		modelId: "glm-5.2",
+		contextWindow: 1000000,
+		input: ["text"],
+		description:
+			"智谱 GLM-5 系列旗舰(7533.3亿/400亿激活),Solid 1M 无损上下文 + 128K 输出,面向长程 Agentic Coding 与多端可部署产物开发。",
+		reasoning: false,
+	},
+	{
+		modelId: "glm-5.2-anthropic",
+		contextWindow: 1000000,
+		input: ["text"],
+		description: "glm-5.2 的 Anthropic 协议兼容封装。",
+		reasoning: false,
 	},
 	{
 		modelId: "deepseek-v4-pro",
@@ -149,12 +185,14 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"DeepSeek V4 旗舰 1.6T MoE，开源 SOTA 世界知识与 Agent Coding，支持双思考模式。",
+		reasoning: false,
 	},
 	{
 		modelId: "deepseek-v4-pro-anthropic",
 		contextWindow: 1000000,
 		input: ["text"],
 		description: "DeepSeek V4-Pro 的 Anthropic 协议封装。",
+		reasoning: false,
 	},
 	{
 		modelId: "deepseek-v4-flash",
@@ -162,6 +200,7 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"DeepSeek V4 轻量版（284B/13B 激活），1M 上下文，主打高吞吐低成本日常 Agent。",
+		reasoning: false,
 	},
 	{
 		modelId: "DeepSeek-V3.2",
@@ -169,6 +208,7 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"DeepSeek V3 末代 DSA 稀疏注意力版本，平衡推理深度与输出长度，适合日常问答与 Agent。",
+		reasoning: false,
 	},
 	{
 		modelId: "Doubao-Seed-2.0-Pro",
@@ -176,6 +216,7 @@ export const BASELINE_MODELS = [
 		input: ["text", "image"],
 		description:
 			"字节豆包 2.0 旗舰，多模态视觉推理/空间推理 SOTA，全面对标 GPT-5.2 / Gemini 3 Pro。",
+		reasoning: false,
 	},
 	{
 		modelId: "Doubao-Seed-2.0-Code",
@@ -183,6 +224,7 @@ export const BASELINE_MODELS = [
 		input: ["text", "image"],
 		description:
 			"字节豆包 2.0 编程专版，前端强、支持 UI-to-Code 视觉理解，与 TRAE 集成最佳。",
+		reasoning: false,
 	},
 	{
 		modelId: "Kimi-K2.5",
@@ -190,6 +232,7 @@ export const BASELINE_MODELS = [
 		input: ["text", "image"],
 		description:
 			"月之暗面原生多模态旗舰，文本+视觉联合优化，Agent Swarm 与视觉编程（UI/视频生成代码）。",
+		reasoning: false,
 	},
 	{
 		modelId: "kimi-k2.6",
@@ -197,12 +240,14 @@ export const BASELINE_MODELS = [
 		input: ["text", "image"],
 		description:
 			"月之暗面 K2.6，开源 SOTA 长程编码（13 小时不间断）+ Agent Swarm 300 子智能体。",
+		reasoning: false,
 	},
 	{
 		modelId: "kimi-k2.6-anthropic",
 		contextWindow: 256000,
 		input: ["text", "image"],
 		description: "kimi-k2.6 的 Anthropic 协议兼容封装。",
+		reasoning: false,
 	},
 	{
 		modelId: "minimax-m3",
@@ -210,6 +255,7 @@ export const BASELINE_MODELS = [
 		input: ["text", "image"],
 		description:
 			"MiniMax 2026 旗舰，国内首个前沿 Coding + 1M 上下文 + 原生多模态三合一模型。",
+		reasoning: false,
 	},
 	{
 		modelId: "MiniMax-M2.7",
@@ -217,12 +263,14 @@ export const BASELINE_MODELS = [
 		input: ["text"],
 		description:
 			"MiniMax M2.7，模型自我进化路径，端到端软件工程交付与 Office 复杂编辑。",
+		reasoning: false,
 	},
 	{
 		modelId: "minimax-m2.7",
 		contextWindow: 204800,
 		input: ["text"],
 		description: "MiniMax M2.7 小写别名，与 MiniMax-M2.7 同款。",
+		reasoning: false,
 	},
 ];
 
@@ -257,9 +305,9 @@ export function lookupBaselineModel(modelId) {
 
 /**
  * 用 baseline 字典补全 model 字段
- * 命中时, baseline 的 contextWindow / input / description 会覆盖传入值
+ * 命中时, baseline 的 contextWindow / input / description / reasoning 会覆盖传入值
  * 命不中则原样返回
- * maxTokens / reasoning 不在 baseline 范围, 由调用方自己处理
+ * maxTokens 不在 baseline 范围, 由调用方自己处理
  * @param {object} model 至少有 { id }
  * @returns {object} 增强后的 model
  */
@@ -282,5 +330,9 @@ export function enrichModelWithBaseline(model) {
 		enriched.description = baseline.description;
 	}
 
+	if (typeof baseline.reasoning === "boolean") {
+		enriched.reasoning = baseline.reasoning;
+	}
+
 	return enriched;
 }

package/src/lib/codex-toml.mjs

@@ -0,0 +1,175 @@
+import { existsSync, readFileSync, writeFileSync, copyFileSync } from "node:fs";
+
+/**
+ * Codex config.toml 稳健操作工具。
+ *
+ * 现有问题：provider.mjs 旧实现用 `/model = .*\n/` 简单正则替换顶层
+ * key，并把 provider 段整段字符串拼接，丢掉 env_key、可能误伤同前缀
+ * key（model_personality / model_reasoning_effort）。
+ *
+ * 本模块用"顶层区域隔离 + 段内逐字段 upsert"的方式重写：
+ * - 顶层 key 只在第一个 table section 之前查找/替换/插入
+ * - provider 段：已存在则段内逐字段更新（不丢用户手动加的字段），
+ *   不存在则追加
+ */
+
+function escapeRegex(s) {
+	return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function ensureNewline(s) {
+	return s === "" || s.endsWith("\n") ? s : s + "\n";
+}
+
+/**
+ * 在"顶层区域"（第一个 table section 之前）精确替换或插入一个字符串 key。
+ * 只匹配行首 `key =`，不会误伤 `key_suffix =` 同前缀 key。
+ */
+function setTopLevelString(content, key, value) {
+	const line = `${key} = "${value}"`;
+	const secMatch = content.match(/^[ \t]*\[/m);
+	const topEnd = secMatch ? secMatch.index : content.length;
+	const top = content.slice(0, topEnd);
+	const rest = content.slice(topEnd);
+
+	const re = new RegExp(`^[ \\t]*${escapeRegex(key)}[ \\t]*=.*$`, "m");
+	if (re.test(top)) {
+		return top.replace(re, line) + rest;
+	}
+	// 顶层没有该 key：插到顶层末尾（第一个 section 之前）
+	return ensureNewline(top) + line + "\n" + rest;
+}
+
+/**
+ * 找 [section] 段的 { start, headerEnd, bodyEnd }。
+ * bodyEnd = 下一个 section 开始处 或 文件尾。
+ */
+function findSectionRange(content, sectionHeader) {
+	const re = new RegExp(`^[ \\t]*${escapeRegex(sectionHeader)}[ \\t]*$`, "m");
+	const m = re.exec(content);
+	if (!m) return null;
+	const headerEnd = m.index + m[0].length;
+	const after = content.slice(headerEnd);
+	const next = after.match(/^[ \t]*\[/m);
+	const bodyEnd = next ? headerEnd + next.index : content.length;
+	return { start: m.index, headerEnd, bodyEnd };
+}
+
+/**
+ * 在 section 段体内 upsert 一个字符串字段。
+ * 已存在则替换该行，不存在则在段体末尾追加。
+ */
+function upsertFieldInSection(content, sectionHeader, key, value) {
+	const range = findSectionRange(content, sectionHeader);
+	if (!range) return content;
+	const line = `${key} = "${value}"`;
+	const body = content.slice(range.headerEnd, range.bodyEnd);
+	const re = new RegExp(`^[ \\t]*${escapeRegex(key)}[ \\t]*=.*$`, "m");
+	if (re.test(body)) {
+		const newBody = body.replace(re, line);
+		return content.slice(0, range.headerEnd) + newBody + content.slice(range.bodyEnd);
+	}
+	// 段体末尾追加（bodyEnd 之前）
+	const insertion = `${line}\n`;
+	return content.slice(0, range.bodyEnd) + insertion + content.slice(range.bodyEnd);
+}
+
+/**
+ * 备份 config.toml -> config.toml.cpc.bak
+ */
+export function backupCodexConfig(configPath) {
+	if (!existsSync(configPath)) return null;
+	const bak = `${configPath}.cpc.bak`;
+	copyFileSync(configPath, bak);
+	return bak;
+}
+
+/**
+ * 写入 codex provider 配置到 config.toml（全局默认方式）。
+ *
+ * - 顶层：model_provider, model（可选 model_reasoning_effort）
+ * - 段：[model_providers.NAME] 内 upsert name/base_url/wire_api/env_key
+ *
+ * @param {string} configPath ~/.codex/config.toml
+ * @param {object} opts
+ * @param {string} opts.providerName
+ * @param {string} opts.baseUrl
+ * @param {string} opts.wireApi   "responses" | "chat_completions"
+ * @param {string} [opts.envKey]  环境变量名；不传则不写 env_key
+ * @param {string} opts.model     全局默认 model id
+ * @param {string} [opts.modelReasoningEffort]
+ * @returns {{backed: string|null, wrote: string}}
+ */
+export function writeCodexProviderConfig(configPath, opts) {
+	const backed = backupCodexConfig(configPath);
+	let content = existsSync(configPath)
+		? readFileSync(configPath, "utf8")
+		: "";
+
+	// 顶层 key
+	content = setTopLevelString(content, "model_provider", opts.providerName);
+	content = setTopLevelString(content, "model", opts.model);
+	if (opts.modelReasoningEffort) {
+		content = setTopLevelString(
+			content,
+			"model_reasoning_effort",
+			opts.modelReasoningEffort,
+		);
+	}
+
+	// provider 段
+	const header = `[model_providers.${opts.providerName}]`;
+	if (!findSectionRange(content, header)) {
+		// 追加新段，确保前导空行
+		const sep = content && !content.endsWith("\n\n")
+			? content.endsWith("\n") ? "\n" : "\n\n"
+			: "";
+		content = content + sep + header + "\n";
+	}
+
+	content = upsertFieldInSection(content, header, "name", opts.providerName);
+	content = upsertFieldInSection(content, header, "base_url", opts.baseUrl);
+	content = upsertFieldInSection(content, header, "wire_api", opts.wireApi);
+	if (opts.envKey) {
+		content = upsertFieldInSection(content, header, "env_key", opts.envKey);
+	}
+
+	writeFileSync(configPath, content);
+	return { backed, wrote: configPath };
+}
+
+/**
+ * 读取 codex config.toml 当前的 provider 配置摘要（用于 list-installed）。
+ * @returns {{provider: string|null, model: string|null, envKey: string|null, baseUrl: string|null, wireApi: string|null}}
+ */
+export function readCodexProviderInfo(configPath) {
+	if (!existsSync(configPath)) {
+		return { provider: null, model: null, envKey: null, baseUrl: null, wireApi: null };
+	}
+	const content = readFileSync(configPath, "utf8");
+	const get = (re) => {
+		const m = content.match(re);
+		return m ? m[1] : null;
+	};
+	const provider = get(/^[ \t]*model_provider[ \t]*=\s*"([^"]*)"/m);
+	const model = get(/^[ \t]*model[ \t]*=\s*"([^"]*)"/m);
+	let envKey = null;
+	let baseUrl = null;
+	let wireApi = null;
+	if (provider) {
+		const range = findSectionRange(content, `[model_providers.${provider}]`);
+		if (range) {
+			const body = content.slice(range.headerEnd, range.bodyEnd);
+			const pick = (key) => {
+				const m = body.match(
+					new RegExp(`^[ \\t]*${key}[ \\t]*=\\s*"([^"]*)"`, "m"),
+				);
+				return m ? m[1] : null;
+			};
+			envKey = pick("env_key");
+			baseUrl = pick("base_url");
+			wireApi = pick("wire_api");
+		}
+	}
+	return { provider, model, envKey, baseUrl, wireApi };
+}

package/src/lib/env.mjs

@@ -0,0 +1,115 @@
+import { homedir } from "node:os";
+import {
+	existsSync,
+	readFileSync,
+	writeFileSync,
+	appendFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import { execSync } from "node:child_process";
+
+/**
+ * 跨平台环境变量持久化模块。
+ *
+ * codex 的 model_providers 只能用 `env_key` 引用环境变量，
+ * 不能内联 key。cpc 安装到 codex 时，需要把 provider.apiKey
+ * 落地到一个环境变量里，并保证新开的终端/codex 进程能读到。
+ *
+ * 平台策略：
+ * - Linux / macOS: 按 $SHELL 检测写 ~/.zshrc 或 ~/.bashrc（幂等）
+ * - Windows: 用 setx 写入用户环境变量（注册表 HKCU\Environment）
+ */
+
+/**
+ * 推断当前 shell 的 rc 文件路径。
+ * @returns {string|null} rc 文件绝对路径；Windows 返回 null
+ */
+function detectShellRc() {
+	const platform = process.platform;
+	if (platform === "win32") return null;
+
+	const shell = process.env.SHELL || "";
+	const home = homedir();
+	if (shell.includes("zsh")) return join(home, ".zshrc");
+	if (shell.includes("bash")) return join(home, ".bashrc");
+
+	// $SHELL 缺失时按平台兜底：macOS 默认 zsh，其余默认 bash
+	if (platform === "darwin") return join(home, ".zshrc");
+	return join(home, ".bashrc");
+}
+
+/**
+ * 幂等地把 `export KEY="value"` 写入 rc 文件。
+ * 已存在该 export 行则替换值，不存在则追加。
+ */
+function persistToRc(rcPath, key, value) {
+	const exportLine = `export ${key}="${value}"`;
+	let content = "";
+	if (existsSync(rcPath)) {
+		content = readFileSync(rcPath, "utf8");
+	}
+	// 精确匹配 `export KEY=...` 整行
+	const regex = new RegExp(`^export ${key}=.*$`, "m");
+	if (regex.test(content)) {
+		const updated = content.replace(regex, exportLine);
+		if (updated !== content) {
+			writeFileSync(rcPath, updated);
+		}
+		return false; // 不是新增
+	}
+	const sep = content && !content.endsWith("\n") ? "\n" : "";
+	const block = `${sep}# Added by cpc (codex provider)\n${exportLine}\n`;
+	appendFileSync(rcPath, block);
+	return true; // 新增
+}
+
+/**
+ * Windows: 用 setx 持久化用户环境变量。
+ * 注意 setx 设置的变量只在新进程生效，当前进程不会自动有。
+ */
+function persistWithSetx(key, value) {
+	// setx 对带空格的值需要引号；API key 一般是 token 串，安全起见仍加引号
+	execSync(`setx ${key} "${value}"`, {
+		shell: "cmd.exe",
+		stdio: "ignore",
+	});
+}
+
+/**
+ * 跨平台持久化环境变量。
+ *
+ * @param {string} key 环境变量名
+ * @param {string} value 值
+ * @returns {{method: "rc"|"setx"|"skip", target: string, created: boolean}}
+ */
+export function persistEnvVar(key, value) {
+	if (!key || value == null) {
+		return { method: "skip", target: "", created: false };
+	}
+
+	const rc = detectShellRc();
+	if (rc) {
+		const created = persistToRc(rc, key, value);
+		return { method: "rc", target: rc, created };
+	}
+
+	// Windows
+	try {
+		persistWithSetx(key, value);
+		return { method: "setx", target: "HKCU\\Environment", created: true };
+	} catch (err) {
+		throw new Error(`Failed to set env var on Windows: ${err.message}`);
+	}
+}
+
+/**
+ * 把 provider 名转成规范环境变量名：CPC_<NAME_UPPER>_API_KEY
+ * 非字母数字字符 -> _
+ */
+export function envKeyNameForProvider(providerName) {
+	const safe = String(providerName)
+		.toUpperCase()
+		.replace(/[^A-Z0-9]+/g, "_")
+		.replace(/^_+|_+$/g, "");
+	return `CPC_${safe}_API_KEY`;
+}