本文说明如何在 VS Code 中通过 oai-compatible-copilot 扩展接入第三方 OpenAI-compatible 服务的 GPT reasoning 模型。

本文只讲 VS Code 界面操作，不讲命令行、不手动改扩展目录，尽量让第一次配置的人也能照着做。

示例扩展版本：oai-compatible-copilot 0.3.6。不同版本字段可能略有差异，请以实际扩展版本为准。

0. 先说结论：照着做可以得到什么

配置完成后，你应该能达到下面结果：

1. VS Code Copilot Chat 里能选择一个第三方 GPT reasoning 模型。
2. 请求会发到你的第三方 OpenAI-compatible 服务。
3. reasoning 档位可以按需配置，例如 medium、high、xhigh。
4. 本文示例选择 openai-responses 模式，让扩展调用 /v1/responses。
5. 如果出现 configure_python_environment 相关 400 错误，可以通过 VS Code 插件界面临时禁用 Python 扩展规避。

注意：reasoning 不等于只能走 Responses API。部分服务商或模型也可能在 Chat Completions 接口上支持 reasoning 参数。本文使用 Responses API，是因为 OpenAI 官方文档将 Responses API 作为新模型能力和工具调用的主要接口之一，同时 oai-compatible-copilot 也提供了 apiMode: "openai-responses" 这种配置方式。

1. 最快成功步骤

这一节先不解释太多原理，先按步骤配置成功。

第一步：确认扩展已安装

1. 打开 VS Code。
2. 看左侧边栏，点击“四个小方块”图标，这个是 Extensions 扩展面板。
3. 如果左侧没有这个图标，可以按 Ctrl + Shift + X 打开扩展面板。
4. 在扩展搜索框输入 oai-compatible-copilot。
5. 确认扩展已经安装并启用。
6. 如果没有安装，就点击 Install 安装。

第二步：打开正确的 settings.json

核心原则：配置要写到 oai-compatible-copilot 实际运行的那一侧。

本地 VS Code

如果你是在本机 VS Code 里直接使用扩展，按下面步骤打开配置文件：

1. 按 Ctrl + Shift + P。
2. VS Code 顶部会出现一个输入框，这个输入框叫“命令面板”。
3. 输入 Preferences: Open User Settings (JSON)。
4. 在搜索结果中选中这一项并回车。
5. VS Code 会打开 settings.json。

Remote-SSH / VS Code Server

如果你是通过 Remote-SSH 连接服务器，并且扩展安装在远程侧，要改的是远程配置：

1. 按 Ctrl + Shift + P。
2. VS Code 顶部会出现命令面板。
3. 输入 Preferences: Open Remote Settings (JSON)。
4. 在搜索结果中选中这一项并回车。
5. VS Code 会打开远程环境的 settings.json。

如果你不确定扩展运行在哪一侧：

1. 打开扩展面板。
2. 搜索 oai-compatible-copilot。
3. 看它显示在 Local 还是 Remote 分组。
4. 如果在 Local，改本地 User Settings。
5. 如果在 Remote，改 Remote Settings。

第三步：粘贴模型配置

在 settings.json 最外层 { ... } 里面加入下面配置。

如果你的 settings.json 里已经有其他配置，要注意 JSONC 格式：

• 每个配置项之间用英文逗号 , 分隔。
• 不要把配置粘到字符串里面。
• 不要多写或少写大括号。

示例配置：

{
    "oaicopilot.baseUrl": "https://your-api.example.com/v1",

    // 仅排查问题时临时打开；平时建议注释掉或使用默认日志级别。
    // "oaicopilot.logLevel": "debug",

    "oaicopilot.retry": {
        "enabled": true,
        "max_attempts": 3,
        "interval_ms": 1000,
        "status_codes": []
    },

    "oaicopilot.models": [
        {
            "id": "your-gpt-model-id",
            "displayName": "GPT reasoning xhigh",
            "configId": "xhigh",
            "owned_by": "openai",
            "context_length": 256000,
            // 按需要选择 reasoning 档位，例如 medium / high / xhigh。
            "reasoning_effort": "xhigh",
            "apiMode": "openai-responses"
        }
    ]
}

需要替换的地方：

占位符	替换成什么
https://your-api.example.com/v1	你的第三方 API base URL，通常只填到 /v1
your-gpt-model-id	服务商给你的模型 ID
displayName	VS Code 模型列表里显示的名字，可以自己起
configId	区分不同 reasoning 档位，例如 medium、high、xhigh
reasoning_effort	reasoning 档位，例如 medium、high、xhigh

如果你只需要中等推理强度，可以把示例改成：

"displayName": "GPT reasoning medium",
"configId": "medium",
"reasoning_effort": "medium"

第四步：保存 settings.json

