---
title: LSP 서버
description: OpenCode는 LSP 서버와 통합됩니다.
---

OpenCode는 Language Server Protocol(LSP) 서버와 통합해 진단 정보를 agent의 피드백으로 사용할 수 있습니다.

---

## 기본 제공 (Built-in)

OpenCode는 널리 사용되는 언어를 위해 여러 built-in LSP 서버를 제공합니다.

| LSP 서버           | 확장자                                                              | 요구 사항                                                  |
| ------------------ | ------------------------------------------------------------------- | ---------------------------------------------------------- |
| astro              | .astro                                                              | Astro 프로젝트에서 자동 설치                               |
| bash               | .sh, .bash, .zsh, .ksh                                              | `bash-language-server` 자동 설치                           |
| clangd             | .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++                | C/C++ 프로젝트에서 자동 설치                               |
| csharp             | .cs                                                                 | `.NET SDK` 설치됨                                          |
| clojure-lsp        | .clj, .cljs, .cljc, .edn                                            | `clojure-lsp` 명령 사용 가능                               |
| dart               | .dart                                                               | `dart` 명령 사용 가능                                      |
| deno               | .ts, .tsx, .js, .jsx, .mjs                                          | `deno` 명령 사용 가능 (`deno.json`/`deno.jsonc` 자동 감지) |
| elixir-ls          | .ex, .exs                                                           | `elixir` 명령 사용 가능                                    |
| eslint             | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue                  | 프로젝트에 `eslint` dependency 존재                        |
| fsharp             | .fs, .fsi, .fsx, .fsscript                                          | `.NET SDK` 설치됨                                          |
| gleam              | .gleam                                                              | `gleam` 명령 사용 가능                                     |
| gopls              | .go                                                                 | `go` 명령 사용 가능                                        |
| hls                | .hs, .lhs                                                           | `haskell-language-server-wrapper` 명령 사용 가능           |
| jdtls              | .java                                                               | `Java SDK (version 21+)` 설치됨                            |
| julials            | .jl                                                                 | `julia` 및 `LanguageServer.jl` 설치됨                      |
| kotlin-ls          | .kt, .kts                                                           | Kotlin 프로젝트에서 자동 설치                              |
| lua-ls             | .lua                                                                | Lua 프로젝트에서 자동 설치                                 |
| nixd               | .nix                                                                | `nixd` 명령 사용 가능                                      |
| ocaml-lsp          | .ml, .mli                                                           | `ocamllsp` 명령 사용 가능                                  |
| oxlint             | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte | 프로젝트에 `oxlint` dependency 존재                        |
| php intelephense   | .php                                                                | PHP 프로젝트에서 자동 설치                                 |
| prisma             | .prisma                                                             | `prisma` 명령 사용 가능                                    |
| pyright            | .py, .pyi                                                           | `pyright` dependency 설치됨                                |
| ruby-lsp (rubocop) | .rb, .rake, .gemspec, .ru                                           | `ruby` 및 `gem` 명령 사용 가능                             |
| rust               | .rs                                                                 | `rust-analyzer` 명령 사용 가능                             |
| sourcekit-lsp      | .swift, .objc, .objcpp                                              | `swift` 설치됨 (macOS에서는 `xcode`)                       |
| svelte             | .svelte                                                             | Svelte 프로젝트에서 자동 설치                              |
| terraform          | .tf, .tfvars                                                        | GitHub releases에서 자동 설치                              |
| tinymist           | .typ, .typc                                                         | GitHub releases에서 자동 설치                              |
| typescript         | .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts                        | 프로젝트에 `typescript` dependency 존재                    |
| vue                | .vue                                                                | Vue 프로젝트에서 자동 설치                                 |
| yaml-ls            | .yaml, .yml                                                         | Red Hat `yaml-language-server` 자동 설치                   |
| zls                | .zig, .zon                                                          | `zig` 명령 사용 가능                                       |

LSP는 기본적으로 비활성화되어 있습니다. 활성화하면 위 확장자 중 하나가 감지되고 요구 사항이 충족될 때 서버가 시작됩니다.

:::note
`OPENCODE_DISABLE_LSP_DOWNLOAD` 환경 변수를 `true`로 설정하면 LSP 서버 자동 다운로드를 비활성화할 수 있습니다.
:::

---

## 작동 방식

LSP가 활성화되어 있고 OpenCode가 파일을 열면 다음과 같이 동작합니다.

