AI News
开源项目 GitHub Topic ai-agent 2026-10-05T12:02 正文 ok 768 words

Codewhale：用 Rust 构建的开源终端编程 Agent

英文标题：📦 codewhale-hq/Codewhale

Codewhale 是一款开源终端编程 Agent，基于 Rust 构建，支持交互式终端、脚本/CI 无头执行、本地 Web 客户端和 PR 审查等使用方式。它内置 40 多种模型提供商接入，兼容 OpenAI API，并可通过 Ollama、vLLM 或 SGLang 使用本地模型。该项目提供计划、工作和操作等模式，以及审批、沙箱、变更恢复和请求预览机制，以提升 Agent 执行任务时的可控性与安全性。开发者还可通过 MCP、技能、插件、Hooks、子 Agent、Agent 团队和工作流扩展其能力。
打开原文相关 7.7 · 机会 6
media5.6 KB media5.6 KB media2.2 KB media1.3 KB media1.2 KB media1.2 KB media3.1 KB media35.5 KB media72.0 KB

中文

macOS 和 Linux：

curl -fsSL https://codewhale.net/install.sh | sh

安装程序会将已验证校验和的二进制文件下载至 ~/.local/bin。如果此后运行 codewhale 提示“找不到命令”，请执行安装程序输出的那一行 PATH 配置命令，或参阅将其加入 PATH。可随时通过 codewhale update 升级。

Windows、npm、Cargo 及其他安装方式

winget install HunterBown.CodeWhale  # Windows x64（也可使用 Scoop，或 GitHub Releases 中的安装程序）
npm install -g codewhale            # 封装相同的发布版二进制文件
cargo install codewhale-cli --locked  # 从 crates.io 构建

Docker、Nix、Linux 上的 Homebrew、Android/Termux、带校验和验证的手动下载，以及可选的 CNB 镜像，均在安装指南中说明。请选择一种安装方式：同一台机器上多种安装方式会争夺 PATH。

  1. 打开你的项目。 在希望处理的文件夹中运行 codewhale。
  2. 连接模型。 运行 /provider（或按 F3）添加托管模型密钥，或选择本地运行时。如果 Ollama 已在运行聊天模型，Codewhale 会自动切换至该模型。使用 /model 切换模型。
  3. 给出明确任务。
Fix the failing tests and explain what changed.

同一任务也可以从脚本或 CI 作业中以无头方式运行：

codewhale exec "fix the failing tests and explain what changed"

运行 /help 查看命令和键盘快捷键。

每个客户端都由同一个本地 Codewhale Engine 驱动，因此会话、工具和权限在各处的行为保持一致。

命令 功能
codewhale 交互式终端界面
codewhale exec "…" 从脚本或 CI 执行一次无头交互，并流式输出 JSON
codewhale web 运行于 127.0.0.1 的内置本地浏览器客户端
codewhale review --pr N 提供建议的 pull request 审查；发布审查结果需显式选择启用
Runtime API 用于线程、事件和审批的本地 HTTP API

原生桌面应用（GPUI）正在作为登录后的产品客户端开发；可在产品页面查看可用性。由社区维护的 VS Code 扩展 可通过侧边栏连接同一个 Engine（源代码）。

  • 支持任意模型，无供应商锁定。 内置超过 40 种提供商接入方式，包括 Anthropic、DeepSeek、Google、Mistral、Moonshot、OpenAI、OpenRouter、xAI 等；还支持任何兼容 OpenAI 的端点，以及通过 Ollama、vLLM 或 SGLang 运行的本地模型。提供商
  • 控制权始终在你手中。 Plan 模式只进行探索而不做改动；Work 和 Operate 模式会执行改动。审批姿态决定工具调用何时需要你的确认；/undo 和 /restore 可恢复工作区改动，/receipts 则列出会话中的每个文件、命令和审批记录。模式 · 回执
  • 为长时间任务而构建。 设置持久化 /goal，将边界明确的工作委派给子 Agent，以预支出检查方式运行受监督的 Agent 团队，或将其编写为可提交到代码库的工作流。
  • 扩展你现有的工具。 连接 MCP 服务器，安装技能和插件，在会话和工具事件中运行 Hooks，并加载已有的 Claude Code 插件。
  • Computer Use。 内置插件增加了观察和操作其他应用程序的工具。使用前请审查其访问权限并启用该插件。指南

| 选择方式 | 选项
---|---|---
模式 —— Agent 正在执行的工作 | Tab 或 /mode | Plan（探索，不作改动）· Work（编辑并运行）· Operate（通过已规划且经过验证的步骤推进目标）
姿态 —— 何时先征求确认 | Shift+Tab | Ask · Auto-Review · Full Access

Full Access 仍会遵守硬性策略边界。模式与权限指南解释了每种选项。

Codewhale 在你的机器上运行，并仅获得你授予它的访问权限。审批姿态和代码库规则会限制 Agent 可执行的操作；在操作系统支持时，命令会在 OS 沙箱中运行（macOS 使用 Seatbelt；Linux 上的 bubblewrap 需选择启用）。/preview-request 会在发送任何内容之前显示精确的脱敏请求。未知的模型价格会保持未知，而不会被标记为免费。

