# 기본 설정(번들 CLI)

Node.js 및 .NET SDK에는 Copilot CLI가 종속성으로 포함됩니다. 앱은 추가 설치 또는 구성 없이 필요한 모든 항목을 제공합니다.

<!-- markdownlint-disable GHD046 GHD005 -->

<!-- Suppressed: GHD046 (outdated release terminology), GHD005 (hardcoded data variable) -->

Python SDK는 설치 후 일회성 다운로드 단계를 권장합니다.

```bash
python -m copilot download-runtime
```

일치하는 런타임을 다운로드하고 로컬로 캐시합니다. 이 단계를 건너뛰면 SDK는 대체(fallback)로 처음 사용할 때 자동으로 다운로드하려고 시도합니다.

**최적 대상:** 대부분의 애플리케이션은 데스크톱 앱, 독립 실행형 도구, CLI 유틸리티, 프로토타입 등입니다.

## 작동 방식

SDK를 설치하면 Copilot 런타임은 자동으로 포함되거나(Node.js, .NET) `python -m copilot download-runtime`를 통해 다운로드됩니다(Python). SDK는 자식 프로세스로 시작하고 stdio를 통해 통신합니다. 구성할 추가 항목은 없습니다.

![다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.](/assets/images/help/copilot/copilot-sdk/setup-bundled-cli-diagram-0.png)

**주요 특징:**

* CLI 이진 파일이 SDK에 포함되어 있습니다. 별도의 설치가 필요하지 않습니다.
* SDK는 호환성을 보장하기 위해 CLI 버전을 관리합니다.
* 사용자가 앱을 통해 인증(또는 env vars/BYOK 사용)
* 세션은 머신에서 사용자별로 관리됩니다.

## 빠른 시작

<div class="ghd-codetabs">
<div class="ghd-codetab" data-lang="typescript" data-label="TypeScript"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">TypeScript</div>

```typescript
import { CopilotClient } from "@github/copilot-sdk";

const client = new CopilotClient();

const session = await client.createSession({ model: "gpt-5.4" });
const response = await session.sendAndWait({ prompt: "Hello!" });
console.log(response?.data.content);

await client.stop();
```

</div>

<div class="ghd-codetab" data-lang="python" data-label="Python"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Python</div>

```python
from copilot import CopilotClient
from copilot.session import PermissionHandler

client = CopilotClient()
await client.start()

session = await client.create_session(on_permission_request=PermissionHandler.approve_all, model="gpt-5.4")
response = await session.send_and_wait("Hello!")
print(response.data.content)

await client.stop()
```

</div>

<div class="ghd-codetab" data-lang="go" data-label="Go"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Go</div>

