OpenCodeの設定 - リモートアクセス

提供: MochiuWiki : SUSE, EC, PCB

2026年2月27日 (金) 11:57時点におけるWiki (トーク | 投稿記録)による版 (→環境変数の設定)

📢 Webサイト閉鎖と移転のお知らせ
このWebサイトは2026年9月に閉鎖いたします。
新しい記事は移転先で追加しております。（旧サイトでは記事を追加しておりません）

概要

OpenCodeはクライアント・サーバアーキテクチャを備えており、リモートアクセス機能を標準でサポートしている。

opencode serve コマンドを使用することで、ヘッドレスHTTPサーバとして動作させ、別のPCからアクセスできる。
また、opencode web コマンドを使用することで、WebブラウザベースのWebインターフェースを提供できる。

クライアント側からの接続方法として、Webブラウザ、デスクトップアプリ、ターミナルTUI、SDKを使用したプログラムからの接続が可能である。
認証機能としてHTTPベーシック認証をサポートしており、環境変数でユーザ名とパスワードを設定できる。

更に、mDNS discovery機能によりローカルネットワーク上でのサーバ発見が可能である。


前提条件

サーバ側 (Windows Server)

  • OpenCodeのインストール
    OpenCodeの公式サイト からインストールする。

  • ネットワーク接続
    クライアントからサーバへのネットワーク接続が必要である。

  • 管理者権限
    ファイアウォール設定、サービス登録に必要である。


サーバ側 (RHEL / SUSE)

  • OpenCodeのインストール
    curl または npm コマンドでインストールする。

  • ネットワーク接続
    クライアントからサーバへのネットワーク接続が必要である。

  • root権限またはsudo権限
    firewalld設定、systemdサービス登録に必要である。

クライアント側 (Windows 11)

  • Webブラウザ
    Chrome、Firefox、Edge等のモダンブラウザ。

  • OpenCode (オプション)
    ターミナルTUIを使用する場合に必要である。

  • OpenCodeデスクトップアプリ (オプション)
    デスクトップアプリを使用する場合に必要である。



アーキテクチャ

下図に、リモートアクセス構成の概要を示す。



サーバ側の設定 (Windows Server)

OpenCodeのインストール

OpenCodeのインストール方法は、インストール - OpenCodeのページを参照すること。

サーバの起動

ヘッドレスサーバモード

APIのみを提供するヘッドレスサーバを起動する。

opencode serve --hostname 0.0.0.0 --port 4096


Web UI付きサーバモード

Webブラウザからアクセス可能なWeb UIを提供するサーバを起動する。

opencode web --hostname 0.0.0.0 --port 4096


サーバ起動時の出力例を以下に示す。

Local access:       http://localhost:4096
Network access:     http://192.168.1.100:4096


起動オプション
サーバ起動オプション
オプション 説明 デフォルト
--port リッスンするポート番号 4096
--hostname リッスンするホスト名 127.0.0.1
--mdns mDNS discoveryを有効にする false
--mdns-domain mDNSドメイン名 opencode.local
--cors 許可するCORSオリジン [] (空)


認証の設定

サーバへのアクセスを保護するために、HTTPベーシック認証を設定する。

環境変数の設定
 # Windows (PowerShell)
 $env:OPENCODE_SERVER_PASSWORD = "<任意のパスワード>"  # これはHTTPベーシック認証のパスワードとして使用される
                                                       # クライアントがサーバにアクセスする時に入力を求められる
 $env:OPENCODE_SERVER_USERNAME = "opencode"  # オプション (デフォルト: opencode)
 
 # 認証付きでサーバ起動
 opencode web --hostname 0.0.0.0 --port 4096


認証情報
環境変数 説明 デフォルト
OPENCODE_SERVER_USERNAME 認証ユーザ名 opencode
OPENCODE_SERVER_PASSWORD 認証パスワード なし (認証無効)


Windowsサービスとしての登録

OpenCodeサーバをWindowsサービスとして登録し、バックグラウンドで自動起動するように設定する。

NSSMのインストール

