Skip to content

🤖 Open-source, local-first alternative to Grok Bot, OpenAI dots and Claude Duet. Your own AI bots on any model: GPT, Claude, Gemini, Grok, DeepSeek, Kimi, GLM and 70+ more through one Modelflare key. Reach them in the app, WeChat or Feishu; they remember you, work in the background, run commands and use your computer. Pay per use.

53.9 KB
Raw Blame

開発ガイド

简体中文 | English | 日本語 | 한국어 | Русский

ソースからの実行、パッケージ作成、開発への参加を考えている方のためのガイドです。アプリを使うだけなら Releases からインストーラーを入手してください。README に手順があります。

  • ボットは役割、既定のモデル、記憶から構成されます。アカウントは設定 › 接続で全体管理し、全ボットで共有します。サービスごとにいくつでも追加できます。一人での個人利用を想定しています。
  • モデルは Modelflare が提供します。初回起動でログインまたは登録するとモデル一覧が自動表示されます。リクエストは同梱の magpie ゲートウェイを通ります。
  • 同じコードを デスクトップ(Electron)、CLI npm start、Docker の 3 通りで実行できます。

リポジトリの構成

src/
  core/          共通メッセージ型、セッションキューと重複排除、ランタイム(/model /reset、ストリーミング)、再起動通知、利用許可(所有者+許可リスト)、永続送信キュー
  agent/         DSH ホストとブリッジ、承認、権限プリセット、記憶とコンテキスト管理、画像・動画生成、Web 検索、コンピューター操作、Windows PowerShell
    prompts/     モデルが読む全プロンプト:役割、会話ルール、記憶のガイド、区間の初回メッセージ、スキル
  llm/           OpenAI 互換クライアント(モデルへのアクセス)
  magpie/        管理プロセス:隔離ディレクトリ、空きポート、秘密値の生成、ヘルスチェック、異常終了からの再起動、終了処理
  channels/      feishu/(持続接続+CardKit) weixin/(iLink、MIT 告知は LICENSE.openclaw-weixin) messenger/(Telegram・Slack・Discord 共通の送受信)
  store/         SQLite(node:sqlite、ネイティブビルド不要)
  account/       Modelflare:PKCE ループバックログイン、トークン更新、残高と通知、ボット別予算キー、モデル機能と参考価格
  web/           コンソールサーバー(JSON API+SSE の会話ストリーミング)
  cli/           初回設定 init、weixin-login
  modelflare.ts  Modelflare の経路、キー検証(GET /v1/models)、モデル振り分けと出所表示
  guide.ts       初回ガイドの進捗
  i18n/          サーバーの多言語化:エラー、状態、トレイ、システムメッセージ(messages/<namespace>.ts)
  diagnostics.ts 診断:疎通テスト、ログ末尾、秘密情報を除いたレポート
  main.ts        CLI のエントリーポイント
electron/        デスクトップのメインプロセス(起動とトレイ)
ui/              コンソール画面(Preact+htm、ビルド不要)
  design/        デザインシステム:tokens/、base/、components/、ボットのキャラクター bots/
  locales/       画面文言:zh-CN/、en/ など、名前空間ごとのファイル
  css/ lib/ components/ screens/ assets/ main.js
dsh-runtime/     DSH ランタイムの依存関係と AnyModelBot プラグイン(plugins/)
scripts/         setup / build-magpie / fetch-cua-driver / prepare-dsh / bundle-dsh / electron-smoke / check-readme など
vendor/          サブモジュール:magpie(ビルド時にコンパイル)、deepseek-harness、kimi-computer-use
site/            Web サイト(Astro 静的サイト、site/README.md 参照)
docs/            開発ガイド、プライバシー、README の素材(docs/assets/)

ソースから実行する(CLI)

Node.js 22.13 以降と、magpie をコンパイルするための Go 1.26.8 以降が必要です。

npm install
npm run setup        # vendor/magpie を取得し build/bin/ にコンパイル
npm run init         # 任意:ターミナルで初回設定(Modelflare ログイン、Feishu 認証情報)
npm start            # ゲートウェイ、ボット、http://127.0.0.1:3600/ のコンソールを起動

既定のデータ保存先は ./data です(AMB_DATA_DIR で変更可能)。そのほかの環境変数は .env.example にあります。

デスクトップアプリ(Electron)

