Codex --remote invalid remote address가 나오면 토큰이나 방화벽보다 현재 CLI가 그 주소 형식을 받는지 먼저 확인하세요. Codex CLI 0.155.1 직접 재현에서는 wss://서버:포트/경로를 네트워크 연결 전에 거절했습니다.
목차
1. 버전과 허용 형식을 먼저 확인하기
터미널에서 다음 두 명령을 실행합니다.
codex --version
codex --help
--remote <ADDR> 아래의 Accepted forms를 읽습니다. 2026-09-22에 확인한 0.155.1은 WebSocket 주소를 ws://host:port, wss://host:port로 표시했고, Unix 소켓만 unix://PATH를 별도로 안내했습니다. 버전이 다르면 내 터미널의 도움말을 다시 확인합니다.
OpenAI의 Codex App Server 공식 문서도 --remote가 ws://, wss://, unix://, unix://PATH endpoint를 받는다고 안내합니다. 다만 WebSocket 예시는 ws://127.0.0.1:4500과 wss://remote-host:4500처럼 host와 port까지이며, URL 경로 지원은 명시하지 않습니다. 공식 문서는 app-server WebSocket transport를 실험적이고 생산 워크로드에 지원되지 않는 기능으로도 표시합니다.
2. 같은 오류인지 입력과 결과를 비교하기
비민감 예시 주소로 경로가 포함된 형식을 넣으면 다음처럼 구분할 수 있습니다.
codex --remote 'wss://example.invalid:443/codex-app-server'
이번 macOS 재현 결과는 exit 1이었고, 서버 연결 오류 대신 다음 형식의 메시지가 즉시 나왔습니다.
Error: invalid remote address ... expected ws://host:port, wss://host:port, unix://, or unix://PATH
이 결과는 DNS, 서버 실행 상태, bearer token을 검사했다는 뜻이 아닙니다. 주소 파서가 먼저 멈춘 것입니다. 토큰을 새로 만들거나 방화벽을 바꾸기 전에 주소 형식을 고쳐야 합니다.
3. 정상 형식으로 대조하기
형식을 통과하는 주소는 실제로 존재하지 않는 로컬 port로 연결해 다음 단계까지 갔는지 구분할 수 있습니다.
codex --remote 'ws://127.0.0.1:9'
여기서 invalid remote address가 아닌 연결 거부나 재시도 유형의 오류로 바뀐다면 주소 문법 단계는 통과한 것입니다. 이 명령은 정상 서버 연결을 증명하지 않고, 오류 단계만 나눕니다.
4. 경로가 꼭 필요한 서버라면
서버가 /codex-app-server 같은 WebSocket 경로에서만 열리도록 배치돼 있다면, 경로를 무작정 지우면 다른 endpoint에 연결할 수 있습니다. 다음 순서로 확인하세요.
- 현재 CLI 도움말과 공식 문서에서 경로형 WebSocket 주소 지원이 명시됐는지 확인합니다.
- 원격 app-server를 별도 host·port에 직접 열 수 있는지 서버 관리자에게 확인합니다.
- localhost나 SSH port forwarding으로 옮길 수 있다면 공식 문서의
ws://127.0.0.1:PORT형식으로 대조합니다. - 외부 연결은 TLS와 WebSocket 인증을 설정하고, bearer token 값이 아닌 토큰을 담은 환경 변수 이름을
--remote-auth-token-env에 넘깁니다.
실제 서버 주소, 인증 토큰, 내부 호스트 이름은 질문이나 캡처에 올리지 마세요. 공개 예시 주소로 문법 오류를 분리한 뒤 비밀값은 로컬에서만 적용합니다. 다른 AI 코딩 도구의 결과와 비교해야 한다면 같은 입력과 검사 명령을 고정하는 방법처럼 조건을 하나씩만 바꾸어 대조합니다.
검색 결과와 기존 글에서 답하지 못한 점
2026년 9월 22일 Google에서 "invalid remote address" codex remote를 검색하면 정확 오류를 설명하는 일반 웹 문서는 거의 없었고, 유사한 GitHub 이슈와 브릿지 구현 자료가 주로 나왔습니다. Google AI 요약에는 현재 공식 문서와 직접 재현으로 확인하지 못한 remote-control 명령·설정 제안도 섞여 있어 해결책으로 채택하지 않았습니다.
같은 날 Naver의 동일 표현 결과는 Codex Remote 소개·SSH 연결·원격 제어 글이 중심이었고, 경로가 든 wss://가 연결 전에 거절되는 현상의 입력→결과 대조는 확인하지 못했습니다. 기존 seoin.dev 담당 URL도 이 오류를 답하지 않아 독립 문제 해결 글로 유지했습니다. 검색 결과 존재는 월간 검색량을 뜻하지 않으며, 정확 수요는 미확인입니다.
오류가 달라지면 다음 점검도 달라집니다
| 표시된 오류 | 먼저 확인할 단계 |
|---|---|
invalid remote address |
주소 문법과 현재 버전의 허용 형식 |
connection refused 또는 timeout |
서버 실행·포트·네트워크 |
| 인증 실패 | --remote-auth-token-env로 넘긴 환경 변수 이름과 서버 정책 |
토큰 값 자체를 명령 기록이나 글에 붙이지 않습니다.
자주 묻는 질문
경로를 지우면 바로 해결되나?
아닙니다. 경로를 지운 주소가 실제 app-server listener를 가리킬 때만 연결을 시도할 수 있습니다. 서버가 특정 경로로만 노출됐다면 다른 host·port listener나 SSH port forwarding 구성이 필요합니다.
인증 토큰부터 다시 만들어야 하나?
invalid remote address가 즉시 나오는 이 재현은 토큰 검사까지 가지 않았습니다. 주소 문법을 통과한 후 인증 오류가 나올 때만 --remote-auth-token-env에 넘긴 환경 변수 이름과 서버 정책을 확인합니다.
wss://라면 임의의 URL 경로도 지원되나?
현재 공식 문서는 wss:// endpoint를 허용하지만 임의의 URL 경로 지원은 약속하지 않습니다. 0.155.1 로컬 파서는 이번 경로 형식을 거절했으므로 버전·도움말·공식 문서를 함께 확인합니다.
확인 범위
2026-09-22 macOS의 Codex CLI 0.155.1에서 경로가 든 wss:// 예시를 실행해 같은 parser 오류를 재현했습니다. codex --help의 허용 형식과 OpenAI 공식 app-server 문서를 대조했습니다. 실제 원격 서버 연결 성공, reverse proxy 우회 성공, 경로 지원의 향후 변경은 이번에 검증하지 않았습니다.
공개 질문은 openai/codex #47255이며, 단일 이슈를 일반적인 사용 빈도로 해석하지 않습니다. 검색량·수정 일정·전체 운영체제에서의 동일 동작은 미확인입니다.
검증 기준
- 마지막 업데이트일: 2026-09-22
- 확인 환경: macOS, Codex CLI 0.155.1, 비민감 예시 주소
- 주요 근거: OpenAI Codex App Server 문서, openai/codex #47255
- 직접 확인: 경로 포함
wss://는 exit 1 parser 오류,codex --help는 WebSocket의 host·port 형식 표시 - 검색 대조: 2026-09-22 Google·Naver Orca 일반 결과, 정확 월간 수요 미확인
- 미확인: 실제 원격 서버 연결 성공, reverse proxy 우회 성공, 향후 경로 지원 변경
직접 만든 실습 자료와 새 도구 소식
AI 도구로 만든 실습 자료, 달라진 기능과 강의 소식을 준비하고 있습니다. 발송을 시작하면 안내해 드려요. 먼저 확인 메일에서 본인 이메일을 확인해 주세요.
신청하기 전에 첫 소식 미리보기에서 내용과 자료를 확인해 보세요.