自定义模型

通过Langcli的配置文件settings.json的 modelProviders 设置项，Langcli 允许你配置自定义模型提供商。这使你能够使用 /model 命令在不同的 AI 模型之间切换（包括来自 LangRouter 的模型以及你自己定义的模型）。

概述

使用 modelProviders 可按协议类型声明自定义的模型列表，供 /model 选择器切换。可选的协议类型包括openai、anthropic、gemini。每个模型定义都需要一个 id 且必须包含 envKey，可选字段包括 name、description、baseUrl 和 generationConfig等。

配置文件settings.json的路径

Macos/Linux/WSL: ~/.langcli/settings.json
windows: C:\Users\%USERNAME%\.langcli\settings.json

协议类型下的重复模型id

在单个协议类型下定义多个具有相同 id 的模型（例如在 openai 中有两个 "id": "gpt-4o" 的条目）目前不受支持。如果存在重复项，首次出现的条目将生效，后续重复项将被跳过并显示警告。请注意，id 字段既用作配置标识符，也用作发送给 API 的实际模型名称，因此使用唯一 ID（如 gpt-4o-creative、gpt-4o-balanced）并不是可行的变通方案。这是一个已知限制，我们计划在后续版本中解决。

验证settings.json的修改是否合法

你修改了settings.json之后，可以执行下面的命令来验证你的修改是否合法：

langcli doctor

如有异常，这条指令会提示你。如无异常，doctor指令仅仅会输出Diagnostics、Updates信息，你按回车键确认即可。

支持的协议类型

modelProviders 对象的键必须是有效的协议类型值。目前支持的协议类型包括：

协议类型	描述
`openai`	OpenAI兼容APIs (例如vLLM/Ollama的本地自托管模型服务, Litellm, OpenAI, Azure OpenAI)
`anthropic`	Anthropic Claude API
`gemini`	Google Gemini API

无效协议类型

如果使用了无效的协议类型键（例如，拼写错误如 "openai-custom"），该配置将被静默跳过，相关模型不会出现在 /model 选择器中。请始终使用上面列出的受支持认证类型值之一。

按协议类型的配置示例

以下是针对不同协议类型的完整配置示例，展示了可用参数及其组合。

本地自托管模型（通过 OpenAI 兼容的 API）

大多数本地推理服务器（vLLM、Ollama、LM Studio 等）都提供与 OpenAI 兼容的 API 端点。使用 openai 协议类型和本地 baseUrl 对其进行配置：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.langrouter.ai",
    "ANTHROPIC_AUTH_TOKEN": "your_langrouter_api_key",
    "OLLAMA_API_KEY": "ollama",
    "VLLM_API_KEY": "not-needed"
  },
  "model": "custom:qwen3.6:35b-a3b-q4_K_M",
  "modelProviders": {
    "openai": [
      {
        "id": "qwen3.6:35b-a3b-q4_K_M",
        "name": "Qwen3.6:35B A3B (Ollama)",
        "envKey": "OLLAMA_API_KEY",
        "baseUrl": "http://localhost:11434/v1",
        "generationConfig": {
          "timeout": 300000,
          "maxRetries": 2,
          "contextWindowSize": 32768,
          "samplingParams": {
            "temperature": 0.7,
            "top_p": 0.9,
            "max_tokens": 4096
          }
        }
      },
      {
        "id": "llama-3.1-8b",
        "name": "Llama 3.1 8B (vLLM)",
        "envKey": "VLLM_API_KEY",
        "baseUrl": "http://localhost:8000/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 2,
          "contextWindowSize": 128000,
          "samplingParams": {
            "temperature": 0.6,
            "max_tokens": 8192
          }
        }
      }
    ]
  }
}

兼容 OpenAI 的提供商（`openai`）

