在 Copilot CLI 中配置 BYOK：使用 Ollama 和 Gemma 4

基于 Copilot CLI 测试，2026 年 4 月 8 日。

我最近在测试 GitHub Copilot CLI 的 BYOK（Bring Your Own Key，自带密钥）功能，使用本地 Ollama 实例运行 Gemma 4。官方文档覆盖了基本配置流程。如果你还没看过，建议先从这里开始：在 GitHub Copilot CLI 中使用自己的 LLM 模型。以下是我在实际操作中遇到的问题。

第一步：确认 Ollama 是否在运行

在设置任何环境变量之前，先确认 Ollama 正常响应：

curl http://localhost:11434/api/tags

如果 Ollama 正在运行，你会看到已安装的模型列表。如果返回 connection refused，说明 Ollama 没有启动。检查系统托盘或先运行 ollama serve。

这听起来很基础，但当你花了 20 分钟排查环境变量，结果发现是进程没启动的时候，就不觉得基础了。

设置环境变量

export COPILOT_PROVIDER_BASE_URL=http://localhost:11434
export COPILOT_MODEL=gemma4:31b

两个容易踩的坑。第一：使用 ollama list 中显示的完整模型名称。不是 gemma4，不是 Gemma-4-31B，必须完全匹配，所以用 gemma4:31b。

第二：本地 Ollama 不需要设置 COPILOT_PROVIDER_API_KEY。Ollama 默认不需要认证，设置空的 key 反而可能导致错误。

默认端口是 11434，如果你修改过，可以用以下命令确认：

# macOS/Linux
lsof -i :11434

# Windows
netstat -an | findstr 11434

关于 Anthropic 模型的说明

文档中提到使用 Anthropic 作为提供者时，COPILOT_PROVIDER_BASE_URL 可能是可选的。在我的测试中（Copilot CLI，2026 年 4 月 8 日），CLI 实际上要求必须设置。如果你在连接 Anthropic 时遇到验证错误，显式设置：

export COPILOT_PROVIDER_BASE_URL=https://api.anthropic.com
export COPILOT_MODEL=claude-sonnet-4-20250514
export COPILOT_PROVIDER_API_KEY=your-key-here

不设置 base URL 会触发验证错误，而且错误信息不够明确。文档和 CLI 行为不一致，直接设置就好。

测试

copilot

如果连接成功，Gemma 4 会开始响应。如果失败，按以下清单检查：Ollama 正在运行、模型名称与 ollama list 完全一致、COPILOT_PROVIDER_API_KEY 未设置。

最后一点特别注意：

unset COPILOT_PROVIDER_API_KEY

在本地模型和 GitHub 托管模型之间切换

这是让我最困惑的部分。截至本文撰写时（2026 年 4 月 8 日），Copilot CLI 内的 /model 选择器只显示 GitHub 托管的模型，比如 Claude、GPT-4o 等。本地 BYOK 模型不会出现在列表中。

BYOK 是会话级别的配置。你要么使用环境变量（本地/BYOK），要么使用 GitHub 托管模型。切换需要退出 Copilot 并使用不同的变量重新启动：

# 使用本地 Ollama
export COPILOT_PROVIDER_BASE_URL=http://localhost:11434
export COPILOT_MODEL=gemma4:31b
copilot

# 切换回 GitHub 托管模型（先退出 copilot）
unset COPILOT_PROVIDER_BASE_URL
unset COPILOT_MODEL
copilot

为了省事，我设置了 shell 别名：

alias copilot-local='COPILOT_PROVIDER_BASE_URL=http://localhost:11434 COPILOT_MODEL=gemma4:31b copilot'
alias copilot-github='copilot'

这能带来什么

你的算力，你的模型，你的掌控。

GitHub 的模型支持更新很快，但托管目录主要是通用模型。BYOK 适用于专业化场景。

如果你的组织已经在 Azure AI Foundry 上部署了模型，这是最自然的接入方式。在 Foundry 中部署模型（微调过的 GPT、Mistral、Llama，或你团队训练的领域专用模型），然后将 Copilot CLI 指向它：

export COPILOT_PROVIDER_BASE_URL=https://YOUR-RESOURCE-NAME.openai.azure.com/openai/deployments/YOUR-DEPLOYMENT-NAME
export COPILOT_PROVIDER_TYPE=azure
export COPILOT_PROVIDER_API_KEY=your-azure-api-key
export COPILOT_MODEL=YOUR-DEPLOYMENT-NAME

医疗、法律、金融团队在私有基础设施上运行微调模型：通过 BYOK 可以将这些模型接入 Copilot CLI 工作流，数据不会离开你的 Azure 租户。

同样的配置模式适用于任何兼容 OpenAI 的端点。OpenAI 直连、Mistral、Cohere、Together AI、自托管的微调模型，都是设置 COPILOT_PROVIDER_BASE_URL 和 COPILOT_MODEL。

# 示例：直连 OpenAI
export COPILOT_PROVIDER_BASE_URL=https://api.openai.com/v1
export COPILOT_PROVIDER_API_KEY=sk-your-key
export COPILOT_MODEL=gpt-4o

# 示例：通过 Mistral API
export COPILOT_PROVIDER_BASE_URL=https://api.mistral.ai
export COPILOT_MODEL=mistral-medium-latest
export COPILOT_PROVIDER_API_KEY=your-mistral-key

# 示例：自托管微调模型
export COPILOT_PROVIDER_BASE_URL=https://your-internal-endpoint
export COPILOT_MODEL=your-model-name
export COPILOT_PROVIDER_API_KEY=your-key-here

对于兼容的本地或自托管环境，BYOK 可以让 Copilot CLI 在不调用外部模型的情况下正常工作。如果你在隔离网络环境或离线状态下工作，这是纯云端工具无法替代的能力。

请始终在当前文档中确认各提供商的模型 ID。具体标识符因提供商和注册表而异。

本文由全球中文开发者社区翻译。如有表达不准确之处，欢迎通过 GitHub 仓库提交 PR 修正。