Agent 向けインストールガイド

https://linkly.ai/docs/ja/agent-setup.md に従ってセットアップしてください

​

AI Agent へ

​

あなたのタスク

1. Linkly AI デスクトップアプリがインストール・初期化され、インデックス作成が動作していること。同梱のサンプルだけでも達成とみなして構いません。 ユーザー自身のドキュメントが入っていれば、なお良いです。かつ
2. あなた（またはユーザーが所有する別の AI ツール）が Linkly AI の検索ツールを実際に呼び出し、実在のドキュメントを見つけられること。

​

あなたの権限範囲とルール

• 自分で実行してよいこと：診断コマンドの実行、CLI のインストール、MCP の設定、Skills のインストール、検証コマンドの実行、エラーの解釈、結果の報告。ソフトウェアをインストールするものについては、先にコマンドを提示し、同意を得てください。
• ユーザーが行う必要があること：インストーラーのダウンロードと実行、セットアップウィザードの完了、アプリ内でのドキュメントフォルダの追加、システム権限の付与。これらは GUI 操作であり、あなたが代わりに行うことはできません。

• 行動する前に診断すること。 ユーザーはすでに途中までセットアップ済みかもしれませんし、再インストール中かもしれません。頭から機械的に全ステップを実行しないでください。
• 各ステップを必ず検証すること。 各ステップには合格判定基準が記載されています。基準を満たさないうちは次に進まないでください。
• ユーザーの操作が必要な場面では、必要なことを一度にすべて伝え、そこで止まって 1 回の返信を待つこと。 1 つの作業を何往復もの確認に分割しないでください。
• インストールコマンドは提示して同意を得てから実行すること — 特にネットワークからスクリプトをダウンロードして実行するものは必ず確認を取ってください。
• MCP や Skills の設定を書き込んだ後、ツールが現れたかどうかを現在のセッションで何度も確認しないこと。 新しいツールはクライアントが再読み込みして初めて入ってきます。これは読み込みの仕組みであって不具合ではありません。設定の書き込みが成功した時点でこのステップは完了です。残りの検証はユーザーが再読み込みした後に回してください。
• 進捗を誇張しないこと。 検証できていないものは完了していません。どこで詰まり、何を試したかを正確に伝えてください。
• ユーザーに API Key（lkai_ で始まるもの）や LAN アクセストークンを求めないこと。ユーザーの代わりに linkly auth set-key を実行しないこと。 これらはユーザーのローカル資料にアクセスするための鍵に相当し、会話を経由するとモデルの提供元に送られ、会話履歴に残ります。ログインが必要なときは linkly auth login の 2 段階の手順（リモート分岐の R2〜R4 を参照）を使い、ユーザーにはブラウザで認可してもらうだけにしてください。ユーザーが Key やトークンを送ってきた場合は使わず、ダッシュボード（https://linkly.ai/dashboard/integrations）で失効させて作り直すよう伝えてください。LAN トークンはデスクトップアプリの「MCP 接続設定を表示」で再生成できます。
• 権限・セキュリティ・検証の要件を回避しないこと。 トラブルシューティングで扱われていない問題に遭遇したら、まず linkly doctor を実行し、該当する公式ガイドを確認してください。ここに記載のない方法を使う場合は、その理由を述べ、再度検証してください。

​

まず、コマンドを実行できるかを確認する

​

次に、デスクトップアプリをこのマシンに置くべきかを確認する

​

ステップ 0：現在の状態を診断する

echo "--- 1. port file ---"
cat ~/.linkly/port 2>/dev/null || echo "NO_PORT_FILE"
echo ""
echo "--- 2. health ---"
PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port 2>/dev/null)
curl -sf --max-time 5 "http://127.0.0.1:${PORT:-60606}/health" || echo "UNREACHABLE"
echo ""
echo "--- 3. cli ---"
linkly --version 2>/dev/null || echo "NO_CLI"
echo "--- 4. status ---"
linkly status --json 2>/dev/null || echo "NO_STATUS"
echo "--- 5. skills ---"
ls ~/.claude/skills/linkly-ai/SKILL.md ~/.agents/skills/linkly-ai/SKILL.md 2>/dev/null || echo "NO_SKILLS"

