diff --git a/README.ja-JP.md b/README.ja-JP.md index 974a547..76d7a2f 100644 --- a/README.ja-JP.md +++ b/README.ja-JP.md @@ -1,451 +1,5 @@ +# 智念助手 -

- ClawX Logo -

+This repository has been customized from the ClawX base project into **智念助手**. -

ClawX

- -

- OpenClaw AIエージェントのためのデスクトップインターフェース -

- -

- 機能 • - なぜClawXなのか • - はじめに • - アーキテクチャ • - 開発 • - コントリビューション -

- -

- Platform - Electron - React - - chat on Discord - - Downloads - License -

- -

- English | 简体中文 | 日本語 | Русский -

- ---- - -## 概要 - -**ClawX**は、強力なAIエージェントと日常のユーザーとの間のギャップを埋めます。[OpenClaw](https://github.com/OpenClaw)をベースに構築されており、コマンドラインによるAIオーケストレーションを、アクセスしやすく美しいデスクトップ体験に変換します。ターミナルは不要です。 - -ワークフローの自動化、AI搭載チャネルの管理、インテリジェントなタスクのスケジューリングなど、ClawXはAIエージェントを効果的に活用するために必要なインターフェースを提供します。 - -ClawXはベストプラクティスのモデルプロバイダーが事前設定されており、Windowsおよび多言語設定をネイティブにサポートしています。もちろん、**設定 → 詳細設定 → 開発者モード**から高度な設定を微調整することもできます。 - ---- -## スクリーンショット - -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- ---- - -## なぜClawXなのか - -AIエージェントの構築にコマンドラインの習得は不要であるべきです。ClawXはシンプルな哲学のもとに設計されました:**強力な技術には、あなたの時間を尊重するインターフェースがふさわしい。** - -| 課題 | ClawXのソリューション | -|------|----------------------| -| 複雑なCLIセットアップ | ワンクリックインストールとガイド付きセットアップウィザード | -| 設定ファイル | リアルタイムバリデーション付きのビジュアル設定 | -| プロセス管理 | ゲートウェイライフサイクルの自動管理 | -| 複数のAIプロバイダー | 統合プロバイダー設定パネル | -| スキル/プラグインのインストール | 組み込みのスキルマーケットプレイスと管理機能 | - -### OpenClaw内蔵 - -ClawXは公式の**OpenClaw**コアを直接ベースに構築されています。別途インストールを必要とせず、アプリケーション内にランタイムを組み込むことで、シームレスな「バッテリー同梱」体験を提供します。 - -私たちはアップストリームのOpenClawプロジェクトとの厳密な整合性を維持することにコミットしており、公式リリースが提供する最新の機能、安定性の改善、エコシステムの互換性に常にアクセスできることを保証します。 - ---- - -## 機能 - -### 🎯 ゼロ設定バリア -インストールから最初のAIインタラクションまで、すべてのセットアップを直感的なグラフィカルインターフェースで完了できます。ターミナルコマンド不要、YAMLファイル不要、環境変数の探索も不要です。 - -### 💬 インテリジェントチャットインターフェース -モダンなチャット体験を通じてAIエージェントとコミュニケーションできます。複数の会話コンテキスト、メッセージ履歴、Markdownによるリッチコンテンツレンダリング(GitHub 風テーブルや KaTeX による LaTeX 数式 `$インライン$`、`$$ブロック$$`、`\(インライン\)`、`\[ブロック\]` を含む)に加え、マルチエージェント構成ではメイン入力欄の `@agent` から対象エージェントへ直接ルーティングできます。 -`@agent` で別のエージェントを選ぶと、ClawX はデフォルトエージェントを経由せず、そのエージェント自身の会話コンテキストへ直接切り替えます。各エージェントのワークスペースは既定で分離されていますが、より強い実行時分離は OpenClaw の sandbox 設定に依存します。 -各 Agent は `provider/model` の実行時設定を個別に上書きできます。上書きしていない Agent は引き続きグローバルの既定モデルを継承します。 - -### 📡 マルチチャネル管理 -複数のAIチャネルを同時に設定・監視できます。各チャネルは独立して動作するため、異なるタスクに特化したエージェントを実行できます。 -現在は各チャンネルで複数アカウントを扱え、Channels ページでアカウントの Agent 紐付けやデフォルトアカウント切替を直接管理できます。 -カスタムのチャンネルアカウント ID には、ルーティング不一致を防ぐため OpenClaw 互換の正規形式(`[a-z0-9_-]`、英小文字、最大 64 文字、先頭は英小文字または数字)を必須にしています。 -ClawX には Tencent 公式の個人 WeChat チャンネルプラグインも同梱されており、Channels ページからアプリ内 QR フローで直接 WeChat を連携できます。 - -### ⏰ Cronベースの自動化 -AIタスクを自動的に実行するようスケジュール設定できます。トリガーを定義し、間隔を設定することで、手動介入なしにAIエージェントを24時間稼働させることができます。 -定期タスク画面では外部配信を「送信アカウント」と「受信先ターゲット」の 2 段階セレクターで設定できるようになりました。対応チャネルでは、受信先候補をチャネルのディレクトリ機能や既知セッション履歴から自動検出するため、`jobs.json` を手で編集する必要はありません。 - - -### 🧩 拡張可能なスキルシステム -事前構築されたスキルでAIエージェントを拡張できます。統合スキルパネルからスキルの閲覧、インストール、管理が可能です。パッケージマネージャーは不要です。 -ClawX はドキュメント処理スキル(`pdf`、`xlsx`、`docx`、`pptx`)もフル内容で同梱し、起動時に管理スキルディレクトリ(既定 `~/.openclaw/skills`)へ自動配備し、初回インストール時に既定で有効化します。追加の同梱スキル(`find-skills`、`self-improving-agent`、`tavily-search`)も既定で有効化されますが、必要な API キーが未設定の場合は OpenClaw が実行時に設定エラーを表示します。 -Skills ページでは OpenClaw の複数ソース(管理ディレクトリ、workspace、追加スキルディレクトリ)から検出されたスキルを表示でき、各スキルの実際のパスを確認して実フォルダを直接開けます。 - -主な検索スキルで必要な環境変数: -- `TAVILY_API_KEY`: `tavily-search` 用(上流ランタイムで OAuth 対応の場合あり) - -### 🔐 セキュアなプロバイダー統合 -複数のAIプロバイダー(OpenAI、Anthropicなど)に接続でき、資格情報はシステムのネイティブキーチェーンに安全に保存されます。OpenAI は API キーとブラウザ OAuth(Codex サブスクリプション)の両方に対応しています。 -OpenAI-compatible ゲートウェイを **Custom プロバイダー** で使う場合、**設定 → AI Providers → Provider 編集** でカスタム `User-Agent` を設定でき、互換性が必要なエンドポイントで有効です。 -互換ゲートウェイで `/models` が認証以外の理由で使えない場合、ClawX は API キー検証時に軽量な `/chat/completions` または `/responses` プローブへ自動フォールバックします。 - -### 🌙 アダプティブテーマ -ライトモード、ダークモード、またはシステム同期テーマ。ClawXはあなたの好みに自動的に適応します。 - -### 🚀 自動起動設定 -**設定 → 通用** から **システム起動時に自動起動** を有効化すると、ログイン後に ClawX が自動的に起動します。 - ---- - -## はじめに - -### システム要件 - -- **オペレーティングシステム**: macOS 11以上、Windows 10以上、またはLinux(Ubuntu 20.04以上) -- **メモリ**: 最低4GB RAM(8GB推奨) -- **ストレージ**: 1GBの空きディスク容量 - -### インストール - -#### ビルド済みリリース(推奨) - -[Releases](https://github.com/ValueCell-ai/ClawX/releases)ページから、お使いのプラットフォーム向けの最新リリースをダウンロードしてください。 - -#### ソースからビルド - -```bash -# リポジトリをクローン -git clone https://github.com/ValueCell-ai/ClawX.git -cd ClawX - -# プロジェクトの初期化 -pnpm run init - -# 開発モードで起動 -pnpm dev -``` -### 初回起動 - -ClawXを初めて起動すると、**セットアップウィザード**が以下の手順をガイドします: - -1. **言語と地域** – 使用する言語・地域の設定 -2. **AIプロバイダー** – APIキーまたは OAuth(ブラウザ/デバイスログイン対応プロバイダー)で追加 -3. **スキルバンドル** – 一般的なユースケース向けの事前設定スキルを選択 -4. **検証** – メインインターフェースに入る前に設定をテスト - -サポート対象のシステム言語がある場合、ウィザードはその言語を初期選択し、未対応の場合は英語にフォールバックします。 - -### プロキシ設定 - -ClawXには、Electron、OpenClaw Gateway、またはTelegramなどのチャネルがローカルプロキシクライアントを介してインターネットにアクセスする必要がある環境向けに、組み込みのプロキシ設定が含まれています。 - -**設定 → ゲートウェイ → プロキシ**を開いて以下を設定します: - -- **プロキシサーバー**: すべてのリクエストのデフォルトプロキシ -- **バイパスルール**: 直接接続すべきホスト(セミコロン、カンマ、または改行で区切る) -- **開発者モード**では、オプションで以下をオーバーライドできます: - - **HTTP プロキシ** - - **HTTPS プロキシ** - - **ALL_PROXY / SOCKS** - -推奨されるローカル設定例: - -```text -プロキシサーバー: http://127.0.0.1:7890 -``` -注意事項: - -- `host:port`のみの値はHTTPとして扱われます。 -- 高度なプロキシフィールドが空の場合、ClawXは`プロキシサーバー`にフォールバックします。 -- プロキシ設定を保存すると、Electronのネットワーク設定が即座に再適用され、ゲートウェイが自動的に再起動されます。 -- ClawXはTelegramが有効な場合、プロキシをOpenClawのTelegramチャネル設定にも同期します。 -- ClawXのプロキシが無効な状態では、Gatewayの通常再起動時に既存のTelegramチャネルプロキシ設定を保持します。 -- OpenClaw設定のTelegramプロキシを明示的に消したい場合は、プロキシ無効の状態で一度「保存」を実行してください。 -- **設定 → 詳細 → 開発者** では **OpenClaw Doctor** を実行でき、`openclaw doctor --json` の診断出力をアプリ内で確認できます。 -- Windows のパッケージ版では、同梱された `openclaw` CLI/TUI は端末入力を安定させるため、同梱の `node.exe` エントリーポイント経由で実行されます。 - ---- - -## アーキテクチャ - -ClawXは、**デュアルプロセス + Host API 統一アクセス**構成を採用しています。Renderer は単一クライアント抽象を呼び出し、プロトコル選択とライフサイクルは Main が管理します: - -```┌─────────────────────────────────────────────────────────────────┐ -│ ClawX デスクトップアプリ │ -│ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ Electron メインプロセス │ │ -│ │ • ウィンドウ&アプリケーションライフサイクル管理 │ │ -│ │ • ゲートウェイプロセスの監視 │ │ -│ │ • システム統合(トレイ、通知、キーチェーン) │ │ -│ │ • 自動アップデートオーケストレーション │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ │ -│ │ IPC(権威ある制御プレーン) │ -│ ▼ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ React レンダラープロセス │ │ -│ │ • モダンなコンポーネントベースUI(React 19) │ │ -│ │ • Zustandによるステート管理 │ │ -│ │ • 統一 host-api/api-client 呼び出し │ │ -│ │ • リッチなMarkdownレンダリング │ │ -│ └────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - │ Main管理のトランスポート戦略 - │(WS優先、HTTP次点、IPCフォールバック) - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ Host API と Main プロキシ層 │ -│ │ -│ • hostapi:fetch(Mainプロキシ、CORS回避) │ -│ • gateway:httpProxy(RendererはGateway HTTPに直アクセスしない) │ -│ • 統一エラーマッピングとリトライ/バックオフ │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - │ WS / HTTP / IPC フォールバック - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ OpenClaw ゲートウェイ │ -│ │ -│ • AIエージェントランタイムとオーケストレーション │ -│ • メッセージチャネル管理 │ -│ • スキル/プラグイン実行環境 │ -│ • プロバイダー抽象化レイヤー │ -└─────────────────────────────────────────────────────────────────┘ -``` -### 設計原則 - -- **プロセス分離**: AIランタイムは別プロセスで動作し、重い計算処理中でもUIの応答性を確保します -- **フロントエンド呼び出しの単一入口**: Renderer は host-api/api-client を通じて呼び出し、下位プロトコルに依存しません -- **Mainによるトランスポート制御**: WS/HTTP の選択と IPC フォールバックを Main で一元管理します -- **グレースフルリカバリ**: 再接続・タイムアウト・バックオフで一時的障害を自動処理します -- **セキュアストレージ**: APIキーや機密データは、OSのネイティブセキュアストレージ機構を活用します -- **CORSセーフ設計**: ローカルHTTPはMainプロキシ経由とし、Renderer側CORS問題を回避します - -### プロセスモデルと Gateway トラブルシューティング - -- ClawX は Electron アプリのため、**1つのアプリインスタンスでも複数プロセス(main/renderer/zygote/utility)が表示される**のが正常です。 -- 単一起動保護は Electron のロックに加え、ローカルのプロセスロックファイルも併用し、デスクトップ IPC / セッションバスが不安定な環境でも重複起動を防ぎます。 -- ローリングアップグレード中に旧版/新版が混在すると、単一起動保護の挙動が非対称になる場合があります。安定運用のため、デスクトップクライアントは可能な限り同一バージョンへ揃えてください。 -- ただし OpenClaw Gateway の待受は常に**単一**であるべきです。`127.0.0.1:18789` を Listen しているプロセスは1つだけです。 -- Listen プロセスの確認例: - - macOS/Linux: `lsof -nP -iTCP:18789 -sTCP:LISTEN` - - Windows (PowerShell): `Get-NetTCPConnection -LocalPort 18789 -State Listen` -- ウィンドウの閉じるボタン(`X`)は既定でトレイへ最小化する動作で、完全終了ではありません。完全終了する場合はトレイメニューの **Quit ClawX** を使用してください。 - ---- - -## ユースケース - -### 🤖 パーソナルAIアシスタント -質問への回答、メールの下書き、ドキュメントの要約、日常タスクのサポートなど、汎用的なAIエージェントを設定できます。すべてクリーンなデスクトップインターフェースから操作できます。 - -### 📊 自動モニタリング -ニュースフィード、価格追跡、特定イベントの監視などを行うスケジュールエージェントを設定できます。結果はお好みの通知チャネルに配信されます。 - -### 💻 開発者の生産性向上 -AI を開発ワークフローに統合できます。エージェントを使用して、コードレビュー、ドキュメント生成、反復的なコーディングタスクの自動化が可能です。 - -### 🔄 ワークフロー自動化 -複数のスキルを連鎖させて、高度な自動化パイプラインを作成できます。データの処理、コンテンツの変換、アクションのトリガーを、すべてビジュアルにオーケストレーションできます。 - ---- - -## 開発 - -### 前提条件 - -- **Node.js**: 22以上(LTS推奨) -- **パッケージマネージャー**: pnpm 9以上(推奨)またはnpm - -### プロジェクト構成 - -```ClawX/ -├── electron/ # Electron メインプロセス -│ ├── api/ # メイン側 API ルーターとハンドラー -│ │ └── routes/ # RPC/HTTP プロキシのルートモジュール -│ ├── services/ # Provider/Secrets/ランタイムサービス -│ │ ├── providers/ # provider/account モデル同期ロジック -│ │ └── secrets/ # OS キーチェーンと秘密情報管理 -│ ├── shared/ # 共通 Provider スキーマ/定数 -│ │ └── providers/ -│ ├── main/ # アプリ入口、ウィンドウ、IPC 登録 -│ ├── gateway/ # OpenClaw ゲートウェイプロセスマネージャー -│ ├── preload/ # セキュア IPC ブリッジ -│ └── utils/ # ユーティリティ(ストレージ、認証、パス) -├── src/ # React レンダラープロセス -│ ├── lib/ # フロントエンド統一 API とエラーモデル -│ ├── stores/ # Zustand ストア(settings/chat/gateway) -│ ├── components/ # 再利用可能な UI コンポーネント -│ ├── pages/ # Setup/Dashboard/Chat/Channels/Skills/Cron/Settings -│ ├── i18n/ # ローカライズリソース -│ └── types/ # TypeScript 型定義 -├── tests/ -│ ├── e2e/ # Playwright による Electron E2E スモークテスト -│ └── unit/ # Vitest ユニット/統合寄りテスト -├── resources/ # 静的アセット(アイコン、画像) -└── scripts/ # ビルド/ユーティリティスクリプト -``` -### 利用可能なコマンド - -```bash -# 開発 -pnpm run init # 依存関係のインストール + uvのダウンロード -pnpm dev # ホットリロードで起動(不足時は同梱スキルを自動準備) - -# コード品質 -pnpm lint # ESLintを実行 -pnpm typecheck # TypeScriptの型チェック - -# テスト -pnpm test # ユニットテストを実行 -pnpm run test:e2e # Electron E2E スモークテストを実行 -pnpm run test:e2e:headed # 表示付きウィンドウで Electron E2E を実行 -pnpm run comms:replay # 通信リプレイ指標を算出 -pnpm run comms:baseline # 通信ベースラインを更新 -pnpm run comms:compare # リプレイ指標をベースライン閾値と比較 - -# ビルド&パッケージ -pnpm run build:vite # フロントエンドのみビルド -pnpm build # フルプロダクションビルド(パッケージアセット含む) -pnpm package # 現在のプラットフォーム向けにパッケージ化(同梱プリインストールスキルを含む) -pnpm package:mac # macOS向けにパッケージ化 -pnpm package:win # Windows向けにパッケージ化 -pnpm package:linux # Linux向けにパッケージ化 -``` - -ヘッドレス Linux では Electron テストに表示サーバーが必要です。`xvfb-run -a pnpm run test:e2e` を利用してください。 - -### 通信回帰チェック - -PR が通信経路(Gateway イベント、Chat 送受信フロー、Channel 配信、トランスポートのフォールバック)に触れる場合は、次を実行してください。 - -```bash -pnpm run comms:replay -pnpm run comms:compare -``` - -CI の `comms-regression` が必須シナリオと閾値を検証します。 -### 技術スタック - -| レイヤー | 技術 | -|---------|------| -| ランタイム | Electron 40以上 | -| UIフレームワーク | React 19 + TypeScript | -| スタイリング | Tailwind CSS + shadcn/ui | -| ステート管理 | Zustand | -| ビルド | Vite + electron-builder | -| テスト | Vitest + Playwright | -| アニメーション | Framer Motion | -| アイコン | Lucide React | - ---- - -## コントリビューション - -コミュニティからのコントリビューションを歓迎します!バグ修正、新機能、ドキュメントの改善、翻訳など、あらゆる貢献がClawXをより良くするのに役立ちます。 - -### コントリビューション方法 - -1. リポジトリを**フォーク**する -2. フィーチャーブランチを**作成**する(`git checkout -b feature/amazing-feature`) -3. 明確なメッセージで変更を**コミット**する -4. ブランチに**プッシュ**する -5. **プルリクエスト**を作成する - -### ガイドライン - -- 既存のコードスタイルに従う(ESLint + Prettier) -- 新機能にはテストを書く -- 必要に応じてドキュメントを更新する -- コミットはアトミックかつ説明的に保つ - ---- - -## 謝辞 - -ClawXは優れたオープンソースプロジェクトの上に構築されています: - -- [OpenClaw](https://github.com/OpenClaw) – AIエージェントランタイム -- [Electron](https://www.electronjs.org/) – クロスプラットフォームデスクトップフレームワーク -- [React](https://react.dev/) – UIコンポーネントライブラリ -- [shadcn/ui](https://ui.shadcn.com/) – 美しくデザインされたコンポーネント -- [Zustand](https://github.com/pmndrs/zustand) – 軽量ステート管理 - ---- - -## コミュニティ - -コミュニティに参加して、他のユーザーとつながり、サポートを受け、体験を共有しましょう。 - -| 企業微信 | Feishuグループ | Discord | -| :---: | :---: | :---: | -| WeChat QRコード | Feishu QRコード | Discord QRコード | - -### ClawX パートナープログラム 🚀 - -ClawX パートナープログラムを開始します。特に、カスタム AI エージェントや自動化ニーズを持つより多くの顧客に ClawX を紹介してくださるパートナーを募集しています。 - -パートナーの皆さまには、見込みユーザーや案件との接点づくりを担っていただき、ClawX チームは技術サポート、カスタマイズ、統合を全面的に提供します。 - -AI ツールや自動化に関心のある顧客とお仕事をされている方は、ぜひご一緒できればうれしいです。 - -詳細は DM いただくか、[public@valuecell.ai](mailto:public@valuecell.ai) までメールでご連絡ください。 - ---- - -## スター履歴 - -

