CoPaw: Your Private, Self-Hosted AI Assistant That Works Across All Your Chat Apps

Imagine having a dedicated assistant that lives entirely on your own computer. It’s not another cloud service you need to log into, and your conversation history won’t be used to train someone else’s model. You can message it directly from within DingTalk, Feishu, or even iMessage. It can read PDFs for you, summarize your weekly reports, remind you of pending tasks on a schedule, and even run a “self-check” while you sleep, then deliver the results straight to your phone.

That’s what CoPaw is all about. It’s not some futuristic concept, but a practical tool you can install with a few commands today and put to work immediately.

This guide will walk you through exactly what CoPaw is, what it can do for you, and how to get it up and running from scratch. We’ll stick strictly to the official documentation, breaking it down into clear, actionable steps.

Part 1: What Exactly Is CoPaw?

In simple terms, CoPaw is a personal assistant application, but its design is fundamentally different from the cloud-based assistants you might be used to.

• It Lives on Your Machine: All of CoPaw’s data and configuration files live in a directory on your own computer (like ~/.copaw). It doesn’t rely on any third-party cloud servers. Your chat history, scheduled tasks, and the preferences it learns about you are all stored locally, under your control.
• It Meets You Where You Already Are: CoPaw isn’t another app or website you need to remember to open. Instead, you connect it to the messaging platforms you use every day. It currently supports DingTalk, Feishu (Lark), QQ, Discord, and even iMessage on macOS. You interact with it by sending messages in these apps, and it replies in the same thread.
• Its Abilities Are Defined by “Skills”: CoPaw is more than just a chat bot. What it can actually do is determined by which “Skills” you enable. Think of Skills as plugins. There are built-in skills for reading PDFs, creating Word documents, fetching the latest news, managing scheduled tasks, and much more. You can turn these on or off, and you can even create your own custom skills.
• It Works for You Automatically: You don’t have to initiate every interaction. You can set up a scheduled job – for example, every weekday at 9 AM, have it send your daily task list to your DingTalk. Or, you can configure a “heartbeat” – a recurring task where CoPaw asks itself a set of questions you’ve pre-defined (like a daily self-review) and then sends you the summary.

In short, CoPaw is a privacy-focused, self-hosted assistant that integrates directly with your existing chat apps, has extensible capabilities, and can perform automated tasks on a schedule.

Part 2: Why Would I Want a Local Assistant Like This?

This is the most direct question. With so many AI chatbots available online, why go through the effort of installing one on your own computer?

The most compelling reasons are data privacy and deep personalization.

Every conversation you have with CoPaw, every preference you ask it to remember (like “I prefer using pytest for testing”), stays on your machine. There’s no corporate cloud database, and your data isn’t used to train models for others. It’s truly your assistant.

Furthermore, it can be deeply integrated into your workflow. It can live in the DingTalk or Feishu groups you use for work. It can scan your local emails (via the himalaya skill). It can read and summarize Word or Excel documents from your hard drive. It becomes a part of your digital life, rather than a separate destination you have to visit.

Part 3: Quick Start: From Installation to Your First Conversation

Let’s get CoPaw running. We’ll follow the official documentation’s steps, breaking them down clearly.

Step 1: Installation (Two Ways, Choose One)

CoPaw offers two main ways to run: locally or on a cloud platform.

Option A: Local Installation (For complete control)

Your computer needs Python, version 3.10, 3.11, 3.12, or 3.13.

1. Open your terminal and install using pip:

   pip install copaw
   

   Pro Tip: It’s a good practice to create a dedicated Python virtual environment for CoPaw first (python -m venv .venv). This keeps its packages separate from your system Python and avoids potential conflicts.

2. Initialize the Configuration:
   This creates the necessary folders and configuration files in your home directory (~/.copaw by default).

   # For a quick test with default settings (skips questions)
   copaw init --defaults
   
   # For a guided setup (recommended for first-time users)
   copaw init
   

   If you run the interactive init, it will ask you about setting up your “heartbeat” interval, which chat channels you want to connect, and crucially, which Large Language Model (LLM) provider you want to use (like ModelScope or DashScope) and your API key.

3. Start the CoPaw Service:

   copaw app
   

   Once the service starts, it listens on your local address, 127.0.0.1:8088, by default. CoPaw is now running in the background, waiting for you.

Option B: ModelScope Studio (For avoiding local setup)

If you prefer not to install Python on your machine, you can deploy CoPaw to Alibaba Cloud’s “ModelScope Studio” with a single click.

1. Register and log in to the ModelScope Community.
2. Visit the CoPaw Studio page and click “One-click Configuration”.
   Important: Make sure to set your created space to “Private”. If it’s public, anyone could potentially interact with your deployed CoPaw instance.

Step 2: Verify the Installation (Optional but Recommended)

