# 연동

> 연동 섹션의 목차입니다. OpenAI SDK, Anthropic SDK, Vercel AI SDK, LangChain, PydanticAI는 각각 별도 페이지로 있고, 코딩 도구 여섯 개(Claude Code, Codex CLI, Hermes Agent, OpenCode, OpenClaw, Cursor)의 설정은 이 페이지에 있습니다.

Source: https://kiln.bricksum.com/docs/ko/integrations

OpenAI 호환 또는 Anthropic 호환 클라이언트가 있는 도구라면 무엇이든 Kiln에 연결할 수 있습니다. base URL을 https://api.bricksum.com/v1으로 설정하고 sk-bk-로 시작하는 키를 넣으세요. 아래에 SDK별 페이지가 하나씩 있고, 각 페이지의 스니펫은 실제 API로 실행해 확인한 것입니다. 그다음은 코딩 도구입니다.

참고

qwen3-32b에서는 구조화 출력(response_format)을 사용할 수 없습니다. qwen3-32b에서는 강제 툴 선택이 명확한 에러 없이 실패합니다(2026-09-26 실측). tool_choice를 "required"로 보내면 본문이 평문 "Internal Server Error"인 HTTP 500이 오고, 함수를 지정하면 arguments가 빈 200(finish_reason "stop")이 옵니다. 둘 다 4xx가 아니므로 재시도로 해결되지 않습니다. tool_choice는 "auto"만 보내세요. qwen3-32b에서는 parallel_tool_calls 설정이 적용되지 않습니다. 이는 응답에 툴 호출이 하나만 온다는 뜻이 아닙니다. parallel_tool_calls: false를 보내도 한 응답에 툴 호출이 여러 건 올 수 있습니다. tool_calls의 모든 항목에 각각 tool 메시지로 답하세요. 모든 툴에 description을 넣으세요. 이를 실측한 gpt-oss-120b에서는 description이 없는 툴이 400으로 거부됩니다. 모델은 답하기 전에 추론하며(thinking 모드) 그 토큰도 max_tokens에 포함되므로 둘 다 들어갈 여유를 두세요. SDK 예제의 800은 이 모델에서 측정하지 않은 시작값이므로, content가 비고 finish_reason이 "length"이면 늘리세요. 다른 모델은 동작이 다르므로 [모델](https://kiln.bricksum.com/docs/ko/models) 페이지를 참고하세요.

## SDK

각 페이지는 일부러 짧게 썼습니다. 무엇을 설치하는지, 실제 API로 실행해 확인한 호출 하나, 그리고 Kiln에서 다른 점 두세 가지입니다. SDK가 공통으로 쓰는 내용은 다섯 페이지에 반복하지 않고 API 레퍼런스에 모아 두었습니다.

[OpenAI SDK가이드 열기](https://kiln.bricksum.com/docs/ko/sdks/openai)[Anthropic SDK가이드 열기](https://kiln.bricksum.com/docs/ko/sdks/anthropic)[Vercel AI SDK가이드 열기](https://kiln.bricksum.com/docs/ko/sdks/vercel-ai)[LangChain가이드 열기](https://kiln.bricksum.com/docs/ko/sdks/langchain)[PydanticAI가이드 열기](https://kiln.bricksum.com/docs/ko/sdks/pydantic-ai)

## 코딩 도구

Claude Code, Codex CLI, Hermes Agent, OpenCode, OpenClaw, Cursor는 각각 짧은 설정 변경으로 연결됩니다. 스니펫은 이 페이지에 있으며, 로그인하면 [콘솔 → 도구 연결](https://kiln.bricksum.com/app/tools)에서도 같은 스니펫을 볼 수 있습니다. 이 도구들의 에이전트 모드는 위에서 설명한 자동 툴 선택에 의존합니다.

참고

Kiln은 Chat Completions API, Responses API, Anthropic Messages API를 제공합니다. Codex CLI는 Responses API로, Claude Code는 Messages API로 중간 라우터 없이 연결합니다. Hermes Agent와 OpenClaw는 custom OpenAI-compatible provider로 설정합니다. qwen3-32b의 컨텍스트 길이는 32,768 토큰이고, 에이전트의 시스템 프롬프트와 툴 정의가 첫 메시지 전에 그중 상당 부분을 차지합니다. 아래 Claude Code, Codex CLI, OpenCode 및 OpenClaw 설정은 도구가 제때 압축하도록 이 크기를 명시합니다. OpenCode는 그중 8,192을 응답용으로 남기고 24,576에서 압축합니다. limit.output에 더한 토큰은 그만큼 프롬프트 창에서 빠집니다. 응답이 finish_reason "length"로 끊기면 limit.output을 늘리되 16,384 이하로 두세요. 그래야 프롬프트에 16,384이 남습니다. 키는 커밋되는 파일이 아닌 환경 변수 또는 시크릿 관리자에 보관하세요. 짧은 프롬프트로 먼저 확인한 뒤 콘솔 → 사용량에서 요청을 확인합니다.

[Claude Code가이드 열기](#claude-code)[Codex CLI가이드 열기](#codex)[Hermes Agent가이드 열기](#hermes)[OpenCode가이드 열기](#opencode)[OpenClaw가이드 열기](#openclaw)[Cursor가이드 열기](#cursor)

### Claude Code

Claude Code는 Anthropic Messages API를 사용하고 Kiln이 이를 직접 제공하므로 router 없이 연결합니다. ANTHROPIC_BASE_URL에 Kiln API 오리진을, ANTHROPIC_AUTH_TOKEN에 Kiln 키를 넣고 ANTHROPIC_MODEL과 ANTHROPIC_DEFAULT_*_MODEL 슬롯을 모두 Kiln 모델 ID로 지정하세요.

[엔드포인트 레퍼런스: Messages API](https://kiln.bricksum.com/docs/ko/api-reference/messages)

**Claude Code**
```bash
# Claude Code connects to Kiln directly — Kiln serves the Anthropic Messages API.
# Put these in your shell profile (or a direnv file); never commit the key.
export ANTHROPIC_BASE_URL="https://api.bricksum.com"
export ANTHROPIC_AUTH_TOKEN="sk-bk-..."   # your Kiln API key

# Claude Code picks a model per task slot — point every slot at Kiln's model.
export ANTHROPIC_MODEL="qwen3-32b"
export ANTHROPIC_DEFAULT_OPUS_MODEL="qwen3-32b"
export ANTHROPIC_DEFAULT_SONNET_MODEL="qwen3-32b"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="qwen3-32b"

# Claude Code does not know this model, so it assumes a 200k context window and
# lets the session grow past what the upstream accepts. Tell it the real one —
# its own system prompt and tools take a large share of it, so it compacts early.
export CLAUDE_CODE_MAX_CONTEXT_TOKENS=32768

claude
```

[Claude Code 공식 문서](https://docs.claude.com/en/docs/claude-code/settings)와 대조해 확인한 날짜: 2026-09-20

### Codex CLI

Codex CLI는 ~/.codex/config.toml에서 provider 블록을 읽고 Responses API(wire_api = "responses")로 Kiln과 통신합니다. Codex를 시작하기 전에 셸에 KILN_API_KEY를 설정하고 Kiln 카탈로그의 모델 ID를 그대로 사용하세요.

**~/.codex/config.toml**
```toml
model = "qwen3-32b"
model_provider = "kiln"
# The model's real window; Codex's own prompt and tools take a large share of it.
model_context_window = 32768

[model_providers.kiln]
name = "Kiln"
base_url = "https://api.bricksum.com/v1"
env_key = "KILN_API_KEY"
# Codex speaks the Responses API (Kiln serves POST /v1/responses); "chat" is gone.
wire_api = "responses"
```

```bash
# Set this in your shell profile, never commit it.
export KILN_API_KEY="sk-bk-..."

codex
```

[Codex CLI 공식 문서](https://github.com/openai/codex/blob/main/docs/config.md)와 대조해 확인한 날짜: 2026-09-18

### Hermes Agent

Hermes Agent는 OpenAI 호환 엔드포인트를 위한 custom provider 경로를 제공합니다. config.yaml에 엔드포인트와 모델을 저장하고 OPENAI_API_KEY로 키를 전달하면 세션이 바뀌어도 설정이 유지됩니다.

**~/.hermes/config.yaml**
```yaml
model:
  provider: custom
  default: qwen3-32b
  base_url: https://api.bricksum.com/v1
```

```bash
# Set this in your shell profile, never commit it.
export OPENAI_API_KEY="sk-bk-..."

# Start Hermes, then send a short test prompt.
hermes
```

[Hermes Agent 공식 문서](https://github.com/NousResearch/hermes-agent)와 대조해 확인한 날짜: 2026-09-15

### OpenCode

OpenCode는 opencode.json에서 OpenAI 호환 provider 패키지를 사용합니다. 같은 provider 설정을 터미널과 데스크톱 워크플로우에 적용할 수 있습니다.

**opencode.json**
```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "kiln": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Kiln",
      "options": {
        "baseURL": "https://api.bricksum.com/v1",
        "apiKey": "{env:KILN_API_KEY}"
      },
      "models": {
        "qwen3-32b": {
          "name": "qwen3-32b",
          "limit": { "context": 32768, "output": 8192 }
        }
      }
    }
  }
}
```

```bash
# Set this in your shell profile, never commit it.
export KILN_API_KEY="sk-bk-..."

opencode
```

[OpenCode 공식 문서](https://opencode.ai/docs/config/)와 대조해 확인한 날짜: 2026-09-15

### OpenClaw

OpenClaw는 models.providers 아래에 custom provider를 등록합니다. Kiln은 openai-completions adapter를 사용하고, 선언한 모델을 kiln/qwen3-32b로 에이전트 기본값에 지정합니다.

**~/.openclaw/openclaw.json**
```json
{
  "models": {
    "mode": "merge",
    "providers": {
      "kiln": {
        "baseUrl": "https://api.bricksum.com/v1",
        "apiKey": "${KILN_API_KEY}",
        "api": "openai-completions",
        "models": [
          {
            "id": "qwen3-32b",
            "name": "qwen3-32b",
            "contextWindow": 32768
          }
        ]
      }
    }
  },
  "agents": {
    "defaults": { "model": { "primary": "kiln/qwen3-32b" } }
  }
}
```

```bash
# Set this in your shell profile, never commit it.
export KILN_API_KEY="sk-bk-..."
```

[OpenClaw 공식 문서](https://docs.openclaw.ai/configuration)와 대조해 확인한 날짜: 2026-09-15

### Cursor

Cursor Settings → Models에서 Kiln 키를 입력하고 Override OpenAI Base URL을 켠 뒤, Kiln 모델 ID를 추가해 선택하세요.

**Cursor**
```text
Cursor → Settings → Models

1. "OpenAI API Key" 에 Kiln API 키 입력 (sk-bk-...)
2. "Override OpenAI Base URL" 활성화
   → https://api.bricksum.com/v1
3. 모델 목록에 qwen3-32b 추가 후 선택
```

[Cursor 공식 문서](https://docs.cursor.com/settings/models)와 대조해 확인한 날짜: 2026-09-15

## 쿡북

이 연동을 처음부터 끝까지 활용하는 레시피(스트리밍 채팅 CLI 등)는 쿡북에 있습니다. [쿡북 보기 →](https://kiln.bricksum.com/docs/ko/cookbook)