- スター履歴チャート -

- ---- - -## ライセンス - -ClawXは[MITライセンス](LICENSE)の下でリリースされています。本ソフトウェアの使用、変更、配布は自由に行えます。 - ---- - -

- ValueCell Teamが❤️を込めて開発 -

+Please use the root [README.md](README.md) as the source of truth for the current product scope, development workflow, packaging flow, and pilot validation notes. diff --git a/README.ru-RU.md b/README.ru-RU.md index bdcaf6c..76d7a2f 100644 --- a/README.ru-RU.md +++ b/README.ru-RU.md @@ -1,476 +1,5 @@ +# 智念助手 -

-ClawX Logo -

+This repository has been customized from the ClawX base project into **智念助手**. -

ClawX

- -

-Десктоп-интерфейс для AI-агентов OpenClaw -

- -

-Возможности • -Почему ClawX • -Быстрый старт • -Архитектура • -Разработка • -Участие -

- -

-Platform -Electron -React - -chat on Discord - -Downloads -License -

- -

-English | 简体中文 | 日本語 | Русский -

- ---- - -## Обзор - -**ClawX** — это мост между мощными AI-агентами и повседневными пользователями. Построенный на базе [OpenClaw](https://github.com/OpenClaw), он превращает управление AI через командную строку в доступный и красивый десктоп-опыт — терминал не нужен. - -Автоматизация рабочих процессов, управление AI-каналами или планирование интеллектуальных задач — ClawX предоставляет интерфейс для эффективного использования AI-агентов. - -ClawX поставляется с предустановленными лучшими практиками для провайдеров моделей и нативно поддерживает Windows, а также многоязычные настройки. Вы можете тонко настроить расширенные параметры через **Настройки → Дополнительно → Режим разработчика**. - ---- - -## Скриншоты - -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- ---- - -## Почему ClawX - -Создание AI-агентов не должно требовать владения командной строкой. Философия ClawX проста: **мощные технологии заслуживают интерфейса, который уважает ваше время.** - -| Проблема | Решение ClawX | -|----------|---------------| -| Сложная настройка через CLI | Установка в один клик с мастером настройки | -| Редактирование конфигурационных файлов | Визуальные настройки с проверкой в реальном времени | -| Управление процессами | Автоматическое управление жизненным циклом шлюза | -| Несколько AI-провайдеров | Единая панель настройки провайдеров | -| Установка навыков/плагинов | Встроенный маркетплейс и управление навыками | - -### OpenClaw внутри - -ClawX построен непосредственно на официальном ядре **OpenClaw**. Вместо отдельной установки мы встраиваем среду выполнения в приложение для бесшовного опыта "всё включено". - -Мы стремимся поддерживать строгое соответствие с проектом OpenClaw, чтобы вы всегда имели доступ к новейшим возможностям, улучшениям стабильности и совместимости с экосистемой. - ---- - -## Возможности - -### 🎯 Нулевой порог настройки -Весь процесс — от установки до первого взаимодействия с AI — выполняется через интуитивный графический интерфейс. Без терминальных команд, без YAML-файлов, без поиска переменных окружения. - -### 💬 Интеллектуальный интерфейс чата -Общайтесь с AI-агентами через современный чат. Поддержка нескольких контекстов разговора, истории сообщений, рендеринга Markdown (включая таблицы GitHub-flavored и математические формулы LaTeX через KaTeX: `$строчные$`, `$$блочные$$`, `\(строчные\)` и `\[блочные\]`) и прямая маршрутизация через `@agent` в главном поле ввода для мультиагентных конфигураций. -При выборе другого агента через `@agent` ClawX переключается непосредственно в контекст этого агента вместо ретрансляции через агента по умолчанию. Рабочие пространства агентов по умолчанию разделены, но более строгая изоляция зависит от настроек песочницы OpenClaw. -Каждый агент может переопределить свои настройки `provider/model`; агенты без переопределения продолжают наследовать глобальную модель по умолчанию. - -### 📡 Управление несколькими каналами -Настраивайте и отслеживайте несколько AI-каналов одновременно. Каждый канал работает независимо, позволяя запускать специализированных агентов для разных задач. -Каждый канал теперь поддерживает несколько учётных записей, привязку агента к учётной записи и переключение канала по умолчанию прямо на странице Каналы. -Для пользовательских идентификаторов учётных записей каналов ClawX требует совместимый с OpenClaw канонический формат (`[a-z0-9_-]`, строчные буквы, максимум 64 символа, должен начинаться с буквы или цифры) для предотвращения ошибок маршрутизации. -ClawX также включает официальный плагин личного WeChat от Tencent, позволяя подключить WeChat напрямую со страницы Каналы через встроенный QR-код. - -### ⏰ Автоматизация по расписанию -Планируйте автоматический запуск AI-задач. Определяйте триггеры, устанавливайте интервалы и позволяйте AI-агентам работать круглосуточно без ручного вмешательства. -На странице Cron теперь можно настроить внешнюю доставку непосредственно в форме задачи с отдельными селекторами учётной записи отправителя и цели получателя. Для поддерживаемых каналов цели получателей автоматически обнаруживаются из каталогов каналов или известной истории сессий, поэтому больше не нужно редактировать `jobs.json` вручную. - -### 🧩 Расширяемая система навыков -Расширяйте возможности AI-агентов готовыми навыками. Просматривайте, устанавливайте и управляйте навыками через встроенную панель — менеджеры пакетов не нужны. -ClawX также предварительно упаковывает полные навыки обработки документов (`pdf`, `xlsx`, `docx`, `pptx`), автоматически развёртывает их в управляемый каталог навыков (по умолчанию `~/.openclaw/skills`) при запуске и включает по умолчанию при первой установке. Дополнительные упакованные навыки (`find-skills`, `self-improving-agent`, `tavily-search`) также включены по умолчанию; если необходимые API-ключи отсутствуют, OpenClaw покажет ошибки конфигурации во время выполнения. -На странице Навыки отображаются навыки из нескольких источников OpenClaw (управляемый каталог, workspace и дополнительные каталоги навыков), а также показывается фактическое расположение каждого навыка для прямого открытия папки. - -Переменные окружения для встроенных поисковых навыков: -- `TAVILY_API_KEY` для `tavily-search` (OAuth также может поддерживаться вышестоящей средой выполнения) -- `find-skills` и `self-improving-agent` не требуют API-ключей - -### 🔐 Безопасная интеграция провайдеров -Подключайтесь к нескольким AI-провайдерам (OpenAI, Anthropic и др.) с учётными данными, безопасно хранящимися в системной связке ключей. OpenAI поддерживает как API-ключи, так и OAuth через браузер (подписка Codex). -Для провайдеров **Custom**, используемых с OpenAI-совместимыми шлюзами, вы можете установить пользовательский `User-Agent` в **Настройки → AI Провайдеры → Редактировать провайдера** для совместимости с чувствительными эндпоинтами. -Когда совместимый шлюз отклоняет `/models` по причинам, не связанным с аутентификацией, ClawX автоматически переключается на легковесный зонд `/chat/completions` или `/responses` при проверке API-ключа. - -### 🌙 Адаптивные темы -Светлая тема, тёмная тема или синхронизация с системой. ClawX автоматически адаптируется к вашим предпочтениям. - -### 🚀 Управление автозапуском -В **Настройки → Общие** вы можете включить **Запускать при старте системы**, чтобы ClawX автоматически запускался после входа в систему. - ---- - -## Быстрый старт - -### Системные требования - -- **Операционная система**: macOS 11+, Windows 10+ или Linux (Ubuntu 20.04+) -- **Память**: минимум 4 ГБ RAM (рекомендуется 8 ГБ) -- **Хранилище**: 1 ГБ свободного места на диске - -### Установка - -#### Готовые релизы (рекомендуется) - -Скачайте последний релиз для вашей платформы со страницы [Releases](https://github.com/ValueCell-ai/ClawX/releases). - -#### Сборка из исходников - -```bash -# Клонирование репозитория -git clone https://github.com/ValueCell-ai/ClawX.git -cd ClawX - -# Инициализация проекта -pnpm run init - -# Запуск в режиме разработки -pnpm dev -``` - -### Первый запуск - -При первом запуске ClawX **Мастер настройки** проведёт вас через: - -1. **Язык и регион** — настройка предпочтительного языка и региона -2. **AI-провайдер** — добавление провайдеров с API-ключами или OAuth (для провайдеров, поддерживающих вход через браузер/устройство) -3. **Пакеты навыков** — выбор предустановленных навыков для распространённых сценариев -4. **Проверка** — тестирование конфигурации перед входом в основной интерфейс - -Мастер предварительно выбирает системный язык, если он поддерживается, иначе переключается на английский. - -### Настройки прокси - -ClawX включает встроенные настройки прокси для сред, где Electron, шлюз OpenClaw или каналы вроде Telegram должны выходить в интернет через локальный прокси-клиент. - -Откройте **Настройки → Шлюз → Прокси** и настройте: - -- **Прокси-сервер**: прокси по умолчанию для всех запросов -- **Правила обхода**: хосты, которые должны подключаться напрямую, разделённые точкой с запятой, запятыми или новыми строками -- В **Режиме разработчика** можно дополнительно переопределить: - - **HTTP Прокси** - - **HTTPS Прокси** - - **ALL_PROXY / SOCKS** - -Рекомендуемые примеры локальных настроек: - -```text -Прокси-сервер: http://127.0.0.1:7890 -``` -Примечания: - -- Значение `host:port` рассматривается как HTTP. -- Если расширенные поля прокси пусты, ClawX использует `Прокси-сервер`. -- Сохранение настроек прокси немедленно повторно применяет сеть Electron и автоматически перезапускает шлюз. -- ClawX также синхронизирует прокси с конфигурацией канала Telegram в OpenClaw, когда Telegram включён. -- При перезапуске шлюза существующий прокси канала Telegram сохраняется, если прокси ClawX отключен. -- Чтобы явно очистить прокси Telegram из конфигурации OpenClaw, сохраните настройки прокси с отключенным прокси. -- В **Настройки → Дополнительно → Разработчик** можно запустить **OpenClaw Doctor** для выполнения `openclaw doctor --json` и просмотра диагностического вывода, не покидая приложение. -- В упакованных сборках Windows встроенный `openclaw` CLI/TUI запускается через поставляемый `node.exe` для стабильного поведения ввода в терминале. - ---- - -## Архитектура - -ClawX использует **двухпроцессную архитектуру с унифицированным уровнем Host API**. Рендерер обращается к единой абстракции клиента, а Electron Main управляет выбором протокола и жизненным циклом процессов: - -``` -┌─────────────────────────────────────────────────────────────────┐ -│ Десктоп-приложение ClawX │ -│ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ Главный процесс Electron │ │ -│ │ • Управление жизненным циклом окна и приложения │ │ -│ │ • Наблюдение за процессом шлюза │ │ -│ │ • Интеграция с системой (трей, уведомления, связка ключей)│ │ -│ │ • Оркестрация автообновлений │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ │ -│ IPC (авторитетная плоскость управления) │ -│ ▼ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ Процесс рендерера React │ │ -│ │ • Современный UI на компонентах (React 19) │ │ -│ │ • Управление состоянием с Zustand │ │ -│ │ • Унифицированные вызовы host-api/api-client │ │ -│ │ • Рендеринг Markdown │ │ -│ └────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - Стратегия транспорта, управляемая Main - (Сначала WS, затем HTTP, затем IPC) - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ Host API и прокси-уровень Main │ -│ │ -│ • hostapi:fetch (прокси Main, избегает CORS в dev/prod) │ -│ • gateway:httpProxy (Рендерер не вызывает Gateway HTTP напрямую)│ -│ • Унифицированное отображение ошибок и повторные попытки │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - Резерв WS / HTTP / IPC - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ Шлюз OpenClaw │ -│ │ -│ • Среда выполнения AI-агентов и оркестрация │ -│ • Управление каналами сообщений │ -│ • Среда выполнения навыков/плагинов │ -│ • Уровень абстракции провайдеров │ -└─────────────────────────────────────────────────────────────────┘ -``` - -### Принципы проектирования - -- **Изоляция процессов**: Среда выполнения AI работает в отдельном процессе, обеспечивая отзывчивость UI даже при тяжёлых вычислениях -- **Единая точка входа для фронтенда**: Запросы рендерера проходят через host-api/api-client; детали протокола скрыты за стабильным интерфейсом -- **Владение транспортом в Main**: Electron Main управляет использованием WS/HTTP и откатом к IPC для надёжности -- **Корректное восстановление**: Встроенная логика переподключения, таймаутов и отката автоматически обрабатывает временные сбои -- **Безопасное хранение**: API-ключи и конфиденциальные данные используют нативные механизмы безопасного хранения ОС -- **Безопасность CORS**: Локальный HTTP-доступ проксируется через Main, предотвращая CORS-проблемы на стороне рендерера - -### Модель процессов и устранение неполадок шлюза - -- ClawX — это приложение Electron, поэтому **один экземпляр приложения обычно отображается как несколько процессов ОС** (main/renderer/zygote/utility). Это нормально. -- Защита единственного экземпляра использует блокировку Electron плюс локальный файл блокировки процессов, предотвращая дублирование запуска приложения в средах с нестабильным IPC/сессионной шиной. -- При последовательных обновлениях смешанные старые/новые версии могут иметь асимметричное поведение защиты. Для лучшей надёжности обновите все десктоп-клиенты до одной версии. -- Слушатель шлюза OpenClaw должен быть **единственным владельцем**: только один процесс должен слушать `127.0.0.1:18789`. -- Для проверки активного слушателя: - - macOS/Linux: `lsof -nP -iTCP:18789 -sTCP:LISTEN` - - Windows (PowerShell): `Get-NetTCPConnection -LocalPort 18789 -State Listen` -- Нажатие кнопки закрытия окна (`X`) скрывает ClawX в трей; это **не** полностью закрывает приложение. Используйте меню трея **Quit ClawX** для полного завершения. - ---- - -## Варианты использования - -### 🤖 Персональный AI-ассистент -Настройте универсального AI-агента, который может отвечать на вопросы, составлять письма, резюмировать документы и помогать с повседневными задачами — всё через чистый десктоп-интерфейс. - -### 📊 Автоматизированный мониторинг -Настройте запланированных агентов для отслеживания новостных лент, цен или определённых событий. Результаты доставляются в ваш предпочтительный канал уведомлений. - -### 💻 Производительность разработчика -Интегрируйте AI в рабочий процесс разработки. Используйте агентов для проверки кода, генерации документации или автоматизации повторяющихся задач кодирования. - -### 🔄 Автоматизация рабочих процессов -Связывайте несколько навыков для создания сложных конвейеров автоматизации. Обрабатывайте данные, преобразовывайте контент и запускайте действия — всё визуально оркестрируется. - ---- - -## Разработка - -### Требования - -- **Node.js**: 22+ (рекомендуется LTS) -- **Менеджер пакетов**: pnpm 9+ (рекомендуется) или npm - -### Структура проекта - -``` -ClawX/ -├── electron/ # Главный процесс Electron -│ ├── api/ # Маршрутизатор API и обработчики Main -│ │ └── routes/ # Модули маршрутов RPC/HTTP прокси -│ ├── services/ # Службы провайдеров, секретов и среды выполнения -│ │ ├── providers/ # Логика синхронизации моделей provider/account -│ │ └── secrets/ # Связка ключей ОС и хранилище секретов -│ ├── shared/ # Общие схемы провайдеров и константы -│ │ └── providers/ -│ ├── main/ # Точка входа приложения, окна, регистрация IPC -│ ├── gateway/ # Менеджер процесса шлюза OpenClaw -│ ├── preload/ # Безопасный IPC-мост -│ └── utils/ # Утилиты (хранилище, аутентификация, пути) -├── src/ # Процесс рендерера React -│ ├── lib/ # Унифицированный фронтенд API и модель ошибок -│ ├── stores/ # Хранилища Zustand (settings/chat/gateway) -│ ├── components/ # Переиспользуемые UI-компоненты -│ ├── pages/ # Setup/Dashboard/Chat/Channels/Skills/Cron/Settings -│ ├── i18n/ # Ресурсы локализации -│ └── types/ # Определения типов TypeScript -├── tests/ -│ ├── e2e/ # Сквозные дымовые тесты Playwright Electron -│ └── unit/ # Модульные/интеграционные тесты Vitest -├── resources/ # Статические ресуры (иконки, изображения) -└── scripts/ # Скрипты сборки и утилит -``` - -### Доступные команды - -```bash -# Разработка -pnpm run init # Установить зависимости + скачать uv -pnpm dev # Запуск с горячей перезагрузкой (автоподготовка упакованных навыков при отсутствии) - -# Качество кода -pnpm lint # Запустить ESLint -pnpm typecheck # Проверка типов TypeScript - -# Тестирование -pnpm test # Запустить модульные тесты -pnpm run test:e2e # Запустить E2E дымовые тесты Electron с Playwright -pnpm run test:e2e:headed # Запустить E2E тесты Electron с видимым окном -pnpm run comms:replay # Вычислить метрики повторного воспроизведения коммуникаций -pnpm run comms:baseline # Обновить базовый снимок коммуникаций -pnpm run comms:compare # Сравнить метрики воспроизведения с базовыми порогами - -# Сборка и упаковка -pnpm run build:vite # Собрать только фронтенд -pnpm build # Полная production-сборка (с ресурсами упаковки) -pnpm package # Упаковать для текущей платформы (включает предустановленные навыки) -pnpm package:mac # Упаковать для macOS -pnpm package:win # Упаковать для Windows -pnpm package:linux # Упаковать для Linux -``` - -На headless Linux запускайте тесты Electron под сервером отображения, например `xvfb-run -a pnpm run test:e2e`. - -### Проверка регрессии коммуникаций - -Когда PR изменяет пути коммуникации (события шлюза, поток отправки/получения чата, доставка каналов или откат транспорта), запустите: - -```bash -pnpm run comms:replay -pnpm run comms:compare -``` - -`comms-regression` в CI проверяет обязательные сценарии и пороги. - -### E2E-тесты Electron - -Сьют Playwright Electron запускает упакованный рендерер и главный процесс из `dist/` и `dist-electron/`, поэтому не требует предварительного ручного запуска `pnpm dev`. - -`pnpm run test:e2e` автоматически: - -- собирает рендерер и пакеты Electron с `pnpm run build:vite` -- запускает Electron в изолированном режиме E2E с временным `HOME` -- использует временный каталог `userData` ClawX -- пропускает тяжёлые побочные эффекты запуска, такие как автозапуск шлюза, установку упакованных навыков, создание трея и автоустановку CLI - -Первые два базовых спецификации покрывают: - -- видимость мастера настройки при первом запуске на чистом профиле -- пропуск настройки и навигация на страницу Models внутри приложения Electron - -Добавляйте будущие потоки Electron в `tests/e2e/` и переиспользуйте общий fixture в `tests/e2e/fixtures/electron.ts`. - -### Технологический стек - -| Уровень | Технология | -|----------------|-------------------------------| -| Среда выполнения | Electron 40+ | -| UI-фреймворк | React 19 + TypeScript | -| Стилизация | Tailwind CSS + shadcn/ui | -| Состояние | Zustand | -| Сборка | Vite + electron-builder | -| Тестирование | Vitest + Playwright | -| Анимация | Framer Motion | -| Иконки | Lucide React | - ---- - -## Участие - -Мы приветствуем вклад сообщества! Исправления багов, новые функции, улучшения документации или переводы — каждый вклад делает ClawX лучше. - -### Как внести вклад - -1. **Сделайте форк** репозитория -2. **Создайте** ветку функции (`git checkout -b feature/amazing-feature`) -3. **Зафиксируйте** изменения с понятными сообщениями -4. **Отправьте** в свою ветку -5. **Откройте** Pull Request - -### Руководящие принципы - -- Следуйте существующему стилю кода (ESLint + Prettier) -- Пишите тесты для нового функционала -- Обновляйте документацию по мере необходимости -- Держите коммиты атомарными и описательными - ---- - -## Благодарности - -ClawX построен на плечах отличных проектов с открытым исходным кодом: - -- [OpenClaw](https://github.com/OpenClaw) – Среда выполнения AI-агентов -- [Electron](https://www.electronjs.org/) – Кроссплатформенный десктоп-фреймворк -- [React](https://react.dev/) – Библиотека UI-компонентов -- [shadcn/ui](https://ui.shadcn.com/) – Красиво спроектированные компоненты -- [Zustand](https://github.com/pmndrs/zustand) – Легковесное управление состоянием - ---- - -## Сообщество - -Присоединяйтесь к нашему сообществу, чтобы общаться с другими пользователями, получать поддержку и делиться опытом. - -| WeChat Enterprise | Feishu Group | Discord | -| :---: | :---: | :---: | -| WeChat QR Code | Feishu QR Code | Discord QR Code | - -### Партнёрская программа ClawX 🚀 - -Мы запускаем Партнёрскую программу ClawX и ищем партнёров, которые могут помочь представить ClawX большему числу клиентов, особенно тем, у кого есть потребности в кастомных AI-агентах или автоматизации. - -Партнёры помогают связывать нас с потенциальными пользователями и проектами, а команда ClawX предоставляет полную техническую поддержку, кастомизацию и интеграцию. - -Если вы работаете с клиентами, заинтересованными в AI-инструментах или автоматизации, мы будем рады сотрудничеству. - -Напишите нам в DM или на [public@valuecell.ai](mailto:public@valuecell.ai) для получения дополнительной информации. - ---- - -## История звёзд - -

