러시아의 OpenClaw: 안전한 Gateway와 API 설정

OpenClaw가 실행하는 것

OpenClaw는 여러 계층으로 구성됩니다. 한 계층의 문제는 다른 계층의 문제처럼 보일 수 있으므로 조정하기 전에 기능을 분리하는 것이 좋습니다.

이 구조에서 BetterToken은 Provider API만 담당합니다. OpenClaw 사이트, installer, channels, community skills, 제3자 서비스의 가용성을 보장하지 않습니다. BetterToken API Endpoint는 러시아에서 VPN 없이 연결할 수 있지만, 이는 OpenClaw 다운로드와 외부 integrations에는 적용되지 않습니다.

영구 Gateway 없이 OpenClaw 설치하기

첫 확인에는 공식 installer와 --no-onboard 플래그를 사용합니다. provider가 검증되기 전에는 setup wizard가 실행되지 않고 영구 service도 만들어지지 않습니다.

macOS, Linux 또는 WSL2

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

Windows PowerShell

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

CLI를 확인합니다.

openclaw --version

공식 installer는 지원되는 Node.js version을 점검하고 필요하면 설치합니다. 제3자 가이드의 오래된 Node에 고정하지 마세요. 현재 요구사항은 OpenClaw installation page에 공개됩니다.

공개 API Key 없이 BetterToken provider 설정하기

주 OpenClaw 파일은 여기에 있습니다.

~/.openclaw/openclaw.json

편집 전 별도 workspace를 만듭니다.

mkdir -p ~/openclaw-first-check

첫 시작에서는 BetterToken GPT group의 현재 Model ID를 선택합니다. 다음 구성은 openai-responses를 사용합니다. 다른 provider의 경우 모델 이름으로 프로토콜을 추측하지 말고, 현재 BetterToken 문서에서 openai-completions 또는 다른 옵션을 확인하세요.

{
  "models": {
    "mode": "merge",
    "providers": {
      "bettertoken": {
        "baseUrl": "https://www.bettertoken.ai/v1",
        "apiKey": {
          "source": "env",
          "provider": "default",
          "id": "BETTERTOKEN_API_KEY"
        },
        "api": "openai-responses",
        "models": [
          { "id": "YOUR_MODEL_ID", "name": "YOUR_MODEL_ID" }
        ]
      }
    }
  },
  "agents": {
    "defaults": {
      "workspace": "~/openclaw-first-check",
      "model": { "primary": "bettertoken/YOUR_MODEL_ID" }
    }
  },
  "gateway": { "mode": "local", "bind": "loopback" },
  "tools": { "profile": "minimal" }
}
더 보기

YOUR_MODEL_ID는 자리표시자입니다. 자신의 Key에 대한 모델 카탈로그 또는 Setup window의 전체 ID로 바꾸세요. Base URL에는 /responses 또는 /chat/completions를 붙이지 않습니다.

apiKey field는 OpenClaw SecretRef를 사용합니다. BETTERTOKEN_API_KEY 값은 Gateway process가 읽을 수 있는 보호된 environment에 설정해야 하며 key 자체를 openclaw.json에 쓰지 않습니다. OpenClaw는 models.providers.*.apiKey의 SecretRef를 공식 지원합니다.

config와 오래된 generated file에 노출 credential이 없는지 점검합니다.

openclaw secrets audit --check

audit가 plaintext를 발견하면 대화형 migration을 사용합니다.

openclaw secrets configure --apply

key를 prompt, log, commit, agent workspace에 복사하지 마세요.

설정, Gateway, 모델 확인하기

1. 실행 전 JSON 확인

openclaw config validate

이 command는 Gateway를 실행하지 않고 active schema를 검증합니다. 오류가 있다면 지정 field, quotes, parentheses를 수정하고 다시 확인합니다.

2. Provider와 선택 모델 확인

openclaw models list --provider bettertoken
openclaw models status

bettertoken/YOUR_MODEL_ID가 list에 있어야 하고 status가 resolved default로 표시해야 합니다. models list는 read-only command라 성공한 API call을 증명하지 않으므로 별도의 짧은 request가 필요합니다.

3. Gateway를 전경에서 시작

별도 terminal에서 실행합니다.

openclaw gateway --force

process는 열린 상태로 둡니다. 첫 terminal에서 확인합니다.

openclaw gateway status --require-rpc
openclaw status

로컬 테스트에서는 Gateway가 loopback에서 listen하고 auth를 요구하며 작동하는 RPC probe를 반환해야 합니다. 처음부터 bind를 lan, tailnet, 0.0.0.0으로 바꾸지 마세요.

4. 새 session 열기

openclaw tui --session first-check

파일 작업 없는 최소 request를 보냅니다.

JSON만 반환하세요: {"agent":"openclaw","sum":4}. tools를 사용하지 말고 파일을 변경하지 마세요.