npm run electron:dev     # 開発モード
npm run electron:smoke   # スモークテスト(画面のない Linux は自動で xvfb-run を使用)
npm run dist             # 現在の環境向けにパッケージ化(magpie は resources/magpie/)
npm run dist:linux | dist:mac | dist:win
npm run test:dsh-bundle  # build/dsh の実ランタイムを Electron でテスト(先に prepare:dsh と bundle:dsh を実行)
  • DSH ランタイム:scripts/prepare-dsh.mjs が対象環境用の dsh-runtime/ を用意し、scripts/bundle-dsh.mjs が resources/dsh/dsh.asar(全 JavaScript を 1 ファイル)と resources/dsh/node_modules/(ネイティブパッケージのみ、約 55 ファイル)にまとめます。Electron メインプロセスと ELECTRON_RUN_AS_NODE の子プロセスは asar を直接読み、初回展開はしません。インストール時の展開対象が数百ファイルに減り、Windows で時間のかかる展開とファイル別ウイルス検査を抑えます。開発時は dsh-runtime/ を直接使います。
  • Windows のコマンド用 PowerShell:サンドボックスでは Windows PowerShell 5.1 が 1 コマンドに 20〜30 秒、PowerShell 7 が約 1 秒かかります。選択順は、システムの動作する PowerShell 7(DSH と同じ起動方法で一度バックグラウンドテストし、ダウンロードはしない)→アプリ専用の 7→5.1 です。使える 7 がなくエージェントが有効なら、公式 PowerShell 7.6.9(LTS)の zip を %LOCALAPPDATA%\AnyModelBot\pwsh\ に取得します。管理者権限、レジストリ変更、PATH 変更は不要で、既存の PowerShell に影響しません。バージョンと x64・arm64 zip の SHA256 は src/agent/pwsh-private.ts で固定します(更新は node scripts/pwsh-hashes.mjs <version>)。取得後にハッシュ、展開後に Microsoft Authenticode 署名を検証し、DSH 形式の試運転(バージョン、仮ファイルの読み書き、外部プログラムの起動)を通過してから使います。失敗・未完了のものは使わず次回起動で掃除します。進捗は会話、設定 → 一般、/status に出し、準備が終わるまでは 5.1 を継続します。待機中のエージェントが裏で切り替わり、アプリ再起動は不要です。削除、ウイルス対策による隔離、ポリシーで起動不能になれば以前の選択肢に戻して理由を通知します。設定 → トラブルシューティングでインストール、再インストール、システム既定値への復帰が可能です。Windows 10 1607 / Server 2016 より古い環境では取得しません。デスクトップは Chromium のネットワーク機能でシステムプロキシを使い、CLI は Node fetch を使います(新しい Node は NODE_USE_ENV_PROXY=1 で HTTPS_PROXY を反映)。AMB_PWSH_MIRROR はミラーの接頭辞を変えますがハッシュ・署名検証は維持し、AMB_PWSH_AUTO_INSTALL=0 は自動取得を止めます。
  • エージェントのコマンドはネットワークを使えます(サンドボックスは書き込みを制限)。HTTP_PROXY / HTTPS_PROXY / ALL_PROXY / NO_PROXY と小文字版、証明書・パッケージ取得先の変数(SSL_CERT_FILE、REQUESTS_CA_BUNDLE、NODE_EXTRA_CA_CERTS、PIP_INDEX_URL、npm_config_registry、GOPROXY など)をアプリから引き継ぎます。環境変数にプロキシがなければ、デスクトップはエージェント起動ごとにシステム設定と PAC を調べ、http://host:port で渡します(src/agent/proxy-env.ts)。ループバックの 127.0.0.1、localhost、::1 は常に NO_PROXY に追加し、プロキシを通しません。
  • データ保存先:<userData>/data(macOS ~/Library/Application Support/anymodel bot/data、Windows %APPDATA%\anymodel bot\data、Linux ~/.config/anymodel bot/data)。ログはその中の logs/app.log です。
  • 単一インスタンスで動作し、閉じると既定ではトレイに入ります(設定 → 一般で終了に変更可能)。トレイには開く、ブラウザーで開く、ログイン時に起動(macOS・Windows)、データフォルダーを開く、終了があります。
  • macOS はタイトルバーなしで、ウィンドウ操作ボタンをサイドバー上部に置きます。最小幅は 860 です。
  • コンソールは 127.0.0.1 のみで待ち受け、毎回ランダムなトークンを作り、他のローカルプログラムによる管理 API の直接利用を防ぎます。
  • 終了はチャネルを先に止め、その後 magpie を止めます。強制終了で残った magpie は次の起動時に処理します(Linux/macOS)。

リリースでは CHANGELOG.md と CHANGELOG_en.md に当該版の項目を書きます。対象はユーザーが気付くアプリの変更であり、サイトや内部実装ではありません。英語サイトでは WeChat・Feishu に言及する行を除外します。package.json の version を更新、コミットし、v<version> タグをプッシュします。変更履歴がないとワークフローは最初に失敗し、あれば GitHub Release のノートとサイトに反映します。.github/workflows/release.yml は OS・アーキテクチャ別の 6 ランナーでビルドし、インストーラーと SHA256SUMS を公開します。署名・公証用のシークレットは同ファイル冒頭のコメントを参照してください。同じタグで .github/workflows/docker.yml も動き、x64+arm64 イメージを ghcr.io/modelflare-ai/anymodel-bot に <version>、latest タグで公開します。

Docker

利用者向けコマンドは docker run -d --name amb -p 3600:3600 -v amb-data:/data ghcr.io/modelflare-ai/anymodel-bot です。ソースからビルドする場合:

git submodule update --init --depth 1 vendor/magpie
docker build -t anymodel-bot .
docker run -d --name amb -p 3600:3600 -v amb-data:/data anymodel-bot
docker exec amb cat /data/ui-token     # http://<host>:3600/?token=<token> を開く

コンテナー内では 0.0.0.0 で待ち受けるためトークン必須です。ポート 3600 をインターネットへ直接公開しないでください。WeChat の QR ログインは設定 › 接続にあります。

