Coopanion README

项目的 README,来自 github.com/Pal-AI-Lab/Coopanion。合并为一个 markdown 文件:README.md。

Coopanion

English | 简体中文

Release CI Windows 10 / 11 macOS 13+ Linux x64 AGPL-3.0

Website | Install | Getting Started | Everyday Use | Cost and Privacy | FAQ | Community | Changelog | Development

Coopanion is a desktop pet named Coo that lives on the bottom edge of your screen. It wanders along the edge, chats with you in speech bubbles and listens while you hold the talk key. If you let it, it can also look at your screen, click and type to use the computer for you. It runs on Windows, macOS and Linux.

The interface comes in 11 languages: 简体中文, 繁體中文, English, 日本語, 한국어, Français, Deutsch, Español (Latinoamérica), Português (Brasil), Italiano and Русский. On first start it follows the system language, falling back to English, and you can change it later under Language on the Habits page. Coo talks to you in the same language. Translations other than Simplified Chinese and English are machine-made; PRs that fix them are welcome.

Coopanion settings: model connections and the Coo preview

Features

What changed in each version is in Releases.

Install

You need:

Every release page has a SHA256SUMS.txt for checking the downloads.

Windows

macOS

  1. From the latest release, download Coopanion-<version>-mac-arm64.dmg (Apple silicon) or …-mac-x64.dmg (Intel), open it and drag Coopanion into Applications.
  2. The app is neither signed with an Apple developer ID nor notarized, so macOS blocks the first launch. Open it once and click Done on the warning, then go to System Settings → Privacy & Security, click Open Anyway and enter your password.
  3. Coopanion's icon is in the menu bar. It shows up in the Dock only while the settings window is open.

While the App Store is in front, Coo drops behind other windows so it doesn't cover the Touch ID prompt for purchases.

[!NOTE] macOS asks for Microphone (voice input), Input Monitoring (talk key), Screen & System Audio Recording and Accessibility (computer use) the first time each one is needed, and switching apps during computer use also asks to control "System Events". Restart Coopanion after changing Screen Recording, Input Monitoring or Accessibility. macOS does not carry these permissions over to an updated version: if a switch is on but Coopanion says the permission is missing, remove Coopanion from that list with −, add /Applications/Coopanion.app back and restart.

Linux

  1. From the latest release, download Coopanion-<version>-linux-x64.deb (Debian / Ubuntu) or Coopanion-<version>-linux-x64.AppImage (other distributions).
  2. deb: sudo apt install ./Coopanion-<version>-linux-x64.deb. AppImage: install your distribution's FUSE 2 compatibility library, run chmod +x Coopanion-*.AppImage, then start it.

[!NOTE] The pet is a transparent always-on-top window, so the desktop needs compositing (on by default in GNOME and KDE). The tray icon needs status icon support (GNOME needs the AppIndicator extension); without a tray you can still right-click Coo to open the settings. Computer use needs xdotool and zenity, which the deb pulls in; under Wayland, screenshots also need one of grim, spectacle, scrot or ImageMagick.

In a Wayland session Coopanion runs through XWayland, which sees the cursor only over X11 windows. While the cursor is over the desktop or a native Wayland window, Coo's eyes do not follow it, and the hover buttons show only once the cursor moves onto Coo.

Getting started

  1. Start: Coo drops to the bottom of the screen and an icon appears in the tray (the menu bar on Mac, the status bar on Linux). No window opens.
  2. Follow the guide: in its bubbles, Coo asks for the interface language, where you heard about it (you can skip this), what it should call you, what Coo is like, how often it walks around, which touches it should answer and which model service to use. Then it downloads the speech model: FunASR, about 230 MB, or Whisper, about 360 MB, when the interface language is French, German, Spanish, Portuguese, Italian or Russian. The download comes from ModelScope and falls back to Hugging Face. Back at the top left of the bubble returns to the step before, with your earlier answer in place. The × ends the guide, and Guide on the Start page runs it again. To change Coo's personality or the way it talks afterwards, just tell it; it writes the persona into its prompt itself.
  3. Say hello: tap Left Alt (Left Option on Mac), then press and hold it, say "hello", and let go to send. Allow microphone access when asked.