With the service running (copaw app), open another terminal window and run this curl command. It sends a simple “hello” message to CoPaw’s API.

curl -N -X POST "http://localhost:8088/agent/process" \
  -H "Content-Type: application/json" \
  -d '{"input":[{"role":"user","content":[{"type":"text","text":"Hello"}]}],"session_id":"test-session"}'

If everything is working correctly, you should see CoPaw’s streaming reply appear in your terminal.

Step 3: Open the Console and Say Hello

Open your web browser and go to http://127.0.0.1:8088/. You’ll see the CoPaw Console, a web-based management interface. You’ll land on the “Chat” page by default.

Type a message in the input box at the bottom and press Enter. Before you connect any external apps (channels), this is the most direct way to interact with CoPaw and confirm it’s working.

Part 4: Bringing CoPaw Into Your Favorite Apps (Channel Configuration)

Chatting in the console is just the first step. To make CoPaw a seamless part of your daily routine, you need to connect it to your messaging apps. This is called “Channel Configuration.”

You manage this in the Console, under Control -> Channels.

The process is simple: click the card for the app you want to add, flip the “Enable” switch in the panel that slides out, and fill in the required credentials. Let’s walk through the most popular one: DingTalk.

Example: Configuring the DingTalk Channel

1. Create an Application on DingTalk’s Developer Platform:

   • Go to the DingTalk Developer Backend and log in.
   • Navigate to “Application Development” -> “Internal Applications” -> “DingTalk App” and click “Create App”.
   • Inside your new app, go to “Capabilities” and add a “Robot”.
   • A critical step: When configuring the robot, set the Message Receiving Mode to “Stream Mode”. This allows your local CoPaw instance to receive messages directly from DingTalk without needing a public IP address or complex firewall setup.
   • Go to “App Publishing” -> “Version Management”, create a new version, fill in the basic info, and save it.
   • Finally, go to “Basic Information” -> “Credentials”. Here you’ll find your Client ID (which is your AppKey) and Client Secret (your AppSecret). Copy these – they are the credentials you need.

2. Bind the Application in CoPaw:

   • Back in the CoPaw Console, on the Channels page, click the “DingTalk” card.
   • In the panel, paste your Client ID and Client Secret. Click “Save”.
   • Configuring DingTalk in CoPaw Console

3. Find Your Robot and Start Chatting:

   • Open the DingTalk app on your phone or computer.
   • Go to your message list and use the search bar. Search for the name you gave your robot when you created it on the developer platform.
   • It should appear under the “Functions” or “Robots” section. Click it to open a 1-on-1 chat and start messaging. You can also add this robot to your DingTalk groups.
   • Finding the robot in DingTalk

The logic is very similar for other channels like Feishu, QQ, or Discord. You always need to create an application on their respective developer platforms first to obtain the necessary credentials (App ID, App Secret, Bot Token, etc.), and then enter those credentials into the CoPaw Console. The official Channel Configuration documentation provides detailed, step-by-step instructions for each platform.

Part 5: Giving CoPaw a Long-Term Memory

This is one of CoPaw’s most practical features. It doesn’t just forget everything after each conversation; it has a system for cross-session, long-term memory.

• How Does the Memory Work?
  CoPaw’s memory system has two main layers:

  1. Context Window Management: When a conversation becomes very long and starts approaching the token limit of the LLM, CoPaw automatically compresses the earlier parts of the conversation into a concise summary. It then uses this summary for context, allowing the conversation to continue smoothly without losing the thread. You can also manually trigger this compression anytime by typing the command /compact.
  2. Long-Term Memory Persistence: CoPaw writes important information – like your stated preferences, key project decisions, or daily work logs – into local Markdown files. For example, a file named MEMORY.md stores long-lasting, stable information. A directory named memory/ contains daily log files like memory/2025-02-15.md, which record summaries of interactions from that day.
• What’s the Practical Benefit of Memory?
  Because of this, you can ask CoPaw on Monday to help you outline tasks for the week. Then, on Wednesday, you can ask, “What’s the status of the tasks we planned on Monday?” CoPaw can use its memory_search function to semantically search through its daily log files, “remember” the context, and give you a meaningful update. It’s not just reacting; it’s recalling.

Part 6: Making It Work Automatically (Heartbeat vs. Scheduled Jobs)

CoPaw has two distinct features for automation, each designed for a slightly different purpose.

