CowAgent

What It Does

CowAgent is an open-source super-agent harness written in Python (73,414 lines across 293 files). Formerly named chatgpt-on-wechat, it was rebranded and rebuilt in February 2026 (v2.0.0) into a full agent platform. Messages arrive through 18 channel integrations (Web console, WeChat, Telegram, Slack, Discord, Feishu, DingTalk, WeCom, QQ, and more), pass through an Agent Core that plans multi-step tasks over memory and knowledge, and execute via 15 built-in tools (bash, read, write, edit, browser, scheduler, web search, vision, MCP, and others) plus any installed skills. The agent supports 21 LLM providers (Claude, OpenAI, Gemini, DeepSeek, Qwen, GLM, Kimi, MiniMax, Doubao, and more), a three-tier memory system with nightly distillation, a self-curating knowledge wiki, and a self-evolution engine that reviews idle conversations to improve skills. The target users are developers and teams who want a self-hosted, always-on agent assistant running on a personal computer or server, accessible across the web and IM platforms.

The Good

The skill system is well-architected with clean separation of concerns, and it is cross-compatible with the OpenClaw ecosystem. The skill runtime lives in agent/skills/ across 8 focused modules: loader.py (recursive discovery with builtin and custom precedence), manager.py (lifecycle, config persistence to skills_config.json), service.py (CRUD with network-aware install), frontmatter.py (YAML parsing with PyYAML and a fallback parser), config.py (requirement resolution), formatter.py (XML prompt generation), and types.py (7 dataclasses). The frontmatter parser defines _KNOWN_METADATA_NAMESPACES = {"cowagent", "openclaw"} and unwraps either namespace, so a SKILL.md written with metadata: {openclaw: {...}} works identically to one with metadata: {cowagent: {...}}. This means skills written for the OpenClaw or Hermes ecosystem can be installed into CowAgent without modification. The skill prompt is injected in the standard XML format with , , , and fields, matching the format Hermes, Claude Code, and other SKILL.md-compatible agents use.

The self-evolution engine is conservative, reversible, and production-conscious. The evolution executor (agent/evolution/executor.py) runs an isolated agent with a restricted toolset (only read, write, edit, ls, bash, memory_search, memory_get) over idle conversation transcripts. Before any change, it creates a backup snapshot of MEMORY.md, daily memory, and editable skills. Most runs return [SILENT] and change nothing, by design. When it does act, it records the change to an evolution log and injects an [EVOLUTION] note into the user session so the main agent can undo it. Built-in skills are explicitly protected: _builtin_skill_names() enumerates the project-root skills/ directory, and the evolution agent is blocked from editing those names even if a copy exists in the workspace. Concurrency is capped at 2 simultaneous passes. The trigger (agent/evolution/trigger.py) fires on either accumulated user turns or context-pressure (80 percent of the token budget), not just idle time. This is a more carefully designed self-modification system than most agent harnesses have.

The security test suite is real, specific, and all tests pass. The repo ships 31 security tests across 4 files covering SSRF protection for web fetch, browser navigation, vision URL validation, and skill service path traversal. The path traversal tests (test_security_ssrf_path_traversal.py::TestSkillServicePathTraversal) verify that the _safe_skill_dir() method in service.py rejects ../ sequences, absolute paths, backslash paths, nested traversal, and whitespace-only names. The SSRF tests verify that loopback addresses, RFC 1918 private ranges, IPv6 loopback, link-local addresses, and cloud metadata endpoints (169.254.169.254) are blocked for web fetches, vision URL loading, and browser navigation. All 31 passed. The web console uses HMAC-signed stateless auth tokens (_create_auth_token and _verify_auth_token in web_channel.py) that survive server restarts and invalidate when the password changes.