モデル(Modelflare)

  • 初回は Modelflare へのログイン・登録ボタンを表示します。標準ブラウザーでログインまたは登録して認可し、アプリに戻ると専用 API キーを発行・接続します。既定モデルを選べば会話を始められます。Docker・リモート環境はブラウザーのコールバックを受けられないため、ログイン後に移動する開けない 127.0.0.1 アドレスのリンクを初回画面に貼り付けます(POST /amb/api/account/login/complete、state と PKCE の検証は同じ)。以前のバージョンで API キーを入力しログインしていない場合、アップグレード時にキーを端末から削除し、ログインが必要になります。
  • 認証方式:RFC 8252 に沿うネイティブアプリの OIDC 認可コード+PKCE(RFC 7636)。公開クライアント(client_id は anymodel-bot)で、クライアントシークレットは持たず不要です。結果は 127.0.0.1 の一時ポートへ返します。Modelflare プロフィールの認可済みアプリから取り消すと、アプリが検知してログイン画面に戻ります。
  • リフレッシュトークンはデータ内の modelflare-account.json(モード 600)に保存し、デスクトップでは OS キーチェーン(Electron safeStorage)で暗号化します。画面にはアカウント名だけを渡します。ログアウトは端末の認可を取り消し、ログイン時に端末とボットへ発行したキーを Modelflare が削除します。
  • 残高は常時表示せず、左下のアバターか設定 → Modelflare で確認します。いずれもウォレット残高を表示します。チャージは Modelflare を開き、アプリへ戻ると残高を更新します。既定 1 米ドルの通知基準(変更・無効化可能)を下回ると一度知らせ、WeChat・Feishu にも送れます。
  • 推論の強さ:モデル選択パネルまたは設定 → Modelflare で選びます(自動 / 低 / 中 / 高)。全体で 1 つの設定で、次のターンから適用されます。自動ではパラメーターを送らず、モデルの既定値を使います。対応モデルにのみ適用されます。Responses API の推論モデルと、モデルプロファイルで推論対応とされた Chat と Claude です(Claude 4.6 以降は adaptive と output_config.effort、それ以前は budget_tokens)。
  • ログインすると設定 → Modelflare に日別・モデル別使用量、Modelflare の通知、招待リンクも出ます。
  • ボットの予算(ログイン必須):ボット設定 → 予算で有効にすると、指定額を上限とする専用キー(ゲートウェイの別 provider)を使い、無効にすると共有キーへ戻ります。
  • 画像・動画:エージェントに media_models(モデル、既定値、引数範囲、参考価格)、media_docs(docs.modelflare.dev からリクエスト形式を取得)、generate_image、generate_video と内蔵スキルを提供します。モデル別の形式を文書で確認してリクエスト本文を作り、ワークスペースの参考画像は workspace:path と表します。キーはアプリから出さず、アプリがボットのキーで呼び出し、結果を media/ に保存して会話へ届けます。
  • 生成前の確認:既定では直ちに生成します。既定以外のモデルや曖昧な依頼を理由に質問せず、妥当に解釈して作成し、使った条件を一行で述べます。見積もりが 0.5 米ドルを超えるときだけ、モデル、プロンプト、条件、参考価格、確認理由を提示します。画像枚数、動画時間・解像度で計算し、費用不明の動画も確認対象です。承認・変更・中止ができ、WeChat は番号・モデル名、Feishu と Web はクリックで回答します。10 分応答がなければ生成しません。毎回確認するには、ボット設定 → 画像・動画 → 生成前に確認で常に確認する設定を選びます。
  • Web 検索:web_search は DeepSeek キーが必要な内蔵検索を使わず、amb-web-search がアプリへ委譲します。初期設定不要で、Exa 公開 MCP、Bing、DuckDuckGo を試し、前回成功したものを優先します。失敗(制限、ボット確認、無関係な Bing 結果)したものは 10 分避けます。設定 → ネットワークとアクセス → Web 検索でキー付きの Tavily・Exa・Bocha・Zhipu、または独自 SearXNG を指定すると最初に使い、失敗時は無料検索へ戻します。キーはローカル DB に保存し、エージェントへ渡しません。デスクトップはシステムプロキシ、CLI は Node fetch(NODE_USE_ENV_PROXY=1 なら HTTPS_PROXY)を使います。
  • チャネルアカウント(src/core/routes.ts):WeChat、Feishu、Telegram、Slack、Discord も設定 › 接続で全体管理し、別名を付けられます。送信者が /bot で選んだボット→アカウントの既定→先頭のボットの順で決定します。/bot は一覧、/bot name は選択を記憶します。各ボットのシステムプロンプトに他のボットと切り替え方を載せ、質問に答えられるようにします。所有者・許可リストはアカウント単位なので、許可された人は全ボットと話せます。アカウントキーは名前空間で、旧チャネルは旧ボット ID を維持し、ログイン、上限、許可、キュー、既定ボットを引き継ぎます。ボット削除はアカウントに影響しません。
  • 接続アカウント(src/agent/accounts.ts):全ボットが設定 › 接続の一つの一覧を共有し、同サービスの複数アカウントを使えます。「1 つ目と 2 つ目の Feishu を調べて」と頼めます。amb-connections がブリッジで呼び出しをアプリに渡すためトークンはエージェントに届きません。account 引数で番号・名前を選び、connected_accounts で一覧化します。アカウントがあるサービスだけツールを出します。読み取り専用のボットと観察モードのルールは書き込めず、ホストも再検査します。チャネルアカウントは別項目で扱います。
    • Notion(notion.ts):ワンクリック認可またはトークンを選びます。トークンは REST API、認可は PKCE・動的登録付き OAuth でローカル /oauth/notion/callback に戻り、公式リモート MCP(mcp.notion.com)を呼びます。どちらも notion_search、notion_read_page、notion_query_database を提供し、読み取り専用でなければ notion_create_page と notion_update_page も出します。削除ツールはありません。
    • Feishu(feishu-account.ts):公式 lark-cli と同様、スキャンして個人アプリを作るか自分のアプリを入力し、デバイス認可でユーザートークンを取得します。feishu_list_chats、feishu_read_chat、feishu_search_messages の読み取り専用です。
  • 既定の画像・動画モデルは初回にテキストモデルと一緒に選び、後から設定 → Modelflare で変更できます。自動では、推奨順のうち参考素材が不要な最初のモデルを使います。
  • モデル選択にはコンテキスト長、画像認識・ツール・推論機能、公開料金表の入力・出力 100 万トークン当たりの最低参考価格を出します。最終的な金額は請求書が基準です。
  • コストと品質(ログイン必須):アプリのキー(端末キーと予算キー)には Modelflare Smart Key の routing_strategy を付けます。低コスト low_cost は最低倍率から、バランス balanced は中間から(既定)、品質 stable は最高倍率から試します。設定 → Modelflare、またはモデル選択の最初のスライダーで変えると、既存キーも PATCH /api/connected-app/api-keys/<id> で更新し、DB の account.routing に保存します。未選択の既存ユーザーには最初のキー検査で一度だけバランスを適用します(ログは applied the default key routing strategy)。応答に routing_strategy が返る場合だけ対応と判定します。400/422 で拒否されたらそのフィールドなしで再発行し、キー発行・検査・予算を失敗させません。無視された場合も未対応とし、設定を隠して 1 日後に再検査します。
  • 知能(2 番目のスライダー):利用可能かつ Artificial Analysis データのあるモデルから、知能指数(高いほど良い)とタスク単価(低いほど良い)のパレート境界を求めます。最大 5 段階で、最安と最高知能を必ず含めます。実際の推論強度に合わせ、Responses API の推論モデルは既定 medium なので AA の medium、ほかは既定行を使います(src/account/model-quality.ts)。費用は AA の公式価格でのタスク単価×現在の品質設定での価格係数(公開グループの倍率×販売倍率)です。低コストは最低、品質は最高、バランスは中間、企業専用グループは除外し、未ログイン・未対応時はバランスとみなします。スライダーでモデルを切り替え、名前を押すと全一覧が開き、段階にないモデルはカスタム表示です。2 段階未満なら一覧だけになります。計算は ui/lib/frontier.js です。
  • AA データは assets/model-quality.json(updatedAt、source、必要フィールドのみ、Modelflare ID に変換済み)で配布します。node scripts/update-model-quality.mjs は https://artificialanalysis.ai/leaderboards/models と Modelflare の公開料金表を取得します。AA_API_KEY があれば公式 API を使いますが、その応答フィールドはキー付きでは未検証です。--html <file>、--pricing <file> は保存済みデータ、--dry-run は表示のみです。列欠落、行形式変更、数値の解釈失敗、行数・対応モデル不足では理由を出して終了コード 1 で止まり、既存スナップショットを変更しません。規則で対応付けできないモデル名は OVERRIDES に入れます。出典は選択画面の下に表示します。
  • 出所表示:Modelflare のリクエストには X-Modelflare-Skill: anymodel-bot/<version>、リンクには utm_source=anymodelbot&utm_campaign=amb_<placement> を付けます。アプリ内は amb_signup、amb_topup、amb_console など、README・リポジトリ文書は amb_readme、サイトは amb_homepage です。形式を test/utm.unit.test.ts で固定します。
  • API ドメイン:設定 → Modelflare → API ドメインで https://modelflare.dev/v1、https://origin.modelflare.dev/v1、https://cf.modelflare.dev/v1 を選べます。手動テストは実行中の端末から 3 ドメインの /v1/models に認証なしで 3 回ずつ接続し、中央値と成功数を表示します。HTTP 401 は応答として数えますが、キーの有効性や生成速度の証明ではありません。自動切り替えはありません。旧設定 auto / global はメイン、cn は origin、cf は cf を選びます。これらは互換値で、地域や品質の意味はありません。
  • 設定 → Modelflare ではアカウント、残高とチャージ、残高通知、使用量、通知、招待、費用対効果、推論の強さ、既定モデル、一覧更新を扱います。
  • 入力欄の右側のモデルボタンで現在のセッションのモデルを変え、ボットの既定値にもできます。/model、/reset、/new、/status、/stop、/help も使えます。
  • アクティビティ:モデルのリクエスト(時間・トークン)、ツール(引数・結果)、再試行、サブエージェントなど全手順を返信上の時間表示に折りたたみ、クリックで開けます。WeChat・Feishu は情報パネルの最近のセッションから進行中の処理を見て中止できます。
  • 停滞したメッセージ:全チャネルの /stop、または情報パネルの停止で現在のターンを直ちに終えます。10 分進捗がない場合(モデル応答もツールもなく再試行だけ。承認・回答待ちは除外)や 1 ターン 30 分の上限で自動中止します(AMB_AGENT_IDLE_TIMEOUT_MS、AMB_AGENT_TURN_TIMEOUT_MS)。プロセス内の amb-control プラグインがそのターンだけを取り消し、同ボットの他の会話は続きます。10 秒(AMB_STOP_GRACE_MS)以内に止まらなければプロセスを再起動します。/status で現在の手順と最後の進捗からの時間を見られます。Web でボットを切り替えたり再読み込みしても進行中の処理は止まらず、戻ると送信内容、途中の返信、アクティビティを復元します。キュー待ち、エージェント起動中、承認待ち、通常会話でも停止できます。
  • 追加指示:エージェント稼働中に送った文章・画像・ファイルは現在のターンに入り、次の手順でモデルが読み、一つの返信にまとめます。先に短い受信通知を送信キュー経由で送り、10 分以内に送れなければ破棄します。通常と同じ利用許可を検査し、未許可の人のメッセージは追加しません。前のメッセージをエージェントが受け取る前や終了処理中、また /model・/reset などのコマンドは従来どおりキューに入れます。Web でも返信中に入力を続けられます。
  • 長いコマンドはバックグラウンドへ:30 秒(Windows PowerShell は 60 秒)を過ぎても動くコマンドは、ターンを塞がないバックグラウンドジョブに移し、実行中だと回答します。終了時に結果でエージェントを起こし、同じ会話に新しい返信を送ります。Web はリアルタイム、WeChat・Feishu は通常の送信キューを使います。ID をセッションとターンから作り一度だけ送り、WeChat の時間・件数制限は送信時に検査します。Feishu は DB に保持した最新受信メッセージ ID に返信します。アクティビティ、/status、停止、監視タイマーも通常のターンと同様です。
  • 会話ごとのモデル:一つのプロセス内でも各会話が独自のモデルと API を使います。API ごとに provider、モデルごとにコンテキストと最大出力を持ちます。切り替えで再起動せず、初期パッチにないモデルは実行中に追加します。
  • プロセスの入れ替え:DSH SDK はセッションを閉じられず、タスク・ルールのセッションが再起動まで残ります(完了して待機中の 1 セッション当たり実測約 0.25〜0.45 MB)。100 個を超えると、完全な待機状態で交換します。会話ターン、実行・終了処理中のタスクやルール、承認待ち、圧縮、バックグラウンドジョブがないことが条件です。セッションはそのまま継続し、処理を中断せずユーザーにも表示しません。診断状態の taskSessions と recycles に現れ、しきい値は AMB_DSH_RECYCLE_SESSIONS で変えられます。
  • 再起動後の通知:終了・クラッシュ時に処理中だったメッセージには会話別の DB マーカーを保持し、完了で消します。次回起動時にその会話で一度だけ「前のメッセージはアプリの再起動で完了しませんでした。もう一度送信してください」と知らせます。自動再送はしません。Web は履歴に記録し、WeChat は保存済み context_token と同じ返信上限を使います。時間・件数制限が尽きていれば次のメッセージへの返信の前に通知します。Feishu は元の会話に送ります。
  • エージェント API:Modelflare の公開カタログで選択します。Responses 対応モデル(GPT-5.4 以降、Grok 4.5 以降、DeepSeek V4、GLM-5、Kimi K3 など)は /v1/responses(推論強度は既定 medium、暗号化された推論を履歴と再送)、Responses 非対応で Anthropic Messages 対応の Claude は /v1/messages、その他・カタログ取得不能・外部エンドポイントは Chat Completions です。プロセスが初めてモデルを使う際に決め、診断に直前ターンの api とモデル一覧を出します。AMB_AGENT_API=chat で全体を Chat Completions に固定できます。通常会話は引き続き Chat Completions です。上流が Responses/Messages を拒否した場合(HTTP 400/404/405/415/422、または unsupported parameter/endpoint)、そのモデルを 24 時間 Chat Completions に切り替えます。レート制限、残高、権限、上流障害、コンテキスト超過は対象外です。dsh/api-fallback.json に記録し、ログに警告、状態に openai-completions (fallback: reason) を出します。まだツールを呼んでいなければ再起動なしで現在の会話を Chat でやり直し、既に呼んでいればエラーを返し次ターンから変更します。
  • 内蔵ゲートウェイ:magpie はデータ内の独自 HOME・設定ディレクトリを使う --gateway モードです。既存の Claude/Codex サブスクリプション認証情報は読まず、エージェント設定も変更しません。自動更新・アカウント検出は無効です。アプリのプロセス内部からだけ呼び、コンソールは magpie のページや /v1 を中継しません。
  • API キーは隔離したゲートウェイ設定だけに保存し、コマンドラインやログに載せません。画面には末尾だけを渡します。
  • 開発・テスト:AMB_MAGPIE_BASE_URL で任意の OpenAI 互換先を指定すると、ゲートウェイを起動せず接続済みとして扱い、アカウント機能は使えません。AMB_MODELFLARE_BASE_URL は Modelflare、AMB_MODELFLARE_ISSUER はログイン・アカウント API をローカルのモックに向けます。