NSSM (Non-Sucking Service Manager) を使用して、Windowsサービスを作成する。

  1. NSSMの公式サイト からダウンロードする。
  2. ZIPファイルを展開し、win64ディレクトリ内のnssm.exeを使用する。


サービスの登録
 # OpenCodeのパスを確認
 where opencode
 
 # サービスをインストール
 nssm install OpenCode-Server "C:\path\to\opencode.exe" web --hostname 0.0.0.0 --port 4096
 
 # 環境変数を設定
 nssm set OpenCode-Server AppEnvironmentExtra OPENCODE_SERVER_PASSWORD=<任意のパスワード>
 
 # 作業ディレクトリを設定
 nssm set OpenCode-Server AppDirectory "C:\Users\YourName\projects"
 
 # サービスを開始
 nssm start OpenCode-Server


サービス管理コマンド
 # サービスの状態確認
 nssm status OpenCode-Server
 
 # サービスの停止
 nssm stop OpenCode-Server
 
 # サービスの再起動
 nssm restart OpenCode-Server
 
 # サービスの削除
 nssm remove OpenCode-Server confirm


ファイアウォール設定

WindowsファイアウォールでOpenCodeサーバのポートを開放する。

PowerShellを使用する方法
 # ポート4096を開放
 New-NetFirewallRule -DisplayName "OpenCode Server" -Direction Inbound -LocalPort 4096 -Protocol TCP -Action Allow


GUIを使用する方法
  1. コントロールパネルを開く。
  2. [システムとセキュリティ] - [Windows Defender ファイアウォール]を選択する。
  3. [詳細設定]を選択する。
  4. [受信の規則] - [新しい規則]を選択する。
  5. [ポート] - [TCP] - [特定のローカルポート: 4096]を指定する。
  6. [接続を許可する]を選択する。
  7. ドメイン、プライベート、パブリックから適切なものを選択する。
  8. [名前:]項目では、OpenCode Server と入力して完了する。



サーバ側の設定 (RHEL / SUSE)

OpenCodeのインストール

OpenCodeのインストール方法は、インストール - OpenCodeのページを参照すること。

サーバの起動

ヘッドレスサーバモード

APIのみを提供するヘッドレスサーバを起動する。

opencode serve --hostname 0.0.0.0 --port 4096


Web UI付きサーバモード

ブラウザからアクセス可能なWeb UIを提供するサーバを起動する。

opencode web --hostname 0.0.0.0 --port 4096


サーバ起動時の出力例を以下に示す。

Local access:       http://localhost:4096
Network access:     http://192.168.1.100:4096


認証の設定

サーバへのアクセスを保護するために、HTTPベーシック認証を設定する。

環境変数の設定
 export OPENCODE_SERVER_PASSWORD="<任意のパスワード>"  # クライアントがサーバにアクセスする時に入力を求められる
                                                       # これはHTTPベーシック認証のパスワードとして使用される
 export OPENCODE_SERVER_USERNAME="opencode"  # オプション (デフォルト: opencode)
 
 # 認証付きでサーバ起動
 opencode web --hostname 0.0.0.0 --port 4096


systemdサービスとしての登録

OpenCodeサーバをsystemdサービスとして登録して、バックグラウンドで自動起動するように設定する。

ユーザサービスとしての登録

ユーザ権限で動作するサービスとして登録する方法である。

Systemdサービスファイルを作成する。

mkdir -p ~/.config/systemd/user/
vi ~/.config/systemd/user/opencode-web.service



 [Unit]
 Description=OpenCode Web Server
 After=network.target
 
 [Service]
 Type=simple
 ExecStart=/path/to/opencode web --hostname 0.0.0.0 --port 4096
 Environment=OPENCODE_SERVER_PASSWORD=<任意のパスワード>
 WorkingDirectory=<任意のプロジェクトディレクトリ  例: /home/<ユーザ名>/projects>
 Restart=on-failure
 RestartSec=5
 
 [Install]
 WantedBy=default.target


ユーザサービスの管理コマンド
# サービスの有効化 (ログイン時自動起動)
systemctl --user enable opencode-web

# サービスの開始
systemctl --user start opencode-web

