@duanluan/openai-local-bridge 0.2.3

package/README.md

@@ -0,0 +1,269 @@
+# openai-local-bridge
+
+[中文说明](./README_CN.md)
+
+`openai-local-bridge` routes local `api.openai.com` requests to a third-party OpenAI-compatible endpoint, allowing tools such as Trae and AI Assistant to use GPT Codex through a non-OpenAI API.
+
+## Prerequisites
+
+- `Git`
+- `Python`
+- `uv`: optional, but recommended. When available, the npm launcher prefers it so the latest CLI can be run directly.
+- `OpenSSL`: required when running `olb enable` or `olb start` to generate local certificates. On Windows, install [OpenSSL](https://slproweb.com/products/Win32OpenSSL.html) first and make sure the directory containing `openssl.exe` is in `PATH`.
+
+Check your environment:
+
+```bash
+git --version
+python --version
+openssl version
+```
+
+## Installation
+
+If you want a standalone binary with the Python runtime bundled, download the platform archive from GitHub Releases. Those archives do not require `Python` or `uv`; only `OpenSSL` is still needed for `olb enable` / `olb start`.
+
+### Method 1: `uv`
+
+```bash
+uv tool install openai-local-bridge
+```
+
+### Method 2: `pip`
+
+```bash
+python -m pip install --user openai-local-bridge
+```
+
+### Method 3: `npm`
+
+```bash
+npm install -g @duanluan/openai-local-bridge
+```
+
+The npm package downloads the matching standalone binary from GitHub Releases during installation, so runtime use does not require `Python` or `uv`.
+
+### Method 4: `curl` / PowerShell
+
+Linux / macOS:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/duanluan/openai-local-bridge/main/install.sh | bash
+```
+
+Windows PowerShell:
+
+```powershell
+irm https://raw.githubusercontent.com/duanluan/openai-local-bridge/main/install.ps1 | iex
+```
+
+### Method 5: standalone binary
+
+Download the matching archive from GitHub Releases, then unpack and run `olb` directly:
+
+- `olb-linux-x86_64.tar.gz`
+- `olb-macos-x86_64.tar.gz`
+- `olb-macos-arm64.tar.gz`
+- `olb-windows-x86_64.zip`
+
+## Quick Start
+
+The most direct way to use it is:
+
+```bash
+olb start
+```
+
+Run it in the background:
+
+```bash
+olb start --background
+```
+
+If the machine has not been configured yet, `olb start` first runs initialization, then continues with enablement and startup. In interactive mode, it asks for:
+
+- `Base URL`
+- `API Key`
+- `Reasoning effort`
+
+If you only want to update the configuration, run:
+
+```bash
+olb init
+```
+
+To stop the takeover:
+
+```bash
+olb disable
+```
+
+To stop a running bridge process:
+
+```bash
+olb stop
+```
+
+## Common Commands
+
+Command overview:
+
+- `olb`: runs initialization when no config exists; otherwise shows the current status
+- `init`: initial setup or reconfiguration
+- `config`: show the current configuration
+- `config-path`: show the configuration file path
+- `status`: show the current status
+- `enable`: install certificates, update hosts, and manage NSS on supported platforms
+- `disable`: remove the hosts takeover
+- `start`: if not initialized, run setup first, then execute `enable` and start the bridge immediately
+- `start --background`: start the bridge in the background and write logs to the config directory
+- `stop`: stop the current bridge process, including one started in the background
+
+## Wrapper Script Entry Points
+
+If you are running directly from the repository, you can also use:
+
+### Linux / macOS
+
+```bash
+./openai-local-bridge.sh <command>
+```
+
+### Windows PowerShell
+
+```powershell
+.\openai-local-bridge.ps1 <command>
+```
+
+### Windows BAT
+
+```bat
+openai-local-bridge.bat <command>
+```
+
+All of these entry points forward to the same CLI.
+
+If you install through npm, `olb` starts the bundled platform binary directly. Supported npm targets are Linux x64, macOS x64, macOS arm64, and Windows x64.
+
+## Release
+
+The release workflow lives in [.github/workflows/release-binaries.yml](/home/duanluan/workspaces/my/projects/openai-local-bridge/.github/workflows/release-binaries.yml).
+
+Before pushing a release tag:
+
+- set matching versions in `pyproject.toml` and `package.json`
+- configure GitHub secrets `PYPI_API_TOKEN` and `NPM_TOKEN`
+- push a tag such as `v0.2.2`
+
+When the workflow runs on that tag, it:
+
+- builds standalone binaries for Linux x64, macOS x64, macOS arm64, and Windows x64
+- uploads those binaries to GitHub Releases
+- publishes the Python package to PyPI
+- publishes the root npm package; the npm installer downloads the matching binary from GitHub Releases
+
+If npm publishing fails but the tag and GitHub Release already exist, use the workflow's `Run workflow` button and pass the existing tag such as `v0.2.3` to retry npm publishing without creating a new version.
+
+## Using It in a Client
+
+Using Trae as an example, the recommended flow is split into two phases.
+
+### Phase 1: Add the model in the client first
+
+1. Keep this project disabled:
+
+   ```bash
+   olb disable
+   ```
+
+2. Confirm that the machine can reach the official OpenAI service.
+3. Add the model in the client, for example:
+   - Provider: `OpenAI`
+   - Model: `Custom model`
+   - Model ID: `gpt-5.4`
+   - API Key: your official OpenAI key
+
+### Phase 2: Enable the bridge for subsequent requests
+
+```bash
+olb start
+```
+
+Then choose the model you just added in the client.
+
+## FAQ
+
+### What does `olb` do by default?
+
+- If no configuration file exists, it starts initialization.
+- If configuration is already complete, it shows the current status.
+
+### What can I check with `olb status`?
+
+These fields are usually the most important:
+
+- `hosts`: whether takeover is active
+- `root_ca`: whether the root certificate exists
+- `nss`: NSS status
+- `listener`: whether the local listener is running
+- `listen_addr`: listening address
+- `config`: configuration file location
+
+### Other software is affected too
+
+That is expected with the current approach, because the takeover happens at the system level for `api.openai.com`.
+
+Restore normal behavior immediately:
+
+```bash
+olb disable
+```
+
+### Model requests fail
+
+Check these items first:
+
+- Whether `Base URL` is correct
+- Whether `API Key` is correct
+- Whether the upstream service is OpenAI-compatible
+- Whether the upstream model you configured actually exists
+
+### Failed to modify `hosts` or import certificates on Windows
+
+This is usually a permission issue. Run the command again in a terminal with sufficient privileges.
+
+### Windows says `missing command: openssl`
+
+The current implementation requires OpenSSL to be installed locally. Install OpenSSL first, then confirm that this works in your terminal:
+
+```powershell
+openssl version
+```
+
+### Startup fails on Linux / macOS
+
+If you use the default port `443`, the system may require elevated privileges. Follow the prompt, or switch to a higher port.
+
+## Configuration File
+
+The CLI writes its configuration to a file under your user configuration directory.
+
+View the path:
+
+```bash
+olb config-path
+```
+
+View the current configuration:
+
+```bash
+olb config
+```
+
+## Security Notes
+
+Before using this project, keep in mind:
+
+- It installs a local certificate on your machine.
+- It modifies the system `hosts` file.
+- Run `olb disable` when you are not using it.

package/README_CN.md

@@ -0,0 +1,269 @@
+# openai-local-bridge
+
+[English README](./README.md)
+
+`openai-local-bridge` 用于在本机将 `api.openai.com` 请求桥接到第三方 OpenAI-compatible 接口，以实现 Trae、AI Assistant 中 GPT Codex 使用第三方 API。
+
+## 前置环境
+
+- `Git`
+- `Python`
+- `uv`：可选，但推荐。有它时 `npm` 启动器会优先直接运行最新 CLI。
+- `OpenSSL`：执行 `olb enable` 或 `olb start` 时需要它来生成本地证书。Windows 请先安装 [OpenSSL](https://slproweb.com/products/Win32OpenSSL.html)，并确认 `openssl.exe` 所在目录已加入 `PATH`。
+
+检查环境：
+
+```bash
+git --version
+python --version
+openssl version
+```
+
+## 安装
+
+如果想直接使用自带 Python 运行时的独立二进制包，可以从 GitHub Releases 下载对应平台压缩包。此方式不再依赖本机 `Python` 或 `uv`，但执行 `olb enable` / `olb start` 仍然需要 `OpenSSL`。
+
+### 方式 1：`uv`
+
+```bash
+uv tool install openai-local-bridge
+```
+
+### 方式 2：`pip`
+
+```bash
+python -m pip install --user openai-local-bridge
+```
+
+### 方式 3：`npm`
+
+```bash
+npm install -g @duanluan/openai-local-bridge
+```
+
+npm 包会在安装阶段从 GitHub Releases 下载当前平台对应的独立二进制文件，所以运行时不再依赖 `Python` 或 `uv`。
+
+### 方式 4：`curl` / PowerShell
+
+Linux / macOS：
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/duanluan/openai-local-bridge/main/install.sh | bash
+```
+
+Windows PowerShell：
+
+```powershell
+irm https://raw.githubusercontent.com/duanluan/openai-local-bridge/main/install.ps1 | iex
+```
+
+### 方式 5：独立二进制包
+
+从 GitHub Releases 下载对应平台压缩包，解压后直接运行 `olb`：
+
+- `olb-linux-x86_64.tar.gz`
+- `olb-macos-x86_64.tar.gz`
+- `olb-macos-arm64.tar.gz`
+- `olb-windows-x86_64.zip`
+
+## 快速开始
+
+最直接的用法就是：
+
+```bash
+olb start
+```
+
+后台启动：
+
+```bash
+olb start --background
+```
+
+如果本机还没有配置，`olb start` 会先进入初始化，再继续执行启用和启动；交互式会采集：
+
+- `Base URL`
+- `API Key`
+- `推理强度`
+
+如果你只想单独修改配置，可以执行：
+
+```bash
+olb init
+```
+
+关闭接管：
+
+```bash
+olb disable
+```
+
+关闭当前运行中的 bridge：
+
+```bash
+olb stop
+```
+
+## 常用命令
+
+命令说明：
+
+- `olb`：未配置时进入初始化，已配置时显示状态
+- `init`：首次初始化或重新配置
+- `config`：查看当前配置
+- `config-path`：查看配置文件路径
+- `status`：查看当前状态
+- `enable`：安装证书、处理 hosts，并在支持的平台上处理 NSS
+- `disable`：取消 hosts 接管
+- `start`：未初始化时先进入初始化，然后执行 `enable` 并直接启动 bridge
+- `start --background`：以后台模式启动 bridge，并将日志写到配置目录
+- `stop`：停止当前 bridge 进程，包括后台运行中的实例
+
+## 包装脚本入口
+
+如果你是在仓库目录里直接使用，也可以：
+
+### Linux / macOS
+
+```bash
+./openai-local-bridge.sh <command>
+```
+
+### Windows PowerShell
+
+```powershell
+.\openai-local-bridge.ps1 <command>
+```
+
+### Windows BAT
+
+```bat
+openai-local-bridge.bat <command>
+```
+
+这些入口最终都会转发到同一个 CLI。
+
+如果通过 npm 安装，`olb` 会直接启动当前平台对应的内置二进制文件。当前支持 Linux x64、macOS x64、macOS arm64、Windows x64。
+
+## 发布
+
+发布工作流位于 [release-binaries.yml](/home/duanluan/workspaces/my/projects/openai-local-bridge/.github/workflows/release-binaries.yml)。
+
+推送发布 tag 前需要：
+
+- 在 `pyproject.toml` 和 `package.json` 中写入相同版本号
+- 在 GitHub Secrets 中配置 `PYPI_API_TOKEN` 和 `NPM_TOKEN`
+- 推送类似 `v0.2.2` 的 tag
+
+该工作流会：
+
+- 构建 Linux x64、macOS x64、macOS arm64、Windows x64 的独立二进制文件
+- 上传到 GitHub Releases
+- 发布 Python 包到 PyPI
+- 发布 npm 主包；npm 安装阶段会再从 GitHub Releases 下载对应平台的二进制文件
+
+如果 npm 发布失败，但 tag 和 GitHub Release 已经存在，可以在 Actions 页面使用 `Run workflow`，传入已有 tag（例如 `v0.2.3`）单独重试 npm 发布，而不需要再增加版本号。
+
+## 在客户端中使用
+
+以 Trae 为例，建议分两个阶段：
+
+### 阶段 1：先在客户端里完成模型添加
+
+1. 保持本项目未接管，执行：
+
+   ```bash
+   olb disable
+   ```
+
+2. 确认当前机器可以正常访问官方 OpenAI。
+3. 在客户端中添加模型，例如：
+   - 服务商：`OpenAI`
+   - 模型：`自定义模型`
+   - 模型 ID：`gpt-5.4`
+   - API Key：官方 OpenAI Key
+
+### 阶段 2：再启用 bridge 接管后续请求
+
+```bash
+olb start
+```
+
+然后在客户端中选择你刚才添加的模型即可。
+
+## 常见问题
+
+### `olb` 默认会做什么
+
+- 如果还没有配置文件：进入初始化
+- 如果已经配置完成：显示当前状态
+
+### `olb status` 可以看什么
+
+通常重点关注这些字段：
+
+- `hosts`：是否已接管
+- `root_ca`：根证书是否存在
+- `nss`：NSS 状态
+- `listener`：本地监听是否已启动
+- `listen_addr`：监听地址
+- `config`：配置文件位置
+
+### 其他软件也被影响了
+
+这是当前方案的正常表现，因为接管的是系统级 `api.openai.com`。
+
+立即恢复：
+
+```bash
+olb disable
+```
+
+### 模型调用失败
+
+优先检查：
+
+- `Base URL` 是否正确
+- `API Key` 是否正确
+- 上游是否兼容 OpenAI 接口
+- 你配置的上游模型是否真实存在
+
+### Windows 写 hosts 或导入证书失败
+
+通常是权限不足。请使用有足够权限的终端再执行。
+
+### Windows 提示 `missing command: openssl`
+
+当前实现要求本机已安装 OpenSSL。请先安装 OpenSSL，并确认终端里可以直接执行：
+
+```powershell
+openssl version
+```
+
+### Linux / macOS 启动失败
+
+如果你使用默认 `443` 端口，系统可能要求更高权限。可直接按提示执行，或改用更高端口。
+
+## 配置文件
+
+CLI 会把配置写到用户目录下的配置文件中。
+
+查看路径：
+
+```bash
+olb config-path
+```
+
+查看当前配置：
+
+```bash
+olb config
+```
+
+## 安全提示
+
+使用前请注意：
+
+- 本项目会在本机安装本地证书
+- 本项目会修改系统 hosts
+- 不使用时建议执行 `olb disable`

package/npm/install.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+
+const fs = require('node:fs');
+const fsp = require('node:fs/promises');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+
+const packageRoot = path.resolve(__dirname, '..');
+const packageJson = require('../package.json');
+const platformPackages = require('./platforms.json');
+
+function platformKey(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`;
+}
+
+function packageSpecFor(platform = process.platform, arch = process.arch) {
+  const spec = platformPackages[platformKey(platform, arch)];
+  if (!spec) {
+    throw new Error(`unsupported platform: ${platform}/${arch}`);
+  }
+  return spec;
+}
+
+function downloadUrl(version = packageJson.version, platform = process.platform, arch = process.arch) {
+  const spec = packageSpecFor(platform, arch);
+  return `https://github.com/duanluan/openai-local-bridge/releases/download/v${version}/${spec.releaseAsset}`;
+}
+
+function downloadFile(url, destination) {
+  return new Promise((resolve, reject) => {
+    const request = https.get(
+      url,
+      {
+        headers: {
+          'User-Agent': 'openai-local-bridge-npm-installer',
+        },
+      },
+      (response) => {
+        if (response.statusCode && response.statusCode >= 300 && response.statusCode < 400 && response.headers.location) {
+          response.resume();
+          downloadFile(response.headers.location, destination).then(resolve, reject);
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(new Error(`download failed: ${url} (${response.statusCode})`));
+          return;
+        }
+
+        const file = fs.createWriteStream(destination, { mode: 0o755 });
+        response.pipe(file);
+        file.on('finish', () => file.close(resolve));
+        file.on('error', reject);
+      },
+    );
+    request.on('error', reject);
+  });
+}
+
+async function installBinary() {
+  const spec = packageSpecFor();
+  const binaryPath = path.join(__dirname, spec.binaryPath);
+  const tempPath = path.join(os.tmpdir(), `${spec.releaseAsset}-${process.pid}`);
+
+  await fsp.mkdir(path.dirname(binaryPath), { recursive: true });
+  await downloadFile(downloadUrl(), tempPath);
+  await fsp.rename(tempPath, binaryPath);
+
+  if (process.platform !== 'win32') {
+    await fsp.chmod(binaryPath, 0o755);
+  }
+}
+
+async function main() {
+  if (process.env.OLB_SKIP_BINARY_DOWNLOAD === '1') {
+    return;
+  }
+  await installBinary();
+}
+
+module.exports = {
+  downloadUrl,
+  installBinary,
+  main,
+  packageSpecFor,
+  platformKey,
+};
+
+if (require.main === module) {
+  main().catch((error) => {
+    console.error(error.message || String(error));
+    process.exit(1);
+  });
+}

package/npm/olb.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+const { spawnSync } = require('node:child_process');
+const { existsSync } = require('node:fs');
+const path = require('node:path');
+
+const packageRoot = path.resolve(__dirname, '..');
+const platformPackages = require('./platforms.json');
+
+function platformKey(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`;
+}
+
+function packageSpecFor(platform = process.platform, arch = process.arch) {
+  const spec = platformPackages[platformKey(platform, arch)];
+  if (!spec) {
+    throw new Error(`unsupported platform: ${platform}/${arch}`);
+  }
+  return spec;
+}
+
+function resolveBinaryPath(options = {}) {
+  const override = options.binaryPath || process.env.OLB_BINARY_PATH;
+  if (override) {
+    return override;
+  }
+
+  const spec = packageSpecFor(options.platform, options.arch);
+  const binaryPath = path.join(packageRoot, 'npm', spec.binaryPath);
+  if (!existsSync(binaryPath)) {
+    throw new Error(`missing binary: ${binaryPath}; rerun npm install openai-local-bridge`);
+  }
+  return binaryPath;
+}
+
+function runBinary(binaryPath, args = process.argv.slice(2)) {
+  const result = spawnSync(binaryPath, args, { stdio: 'inherit' });
+  if (result.error) {
+    throw result.error;
+  }
+  return result.status ?? 1;
+}
+
+function main(args = process.argv.slice(2)) {
+  try {
+    const binaryPath = resolveBinaryPath();
+    process.exit(runBinary(binaryPath, args));
+  } catch (error) {
+    console.error(error.message || String(error));
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  packageSpecFor,
+  platformKey,
+  resolveBinaryPath,
+  runBinary,
+};
+
+if (require.main === module) {
+  main();
+}

package/npm/platforms.json

@@ -0,0 +1,26 @@
+{
+  "darwin-arm64": {
+    "releaseAsset": "olb-macos-arm64",
+    "binaryPath": "bin/olb",
+    "os": "darwin",
+    "cpu": "arm64"
+  },
+  "darwin-x64": {
+    "releaseAsset": "olb-macos-x86_64",
+    "binaryPath": "bin/olb",
+    "os": "darwin",
+    "cpu": "x64"
+  },
+  "linux-x64": {
+    "releaseAsset": "olb-linux-x86_64",
+    "binaryPath": "bin/olb",
+    "os": "linux",
+    "cpu": "x64"
+  },
+  "win32-x64": {
+    "releaseAsset": "olb-windows-x86_64.exe",
+    "binaryPath": "bin/olb.exe",
+    "os": "win32",
+    "cpu": "x64"
+  }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@duanluan/openai-local-bridge",
+  "version": "0.2.3",
+  "description": "Standalone npm launcher for openai-local-bridge",
+  "bin": {
+    "olb": "npm/olb.js"
+  },
+  "scripts": {
+    "postinstall": "node npm/install.js"
+  },
+  "files": [
+    "npm/install.js",
+    "npm/olb.js",
+    "npm/platforms.json",
+    "README.md",
+    "README_CN.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/duanluan/openai-local-bridge.git"
+  },
+  "homepage": "https://github.com/duanluan/openai-local-bridge",
+  "bugs": {
+    "url": "https://github.com/duanluan/openai-local-bridge/issues"
+  },
+  "keywords": [
+    "github",
+    "launcher",
+    "openai",
+    "bridge",
+    "cli",
+    "binary"
+  ],
+  "license": "UNLICENSED"
+}