インターフェース

  • グループチャット(src/core/groups.ts、ui/screens/group.js):ボットが 2 体以上あると + から作れます。各メンバーは <bot>:web:group:<group> という会話を持ち、モデル、権限、記憶、承認、費用は個別会話と同じ処理を使います。ユーザー発言は group:<group> に保存し、ID で時系列を統合します。@ されたボット(@everyone は全員)が答え、指定がなければ前の回答者が続けます。回答中に他のメンバーを @ すると引き継ぎ、ユーザー発言当たり最大 6 回までです。グループ内では同時に 1 体だけが回答します。
  • サイドバー:ボット一覧(アバター・名前・最新メッセージ)、+ 新規作成、右クリックで名前変更・削除。左下のアバターで残高、歯車で設定(⌘/Ctrl+,)を開きます。
  • 会話:上のボット名から情報パネル(⌘/Ctrl+⇧+I)を開き、既定で応答するチャネルアカウント、承認待ち、タスク・ルール、記憶、最近のセッションを確認します。⚙ はボット設定です。返信は Markdown とコードのワンクリックコピーに対応し、逐次表示して Esc で止められます。承認・質問はカードになり、上にスクロールしても強制的に末尾へ戻しません。
  • コマンドパレットは ⌘/Ctrl+K。外観(システム・ライト・ダーク)は設定 → 一般にあります。
  • 言語:中国語簡体字、英語、日本語、韓国語、ロシア語を設定 → 一般 → 言語で選びます。初回画面右上やコマンドパレットでも選べます。既定はシステムに従い、未対応言語では英語です。選択は config.json の ui.lang に保存し、トレイ、サーバーのエラー・状態、WeChat/Feishu に送る /help や承認通知にも反映します。CLI・Docker のシステム設定は AMB_LANG、次に LC_ALL / LC_MESSAGES / LANG を見て、なければ中国語簡体字です。ログ、モデル用プロンプト、ユーザーが付けた名前は翻訳しません。
    • 画面文言は ui/locales/<lang>/<namespace>.js に置き、t("namespace.key", { params })(ui/lib/i18n.js)で使います。サーバー文言は src/i18n/messages/<namespace>.ts にあり、キーを型検査します。各画面リクエストの x-amb-lang と同じ言語でサーバーが返答します。
    • 新規文言は両方の基準言語へ追加します。node scripts/i18n-check.mjs [files…] は画面コードに残る中国語、存在しないキー、zh/en の不一致を検出します。npm test の test/i18n.unit.test.ts でも同じ内容を検査します。フォント名や中国語を照合する正規表現など必要な文字列には、その行に // i18n-ignore を付けます。
  • 初回チェックリスト:空の会話に、挨拶、モデル変更、WeChat 接続、作業依頼、記憶、画像生成の 6 段階を出します。最後は画像・動画モデルの有無にかかわらず内蔵デモです。通常どおり即生成して会話に表示しますが、ボットに送らずモデルも呼ばず課金しません。画像は ui/assets/guide-demo.svg です。費用をかけずに流れを学ぶ目的で、実際の描画依頼・画像受信でも完了になります。送信で直接試し、案内ボタンや左下の項目で該当操作をリングで強調するカードを出します。返信、モデル変更、ファイル・画像受信、チャネル接続、記憶への書き込みで自動完了し、config.json の ui.guide(API /amb/api/guide)に保存します。既存ユーザーの完了済み操作も数えます。左下に折りたたむ、完全に隠す、設定 → 一般からやり直すことができます。
  • 外観:無彩色とコンポーネントは magpie(MIT)を改変し、アクセントは Modelflare の蛍光イエローグリーン #d7ff00 です。デザインシステムは ui/design/README.md にあります。