Write-Output "--- 1. port file ---"
$port = 60606
if (Test-Path "$HOME\.linkly\port") {
  Get-Content "$HOME\.linkly\port"
  $port = (Get-Content "$HOME\.linkly\port" | ConvertFrom-Json).port
} else { Write-Output "NO_PORT_FILE" }
Write-Output "--- 2. health ---"
try { Invoke-RestMethod "http://127.0.0.1:$port/health" -TimeoutSec 5 | ConvertTo-Json -Compress } catch { "UNREACHABLE" }
Write-Output "--- 3. cli ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly --version } else { Write-Output "NO_CLI" }
Write-Output "--- 4. status ---"
if (Get-Command linkly -ErrorAction SilentlyContinue) { linkly status --json } else { Write-Output "NO_STATUS" }
Write-Output "--- 5. skills ---"
if ((Test-Path "$HOME\.claude\skills\linkly-ai\SKILL.md") -or (Test-Path "$HOME\.agents\skills\linkly-ai\SKILL.md")) { Write-Output "SKILLS_OK" } else { Write-Output "NO_SKILLS" }

​

結果の読み方

{
  "version": "1.1.0",
  "doc_count": 12009,
  "mcp_endpoint": "http://127.0.0.1:60606/mcp",
  "index_status": "watching",
  "capabilities": ["clips-v1", "reveal-v1", "clip-tags-v1"]
}

• ポート 60606 をハードコードしないこと。 これはあくまでデフォルト値であり、そのポートが使用中の場合、アプリは番号を 1 つずつ繰り上げます。必ず ~/.linkly/port から実際のポートを読み取ってください。中身は {"port":60606} のようなコンパクトな JSON です。
• port file があるからといってサービスが動作しているとは限りません。 アプリが強制終了されたりクラッシュしたりすると、このファイルが残ります。/health が 200 を返せばサービスは正常です。ただし AI エージェントのネットワークサンドボックス内で /health に到達できない場合、localhost が遮断されている可能性があるため、Desktop が停止しているとは断定できません。
• mcp_endpoint が null の場合は MCP トグルがオフになっています（/health は 200 を返したままです）。ポートのデバッグを始めず、メインウィンドウ左サイドバー下部のエージェントアイコンから「エージェントの利用」ページを開き、「管理」セクションの「ローカルアクセスを許可」をオンにする（または「停止中」カードの「起動」ボタンをクリックする）ようユーザーに伝えてください。
• index_status の値：watching（完了 — CLI では Up to date と表示）、scanning、indexing、idle、error。
• doc_count はインデックス済みのドキュメント数です。インデックス作成の進捗を測る目安として使い、ユーザーのファイルが取り込まれたことの確たる証拠とはしないでください。あくまで合計値であり、ファイルを 1〜2 個追加しただけでは 151 と 150 の区別はほとんどつきません。

​

状態対応表

​

ステップ 1：インストールと初期化

​

1. ダウンロードとインストール

• macOS：.dmg をダブルクリックしてマウントし、LinklyAI アイコンを Applications にドラッグしてから、Launchpad で起動します。
• Windows：.exe をダブルクリックしてウィザードに従います（デフォルトではユーザーディレクトリにインストールされます）。その後スタートメニューから起動します。
• Linux：x86_64 AppImage の場合は chmod +x LinklyAI-*.AppImage && ./LinklyAI-*.AppImage（glibc 2.35 以降が必要、例：Ubuntu 22.04+ / Debian 12+。起動しない場合は Linux AppImage のトラブルシューティングを参照）。

​

2. 初回起動ウィザードを完了する

• カバー画面：先に進むには「以下を読み、同意します: プライバシーポリシー」にチェックを入れる必要があります。 同じ画面に「Linkly AI の改善に協力する（匿名）」というテレメトリの項目があり、デフォルトでチェックが入っていますが、外すこともできます。
• 資料を取り込む（1/2）：「サンプル資料」は必須で、アプリがバックグラウンドでインデックスを作成するため、待つ必要はありません。その下の「書類」「デスクトップ」「ダウンロード」はデフォルトでチェックが外れており、必要に応じて選べます。macOS ではチェックを入れるとシステムの許可ダイアログが表示されるので、許可してください。
• エージェントと接続（2/2）：「Linkly CLI と Skills をインストール」の右にある「インストール」をクリックすると、アプリがバックグラウンドで CLI と Skills をインストールします。「CLI と Skills を常に最新に」はデフォルトでオンです。「インストール」をクリックしなければインストールされませんが、あとからメインウィンドウの「エージェントの利用」ページでインストールすることもできます。
• 準備完了：「始める」をクリックするとウィザードが終了し、メインウィンドウのホームが開きます。