-Star History Chart -

- ---- - -## Лицензия - -ClawX выпускается под [лицензией MIT](LICENSE). Вы можете свободно использовать, модифицировать и распространять это программное обеспечение. - ---- - -

-Создано с ❤️ командой ValueCell -

+Please use the root [README.md](README.md) as the source of truth for the current product scope, development workflow, packaging flow, and pilot validation notes. diff --git a/README.zh-CN.md b/README.zh-CN.md index f35df2f..7dd3102 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -1,455 +1,5 @@ +# 智念助手 -

- ClawX Logo -

+本项目已经从 ClawX 基础工程定制为 **智念助手**。 -

ClawX

- -

- OpenClaw AI 智能体的桌面客户端 -

- -

- 功能特性 • - 为什么选择 ClawX • - 快速上手 • - 系统架构 • - 开发指南 • - 参与贡献 -

- -

- Platform - Electron - React - - chat on Discord - - Downloads - License -

- -

- English | 简体中文 | 日本語 | Русский -

- ---- - -## 概述 - -**ClawX** 是连接强大 AI 智能体与普通用户之间的桥梁。基于 [OpenClaw](https://github.com/OpenClaw) 构建,它将命令行式的 AI 编排转变为易用、美观的桌面体验——无需使用终端。 - -无论是自动化工作流、连接通讯软件,还是调度智能定时任务,ClawX 都能提供高效易用的图形界面,帮助你充分发挥 AI 智能体的能力。 - -ClawX 预置了最佳实践的模型供应商配置,原生支持 Windows 平台以及多语言设置。当然,你也可以通过 **设置 → 高级 → 开发者模式** 来进行精细的高级配置。 - ---- - -## 截图预览 - -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- -

