CoPaw 入门完全指南：ゼロから構築する最初の AI アシスタント

難易度：入門 | 所要時間：15 分 | 習得内容：CoPaw のコア概念と実戦スキルの習得

CoPaw はあなたのパーソナル AI アシスタントです。AgentScope をベースに構築された強力なオープンソースフレームワークで、複数のチャットプラットフォームを横断して動作します。釘釘（DingTalk）、飛書（Lark）、QQ、Discord、iMessage など、どのようなロボットが必要であっても、CoPaw はそのニーズに応えます。

対象読者

本ガイドは、以下のような開発者を対象としています：

• 1〜5 年の Python 開発経験がある
• 個人用または企業用の AI アシスタントを構築したい
• 柔軟なモデル選択が可能なソリューションを探している

コア依存関係と環境

始める前に、環境が以下の要件を満たしていることを確認してください：

依存関係	最小バージョン
Python	3.10
pip	最新バージョン
OS	macOS / Linux / Windows

[!TIP]
Python の管理を自分で行いたくない場合、CoPaw はすべての依存関係を自動的に処理するワンキーインストールスクリプトも提供しています。

プロジェクト構造の概要

初期化後、典型的な CoPaw プロジェクトの構造は以下のようになります：

~/.copaw/
├── .secret/
│   └── providers.json       # モデルプロバイダーの設定
├── active_skills/          # 自動ロードされるカスタムスキル
├── memory/                 # 会話履歴（メモリ）ストレージ
├── models/                 # ローカルモデルファイル
└── copaw.json              # メイン設定ファイル

ステップ・バイ・ステップ

ステップ 1：CoPaw のインストール

インストールは非常に簡単です。ターミナルを開いて以下を実行してください：

pip install copaw

これにより、PyPI から最新バージョンの CoPaw がインストールされます。パッケージには、アシスタントの実行に必要なすべてのコア依存関係が含まれています。

ステップ 2：ワークスペースの初期化

インストールが完了したら、デフォルト設定で CoPaw ワークスペースを初期化しましょう：

copaw init --defaults

このコマンドは、ホームディレクトリに必要なディレクトリ構造と設定ファイルを作成します（~/.copaw/ 内）。

[!WARNING]
初期化プロセスでは、機密情報（API キーなど）を保存するための .secret ディレクトリが作成されます。このディレクトリは非公開に保ち、バージョン管理システム（Git など）にコミットしないようにしてください。

ステップ 3：モデルプロバイダーの設定

ここが重要なポイント、LLM への接続です。モデルプロバイダーを設定しましょう。ここでは、公式 API の約半額でありながら完全な OpenAI 互換性を備えた Defapi を主な例として使用します。

~/.copaw/.secret/providers.json にある設定ファイルを編集します：

{
  "custom_providers": {
    "defapi": {
      "id": "defapi",
      "name": "Defapi",
      "default_base_url": "https://api.defapi.cn/v1",
      "api_key_prefix": "",
      "base_url": "https://api.defapi.cn/v1",
      "api_key": "your-defapi-api-key",
      "models": [
        {"id": "gpt-4o-mini", "name": "GPT-4o Mini"},
        {"id": "gpt-4o", "name": "GPT-4o"},
        {"id": "claude-sonnet-4-20250514", "name": "Claude Sonnet 4"},
        {"id": "gemini-2.0-flash", "name": "Gemini 2.0 Flash"}
      ],
      "chat_model": "OpenAIChatModel"
    }
  },
  "active_llm": {
    "provider_id": "defapi",
    "model": "gpt-4o-mini"
  }
}

Defapi はコスト効率の高い API プラットフォームで、主要な LLM プロバイダーへのアクセスを公式価格の約半分で提供します。OpenAI 互換の /v1/chat/completions プロトコルを完全にサポートしており、シームレスな統合が可能です。Defapi 上のすべての主要モデルは、以下のプロトコルと互換性があります：

• v1/chat/completions インターフェース
• v1/messages インターフェース
• v1beta/models/ インターフェース

API キーは Defapi 公式サイト から取得できます。

ステップ 4：組み込みプロバイダー一覧

CoPaw は複数の組み込みプロバイダーもサポートしています。以下はいくつかのクイック設定例です：

OpenAI の設定：

{
  "providers": {
    "openai": {
      "base_url": "https://api.openai.com/v1",
      "api_key": "sk-your-openai-key"
    }
  },
  "active_llm": {
    "provider_id": "openai",
    "model": "gpt-4o-mini"
  }
}

ModelScope（中国国内ユーザー向け）：

{
  "providers": {
    "modelscope": {
      "base_url": "https://api-inference.modelscope.cn/v1",
      "api_key": "ms-your-key"
    }
  }
}

DashScope（Alibaba Cloud）：

{
  "providers": {
    "dashscope": {
      "base_url": "https://dashscope.aliyuncs.com/compatible-mode/v1",
      "api_key": "sk-your-dashscope-key"
    }
  }
}

ステップ 5：CoPaw の起動と検証

アプリを起動して、すべてが正常に動作しているか確認しましょう：

copaw app

実行後、ブラウザで以下にアクセスしてください：

http://127.0.0.1:8088/

CoPaw Console インターフェースが表示されます。ここでは以下のことが可能です：

