codewhale-hq / Codewhale

codewhale-hq/Codewhale

open_in_new前往仓库

开源、社区驱动的智能体工具集

项目概览

项目概述

CodeWhale 是一个开源的、社区驱动的终端编码智能体（coding agent）工具，使用 Rust 编写，采用 MIT 许可证。它最初为 DeepSeek 模型提供原生体验，现已发展为一个支持多种模型和提供商的通用编码工具。CodeWhale 允许用户自带模型（BYOM），支持托管或本地模型，并强调开源模型优先，不偏向任何特定提供商。它运行在用户自己的机器上，提供交互式 TUI 和命令行执行模式。

核心功能

  • 多模型、多提供商支持：支持 DeepSeek、Claude、GPT、Kimi、GLM 等 30+ 提供商，以及本地 vLLM、SGLang、Ollama 等，无需 API 密钥。
  • 角色化模型编排（Fleet）：用户可以为不同角色（如规划者、执行者、审查者）指定不同的模型和提供商，实现混合模型工作流。
  • 可定制的智能体框架：角色定义、宪法（constitution）等均为可编辑文件，用户可自定义智能体行为。
  • 安全与权限控制：提供 Plan/Act/Operate 模式，支持审批策略、沙箱（macOS Seatbelt、Linux bubblewrap）、仓库法律（repo law）等安全机制。
  • 持久化与恢复：支持会话快照、任务队列、Fleet 账本（ledger），可恢复中断的工作。
  • 丰富的工具集：内置 shell、文件操作、Git、GitHub、MCP、技能（skills）、钩子（hooks）等工具。
  • TUI 与 CLI：提供交互式终端界面和 codewhale exec 命令行模式，支持脚本和 CI 集成。
  • 可访问性：提供低动态、ASCII 安全模式等辅助功能。

适用与不适用场景

适用场景：

  • 需要在终端中进行代码编写、修改、测试等开发任务的开发者。
  • 希望使用多种 LLM 提供商（包括本地模型）的用户。
  • 需要自动化编码任务、CI/CD 集成的团队。
  • 需要可定制、可审计的智能体行为的用户。

不适用场景：

  • 需要图形化 IDE 完整体验的用户（CodeWhale 是终端工具）。
  • 需要托管云服务的用户（CodeWhale 是本地优先）。
  • 需要非编码类任务（如文档撰写）的用户（虽然可通过覆盖基础提示词扩展，但主要面向编码）。
  • 需要 Windows 沙箱完整支持的用户（Windows 沙箱支持有限）。

技术架构与依赖

  • 语言：Rust（edition 2024）
  • 许可证：MIT
  • 主要依赖：
    • ratatui：TUI 渲染
    • clap：命令行参数解析
    • tokio：异步运行时
    • serde：序列化
    • sqlite：状态持久化
    • quickjs：Workflow 脚本引擎
    • portable-pty：PTY 支持
    • ratatui、crossterm 等
  • 架构：Cargo workspace，包含多个 crate，如 tui、cli、core、config、state、tools、mcp、hooks、execpolicy、agent 等。

安装与快速开始

安装方式：

  • npm：npm install -g codewhale
  • Cargo：cargo install codewhale-cli codewhale-tui（需要 Rust 工具链）
  • Docker：docker pull ghcr.io/hmbown/codewhale:latest
  • 预编译二进制：从 GitHub Releases 下载
  • 其他：Nix、Scoop、Android/Termux 等，详见官方文档。

快速开始：

# 设置提供商（例如 DeepSeek）
codewhale auth set --provider deepseek

# 启动 TUI
codewhale

# 无头模式执行任务
codewhale exec "修复失败的测试"

# 启动本地 Web 客户端
codewhale web

典型使用方法

TUI 交互：

  • /model：切换提供商和模型
  • /fleet：构建和运行团队（角色化模型编排）
  • /undo：撤销上一轮操作
  • /restore <N>：回滚工作区到之前的快照
  • Tab：在 Plan/Act/Operate 模式间切换（空输入时）或补全命令（有输入时）
  • Shift+Tab：切换权限姿态（Ask/Auto-Review/Full Access）
  • !：通过审批路径运行 shell 命令

CLI 示例：

# 运行任务并输出 JSON 事件流
codewhale exec --output-format stream-json "分析代码库"

# 使用 Fleet 运行多任务
codewhale fleet run tasks.json --max-workers 4

# 查看 Fleet 状态
codewhale fleet status

配置示例：

# ~/.codewhale/config.toml
provider = "deepseek"
default_text_model = "deepseek-v4-pro"

[providers.deepseek]
api_key = "YOUR_API_KEY"

配置与部署要点

  • 配置文件：~/.codewhale/config.toml（主配置）、~/.codewhale/settings.toml（UI 偏好）、~/.codewhale/mcp.json（MCP 服务器）、~/.codewhale/constitution.json（用户宪法）等。
  • 环境变量：支持 CODEWHALE_* 和 DEEPSEEK_* 系列变量，如 CODEWHALE_PROVIDER、CODEWHALE_MODEL、CODEWHALE_API_KEY 等。
  • 项目覆盖：<workspace>/.codewhale/config.toml 可覆盖部分配置，但只能收紧安全策略。
  • 部署：支持 Docker、Kubernetes（通过 Docker 镜像）、CI/CD 集成（codewhale exec）。
  • 安全：支持审批策略、沙箱、仓库法律、权限规则（permissions.toml）等。
  • 更新：支持自动更新检查，可通过 codewhale update 更新。

限制、风险与许可证

  • 许可证：MIT，独立社区项目，与任何模型提供商无关。
  • 限制：
    • Windows 沙箱支持有限（无 OS 级命令沙箱）。
    • 部分功能（如 Workflow）仍处于预览阶段。
    • 依赖第三方模型提供商的服务可用性。
  • 风险：
    • 使用 API 密钥需注意安全，避免泄露。
    • 沙箱并非绝对安全，用户需谨慎授权。
    • 项目仍在快速发展，API 可能变化。

官方链接

信息来源和分析时间

  • 信息来源：GitHub 仓库 README、文档（docs/ 目录）、CONTRIBUTING.md 等。
  • 分析时间：2026-08-08（基于最新发布版本 v0.9.5）。