1. 활성화된 모든 LSP 서버에 대해 파일 확장자를 확인합니다.
2. 적절한 LSP 서버가 아직 실행 중이지 않다면 시작합니다.

---

## 모범 사례

LSP는 언어 서버의 진단을 제공해 agent가 문제를 찾고 수정하는 데 도움을 줄 수 있습니다. 일부 프로젝트에서는 유용하지만 항상 순이익이 되는 것은 아닙니다.

언어 서버는 동기화가 어긋나거나 많은 메모리를 사용하거나 버전 또는 프로젝트에 따라 다르게 동작하고 agent 워크플로를 느리게 만들 수 있습니다. 많은 프로젝트에서는 agent가 lint, typecheck 또는 다른 진단용 CLI 도구를 직접 실행하게 하는 편이 더 좋습니다. 이렇게 하면 이러한 트레이드오프 없이 오류가 agent 루프로 다시 전달됩니다. agent가 무엇을 실행해야 하는지 알 수 있도록 해당 명령을 `AGENTS.md` 또는 skills 같은 instruction files에 문서화하세요. 프로젝트가 추가 언어 서버 피드백의 이점을 얻을 때 LSP를 활성화하세요.

---

## 구성

OpenCode config의 `lsp` 섹션에서 LSP 서버를 활성화하고 사용자 정의할 수 있습니다.

모든 내장 LSP 서버를 활성화하려면 `lsp`를 `true`로 설정하세요.

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": true
}
```

객체를 사용하면 내장 서버를 활성화한 상태로 유지하면서 오버라이드나 사용자 정의 서버를 구성할 수 있습니다.

```json title="opencode.json"
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {}
}
```

각 LSP 서버는 다음 속성을 지원합니다.

| 속성             | 타입     | 설명                                          |
| ---------------- | -------- | --------------------------------------------- |
| `disabled`       | boolean  | LSP 서버를 비활성화하려면 `true`로 설정하세요 |
| `command`        | string[] | LSP 서버를 시작하는 명령입니다                |
| `extensions`     | string[] | 이 LSP 서버가 처리할 파일 확장자입니다        |
| `env`            | object   | 서버 시작 시 설정할 환경 변수입니다           |
| `initialization` | object   | LSP 서버로 전송할 초기화 옵션입니다           |

예시를 살펴보겠습니다.

---

### 환경 변수

`env` 속성을 사용하면 LSP 서버 시작 시 환경 변수를 설정할 수 있습니다.

```json title="opencode.json" {5-7}
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "rust": {
      "env": {
        "RUST_LOG": "debug"
      }
    }
  }
}
```

---

### 초기화 옵션

`initialization` 속성을 사용해 LSP 서버에 초기화 옵션을 전달하세요. 이 값은 LSP `initialize` 요청 중에 전송되는 서버별 설정입니다.

```json title="opencode.json" {5-9}
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "initialization": {
        "preferences": {
          "importModuleSpecifierPreference": "relative"
        }
      }
    }
  }
}
```

:::note
초기화 옵션은 LSP 서버마다 다릅니다. 사용 가능한 옵션은 해당 LSP 서버 문서를 확인하세요.
:::

---

### LSP 서버 비활성화

`lsp`를 생략하면 모든 LSP 서버가 비활성화됩니다. 다른 config에서 활성화한 모든 LSP 서버를 비활성화하려면 `lsp`를 `false`로 설정하세요.

```json title="opencode.json" {3}
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": false
}
```

**특정** LSP 서버를 비활성화하려면 `disabled`를 `true`로 설정하세요.

```json title="opencode.json" {5}
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "disabled": true
    }
  }
}
```

---

## 사용자 정의 LSP 서버

명령과 파일 확장자를 지정해 사용자 정의 LSP 서버를 추가할 수 있습니다.

```json title="opencode.json" {4-7}
{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "custom-lsp": {
      "command": ["custom-lsp-server", "--stdio"],
      "extensions": [".custom"]
    }
  }
}
```

---

## 추가 정보

### PHP Intelephense

PHP Intelephense는 라이선스 키를 통해 프리미엄 기능을 제공합니다. 텍스트 파일에 키만 저장해 라이선스 키를 제공할 수 있습니다.

- macOS/Linux: `$HOME/intelephense/license.txt`
- Windows: `%USERPROFILE%/intelephense/license.txt`

파일에는 추가 내용 없이 라이선스 키만 포함하는 것이 좋습니다.