- ---- - -## 为什么选择 ClawX - -构建 AI 智能体不应该需要精通命令行。ClawX 的设计理念很简单:**强大的技术值得拥有一个尊重用户时间的界面。** - -| 痛点 | ClawX 解决方案 | -|------|----------------| -| 复杂的命令行配置 | 一键安装,配合引导式设置向导 | -| 手动编辑配置文件 | 可视化设置界面,实时校验 | -| 进程管理繁琐 | 自动管理网关生命周期 | -| 多 AI 供应商切换 | 统一的供应商配置面板 | -| 技能/插件安装复杂 | 内置技能市场与管理界面 | - -### 内置 OpenClaw 核心 - -ClawX 直接基于官方 **OpenClaw** 核心构建。无需单独安装,我们将运行时嵌入应用内部,提供开箱即用的无缝体验。 - -我们致力于与上游 OpenClaw 项目保持严格同步,确保你始终可以使用官方发布的最新功能、稳定性改进和生态兼容性。 - ---- - -## 功能特性 - -### 🎯 零配置门槛 -从安装到第一次 AI 对话,全程通过直观的图形界面完成。无需终端命令,无需 YAML 文件,无需到处寻找环境变量。 - -### 💬 智能聊天界面 -通过现代化的聊天体验与 AI 智能体交互。支持多会话上下文、消息历史记录、Markdown 富文本渲染(包括 GitHub 风格表格以及由 KaTeX 渲染的 LaTeX 数学公式:`$行内$`、`$$块级$$`、`\(行内\)` 和 `\[块级\]`),以及在多 Agent 场景下通过主输入框中的 `@agent` 直接路由到目标智能体。 -当你使用 `@agent` 选择其他智能体时,ClawX 会直接切换到该智能体自己的对话上下文,而不是经过默认智能体转发。各 Agent 工作区默认彼此分离,但更强的运行时隔离仍取决于 OpenClaw 的 sandbox 配置。 -每个 Agent 还可以单独覆盖自己的 `provider/model` 运行时设置;未覆盖的 Agent 会继续继承全局默认模型。 - -### 📡 多频道管理 -同时配置和监控多个 AI 频道。每个频道独立运行,允许你为不同任务运行专门的智能体。 -现在每个频道支持多个账号,并可在 Channels 页面直接完成账号绑定到 Agent 与默认账号切换。 -对于自定义频道账号 ID,ClawX 现在会强制校验 OpenClaw 兼容的规范格式(`[a-z0-9_-]`、小写、最长 64 位、且必须以字母或数字开头),避免路由匹配异常。 -ClawX 现在还内置了腾讯官方个人微信渠道插件,可直接在 Channels 页面通过内置二维码流程完成微信连接。 - -### ⏰ 定时任务自动化 -调度 AI 任务自动执行。定义触发器、设置时间间隔,让 AI 智能体 7×24 小时不间断工作。 -现在定时任务页面已经可以直接配置外部投递,统一拆成“发送账号”和“接收目标”两个下拉选择。对于已支持的通道,接收目标会从通道目录能力或已知会话历史中自动发现,不需要再手动修改 `jobs.json`。 - - -### 🧩 可扩展技能系统 -通过预构建的技能扩展 AI 智能体的能力。在集成的技能面板中浏览、安装和管理技能——无需包管理器。 -ClawX 还会内置预装完整的文档处理技能(`pdf`、`xlsx`、`docx`、`pptx`),在启动时自动部署到托管技能目录(默认 `~/.openclaw/skills`),并在首次安装时默认启用。额外预装技能(`find-skills`、`self-improving-agent`、`tavily-search`)也会默认启用;若缺少必需的 API Key,OpenClaw 会在运行时给出配置错误提示。 -Skills 页面可展示来自多个 OpenClaw 来源的技能(托管目录、workspace、额外技能目录),并显示每个技能的实际路径,便于直接打开真实安装位置。 - -重点搜索技能所需环境变量: -- `TAVILY_API_KEY`:用于 `tavily-search`(上游运行时也可能支持 OAuth) - -### 🔐 安全的供应商集成 -连接多个 AI 供应商(OpenAI、Anthropic 等),凭证安全存储在系统原生密钥链中。OpenAI 同时支持 API Key 与浏览器 OAuth(Codex 订阅)登录。 -如果你通过 **自定义(Custom)Provider** 对接 OpenAI-compatible 网关,可以在 **设置 → AI Providers → 编辑 Provider** 中配置自定义 `User-Agent`,以提高兼容性。 -如果兼容网关的 `/models` 因非鉴权原因不可用,ClawX 会在校验 API Key 时自动降级为轻量的 `/chat/completions` 或 `/responses` 探测。 - -### 🌙 自适应主题 -支持浅色模式、深色模式或跟随系统主题。ClawX 自动适应你的偏好设置。 - -### 🚀 开机启动控制 -在 **设置 → 通用** 中,你可以开启 **开机自动启动**,让 ClawX 在系统登录后自动启动。 - ---- - -## 快速上手 - -### 系统要求 - -- **操作系统**:macOS 11+、Windows 10+ 或 Linux(Ubuntu 20.04+) -- **内存**:最低 4GB RAM(推荐 8GB) -- **存储空间**:1GB 可用磁盘空间 - -### 安装方式 - -#### 预构建版本(推荐) - -从 [Releases](https://github.com/ValueCell-ai/ClawX/releases) 页面下载适用于你平台的最新版本。 - -#### 从源码构建 - -```bash -# 克隆仓库 -git clone https://github.com/ValueCell-ai/ClawX.git -cd ClawX - -# 初始化项目 -pnpm run init - -# 以开发模式启动 -pnpm dev -``` -### 首次启动 - -首次启动 ClawX 时,**设置向导** 将引导你完成以下步骤: - -1. **语言与区域** – 配置你的首选语言和地区 -2. **AI 供应商** – 通过 API 密钥或 OAuth(支持浏览器/设备登录的供应商)添加账号 -3. **技能包** – 选择适用于常见场景的预配置技能 -4. **验证** – 在进入主界面前测试你的配置 - -如果系统语言在支持列表中,向导会默认选中该语言;否则回退到英文。 - -> Moonshot(Kimi)说明:ClawX 默认保持开启 Kimi 的 web search。 -> 当配置 Moonshot 后,ClawX 也会将 OpenClaw 配置中的 Kimi web search 同步到中国区端点(`https://api.moonshot.cn/v1`)。 - -### 代理设置 - -ClawX 内置了代理设置,适用于需要通过本地代理客户端访问外网的场景,包括 Electron 本身、OpenClaw Gateway,以及 Telegram 这类频道的联网请求。 - -打开 **设置 → 网关 → 代理**,配置以下内容: - -- **代理服务器**:所有请求默认使用的代理 -- **绕过规则**:需要直连的主机,使用分号、逗号或换行分隔 -- 在 **开发者模式** 下,还可以单独覆盖: - - **HTTP 代理** - - **HTTPS 代理** - - **ALL_PROXY / SOCKS** - -本地代理的常见填写示例: - -```text -代理服务器: http://127.0.0.1:7890 -``` -说明: - -- 只填写 `host:port` 时,会按 HTTP 代理处理。 -- 高级代理项留空时,会自动回退到“代理服务器”。 -- 保存代理设置后,Electron 网络层会立即重新应用代理,并自动重启 Gateway。 -- 如果启用了 Telegram,ClawX 还会把代理同步到 OpenClaw 的 Telegram 频道配置中。 -- 当 ClawX 代理处于关闭状态时,Gateway 的常规重启会保留已有的 Telegram 频道代理配置。 -- 如果你要明确清空 OpenClaw 中的 Telegram 代理,请在关闭代理后点一次“保存代理设置”。 -- 在 **设置 → 高级 → 开发者** 中,可以直接运行 **OpenClaw Doctor**,执行 `openclaw doctor --json` 并在应用内查看诊断输出。 -- 在 Windows 打包版本中,内置的 `openclaw` CLI/TUI 会通过随包分发的 `node.exe` 入口运行,以保证终端输入行为稳定。 - ---- - -## 系统架构 - -ClawX 采用 **双进程 + Host API 统一接入架构**。渲染进程只调用统一客户端抽象,协议选择与进程生命周期由 Electron 主进程统一管理: - -```┌─────────────────────────────────────────────────────────────────┐ -│ ClawX 桌面应用 │ -│ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ Electron 主进程 │ │ -│ │ • 窗口与应用生命周期管理 │ │ -│ │ • 网关进程监控 │ │ -│ │ • 系统集成(托盘、通知、密钥链) │ │ -│ │ • 自动更新编排 │ │ -│ └────────────────────────────────────────────────────────────┘ │ -│ │ │ -│ │ IPC(权威控制面) │ -│ ▼ │ -│ ┌────────────────────────────────────────────────────────────┐ │ -│ │ React 渲染进程 │ │ -│ │ • 现代组件化 UI(React 19) │ │ -│ │ • Zustand 状态管理 │ │ -│ │ • 统一 host-api/api-client 调用 │ │ -│ │ • Markdown 富文本渲染 │ │ -│ └────────────────────────────────────────────────────────────┘ │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - │ 主进程统一传输策略 - │(WS 优先,HTTP 次之,IPC 回退) - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ Host API 与主进程代理层 │ -│ │ -│ • hostapi:fetch(主进程代理,规避开发/生产 CORS) │ -│ • gateway:httpProxy(渲染进程不直连 Gateway HTTP) │ -│ • 统一错误映射与重试/退避策略 │ -└──────────────────────────────┬──────────────────────────────────┘ - │ - │ WS / HTTP / IPC 回退 - ▼ -┌─────────────────────────────────────────────────────────────────┐ -│ OpenClaw 网关 │ -│ │ -│ • AI 智能体运行时与编排 │ -│ • 消息频道管理 │ -│ • 技能/插件执行环境 │ -│ • 供应商抽象层 │ -└─────────────────────────────────────────────────────────────────┘ -``` -### 设计原则 - -- **进程隔离**:AI 运行时在独立进程中运行,确保即使在高负载计算期间 UI 也能保持响应 -- **前端调用单一入口**:渲染层统一走 host-api/api-client,不感知底层协议细节 -- **主进程掌控传输策略**:WS/HTTP 选择与 IPC 回退在主进程集中处理,提升稳定性 -- **优雅恢复**:内置重连、超时、退避逻辑,自动处理瞬时故障 -- **安全存储**:API 密钥和敏感数据利用操作系统原生的安全存储机制 -- **CORS 安全**:本地 HTTP 请求由主进程代理,避免渲染进程跨域问题 - -### 进程模型与 Gateway 排障 - -- ClawX 基于 Electron,**单个应用实例出现多个系统进程是正常现象**(main/renderer/zygote/utility)。 -- 单实例保护同时使用 Electron 自带锁与本地进程文件锁回退机制,可在桌面会话总线异常时避免重复启动。 -- 滚动升级期间若新旧版本混跑,单实例保护仍可能出现不对称行为。为保证稳定性,建议桌面客户端尽量统一升级到同一版本。 -- 但 OpenClaw Gateway 监听应始终保持**单实例**:`127.0.0.1:18789` 只能有一个监听者。 -- 可用以下命令确认监听进程: - - macOS/Linux:`lsof -nP -iTCP:18789 -sTCP:LISTEN` - - Windows(PowerShell):`Get-NetTCPConnection -LocalPort 18789 -State Listen` -- 点击窗口关闭按钮(`X`)默认只是最小化到托盘,并不会完全退出应用。请在托盘菜单中选择 **Quit ClawX** 执行完整退出。 - ---- - -## 使用场景 - -### 🤖 个人 AI 助手 -配置一个通用 AI 智能体,可以回答问题、撰写邮件、总结文档并协助处理日常任务——全部通过简洁的桌面界面完成。 - -### 📊 自动化监控 -设置定时智能体来监控新闻动态、追踪价格变动或监听特定事件。结果将推送到你偏好的通知渠道。 - -### 💻 开发者效率工具 -将 AI 融入你的开发工作流。使用智能体进行代码审查、生成文档或自动化重复性编码任务。 - -### 🔄 工作流自动化 -将多个技能串联起来,创建复杂的自动化流水线。处理数据、转换内容、触发操作——全部通过可视化方式编排。 - ---- - -## 开发指南 - -### 前置要求 - -- **Node.js**:22+(推荐 LTS 版本) -- **包管理器**:pnpm 9+(推荐)或 npm - -### 项目结构 - -```ClawX/ -├── electron/ # Electron 主进程 -│ ├── api/ # 主进程 API 路由与处理器 -│ │ └── routes/ # RPC/HTTP 代理路由模块 -│ ├── services/ # Provider、Secrets 与运行时服务 -│ │ ├── providers/ # Provider/account 模型同步逻辑 -│ │ └── secrets/ # 系统钥匙串与密钥存储 -│ ├── shared/ # 共享 Provider schema/常量 -│ │ └── providers/ -│ ├── main/ # 应用入口、窗口、IPC 注册 -│ ├── gateway/ # OpenClaw 网关进程管理 -│ ├── preload/ # 安全 IPC 桥接 -│ └── utils/ # 工具模块(存储、认证、路径) -├── src/ # React 渲染进程 -│ ├── lib/ # 前端统一 API 与错误模型 -│ ├── stores/ # Zustand 状态仓库(settings/chat/gateway) -│ ├── components/ # 可复用 UI 组件 -│ ├── pages/ # Setup/Dashboard/Chat/Channels/Skills/Cron/Settings -│ ├── i18n/ # 国际化资源 -│ └── types/ # TypeScript 类型定义 -├── tests/ -│ ├── e2e/ # Playwright Electron 端到端冒烟测试 -│ └── unit/ # Vitest 单元/集成型测试 -├── resources/ # 静态资源(图标、图片) -└── scripts/ # 构建与工具脚本 -``` -### 常用命令 - -```bash -# 开发 -pnpm run init # 安装依赖并下载 uv -pnpm dev # 以热重载模式启动(若缺失会自动准备预装技能包) - -# 代码质量 -pnpm lint # 运行 ESLint 检查 -pnpm typecheck # TypeScript 类型检查 - -# 测试 -pnpm test # 运行单元测试 -pnpm run test:e2e # 运行 Electron E2E 冒烟测试 -pnpm run test:e2e:headed # 以可见窗口运行 Electron E2E 测试 -pnpm run comms:replay # 计算通信回放指标 -pnpm run comms:baseline # 刷新通信基线快照 -pnpm run comms:compare # 将回放指标与基线阈值对比 - -# 构建与打包 -pnpm run build:vite # 仅构建前端 -pnpm build # 完整生产构建(含打包资源) -pnpm package # 为当前平台打包(包含预装技能资源) -pnpm package:mac # 为 macOS 打包 -pnpm package:win # 为 Windows 打包 -pnpm package:linux # 为 Linux 打包 -``` - -在无头 Linux 环境下,Electron 测试需要显示服务;可使用 `xvfb-run -a pnpm run test:e2e`。 - -### 通信回归检查 - -当 PR 涉及通信链路(Gateway 事件、Chat 收发流程、Channel 投递、传输回退)时,建议执行: - -```bash -pnpm run comms:replay -pnpm run comms:compare -``` - -CI 中的 `comms-regression` 会校验必选场景与阈值。 -### 技术栈 - -| 层级 | 技术 | -|------|------| -| 运行时 | Electron 40+ | -| UI 框架 | React 19 + TypeScript | -| 样式 | Tailwind CSS + shadcn/ui | -| 状态管理 | Zustand | -| 构建工具 | Vite + electron-builder | -| 测试 | Vitest + Playwright | -| 动画 | Framer Motion | -| 图标 | Lucide React | - ---- - -## 参与贡献 - -我们欢迎社区的各种贡献!无论是修复 Bug、开发新功能、改进文档还是翻译——每一份贡献都让 ClawX 变得更好。 - -### 如何贡献 - -1. **Fork** 本仓库 -2. **创建** 功能分支(`git checkout -b feature/amazing-feature`) -3. **提交** 清晰描述的变更 -4. **推送** 到你的分支 -5. **创建** Pull Request - -### 贡献规范 - -- 遵循现有代码风格(ESLint + Prettier) -- 为新功能编写测试 -- 按需更新文档 -- 保持提交原子化且描述清晰 - ---- - -## 致谢 - -ClawX 构建于以下优秀的开源项目之上: - -- [OpenClaw](https://github.com/OpenClaw) – AI 智能体运行时 -- [Electron](https://www.electronjs.org/) – 跨平台桌面框架 -- [React](https://react.dev/) – UI 组件库 -- [shadcn/ui](https://ui.shadcn.com/) – 精美设计的组件库 -- [Zustand](https://github.com/pmndrs/zustand) – 轻量级状态管理 - ---- - -## 社区 - -加入我们的社区,与其他用户交流、获取帮助、分享你的使用体验。 - -| 企业微信 | 飞书群组 | Discord | -| :---: | :---: | :---: | -| 企业微信二维码 | 飞书二维码 | Discord 二维码 | - -### ClawX 合作伙伴计划 🚀 - -我们正在启动 ClawX 合作伙伴计划,寻找能够帮助我们将 ClawX 介绍给更多客户的合作伙伴,尤其是那些有定制化 AI 智能体或自动化需求的客户。 - -合作伙伴负责帮助我们连接潜在用户和项目,ClawX 团队则提供完整的技术支持、定制开发与集成服务。 - -如果你服务的客户对 AI 工具或自动化方案感兴趣,欢迎与我们合作。 - -欢迎私信我们,或发送邮件至 [public@valuecell.ai](mailto:public@valuecell.ai) 了解更多。 - ---- - -## Stars 历史 - -

- Stars 历史图表 -

- ---- - -## 许可证 - -ClawX 基于 [MIT 许可证](LICENSE) 发布。你可以自由地使用、修改和分发本软件。 - ---- - -

- 由 ValueCell 团队用 ❤️ 打造 -

+请以根目录 [README.md](README.md) 为准,那里包含当前产品定位、功能范围、开发方式、打包方式和内测验证重点。