CLI 도구 개요
CLI는 특정 소프트웨어가 아닌 커맨드라인 도구를 통칭합니다. Claude Code, Codex CLI, Gemini CLI, OpenClaw, OpenCode 등이 모두 여기에 속합니다. 터미널에서 자연어로 입력하면 프로젝트를 읽고, 코드를 해석하며, 파일을 생성하고, 명령어를 실행하거나 개발 작업을 완료하도록 도와줍니다.
공식 정보 다운로드 및 문서는 공식 사이트를 기준으로 합니다.
CLI란 무엇이며 어떤 용도로 사용되나요
CLI 도구는 일반적인 챗봇 소프트웨어보다 강력하지만, 그만큼 잘못 사용하기도 쉽습니다. 초보자가 처음 설정할 때는 테스트용 프로젝트에서만 실행하고, "명령어를 실행하거나 파일을 수정하지 않고 코드 해석만 수행"하도록 설정하세요.
사전 준비 사항
| 준비 항목 | 설명 | 중요한 이유 |
|---|---|---|
| 터미널 | Windows는 PowerShell, macOS / Linux는 터미널(Terminal) 사용 | CLI는 전적으로 터미널에서 실행됨 |
| 도구 본체 | 먼저 Claude Code, Codex CLI, Gemini CLI, OpenClaw, OpenCode 등을 설치 | 설정 파일은 도구가 설치되어 있어야 적용됨 |
| 키 / 로그인 방식 | 공식 로그인, API Key, OAuth 또는 AI provider 키 등 | CLI마다 인증 방식이 다름 |
| Base URL | AI provider나 프록시를 경유할 때만 필요 | 프로토콜에 따라 주소 접미사(경로)가 다를 수 있으므로 도메인만 바꿔서는 안 됨 |
| 테스트 프로젝트 | 새 빈 폴더를 만들거나 기존 프로젝트를 복사하여 준비 | 초기 설정 중 실제 프로젝트가 훼손되는 것을 방지 |
AI provider 문서에 기재된 URL은 대개 예시일 뿐입니다. 실제로 입력할 때는 이용 중인 provider에서 제공하는 API 주소와 Key로 대체해야 합니다. 또한 OpenAI, Claude, Gemini 인터페이스가 별도로 제공되는 경우 세 주소를 혼용해서는 안 됩니다.
도구별 개별 가이드
Claude Code 설정 Claude Code의 Key, Base URL, 모델 및 settings.json 설정 안내.
Codex CLI 설정 Codex 터미널 도구의 config.toml, 커스텀 Provider 및 테스트 방법.
Gemini CLI 설정 Gemini CLI의 Google 로그인, API Key 및 AI provider 연동 시 주의사항.
OpenClaw 설정 OpenClaw의 baseUrl 및 api 필드 매칭 설정 방법.
OpenCode 설정 OpenCode의 연결 마법사, 설정 파일 위치 및 수동 설정 시 주의사항.
어떤 가이드를 확인해야 하나요
| 현재 진행하려는 작업 | 추천 가이드 | 이유 |
|---|---|---|
| 여러 CLI provider를 일괄 전환하고 싶은 경우 | CC-Switch 일반 절차 | CC-Switch는 여러 Provider를 중앙에서 관리하고 Claude, Codex, Gemini 등의 도구로 배포하는 데 적합합니다. |
| Claude Code만 단독으로 설정하려는 경우 | Claude Code 설정 | Claude Code의 경우 Anthropic/Claude 관련 Key, Base URL, 모델명, settings.json에 집중해야 합니다. |
| Codex CLI만 단독으로 설정하려는 경우 | Codex 설정 | Codex의 경우 config.toml, OpenAI 호환 Provider, 모델명 및 환경 변수에 집중해야 합니다. |
| Gemini CLI만 단독으로 설정하려는 경우 | Gemini 설정 | Gemini의 로그인 방식, Key, Vertex/Gemini 인터페이스는 OpenAI 호환 인터페이스와 다릅니다. |
| OpenClaw / OpenCode를 사용하는 경우 | OpenClaw / OpenCode | 두 도구의 Provider 설정 필드는 버전에 따라 달라질 수 있으므로 해당 페이지 및 공식 문서를 참조해야 합니다. |
설정 전 주의해야 할 위험 요소
| 위험 요소 | 발생 가능 위치 | 권장 대처 방법 |
|---|---|---|
| 도구가 프로젝트 파일을 읽을 수 있음 | Claude Code, Codex, Gemini, OpenClaw, OpenCode | 첫 실행 시 테스트 디렉터리에서 실행하고, 실제 프로덕션 프로젝트를 바로 열지 마세요. |
| 모델이 명령어를 실행하거나 제안할 수 있음 | 모든 코드 CLI 도구 | 우선 확인 모드를 켜두고 삭제(delete), 이동(move), 설치(install), 업로드(upload) 등의 동작이 있을 때 꼼꼼히 확인하세요. |
| 설정 항목 간 우선순위 충돌 | 시스템 환경 변수, 프로젝트 설정, 사용자 설정, CC-Switch | 설정이 적용되지 않을 때는 우선순위를 먼저 점검하고, 여러 곳을 동시에 수정하지 마세요. |
| 프로토콜 혼용 오류 | OpenAI, Claude, Gemini, Vertex, AI provider 호환 인터페이스 | 이용 중인 provider 백엔드에서 제공하는 인터페이스 규격에 맞춰 도구 설정 페이지에 입력하세요. |
| 다른 사람의 예시를 그대로 복사 | 서드파티 튜토리얼, 스크린샷, 지난 문서 | 예시에 있는 URL, Key, 모델명은 반드시 본인이 사용하는 provider 백엔드 정보로 변경해야 합니다. |
첫 번째 보안 테스트 진행 방법
설정이 완료된 후 CLI가 실제 프로젝트를 바로 수정하게 두지 마세요. 먼저 빈 디렉터리를 만들고 간단한 테스트 파일을 넣은 뒤, 도구가 파일을 수정하지 않고 읽고 해석하기만 하도록 요청하세요.
CLI에 전달할 수 있는 안전 테스트 명령어
Read only the current directory first. Tell me which files are here. Do not modify any files, run any commands, or install any dependencies.이 단계에서 정상적인 응답이 오지 않는다면 관련 문제 해결 가이드를 확인하세요. 설정이 정상적으로 작동하는지 확인하기 전에는 절대로 CLI가 실제 프로젝트를 자동 처리하도록 두지 마세요.