OpenCode 구성

OpenCode는 오픈소스 터미널 코딩 에이전트입니다. OpenAI 호환 엔드포인트라면 무엇이든 사용할 수 있으므로 CodeByAI API Key만 있으면 됩니다. 이 사이트를 사용자 지정 프로바이더로 선언하고 모델 중 하나를 선택하면 됩니다.

1. OpenCode 설치

macOS 또는 Linux:

1 curl -fsSL https://opencode.ai/install | bash

npm을 선호한다면:

1 npm install -g opencode-ai

Windows에서는 WSL을 권장합니다. 네이티브 설치도 npm install -g opencode-ai로 가능합니다.

2. 구성 파일 생성

OpenCode는 ~/.config/opencode/(전역) 또는 프로젝트 루트에서 opencode.json을 읽습니다. 전역 구성은 모든 곳에 적용되므로 여기서 시작하세요:

macOS / Linux: ~/.config/opencode/opencode.json
Windows: C:\Users\YourUserName\.config\opencode\opencode.json

다음 내용으로 파일을 생성하세요:

1 {
2   "$schema": "https://opencode.ai/config.json",
3   "model": "codebyai/gpt-5.6-terra",
4   "small_model": "codebyai/gpt-5.6-terra",
5   "provider": {
6     "codebyai": {
7       "npm": "@ai-sdk/openai-compatible",
8       "name": "CodeByAI",
9       "options": {
10         "baseURL": "https://www.codebyai.net/api/agent",
11         "apiKey": "{env:CODEBYAI_API_KEY}"
12       },
13       "models": {
14         "gpt-5.6-terra": {
15           "name": "GPT-5.6 Terra",
16           "limit": { "context": 200000, "output": 65536 }
17         }
18       }
19     }
20   }
21 }

몇 가지 알아두면 좋은 점이 있습니다:

npm은 통신 프로토콜을 선택합니다. @ai-sdk/openai-compatible은 OpenCode가 /chat/completions를 호출한다는 뜻입니다.
baseURL은 /api/agent에서 끝납니다. /v1을 덧붙이지 마세요: 게이트웨이는 해당 경로 뒤의 모든 내용을 업스트림 프로바이더로 전달하므로, /api/agent/v1/chat/completions는 404 page not found로 응답합니다.
models 아래의 키가 OpenCode가 전송할 모델 ID입니다. Model Plaza에서 원하는 모델을 추가할 수 있습니다. 예를 들면 gpt-6-astra입니다.
small_model은 의도적으로 명시했습니다. 그렇지 않으면 OpenCode는 같은 프로바이더에서 더 저렴한 모델을 찾고, 찾지 못하면 주 모델을 사용합니다. 이름을 지정하면 제목 생성 오류를 피할 수 있습니다.

3. API Key 제공

위 apiKey에서 사용한 변수를 내보내세요(먼저 API Keys 페이지에서 키를 생성하세요):

1 export CODEBYAI_API_KEY="sk-proj-xxxx"

이 줄을 ~/.zshrc 또는 ~/.bashrc에 추가하면 새 터미널이 모두 이 값을 상속받습니다. 환경 변수를 사용하지 않으려면 opencode auth login을 한 번 실행하고 거기에 키를 붙여넣으세요. apiKey를 생략하면 저장된 자격 증명이 사용됩니다.

4. OpenCode 시작

1 cd your-project
2 opencode --model codebyai/gpt-5.6-terra

대화형 인터페이스 없이 한 번만 질문하려면:

1 opencode run -m codebyai/gpt-5.6-terra "summarise the structure of this repository"

인터페이스 안에서 /models를 사용하면 구성에 선언한 모델 사이를 전환할 수 있습니다.

5. 문제 해결

응답에 404 page not found가 표시됨: baseURL이 /v1로 끝납니다. 이것을 제거하세요.
응답이 Hello! How can I help you with your software engineering tasks today?로 시작하는 경우(HTTP 403): 게이트웨이가 API 키를 받지 못했다는 뜻이며, OpenCode를 시작한 터미널에서 CODEBYAI_API_KEY가 비어 있습니다. Invalid key!라는 403 응답은 키 자체가 삭제되었거나 잘못 입력되었다는 뜻입니다.
잔액 부족: 지갑 페이지에서 충전하세요.
Claude 모델은 이 가이드의 Claude Code 페이지에서 구성하는 Anthropic 호환 엔드포인트로 제공됩니다. 이 페이지는 OpenAI 호환 경로를 다룹니다.

1	`{`
2	`"$schema": "https://opencode.ai/config.json",`
3	`"model": "codebyai/gpt-5.6-terra",`
4	`"small_model": "codebyai/gpt-5.6-terra",`
5	`"provider": {`
6	`"codebyai": {`
7	`"npm": "@ai-sdk/openai-compatible",`
8	`"name": "CodeByAI",`
9	`"options": {`
10	`"baseURL": "https://www.codebyai.net/api/agent",`
11	`"apiKey": "{env:CODEBYAI_API_KEY}"`
12	`},`
13	`"models": {`
14	`"gpt-5.6-terra": {`
15	`"name": "GPT-5.6 Terra",`
16	`"limit": { "context": 200000, "output": 65536 }`
17	`}`
18	`}`
19	`}`
20	`}`
21	`}`

1	`cd your-project`
2	`opencode --model codebyai/gpt-5.6-terra`