mirror of
https://github.com/NeuralNomadsAI/CodeNomad.git
synced 2026-10-31 19:10:30 +00:00
1dabb5110f
docs(help): bring the user guide back in line with the current app The help was written on 2026-10-14 and about forty user-visible changes merged since without touching it, so several pages described controls that no longer exist: Missions still listed four playbooks and a Save step for preferences that now save on each change, the depth editor kept its old names, notifications still had their former switches, and voice input pointed to a microphone button that is not in the composer. Every English page was re-checked claim by claim against the current labels (English UI messages) and behaviour, then the nine translations were updated to match, using each locale's own UI labels. Notable corrections: Missions (Compare two models, autosaving defaults with Apply to / Global / Reset, Subsession nesting depth, prepared hand-offs, retired-task interrupts, the named causes of "Mission Control is unavailable", standalone server support); conversations and history (reasoning/tool durations, token lines adding up the cleanup selection, presets including Nothing, timeline markers following Message content, in-place reveal of long text, Open in session, focus after send, Queue message / Steer now, Retrying); settings (notification routing table and defaults, Stats, Mode, info tips, Server setting badge, localized native menus); shortcuts (72 actions, Clear shortcut, Ctrl/Cmd+K); voice (More actions entries, Save status); files (live Workspace refresh, Show 200 more); OpenCode, install, server and updates (2.1.1 recommended, OpenCode 2 beside an older installation, version card first, private loopback listener for Missions, preview releases offered once all builds are published); providers, integrations, browser, SideCars, desktop and remote pages. Translations also repaired older drift, mainly the project-tab closing passages. The Chat settings table header (Default state, its title, item column, the thinking row and its accessible label) was still English in eight locales; it is now translated so the help can cite what users see. AGENTS.md now asks every PR changing user-visible behavior to update the affected help pages in the same PR, since CI validates structure and links but not whether the text still matches the UI; it also corrects the needs-input notification default. USER_HELP.md no longer claims native menus stay English. Validation: npm run test:help (all ten locales, 25 pages, heading ids unchanged), a full help build, and the i18n and transcript-visibility unit tests.
92 lines
11 KiB
Markdown
92 lines
11 KiB
Markdown
# 直接リモートアクセス
|
||
|
||
直接アクセスは、サーバーパスワードを使って CodeNomad の HTTP/HTTPS リスナーに接続します。[リモートコントロール](remote-control.md)とは別です。ペアリングには LAN バインドや受信ポートは不要で、どちらの経路も他方へ無断でフォールバックしません。
|
||
|
||
## アクセス経路を選ぶ {#access-paths}
|
||
|
||
| 経路 | 管理する内容 |
|
||
| --- | --- |
|
||
| 同じマシンのブラウザー | ループバックへのバインドを維持し、表示されたローカル URL を使用します。 |
|
||
| LAN または VPN | 到達可能なインターフェースにバインドし、ファイアウォールを意図したクライアントに限定し、信頼された HTTPS を使用します。VPN は CodeNomad のリスナーを設定しません。 |
|
||
| SSH 転送 | バックエンドをループバックにバインドしたまま、実際に表示されたポートを転送します。トンネルは通信を保護しますが、CodeNomad の認証の代わりにはなりません。 |
|
||
| リバースプロキシ | バックエンドをプライベート／ループバックインターフェースに置き、プロキシで信頼された TLS を終端し、上流接続を保護します。長時間の SSE と、直接アクセスのツールが必要とする WebSocket に対応させます。 |
|
||
| リモートコントロール | ホストから端末をペアリングします。画面の制限と寿命は、[リモートコントロール](remote-control.md)を参照してください。 |
|
||
|
||
バインドは、ファイアウォールルール、ポート転送、DNS、VPN を作成しません。未認証の HTTP リスナーをインターネットに公開しないでください。ワークスペースルートはセキュリティサンドボックスではありません。サーバーを公開する前に[セキュリティ](security.md)を読んでください。
|
||
|
||
## 直接アクセスを有効にする {#enable-direct-access}
|
||
|
||
1. ホストで **設定 → リモートアクセス** を開き、**直接アクセス（ローカルネットワーク、上級者向け）** を展開します。
|
||
2. **サーバーパスワード** で **パスワードを設定** または **パスワードを変更** を選び、**新しいパスワード** と **パスワードの確認** を入力して **パスワードを保存** します。起動時指定のパスワードはここでは変更できません。[セキュリティ](security.md)を参照してください。
|
||
3. **リッスンモード** の **他の IP からの接続を許可** をオンにします。再起動の警告を読み、一時的な中断の準備ができた場合にのみ **今すぐ再起動** を選びます。
|
||
4. 再起動後に **更新** し、**到達可能なアドレス** を確認します。別端末で到達可能な HTTPS アドレスを開くか、ホストで **QR を表示** して別端末で読み取り、ログインします。
|
||
|
||
これはホストの直接リッスンモードの変更であり、1 つのプロジェクトやリモートコントロールの変更ではありません。サーバーが localhost 以外で待ち受けている間、この開閉セクションは自動的に開きます。自動再起動が使えなければ CodeNomad を手動で再起動します。スタンドアロン環境では、起動時の `--host` を整合させる必要があります。公開を解除するには、スイッチをオフにして再起動するか、ループバックへのバインドで CLI を再起動します。ペアリング済みのリモートコントロール端末は失効しません。
|
||
|
||
### リスナーのバインド表 {#binding-matrix}
|
||
|
||
`--host` の既定は `127.0.0.1` で、`localhost` もそのアドレスに正規化されます。有効なリスナーには次の規則が適用されます。
|
||
|
||
| 起動／モード | HTTP のバインド先 | HTTPS のバインド先 |
|
||
| --- | --- | --- |
|
||
| スタンドアロン、HTTPS のみ（既定） | 非公開のループバックリスナーのみ（下記参照） | `--host` |
|
||
| スタンドアロン、HTTP のみ | LAN／ワイルドカードアドレスを含む **`--host`** | 無効 |
|
||
| スタンドアロン、両リスナー | `--host` に関係なく `127.0.0.1` | `--host` |
|
||
| ネイティブデスクトップのバックエンド | ホスト内部用を含め、HTTP リスナーは `127.0.0.1` に維持 | HTTPS 有効時の `--host` |
|
||
|
||
すべてのバックエンドは、ミッションなど CodeNomad 自身の同梱 OpenCode プラグインのために、`127.0.0.1` 上の HTTP リスナーも維持します。HTTP が要求されていない場合、または要求された HTTP リスナーが `127.0.0.1` や `0.0.0.0` 以外のアドレスにバインドされている場合、バックエンドはランダムな `127.0.0.1` ポートに非公開の HTTP リスナーを追加します。このリスナーは表示されることも接続先アドレスとして提示されることもなく、他のマシンからは到達できず、同じ認証付きアプリケーションを提供します。
|
||
|
||
具体的な LAN アドレスは、ループバック接続を受け付けるとは限りません。`0.0.0.0` はすべての IPv4 インターフェース、`::` はデュアルスタックのワイルドカードリスナーです。ブラウザーにはワイルドカードではなく、実際に到達可能なアドレスを使用してください。`--host` は IPv6 ゾーン識別子に対応しません。
|
||
|
||
スタンドアロン HTTPS 環境では、[初期設定手順](security.md)でパスワードを設定してから実行します。
|
||
|
||
```sh
|
||
codenomad --host 0.0.0.0 --https=true --http=false
|
||
```
|
||
|
||
ローカルの信頼されたプロキシの背後などで、ループバック専用 HTTP を使う場合：
|
||
|
||
```sh
|
||
codenomad --host 127.0.0.1 --https=false --http=true
|
||
```
|
||
|
||
ポートを 9898 や 9899 と決めつけないでください。省略時は使用中なら別ポートにフォールバックできます。ゼロ以外の `--https-port`、または HTTP 有効時の `--http-port` を明示するとポートを固定し、バインドできなければ失敗します。`0` は OS の割り当てを要求します。その実行での正規の情報は、表示された **Local Connection URL** と **Remote Connection URL**、および更新した **到達可能なアドレス** です。完全な[サーバー CLI リファレンス](server.md)を参照してください。
|
||
|
||
## 信頼された TLS を設定する {#tls}
|
||
|
||
### 独自の証明書を指定する {#custom-certificates}
|
||
|
||
1. クライアントが実際に使うホスト名または IP を Subject Alternative Names（SAN）に含む証明書を取得します。
|
||
2. `--tls-key <path>` と `--tls-cert <path>` の両方を PEM ファイルで指定します。環境で CA チェーン／バンドルが必要なら `--tls-ca <path>` を追加します。
|
||
3. CodeNomad を再起動し、クライアント端末で証明書と表示された HTTPS アドレスを確認します。
|
||
|
||
独自の証明書ファイルは起動時に読み込まれ、CodeNomad が書き換えることはありません。更新と、新しいファイルを読み込むための再起動はユーザーが管理します。`--tlsSANs` は生成証明書を設定するもので、指定済み証明書に名前を追加できません。秘密鍵を保護し、ホストの識別を確認した証明書だけを信頼してください。
|
||
|
||
### 生成されたローカル CA を使う {#generated-certificates}
|
||
|
||
HTTPS が有効で鍵／証明書のペアを指定していない場合、CodeNomad は設定ベースディレクトリにローカル CA とサーバー証明書を作成します。
|
||
|
||
| ファイル | 用途 |
|
||
| --- | --- |
|
||
| `tls/ca-cert.pem` | 管理するクライアントへ安全に配布する公開 CA 証明書。 |
|
||
| `tls/ca-key.pem` | CA の秘密鍵。絶対に配布しないでください。 |
|
||
| `tls/server-cert.pem` | サーバー証明書。 |
|
||
| `tls/server-key.pem` | サーバーの秘密鍵。絶対に配布しないでください。 |
|
||
|
||
1. `--tlsSANs "host.example.test,192.0.2.10"` で、クライアント向けの全 DNS 名／IP を追加します。ワイルドカードへのバインドは、SAN 用に全 LAN アドレスを検出するものではありません。
|
||
2. バックエンドを再起動し、証明書を生成／再確認します。
|
||
3. 信頼できる経路でホスト／CA を確認し、意図した各クライアント／ブラウザーの信頼ストアに **CA 証明書だけ** をインポートします。代わりに、公に信頼された証明書や TLS リバースプロキシも使用できます。
|
||
|
||
生成されるサーバー証明書の有効期間は 30 日です。起動時に、期限まで 3 日以内、必要な SAN の不足、証明書チェックの失敗、秘密鍵ファイルの欠落があれば更新します。生成 CA は 365 日有効で、期限切れ、証明書チェックの失敗、秘密鍵ファイルの欠落で置き換えられます。置き換え時はサーバー証明書も再発行します。既存の破損、読み取り不能、不一致の秘密鍵は自動修復しません。クライアントは新しい CA を信頼する必要があります。プロセス内で継続的には更新しないため、長期稼働では期限前に意図的な再起動を計画してください。
|
||
|
||
クライアントに証明書警告が出たら、いったん止めてホスト名、SAN、信頼ストア、有効期限を確認してください。検証を無効にしたり、警告を無視して進むことを運用手順にしたりしないでください。信頼された HTTPS は、[PWA のインストールやマイクアクセス](mobile.md)など、リモートブラウザー機能にも必要です。
|
||
|
||
## リモートサーバーを保存する {#saved-servers}
|
||
|
||
1. デスクトップのホームページで **CodeNomad サーバーに接続** を選びます。同じボタンは、空の **サーバー** タブと **設定 → リモートアクセス → サーバー** にもあります。
|
||
2. **サーバーに接続** で、信頼された HTTPS オリジンを使用して **サーバー名** と **サーバー URL** を入力します。**自己署名証明書の TLS 検証をスキップします。** はチェックせず、代わりに信頼を確立します。
|
||
3. ブックマークには **保存**、保存して開くには **接続** を選び、そのサーバーでログインします。
|
||
|
||
保存したサーバーを再び開くには、ホームページの **サーバー** タブで選びます。ブックマークは、この CodeNomad 設定に属し、リモートサーバーのプロジェクトに属するわけではありません。URL の保存はサーバーの起動やアクセス許可を行いません。**保存したサーバーを削除** はブックマークを削除しますが、リモートの会話、バックエンド、認証情報は削除しません。
|
||
|
||
リモートコントロールでは、代わりに新しいペアリングリンクを **サーバー URL** に貼り付けます。ブックマークはトンネルのオリジンだけを保持し、使い捨てのペアリングコードは保持しません。端末 Cookie 消失後の再ペアリングは、[リモートコントロール](remote-control.md)を参照してください。
|