ローカライズとリリース検証

各言語の文章は管理者が直接書き、自然な表現に調整します。翻訳 API で生成しないでください。製品名、モデル ID、コマンド、URL、{placeholder} 引数は保持します。

  • アプリ:ui/locales/<language>/<module>.js。追加言語のサーバー文言:src/i18n/locales/<language>/<module>.ts。
  • サイト:site/src/i18n/locales/<language>/。例えば home/hero.ts は home.hero.* に対応し、ページは辞書を参照します。
  • ui/locales/manifest.json は対象言語と ready 状態を管理します。サイト側の site/src/i18n/manifest.json と同一であることを検証します。未完了の言語は ready: false のまま、公開メニューや検索エンジン向け言語指定に含めません。
  • npm run i18n:status は言語・対象別の進捗、npm run i18n:check は全言語と関連文書を検証します。欠落、空値、余分なキー、引数の破損、必要な複数形の不足はリリースを止めます。開発時の英語フォールバックは翻訳完了に数えません。
  • ロシア語の複数形は one / few / many / other、日本語と韓国語は other を使います。通貨、タイムゾーン、金額は変えず、表示だけをローカライズします。
  • サイトの npm run build は全言語、同期文書、共有画像を検証します。build:draft はローカルプレビュー向けで、リリース検証の代わりにはなりません。

