# How to Configure OpenMAIC for China and Slow Network Environments: Complete Setup Guide

> Configure OpenMAIC for China and slow networks. Learn to set AI providers, proxyFetch, MAX_PROXY_BYTES, and feature flags for optimal performance in restricted environments.

- Repository: [MAIC/OpenMAIC](https://github.com/THU-MAIC/OpenMAIC)
- Tags: how-to-guide
- Published: 2026-09-08

---

**Set the China region for AI providers in [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts), configure `HTTPS_PROXY`/`HTTP_PROXY` environment variables for the `proxyFetch` wrapper, and tune `MAX_PROXY_BYTES` and feature flags to reduce bandwidth usage.**

OpenMAIC is a multi-modal AI platform developed by THU-MAIC that integrates multiple large language models. When deploying in mainland China or on bandwidth-constrained networks, you need to redirect traffic to domestic endpoints and optimize payload handling. This guide covers the exact source code locations and configuration steps to achieve reliable performance.

## Select China Region Endpoints for AI Providers

OpenMAIC supports region-specific base URLs through the `alternateBaseUrls` array in each provider definition. Switching to China endpoints eliminates cross-border latency and ensures compliance with local API hosting requirements.

### Where Region URLs Are Defined

In [[`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts)](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts), each provider includes a `settings.baseUrlRegion` configuration:

- **GLM (Zhipu AI)**: `https://open.bigmodel.cn/api/paas/v4` (lines 628-630)
- **Moonshot AI**: `https://api.moonshot.cn/v1` (lines 953-954)
- **MiniMax**: `https://api.minimaxi.com/anthropic/v1` (lines 1065-1066)
- **Tencent MaaS**: `https://tokenhub.tencentmaas.com/v1` (lines 1394-1396)

### Configuration Methods

**Via UI (recommended for end users):**
Navigate to **Settings → Provider → Base URL Region** and select "China" for each active provider.

**Via source edit (for self-hosted deployments):**
Modify the `defaultBaseUrl` assignment in [`providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/providers.ts) to reference the China entry from `alternateBaseUrls`:

```typescript
// Example: hard-code GLM to China endpoint
defaultBaseUrl: provider.alternateBaseUrls.find(
  url => url.region === 'china'
)?.url || provider.defaultBaseUrl

```

## Configure HTTP/HTTPS Proxy Support

Corporate networks and regional ISPs often require traffic routing through proxy servers. OpenMAIC's `proxyFetch` utility automatically detects and uses standard proxy environment variables.

### How Proxy Detection Works

The [[`lib/server/proxy-fetch.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/proxy-fetch.ts)](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/proxy-fetch.ts) module implements this logic:

- Reads `HTTPS_PROXY`/`https_proxy` and `HTTP_PROXY`/`http_proxy` (lines 4-18)
- Creates an `undici` `ProxyAgent` when a proxy is present (lines 30-38)
- Respects `NO_PROXY` for loopback addresses and excluded hosts (lines 81-90)

### Setting Environment Variables

```bash
export HTTPS_PROXY=http://proxy.mycompany.cn:3128
export HTTP_PROXY=http://proxy.mycompany.cn:3128
export NO_PROXY=localhost,127.0.0.1,api.myinternal.cn

```

The `proxyFetch` wrapper applies these settings globally—no code changes required for standard API calls.

### Docker Deployment Example

```bash
cat > .env <<EOF
HTTPS_PROXY=http://proxy.mycompany.cn:3128
HTTP_PROXY=http://proxy.mycompany.cn:3128
NO_PROXY=localhost,127.0.0.1
TRUST_PROXY_HEADERS=true
EOF

docker-compose up -d

```

## Tune for Low-Bandwidth Networks

Three levers control bandwidth consumption and timeout behavior when network conditions degrade.

### Reduce Video Export Payload Size

The [[`app/api/export-video/render/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/export-video/render/route.ts)](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/export-video/render/route.ts) file defines this constant at line 67:

```typescript
const MAX_PROXY_BYTES = 25 * 1024 * 1024; // 25 MiB

```

Lower this value to enforce stricter caps on streamed media transfers.

### Add Request-Level Timeouts

Pass an `AbortController` signal to `proxyFetch` for granular timeout control:

```typescript
import { proxyFetch } from '@/lib/server/proxy-fetch';

const controller = new AbortController();
const timeout = setTimeout(() => controller.abort(), 30_000); // 30 seconds

try {
  const response = await proxyFetch(url, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify(payload),
    signal: controller.signal,
  });
} finally {
  clearTimeout(timeout);
}

```

### Disable Heavy Model Capabilities

In [`providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/providers.ts), set capability flags to `false` for unused features:

```typescript
{
  id: 'some-model',
  capabilities: {
    vision: false,      // Disable image understanding
    tools: false,       // Disable function calling
  }
}

```

This reduces token consumption and response payload sizes.

## Enable Trusted Proxy Headers

When OpenMAIC runs behind a reverse proxy (common in China for SSL termination or WAF protection), preserve the original client IP by setting:

```bash
export TRUST_PROXY_HEADERS=true

```

This is consumed at line 29 of [`app/api/export-video/render/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/export-video/render/route.ts), making `X-Forwarded-For` and related headers authoritative for request logging and rate limiting.

## Complete Configuration Example

```typescript
// lib/server/example-usage.ts
import { proxyFetch } from '@/lib/server/proxy-fetch';

// China GLM endpoint with full proxy and timeout handling
async function callChinaGLM() {
  const url = new URL('https://open.bigmodel.cn/api/paas/v4/chat/completions');
  
  const controller = new AbortController();
  const timeout = setTimeout(() => controller.abort(), 20_000);
  
  try {
    const response = await proxyFetch(url, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${process.env.GLM_API_KEY}`,
      },
      body: JSON.stringify({
        model: 'glm-4',
        messages: [{ role: 'user', content: '你好' }],
        stream: false, // Reduce overhead for slow networks
      }),
      signal: controller.signal,
    });
    
    return await response.json();
  } finally {
    clearTimeout(timeout);
  }
}

```

## Source File Reference

| File | Lines | Purpose |
|------|-------|---------|
| [`lib/ai/providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/ai/providers.ts) | 628-630, 953-954, 1065-1066, 1394-1396 | China region URL definitions |
| [`lib/server/proxy-fetch.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/proxy-fetch.ts) | 4-18, 30-38, 81-90 | Proxy detection and `ProxyAgent` configuration |
| [`app/api/export-video/render/route.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/app/api/export-video/render/route.ts) | 29, 67 | `TRUST_PROXY_HEADERS` flag and `MAX_PROXY_BYTES` limit |

## Summary

- **Select China endpoints** by choosing the `china` region from `alternateBaseUrls` in [`providers.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/providers.ts) or via the Settings UI
- **Configure corporate proxies** through standard `HTTPS_PROXY`/`HTTP_PROXY` variables; `proxyFetch` handles the rest
- **Reduce bandwidth usage** by lowering `MAX_PROXY_BYTES`, adding `AbortController` timeouts, and disabling unused capabilities
- **Preserve client IPs** behind reverse proxies with `TRUST_PROXY_HEADERS=true`

## Frequently Asked Questions

### What happens if I don't set HTTPS_PROXY but my network requires it?

API calls to external providers will timeout or fail with connection errors. The `proxyFetch` wrapper only activates proxy mode when environment variables are present—there is no fallback detection.

### Can I use different proxies for different providers?

Not directly through environment variables. The current `proxyFetch` implementation uses global proxy settings. For per-provider routing, you would need to modify [`lib/server/proxy-fetch.ts`](https://github.com/THU-MAIC/OpenMAIC/blob/main/lib/server/proxy-fetch.ts) to accept proxy parameters in the options object.

### Is the China region setting required for all providers?

Only for providers that host APIs in mainland China. International providers without China infrastructure (e.g., some OpenAI-compatible endpoints) should remain on international URLs to avoid routing inefficiencies.

### How do I verify my proxy configuration is working?

Check server logs for successful API responses to China endpoints. You can also enable `NODE_DEBUG=undici` to see proxy agent activity, or test with a known-restricted URL that only resolves through your corporate proxy.