​

3. 自分のドキュメントフォルダを追加する（任意）

• メインウィンドウの左サイドバーで「ライブラリ」を開き、「フォルダを追加」からインデックス対象のディレクトリ（ドキュメント、ダウンロード、プロジェクトのディレクトリなど）を追加する。
• あるいは ~/LinklyAI フォルダにファイルを置く — このフォルダはデフォルトで監視されているため、置いたものは自動的にインデックスされます。

​

4. モデルがバックグラウンドでダウンロードされていることを把握する（操作は不要だが、ユーザーに伝える）

• キーワード検索はすぐに使え、まったく影響を受けません。
• セマンティック検索はダウンロードとインデックス作成の完了を待ちます。 それまでは search は自動的にキーワードのみ（全文）検索にフォールバックします — 関連度はわずかに下がります。これは想定どおりの動作であり、不具合ではありません。

​

5. すべて終わったら 1 回だけ返信する

• まずステップ 0 の検出をやり直してください。インストール済みのものについてはステップ 2 の方法 A とステップ 3 を飛ばし、重複してインストールしないでください。
• linkly コマンドが見つからない場合は、まずユーザーに新しいターミナルウィンドウを開いてもらってください。
• 例外：あなたが Claude Code で、~/.claude/skills/linkly-ai が存在しない場合、Skills はまだあなたから見えません（Claude Code は ~/.agents/skills を読み込みません）。この場合も linkly skills install を実行してください。このリンクを補ってくれます。

​

ステップ 2：ツール経路を接続する

PORT=$(sed -n 's/.*"port":\([0-9]*\).*/\1/p' ~/.linkly/port)
MCP_URL="http://127.0.0.1:$PORT/mcp"

​

方法 A：CLI をインストールする（推奨）

curl -sSL https://updater.linkly.ai/cli/install.sh | sh

brew tap LinklyAI/tap
brew install linkly

irm https://updater.linkly.ai/cli/install.ps1 | iex

cargo install linkly-ai-cli

• macOS / Linux：~/.linkly/bin/linkly にインストールされ、.zshrc / .bashrc / .profile に PATH が追加されます。
• Windows：%LOCALAPPDATA%\linkly\bin\linkly.exe にインストールされ、ユーザーレベルの PATH が変更されます。

​

方法 B：MCP を設定する

• Claude Code：claude mcp add --transport http linkly-ai "$MCP_URL?client=claude-code"
• Codex：codex mcp add linkly-ai --url "$MCP_URL?client=codex"
• Cursor：Settings → MCP Servers → Add Server を開き、Name は linkly-ai、Type は StreamableHTTP、URL は $MCP_URL を解決した値の末尾に ?client=cursor を付けたものを指定します。

1. 新しい会話を始める（コマンドラインツールの場合は、いったん終了して新しいセッションを開く）。すでに進行中の会話は開始時点のツール一覧を使い続けるため、新しく始めれば最新のものが読み込まれます。
2. クライアントを完全に終了してから、開き直す。 1 つ目で解決しないときはこちらを使います — ウィンドウを閉じることは終了ではない点に注意してください：macOS では Cmd + Q を押すかメニューバーから「終了」を選び、Windows ではタスクトレイからも終了しているか確認します。

curl -sf --max-time 5 -X POST "$MCP_URL" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"setup-probe","version":"1"}}}'

​

ステップ 3：Skills をインストールする

npx skills add LinklyAI/linkly-ai-skills

# Claude Code (user level)
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.claude/skills/linkly-ai

# Codex CLI
git clone https://github.com/LinklyAI/linkly-ai-skills.git ~/.agents/skills/linkly-ai

https://updater.linkly.ai/skills/linkly-skills-latest.zip

​

ステップ 4：エンドツーエンドの検証

linkly search "Holmes" --json

再読み込みしたら、この一文を私に送ってください：「linkly-ai で Holmes を検索して」。ドキュメントのエントリが返ってくれば、チェーン全体が動作しています。

​

リモート分岐：このマシンにデスクトップアプリがない場合

​

R1：CLI をインストールする

​

R1.5：既存のログインを確認する

linkly auth status --json

​

R2：ログインを開始する

linkly auth login --no-wait --json

​

R3：リンクをユーザーに渡し、止まって待つ

