OpenCode LSP Server Configuration

OpenCode deeply integrates with the Language Server Protocol (LSP), using LSP servers to provide LLMs with real-time feedback such as code diagnostics and error hints, helping AI understand and operate your codebase more accurately.

In simple terms, an LSP server is a component that gives OpenCode the ability to "read code," similar to plugins in VS Code that provide code completion and error hints. When a syntax error or type mismatch appears in a file, the LSP server feeds this diagnostic information back to the LLM, enabling it to make more accurate modifications.

How It Works

OpenCode's LSP integration is fully automatic and requires no manual intervention. When OpenCode opens a file, it performs the following process in sequence:

打开文件
  │
  ▼
读取文件扩展名（如 .ts、.py、.go）
  │
  ▼
与所有已启用的 LSP 服务器进行匹配
  │
  ├── 匹配成功且服务器已运行 → 直接使用
  │
  └── 匹配成功但服务器未运行 → 自动启动对应 LSP 服务器

The entire process completes silently in the background. Once the LSP server starts, it continuously provides diagnostic information for the current session.

Built-in LSP Servers

OpenCode has built-in LSP server support for mainstream languages,When the corresponding file extension is detected and the relevant requirements are met, the LSP server is enabled automatically, and in most cases no configuration is needed.

LSP Server Supported File Extensions Enablement Requirements
astro .astro Automatically installed for Astro projects
bash .sh, .bash, .zsh, .ksh Automatically installs bash-language-server
clangd .c, .cpp, .cc, .cxx, .c++, .h, .hpp, .hh, .hxx, .h++ Automatically installed for C/C++ projects
csharp .cs Requires .NET SDK to be installed
clojure-lsp .clj, .cljs, .cljc, .edn Requiresclojure-lspcommand to be available
dart .dart Requiresdartcommand to be available
deno .ts, .tsx, .js, .jsx, .mjs Requiresdenocommand to be available, and the project must containdeno.jsonordeno.jsonc(auto-detected)
elixir-ls .ex, .exs Requireselixircommand to be available
eslint .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue The project must haveeslintdependency installed
fsharp .fs, .fsi, .fsx, .fsscript Requires .NET SDK to be installed
gleam .gleam Requiresgleamcommand to be available
gopls .go Requiresgocommand to be available
hls .hs, .lhs Requireshaskell-language-server-wrappercommand to be available
jdtls .java Requires Java SDK (version 21 or above) to be installed
julials .jl requires installationjuliaandLanguageServer.jlPackage
kotlin-ls .kt, .kts Automatically installed for Kotlin projects
lua-ls .lua Automatically installed for Lua projects
nixd .nix Requiresnixdcommand to be available
ocaml-lsp .ml, .mli Requiresocamllspcommand to be available
oxlint .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts, .vue, .astro, .svelte The project must haveoxlintdependency installed
php intelephense .php Automatically installed for PHP projects
prisma .prisma Requiresprismacommand to be available
pyright .py, .pyi requirespyrightdependency to be installed
ruby-lsp .rb, .rake, .gemspec, .ru Requiresrubyandgemcommand to be available
rust .rs Requiresrust-analyzercommand to be available
sourcekit-lsp .swift, .objc, .objcpp Requires Swift to be installed (installed via Xcode on macOS)
svelte .svelte Automatically installed for Svelte projects
terraform .tf, .tfvars Automatically installed from GitHub Releases
tinymist .typ, .typc Automatically installed from GitHub Releases
typescript .ts, .tsx, .js, .jsx, .mjs, .cjs, .mts, .cts The project must havetypescriptdependency installed
vue .vue Automatically installed for Vue projects
yaml-ls .yaml, .yml Automatically installs Red Hat yaml-language-server
zls .zig, .zon Requireszigcommand to be available
If you do not want OpenCode to automatically download LSP servers, you can set the environment variableOPENCODE_DISABLE_LSP_DOWNLOADtotrueto disable the automatic download behavior. See the notes at the end of this article for details.

Configuring LSP Servers

LSP-related configuration is written in theopencode.jsonoflspfield. In most cases, no configuration is needed and LSP will be enabled automatically; but when custom behavior is needed, each LSP server supports the following configuration items:

Property Type Description
disabled boolean Set totrueto disable that LSP server
command string[] Command to start the LSP server (as an array; the first element is the executable name, the rest are arguments)
extensions string[] List of file extensions handled by this LSP server
env object Environment variables injected when starting the server; keys are variable names, values are variable values
initialization object During the LSPinitializehandshake phase, initialization options sent to the server; the content varies by server