The image-generation skill is a real, non-trivial multi-provider script. The skills/image-generation/scripts/generate.py file is 600-plus lines implementing an abstract ImageProvider base class with six concrete providers: OpenAI (gpt-image-2), Gemini (Nano Banana family with alias expansion), Seedream (Volcengine Ark), Qwen (DashScope), MiniMax (image-01), and LinkAI (universal proxy). Each provider handles generation and image-to-image editing, with provider-specific API formats, size and aspect-ratio resolution tables, image compression via Pillow, and graceful error messages. The factory (_build_providers) tries providers in priority order based on which API keys are configured, promotes the native provider when a specific model is requested, and falls back to automatic routing when the preferred provider has no key. This is the kind of bundled executable skill that most agent frameworks describe but do not ship.

The MCP integration is dependency-free and supports three transports. The agent/tools/mcp/mcp_client.py implements JSON-RPC 2.0 over stdio, SSE, and Streamable HTTP without any external MCP SDK. It handles per-server timeouts, session management for Streamable HTTP, and concurrent calls. The on-demand tool retrieval system (agent/tools/mcp/tool_retrieval.py) uses vector similarity to select which MCP tools to inject into a given LLM turn, with a union-only-grows invariant so a tool that produced a tool_use in message history can never disappear from the schema mid-run (which would cause model errors). The 17 retrieval tests all pass, covering query building, cosine similarity, top-k selection, dimension mismatch fallback, and degradation behavior.

The Bad

Only 3 skills ship in the box, and the marketplace ecosystem is small. The skills/ directory contains knowledge-wiki, image-generation, and skill-creator. The Skill Hub marketplace (at skills.cowagent.ai, open-sourced at github.com/zhayujie/cow-skill-hub) has 37 stars and 2 forks as of this review. For comparison, DeerFlow ships 28 built-in skills, Anthropic's skill pack ships dozens, and the CowAgent README's own skill-creator SKILL.md is adapted from Anthropic's original. A user installing CowAgent for its skill system will find a capable runtime but a thin starting catalog, and will need to author or install skills from external sources to get value beyond the three defaults.

This is a full-stack application descended from a WeChat bot, and the heritage shows. The config.py file is 37,839 bytes (1,000-plus lines) of configuration logic, and config-template.json mixes model API keys, channel credentials, voice settings, agent parameters, and skill retrieval settings in a single flat JSON. The channel/ directory has 18 subdirectories for IM platforms, most of which are Chinese ecosystems (WeChat, Feishu, DingTalk, WeCom, QQ, WeChat Official Accounts, WeChat Customer Service) that require platform-specific registration and credentials non-Chinese users will not have. The web channel (channel/web/web_channel.py) is over 16,000 bytes of HTTP handler code. While the agent core, skills, tools, memory, and evolution systems are cleanly separated under agent/, the channel and configuration layers carry the weight of the project's chatgpt-on-wechat origin. A developer who wants only the skill system still inherits the entire stack.

There is no skill security scanner, which is a gap given the install-from-URL surface. The SkillService.add() method downloads skill files from arbitrary URLs (type "url") or zip archives (type "package") and extracts them to the workspace. While _safe_skill_dir() prevents path traversal in the skill name, there is no equivalent of DeerFlow's SkillScan scanner that inspects skill contents for prompt injection phrases, executable binaries, or sensitive file patterns before installation. The zip extraction in _add_package() uses zf.extractall() without checking for zip-slip (path traversal inside the archive), though the subsequent shutil.copytree to the validated skill_dir mitigates this partially. A malicious skill installed from an untrusted source could execute arbitrary code through the bash tool, which the evolution agent also has access to (though it is confined to the workspace by a bash guard).

8 of 222 tests fail on a clean clone because optional dependencies are not isolated. The dashscope provider tests fail because models/dashscope/dashscope_bot.py does import dashscope at module level, and the test patches a module attribute that fails to load when the SDK is missing. The qianfan provider tests fail because they assert on Chinese localization strings and model names that have changed between test authoring and the current code. The web fetch SSRF tests fail because web_fetch.py uses requests.Response as a type annotation at class-definition time, and the test environment has a stub requests module. These are not fundamental defects (the security logic itself is correct and tested), but a developer running pytest on a fresh clone sees 8 red items before seeing green, which undermines confidence in the test suite.

