## 配置教程

### 配置文件说明

所有配置文件都存放在 `configs/` 目录下。主要配置文件包括：

config.json 必需

主配置文件，包含 API Key、端口、模型提供商等核心设置

provider_pools.json 必需

提供商池配置，用于多账号轮询和故障转移

plugins.json 可选

插件配置，用于启用或禁用系统插件

pwd 可选

后台登录密码文件，默认密码为 admin123

### 主配置详解 (config.json)

#### 基础配置

参数 | 类型 | 默认值 | 说明
--- | --- | --- | ---
`REQUIRED_API_KEY` | string | - | 访问本服务所需的 API Key
`SERVER_PORT` | number | 3000 | 服务监听端口
`HOST` | string | 0.0.0.0 | 服务监听地址
`MODEL_PROVIDER` | string | - | 默认模型提供商

#### 系统提示配置

参数 | 类型 | 默认值 | 说明
--- | --- | --- | ---
`SYSTEM_PROMPT_FILE_PATH` | string | - | 系统提示文件路径
`SYSTEM_PROMPT_MODE` | string | overwrite | 系统提示模式：overwrite(覆盖) 或 append(追加)

#### 重试配置

参数 | 类型 | 默认值 | 说明
--- | --- | --- | ---
`REQUEST_MAX_RETRIES` | number | 3 | 最大重试次数
`REQUEST_BASE_DELAY` | number | 1000 | 重试基础延迟（毫秒）
`MAX_ERROR_COUNT` | number | 10 | 提供商最大错误次数，超过后标记为不健康

#### 配置示例

    {
        "REQUIRED_API_KEY": "your-api-key",
        "SERVER_PORT": 3000,
        "HOST": "0.0.0.0",
        "MODEL_PROVIDER": "gemini-cli-oauth",
        "SYSTEM_PROMPT_FILE_PATH": "configs/input_system_prompt.txt",
        "SYSTEM_PROMPT_MODE": "overwrite",
        "REQUEST_MAX_RETRIES": 3,
        "REQUEST_BASE_DELAY": 1000,
        "MAX_ERROR_COUNT": 10,
        "PROVIDER_POOLS_FILE_PATH": "configs/provider_pools.json"
    }

### 提供商池配置 (provider_pools.json)

提供商池用于配置多个账号，实现负载均衡和故障转移。每个提供商类型可以配置多个账号节点。

#### 节点配置参数

参数 | 类型 | 说明
--- | --- | ---
`uuid` | string | 节点唯一标识，自动生成
`name` | string | 节点自定义名称
`oauthCredsFilePath` | string | OAuth 凭据文件路径
`checkHealth` | boolean | 是否启用健康检查
`checkModel` | string | 健康检查使用的模型
`notSupportedModels` | array | 该节点不支持的模型列表
`disabled` | boolean | 是否禁用该节点

#### 配置示例

    {
        "gemini-cli-oauth": [
            {
                "uuid": "gemini-account-1",
                "name": "Gemini 账号 1",
                "oauthCredsFilePath": "configs/gemini/oauth_creds_1.json",
                "checkHealth": true,
                "checkModel": "gemini-2.0-flash-exp"
            },
            {
                "uuid": "gemini-account-2",
                "name": "Gemini 账号 2",
                "oauthCredsFilePath": "configs/gemini/oauth_creds_2.json",
                "checkHealth": true,
                "notSupportedModels": ["gemini-3.0-pro"]
            }
        ],
        "claude-kiro-oauth": [
            {
                "uuid": "kiro-account-1",
                "name": "Kiro 账号 1",
                "oauthCredsFilePath": "configs/kiro/kiro-auth-token.json",
                "checkHealth": true,
                "checkModel": "claude-sonnet-4-5"
            }
        ]
    }

### Fallback 降级配置

当某一提供商类型的所有账号都不可用时，可以自动切换到配置的备用提供商。

#### 跨类型 Fallback 链

在 config.json 中配置 providerFallbackChain，指定每个提供商类型的备用类型：

    {
        "providerFallbackChain": {
            "gemini-cli-oauth": ["gemini-antigravity"],
            "gemini-antigravity": ["gemini-cli-oauth"],
            "claude-kiro-oauth": ["claude-custom"],
            "claude-custom": ["claude-kiro-oauth"]
        }
    }

#### 跨协议模型映射

当主提供商不可用时，可以将特定模型映射到其他协议的提供商：

    {
        "modelFallbackMapping": {
            "gemini-claude-opus-4-5-thinking": {
                "targetProviderType": "claude-kiro-oauth",
                "targetModel": "claude-opus-4-5"
            },
            "claude-opus-4-5": {
                "targetProviderType": "gemini-antigravity",
                "targetModel": "gemini-claude-opus-4-5-thinking"
            }
        }
    }

### 代理配置

支持为特定提供商配置代理，用于网络受限环境。

#### 代理配置参数

参数 | 类型 | 说明
--- | --- | ---
`PROXY_URL` | string | 代理地址，支持 HTTP、HTTPS、SOCKS5
`PROXY_ENABLED_PROVIDERS` | array | 启用代理的提供商列表

#### 配置示例

    {
        "PROXY_URL": "http://127.0.0.1:7890",
        "PROXY_ENABLED_PROVIDERS": [
            "gemini-cli-oauth",
            "gemini-antigravity"
        ]
    }

支持的代理类型：HTTP (http://)、HTTPS (https://)、SOCKS5 (socks5://)

### OAuth 授权配置

各提供商的 OAuth 凭据文件默认存储位置：

Gemini
`~/.gemini/oauth_creds.json`
Antigravity
`~/.antigravity/oauth_creds.json`
Kiro
`~/.aws/sso/cache/kiro-auth-token.json`
Qwen
`~/.qwen/oauth_creds.json`
推荐通过 Web UI 控制台的"提供商池管理"页面点击"生成授权"按钮进行可视化授权，系统会自动保存凭据文件。

### 日志配置

#### 提示日志配置

参数 | 类型 | 说明
--- | --- | ---
`PROMPT_LOG_MODE` | string | 日志模式：none(关闭)、console(控制台)、file(文件)
`PROMPT_LOG_BASE_NAME` | string | 日志文件基础名称

#### 配置示例

    {
        "PROMPT_LOG_MODE": "file",
        "PROMPT_LOG_BASE_NAME": "prompt_log"
    }