OpenClaw入門：インストール、設定、カスタムOpenAI互換エンドポイント

Node.jsでOpenClawを導入し、Gatewayを起動して、公式のcustom provider設定でカスタムOpenAI互換エンドポイントへ接続する方法を説明します。

OpenClaw入門：インストールからカスタムOpenAI互換エンドポイントまで

OpenClawは、オープンソースのAI assistantです。会話、Gateway、各種チャネル、ツール、追加可能なskillを、ひとつの自分で運用できるワークフローにまとめられます。まずローカルでGatewayを起動し、複数の入口から同じagent設定を使う構成です。

2026-09-21時点の公式npmパッケージのバージョンは2026.9.5です。この記事では、公式ドキュメントで確認できるインストール、最小起動、モデル設定、ClawHubの基本操作を扱います。手元のバージョンが異なる場合は、そのバージョンの公式ドキュメントを優先してください。

1. OpenClawとは。何ができるのか

ターミナルからモデルに質問するだけなら、単体のSDKでも足ります。しかし、同じassistantを複数のチャネルで使い、常駐するGatewayでagentの処理を管理し、skillでワークフローを拡張したい場合は、接続設定をひとつにまとめられると扱いやすくなります。

OpenClawの構成は、まず次のように捉えると分かりやすいでしょう。

• Gateway：リクエストを受け、agentの処理を管理する常駐プロセス。
• agent：どのモデルとデフォルト設定を使うかを決める単位。
• provider：接続先、API形式、モデルの能力を定義する設定。
• skill：OpenClawから利用できる拡張機能。ClawHubは公開skill registryです。

この記事では、ローカルでGatewayを動かし、agentをカスタムOpenAI互換エンドポイントへ向けるところまでに絞ります。チャネル、daemon、skillの追加は、この最小経路が確認できてから進めます。

2. インストールして、最小構成で動かす

Node.jsを確認する

公式Getting Startedでは、現在Node.js 24.16+または26.1+が必要で、Node 26が推奨されています。

node --version
npm --version

OpenClawをインストールする

公式のインストーラーを使う方法のほか、npmでグローバルインストールできます。

npm install -g openclaw@latest --allow-scripts=openclaw

インストール後、まずonboardingを実行します。

openclaw onboard --install-daemon

daemonをまだ登録したくない場合は、こちらです。

openclaw onboard

Gatewayの状態確認と起動は次のコマンドで行えます。

openclaw gateway status
openclaw gateway

公式のデフォルトGateway portは18789です。管理画面を開く場合は、次を実行します。

openclaw dashboard

CLIだけを確認するなら、次のコマンドで十分です。

openclaw --version

skillのコマンドを確認する

ClawHubのskillを検索、インストール、更新する公式コマンド例です。

openclaw skills search "calendar"
openclaw skills install @openclaw/demo
openclaw skills update --all

ここでは特定のskillがすでに入っていることは前提にしません。CLI、Gateway、skillのパスが動くことを先に確認します。

3. 設定：カスタムOpenAI互換エンドポイントを使う

OpenClawの公式custom provider設定は、設定ファイルのmodels.providersに置きます。最小構成は次のようになります。

