OpenClaw 프록시 및 네트워크 설정 튜토리얼

서문

많은 네트워크 환경에서는 OpenAI, Claude 등 AI 서비스의 API에 직접 접근하는 것이 제한될 수 있습니다. 프록시를 올바르게 설정하면 제한된 네트워크에서도 OpenClaw를 정상적으로 사용할 수 있습니다. 이 글에서는 HTTP 프록시, SOCKS5 프록시, 그리고 모델별 프록시 설정 방법을 상세히 소개합니다.

환경 변수를 통한 프록시 설정

가장 간단한 방법은 환경 변수를 통해 글로벌 프록시를 설정하는 것입니다. OpenClaw는 다음과 같은 표준 환경 변수를 자동으로 읽어들입니다:

환경 변수	설명	예시
`HTTP_PROXY`	HTTP 요청 프록시	`http://127.0.0.1:7890`
`HTTPS_PROXY`	HTTPS 요청 프록시	`http://127.0.0.1:7890`
`ALL_PROXY`	모든 요청의 프록시 (우선순위 최하)	`socks5://127.0.0.1:1080`
`NO_PROXY`	프록시를 사용하지 않을 주소 목록	`localhost,127.0.0.1,.local`

Linux / macOS 설정

터미널에서 OpenClaw를 시작하기 전에 환경 변수를 내보냅니다:

export HTTP_PROXY="http://127.0.0.1:7890"
export HTTPS_PROXY="http://127.0.0.1:7890"
export NO_PROXY="localhost,127.0.0.1"

openclaw up

매번 자동으로 적용되도록 하려면 이 변수들을 ~/.bashrc 또는 ~/.zshrc에 추가할 수 있습니다:

echo 'export HTTP_PROXY="http://127.0.0.1:7890"' >> ~/.bashrc
echo 'export HTTPS_PROXY="http://127.0.0.1:7890"' >> ~/.bashrc
source ~/.bashrc

Windows 설정

PowerShell에서:

$env:HTTP_PROXY = "http://127.0.0.1:7890"
$env:HTTPS_PROXY = "http://127.0.0.1:7890"

openclaw up

영구적으로 적용하려면 시스템 환경 변수에 추가하면 됩니다.

설정 파일을 통한 프록시 설정

환경 변수 외에도 OpenClaw의 설정 파일에서 직접 프록시를 설정할 수 있습니다. ~/.config/openclaw/openclaw.json5를 편집합니다:

{
  // 글로벌 프록시 설정
  proxy: {
    // HTTP/HTTPS 프록시 주소
    url: "http://127.0.0.1:7890",
    // 프록시를 사용하지 않을 호스트명 목록
    bypass: ["localhost", "127.0.0.1", "192.168.*"]
  }
}

SOCKS5 프록시 설정

SSH 터널이나 Shadowsocks와 같은 SOCKS5 프록시를 사용하는 경우 다음과 같이 설정합니다:

{
  proxy: {
    url: "socks5://127.0.0.1:1080",
    // 프록시에 인증이 필요한 경우
    username: "your-username",
    password: "your-password"
  }
}

환경 변수를 통해 SOCKS5를 사용할 수도 있습니다:

export ALL_PROXY="socks5://127.0.0.1:1080"
openclaw up

모델별 개별 프록시 설정

AI 모델 API마다 서로 다른 프록시 전략이 필요할 수 있습니다. 예를 들어 OpenAI는 해외 프록시를 사용하고, Ollama 로컬 모델은 프록시를 사용하지 않도록 설정할 수 있습니다. 설정 파일에서 다음과 같이 지정할 수 있습니다:

{
  // 글로벌 기본 프록시
  proxy: {
    url: "http://127.0.0.1:7890"
  },

  models: {
    openai: {
      apiKey: "sk-xxxx",
      // OpenAI는 글로벌 프록시 사용 (위 설정을 상속)
    },
    claude: {
      apiKey: "sk-ant-xxxx",
      // Claude는 별도의 프록시 사용
      proxy: {
        url: "http://127.0.0.1:8080"
      }
    },
    ollama: {
      baseUrl: "http://localhost:11434",
      // Ollama는 로컬 서비스이므로 프록시 불필요
      proxy: {
        url: null  // 프록시를 명시적으로 비활성화
      }
    }
  }
}

프록시 우선순위

여러 프록시 설정이 동시에 존재할 경우 OpenClaw는 다음 우선순위로 적용합니다:

모델 레벨 프록시 - 최상위 우선순위, 지정된 모델에만 적용
설정 파일 글로벌 프록시 - 중간 우선순위
환경 변수 프록시 - 최하위 우선순위