1. Setting Environment Variables (env)

Use theenvproperty to inject environment variables when starting the LSP server. Commonly used to enable debug logging or specify paths required by the runtime:

Example

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "rust": {
      "env": {
"RUST_LOG": "debug" // Enables debug-level logging for rust-analyzer to make LSP troubleshooting easier
      }
    }
  }
}

2. Setting Initialization Options (initialization)

initializationUsed to pass server-specific configuration to the LSP server. These options are sent once during the LSP handshake (initializerequest) phase and affect all subsequent behavior of the server:

Example

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
      "initialization": {
        "preferences": {
          "importModuleSpecifierPreference": "relative"
// Tells the TypeScript LSP to prefer relative-path imports (e.g., ./utils)
// instead of absolute paths (e.g., /src/utils) or path aliases configured in tsconfig.json
        }
      }
    }
  }
}
Initialization options vary by LSP server. For example,typescriptthe options forgoplsare completely different; consult the official documentation of the corresponding LSP server before use to avoid passing invalid configuration.

Disabling LSP Servers

1. Disabling All LSP Servers

If you do not need LSP functionality at all, you can setlspentirely tofalse, turning off all LSP servers at once:

Example

{
  "$schema": "https://opencode.ai/config.json",
"lsp": false // Globally disables all LSP servers; suitable for environments that do not need code diagnostics or have limited network/resources
}

2. Disabling a Specific LSP Server

If you only want to disable one LSP server while keeping others, set it individually for that serverdisabled: true：

Example

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "typescript": {
"disabled": true // Only disables the TypeScript LSP; LSP servers for other languages are unaffected
    }
  }
}

Adding Custom LSP Servers

If the language you use is not in the built-in support list, you can specifycommandandextensionsto manually add any LSP server, as long as the server follows the standard LSP protocol and supports--stdiomode (communicating over standard input/output):

Example

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
"custom-lsp": { // Custom key name; can be named arbitrarily, used to identify the server in configuration
"command": ["custom-lsp-server", "--stdio"], // Startup command: the first element is the executable name,
// the remaining elements are the startup arguments passed to it
// --stdio indicates communication with OpenCode over standard input/output
"extensions": [".custom"] // Specifies which file extensions this LSP server handles
    }
  }
}

You can also configure environment variables and initialization options for a custom LSP server, exactly the same as for built-in servers:

Example

{
  "$schema": "https://opencode.ai/config.json",
  "lsp": {
    "my-lang-server": {
      "command": ["my-lang-server", "--stdio", "--log-level", "warn"],
"extensions": [".mylang", ".ml2"], // Supports binding multiple file extensions at the same time
      "env": {
"MY_LSP_HOME": "/usr/local/my-lang" // Inject the required environment variables for the server process
      },
      "initialization": {
"formatOnSave": true // Pass the initialization options defined in the server's documentation
      }
    }
  }
}

Additional Notes

PHP Intelephense License

PHP Intelephense offers a free version and a paid premium version. The premium version is unlocked via a license key and includes enhanced features such as import sorting, code folding, call hierarchy viewing, and more. If you have purchased a license, simply write the key into a text file at the following path to activate it automatically, without any additional configuration:

Operating System License File Path
macOS / Linux $HOME/intelephense/license.txt
Windows %USERPROFILE%/intelephense/license.txt

The license file should contain only the license key itself. Do not add any other content (including extra spaces or line breaks), otherwise activation may fail.

Disable Automatic Download

By default, OpenCode automatically downloads the required LSP server from the network when it detects a corresponding file extension. If you are in a network-restricted environment, or prefer to manage LSP tools completely manually, you can disable automatic downloads by setting the following environment variable:

# Linux / macOS：临时禁用（仅当前终端会话有效）
export OPENCODE_DISABLE_LSP_DOWNLOAD=true

# Linux / macOS：永久禁用（写入 shell 配置文件）
echo 'export OPENCODE_DISABLE_LSP_DOWNLOAD=true' >> ~/.bashrc
source ~/.bashrc

# Windows（PowerShell：仅当前会话）
$env:OPENCODE_DISABLE_LSP_DOWNLOAD = "true"

Once disabled, OpenCode will no longer automatically download any LSP servers, but LSP tools already pre-installed on the system can still be detected and used normally.

Other Extensions