Aside 커스텀 프로바이더 설정 가이드: 원하는 모델을 5단계로 연결하기
Aside 설정의 Models → Connect → Add custom provider에 JSON 한 덩어리를 붙여넣으면, 기본 목록에 없는 모델도 Aside의 기본 모델로 쓸 수 있습니다. 이 글의 5단계를 따라 하면 Upstage Solar Pro 4 같은 모델을 연결하고 첫 대화까지 확인할 수 있습니다.
이 글은 이런 분께 필요합니다
- Aside를 쓰고 있고, 기본 목록에 없는 모델을 쓰고 싶은 분
- OpenRouter에서 특정 모델(스텔스 모델, 한국어 특화 모델 등)을 골라 쓰고 싶은 분
- Upstage처럼 OpenAI 호환 API를 제공하는 회사의 모델을 직접 연결하고 싶은 분
- Add custom provider에 붙여넣었는데
Provider authentication failed나400오류가 나서 막힌 분
준비물은 두 가지입니다. 쓰려는 서비스의 API 키와, 그 서비스의 모델 ID입니다. 모델 ID는 서비스 문서나 모델 페이지에 적혀 있습니다. 예를 들어 OpenRouter의 Solar Pro 4는 upstage/solar-pro4, Upstage에 직접 연결할 때는 solar-pro4입니다.
Step 1. 설정에서 Models 화면을 엽니다
Aside 설정을 열고 왼쪽 메뉴에서 Models를 누릅니다. 화면 위쪽 Providers 목록에 지금 연결된 서비스가 보이고, 목록 맨 아래에 + Connect 버튼이 있습니다.
Step 2. Connect → Add custom provider를 누릅니다
+ Connect를 누르면 연결할 수 있는 서비스 목록이 열립니다. 원하는 서비스가 이 목록에 있으면 그걸 고르면 됩니다. 목록에 없으면 맨 아래 + Add custom provider를 누릅니다.
입력 칸에는 "Paste a pi-compatible provider config"라는 안내가 나옵니다. Aside는 오픈소스 코딩 에이전트 pi와 같은 설정 형식을 쓰기 때문에, pi용으로 만든 설정을 그대로 붙여넣어도 됩니다.
Step 3. 설정 JSON을 붙여넣습니다
아래 두 예시 중 상황에 맞는 것을 복사하고, apiKey 값만 본인 키로 바꿔서 붙여넣습니다. 둘 다 Aside에서 직접 대화를 보내 응답까지 확인한 설정입니다.
예시 A. OpenRouter를 거쳐 연결하기 (가장 간단)
OpenRouter 키 하나로 OpenRouter에 올라온 모델을 골라 쓰는 방법입니다. 추가 옵션 없이 바로 동작합니다.
{
"providers": {
"openrouter-upstage": {
"name": "OpenRouter Solar Pro 4",
"baseUrl": "https://openrouter.ai/api/v1",
"apiKey": "sk-or-여기에_본인_OpenRouter_키",
"api": "openai-completions",
"authHeader": true,
"models": [
{
"id": "upstage/solar-pro4",
"name": "Solar Pro 4",
"reasoning": true,
"input": ["text"],
"contextWindow": 524288,
"maxTokens": 16384
}
]
}
}
}
다른 OpenRouter 모델을 쓰려면 id만 모델 페이지 주소의 이름(예: stealth/space-bunny-alpha)으로 바꾸면 됩니다.
예시 B. Upstage에 직접 연결하기
Upstage 콘솔에서 받은 키로 직접 연결하는 방법입니다. 예시 A와 달리 compat 두 줄이 꼭 필요합니다. 이 두 줄이 없으면 400 오류가 납니다. 이유는 아래 오류 해결 표에 정리했습니다.
{
"providers": {
"upstage": {
"name": "Upstage",
"baseUrl": "https://api.upstage.ai/v1",
"apiKey": "up_여기에_본인_Upstage_키",
"api": "openai-completions",
"authHeader": true,
"compat": {
"supportsStore": false,
"supportsDeveloperRole": false
},
"models": [
{
"id": "solar-pro4",
"name": "Solar Pro 4",
"reasoning": true,
"input": ["text"],
"contextWindow": 524288,
"maxTokens": 16384
}
]
}
}
}
바꿔야 하는 칸만 정리하면
| 칸 | 넣을 값 |
|---|---|
providers 아래 이름 (upstage 등) | 영문 소문자와 하이픈으로 된 이름. Providers 목록에 이 이름이 표시됩니다(openrouter-upstage → Openrouter Upstage). 다른 프로바이더와 겹치지 않게 짓습니다 |
name | 프로바이더를 알아보기 쉬운 이름 |
baseUrl | 서비스의 OpenAI 호환 주소. /v1까지만 쓰고 /chat/completions는 붙이지 않습니다 |
apiKey | 실제 API 키 문자열 |
models[].id | 서비스가 받는 모델 ID |
models[].name | 모델 선택 목록에 보일 이름 |
contextWindow, maxTokens | 모델 페이지에 적힌 컨텍스트 길이와 최대 출력 토큰 |
apiKey에는 키 문자열을 그대로 넣는 방법을 권합니다. pi 형식은 환경변수 이름도 받지만, Aside 앱에는 터미널에서 설정한 환경변수가 전달되지 않을 수 있어 인증 실패로 이어지기 쉽습니다.
Step 4. 목록에 뜬 모델을 기본 모델로 고릅니다
저장하면 Providers 목록에 새 프로바이더가 추가됩니다. 위 예시 A라면 "Openrouter Upstage"라는 이름으로 보입니다. 같은 Models 화면 아래 Task models → Default model 드롭다운을 열면 새 모델(models[].name에 적은 이름)을 고를 수 있습니다. 화면 설명("The last used model becomes the default for new chat")처럼 마지막에 쓴 모델이 새 대화의 기본값이 됩니다. 다른 모델로 대화하면 기본값도 그 모델로 바뀐다는 점만 알아두면 됩니다.
Step 5. 짧은 질문으로 연결을 확인합니다
새 대화를 열고 답이 정해진 짧은 질문을 보내 봅니다. 예를 들면 이런 질문입니다.
An $80 item gets a 20% discount, then 10% tax is added. What is the final price? Answer with only the dollar amount.
$70.40이 돌아오면 연결이 끝난 것입니다. 오류가 나면 아래 표에서 같은 메시지를 찾아 설정을 고칩니다.
오류가 나면 여기부터 확인하세요
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
Provider authentication failed | apiKey가 빠졌거나, 환경변수 이름이 들어가 있어 키가 전달되지 않음 | apiKey에 실제 키 문자열을 넣습니다 |
400: Unrecognized request arguments supplied: store | Aside가 보내는 store 필드를 서비스가 모름 | "compat": { "supportsStore": false }를 추가합니다 |
400: The 'role' value 'developer' must be one of ['system', 'assistant', 'user', 'tool'] | 시스템 프롬프트를 developer 역할로 보내는데 서비스가 지원하지 않음 | compat에 "supportsDeveloperRole": false를 추가합니다 |
Upstage에 직접 연결하면 두 번째와 세 번째 오류가 차례로 나옵니다. store를 끄고 나면 다음 요청에서 developer 오류가 나오기 때문에, 처음부터 예시 B처럼 두 옵션을 함께 넣는 편이 빠릅니다. compat는 pi 문서의 OpenAI Compatibility 항목에 전체 목록이 있습니다. 다른 서비스를 연결하다 비슷한 400 오류를 만나면, 오류에 나온 필드 이름으로 이 목록에서 맞는 옵션을 찾으면 됩니다.
정리
Aside에 원하는 모델을 붙이는 과정은 Models → Connect → Add custom provider → JSON 붙여넣기 → Default model 선택 다섯 단계입니다. OpenRouter를 거치면 옵션 없이 바로 되고, Upstage처럼 직접 연결할 때는 compat 두 줄만 더 넣으면 됩니다. 막히면 오류 메시지를 위 표에서 찾아보세요.