프록시 인증

프록시 서버에 사용자 이름과 비밀번호 인증이 필요한 경우 두 가지 설정 방식이 있습니다:

방식 1: URL에 인증 정보 포함

{
  proxy: {
    url: "http://username:[email protected]:8080"
  }
}

방식 2: 별도 필드로 지정

{
  proxy: {
    url: "http://proxy.example.com:8080",
    username: "your-username",
    password: "your-password"
  }
}

방식 2를 사용하는 것을 권장합니다. 비밀번호에 포함된 특수 문자로 인한 URL 파싱 문제를 방지할 수 있습니다.

프록시 연결 테스트

프록시 설정을 완료한 후 openclaw doctor 명령으로 네트워크 연결 상태를 확인할 수 있습니다:

openclaw doctor

이 명령은 다음 항목을 순차적으로 검사합니다:

프록시 서버 접근 가능 여부
프록시를 통해 각 AI 모델의 API 엔드포인트에 연결 가능한지 여부
DNS 확인이 정상적인지 여부
TLS 인증서가 유효한지 여부

출력 예시:

[✓] 프록시 서버 http://127.0.0.1:7890 접근 가능
[✓] OpenAI API (api.openai.com) 연결 정상 (지연: 320ms)
[✓] Claude API (api.anthropic.com) 연결 정상 (지연: 280ms)
[✓] Ollama (localhost:11434) 연결 정상 (지연: 2ms)
[✓] 모든 검사 통과

일반적인 연결 문제 해결

문제 1: 프록시 타임아웃

ETIMEDOUT 또는 ECONNREFUSED 오류가 발생하는 경우:

# 먼저 프록시 서비스가 실행 중인지 확인
curl -x http://127.0.0.1:7890 https://httpbin.org/ip

# 포트가 리스닝 중인지 확인
netstat -tlnp | grep 7890

문제 2: SSL 인증서 오류

일부 프록시는 TLS 인증서를 교체하여 인증서 검증이 실패할 수 있습니다:

{
  proxy: {
    url: "http://127.0.0.1:7890",
    // 개발 환경에서만 사용, 운영 환경에서는 비활성화하지 않는 것을 권장
    rejectUnauthorized: false
  }
}

더 안전한 방법은 프록시의 CA 인증서를 가져오는 것입니다:

export NODE_EXTRA_CA_CERTS="/path/to/proxy-ca.crt"
openclaw up

문제 3: 기업 내부망에서 PAC 파일 필요

OpenClaw는 PAC 파일을 직접 지원하지 않지만, PAC 파일의 규칙을 수동으로 분석하여 해당 프록시 주소를 설정할 수 있습니다. 또는 로컬 프록시 도구(예: Privoxy)를 사용하여 PAC를 표준 HTTP 프록시로 변환할 수 있습니다.

문제 4: WSL 환경 프록시 설정

WSL에서는 프록시 주소를 Windows 호스트의 IP로 지정해야 합니다:

# Windows 호스트 IP 가져오기
WIN_HOST=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
export HTTP_PROXY="http://${WIN_HOST}:7890"
export HTTPS_PROXY="http://${WIN_HOST}:7890"

openclaw up

Docker 환경에서의 프록시 설정

Docker로 OpenClaw를 실행하는 경우 docker-compose.yml을 통해 프록시 변수를 전달할 수 있습니다:

services:
  openclaw:
    image: openclaw/openclaw:latest
    environment:
      - HTTP_PROXY=http://host.docker.internal:7890
      - HTTPS_PROXY=http://host.docker.internal:7890
      - NO_PROXY=localhost,127.0.0.1,ollama
    ports:
      - "18789:18789"

Docker에서는 host.docker.internal을 사용하여 호스트 머신의 프록시 서비스에 접근해야 한다는 점에 유의하십시오.

요약

프록시 설정은 제한된 네트워크에서 OpenClaw를 사용하기 위한 핵심 단계입니다. 권장하는 방법은 다음과 같습니다:

개인 사용: 환경 변수를 통한 설정으로 충분합니다
다중 모델 시나리오: 설정 파일에서 모델별로 프록시를 개별 설정합니다
기업 배포: Docker 환경 변수와 설정 파일을 결합하여 통합 관리합니다
문제 해결: openclaw doctor를 활용하여 연결 문제를 빠르게 파악합니다

설정 완료 후 openclaw restart로 서비스를 재시작하여 설정을 적용하는 것을 잊지 마십시오.