> \[!NOTE]
> Node.js, Python 및 .NET 달리 Go SDK는 CLI를 자동 종속성으로 포함하지 않습니다. 명시적 경로가 없으면 `NewClient(nil)`는 사용 가능한 경우 내장된 CLI를 사용한 다음, `copilot`에서는 `PATH`를 대신 사용합니다. CLI를 포함하려면 빌드 시 [번더 도구를](https://github.com/github/copilot-sdk/tree/main/go/README.md#distributing-your-application-with-an-embedded-github-copilot-cli) 실행합니다.
> `COPILOT_CLI_PATH`을(를) 설정하거나 `Connection`이(가) 기존 바이너리를 가리키도록 할 수도 있습니다. 자세한 내용을 보려면 [로컬 CLI 설정](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/local-cli)(을)를 참조하세요.

```golang
client := copilot.NewClient(nil)
if err := client.Start(ctx); err != nil {
    log.Fatal(err)
}
defer client.Stop()

session, _ := client.CreateSession(ctx, &copilot.SessionConfig{Model: "gpt-5.4"})
response, _ := session.SendAndWait(ctx, copilot.MessageOptions{Prompt: "Hello!"})
if d, ok := response.Data.(*copilot.AssistantMessageData); ok {
    fmt.Println(d.Content)
}
```

</div>

<div class="ghd-codetab" data-lang="dotnet" data-label=".NET"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">.NET</div>

```csharp
await using var client = new CopilotClient();
await using var session = await client.CreateSessionAsync(
    new SessionConfig { Model = "gpt-5.4" });

var response = await session.SendAndWaitAsync(
    new MessageOptions { Prompt = "Hello!" });
Console.WriteLine(response?.Data.Content);
```

</div>

<div class="ghd-codetab" data-lang="java" data-label="Java"><div class="ghd-codetab-fallback-label" role="heading" aria-level="3">Java</div>

> \[!NOTE]
> Java SDK는 Copilot CLI를 번들하거나 포함하지 않습니다. CLI를 별도로 설치한 다음 `copilot`에서 `PATH`를 사용할 수 있게 하거나, `setCliPath(...)`로 해당 위치를 지정하거나, `setCliUrl(...)`로 실행 중인 CLI 서버에 연결하세요.

```java
import com.github.copilot.CopilotClient;
import com.github.copilot.rpc.*;

var client = new CopilotClient(new CopilotClientOptions()
    // Point to the CLI binary installed on the system
    .setCliPath("/path/to/vendor/copilot")
);
client.start().get();

var session = client.createSession(new SessionConfig()
    .setModel("gpt-5.4")
    .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)
).get();

var response = session.sendAndWait(new MessageOptions()
    .setPrompt("Hello!")).get();
System.out.println(response.getData().content());

client.stop().get();
```

</div>

</div>

## 인증 전략

사용자가 인증하는 방법을 결정해야 합니다. 일반적인 패턴은 다음과 같습니다.

![다이어그램: 설명된 프로세스를 보여 주는 순서도입니다.](/assets/images/help/copilot/copilot-sdk/setup-bundled-cli-diagram-1.png)

### 옵션 A: 사용자의 로그인 자격 증명(가장 간단한)

사용자가 CLI에 한 번 로그인하면 앱에서 해당 자격 증명을 사용합니다. 추가 코드가 필요하지 않습니다. 기본 동작입니다.

```typescript
const client = new CopilotClient();
// Default: uses signed-in user credentials
```

### 옵션 B: 환경 변수를 통한 토큰

토큰을 설정하거나 프로그래밍 방식으로 설정하는 지침과 함께 앱을 제공합니다.

```typescript
const client = new CopilotClient({
    env: {
        COPILOT_GITHUB_TOKEN: getUserToken(),  // Your app provides the token
    },
});
```

### 옵션 C: BYOK(GitHub 인증 필요 없음)

고유한 모델 공급자 키를 관리하는 경우 사용자는 GitHub 계정이 전혀 필요하지 않습니다.

```typescript
const client = new CopilotClient();

const session = await client.createSession({
    model: "gpt-5.4",
    provider: {
        type: "openai",
        baseUrl: "https://api.openai.com/v1",
        apiKey: process.env.OPENAI_API_KEY,
    },
});
```

자세한 내용은 **[BYOK(사용자 고유의 키 가져오기)](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/auth/byok)** 을 참조하세요.

## 세션 관리

앱은 일반적으로 사용자가 대화를 다시 시작할 수 있도록 명명된 세션을 원합니다.

```typescript
const client = new CopilotClient();

// Create a session tied to the user's project
const sessionId = `project-${projectName}`;
const session = await client.createSession({
    sessionId,
    model: "gpt-5.4",
});

// User closes app...
// Later, resume where they left off
const resumed = await client.resumeSession(sessionId);
```

세션 상태는 .에 `~/.copilot/session-state/{sessionId}/`유지됩니다.

## 이동 시기

| 필요                                                                                            | 다음 가이드 |
| --------------------------------------------------------------------------------------------- | ------ |
| GitHub 계정으로 로그인하는 사용자                                                                         |        |
| [GitHub OAuth 설정](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/github-oauth) |        |
| 사용자 컴퓨터 대신 서버에서 실행                                                                            |        |
| [백 엔드 서비스 설정](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/setup/backend-services) |        |
| 사용자 고유의 모델 키 사용                                                                               |        |
| [BYOK(사용자 고유의 키 가져오기)](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/auth/byok)     |        |

## 다음 단계

* **[BYOK(사용자 고유의 키 가져오기)](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/auth/byok)**: 사용자 고유의 모델 공급자 키 사용
* **[세션 다시 시작 및 지속성](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/session-persistence)**: 고급 세션 관리
* **[첫 번째 Copilot 기반 앱 빌드](/ko/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started)**: 전체 앱 빌드