Academic Research Skills 接入OpenAI兼容接口的密钥与路由配置

如果你正在使用 Academic Research Skills 这类研究工具，又希望把默认模型服务替换成自己可用的 OpenAI 兼容接口，核心要处理的只有三件事：找到配置里写死的基础地址和密钥、确认请求路径是否能被目标接口接受、在启动前用 curl 验证连通。整个过程不需要改动工具的业务逻辑，通常在半小时内可以完成排查。

可行思路：修改 base_url 与 api_key 后，先 curl 接口验证模型可用性，再启动 Agent 并从日志确认实际请求地址。由于不同工具的配置格式、默认路径和网络环境可能不同，任何改动后都必须做一次最小化请求测试，避免只改配置不验证。

在配置文件中定位base_url与api_key字段

大多数 Academic Research Skills 的插件或本地服务端会使用 .yaml、.env 或 .json 保存模型接入信息。常见字段名包括 base_url、api_base、openai_base_url，以及 api_key。你需要先找到这些字段的实际位置，而不是在 UI 里盲目修改。

# 在项目目录下递归查找包含 base_url 的配置文件
grep -r "base_url" `--include`="*.yaml" `--include`="*.yml" `--include`="*.env" .

# 如果使用 .env 文件，直接查看文件内容
cat .env | grep -i "base\|key"

如果工具是用 Python 写的，也可以检查是否在代码里硬编码了 api_base。找到配置项后，先记录原始值，方便回滚。

修改环境变量或配置文件中的模型服务地址

将默认的 OpenAI 官方地址替换成你自己的兼容接口地址。通常只需要修改两个值：BASE_URL 和 API_KEY。以下是一个 .env 文件的示例：

BASE_URL=https://your-endpoint.example.com/v1
API_KEY=sk-your-actual-key-here
MODEL_NAME=your-model-name

如果你使用 shell 环境变量，可以这样导出：

Academic Research Skills 接入OpenAI兼容接口的密钥与路由配置

export BASE_URL="https://your-endpoint.example.com/v1"
export API_KEY="sk-your-actual-key-here"

这里有一个关键边界：BASE_URL 需要包含到 /v1 路径为止，后面的 /chat/completions 由工具自动拼接。部分接口商希望使用自定义路径，则需要看工具是否支持把完整 URL 写入 base_url。另外，不要把真实密钥写进会提交到 Git 的文件，建议用 .env.local 或单独的环境变量文件，并检查 .gitignore。

确认路由代理是否需要对特定路径重写

很多 OpenAI 兼容接口会要求路径严格匹配 /v1/chat/completions，但某些网关或自建代理的路径可能带前缀，例如 /api/openai/v1/chat/completions。如果工具请求的是 /v1/chat/completions，而后端实际路径不同，就会返回 404 或提示模型不存在。

先看日志中的请求 URI。以 Nginx 反向代理为例，日志里会记录完整的请求地址：

tail -f /var/log/nginx/access.log | grep "chat/completions"

如果发现路径不匹配，可以在反向代理层重写路径。例如把 /v1 前缀转发到后端 /some/internal/v1：

location /v1/ {
    rewrite ^/v1/(.*)$ /internal/v1/$1 break;
    proxy_pass http://backend-endpoint;
}

重写路径后，需要再次用 curl 测试，确认请求能够到达正确的路由。注意：有些工具会在启动时读取环境变量，改动代理配置后需要重启工具进程才能生效。

用curl测试接口连通性并观察返回

在启动 Agent 之前，先用 curl 独立验证接口是否可用。下面的命令是一个通用骨架，把 YOUR_BASE_URL、YOUR_API_KEY 和 YOUR_MODEL_NAME 替换成实际值即可：

curl -X POST "${BASE_URL}/chat/completions" \
  -H "Authorization: Bearer ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "YOUR_MODEL_NAME",
    "messages": [{"role": "user", "content": "ping"}],
    "max_tokens": 10
  }'

成功返回的 JSON 结构通常包含 id、object、choices 和 usage 几个字段。其中 choices[0].message.content 是模型回复，usage.total_tokens 表示消耗的 token 数。如果返回的是 404，先检查路径；如果是 401，检查密钥；如果是模型不存在，检查模型名是否与接口商提供的完全一致。

启动Agent后从日志验证请求去向

curl 成功不代表 Agent 一定会走同一个地址。启动 Agent 后，需要观察日志确认请求确实发到了预期 base_url。通常可以同时跟踪工具日志和代理日志：

# 跟踪 Agent 日志
tail -f ~/.agent/logs/app.log

# 如果使用了反向代理，同时跟踪代理访问日志
tail -f /var/log/nginx/access.log

在日志中搜索 chat/completions，并确认请求的 Host 头、路径和你配置的 BASE_URL 一致。如果日志只显示 ip 地址或短路径，可以查看请求体的模型名是否与你配置的 MODEL_NAME 相同。如果发现仍有请求发往默认官方地址，说明配置可能没被加载，检查环境变量是否泄漏到子进程，或工具是否使用了缓存配置。

最后建议保留一次 curl 测试脚本，并在后续更换模型或调整网络环境时重复执行。配置接入的本质是让工具发出的请求与你选定的接口在地址、路径、密钥和模型名四个维度上完全匹配，任何一项不一致都会导致连通失败。