AI에게 코드에 대해 상담하다가, "어라, 그 정보 좀 너무 오래된 거 아닌가...?"라고 느낀 적 없으신가요.

새로 나온 라이브러리의 버전을 물어봤는데, 조금 전의 답변이 돌아온다. 아직 존재하지 않는다는 전제로 이야기가 진행된다. 왠지 이건 정말 아깝다는 생각이 듭니다. 기껏 똑똑한데, 보고 있는 세계가 "조금 전"에 멈춰 있는 느낌이죠.

오늘은 그 고민에 핀포인트로 효과가 있는, OpenAI의 Codex CLI 의 --search 라는 기능을, 딱 하나만, 아주 정성스럽게 소개하겠습니다. 아직 Codex를 접해본 적이 없는 분이라도, 이 기사만으로 "최신 정보를 Web에서 검색하게 하는" 단계까지 도달할 수 있도록 작성했습니다. 다루는 것은 --search 하나뿐입니다. 이것저것 많이 담지는 않겠습니다.

이 기사는 Codex의 공식 문서를 실제로 읽고, 명령어 이름이나 모드의 동작을 대조한 뒤에 작성했습니다. 읽은 페이지는 말미의 "참고 링크"에 정리해 두었습니다.

먼저 용어부터 하나씩 풀어가겠습니다.

CLI… 「Command Line Interface」의 약으로, 터미널(검은 화면에 글자를 입력하여 조작하는 앱)에서 명령어를 입력하여 사용하는 방식을 말합니다. 마우스로 버튼을 누르는 대신, 글자로 지시를 내리는 이미지입니다. -
Codex CLI… 그 터미널 안에서 동작하는, OpenAI의 코딩용 AI 에이전트입니다. 당신의 컴퓨터에서 파일을 읽거나, 코드를 작성하거나, 명령어를 실행해 줍니다. -
플래그 (Flag)… 명령어 뒤에 붙이는 "옵션 스위치"를 말합니다. --search 처럼 --로 시작하는 문자를 추가하면, 해당 회차의 동작을 조금 바꿀 수 있습니다.

즉 --search 는, Codex를 실행할 때 붙이는 "이번에는 Web에서 최신 정보를 가져와도 좋아"라는 스위치 입니다. 이 부분은 사소해 보이지만 중요하므로 미리 말씀드립니다. --search 는 터미널에서 입력하는 검색 명령어(grep 같은 것)가 아닙니다. Codex를 실행할 때의 플래그 입니다. 이 부분을 먼저 파악해 두면 뒤의 내용이 쉽게 이해됩니다.

여기서 조금 의외인 이야기를 해볼까요.

"그럼 --search 를 붙이지 않으면 Web 검색은 전혀 할 수 없는 거야?"라고 생각하실 겁니다. 솔직히 말씀드리면, 그렇지 않습니다.

공식의 Config basics에 따르면, Codex는 로컬에서의 채팅에서 표준으로 Web 검색이 활성화 되어 있습니다. 다만 기본값은 "cached (캐시) 모드"입니다. 이는 OpenAI가 관리하는 Web 결과의 인덱스(미리 가져다 놓은 색인)에서 답을 찾는 방식입니다. 라이브로 그 시점의 페이지를 가져오는 것이 아니라, 사전에 색인화된 결과를 반환합니다. 그래서 동작은 하고 있지만 "최신의 바로 지금"은 아닐 때가 있다는 것입니다.

Codex의 web_search 에는 다음 4가지 모드가 있습니다.

그리고 본론인 --search 는, 이 live를 일시적으로 켜는 플래그 입니다. 공식 문서에도 "live (--search 와 동일)"라고 명시되어 있습니다. 요약하자면, 다음과 같은 분기로 생각하면 헷갈리지 않습니다.

• 평소 (cached)… 대부분의 조사에는 이것으로 충분합니다.
• 최신 정보가 필요한 딱 한 번 (--search = live)… "어제 출시된 이야기" 같은 상황일 때 붙입니다.
• 완전히 끔 (disabled)… 인터넷에 내보내고 싶지 않은 환경일 때.

AI 코딩에서 가장 무서운 것은, "틀린 채로, 그럴싸하게 진행되어 버리는 것"이라고 생각합니다.

예를 들어, 최신 라이브러리 사용법을 상담한다고 가정해 봅시다. cached 인덱스에 아직 충분히 반영되지 않았다면, AI는 조금 이전의 API를 전제로 아주 당당하고 자신만만하게 코드를 작성해 줍니다. 그러다 실행해 보고 나서야 "아, 그 메서드 이제 없구나..."라고 깨닫게 되죠. 이런 재작업은 은근히 시간을 잡아먹습니다.