Skills cannot be exercised in isolation without the full agent stack running. Unlike a Claude Code skill (which is a self-contained SKILL.md the model reads) or a standalone MCP server (which speaks the protocol directly), CowAgent skills are loaded by the SkillManager at agent startup and injected into the system prompt. To verify a skill works, you need a running agent with a configured LLM provider, a web console or channel connection, and the skill's required API keys. There is no cow skill test or dry-run mode. The quick_validate.py script checks frontmatter format but cannot verify runtime behavior. This is inherent to the architecture (skills are prompt augmentations executed by the agent's tools), but it raises the barrier for skill authors compared to systems with isolated skill testing.

Smoke Test Results

Tested on a macOS host (aarch64) with Python 3.12.13. The repo was shallow-cloned to 12MB. Dependencies were installed via pip (PyYAML, requests, pytest). The full test suite was run, plus targeted security and skill tests.

Run A. Fresh clone, full test suite

$ git clone --depth 1 https://github.com/zhayujie/CowAgent.git cowagent-review
Cloning into 'cowagent-review'... (12MB)

$ pip install -r requirements.txt
$ python3 -m pytest tests/ -v --tb=line

tests/test_security_ssrf_path_traversal.py::TestSkillServicePathTraversal::test_dotdot_traversal_blocked PASSED
tests/test_security_ssrf_path_traversal.py::TestSkillServicePathTraversal::test_absolute_path_blocked PASSED
tests/test_security_ssrf_path_traversal.py::TestSkillServicePathTraversal::test_backslash_path_blocked PASSED
tests/test_security_ssrf_path_traversal.py::TestVisionSSRFValidation::test_loopback_ipv4_blocked PASSED
tests/test_security_ssrf_path_traversal.py::TestVisionSSRFValidation::test_private_10_network_blocked PASSED
tests/test_security_ssrf_path_traversal.py::TestVisionSSRFValidation::test_cloud_metadata_blocked PASSED
... (200 more)
tests/test_mcp_tool_retrieval.py::TestSelectMcpTools::test_union_only_grows_across_turns PASSED

211 passed, 8 failed, 3 skipped in 10.20s PASS (with caveats)

Pass rate: 211 of 222. The 8 failures are all caused by missing optional dependencies (dashscope SDK, qianfan provider data, web.py for the web channel) and are not logic defects. The 3 skipped tests are Windows-specific bash streaming tests. All 31 security tests pass. All 17 MCP tool retrieval tests pass.

Run B. Skill validation and loader