1. 配置粘贴完成后，按 Ctrl + S 保存。
2. 如果 VS Code 提示 JSON 格式错误，先检查逗号和括号。
3. settings.json 是 JSONC，允许注释，所以示例里的 // 注释是可以存在的。

第五步：重新加载 VS Code 窗口

修改扩展配置后，建议重新加载窗口。

Developer: Reload Window 不是终端命令，不是在命令行里输入。它是 VS Code 命令面板里的命令。

操作步骤：

1. 回到 VS Code 主窗口。
2. 按 Ctrl + Shift + P。
3. 顶部出现命令面板。
4. 输入 Developer: Reload Window。
5. 在搜索结果中选中 Developer: Reload Window。
6. 按回车。
7. VS Code 窗口会刷新。

第六步：在 Copilot Chat 里选择模型并测试

1. 打开 VS Code 的 Copilot Chat 面板。
2. 找到模型选择入口。
3. 选择刚才配置的 displayName，例如 GPT reasoning xhigh。
4. 输入一句简单问题，例如：

你好，用一句话介绍你当前使用的模型配置。

如果能正常回答，说明基础配置已经成功。

2. 配置项解释

配置项	说明
oaicopilot.baseUrl	第三方 API base URL。一般只填到 /v1，不要手动拼 /responses
oaicopilot.logLevel	日志级别。只建议排查问题时临时设为 debug
id	服务商提供的模型 ID
displayName	VS Code 模型列表里显示的名字
configId	区分同一模型的不同配置，例如 medium、high、xhigh
context_length	模型上下文长度，按服务商能力填写
reasoning_effort	reasoning 强度，按服务商支持的值填写
apiMode	本文示例使用 openai-responses，表示走 Responses API

这里最容易混淆的是 baseUrl 和 apiMode：

• baseUrl 通常写到 /v1。
• apiMode: "openai-responses" 告诉扩展实际请求时使用 Responses API。
• 因此最终请求通常会变成 /v1/responses。

3. 关于 reasoning 与 Responses API 的严谨说明

不能简单说“reasoning 必须走 Responses API”。更严谨的说法是：

1. OpenAI API Reference 中，Chat Completions 接口也出现过 reasoning 相关参数，例如 reasoning_effort。
2. OpenAI API Reference 中，Responses 接口也支持 reasoning 配置。
3. OpenAI 官方文档中，Responses API 提供了 reasoning 配置，并覆盖新模型、工具调用等能力。
4. 第三方 OpenAI-compatible 服务是否支持 Chat Completions reasoning，要看服务商实现。
5. 本文选择 apiMode: "openai-responses"，是为了让 VS Code 扩展明确走 Responses API，并便于和 reasoning 配置配合。

所以本文结论是：

如果你使用 oai-compatible-copilot 接第三方 GPT reasoning 模型，推荐优先尝试 apiMode: "openai-responses"；但这不代表 Chat Completions 一定不能支持 reasoning。

4. 什么时候临时打开 debug 日志

平时不建议长期打开 debug 日志，因为日志可能比较大，也可能包含请求内容。

只有下面场景建议临时打开：

• 初次接入，想确认请求是否走 /v1/responses
• 模型不响应
• API 返回 400 / 429 / 5xx
• 想确认请求里是否带了 reasoning.effort
• 想排查 tools[x].parameters 这类 tool schema 错误

临时打开方式：

"oaicopilot.logLevel": "debug"

操作步骤：

1. 按前面的步骤打开 settings.json。
2. 找到最外层 { ... }。
3. 加入上面这一行。
4. 保存文件。
5. 按前文方法执行 Developer: Reload Window。
6. 复现问题并查看日志。
7. 抓到日志后，建议把这一行注释掉：

// "oaicopilot.logLevel": "debug"

5. 如何用 VS Code 界面查看日志

本文只讲 VS Code 界面操作，不讲命令行搜索。

打开日志文件

1. 在 VS Code 中按 Ctrl + O。
2. 会弹出打开文件窗口。
3. 找到日志目录。

常见日志目录：

环境	日志目录
Windows	C:\Users\<用户名>\.copilot\oaicopilot\logs\
Linux / macOS	~/.copilot/oaicopilot/logs/

4. 打开当天的日志文件，文件名通常类似：

oaicopilot-YYYYMMDD.log

在日志中搜索关键字

打开日志后：

1. 按 Ctrl + F。
2. 搜索 /responses。
3. 如果能搜到类似 /v1/responses，说明请求走了 Responses API。
4. 再搜索 reasoning。
5. 如果能看到 reasoning 或 reasoning_effort，说明 reasoning 配置被带入请求。
6. 如果遇到错误，搜索 request.error、Bad Request 或 invalid_function_parameters。