• url——どのデバイスで開いてもよく、スマートフォンでも構いません；
• user_code——承認 をクリックする前に、ページに同じコードが表示されていることを確認してもらいます；
• リンクの有効期限は 10 分で、ページには認可するアカウントが表示されるので、正しいアカウントか確認してもらいます。

​

R4：ログインを完了する

linkly auth login --wait --json

• R2 と R4 は、同じ環境・同じシステムユーザー・同じ設定ディレクトリで実行してください。 認可待ちのログインはそこに保存されます。新しいコンテナ、別のユーザー、別の LINKLY_CONFIG_DIR からは見えません。
• 複数のユーザーにサービスを提供している場合は、ユーザーごとに専用の LINKLY_CONFIG_DIR を用意し（1 つのディレクトリに保存できるアカウントは 1 つ）、そのユーザーのために実行するすべてのコマンドに指定してください。例：LINKLY_CONFIG_DIR=~/.linkly-alice linkly auth login --no-wait --json。
• 環境が再構築されて認証情報が消えた場合は、R2 からログインし直すだけです。

​

R5：3 層で検証する

1. ログイン成功：linkly auth status --json に "valid": true とプランが表示されること。これが証明するのはアカウントだけで、コンテンツに到達できることは証明しません。
2. クラウド検索が動く（Free プランで十分）：ユーザーがリンク済みのクラウドナレッジベースを使い（わからなければユーザーに尋ねてください）、次を実行します：
   linkly search "<query>" --remote --library cloud://<owner>/<slug>
   
   実際の結果が返れば合格です。ユーザーにクラウドナレッジベースがない場合は、この層は合格ではなくスキップしたと伝えてください。
3. ローカル検索が動く（ユーザーのデスクトップ上のドキュメント）：Pro が必要で、デスクトップアプリがオンラインかつリモートアクセスが接続済みである必要があります（リモートアクセスを参照）。まず確認します：
   linkly doctor --remote
   
   トンネルが接続済みなら、linkly search "<query>" --remote を実行し、実際の結果が返ることを確認します。デスクトップアプリがオフライン、またはトンネルが未接続の場合は、そのとおりに報告し、デスクトップアプリを開き、「エージェントの利用」ページの「管理」セクションで「リモートアクセスを許可（インターネット）」をオンにして、状態が「接続済み」になるまで待つようユーザーに伝えてください——成功したとは言わないでください。

​

トラブルシューティング

​

完了したら報告する

• どのステップを、どの経路（CLI、MCP、またはリモート分岐。リモート分岐の場合は 3 層の検証のどれが通ったか）で完了したか
• 反映のために再読み込みが必要か — 必要なら「新しい会話を始める / クライアントを完全に終了して開き直す」の 2 つの方法もあわせて伝えること
• 現在のインデックスの状態とドキュメント数
• 実際の使い方 — 例えば任意のプロンプトの末尾に use linkly-ai を付ける、Cmd/Ctrl + L で検索ランチャー、Cmd/Ctrl + K でメインウィンドウを開く、など（旧バージョンからアップグレードしたユーザーは以前設定したショートカットがそのまま使われます）

​

最後に 4 つの質問例を添える

1. A Life in 10 Years を読んで、Samuel Pepys の10年間の日記に繰り返し現れる人生のパターンと、彼自身は気づいていなかったかもしれない盲点を分析してください。
2. シャーロック・ホームズはなぜ勝てるのか？Detectives Library の12の事件簿を読んで、彼の推理の公式を抽出し、Holmes の手法を複雑なビジネス課題を診断するためのチェックリストに変換してください。
3. アメリカの建国者たちが本当に恐れていたものは何か？Federalist Papers 全体を読んで、答えを出してください。野心と派閥を互いに抑制させる制度をどう設計したのかを説明し、最後にそのロジックを今日の AI 企業やインターネットプラットフォームのガバナンス原則に翻訳してください。
4. 数百人の元奴隷たちが自ら語った回想を読んで、アメリカの歴史教科書が最も詳しく語ろうとしないことは何かを見つけてください。WPA Slave Narratives に基づいて答えてください。

​

関連ドキュメント

• クイックスタート — 人間向けに書かれた、インストールと導入の完全ガイド
• CLI の使い方 — CLI のすべてのサブコマンドとパラメータ
• MCP の使い方 — 3 つのアクセス方式とクライアント別の設定方法
• Skills の使い方 — Skills のインストール方法と動作の仕組み