---
title: OpenCode 서버
description: OpenChamber를 로컬 또는 원격 OpenCode 서버에 연결하세요.
---

# OpenCode 서버

OpenChamber는 OpenCode 서버 위에서 실행됩니다. 기본적으로 OpenChamber가 서버를 직접 시작하므로 따로 할 일은 없습니다. 이미 운영 중인 서버를 OpenChamber가 사용하도록 지정하거나, OpenChamber가 시작한 서버를 관리하려는 경우에만 이 페이지가 필요합니다.

## OpenChamber가 서버를 찾는 방법

OpenChamber가 시작되면 다음 순서로 서버를 찾습니다.

1. 이미 시작한 서버를 재사용합니다
2. 외부 서버를 사용하도록 지정했다면 그 서버에 연결합니다(아래 참고)
3. 기본 포트(`4096`)에서 서버를 자동으로 감지합니다
4. 그 외에는 자체 서버를 시작하고 관리합니다

아무것도 설정하지 않으면 4단계가 자동으로 실행되어 바로 사용할 수 있습니다.

## 이미 운영 중인 서버에 연결하기

OpenChamber를 시작하기 전에 다음을 설정하세요.

```bash
OPENCODE_HOST=http://localhost:4096 OPENCODE_SKIP_START=true openchamber
```

- `OPENCODE_HOST` — 포트를 포함한 OpenCode 서버의 전체 주소(예: `http://localhost:4096`)입니다. 끝에 경로가 붙어서는 안 됩니다.
- `OPENCODE_SKIP_START=true` — OpenChamber가 자체 서버를 시작하지 않도록 지정합니다.

포트만 변경하면 된다면 `OPENCODE_HOST` 대신 `OPENCODE_PORT`를 설정하세요.

`OPENCODE_HOST`에 포트가 없거나 경로가 붙어 있으면 OpenChamber는 이를 무시하고 자체 서버를 시작하는 방식으로 되돌아갑니다. 예상한 연결이 일어나지 않았다면 시작 로그에서 `[config]` 경고를 확인하세요.

## CLI에서 서버 관리하기

```bash
openchamber status
openchamber logs
openchamber restart
openchamber stop
```

`openchamber`만 입력하면 서버가 백그라운드에서 시작됩니다. 터미널에 연결된 상태로 유지하려면 `--foreground`를 추가하세요.

## 로그인할 때 OpenChamber 시작하기

`startup enable`을 사용해 네이티브 사용자 서비스를 설치하세요. OpenChamber는 macOS에서 `launchd`, Linux에서 `systemd --user`, Windows에서 Task Scheduler를 사용합니다.

```bash
openchamber startup enable
openchamber startup status
openchamber startup disable
```

UI를 보호하려면 서비스를 활성화할 때 비밀번호를 설정하세요:

```bash
OPENCHAMBER_UI_PASSWORD='secret' openchamber startup enable
```

로그인 시 시작되고 데스크톱 또는 모바일 앱에서 사용할 headless 서버라면 `--api-only`와 접근 가능한 host를 함께 지정하세요:

```bash
openchamber startup enable --port 3000 --api-only --host 0.0.0.0 --ui-password secret
```

`startup enable`은 현재 환경의 스냅샷을 서비스에 저장해, 같은 셸에서 `openchamber`를 직접 실행한 것에 더 가깝게 동작하게 합니다. provider 토큰, `PATH`, SSH agent 설정, 기타 CLI auth/config 환경 변수가 유지됩니다. 최소한의 서비스 환경을 원하면 `--no-env-snapshot`을 사용하세요.

시작 서비스는 `--port`, `--host`, `--ui-password`, `--api-only`를 기억합니다. CLI 재시작과 업데이트 재시작은 이 저장된 설정을 다시 사용합니다.

다른 OpenChamber 앱용 연결 링크를 만들려면 다음을 사용하세요:

```bash
openchamber connect-url --port 3000 --server http://your-host:3000 --qr
```

`openchamber connect-url --help`를 실행하면 `--name`, `--lan`, `--server`, `--api-only`, `--ui-password`, `--qr` 같은 모든 링크 옵션을 볼 수 있습니다.

실행 중인 이 서비스의 터널은 별도로 관리할 수 있습니다:

```bash
openchamber tunnel start --port 3000
openchamber tunnel stop --port 3000
```

터널을 중지해도 서비스나 앱은 재시작되지 않습니다.

## "OpenCode is restarting"

서버가 시작되거나 재시작되는 동안 OpenChamber는 "OpenCode is restarting" 상태를 표시하고 준비가 끝날 때까지 요청을 일시 중지합니다. 실행 직후나 재시작 직후에는 정상적인 동작입니다. 이 상태가 계속 사라지지 않으면 [OpenCode 연결](/ko/troubleshooting/opencode-connection/)을 참고하세요.

## 관련 항목

- [Providers, Models & Agents](/ko/providers/) — 서버가 통신할 대상을 설정합니다
- [OpenCode 연결](/ko/troubleshooting/opencode-connection/) — 연결되지 않을 때