• The “Heartbeat” (Periodic Self-Check):
  Think of this as a recurring “daily stand-up” or “system health check” for your own tasks. You maintain a file called HEARTBEAT.md in your working directory. Inside, you write a list of questions you want CoPaw to ask itself on a regular basis.
  Then, in your config.json file, you configure an interval (e.g., "every": "30m" for every 30 minutes) and a delivery target ("target": "main" runs the check without sending a message; "target": "last" sends the results to the same channel where you last had a conversation).
  Example HEARTBEAT.md:

  # Heartbeat Checklist
  - Scan my inbox for any urgent emails.
  - Check my calendar for meetings in the next 2 hours.
  - Review my to-do list for any tasks that are overdue or due soon.
  

  Once configured, CoPaw will, like a steady heartbeat, run this checklist in the background at your specified interval. It’s perfect for a proactive assistant that keeps you on track.

• Scheduled Jobs (Cron Jobs):
  This is a more general-purpose scheduler for one-off or recurring tasks. You manage these via the copaw cron command or through the Console. Each job has its own independent schedule and content.

  • Type A: Text Job. For example, send the message “Good morning, team!” to a specific DingTalk group every day at 9:00 AM.
  • Type B: Agent Job. For example, every 2 hours, ask CoPaw the question “What are my pending tasks?” and then forward its answer to your QQ.
    Scheduled jobs use the standard and flexible cron expression syntax for defining schedules.

Part 7: Expanding Its Capabilities (Skills)

What CoPaw can actually do is determined by its “Skills.” You manage these in the Console under Agent -> Skills, where you can toggle them on and off like light switches.

The built-in skills cover a wide range of common use cases:

• Document Processing: Skills like pdf, docx, pptx, and xlsx allow CoPaw to create, read, and edit common office documents.
• Information Gathering: The news skill can fetch and summarize recent headlines from various categories. The himalaya skill provides email management capabilities directly from the command line (which CoPaw can interact with).
• System Interaction: The browser_visible skill can launch a real, headed browser window. This is useful for tasks that require logging into a website or solving a captcha.
• Core Utilities: The file_reader skill handles reading various text-based files. The cron skill is the engine that powers the scheduled jobs feature itself.

If you have a specific need not covered by built-in skills, you can create your own Custom Skill. Simply create a new folder inside ~/.copaw/customized_skills/. Inside that folder, create a SKILL.md file. Write a clear Markdown description of your skill, including its name, description, and any instructions for its use. CoPaw will automatically detect and load it.

Part 8: Core Configuration and Commands (The CLI)

For users comfortable with the terminal, CoPaw provides the copaw command-line tool to manage nearly every aspect of the application.

Commands that interact with a running service (like cron, chats) automatically use the host and port saved from the last time you ran copaw app. You can override them with global flags like --host and --port if needed.

Part 9: Frequently Asked Questions (FAQ)

• Is my chat history and data secure?
  Yes. By default, all your conversation logs, configuration files, and long-term memory files are stored locally on your computer in the ~/.copaw directory. CoPaw does not automatically upload any of this data to third-party servers, except when you use a skill that explicitly calls an external API (like a news fetch).

• Do I need to keep the terminal and browser open all the time?
  You need the copaw app service to be running continuously in the background for CoPaw to receive messages and execute scheduled tasks. However, you can close the browser tab with the Console. You only need to reopen the Console when you want to change configurations or have a chat session there.

• What happens if I accidentally delete the ~/.copaw folder?
  You will lose all your configuration, chat history, and long-term memory. It’s a good idea to periodically back up this directory if you have important data stored within it. If you delete it, you can start over by running copaw init again.

• Can CoPaw help me write code or research topics?
  This depends entirely on the LLM model you configured for it and the skills you have enabled. If you chose a powerful model known for its coding abilities, then yes, it can help with code. If you have the news skill enabled, it can summarize news. Its core capability is defined by the model’s intelligence and the specific tools (skills) you give it access to.

• Will CoPaw work if I shut down my computer?
  No. The copaw app service runs on your local machine. If your computer is off, asleep, or disconnected from the internet, the service stops. It won’t be able to receive new messages or execute scheduled jobs until it’s running again and connected.

Conclusion: An Assistant That Truly Works for You

CoPaw presents a refreshingly different model for a personal AI assistant. It prioritizes your privacy by putting you in complete control of your data. It lowers the barrier to use by integrating seamlessly with the messaging apps you already rely on. And it offers genuine utility through its extensible skill system and powerful automation features, from the proactive “heartbeat” checks to flexible scheduled jobs.

It’s not just a chatbot; it’s a framework for building a digital partner that lives on your own terms. If you value data privacy, enjoy tailoring tools to your specific workflow, and are looking for an assistant that can do more than just chat, CoPaw is definitely worth setting up. The journey from a few terminal commands to a personalized, always-on helper is surprisingly short.

Useful Resources & Documentation:

• Project Introduction
• Quick Start Guide
• Console User Guide
• Channel Configuration (DingTalk, Feishu, QQ, etc.)
• Skills Documentation
• Memory System Explained
• Heartbeat Configuration
• CLI Command Reference
• Configuration File Details