参阅授权顺序、沙箱机制和遥测——使用计数默认开启，可通过 codewhale config set telemetry false 关闭。

社区

欢迎提交 Bug 报告、功能建议和 pull request——无论你已使用 Codewhale 数月，还是首次尝试。如果缺少某个提供商，或某项工作流使用不便，请创建 issue或提交 pull request。欢迎首次贡献，贡献者将保留其合入工作的署名。代码库结构是不错的起点。

加入 Discord，或在微信添加 Hunter（hunterbown），申请加入 Whale Brothers 群。

Codewhale 起源于 deepseek-tui，目前仍可读取该项目的配置和会话。它现已实现提供商中立并由独立团队维护，且与任何模型提供商均无关联。感谢每一位贡献者，以及帮助其成长的开源社区。

MIT。改编自其他开源项目的部分内容记录于第三方声明。

English / 原文

macOS and Linux:

curl -fsSL https://codewhale.net/install.sh | sh

The installer downloads checksum-verified binaries into ~/.local/bin. If codewhale then says "command not found", run the one PATH line the installer prints, or see Put it on your PATH. Upgrade any time with codewhale update.

Windows, npm, Cargo, and other routes

winget install HunterBown.CodeWhale  # Windows x64 (or Scoop, or the installer from GitHub Releases)
npm install -g codewhale            # wraps the same release binaries
cargo install codewhale-cli --locked  # build from crates.io

Docker, Nix, Homebrew on Linux, Android/Termux, manual downloads with checksum verification, and the optional CNB mirror are covered in the installation guide. Pick one route: several installs on one machine end up fighting over PATH.

  1. Open your project. Run codewhale in the folder you want to work on.
  2. Connect a model. Run /provider (or press F3) to add a hosted key or pick a local runtime. If Ollama is already running with a chat model, Codewhale switches to it on its own. Use /model to change models.
  3. Give it a concrete task.
Fix the failing tests and explain what changed.

The same task runs headless from a script or CI job:

codewhale exec "fix the failing tests and explain what changed"

Run /help for commands and keyboard shortcuts.

Every client drives the same local Codewhale Engine, so sessions, tools, and permissions behave the same everywhere.

Command What it does
codewhale The interactive terminal interface
codewhale exec "…" One headless turn from a script or CI, streaming JSON
codewhale web The bundled local browser client on 127.0.0.1
codewhale review --pr N An advisory pull request review; posting is opt-in
Runtime API A local HTTP API for threads, events, and approvals

A native desktop app (GPUI) is being built as the signed-in product client; see the product page for availability. The community-maintained VS Code extension connects to the same Engine from a sidebar (source).

  • Any model, no lock-in. Over 40 built-in provider routes — Anthropic, DeepSeek, Google, Mistral, Moonshot, OpenAI, OpenRouter, xAI and more — plus any OpenAI-compatible endpoint and local models through Ollama, vLLM, or SGLang. Providers
  • You stay in control. Plan mode explores without changing anything; Work and Operate make changes. Approval postures decide when a tool call needs your OK, /undo and /restore recover workspace changes, and /receipts lists every file, command, and approval in a session. Modes · Receipts
  • Built for long jobs. Set a durable /goal, delegate bounded work to sub-agents, run supervised agent teams with a pre-spend check, or script them as checked-in workflows.
  • Extend what you already use. Connect MCP servers, install skills and plugins, run hooks on session and tool events, and load existing Claude Code plugins.
  • Computer Use. An included plugin adds tools for observing and operating other applications. Review its access and enable it before use. Guide

| Choose with | Options
---|---|---
Mode — what the agent is doing | Tab or /mode | Plan (explore, no changes) · Work (edit and run) · Operate (drive a goal through planned, verified steps)
Posture — when it asks first | Shift+Tab | Ask · Auto-Review · Full Access

Full Access still respects hard policy boundaries. The modes and permissions guide explains each option.

Codewhale runs on your machine with the access you grant it. Approval postures and repository rules limit what the agent may do, and commands run inside an OS sandbox where supported (Seatbelt on macOS; bubblewrap on Linux is opt-in). /preview-request shows the exact redacted request before anything is sent. Unknown model prices stay unknown instead of being reported as free.

See authorization order, sandboxing, and telemetry — usage counts are on by default and codewhale config set telemetry false turns them off.

Community

Bug reports, feature ideas, and pull requests are welcome — whether you have used Codewhale for months or are trying it for the first time. If a provider is missing or a workflow is awkward, open an issue or send a pull request. First contributions are welcome, and contributors keep credit for the work that lands. The repository layout is a good place to start.

Join the Discord, or add Hunter on WeChat (hunterbown) and ask to join the Whale Brothers group.

Codewhale began as deepseek-tui and still reads that project's configuration and sessions. It is now provider-neutral and independently maintained, and is not affiliated with any model provider. Thanks to every contributor and to the open-source communities that helped it grow.

MIT. Portions adapted from other open-source projects are recorded in third-party notices.