---
slug: "pi-provider-headers"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/MuJianxuan/pi-provider-headers@main/README.md"
repo: "https://github.com/MuJianxuan/pi-provider-headers"
source_file: "README.md"
branch: "main"
---
# pi-provider-headers

`pi-provider-headers` 是一个 Pi extension package。

它会按 `models.json` 中每个 provider 的 `api` 类型，自动注入默认 headers，模拟 codex CLI / claude code CLI 的请求特征。新增自定义 provider 时，不需要再手动为每个 provider 重复配置 headers。

## 工作原理

启动时读取 `~/.pi/agent/models.json` 与 `~/.pi/agent/provider-headers.json`，对每个 provider：

1. 取其 `api` 类型（provider 级优先，否则取第一个 model 级）。
2. 在配置 `rules` 中匹配 `api`，渲染 header 值（支持 `{var}` 模板）。
3. 与 `models.json` 里已有的 `headers` 合并（`models.json` 同名 header 优先）。
4. 调用 `pi.registerProvider(name, { baseUrl, apiKey, authHeader, headers })` 注入，并透传原有鉴权字段。

### 版本号解析

- `codexVersion`：默认自动读取本机 Codex CLI（`codex --version`，失败则查全局 `@openai/codex` package.json），探测失败回退到 `0.141.0`。
- `claudeCodeVersion`：默认自动读取本机 Claude Code（`claude --version`，失败则查全局 `@anthropic-ai/claude-code` package.json），探测失败回退到 `2.1.178`。
- 若在 `provider-headers.json` 的 `vars` 中显式写了同名变量，则优先生效（可强制覆盖）。

## 配置文件

`~/.pi/agent/provider-headers.json` 缺失时，会使用扩展内置默认配置：

```jsonc
{
  "debug": false,  // 是否开启调试日志，默认 false
  // vars 可选；显式版本会覆盖本机自动探测结果
  "vars": {
    // "codexVersion": "0.141.0",
    // "claudeCodeVersion": "2.1.178"
  },
  "rules": [
    {
      "name": "codex-cli",
      "api": ["openai-responses", "openai-codex-responses", "azure-openai-responses", "openai-completions"],
      "headers": {
        "User-Agent": "codex_cli_rs/{codexVersion}  ({osInfo}) Terminal",
        "originator": "codex_cli_rs",
        "version": "{codexVersion}"
      }
    },
    {
      "name": "claude-code",
      "api": ["anthropic-messages"],
      "headers": {
        "User-Agent": "{claudeCodeVersion} (Claude Code)",
        "anthropic-version": "2023-06-01",
        "anthropic-beta": "context-1m-2025-08-07"
      }
    }
  ]
}
```
## 安装

### 本地路径安装

```bash
pi install /absolute/path/to/pi-provider-headers
```

### npm 安装

正式发布到 npm 后可用：

```bash
pi install npm:pi-provider-headers
```

### 临时试用

```bash
pi -e ./pi-provider-headers
```

## 使用

安装后重新启动 Pi，或执行：

```text
/reload
```

启动后如果配置了 `debug: true`，会打印类似日志：

```text
[provider-headers] codexVersion=0.144.5 (source=local)
[provider-headers] claudeCodeVersion=2.1.190 (source=local)
[provider-headers] 已注入 headers：
```

如果有 provider 未命中规则，也会打印跳过列表。默认不打印日志，需要调试时请在配置文件中设置 `debug: true`。

## 生效与调试

- 若想让自动检测的 `osInfo` 真正生效，请删除 `models.json` 中各 provider 已手写的同名 `headers`。
- 这个包当前通过 `package.json` 里的 `pi.extensions` 暴露入口：`./index.ts`
- 修改代码后可用 `/reload` 热重载

## 开发

发布前检查：

```bash
npm test
npm run check:import
npm run pack:check
npm run prepublishOnly
```

更完整的首次发布步骤见：
- `.docs/first-npm-release.md`

## 作用范围

仅处理 `~/.pi/agent/models.json` 中显式声明的 provider。项目级 `.pi/models.json` 不处理。