--search

(live)를 붙여두면, Codex는 해당 회차에 지금의 Web을 확인한 뒤에 답을 구성합니다. 즉, "오래된 전제를 바탕으로 달려 나가기" 전에, 최신 1차 정보로 발밑을 확인할 수 있습니다. 저는 이 점이 --search의 진정한 가치라고 생각합니다.

아직 Codex를 설치하지 않은 분들을 위해 가장 짧은 경로만 남겨둡니다. 이미 사용 중인 분들은 다음 ②번까지 건너뛰셔도 괜찮습니다.

Mac / Linux의 경우 (터미널에 붙여넣어 실행):

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Windows의 경우 (PowerShell에 붙여넣기):

powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"

npm이나 Homebrew를 선호하는 분은 이 방법으로도 설치 가능합니다:

# npm을 사용하는 경우
npm install -g @openai/codex
# Homebrew를 사용하는 경우 (Mac)
...

설치가 완료되었다면, 우선 실행하여 제대로 설치되었는지 확인해 봅시다.

codex --version

버전 번호가 표시되면 OK입니다. (이 글에서는 여기까지를 실제로 직접 확인할 수 있는 범위로 작성했습니다. 이후의 대화 부분은 공식 사양에 기반한 절차이며, 필자의 환경에서는 검색 실행 예시까지는 실행하지 않았습니다.)

처음에는 그대로 codex라고 입력하면 로그인을 요청받습니다. **"Sign in with ChatGPT"**를 선택하여 사용 중인 ChatGPT 계정(Plus / Pro 등)으로 로그인하는 것이 공식적인 권장 사항입니다. API 키로도 이용할 수 있지만, 이는 추가 설정이 필요하므로 우선은 ChatGPT 로그인이 가장 쉬운 입구입니다.

codex
# → "Sign in with ChatGPT"를 선택하여 로그인

이 부분이 오늘의 주인공이자, 가장 해보길 권하는 "첫걸음"입니다. 10분이면 끝납니다.

할 일은 딱 세 가지입니다.

1. --search를 붙여서 실행하기
2. "최근 출시된 ○○의 변경점은?"이라고 딱 하나만 물어보기
3. 대화 로그(transcript)에서 실제로 검색이 수행되었는지 확인하기

먼저, --search를 붙여 실행합니다.

codex --search

실행했다면, 입력창에 최신 정보가 필요한 질문을 하나 던져보세요. 예를 들면 다음과 같습니다.

최근 업데이트된 어떤 프론트엔드 빌드 도구의
최신 안정 버전(stable version)과 주요 변경점 3가지만 알려줘.
출처 URL도 함께 제공해 줘.

포인트는 "출처 URL도 함께"라고 덧붙이는 것입니다. 이렇게 하면 AI가 어디를 보고 답했는지 알 수 있어, 나중에 스스로 교차 검증(fact-check)을 할 수 있습니다.

Codex는 검색 동작(어떤 검색을 했는지)을 다른 도구 호출과 함께 대화 로그(transcript)에 남기는 사양으로 되어 있습니다. 따라서 답이 돌아오면 로그 안에 검색이 실행된 흔적이 있는지 확인해 보세요. 그곳에 검색 단계가 보인다면 그것이 당신의 "첫 번째 성공"입니다. AI가 지금의 Web을 제대로 살펴보고 나서 말해 주었다는 체감을 얻게 되는 것이죠.

"매번 --search를 붙이는 걸 잊어버릴 것 같아요..." 하는 분들을 위해, 영구적으로 live 모드로 설정하는 방법도 한 줄 소개해 드립니다.

Codex의 개인 설정은 ~/.codex/config.toml 파일에 작성합니다 (~는 사용자의 홈 디렉토리를 의미합니다). 여기에 다음 한 줄을 추가하기만 하면 됩니다.

web_search = "live"

이렇게 하면 다음부터는 붙이지 않아도 live 모드로 동작합니다. 반대로 반드시 꺼두어야 하는 환경이라면 web_search = "disabled"로 설정하면 됩니다.

다만, 개인적으로는 **"평소에는 cached 상태로 유지하다가, 필요할 때만 --search"**를 사용하는 방식을 추천합니다. 이유는 다음 장에서 설명하겠습니다. 설정 파일에 대한 심층 분석은 오늘은 여기까지 하겠습니다. 주인공은 어디까지나