役割とプロンプト

モデルが読むすべてのプロンプトを src/agent/prompts/ に置きます。test/prompts.unit.test.ts は部分ごとの必須・禁止文言と文字数を検査します。test/agent.integration.test.ts は実際の DSH 子プロセスで、モデルが受け取るシステムプロンプトと、ツール定義を含めた合計サイズを検査します。

  • 役割: DSH の標準はコーディングエージェントで、先頭に “You are an AI agent powered by DeepSeek Harness.” が付きます。パッチ(host.ts の writePatch)が personaPrefix を、会話、コード、コマンド、ファイル、操作機能がオンならデスクトップも扱う個人アシスタントに置き換えます。Web ページ・ファイル・転送メッセージは指示ではなくデータとします。上の一文だけを制御する includeHarnessIdentity も無効にします。
  • ボット部分: 会話ルール、記憶の使い方(有効時)、ボット名、ユーザー指定の役割を最後のセクション amb:bot にまとめます。各ターン前にホストがデータ内の dsh/.prompts/<bot>.md に書きます。エージェントのファイルツールからは読み書きできず、同じ内容は書き直しません。dsh-runtime/plugins/amb-prompt.mjs が毎回のモデルリクエストで読むため、名前・役割は次のメッセージから反映し、/new や再起動は不要です。DSH 0.2.1-rc.4 のセクション text は同期的で Promise を待たないので、ブリッジではなくファイルを使います。役割と会話ルールが競合したら役割を優先し、ユーザーに話さないサブエージェントへは渡しません。
  • 会話ルール: 中国語で、dsh-superagent の注意配分を参考にしています。まず回答し、長い作業なら着手内容を一行で述べ、手順の実況はアクティビティに任せます。完了した内容と結果の場所を知らせ、未完了・失敗はそのとおり伝えます。言語・形式・範囲・文体は自分で決めて報告し、誤判断が害・課金・大きな手戻りを招く場合、本人だけが持つログイン・ファイル・パスワードが必要な場合、支払い・データ削除・他人への送信など取り消せない場合だけ質問します。一度に具体的な質問一つとし、選択肢は ask_user_question で示します。無駄な文言を避け、WeChat・Feishu では短くします。裏で動くタスクも同じ原則で、選んだ条件を結果に書きます。
  • 区間の初回メッセージ: チャネル(WeChat はプレーンテキスト、Feishu と Web は Markdown)、開始時の長期記憶、前区間の引き継ぎ、その後にユーザーメッセージを置きます。グループ記憶・チャネルは会話ごと、記憶は更新ごとに違うため、共有プレフィックスキャッシュを壊さないようシステム部分に入れません。区間内では固定し、後の更新は recall で読みます。
  • プレフィックスキャッシュ:変更のない部分はバイト単位で維持し、役割変更は末尾だけを変えます。アップグレード前に始まった会話には、次の区間(/new または管理機能による切り替え)まで古い役割が残ります。

ファイルの権限

ボットごとに権限プリセットを持ちます。入力欄左下またはボット設定 → 権限で変更し、/status で確認できます。

  • ワークスペースへの書き込み(既定): コマンドをサンドボックスで実行し、そのボットのワークスペースだけを変更します。外側は会話で確認します。
  • 読み取り専用: ファイルを変更せず、コマンドも読み取り専用のサンドボックスで実行します。
  • フルアクセス: 頻繁な確認を避けたい、リスクを理解している人向けです。サンドボックスを使わずユーザーの権限で直接動かし、範囲外でも確認しません。DB、チャネルトークン、キーなどアプリ自体のデータを含む全ファイルを読み書きできます。再帰的な削除だけは従来どおり確認します(WeChat は番号回答、Feishu/Web はカード)。rm -r / -rf / --recursive(sudo、xargs、sh -c 内も)、find -delete、git clean、rsync --delete、PowerShell Remove-Item / rm / del / rd / rmdir の -Recurse と短縮形、cmd rd /s、del /s、robocopy /MIR、Python shutil.rmtree、Node fs.rm(…, { recursive }) などを検査し、指定されたスクリプトファイルも読みます。選択時に確認し、権限ボタンと設定を赤で示します。
    • 誤削除防止であり、セキュリティ境界ではありません。コマンドの文字列を調べるので、実行中に組み立てる eval "$(…)"、curl … | sh や make clean、npm run clean 内の動作は見えません。判定に迷えば確認します。現在のモデルとタスクを信頼する場合だけ有効にしてください。