$ for d in skills/*/; do python3 skills/skill-creator/scripts/quick_validate.py "$d"; done
image-generation: Skill is valid!
knowledge-wiki: Skill is valid!
skill-creator: Skill is valid!

$ python3 test_skill_loader.py
Loaded 3 builtin skills:
 - knowledge-wiki: Manage the personal knowledge wiki...
 - image-generation: Generate or edit images from text prompts...
 - skill-creator: Create, install, or update skills...

SkillManager loaded 3 skills
 - knowledge-wiki (source=builtin, enabled=True)
 - image-generation (source=builtin, enabled=True)
 - skill-creator (source=builtin, enabled=True)

Skills prompt length: 1562 chars PASS

Pass rate: 3 of 3. All built-in skills pass format validation. The SkillLoader discovers them recursively, the SkillManager loads them with correct source and enabled state, and the prompt builder generates valid XML in the format.

Run C. Security and MCP retrieval tests (targeted)

$ python3 -m pytest tests/test_security_ssrf_path_traversal.py \
 tests/test_security_ssrf_web_fetch.py tests/test_security_ssrf_browser_navigate.py \
 tests/test_security_read_env_bypass.py tests/test_mcp_tool_retrieval.py \
 tests/test_evolution.py -v

tests/test_security_ssrf_path_traversal.py::TestSkillServicePathTraversal::test_dotdot_traversal_blocked PASSED
tests/test_security_ssrf_path_traversal.py::TestSkillServicePathTraversal::test_nested_dotdot_blocked PASSED
tests/test_security_ssrf_path_traversal.py::TestSkillServicePathTraversal::test_whitespace_only_blocked PASSED
... (30 more)
tests/test_mcp_tool_retrieval.py::TestSelectToolsForInjection::test_builtins_always_injected_and_set_grows PASSED

48 passed, 0 failed in 0.49s PASS

Functional pass rate: 48 of 48 exercised. Every security test (path traversal, SSRF across web fetch, browser, and vision surfaces, env bypass) and every MCP retrieval test passes. The skill validation and loading pipeline works end to end. What could not be exercised: the full agent workflow (multi-step planning, tool execution loops, self-evolution review passes, skill install from Skill Hub or GitHub) requires a running full-stack instance with an LLM provider and API keys.

What the runs tell you

The skill system is verifiable without API keys: the loader, manager, formatter, validator, and all security logic can be tested on any host with Python 3.12. The 211 passing tests cover the security surface (SSRF, path traversal, auth), the MCP tool retrieval logic, the bash streaming, the custom provider configuration, and the evolution test. The limitation is that the headline capabilities (agent planning, tool execution, self-evolution, skill marketplace install) require a running instance with an LLM key, so they stay at "partial" by honest necessity.

Setup Walkthrough

1. Install Python 3.9 or newer (Python 3.12 recommended; Python 3.13 supported with a web.py GitHub fork). On macOS: brew install python@3.12.
2. Use the one-line installer for the quickest path: bash <(curl -fsSL https://cdn.link-ai.tech/code/cow/run.sh). This installs dependencies, generates config.json, and starts the service.
3. Alternatively, install from source: git clone https://github.com/zhayujie/CowAgent.git && cd CowAgent && pip install -r requirements.txt && pip install -e . && cow start.
4. Open http://localhost:9899 to access the web console. Configure an LLM provider (paste an API key for OpenAI, Claude, DeepSeek, or any of the 21 supported providers). The agent will not start processing without at least one configured model.
5. Install the browser automation tool if you need it: cow install-browser. This downloads Playwright for the browser tool.
6. To manage skills: use cow skill list to see installed skills, cow skill install to install from Skill Hub, or /skill install / in the web console to install from GitHub.

Post-install gotcha: if you want the self-evolution engine (enabled by default in config-template.json as "self_evolution_enabled": true), it will run background LLM calls on idle conversations, which consumes tokens. Set it to false if you are cost-sensitive. The config-template.json mixes all settings in one flat file, so finding a specific setting requires searching. The mcp_tool_retrieval_enabled defaults to false, meaning all MCP tools are injected into every turn by default; enable it and set a threshold (default 20) if you have many MCP servers and want on-demand retrieval.

Alternatives

1. bytedance/deer-flow - ByteDance's super-agent harness with 28 built-in skills and a native SkillScan security scanner. Prefer DeerFlow if you want a larger starting skill catalog and deterministic skill security scanning. Prefer CowAgent if you want broader IM channel integration, self-evolution, and OpenClaw namespace compatibility.
2. anthropics/skills - the official Anthropic skill pack that CowAgent's skill-creator is adapted from. Prefer it if you want vendor-neutral skills that drop directly into Claude Code without standing up a full agent platform.
3. DeusData/codebase-memory-mcp - an MCP server for persistent codebase memory. Prefer it if you want memory and context management as a protocol-level tool that works across MCP clients. CowAgent has its own three-tier memory system but it is tightly coupled to the harness.
4. obra/superpowers - the community brainstorming and methodology skill pack at 251,255 stars. Prefer it if you want lightweight, drop-in skills for creative and planning workflows without the infrastructure overhead of a full-stack agent runtime.