opencode-api-proxy-manager

简介 / Overview

中文简介

一个用于 OpenCode 的 API 代理管理插件，支持按配置文件切换代理、按域名规则路由请求，并通过本地 HTTP/HTTPS 代理统一接管 OpenCode 与 shell 命令的网络访问。适合在需要精细控制 OpenAI、OpenRouter、MCP 服务或其他 API 提供商访问路径的环境中使用。

English Overview

An OpenCode plugin for profile-based API proxy management. It supports proxy profile switching, hostname-based routing rules, and a local HTTP/HTTPS proxy that applies proxy settings to OpenCode and shell commands. It is useful when you need precise control over network access for OpenAI, OpenRouter, MCP services, or other API providers.

GitHub About / 仓库简介

中文：OpenCode API 代理管理插件，支持代理配置文件、域名规则路由、本地 HTTP/HTTPS 代理和凭据脱敏输出。

English: OpenCode API proxy manager with proxy profiles, hostname routing rules, a local HTTP/HTTPS proxy, and redacted credential output.

功能特性 / Features

• 支持多个代理配置文件，可在直连和不同上游代理之间切换。

• 支持按主机名、通配符、正则和 IPv4 CIDR 配置路由规则。

• 启动仅监听 127.0.0.1 的本地 HTTP/HTTPS 代理。

• 自动向 OpenCode 进程和 shell 命令注入 HTTP_PROXY / HTTPS_PROXY。

• 代理账号密码从环境变量读取，不写入配置文件。

• 工具输出中的代理凭据会自动脱敏。

• Supports multiple proxy profiles and switching between direct mode and upstream proxies.

• Supports routing rules based on exact hostnames, wildcards, regex patterns, and IPv4 CIDR ranges.

• Starts a local HTTP/HTTPS proxy bound to 127.0.0.1 only.

• Injects HTTP_PROXY / HTTPS_PROXY into OpenCode and shell command environments.

• Reads proxy credentials from environment variables instead of config files.

• Redacts proxy credentials from tool output.

安装 / Install

方式 A：npm pack / Option A: npm pack

将 opencode-api-proxy-manager-1.0.0.tgz 复制到目标机器，然后运行：

Copy opencode-api-proxy-manager-1.0.0.tgz to the target machine, then run:

npm install -g ./opencode-api-proxy-manager-1.0.0.tgz

在 opencode.json 中启用插件：

Enable the plugin in opencode.json:

{ "plugin": ["opencode-api-proxy-manager"] }

方式 B：本地插件 / Option B: local plugin

将 .opencode/plugins/api-proxy-manager/ 复制到目标机器的相同位置。

Copy .opencode/plugins/api-proxy-manager/ to the same location on the target machine.

配置 / Configuration

创建 .opencode/api-proxy-config.json。

Create .opencode/api-proxy-config.json.

{
  "activeProfile": "local",
  "debug": false,

  // -1 = disabled, 0 = auto, >0 = fixed.
  // The local proxy listens on 127.0.0.1 only.
  "localPort": 7899,

  "profiles": {
    "local": {
      "type": "http",
      "host": "127.0.0.1",
      "port": 7897,

      // Optional: read credentials from environment variables.
      // Do not hardcode proxy credentials in this config file.
      "auth": {
        "usernameEnv": "PROXY_USER",
        "passwordEnv": "PROXY_PASS"
      }
    },
    "direct": {
      "type": "direct"
    }
  },

  "rules": [
    { "pattern": "localhost|127.0.0.1|::1|[::1]", "action": { "type": "direct" } },
    { "pattern": "*.local", "action": { "type": "direct" } },
    { "pattern": "192.168.*|10.*", "action": { "type": "direct" } },

    { "pattern": "api.openai.com", "action": { "type": "proxy", "profile": "local" } },
    { "pattern": "openrouter.ai|*.openrouter.ai", "action": { "type": "proxy", "profile": "local" } },
    { "pattern": "context7.com|*.context7.com", "action": { "type": "proxy", "profile": "local" } },

    { "pattern": "*", "action": { "type": "direct" } }
  ],

  "noProxyExtra": [".local", ".internal"]
}

规则语法 / Pattern Syntax

Pattern	匹配说明 / Match
api.openai.com	精确主机名 / Exact hostname
*.context7.com	通配符子域名，例如 x.context7.com / Wildcard subdomain, such as x.context7.com
host1|host2|*.example.com	多个 OR 规则 / Multiple OR patterns
~^api\..*\.com$	以 ~ 开头的正则 / Regex prefixed with ~
10.0.0.0/8	IPv4 CIDR 范围 / IPv4 CIDR range

架构 / Architecture

OpenCode process and shell commands
       |
       v
HTTP_PROXY / HTTPS_PROXY = http://127.0.0.1:{localPort}
       |
       v
local proxy
       |
       +-- DIRECT: raw TCP / fetch()
       |
       +-- PROXY: upstream proxy via CONNECT tunnel / HTTP forward

中文说明：插件启动一个本地代理，并将 OpenCode 进程和 shell 命令的代理环境变量指向它。本地代理根据规则决定请求直连还是转发到上游代理。

English explanation: The plugin starts a local proxy and points OpenCode and shell command proxy environment variables to it. The local proxy uses routing rules to decide whether each request should go direct or through an upstream proxy.

自定义工具 / Custom Tools

Tool	说明 / Description
proxy_status	显示当前代理状态、活动配置文件和规则 / Show current proxy status, active profile, and rules
proxy_switch	切换活动代理配置文件 / Switch the active proxy profile
proxy_profiles	列出所有代理配置文件 / List all available proxy profiles
proxy_rules	按顺序列出路由规则 / List routing rules in order
proxy_test	测试到指定提供商的连通性 / Test connectivity to a provider

TUI 命令 / TUI Command

/proxy 用于显示当前代理状态。

/proxy shows the current proxy status.

环境变量 / Environment Variables

代理凭据从环境变量读取，并会在状态输出中自动脱敏。

Proxy credentials are read from environment variables and are redacted from status output.

export PROXY_USER=your-user
export PROXY_PASS=your-password

安全说明 / Security Notes

• 本地代理只绑定到 127.0.0.1。

• 如果 .opencode/api-proxy-config.json 包含内部代理地址或敏感路由规则，不要提交到公开仓库。

• 代理凭据应通过环境变量提供，不应写入配置文件。

• 工具输出会对代理 URL 中的凭据进行脱敏。

• The local proxy binds to 127.0.0.1 only.

• Do not commit .opencode/api-proxy-config.json if it contains internal proxy hosts or sensitive routing rules.

• Proxy credentials should be provided through environment variables, not config files.

• Tool output redacts credentials in proxy URLs.

限制 / Limitations

• 当前仅处理 HTTP 和 HTTPS。

• 尚未实现 SOCKS5 上游代理支持。

• HTTPS 请求使用 CONNECT 隧道。明文 HTTP 转发能力较基础，不会保留任意请求头或请求体；建议优先使用 HTTPS API 端点。

• The local proxy handles HTTP and HTTPS only.

• SOCKS5 upstream support is not yet implemented.

• HTTPS traffic uses CONNECT tunneling. Plain HTTP forwarding is basic and does not preserve arbitrary request headers or bodies; prefer HTTPS API endpoints.