ボットを利用できる人

自分のコンピューター上で、場合によっては全権限で動くため、既定では所有者と許可した人だけが会話できます。チャネルアカウント単位で判定し、許可済みなら全ボットと話せます(src/core/access.ts)。

  • 所有者: WeChat は QR を読んだアカウントです。Feishu はアプリ作成が QR でも ID・Secret 入力でも個人ログインがないため、接続後最初に個別メッセージを送る人を所有者とします。接続後に本人が一言送れば通常どおり回答します。スキャン者 ID を返さなかった WeChat も同じです。ボット設定の利用者欄から Feishu 所有者を確認でき、変更の確認後に消すと次の送信者が所有者になります。他アプリへの切り替えや接続解除でも消えます。拒否済みの人は所有者になれず、ローカル Web 会話は制限しません。
  • それ以外: 「まだ利用は許可されていません。所有者に通知しました」と一行だけ返します(人ごとに最大 1 時間に 1 回)。キューに入れず、モデルを呼ばず、課金もしません。設定 › 接続の対象アカウントの管理に許可・拒否を表示し、4 桁のペアリングコードを所有者へ送ります(アカウントごとに毎時最大 3 件、所有者の発言が過去 24 時間以内の場合のみ)。所有者は 同意 1234 / 拒绝 1234 または yes 1234 / no 1234 で答えます。コードはツール承認と衝突せず、拒否済みの相手には無応答です。
  • 許可リストは対象アカウントの管理にあり、削除すると次のメッセージで再申請できます。/status にも表示します。
  • アップグレード時は既に個別会話がある相手を「更新前に利用」として許可し、利用を途切れさせません。別の WeChat で再スキャンしても前所有者をリストに残します。
  • グループ:今のチャネルはグループを届けません(Feishu は個別のみ、WeChat iLink はグループなし)。グループメッセージは従来の扱いとし、対応時に access.ts へ規則を加えます。

返信を失わない仕組み

最終返信、ファイル、承認依頼、通知は、送信前にローカル DB の送信キューへ記録します(src/core/outbox.ts)。逐次カード更新と入力中表示は除きます。

  • 同じ会話では一つずつ順番に送り、ネットワーク・プラットフォームのエラーは 5 秒から最大 5 分まで間隔を広げて再試行します。チャネルがオフラインなら待ちます。
  • 終了・クラッシュ後は次回起動で続け、送信済みは再送しません。長文は最初の未送信部分から再開します。受信メッセージから ID を作るので二重配信でも最終返信は一度です。クラッシュ時に送信中だった部分だけ重複する可能性があり、固定の Feishu uuid(1 時間重複排除)と WeChat client_id を付けます。
  • WeChat は最後の受信から 24 時間内、受信 1 件当たり最大 10 返信です。制限にかかったら捨てずに保留し、次に相手が送ると返信より先に元の順序で一度だけ送ります。1 通に収まる文章は「不在の間に:…」にまとめ、ファイルはそのまま送ります。最大 7 日保持し、受信通知や承認依頼のような短命のものは独自期限を使います。
  • 拒否が続く、長時間待ちすぎるなど送れなくなったものは、ログと診断に理由を残します。

バックグラウンドタスクとルール

時間のかかる仕事は裏で動かし、会話を止めません(設計 docs/design/background-tasks-and-proactive.md、実装 src/tasks/)。

  • タスク: task_start で専用 DSH セッション task-<id> と tasks/<name>-<id6>/ を作り、予定を一行で伝えます。結果は依頼元に戻り、WeChat の引用や Feishu の返信で続けられます。質問は会話ごとに一度に一つです。アプリ再起動後は続行し、外部操作の繰り返し前に確認します。/tasks で一覧、/stop <number> で停止します。
  • ルール: rule_create またはボット設定 › ボットからのメッセージ › ルールで作り、直ちに実行モードにします。ユーザーの文言を許可とし、毎回調べて意味のある結果だけ送ります。文言変更後も実行を維持します。「まず観察して」または編集画面の「観察」を選ぶと、読み取り専用で送信せず予定を記録します。3 回後に「あなたの対応待ち」で実行への切り替えを尋ねます。実行ごとに新しいセッションを使い、履歴を Markdown に書き出せます。
  • 見えるが騒がしくない: 情報パネルにタスク・ルールを並べ、終了分は折りたたみます。依頼元、最新進捗、予算、フォルダー、各実行手順を開けます。待ち事項は「あなたの対応待ち」に集約します。通知は結果・判断・失敗のみで、静かな時間(既定 22:00〜08:00)、日次上限(WeChat 3 件、Feishu 5 件)、まとめ通知はボット設定で管理します。
  • 予算: 既定はタスク 1 米ドル、ルール実行 0.10 米ドル、ルールごとの月額 3 米ドルです。Modelflare 参考価格で見積もり、上限で停止して確認します。タスク詳細・ルール編集で変更できます。ボット予算の残高が 20% 未満になると裏の作業を止め、会話用に残します。
  • 一時停止: ボット設定 › ボットからのメッセージ › バックグラウンド処理を一時停止、またはボットへの依頼でタスク・ルール・通知を保留します。会話は続けられます。
  • 保持: タスクと履歴は 30 日保持し、30 日未使用のタスクはアーカイブします。未使用フォルダーは 30 日で DSH セッション(dsh/<bot>/sessions/)とともに削除します。SDK に削除 API がないためアプリが行い、プロセス内で開いている分は交換後に削除します。確認や通知は行わず、27 日経過時に削除予定日を詳細に表示します。「保持」で残せます。予定日を設定してから最低 3 日間は消しません。詳細にはサイズを表示し、フォルダー込みでタスクを削除できます。

コンピューター操作