Connect a model: API key or ChatGPT sign-in

Choose a service in Coo's bubble or on the Start page, create an API key on its platform (DeepSeek also needs a topped-up balance) and paste it in.

Service Get a key Default model
OpenAI platform.openai.com gpt-6-luna
Anthropic platform.claude.com claude-haiku-5-5
Gemini (Google AI Studio) aistudio.google.com gemini-3.5-flash-lite
xAI console.x.ai grok-4.3
OpenRouter openrouter.ai deepseek/deepseek-v4.1-flash
DeepSeek platform.deepseek.com deepseek-flash
Kimi (Moonshot) international platform.kimi.ai, mainland China platform.kimi.com kimi-k3
Qwen (Alibaba Cloud Model Studio) international modelstudio.console.alibabacloud.com, mainland China bailian.console.aliyun.com qwen3.8-flash
MiniMax international platform.minimax.io, mainland China platform.minimax.cn MiniMax-M3
Zhipu GLM international (Z.ai) z.ai, mainland China bigmodel.cn glm-5.3-flash (if it fails to connect on the mainland China platform, glm-5.3 works, but it can't see images, so no computer use)
Doubao (Volcengine Ark) ark.volcengine.com doubao-seed-2-1-lite-260915 (enable it in the Ark console first)
Baidu Qianfan console.bce.baidu.com glm-5.3-flash
StepFun platform.stepfun.com step-3.7-flash
StepFun Step Plan platform.stepfun.com step-5-preview (billed to the Step Plan subscription)

These are the defaults from the app's vendor table. To use another model, change the Model field on the Start page; for computer use the model has to accept images. Kimi, Qwen, MiniMax and Zhipu GLM each have a mainland China and an international platform with separate accounts and keys. A new connection uses the mainland platform when the interface language is Simplified Chinese and the international one otherwise; switch on the Start page. Doubao, Baidu Qianfan, StepFun and StepFun Step Plan only take mainland China accounts. We have only tested DeepSeek, Anthropic and StepFun Step Plan with real keys, so please open an issue if another one fails.

ChatGPT needs no key: choose it, press Continue with ChatGPT and sign in in the browser that opens. Coo then uses that account's ChatGPT plan. When the plan's usage limit is reached, Coo goes quiet and tries again every 5 minutes.

Everyday use

Talking and playing

Speech is recognized locally by default: FunASR for Chinese, English, Japanese and Korean, Whisper for French, German, Spanish, Portuguese, Italian and Russian, and on Windows you can also use the system recognizer. You can switch to an OpenAI-compatible transcription service on the Voice input page instead; each sentence you say is then sent to that service as audio.

Rest the pointer on Coo and the buttons you picked pop up beside it: up to 6 of typing, voice input, walking, night mode, sounds, hide, size, dress up and My Worlds (picked in the first-run introduction, changed later under Habits). Right-clicking Coo shows the same ones, plus settings, pause / resume and quit. Hovering the dress button shows your favourite looks in a row over Coo's head; scroll or click to switch. A Size hover button can be added too: hovering it shows a size slider over Coo's head; drag it, or scroll over the button. Clicking Size keeps the slider open until you click it again or click elsewhere. While the size or the look changes, the button under the pointer stays put and moves back beside Coo once the pointer leaves. Closing the settings window does not quit the app. The tray menu (the menu bar icon on Mac) has Show pet or Hide pet, Let clicks pass through Coo, Restart and Quit; Start at login is under Habits → General. With click-through on, every click goes through Coo to the window below while Coo keeps walking and talking, which helps while gaming. It only lasts for the current run: choose Stop clicks passing through Coo or quit to turn it off.

Appearance and sound

Change the figure, colors and accessories on the Dress up page, including the accessories' main and accent colors; changes apply right away. Figure packs can be imported from a zip or a folder, or dragged onto the page, and imported packs are uninstalled there too. Import, replacement and uninstall confirmations, progress and errors use the settings window’s shared dialogs. Size, under the figures, sets how large Coo is on the desktop; each figure keeps its own size and gets it back when you switch to it again. The previews on Dress up and Start keep one size.

The star at the top right of the preview adds the look Coo wears to Favourite looks, listed in one row at the top of the page: click one to put it on, drag it to reorder, or rename and delete it. A favourite keeps the size it was saved at and puts it back on with the look; its picture is drawn at that size, with the percentage in its corner. After you pick a favourite and change it, its size included, a save button next to the star writes the change back to it.

You can also just ask Coo to change its look. By default it changes its figure, colors, walking and snoring on its own, and asks you first before changing sizes, sounds, night mode or names; Habits → Self-adjustment loosens or tightens this. Asked what it looks like right now, Coo can take a picture of its body as it is on the desktop at that moment, without bubbles or the desktop behind it; while the pet is hidden there is none to take.

Dress up: Coo palettes, hats and accessories

Under Habits → Sounds you can choose which sounds play, set the volume for all of the pet's sounds, and let the sound pan left or right with Coo's position on the screen. Speech → Read bubbles aloud makes Coo babble short syllables as the text appears, instead of the usual talking sound; pitch and speed are adjustable. These settings only cover the pet's own sounds. Sounds from other Worlds are set on their own pages.

Habits: pet sound volume, stereo positioning and speech settings

To show Coo in OBS, turn on Habits → Other → Export OBS overlay, add the URL it shows as an OBS Browser source and set the width and height to your screen resolution. The source contains only Coo and its bubbles, on a transparent background.

Computer use

Computer use is off by default. Turn on Let Coo use this computer under Habits → Computer use and confirm the risk notice. If you only want Coo to see the screen and keep its hands off the mouse and keyboard, turn off Allow the mouse and keyboard.

There are four settings for when Coo asks you first:

When to ask you When Coo asks
Every turn Before the first screenshot or mouse/keyboard action in each turn
Before acting Screenshots without asking; before the first mouse or keyboard action in each turn
Once (default) Screenshots without asking; once before acting, then not again for the consent period (30 minutes by default)
Never Never

Settings window

Open the settings window from the tray icon or from Coo's right-click menu.

Page What's there
Start Model connection, showing or hiding the pet, interface colors, the first-run guide
Habits Language and names, automatic updates, usage statistics, walking and touch responses, which settings Coo may change itself, shortcuts, display, sound, computer use, OBS overlay
Dress up Figure, colors and accessories; import or uninstall figure packs
Voice input Recognition engine or transcription service, model download, talk key, microphone, listening mode, speech threshold
System prompt Persona and prompt templates; Ctrl+S saves, and Apply now puts the new prompt into the current conversation
Usage & cost Token usage and spending by day and model
Chat Conversation history, typing, images
World extensions Installed Worlds, groups and order, the extension market

Pause / resume and the switch to Advanced mode are at the bottom of the sidebar. Advanced mode adds the Model connections, Persona, Memory, Console and Diagnostics pages. Model connections is where you change models, adjust reasoning effort, add other compatible services, enter prices for services without built-in ones and install provider extensions.

Settings show operation errors beside the initiating control. If that control is no longer visible, the error uses a bottom notification. Read failures stay in the affected content region; refresh failures preserve loaded data and edits until a successful retry. Diagnostics report connection, event and log failures separately. Saving an avatar or name, pausing Coo and cancelling an alarm use the updated state as confirmation.

World extensions

In World extensions → Extension market you can search for Worlds, filter by category or tag, and install one with Add to My Worlds on its card, or open its details first. Packages in the official index also show tags, votes and comments; commenting needs a GitHub sign-in. Caution tags can be excluded; packages with an excluded tag stay out of the results, and the exclusion is remembered next time.

A newly installed extension shows up under Applies on restart; click Restart process to load it. In My Worlds you can:

A running World can't be deleted; stop it first. A deleted World stays under Applies on restart, marked in red, until you restart the process.

World extensions: installed Worlds, status and grouping controls

Provider extensions are under Advanced mode → Model connections → Extension market; one that a connection still uses can't be deleted until you delete that connection. Installed extensions live in the data folder and survive a reinstall of the app.

If you quit the app while an extension is being installed or uninstalled, it waits for that install or uninstall to finish before quitting.

Updates

The Windows installer build and the AppImage download new versions in the background, and Coo asks whether to restart and update when one is ready. Choose Later and it installs when you quit. To stop automatic updates, turn off Habits → General → Automatic updates: Coopanion then stops checking and downloading, and an update that was already downloaded is not installed.

The Mac version, the deb and the Windows portable version do not update themselves. When a new version is out, a download link appears in the settings window's title bar; download it and install it yourself.

Cost and privacy

Data and uninstalling

System Data folder Uninstall
Windows data in the install folder; for the portable version, data in its folder Settings → Apps; for the portable version, turn off Start at login under Habits → General, then delete the folder
macOS ~/Library/Application Support/Coopanion Drag Coopanion from Applications to the Trash
Linux ~/.config/Coopanion deb: sudo apt remove coopanion; AppImage: delete the file

Uninstalling the installed version keeps your data. The portable version keeps data inside its own folder, so back it up before deleting the folder. To remove everything, delete the data folder by hand; on Windows, delete the whole install folder and also %LOCALAPPDATA%\Coopanion, which records where the data is. Inside it, home holds memory, conversation history, settings and API keys, home/models the speech model, extensions the extensions and logs the logs.

On Windows, after reinstalling into a new folder, the first start asks whether to keep using your earlier data or start a new Coo.

FAQ

The pet is gone

Right-click the tray icon and choose Show pet; if the tray icon is hidden, click ^ at the bottom right of the taskbar first. Opening the program again works too. On Mac, click the menu bar icon and choose Show pet.

Clicks go straight through Coo

Let clicks pass through Coo is on in the tray menu. Click it again to turn it off, or restart Coopanion.

Coo does not answer

Check Start → Connected model and the run status at the bottom of the sidebar. If it says Paused, click resume. If it says Not connected, make sure the API key was pasted in full and the account has credit, then click Save and start; for an existing connection, Test checks it again. Keys for Kimi, Qwen, MiniMax and Zhipu GLM only work on the platform (mainland China or international) where they were created, and Doubao needs the default model enabled in the Ark console.

After 5 failed model requests in a row, Coo tells you what went wrong in a bubble. For a rejected key or an unknown model name it offers a button that opens the settings; for rate limits and server errors it asks you to wait a while.

Coo cannot hear me
  • The mic button next to Coo should not be crossed out.
  • Tap Left Alt first, then press and hold it (two presses too far apart don't count).
  • The Voice input page should show the recognizer as ready (click Download if the model is missing), and its level meter should move while you speak.
  • Windows: in Settings → Privacy & security → Microphone, allow desktop apps to use the microphone.
  • Mac: in System Settings → Privacy & Security, turn on Microphone and Input Monitoring for Coopanion, then restart it.
I need a proxy

Coopanion uses the system proxy (HTTP or HTTPS; SOCKS proxies are not used) as it is set at the moment of each request, so turning a proxy app on or off needs no restart, and a PAC script picks the proxy per site. If HTTP_PROXY / HTTPS_PROXY are set in the environment Coopanion starts from, those take precedence. Local traffic inside the app skips the proxy.

On Linux, Coo leaves square trails behind it

With Intel graphics (Mesa's iris driver), fast clear leaves old frames in transparent windows. Start Coopanion with INTEL_DEBUG=nofc set to turn it off, for example INTEL_DEBUG=nofc coopanion for the deb; rendering on a discrete GPU also fixes it.

The whole screen under the pet turns black

On some Windows machines, transparent windows are drawn black while hardware acceleration is on. Try adding --disable-gpu-compositing to the end of the shortcut's Target field.

What is it thinking?

The Chat page has the full record. If something goes wrong, switch to advanced mode, click Export diagnostics on the Diagnostics page and attach the file to an issue.

Community

Contributing

Acknowledgements

Thanks to everyone who has written code for Coopanion:

Coopanion contributors

And thanks to everyone who reports bugs and suggests ideas in Issues, the QQ groups and Discord.

Coopanion is assembled from Cortico: Cortico Core + Cormini Persona + the desktop pet World, computer use included.

Star history

Coopanion star history

License

AGPL-3.0-or-later, with an additional permission under section 7 to link the Steamworks API libraries that the Steam version loads. Releases up to and including 0.1.10 are MIT. The Cortico framework is MIT and ships as a submodule. Before opening a PR, read CONTRIBUTING.md; your first contribution needs a signed Contributor License Agreement.

The DeepSeek Chan artwork (the textures under packages/cortico-world-desktop-pet/web/whale/) is not covered by the AGPL; its origin and the vendor logos are described in the desktop pet World's third-party notices. Third-party components shipped or downloaded at runtime: Electron (MIT), Cortico (MIT), sherpa-onnx (Apache-2.0), FunASR's SenseVoiceSmall model (FunASR model license, downloaded when needed), OpenAI's Whisper small model (MIT, downloaded when needed), koffi (MIT), jpeg-js (BSD-3-Clause), pnpm (MIT), and on Windows MinGit from Git for Windows (GPL-2.0); model service logos come from lobe-icons (MIT; each logo belongs to its company and only identifies the service).

Coopanion (Pal-AI-Lab/Coopanion)

正在搜索数据库…

这是什么?Coopanion(Coo)是一个小巧的桌面宠物,住在屏幕底部边缘,通过对话气泡和你聊天,你说话时它会听,还会四处走动;在你授权的情况下,它还可以操作你的电脑。
这是浏览器小部件,还是需要安装的实际应用?它是一款原生 Electron 桌面应用,需要按操作系统分别安装。运行时以始终置顶的悬浮宠物窗口呈现,并在托盘中显示图标(macOS 为菜单栏,Linux 为状态栏),而不是浏览器扩展。
我该如何安装 Coo?从最新的 GitHub Release 下载适用于你操作系统的安装包或便携版:Windows 用 .exe,macOS 用 .dmg(arm64 或 x64),Linux 用 .deb 或 .AppImage,然后运行即可。
在 Coo 能真正和我聊天之前,我需要准备什么?你需要从以下任一受支持的模型服务获取 API 密钥(OpenAI、Anthropic、Gemini、xAI、OpenRouter、DeepSeek、Kimi、Qwen、MiniMax、智谱 GLM、豆包、百度千帆或 StepFun),或者拥有一个带套餐的 ChatGPT 账户;语音识别会下载本地模型(FunASR 约 230MB,或 Whisper 约 360MB)。
安装时可能会遇到哪些问题?安装包没有经过代码签名,因此 Windows 会弹出「Windows 已保护你的电脑」的提示,macOS 会在首次打开时拦截,需要你在「隐私与安全性」中手动允许;Linux 上的语音识别还需要 glibc 2.32 及以上版本(Ubuntu 22.04 / Debian 12 或更新版本)。
Coo 能在哪些系统上运行?Windows 10/11 64 位、搭载 Apple 芯片或 Intel 处理器的 macOS 13 或更高版本,以及 64 位 Linux 桌面(X11,或 Wayland 下的 XWayland)。
我的聊天记录和个人信息会存到哪里?Coo 了解到的关于你的信息会写入其工作区中的本地文件 PARTNER.md,应用的提示词会完整包含该文件;每次修改都会留有版本记录,在高级模式下可在记忆页面中查看。
DeepSeek Chan 形象是什么?它是一个可选的全动画鲸鱼少女角色,你可以选择它来代替默认的 Coo,共有八种厂商配色方案和三套服装(女仆装、冬季装和船员制服)。
我能同时运行多个宠物吗?可以,复制便携版的文件夹即可创建一个独立的宠物,拥有自己的记忆和设置;同时最多可运行 5 个实例(已安装版加便携版)。
我可以为 Coo 添加新功能吗?可以,扩展页面可以安装「Worlds」,例如 QQ 机器人、绘画室和一些小游戏,每个扩展的更新日志都在发布页面中。
Coo 在「使用电脑」时到底会做什么?它可以代你点击按钮、输入文字和切换窗口,但每次行动前都会先征求你的同意;活动气泡会显示它当前正在做什么(阅读、搜索、写作或使用电脑)。
大小
44.3 MB
星标
3.3K
时长
1个月
提交 · 90 天