Configuration Schema

Relevant source files

The following files were used as context for generating this wiki page:

• src/config/unified-config-loader.ts
• src/config/loader/yaml-serializer.ts
• scripts/postinstall.js
• src/web-server/services/codex-dashboard-service.ts (via test implementation)
• src/web-server/routes/config-routes.ts (via test implementation)
• src/cliproxy/config/config-generator.ts (via test implementation)

The Configuration Schema in CCS provides a centralized and unified system for managing multiple AI provider profiles, account contexts, and runtime settings. The project has transitioned from a legacy JSON-based configuration (config.json) to a more robust, human-readable YAML-based "Unified Config" (config.yaml) stored within the ~/.ccs/ directory.

This system ensures that various CLI tools—such as Claude Code, Codex, and Factory Droid—can be executed using consistent settings without manual configuration thrashing. It handles provider-specific environment variables, OAuth account management, and local proxy routing rules through a structured schema that supports atomic writes and versioning.

Sources: src/config/unified-config-loader.ts, scripts/postinstall.js:10-25, README.md:40-55

Unified Config Structure

The core of the system is the UnifiedConfig, which is managed via a dedicated loader that handles I/O locks, default merging, and YAML serialization.

Core Configuration Sections

The schema is divided into several logical blocks, each responsible for a specific aspect of the application's runtime environment:

Section	Description	Key Fields
Accounts	Isolated instances with separate auth and sessions.	created, last_used, context_mode, context_group
Profiles	API-based providers (GLM, Kimi, etc.) pointing to settings files.	name, settings_path
CLIProxy	OAuth-based providers (Gemini, Codex, etc.) managed by the local proxy.	variants, oauth_accounts, management_panel_repository
Proxy Routing	Rules for OpenAI-compatible local proxy model selection.	routing, fallback
Thinking	Reasoning budget and depth configuration for supported models.	mode, levels, overrides
Browser	Automation settings for Claude attach and Codex tooling.	user_data_dir, devtools_port, eval_mode

Sources: src/config/loader/yaml-serializer.ts:24-150, tests/unit/web-server/config-routes-account-context.test.ts:110-140

Configuration Lifecycle

The following diagram illustrates how the system loads, validates, and saves configuration data, ensuring that version upgrades and default merges happen automatically.

The configuration loader includes an auto-upgrade mechanism that regenerates the YAML file with updated comments and new fields whenever the schema version is incremented.

Sources: src/config/unified-config-loader.ts:125-160, src/config/loader/yaml-serializer.ts:15-20

Account and Context Management

CCS introduces "Account Contexts" that define how local session data and history are handled. Accounts can operate in different modes to either isolate or share execution environments.

Context Modes

• Isolated: Default mode where each account maintains separate state.
• Shared: Allows multiple profiles to reuse account continuity artifacts (such as CLAUDE_CONFIG_DIR). This requires a context_group identifier.

Validated Context Fields

The schema enforces strict validation on account metadata through the web server routes:

• context_mode: Must be one of isolated or shared.
• context_group: Required when mode is shared; must be a non-empty, alphanumeric string.
• continuity_mode: Optional depth setting (e.g., deeper) available only in shared mode.

Sources: tests/unit/web-server/config-routes-account-context.test.ts:110-150

CLIProxy and Provider Schema

The cliproxy section manages the integration with OAuth-backed providers. It defines "variants" which are specific configurations for providers like Gemini or Codex.

Variant Configuration

Each variant in the cliproxy schema typically contains:

• Provider: The backend identifier (e.g., gemini, codex, agy).
• Auth: Redacted sensitive credentials including api_key and management_secret.
• Settings: A pointer to a *.settings.json file containing the environment variables injected at runtime.

Model Alias Handling

For the Codex provider, the schema supports model aliases that include a fork boolean. This is specifically used to manage compatibility for Claude-based models within the Codex ecosystem.

Security and Data Integrity

The configuration system prioritizes the protection of sensitive information through redaction and atomic I/O operations.

Secret Redaction

When configuration data is served via the API (e.g., to the Dashboard UI) or serialized for certain logs, sensitive keys are automatically replaced with a [redacted] placeholder. This affects:

• Environment variables like GITHUB_TOKEN or OPENAI_API_KEY.
• CLIProxy api_key and management_secret fields.
• Dashboard authentication password_hash.

Sources: tests/unit/web-server/config-routes-account-context.test.ts:178-220

Atomic Writes and Locking

To prevent corruption during concurrent writes (especially when the dashboard and CLI are used simultaneously), CCS uses:

1. Lockfiles: A config.lock file is used to gate write access.
2. Temp Files: Config is written to config.yaml.tmp and سپس renamed to the target path.
3. Syncing: The withConfigWriteLock helper ensures that the read-modify-write cycle is atomic.

Sources: src/config/unified-config-loader.ts:35-50, src/cliproxy/config/tests/config-generator.test.js:130-150

Summary

The CCS Configuration Schema provides a robust, versioned, and secure foundation for multi-provider AI management. By centralizing settings in a human-readable YAML format and enforcing strict validation and redaction, the system ensures interoperability between different AI runtimes while protecting user credentials. The transition to the "Unified Config" architecture facilitates automatic upgrades and minimizes the risk of configuration corruption.