ボット設定(情報パネルの ⚙)→ コンピューター操作でオン・オフ、バックエンド、承認方式を選べます。/status と設定に現在の方式、利用可否と理由を出します。

  • バックエンド
    • Cua Driver(既定、3 種のデスクトップ OS): 公式ビルドの cua-driver 0.37.0(MIT)を同梱します。scripts/fetch-cua-driver.mjs がビルド時に OS・アーキテクチャ別に取得し SHA256 を検査します。cua-driver mcp として動かし、常に CUA_DRIVER_PERMISSION_MODE=bounded と機能マニフェストを使い、--dangerously-bypass-approvals は使いません。子プロセスの環境から秘密情報を除き、テレメトリーと run_script を無効にします。必要な 24 ツール(ウィンドウ・画面読取、アプリ起動、クリック、文字・キー入力、キー組合せ、スクロール、ドラッグ、値設定、メニュー等)だけを出します。スクリプト、プロセス終了、クリップボード、ブラウザーへの注入、録画、更新等は見せず拒否します。マニフェストはインストール済み GUI アプリを列挙(Linux .desktop、macOS /Applications、Windows スタートメニュー)し、全画面入力を許可します。有効期間は最大 24 時間で、その前に再起動します。
    • Codex Computer Use ブリッジ(任意、macOS のみ): kimi-computer-use です。OpenAI Codex Computer Use のローカルインストールが必要で、利用不能なら Cua Driver に戻ります。
  • 承認: 読み取り、スクリーンショット、クリック、入力、キー、スクロール、ドラッグ、値設定は既定で確認なしに自動実行します。画面変更前に尋ねる設定もあり、読み取りは常に自動です。更新時は既定ボットを含め既存のボットも自動へ移行します。読み取り専用のボットには読むツールだけを出します。
  • OS ごとの注意
    • macOS:システム設定 → プライバシーとセキュリティでアクセシビリティと画面収録を許可します。--direct モードで動き、実機検証は未完了です。
    • Linux:X11 は AT-SPI(at-spi2-core とアプリのアクセシビリティ有効化が必要)で UI を読みます。Wayland は XWayland アプリの手前のウィンドウだけを操作し、画面にも制約を出します。DISPLAY / WAYLAND_DISPLAY のない環境では使えません。
    • Windows:ログイン中ユーザーの対話型デスクトップセッションが必要です。サービス・定期タスクの非対話セッションは対象外です。
  • スクリーンショットは画像対応モデルだけに送り、WeChat・Feishu の会話に中継しません。求められた場合だけファイルとして送ります。
  • cua-perception、OmniParser(AGPL)、Cua Spaces(FSL)は同梱しません。

Feishu アプリの設定

最も簡単なのは設定 › 接続 → Feishu → アカウント追加で QR を読み、ボットアプリを作ってから Feishu で話しかける方法です。

既存の企業向けカスタムアプリを使う場合は、自分のアプリを使う項目を選び、次を設定します。

  1. Feishu Open Platform で企業向けカスタムアプリを作り、ボット機能を追加します。
  2. 次の権限を有効にします。
    • im:message.p2p_msg:readonly:ユーザーからボットへの個別メッセージを読む。
    • im:message:send_as_bot:アプリとしてメッセージを送る。
    • cardkit:card:write:逐次返信用のカードを作成・更新する。
    • im:message.history:readonly:履歴を読む。持続接続はオフライン中のメッセージを再送しないため、起動・再接続時に過去 7 日で使われた会話から直近 24 時間分を最大 20 件ずつ補います。権限がなくても他機能は動きますが補完はできず、一度通知します。
  3. 設定 › 接続 → Feishu → アカウント追加 → 自分のアプリを使う、で App ID / App Secret を保存します。次の設定を保存する前に持続接続がオンラインである必要があります。
  4. Events & callbacks の購読モードで Receive events through persistent connection を選び、im.message.receive_v1 を追加します。
  5. バージョンを公開し、自分を利用可能範囲に追加して、自分の Feishu から一言送ります。接続後の最初の送信者が所有者です(ボットを利用できる人 参照)。

現状は一対一(p2p)のみで、グループメッセージは無視します。

WeChat(iLink)

  • 設定 › 接続 → WeChat → アカウント追加 → QR コードでログイン、でスキャンして確認します。または npm run weixin:login を実行します。QR はターミナルに表示し、データ内に PNG でも保存します。
  • ログイン状態、同期カーソル、context_token はデータ内に保持して再起動後も使います。
  • プラットフォーム制限:受信ごとに 24 時間内で最大 10 件返信します。生成完了後にまとめて送り、4,000 文字を超えたら分割します。生成中は入力中を表示します。
  • 画像・ファイル・動画:送信・引用されたものを WeChat CDN から取得し復号します(各最大 50 MB)。エージェントではワークスペースの inbox/ に保存し、パスを伝えて読取・処理・生成の参考に使います。Claude、GPT-5/6、Gemini、Grok 4、Kimi K3、Muse Spark 等の画像対応モデルには画像自体も送り、それ以外はパスのみです。Linux は Electron 上の sharp がクラッシュするため、まだ画像を直接渡さずパスのみです。ボットが提示するファイル(present)は画像・ファイルとして WeChat に戻します。
  • セッション失効(-14)でチャネルを一時停止して画面に通知します。再スキャンで再開します。

開発とテスト

npm run typecheck
npm test            # 単体+オフライン E2E(Feishu/iLink/Modelflare のモック、ストリーミングと停止を含む)+ゲートウェイ統合(ビルド済み magpie が必要)
npm run docs:check  # README 検証:素材の存在とサイズ、zh/en の構造、相対リンクとアンカー、禁止表現、代替テキスト

README の素材一覧と収録仕様は docs/assets/README.md を参照してください。

ライセンス

MIT です。LICENSE を参照してください。magpie(MIT、改変した画面スタイルを含む)、Tencent openclaw-weixin(MIT)等の第三者コンポーネントは THIRD_PARTY_NOTICES.md と設定 → このアプリについてに掲載しています。