--search

하나에 집중하겠습니다. 처음에는 누구나 여기서 조금 막히곤 합니다. 괜찮습니다, 차근차근 살펴봅시다.

Q. 검색이 실행되고 있는 것 같지 않다

--search를 붙여서 실행했는지 다시 한번 확인해 보세요. 플래그는 codex --search와 같이 codex 직후에 붙입니다. 또한, 애초에 "최신 정보가 필요한 질문"이 아니면 AI가 검색을 사용하지 않겠다고 판단할 수도 있습니다. "어제/이번 주에 출시된 ~"와 같이 시기를 포함해서 질문하면 더 잘 작동합니다.

Q. 그래도 정보가 오래되었다

기본값인 cached는 인덱스(index)를 경유하기 때문에, 방금 나온 이야기는 반영이 늦어질 수 있습니다. 그럴 때야말로 live(--search)가 활약할 차례입니다. live는 "현재의 Web"을 가져옵니다.

Q. 회사의 규칙상 인터넷에 올리고 싶지 않다

web_search = "disabled"로 설정하면 Web 검색 도구 자체를 끌 수 있습니다. 사내 한정 정보만으로 작업을 완결하고 싶을 때는 이 방법이 안심됩니다.

Q. --search는 검색 명령어인가요?

아니요. 터미널에서 단독으로 입력하는 검색 명령어가 아니라, **Codex를 실행할 때 사용하는 플래그 (flag)**입니다.

codex --search와 세트로 사용합니다. 마지막으로, 가장 중요한 주의사항을 하나 말씀드리겠습니다.

공식 문서에서는 명확하게 밝히고 있습니다. Web 검색 결과는 신뢰할 수 없는 입력 (untrusted)으로 취급할 것.

생소한 용어일 수 있지만, 여기서 말하는 위험 중 하나가 바로 "프롬프트 인젝션 (Prompt Injection)"입니다. 간단히 말해, AI가 읽어들인 Web 페이지나 문서 안에 AI를 향한 악의적인 지시가 숨겨져 있어, AI가 무심코 그 지시를 따르게 되는 공격을 의미합니다.

cached 모드는 OpenAI가 관리하는 인덱스를 경유하는 만큼 이 리스크가 낮은 편입니다. 하지만 live는 "그 시점의 페이지"를 직접 가져오기 때문에, 리스크가 상대적으로 높아집니다. 그렇기 때문에 live로 얻은 내용은 무조건 믿지 말고, 출처 URL을 자신의 눈으로 직접 확인해야 합니다. 이 작은 수고만큼은 습관으로 들여두는 것이 안전합니다.

그리고 반론도 솔직하게 남겨두겠습니다. Web 검색이 항상 필요한 것은 아닙니다.

• 정답이 확정되어 있는 작은 태스크 (예: 이 함수의 버그를 수정해 줘 등) … cached 상태로도 충분합니다.
• 사내 또는 비공개 정보만으로 완결되는 작업 … 오히려 disabled가 안전합니다.

"최신 정보가 필요한가"에 따라 전환하기. 그것만으로도 속도와 안전의 균형이 훨씬 좋아집니다.

오늘의 내용을 3줄로 요약하면 다음과 같습니다.

평소에는 cached로 충분합니다. Web 검색은 이미 작동하고 있습니다. -
최신 정보가 필요한 한 번만 플래그를 붙입니다. 우선은 "출처 URL도 함께"라고 덧붙여 질문해 보세요. codex --search (live) -
live의 결과는 전적으로 신뢰하지 마세요. 출처를 직접 확인하는 습관을 들입니다.

우선 오늘, codex --search로 딱 한 문제만 질문해 보세요. AI가 "지금의 세계"를 보고 대답해 주는 느낌을 한 번 맛보고 나면, 아마 이전으로 돌아가기 힘드실 겁니다.

• Codex CLI 개요: https://developers.openai.com/codex/cli
• Config basics (web_search의 4가지 모드 및 --search = live 관련 내용): https://developers.openai.com/codex/local-config
• Web search (결과를 untrusted로 취급한다는 내용): https://developers.openai.com/codex/web-search
• 설치 / 로그인 절차 (공식 리포지토리 README): https://github.com/openai/codex

생성형 AI 활용 엔지니어이자 세 아이의 아빠. AI × 개발의 실전 지식을 매일 발신하고 있습니다 → X(구 Twitter)도 꼭 방문해 보세요.