# サービスの状態確認
systemctl --user status opencode-web

# サービスの停止
systemctl --user stop opencode-web

# サービスの再起動
systemctl --user restart opencode-web

# サービスの無効化
systemctl --user disable opencode-web


システムサービスとしての登録

システム全体で動作するサービスとして登録する場合、以下のファイルを作成する。

sudo vi /etc/systemd/system/opencode-web.service



 [Unit]
 Description=OpenCode Web Server
 After=network.target
 
 [Service]
 Type=simple
 User=opencode
 Group=opencode
 ExecStart=/path/to/opencode web --hostname 0.0.0.0 --port 4096
 Environment=OPENCODE_SERVER_PASSWORD=<任意のパスワード>
 WorkingDirectory=<任意のプロジェクトディレクトリ  例: /opt/opencode/projects>
 Restart=on-failure
 RestartSec=5
 
 [Install]
 WantedBy=multi-user.target


システムサービスの管理コマンド
# systemdの設定を再読み込み
sudo systemctl daemon-reload

# サービスの有効化
sudo systemctl enable opencode-web

# サービスの開始
sudo systemctl start opencode-web

# サービスの状態確認
sudo systemctl status opencode-web

# サービスのログ確認
sudo journalctl -u opencode-web -f


ファイアウォール設定 (firewalld)

ポートの開放
# ポート4096を開放 (一時的)
sudo firewall-cmd --zone=public --add-port=4096/tcp

# ポート4096を開放 (永続的)
sudo firewall-cmd --zone=public --add-port=4096/tcp --permanent

# 設定を反映
sudo firewall-cmd --reload


設定の確認
# 開放されているポートを確認
sudo firewall-cmd --zone=public --list-ports

# 全ての設定を確認
sudo firewall-cmd --zone=public --list-all


サービスとして定義する方法

カスタムサービスとして定義することにより、管理しやすくなる。

sudo vi /etc/firewalld/services/opencode.xml



 <?xml version="1.0" encoding="utf-8"?>
 <service>
   <short>OpenCode Server</short>
   <description>OpenCode remote access server</description>
   <port protocol="tcp" port="4096"/>
 </service>



# サービスを追加
sudo firewall-cmd --zone=public --permanent --add-service=opencode
sudo firewall-cmd --reload



クライアント側の設定 (Windows 11)

Webブラウザからの接続

接続手順
  1. Webブラウザを起動する。
  2. アドレスバーに http://<サーバのIPアドレス>:4096 を入力する。
  3. 認証ダイアログが表示された場合、ユーザ名とパスワードを入力する。
  4. OpenCodeのWeb UIが表示される。


アクセスURLの例を以下に示す。


デスクトップアプリからの接続

OpenCodeデスクトップアプリをリモートサーバに接続するように設定することもできる。

設定手順
  1. OpenCodeデスクトップアプリを起動する。
  2. 設定画面を開く。
  3. サーバ選択ダイアログでデフォルトサーバURLを設定する。
  4. http://<サーバのIPアドレス>:4096 を入力する。
  5. 接続を確認する。


接続失敗時の対処

サーバに到達できない場合、以下に示すオプションが表示される。

  • Retry
    再度接続を試みる。
  • Start Local
    ローカルサーバを起動する。


ターミナル (TUI) からの接続

opencode attach コマンドを実行して、リモートサーバに接続する。

接続コマンド
# リモートサーバにアタッチ
opencode attach http://server-ip:4096

# 認証が必要な場合
# Webブラウザで認証を完了してからアタッチ


切断方法

[Ctrl] + [C]キーを押下することで、接続を切断できる。
セッションはサーバ側で維持されるため、再接続後に続きから作業できる。

SDKを使用した接続

TypeScript/JavaScript SDKを使用してプログラムから接続できる。

SDKのインストール
npm install @opencode-ai/sdk