该协议类型不仅支持 OpenAI 的官方 API，还支持任何与 OpenAI 兼容的端点，包括 OpenRouter 等聚合模型提供商。

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.langrouter.ai",
    "ANTHROPIC_AUTH_TOKEN": "your_langrouter_api_key",
    "DEEPSEEK_API_KEY": "abc",
    "OPENAI_API_KEY": "sk-your-actual-openai-key-here",
    "OPENROUTER_API_KEY": "sk-or-your-actual-openrouter-key-here"
  },
  "model": "custom:gpt-4o",
  "modelProviders": {
    "openai": [
      {
        "id": "deepseek-v4-flash[1m]",
        "name": "deepseek-v4-flash[1m] (custom)",
        "envKey": "DEEPSEEK_API_KEY",
        "baseUrl": "https://api.deepseek.com",
        "generationConfig": {
          "timeout": 300000,
          "maxRetries": 2,
          "contextWindowSize": 1000000,
          "samplingParams": {
            "temperature": 0.7,
            "top_p": 0.9,
            "max_tokens": 384000
          }
        }
      },
      {
        "id": "deepseek-v4-pro[1m]",
        "name": "deepseek-v4-pro[1m] (custom)",
        "envKey": "DEEPSEEK_API_KEY",
        "baseUrl": "https://api.deepseek.com",
        "generationConfig": {
          "timeout": 300000,
          "maxRetries": 2,
          "contextWindowSize": 1000000,
          "samplingParams": {
            "temperature": 0.7,
            "top_p": 0.9,
            "max_tokens": 384000
          }
        }
      },
      {
        "id": "gpt-4o",
        "name": "GPT-4o",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 3,
          "enableCacheControl": true,
          "contextWindowSize": 128000,
          "modalities": {
            "image": true
          },
          "customHeaders": {
            "X-Client-Request-ID": "req-123"
          },
          "extra_body": {
            "enable_thinking": true,
            "service_tier": "priority"
          },
          "samplingParams": {
            "temperature": 0.2,
            "top_p": 0.8,
            "max_tokens": 4096,
            "presence_penalty": 0.1,
            "frequency_penalty": 0.1
          }
        }
      },
      {
        "id": "gpt-4o-mini",
        "name": "GPT-4o Mini",
        "envKey": "OPENAI_API_KEY",
        "baseUrl": "https://api.openai.com/v1",
        "generationConfig": {
          "timeout": 30000,
          "samplingParams": {
            "temperature": 0.5,
            "max_tokens": 2048
          }
        }
      },
      {
        "id": "openai/gpt-4o",
        "name": "GPT-4o (via OpenRouter)",
        "envKey": "OPENROUTER_API_KEY",
        "baseUrl": "https://openrouter.ai/api/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "samplingParams": {
            "temperature": 0.7
          }
        }
      }
    ]
  }
}

Anthropic (`anthropic`)

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.langrouter.ai",
    "ANTHROPIC_AUTH_TOKEN": "your_langrouter_api_key",
    "MY_ANTHROPIC_API_KEY": "sk-ant-your-actual-anthropic-key-here"
  },
  "model": "custom:claude-3-opus",
  "modelProviders": {
    "anthropic": [
      {
        "id": "claude-3-5-sonnet",
        "name": "Claude 3.5 Sonnet",
        "envKey": "MY_ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 120000,
          "maxRetries": 3,
          "contextWindowSize": 200000,
          "samplingParams": {
            "temperature": 0.7,
            "max_tokens": 8192,
            "top_p": 0.9
          }
        }
      },
      {
        "id": "claude-3-opus",
        "name": "Claude 3 Opus",
        "envKey": "MY_ANTHROPIC_API_KEY",
        "baseUrl": "https://api.anthropic.com/v1",
        "generationConfig": {
          "timeout": 180000,
          "samplingParams": {
            "temperature": 0.3,
            "max_tokens": 4096
          }
        }
      }
    ]
  }
}

Google Gemini (`gemini`)

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://api.langrouter.ai",
    "ANTHROPIC_AUTH_TOKEN": "your_langrouter_api_key",
    "GEMINI_API_KEY": "AIza-your-actual-gemini-key-here"
  },
  "model": "custom:gemini-2.0-flash",
  "modelProviders": {
    "gemini": [
      {
        "id": "gemini-2.0-flash",
        "name": "Gemini 2.0 Flash",
        "envKey": "GEMINI_API_KEY",
        "baseUrl": "https://generativelanguage.googleapis.com",
        "capabilities": {
          "vision": true
        },
        "generationConfig": {
          "timeout": 60000,
          "maxRetries": 2,
          "contextWindowSize": 1000000,
          "schemaCompliance": "auto",
          "samplingParams": {
            "temperature": 0.4,
            "top_p": 0.95,
            "max_tokens": 8192,
            "top_k": 40
          }
        }
      }
    ]
  }
}

补充说明

对于不需要身份验证的本地服务器，您可以使用任何占位符值作为 API 密钥：

# 对于 Ollama（无需验证）
"OLLAMA_API_KEY": "ollama"

# 对于 vLLM（如果未配置身份验证）
"VLLM_API_KEY": "not-needed"

extra_body参数的设置

extra_body 参数 仅对兼容openai协议的模型/服务商 有效。Anthropic 和 Gemini 提供商会忽略此参数。

envKey参数的设置

envKey 字段指定的是环境变量的名称，而不是实际的 API 密钥值。要使配置生效，您需要确保已将相应的环境变量设置为您的真实 API 密钥。您可以通过在 settings.json 文件中使用 env 字段来实现（如上面的示例所示）:

{
  "env": {
    "OPENAI_API_KEY": "sk-your-actual-key-here"
  }
}

每个自定义模型示例都包含一个 envKey 字段，用于说明如何配置 API 密钥。

目录