feat: add global and per-provider upstream proxy settings

docs/en/config-reference.md

@@ -60,6 +60,8 @@ providers:
 | `reactivate_after` | duration | `1h` | Auto-reactivation delay for temporarily deactivated providers; set `0` to disable temporary deactivation for auth, billing, and quota failures |
 | `upstream_idle_timeout` | duration | `3m` | Abort the current upstream attempt if no response body bytes arrive for too long |
 | `response_header_timeout` | duration | `2m` | Timeout while waiting for upstream response headers |
+| `upstream_proxy_mode` | string | `environment` | Default upstream proxy mode for providers that use `proxy_mode: default`; `environment` / `direct` / `custom` |
+| `upstream_proxy_url` | string | empty | Required when `upstream_proxy_mode: custom`; supports `http://`, `https://`, `socks5://`, and `socks5h://` proxy URLs |
 | `max_request_body_bytes` | int | `33554432` | Request body size limit, default 32 MiB |
 | `log_dir` | string | `<config-dir>/logs` | Log directory |
 | `log_retention_days` | int | `7` | Log retention days; `0` keeps logs forever; default is 7 days |
@@ -179,6 +181,8 @@ providers:
 | `base_url` | string | yes | Upstream API base URL |
 | `api_key` | string | one of two | Single API key |
 | `api_keys` | array | one of two | Multiple API keys, used in order |
+| `proxy_mode` | string | no | Upstream proxy mode for this provider; `default` follows the global default |
+| `proxy_url` | string | no | Required when `proxy_mode: custom`; supports `http://`, `https://`, `socks5://`, and `socks5h://` proxy URLs |
 | `priority` | int | no | Lower number = higher priority; omitted or `0` is treated as `1` |
 | `enabled` | bool | no | Defaults to `true` |
 | `model` | string | no | Force this provider to use a specific upstream model name for supported OpenAI and Claude requests |
@@ -189,6 +193,8 @@ providers:
 
 - Use `api_key` when you only have one key
 - Use `api_keys` when you want retries across multiple keys within the same provider
+- Use global `upstream_proxy_mode` / `upstream_proxy_url` to define the default proxy for providers that use `proxy_mode: default`
+- Use provider `proxy_mode: direct` to bypass both the global default proxy and environment proxy settings
 - Use `model` when different upstream providers expose the same family under different model IDs
 - Use `reasoning_effort` and `thinking_budget_tokens` only when you want Clipal to override the client-sent defaults for that provider
 - For long-running background setups, this is a good default:

docs/zh/config-reference.md

@@ -60,6 +60,8 @@ providers:
 | `reactivate_after` | duration | `1h` | provider 临时禁用后的自动恢复时间；设为 `0` 可禁用基于鉴权、计费、额度错误的临时禁用 |
 | `upstream_idle_timeout` | duration | `3m` | 上游响应 body 长时间无字节时中断当前尝试 |
 | `response_header_timeout` | duration | `2m` | 等待上游响应头的超时 |
+| `upstream_proxy_mode` | string | `environment` | 作为默认值应用到 `proxy_mode: default` 的 provider；可选 `environment` / `direct` / `custom` |
+| `upstream_proxy_url` | string | 空 | 当 `upstream_proxy_mode: custom` 时必填；支持 `http://`、`https://`、`socks5://` 和 `socks5h://` 代理 URL |
 | `max_request_body_bytes` | int | `33554432` | 请求体大小上限，默认 32 MiB |
 | `log_dir` | string | `<config-dir>/logs` | 日志目录 |
 | `log_retention_days` | int | `7` | 日志保留天数；`0` 表示永久保留；默认保留 7 天 |
@@ -179,6 +181,8 @@ providers:
 | `base_url` | string | 是 | 上游 API Base URL |
 | `api_key` | string | 二选一 | 单个 API Key |
 | `api_keys` | array | 二选一 | 多个 API Key，按顺序使用 |
+| `proxy_mode` | string | 否 | 该 provider 的上游代理模式；`default` 表示使用全局默认代理 |
+| `proxy_url` | string | 否 | 当 `proxy_mode: custom` 时必填；支持 `http://`、`https://`、`socks5://` 和 `socks5h://` 代理 URL |
 | `priority` | int | 否 | 数字越小优先级越高；省略或 `0` 时按 `1` 处理 |
 | `enabled` | bool | 否 | 是否启用，默认 `true` |
 | `model` | string | 否 | 对支持的 OpenAI / Claude 请求强制改写为这个上游模型名 |
@@ -189,6 +193,8 @@ providers:
 
 - 只有一个 key 时用 `api_key`
 - 需要同 provider 多 key 轮转时用 `api_keys`
+- 需要统一默认代理时，优先配置全局 `upstream_proxy_mode` / `upstream_proxy_url`，并让 provider 使用 `proxy_mode: default`
+- 需要让某个 provider 绕过全局默认代理和环境代理时，用 `proxy_mode: direct`
 - 不同上游对同一模型族使用不同模型 ID 时，可为该 provider 配置 `model`
 - 只有在你希望 Clipal 按 provider 覆盖客户端默认思考参数时，才配置 `reasoning_effort` 或 `thinking_budget_tokens`
 - 常驻后台运行时，建议：

internal/config/canon_edge_test.go

@@ -0,0 +1,17 @@
+package config
+
+import "testing"
+
+func TestXXXCanonTrailingSlash(t *testing.T) {
+	cases := []struct{ in, want string }{
+		{"http://proxy:8080/", "http://proxy:8080/"},
+		{"http://proxy:8080", "http://proxy:8080"},
+		{"http://user:pass@proxy:8080", "http://user:pass@proxy:8080"},
+		{"http://USER:PASS@PROXY:8080", "http://USER:PASS@proxy:8080"},
+		{"http://proxy:8080/path", "http://proxy:8080/path"},
+	}
+	for _, c := range cases {
+		got := CanonicalProxyURL(c.in)
+		t.Logf("CanonicalProxyURL(%q) = %q (want %q, match=%v)", c.in, got, c.want, got == c.want)
+	}
+}