接続コード例
 import { createOpencodeClient } from "@opencode-ai/sdk"
 
 const client = createOpencodeClient({
    baseUrl: "http://<サーバのIPアドレス>:4096",
 })
 
 // ヘルスチェック
 const health = await client.global.health()
 console.log(health.data.version)
 
 // セッションの作成
 const session = await client.session.create({
    body: { title: "My session" },
 })
 
 // メッセージの送信
 const result = await client.session.prompt({
    path: { id: session.id },
    body: {
       model: { providerID: "zai-coding-plan", modelID: "glm-5" },
       parts: [{ type: "text", text: "Hello!" }],
   },
 })



GLM-5の設定

プロバイダの追加

opencode auth login コマンドを実行して、Z.aiの認証情報を追加する。

opencode auth login
# Z.ai Coding Plan を選択
# 認証を完了


設定ファイルの編集

opencode.json ファイルでGLM-5をデフォルトモデルとして設定する。

グローバル設定
  • ファイル場所
    • Linux / MacOS
      ~/.config/opencode/opencode.json
    • Windows
      %USERPROFILE%\.config\opencode\opencode.json


プロジェクト設定

設定ファイルの場所は、プロジェクトルートの opencode.json ファイルである。

 {
    "$schema": "https://opencode.ai/config.json",
    "model": "zai-coding-plan/glm-5",
    "provider": {
       "zai-coding-plan": {
          "options": {
             "baseURL": "https://api.z.ai/v1"
          }
       }
    }
 }


GLM-5の仕様

GLM-5モデル仕様
項目 仕様
パラメータ数 744B (40B active)
コンテキスト長 200K tokens
最大出力 128K tokens
入力モダリティ テキスト
出力モダリティ テキスト
Thinking Mode 対応
Function Call 対応



設定ファイル (opencode.json)

サーバ設定

サーバ関連の設定を opencode.json ファイルに記述する。

 {
    "$schema": "https://opencode.ai/config.json",
    "server": {
       "port": 4096,
       "hostname": "0.0.0.0",
       "mdns": true,
       "mdns-domain": "opencode.local",
       "cors": ["http://localhost:5173", "https://app.example.com"]
    }
 }


設定ファイルの優先順位

設定ファイルは以下に示す順序で読み込まれ、後のものが優先される。

設定ファイルの優先順位
優先度 場所 説明
1 (低) リモート .well-known/opencode 組織のデフォルト設定
2 ~/.config/opencode/opencode.json グローバルユーザ設定
3 環境変数 OPENCODE_CONFIG カスタム設定ファイルパス
4 ./opencode.json プロジェクトルート設定
5 ./.opencode/opencode.json .opencodeディレクトリ設定
6 環境変数 OPENCODE_CONFIG_CONTENT インライン設定
7 (高) 管理設定ディレクトリ エンタープライズ展開用



HTTPS設定 (リバースプロキシ)

OpenCodeは現在HTTPのみをサポートしているため、HTTPSを使用する場合はリバースプロキシが必要である。

NginXを使用した設定例

 server {
    listen 443 ssl;
    server_name opencode.example.com;
 
    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;
 
    location / {
       proxy_pass http://127.0.0.1:4096;
       proxy_http_version 1.1;
       proxy_set_header Upgrade $http_upgrade;
       proxy_set_header Connection "upgrade";
       proxy_set_header Host $host;
       proxy_set_header X-Real-IP $remote_addr;
       proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
       proxy_set_header X-Forwarded-Proto $scheme;
    }
 }


Let's Encryptを使用したSSL証明書取得

 # certbotをインストール
 # Windows: https://certbot.eff.org/ からダウンロード
 
 # 証明書を取得
 certbot certonly --standalone -d opencode.example.com
 
 # 証明書の場所
 # /etc/letsencrypt/live/opencode.example.com/fullchain.pem
 # /etc/letsencrypt/live/opencode.example.com/privkey.pem



トラブルシューティング

接続できない場合

チェックリスト
  • サーバが起動しているか確認
    curl http://localhost:4096/global/health コマンドを実行して確認する。

  • ファイアウォール設定を確認
    4096番ポートが開放されているか確認する。

  • ネットワーク接続を確認
    ping <サーバのIPアドレス> で接続確認する。

  • ホスト名の設定を確認
    --hostname 0.0.0.0 が設定されているか確認する。


