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

Set the China region for AI providers in 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), 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 to reference the China entry from alternateBaseUrls:

// 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) 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

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

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) file defines this constant at line 67:

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:

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, set capability flags to false for unused features:

{
  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:

export TRUST_PROXY_HEADERS=true

This is consumed at line 29 of app/api/export-video/render/route.ts, making X-Forwarded-For and related headers authoritative for request logging and rate limiting.

Complete Configuration Example

// 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	628-630, 953-954, 1065-1066, 1394-1396	China region URL definitions
lib/server/proxy-fetch.ts	4-18, 30-38, 81-90	Proxy detection and ProxyAgent configuration
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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}