{
  models: {
    providers: {
      bazaarlink: {
        baseUrl: "https://api.bazaarlink.ai/v1",
        apiKey: "${BAZAARLINK_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gemini-3.8-flash",
            name: "gemini-3.8-flash",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: {
        primary: "bazaarlink/gemini-3.8-flash",
      },
    },
  },
}

gemini-3.8-flashは、2026-09-21に公開モデル一覧を読み取った時点で確認できた実際のmodel IDです。今回、OpenAI互換のimage_url data URI形状を実際に送ると200で、モデルが画像を読み取って色を回答しました。そのため例では確認済みのtextとimage入力を宣言します。確認日は2026-09-21です。

API keyはリポジトリへ直接書き込まず、現在のshellから環境変数を渡します。

export BAZAARLINK_API_KEY="<BAZAARLINK_API_KEY>"

Windows PowerShellの場合：

$env:BAZAARLINK_API_KEY = "<BAZAARLINK_API_KEY>"

公式custom providerドキュメントで押さえる欄は次のとおりです。

• baseUrl：互換エンドポイントのbase URL。
• apiKey：環境変数の置換値を指定できます。
• api：API形式。公式例ではOpenAI互換のcompletion形式にopenai-completionsを使います。
• models[].id：エンドポイントが受け付ける実際のmodel ID。
• reasoning、input、contextWindow、maxTokens：モデルの能力と制限を表す欄。
• agents.defaults.model.primary：provider/model形式でデフォルトモデルを指定する欄。

既存のprovider設定を残しながら追加したい場合は、公式ドキュメントにある mode: "merge" も使えます。

{
  models: {
    mode: "merge",
    providers: {
      bazaarlink: {
        baseUrl: "https://api.bazaarlink.ai/v1",
        apiKey: "${BAZAARLINK_API_KEY}",
        api: "openai-completions",
        models: [{ id: "gemini-3.8-flash", name: "gemini-3.8-flash" }],
      },
    },
  },
}

custom providerの欄とモデル指定方法は公式ドキュメントで確認済みです。さらに2026-09-21、実アカウントで最小のrequest shapeをreplayしました。

• GET https://api.bazaarlink.ai/v1/modelsをAuthorization: Bearerで送ると200で、object、dataを含み、gemini-3.8-flashが一覧にありました。
• この設定はmodels[]にmodel IDを明示しているため、固定モデルの生成経路は/v1/modelsを先に呼ばなくてもリクエストを組み立てられます。openclaw models list --refreshなどのカタログ更新は別の処理で、モデル一覧を読むことがあります。
• OpenClawのopenai-completions形状でPOST https://api.bazaarlink.ai/v1/chat/completionsをstream: trueで送ると200、text/event-stream、5個のSSEチャンク、テキストdelta、[DONE]でした。非ストリームのテキスト対話も200で、finish_reason=stopの通常テキストが返りました。
• toolsとtool_choice: autoを送ると200で、finish_reason=tool_calls、get_weatherと{"city":"Taipei"}が返りました。今回、OpenAI互換のtool callにおける標準的な終了理由を確認済みです。
• 標準top-level reasoning_effort: "low"は200でしたが、応答はroleとcontentだけで構造化reasoningフィールドがありません。リクエスト欄が受理されたことと、reasoningの完全互換性を分けて扱います。
• agentで使われるimage_urlのdata URI形状は200で、モデルが画像を読み取って色を回答しました。この画像入力形状は2026-09-21に確認済みです。
• custom providerをAnthropic Messages形状へ明示的に切り替えれば、x-api-keyのPOST /v1/messagesによる短いテキストは200で、レスポンスはtype=messageでした。ただしこれは現在のopenai-completionsの既定経路ではなく、Anthropic形式のツールとストリーミングの相互運用は確認していません。

ここまでの結果はエンドポイントのrequest-shape検証であり、OpenClaw Gatewayをインストールして行うsession、channel、skillの全フロー検証ではありません。そこは未検証として残します。

4. よくあるつまずき

モデルが見つからない

agents.defaults.model.primaryがprovider/model形式になっているか確認します。たとえばbazaarlink/gemini-3.8-flashです。次に、models.providers.bazaarlink.models[].idが公開モデル一覧のIDと完全に一致しているかを確認します。

provider名とmodel IDを混ぜてしまう

OpenClawはprovider/modelを分けて解釈します。providerは設定ファイルで付けた名前、modelはエンドポイントが受け付けるIDです。ここを取り違えると、Gatewayは起動してもモデル解決で失敗します。

JSON5ではなくJSONとして書くべき？

公式例はJSON5です。そのためコメントや末尾カンマが使える場合がありますが、実際に受け付ける形式は手元のバージョンに合わせてください。解析エラーが出たら、コメントと末尾カンマを外した最小のJSONから確認します。

設定変更が反映されない

編集したファイルをGatewayが読んでいるか確認し、Gatewayを再起動します。sessionや別のprofileがモデルを上書きしていないかも確認してください。dashboardが開くことだけでは、現在のmodel選択までは確認できません。

Node.jsの条件を満たしているのに失敗する

node --versionとnpm --versionを確認し、新しいshellでグローバルインストールのPATHを読み直します。公式インストーラーを使った場合は、表示されたエラーをそのバージョンのGetting Startedと照合してください。

応答がほとんど空で、finish_reasonがlengthになるのはなぜですか？

このモデルはデフォルトで思考を有効にしています。max_tokensが小さすぎると推論トークンで上限を使い切り、finish_reason=lengthになって表示テキストがほとんど残らないことがあります。max_tokensを増やしてください。実測では16から400に増やすと正常に出力されました。

5. BazaarLinkにつなぐ場合

providerのbaseUrlをhttps://api.bazaarlink.ai/v1、apiKeyを<BAZAARLINK_API_KEY>にし、公開モデル一覧にあるmodel ID（この記事ではgemini-3.8-flash）を指定します。テキスト、tool call（finish_reason=tool_calls）、5個のSSEチャンク、画像入力（モデルが画像を読み取って色を回答）の最小形状は2026-09-21に確認済みです。OpenClawの完全なsession／channel／skillフローと、Anthropic形式のツールとストリーミングの相互運用は未検証として扱います。追加情報はモデル一覧とSDKドキュメントを参照してください。

台幣計費・統一發票・主流 AI 模型・OpenAI 相容 API