첫 시작은 다음을 모두 만족할 때 확인됩니다.

• TUI가 유효한 JSON을 반환했다.
• openclaw models status가 bettertoken/YOUR_MODEL_ID를 표시한다.
• 예상 모델, status, Token 소비의 request가 BetterToken Dashboard에 나타난다.
• workspace에 예상하지 못한 변경이 없다.

확인 뒤 Ctrl+C로 전경 Gateway를 중지합니다. 그 후에만 영구 service 필요 여부를 결정합니다.

5. 검증 뒤에만 service 설치

terminal을 닫은 뒤에도 Gateway를 실행하려면 다음을 사용합니다.

openclaw gateway install
openclaw gateway restart
openclaw gateway status --require-rpc

재시작에는 openclaw gateway restart를 사용합니다. 공식 runbook은 이를 stop과 start 체인으로 대체하지 말라고 합니다.

첫 시작에 최소 권한이 필요한 이유

Gateway는 기본적으로 하나의 신뢰된 circuit용으로 설계됩니다. tools가 가능한 agent는 파일을 읽고 바꾸고, command를 실행하고, network에 접근할 수 있습니다. prompt injection은 공개 chat뿐 아니라 web page, document, attachment, log에서도 올 수 있습니다.

첫 테스트에서는 tools.profile을 minimal, Gateway를 loopback, channels를 미설정으로 둡니다. source와 permissions를 확인하기 전에 community skills나 plugins를 설치하지 마세요. access를 확장하기 전에 실행합니다.

openclaw security audit --deep

나중에 channel을 연결한다면 pairing 또는 allowlist와 별도 session scope로 시작합니다. 서로 신뢰하지 않는 사용자를 위한 공유 Gateway는 지원되는 isolation boundary가 아닙니다.

오래된 session이 오래된 모델을 사용할 수 있는 이유

agents.defaults.model.primary를 바꾼 뒤에도 이미 열린 대화에는 JSON edit만으로 충분하지 않습니다. config를 확인하고 Gateway를 재시작한 뒤 새 session key를 만듭니다.

openclaw config validate
openclaw gateway restart
openclaw tui --session after-model-change

이 방식은 테스트와 이전 context가 섞이는 것을 막습니다. 새 session이 여전히 다른 provider를 쓰면 agents.defaults.model.primary, models.providers.bettertoken.models, openclaw models status 출력을 맞춰 보세요.

자주 발생하는 오류

config validate가 통과하지 않음

JSON structure와 지원되는 api values를 확인합니다. invalid config로 Gateway를 시작하지 마세요. validation이 성공하기 전까지 editor의 직접 변경은 untrusted로 취급합니다.

Gateway가 시작되지 않거나 RPC probe가 실패함

먼저 openclaw gateway status를 실행합니다. EADDRINUSE는 port conflict 또는 두 번째 Gateway process를 뜻합니다. auth error는 Gateway credential과 client의 불일치를 뜻합니다. 오류를 피하려고 auth를 끄거나 bind를 외부 network로 열지 마세요.

401, 404, protocol error

401에서는 Gateway environment에서 SecretRef가 해석되는지 확인합니다. GPT group에는 openai-responses와 Base URL https://www.bettertoken.ai/v1을 사용합니다. 다른 provider는 Docs에서 정확한 protocol을 가져오고 endpoint를 수동으로 추가하지 않습니다.

모델이 JSON에는 있지만 보이지 않음

models.providers.bettertoken.models의 ID와 agents.defaults.model.primary를 비교하고, openclaw config validate, openclaw models list --provider bettertoken, openclaw models status를 실행합니다.

OpenClaw 또는 Hermes Agent

이 지침은 설치 질문에만 답합니다. 아직 architecture를 고르는 중이라면 Hermes Agent 또는 OpenClaw: 선택 방법이라는 별도 문서가 이 구성을 반복하지 않고 local agent runtime, Gateway approach, operational complexity를 비교합니다.

FAQ

Telegram 또는 Discord를 바로 연결해야 하나요?

아니요. 먼저 local provider, Gateway, 모델, 새 session을 확인하세요. channels는 access surface를 넓히고 별도의 pairing 또는 allowlist policy가 필요합니다.

API Key를 openclaw.json에 직접 쓸 수 있나요?

plaintext는 기술적으로 지원되지만 안전한 실행에는 SecretRef를 사용하세요. config의 공개 key는 파일을 읽을 수 있는 모든 process 또는 Agent tool에 접근 가능합니다.

성공한 모델 요청 없이 Gateway를 테스트하는 방법은?

openclaw gateway status --require-rpc는 RPC를, openclaw models status는 모델 권한과 credential을 확인합니다. 완전한 end-to-end test는 새 session의 짧은 response와 BetterToken Dashboard request가 나타난 뒤에야 완료됩니다.