ポートが使用中の場合
 # 使用中のポートを確認
 netstat -ano | findstr :4096
 
 # プロセスを終了
 taskkill /PID <pid> /F


Linux (RHEL / SUSE) の場合
# 使用中のポートを確認
sudo ss -tlnp | grep :4096

# または lsofを使用
sudo lsof -i :4096

# プロセスを終了
sudo kill <pid>


認証エラー

ブラウザで認証ダイアログが繰り返し表示される場合
  • ユーザ名とパスワードが正しいか確認する。
  • 環境変数が正しく設定されているか確認する。
  • Webブラウザのキャッシュをクリアする。


環境変数の確認
 # PowerShell
 echo $env:OPENCODE_SERVER_USERNAME
 echo $env:OPENCODE_SERVER_PASSWORD



# Linux (bash)
echo $OPENCODE_SERVER_USERNAME
echo $OPENCODE_SERVER_PASSWORD


ログの確認方法

ログファイルの場所
OS ログの場所
Windows %USERPROFILE%\.local\share\opencode\log
MacOS / Linux ~/.local/share/opencode/log/


デバッグモードでの起動
opencode web --hostname 0.0.0.0 --port 4096 --log-level DEBUG


systemdサービスのトラブルシューティング (Linux)

サービスが起動しない場合
  • サービスファイルのパスが正しいか確認する。

  • ExecStartのパスを確認する。
    which opencode で実際のパスを確認し、サービスファイルのパスと照合する。

  • 環境変数が正しく設定されているか確認する。

サービスのログを確認
# ユーザサービスのログ
journalctl --user -u opencode-web -f

# システムサービスのログ
sudo journalctl -u opencode-web -f

# 直近のログを確認
sudo journalctl -u opencode-web -n 50


ユーザサービスがログイン時に自動起動しない場合

ユーザサービスをログイン時に自動起動させるには、lingeringを有効にする必要がある。

# lingeringを有効化
loginctl enable-linger $USER

# 確認
ls /var/lib/systemd/linger


WSLでの問題

Windows環境でWSLを使用する場合、以下の問題が発生することがある。

空白画面が表示される場合
  • WSL2を使用しているか確認する。
  • Ubuntu 20.04以降を使用しているか確認する。
  • opencode コマンドをWSL内で実行する。


デスクトップアプリからWSLサーバに接続する場合
 # WSL内でサーバを起動
 opencode serve --hostname 0.0.0.0 --port 4096
 
 # デスクトップアプリから接続
 # http://localhost:4096



既知の問題

HTTPSの直接サポートがない

現在、OpenCodeはHTTPSを直接サポートしていない。
リバースプロキシ (nginx等) を使用してHTTPS化する必要がある。

デスクトップアプリとターミナルの同時実行

同じポートで複数のOpenCodeインスタンスを起動しようとすると競合が発生する。
既存のサーバに接続する場合は opencode attach を使用する。

社内ネットワークでの接続問題

外部ネットワークアクセスがない環境では、一部の機能が動作しない可能性がある。
プロキシ設定が必要な場合は環境変数を設定する。

 export HTTPS_PROXY=http://proxy.example.com:8080
 export NO_PROXY=localhost,127.0.0.1



APIリファレンス

サーバはOpenAPI 3.1仕様に準拠したREST APIを提供する。

APIドキュメント

http://<サーバのIPアドレス>:4096/doc でSwagger UI形式のAPIドキュメントにアクセスできる。

主なエンドポイント

主要APIエンドポイント
カテゴリ エンドポイント 説明
Global GET /global/health サーバのヘルスチェック
Session GET /session セッション一覧取得
Session POST /session 新規セッション作成
Session POST /session/:id/message メッセージ送信
File GET /file?path= ファイル一覧取得
File GET /file/content?path= ファイル内容取得
Find GET /find?pattern= テキスト検索
Config GET /config 設定取得
Provider GET /provider プロバイダ一覧



関連リンク



「http://mochiuwiki.e2.valueserver.jp/index.php?title=OpenCodeの設定_-_リモートアクセス&oldid=14498」から取得