aider 연동

터미널 AI 페어 프로그래밍 도구 aider에서 베이즈 Gateway의 AI 모델을 사용하는 방법을 안내합니다.

aider는 OpenAI 호환 형식으로 Gateway의 /v1/gateway/chat/completions/를 호출합니다. Base URL과 API 키를 지정하고, 모델 ID 앞에 openai/를 붙이면 됩니다.

공식 레퍼런스: aider — OpenAI compatible APIs

시작하기 전에 베이즈 API 키가 필요합니다. 인증 가이드에서 발급 방법을 확인해주세요.

설정

Gateway 주소와 API 키를 환경 변수로 지정합니다:

환경 변수 대신 실행할 때 --openai-api-base 옵션으로 Base URL을 넘겨도 됩니다.

실행

대화형으로 실행합니다:

한 번만 실행하고 끝내려면 --message를 사용합니다:

주요 형식 세부사항

옵션	값
`--model`	`openai/` + 모델 ID. 모델 ID는 `GET /v1/gateway/models/`가 반환하는 값을 그대로 씁니다 (예: `openai/claude-sonnet-5`)
`OPENAI_API_BASE` / `--openai-api-base`	Gateway Base URL (후행 슬래시 없음)
`OPENAI_API_KEY`	베이즈 API 키
`--edit-format`	편집 형식. `openai/` 모델은 기본값이 `whole`(파일 전체를 다시 출력)입니다. 긴 파일은 `diff`를 지정하면 바뀐 부분만 주고받습니다

aider가 컨텍스트 크기와 가격을 모르는 모델이면 시작할 때 Unknown context window size and costs 경고와 함께 claude-sonnet-5, vertex_ai/claude-sonnet-5 같은 다른 이름을 제안합니다. 동작에는 영향이 없으니 openai/ 접두사를 그대로 두세요. 접두사를 바꾸면 요청이 Gateway로 가지 않습니다. 경고는 --no-show-model-warnings로 숨길 수 있습니다. aider가 출력하는 Cost도 aider 자체 추정치이며, 실제로 차감되는 크레딧과 다릅니다.

트러블슈팅

증상	원인	해결
`litellm.AuthenticationError` (`401 authentication_error - Invalid API key`)	API 키가 없거나 잘못됨	`OPENAI_API_KEY`가 현재 셸에 설정되어 있는지, 값이 베이즈 API 키인지 확인해주세요.
`402` (`Credit balance exhausted`)	크레딧 잔액 없음	개발자 설정에서 크레딧을 충전해주세요.
`403 Model is not available through the Gateway API`	무료 모델이나 Super Agent를 지정	정책상 API로는 호출할 수 없습니다. 다른 유료 모델을 사용해주세요.
`404 Model not found`	존재하지 않는 모델 ID (오타·미제공 모델)	`--model`의 `openai/` 뒤가 Gateway `/models/` 목록에 있는 ID인지 확인해주세요.

참고

aider는 사용자가 추가한 파일을 편집하는 데 집중하는 도구입니다. 셸 명령은 /run, /test, --test-cmd(--auto-test), --lint-cmd처럼 직접 지정하거나 승인할 때만 실행합니다. 코드베이스 탐색·명령 실행까지 모델이 자유롭게 주도하는 작업에는 Claude Code나 OpenCode가 더 적합합니다
Claude 모델도 OpenAI 호환 경로로 호출되므로 프롬프트 캐시가 적용되지 않습니다. Claude로 긴 코딩 작업을 한다면 Anthropic 형식을 쓰는 Claude Code가 입력 비용이 적게 듭니다
전체 오류 목록은 에러 레퍼런스를 참고하세요

마지막 수정 날짜: Oct 07, 2026

/chat/completions