내 PC/서버에 직접 설치해 텔레그램·디스코드로 제어하는 셀프호스팅 AI 에이전트 플랫폼입니다.
외부 서버 없이 로컬 환경에서 Claude, GPT 등 LLM을 연결해 나만의 AI 직원을 구성할 수 있습니다.
"AI 에이전트를 열심히 세팅해 뒀는데, 터미널 창을 닫으면 봇이 꺼져 버린다." "서버를 외부에 열어두니 해킹이 걱정된다." — VPS나 홈 서버에서 OpenClaw를 운영해 보신 분이라면 한 번쯤 겪어 보셨을 고민입니다. 채널을 연결하고 모델을 세팅하는 것만큼이나 중요한 것이 바로 게이트웨이를 안전하고 안정적으로 굴러가게 만드는 일입니다.
이번 23편에서는 openclaw gateway 설정의 핵심 보안 요소(포트·바인딩·인증 토큰)를 완벽하게 정리하고, 터미널 창을 닫아도 에이전트가 24시간 멈추지 않게 만드는 데몬 상시 실행법까지 실전 코드와 함께 마스터합니다. 오늘 설정을 마치면 여러분의 AI 서버는 튼튼한 성벽을 갖추게 됩니다.
지난 편(22편: 로컬 LLM(Ollama) + OpenClaw 연동 — 완전 무료 AI 에이전트 구축)에서는 Ollama로 완전 무료 로컬 AI를 연동하는 방법을 배웠습니다. 이번 편에서는 그 시스템을 외부 공격으로부터 지키고 24시간 무중단 운영하는 인프라 보안을 다룹니다.
Gateway의 역할 — 최전방 경비대 이해하기
게이트웨이(Gateway)는 텔레그램·디스코드·웹 대시보드 등 외부에서 들어오는 모든 요청을 가장 먼저 맞이하고 검증하는 최전방 경비대입니다. 에이전트가 아무리 똑똑해도 이 관문이 뚫리면 아무 의미가 없습니다. openclaw 사용법에서 게이트웨이 보안 설정이 가장 먼저 언급되는 이유가 바로 여기 있습니다.
게이트웨이가 처리하는 세 가지 일
- 접속 허용 범위 결정(Bind): 어떤 네트워크 인터페이스에서 오는 연결을 받아들일지 정합니다. VPS 환경에서는 외부 IP 전체 허용(
0.0.0.0)이 아닌 로컬호스트(loopback)만 허용하는 것이 기본 원칙입니다. - 신원 검증(Auth Token): 올바른 토큰을 가진 요청만 게이트웨이를 통과시킵니다. 2026년 1월 CVE-2026-25253 취약점 발견 이후
auth: none옵션은 공식 폐지되었으며, 반드시 토큰을 설정해야 합니다. - 로그 기록 및 마스킹: 모든 요청 이력을 기록하되, 설정에 따라 API 키 등 민감 정보를 자동으로
***처리합니다.
핵심 보안 설정 — Bind와 Token 완전 정복
실제 ~/.openclaw/openclaw.json 파일에서 openclaw gateway 설정을 어떻게 작성하는지 살펴봅니다. 아래 두 가지 항목만 올바르게 설정해도 일반적인 외부 공격의 99%를 원천 차단할 수 있습니다.
bind: loopback — 외부 노출 차단
VPS 서버에서 "bind": "0.0.0.0"(모든 접속 허용)이나 "all"을 사용하면 전 세계 어디서나 게이트웨이 포트에 직접 접근할 수 있어 무차별 대입 공격에 취약해집니다. 반드시 "loopback"으로 설정하여 서버 내부(localhost)에서만 통신하도록 제한해야 합니다.
auth.token — 뚫기 어려운 비밀번호 설정
토큰은 비밀번호와 동일합니다. 짧거나 단순한 단어는 절대 사용하지 마세요. 영문 대소문자·숫자·특수문자를 혼합한 32자 이상의 무작위 문자열이 이상적입니다. 아래 실전 설정 예시를 참고하세요.
{
"gateway": {
"port": 18789,
"mode": "local",
"bind": "loopback",
"auth": {
"mode": "token",
"token": "MY_SUPER_SECRET_COMPLEX_TOKEN_2026"
}
},
"logging": {
"redactSensitive": "tools"
}
}port)나 바인드(bind) 설정을 변경한 뒤에는 반드시 openclaw gateway restart를 실행해야 합니다. 이 두 항목은 실시간 핫 리로드(Hot Reload)가 지원되지 않습니다.단계별 가이드 — tmux 데몬 상시 실행 설정법
게이트웨이를 단순히 openclaw gateway 명령어로 실행하면, SSH 접속(터미널 창)을 닫는 순간 프로세스도 함께 종료됩니다. 24시간 무중단 에이전트를 위해서는 백그라운드 상시 실행(Daemon) 설정이 필수입니다. 초보자에게 가장 직관적인 방법인 tmux를 활용합니다. 아래 순서대로 따라 하시면 10분 내에 완료됩니다.
- tmux 설치Ubuntu/Debian 기준으로 아래 명령어를 실행합니다. 이미 설치되어 있다면 이 단계는 건너뜁니다.
sudo apt-get update && sudo apt-get install tmux -y- openclaw.json 보안 설정 저장앞서 작성한
bind: loopback·auth.token설정을~/.openclaw/openclaw.json에 저장합니다. 그런 다음 변경사항을 적용합니다. openclaw gateway restart- 새 tmux 세션 생성 및 게이트웨이 실행터미널에서 아래 두 명령어를 순서대로 실행합니다.
openclaw-bot은 세션 이름으로, 원하는 이름으로 변경해도 됩니다. # 새 백그라운드 세션 생성 및 진입 tmux new -s openclaw-bot # 세션 안에서 게이트웨이 실행 openclaw gateway run- 세션에서 빠져나오기 (Detach)키보드에서
Ctrl + B를 누른 뒤, 손을 떼고D를 누릅니다. 터미널에
[detached (from session openclaw-bot)]메시지가 뜨면 성공입니다. 이제 터미널 창을 완전히 닫아도 게이트웨이는 24시간 백그라운드에서 작동합니다. # 나중에 세션에 다시 접속(Attach)하려면: tmux attach -t openclaw-bot
운영 안정화 — 설정 체크리스트와 로그 보안
게이트웨이를 처음 세팅한 뒤에는 아래 체크리스트를 통해 운영 안정성을 점검하세요. 특히 장기 운영에서 로그 관리와 포트 충돌 대응은 빠뜨리기 쉬운 항목입니다.
포트 충돌 시 즉시 해결법
"Error: listen EADDRINUSE :::18789" 오류는 포트를 다른 프로그램이 점유 중이거나, 이전 게이트웨이 프로세스가 백그라운드에 남아있을 때 발생합니다. 아래 명령어로 깔끔하게 해결합니다.
# 숨어있는 openclaw 프로세스 전체 강제 종료
pkill -f openclaw
# 이후 다시 실행
openclaw gateway run로그 민감 정보 마스킹
logging.redactSensitive를 "tools"로 설정하면 로그 파일에 API 키·토큰이 ***로 마스킹되어 기록됩니다. 로그를 팀원과 공유하거나 GitHub 이슈에 붙여넣을 때 키 유출 사고를 예방합니다. 더 강력한 보안이 필요하다면 "all"로 설정하세요.
gateway URL도 함께 업데이트해야 합니다. 포트만 바꾸고 채널 설정을 그대로 두면 봇이 응답하지 않습니다.loopback, auth token은 32자 이상 복잡한 문자열, heartbeat 프로세스는 tmux로 데몬화 — 이 세 가지가 안정적인 OpenClaw 운영의 기본 공식입니다.
실전 팁과 주의사항
- 처음엔 기본 포트(18789) 그대로 사용: 포트를 바꿔야 할 특별한 이유가 없다면 기본값을 유지하세요. 변경 시 채널 설정도 함께 업데이트해야 해서 실수가 발생하기 쉽습니다.
- 토큰은 환경 변수로 분리 보관: 토큰 값을
openclaw.json에 직접 하드코딩하지 말고,"token": "${OPENCLAW_TOKEN}"형태로 환경 변수를 참조하고 실제 값은~/.openclaw/.env에만 보관하세요. - tmux 세션 재부팅 후 자동 복구를 원한다면: 서버가 재부팅될 때마다 tmux 세션이 사라집니다. 완전 자동 복구를 원한다면
tmux대신 systemd 서비스로 등록하는 방법을 검토하세요. - bind: loopback과 외부 접속을 동시에 원한다면:
loopback으로 직접 외부 노출을 막되, Nginx 리버스 프록시나 Tailscale VPN으로 안전한 우회 경로를 만드세요. 다음 24편에서 자세히 다룹니다.
자주 묻는 질문 (FAQ)
- 설정 파일에서 포트 번호를 바꿨는데 적용이 안 됩니다.
- 채널 정책이나 프롬프트는 파일 저장 즉시 반영(Hot Reload)되지만, 게이트웨이의 포트(
port)나 바인드(bind)는 네트워크 소켓을 새로 열어야 하므로 반드시 재시작이 필요합니다. 설정 수정 후 터미널에서openclaw gateway restart를 실행해 보세요. - bind를 'loopback'으로 막아두면 외부에서 스마트폰으로 어떻게 접속하나요?
loopback은 외부 인터넷의 직접 접근을 차단하는 것이지, 내가 외부에서 접속하는 것 자체를 막는 것이 아닙니다. 카페나 외부에서 내 서버 대시보드에 접속하고 싶다면 Nginx 리버스 프록시를 세팅하거나, Tailscale 같은 VPN으로 로컬망에 우회 접속하는 방법을 사용하세요. 이는 다음 24편에서 자세히 다룹니다.- 게이트웨이 실행 시 "Error: listen EADDRINUSE :::18789" 에러가 발생합니다.
- 18789번 포트를 다른 프로그램이 이미 사용 중이거나, 이전에 실행해 둔 OpenClaw 프로세스가 백그라운드에 남아있는 경우입니다. 터미널에서
pkill -f openclaw를 입력해 숨어있는 프로세스를 모두 강제 종료한 뒤 다시 실행하면 해결됩니다. - 로그 파일에 제 API 키가 그대로 찍힐까 봐 걱정됩니다.
- 본문 예제처럼
logging설정에"redactSensitive": "tools"(또는"all")를 추가해 두면 OpenClaw가 API 키와 인증 토큰을 자동으로 감지하여***형태로 마스킹한 뒤 로그에 기록합니다. 로그를 안심하고 팀원과 공유할 수 있습니다.
이 글이 도움이 됐다면 댓글로 여러분의 경험을 알려주세요! 🙌
openclaw gateway 설정에서 막히는 부분은 댓글에 남겨주세요 — 직접 답변드립니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
'OpenClaw' 카테고리의 다른 글
| 오픈클로 완전 가이드 24편 openclaw 원격 접속 설정 — Tailscale·SSH 터널로 어디서나 안전한 AI 에이전트 만들기 (1) | 2026.04.08 |
|---|---|
| 오픈클로 완전 가이드 22편 로컬 LLM(Ollama) + OpenClaw 연동 — 완전 무료 AI 에이전트 구축 (0) | 2026.04.07 |
| 오픈클로 완전 가이드 21편 Models 설정 완전 가이드 — GPT·Claude·Gemini 연결 비교 (0) | 2026.04.07 |
| 오픈클로 가이드 20편 openclaw MCP 연동 — 외부 데이터 연결 완전 가이드 (0) | 2026.04.04 |
| 오픈클로 완전 가이드 19편 커스텀 Tool 만들기 — Python 스크립트를 AI 도구로 등록하는 법 (1) | 2026.04.04 |
댓글