正常请求大致会包含类似信息：

{
  "url": "https://your-api.example.com/v1/responses",
  "requestBody": {
    "model": "your-gpt-model-id",
    "reasoning": {
      "effort": "xhigh"
    }
  }
}

判断标准：

• 看到 /v1/responses：说明使用了 Responses API。
• 看到 reasoning 或 reasoning.effort：说明 reasoning 配置被带上。
• 看到 /v1/chat/completions：说明当前配置没有走 Responses API，优先检查 apiMode。

6. 常见 400 错误：tool schema 校验失败

可能遇到这种错误：

Responses API error: [400] Bad Request
Invalid schema for function 'configure_python_environment': {} is not of type 'array'.
param: tools[36].parameters
code: invalid_function_parameters
URL: https://your-api.example.com/v1/responses

这个错误不是模型推理失败，也不是 Python 代码执行失败。

它表示：

请求发到 API 后，服务端在校验 tools 定义时失败，模型还没开始回答。

常见原因是：某些 VS Code 扩展向 Copilot/AI 暴露了工具，oai-compatible-copilot 把这些工具转换成 OpenAI-compatible API 的 tools 格式后，第三方 API 对 schema 校验不通过。

7. configure_python_environment 是什么

configure_python_environment 通常来自 Microsoft Python 扩展：

ms-python.python

它的用途是让 AI 在处理 Python 项目时配置 Python 环境，比如解释器、虚拟环境、依赖等。

当安装了 Python 扩展时，这个工具可能会被带进请求里。如果第三方 API 对 tool schema 校验比较严格，就可能出现：

invalid_function_parameters
tools[x].parameters

这类问题更像是组合兼容问题：

VS Code Python 扩展暴露的 AI tool
        +
oai-compatible-copilot 的 tool 转换
        +
第三方 API 的 schema 校验

8. 如何用 VS Code 界面检查 Python 扩展

1. 打开 VS Code。
2. 看左侧边栏，点击“四个小方块”图标，打开 Extensions 扩展面板。
3. 如果左侧没有图标，可以按 Ctrl + Shift + X。
4. 在搜索框输入 Python。
5. 找到 Microsoft 发布的 Python 扩展。
6. 点开扩展详情。
7. 确认扩展 ID 是：

ms-python.python

如果你使用 Remote-SSH，还要注意扩展是在本地还是远程环境中启用。扩展面板通常会区分 Local 和 Remote 分组。

9. 如何通过 VS Code 界面临时禁用 Python 扩展

如果当前项目不是 Python 项目，可以临时禁用 Python 扩展，避免它暴露的 AI tool 被带入请求。

操作步骤：

1. 打开 VS Code。
2. 点击左侧“四个小方块”图标，打开 Extensions 扩展面板。
3. 也可以按 Ctrl + Shift + X 打开扩展面板。
4. 在搜索框输入 Python。
5. 找到 Microsoft 发布的 Python 扩展。
6. 点击这个扩展，进入扩展详情页。
7. 点击 Disable。
8. 如果 VS Code 询问禁用范围，按实际情况选择：
   • 本地 VS Code：选择本地禁用。
   • Remote-SSH：选择远程环境禁用。
9. 按前文方法执行 Developer: Reload Window。
10. 重新打开 Copilot Chat 测试。

恢复也很简单：

1. 重新打开 Extensions 扩展面板。
2. 搜索 Python。
3. 进入 Microsoft Python 扩展详情页。
4. 点击 Enable。
5. 再执行一次 Developer: Reload Window。

10. 禁用 Python 扩展的副作用

会影响：

• Python 补全、跳转、类型检查
• Pylance
• Python 调试
• Python 测试发现和运行
• AI 自动配置 Python 环境

通常不影响：

• C / C++ / 嵌入式项目编辑
• SCons / Make / CMake 编译
• 终端手动运行 python / python3
• Copilot 普通聊天、读代码、改非 Python 代码

11. 最容易踩的坑

1. baseUrl 通常只填到 /v1，不要自己拼 /v1/responses。
2. apiMode: "openai-responses" 是本文推荐实践，不代表 Chat Completions 绝对不能做 reasoning。
3. reasoning_effort 是 reasoning 档位，不一定必须是 xhigh；按需求配置 medium、high、xhigh 等。
4. oaicopilot.logLevel: "debug" 不建议长期打开；只在接入或排障时临时开启。
5. settings.json 是 JSONC，可以有注释，但逗号和括号仍然要正确。
6. 如果出现 tools[x].parameters，优先怀疑 tool schema 兼容问题，不要先怀疑模型不可用。
7. Python 扩展可能会额外暴露 AI tools；非 Python 项目中可以通过 VS Code 插件界面临时禁用它来规避问题。