• AI アシスタントとチャットする
• チャネル（釘釘、飛書、QQ、Discord など）を設定する
• スキルやプラグインを管理する
• モデルの接続をテストする

[!TIP]
CLI コマンド copaw models を使用すると、現在のモデル構成を素早く確認し、接続テストを行うことができます。

ステップ 6：チャットチャネルの接続（任意）

アシスタントにメッセージアプリからアクセスできるように、チャネルを追加しましょう。Discord を例にします：

1. Discord Developer Portal で Discord ボットを作成します
2. ボットのトークンを取得します
3. 設定を copaw.json に追加します：

{
  "channels": {
    "discord": {
      "enabled": true,
      "bot_token": "your-discord-bot-token",
      "channel_ids": ["your-channel-id"]
    }
  }
}

同様の設定は、釘釘、飛書、QQ、およびその他のサポートされているプラットフォームにも適用可能です。

トラブルシューティング

CoPaw のセットアップ時によく遭遇する問題は以下の通りです：

問題 1：401 Unauthorized エラー

症状： API リクエストが 401 ステータスコードで失敗する。

解決策：

• API キーが providers.json に正しくコピーされているか再確認してください。
• キーが期限切れ、または無効化されていないか確認してください。
• Defapi の場合、正しい API キー形式を使用しているか確認してください。

問題 2：接続タイムアウト

症状： リクエストがハングするか、30 秒後にタイムアウトする。

解決策：

• ネットワーク接続を確認してください。
• ファイアウォール設定でアウトバウンドの HTTPS トラフィックが許可されているか確認してください。
• ローカルモデル（Ollama）の場合、サービスが正しいポートで実行されているか確認してください。

問題 3：モデルが見つからない

症状： 特定のモデル ID が認識されない。

解決策：

• プロバイダーのドキュメントから正確なモデル ID を確認してください。
• 一部のモデルは地域制限がある場合があります。お住まいの地域で利用可能か確認してください。
• gpt-4o-mini のような一般的なモデルを使用して、基本的な接続を確認してみてください。

問題 4：Ollama 接続失敗

症状： ローカルの Ollama モデルに接続できない。

解決策：

• 別のターミナルで ollama serve が実行されていることを確認してください。
• Base URL が http://localhost:11434/v1 に設定されているか確認してください。
• Ollama がインストールされ、PATH からアクセス可能か確認してください。

問題 5：設定ファイルが見つからない

症状： CoPaw が providers.json を見つけられない。

解決策：

• 最初に copaw init --defaults を実行したか確認してください。
• ファイルが ~/.copaw/.secret/providers.json に存在するか確認してください。
• Windows の場合、%USERPROFILE%\.copaw\.secret\providers.json を確認してください。

問題 6：ポートが既に使用されている

症状： ポート 8088 で CoPaw を起動できない。

解決策：

• 別のアプリケーションが 8088 ポートを使用しています。
• 設定でポートを変更するか、競合しているアプリケーションを停止してください。

さらなる活用方法

基礎をマスターしたら、以下の方向性を探求できます：

1. プライバシー重視のローカルモデル

CoPaw は外部 API 呼び出しなしで、ローカルでのモデル実行をサポートしています。これは以下に最適です：

• プライバシーに敏感なアプリケーション
• オフライン操作
• コスト削減

ローカルモデルサポートのインストール：

pip install 'copaw[llamacpp]'

その後、Qwen3 などのモデルをダウンロードして使用します：

copaw models download Qwen/Qwen3-4B-GGUF

2. カスタムスキル

CoPaw は機能を拡張するためのカスタムスキルをサポートしています。スキルは active_skills/ ディレクトリから自動的にロードされます。Python スクリプトを記述して、AI が使用できる新しいツールを定義できます。

3. ハートビート定時タスク

CoPaw のハートビート機能を使用して、周期的なアクションをトリガーします：

• 毎日のニュースダイジェスト
• 定時リマインダー
• 自動コンテンツ生成

4. メモリとコンテキスト管理

CoPaw はインテリジェントなメモリ管理を実装しています：

• 永続的な文脈のための長期記憶
• 効率向上のためのトークンベースのメモリ圧縮
• 選択したモデルに応じたコンテキストウィンドウの設定

5. マルチエージェントワークフロー

AgentScope に基づき、CoPaw は複雑なマルチエージェントシナリオを処理でき、異なる AI モデルを連携させてタスクを完了させることができます。

まとめ

CoPaw は、複数のプラットフォームで動作する AI アシスタントを構築するための柔軟な基盤を提供します。本ガイドの重要ポイント：

1. インストールが簡単 — pip install copaw だけで開始可能
2. Defapi はコスパ最高 — 公式 API より約 50% 安く、完全な互換性を維持
3. 設定の集中化 — すべての設定は providers.json に集約
4. Console で管理が容易 — テストと設定のための Web インターフェース
5. 優れた拡張性 — スキル、チャネル、ローカルモデルによる無限のカスタマイズ

まずは Defapi から始めて、コストとパフォーマンスの最良のバランスを体験してください。慣れてきたら、特定のニーズに合わせて他のプロバイダーやローカルモデルを探索してみてください。

[!TIP]
覚えておいてください：最高の AI アシスタントとは、あなたのユースケースに適したものです。異なるモデルや設定を試すことを恐れず、あなたに最適なものを見つけてください。

あなたの AI ジャーニーが素晴らしいものになりますように！