Hmbown/CodeWhale：开源、社区驱动的 Agent Harness

一款面向终端的开源编程 Agent——自带模型即可使用。

Codewhale 最初是为 DeepSeek 打造的原生体验。此后，它已成长为一个由社区驱动的项目：一套面向日益壮大的国际社区的编程 Harness，支持尽可能多的模型与提供商——优先支持开放模型，无论托管还是本地模型，均不享有高于其他模型的特权。

只需提供一个提供商、一个模型和一项任务。它会读取你的代码、编辑文件、运行命令并检查自己的工作；任务完成或需要你的协助时便会停止。可通过 /model 在任务执行过程中切换模型。你可以在 TUI 中交互式工作，也可以在脚本和 CI 中运行 codewhale exec。它使用 Rust 编写，采用 MIT 许可证，并运行在你的机器上。

与其他 Harness 不同之处在于：你可以为每个角色选择模型，而且它们不必相同。 Fleet 会为每个角色固定指定提供商、模型和推理等级——因此，一个低成本的快速模型可以指挥一个昂贵的推理模型，或者 GLM 构建者可以与 Kimi 审阅者协作完成同一任务。你可以编写自己的角色、自己的宪章（constitution）；Harness 归你所有，而非归我们所有。

我们始终欢迎贡献者，并持续寻找改进方式。如果你使用的模型或提供商尚未被支持，或者有功能出现故障，告诉我们会是你能提供的最有价值帮助之一——请参阅 Contributing。

简体中文 · 日本語 · Tiếng Việt · Bahasa Indonesia · 한국어 · Español · Português · Русский · Українська · codewhale.net · 文档 · 更新日志 · Discord

Cargo、Docker、Nix、Scoop、预构建归档包、Android/Termux，以及面向无法访问 GitHub 用户的 CNB 镜像，均已在 docs/INSTALL.md 中覆盖。你是从 deepseek-tui 迁移而来？配置和会话均可延续——请参阅 docs/REBRAND.md。

codewhale auth set --provider deepseek   # 或 export ANTHROPIC_API_KEY 等
codewhale                                # 打开 TUI
codewhale exec "fix the failing test"    # 无头模式
codewhale web                            # 127.0.0.1 上的本地浏览器客户端

在 TUI 中：/model 会同时切换提供商和模型；/fleet 可构建并运行团队——每次处理一个角色，每个角色使用各自的模型；/undo 会撤销上一轮操作；/restore <N> 可将工作区回滚到更早的快照（不带参数的 /restore 会列出快照）。当输入框为空时，Tab 可在 Plan / Work / Operate 之间切换；当其中有文本时，Tab 则用于补全斜杠命令和 @ 提及。Shift+Tab 可随时在 Ask / Auto-Review / Full Access 权限模式之间切换。! 会通过常规审批流程运行 Shell 命令。

• 任意模型、任意提供商——以及它们的任意组合。 通过一套运行时和一套工具集，即可使用 DeepSeek、Claude、GPT、Kimi、GLM 与 30 多家提供商，以及无需密钥即可使用的自有 vLLM、SGLang 或 Ollama。目录会跟踪每个提供商当前可用的模型阵容——DeepSeek 的 V4 Pro 后端（标注为 DeepSeek-V4-Pro-0813）仍可通过 deepseek-v4-pro 调用，Grok 4.6 是直接使用的 xAI 默认模型，OrcaRouter 则经由 orcarouter/auto 路由。已保存的角色会明确记录其 provider、model 和推理等级，因此一个 Fleet 可在单次运行中跨越多个厂商，角色的路由也不会依赖当前恰好处于激活状态的提供商。上下文限制和价格均来自实际路由；未知价格会显示为未知，而不会显示为 $0。

• 由你编写的 Harness。 角色是可读取、可编辑的文件——每个角色包含模型、工具权限策略和常驻指令——可以保存在项目中以便团队共享，也可以与其他个人设置放在一起，从而随你在不同代码仓库之间迁移。宪章会记录你希望 Agent 在每次会话中遵守的行为方式，因此 Harness 会匹配你的工作实践，而非我们的。

• 在你允许前保持只读。 Plan 模式无法更改文件，风险命令受到审批机制约束。当操作系统沙箱实际包裹某项命令时，Codewhale 会明确提示：macOS 在可用情况下使用 Seatbelt，Linux 则可选择启用 bubblewrap。仓库中的 constitution.json 会被编译为写入限制，即使 Full Access 也无法绕过。

• 可恢复的工作。 Fleet 会将每一步记录到仅追加的账本中，因此 fleet resume 可以从你上次中断的位置继续。

• DeepSeek Harness（dsh）——通过 Codewhale 连接。 codewhale integrations dsh connect 会将现有的 @deepseek-ai/dsh 安装连接到你的 Codewhale 提供商路由、权限和工作区；integrations dsh install-bundle 则会添加可选安装的 DSH 插件包，使 dsh --profile codewhale 能够独立携带该身份。Codewhale 掌管权限和生命周期控制权；dsh 的会话、配置文件和凭据则保持不变。请参阅 docs/INTEGRATIONS_DSH.md。

• VS Code。 官方扩展脚手架（extensions/vscode）可在集成终端中打开 Codewhale，并通过本地运行时提供只读的 Agent View。它目前是本地开发预览版本，尚未发布至扩展市场。

• docs/PROVIDERS.md ——所有提供商路由：托管、网关和本地

• docs/FLEET.md ——Fleet、账本与恢复

• docs/WORKFLOW_EXPERIMENTAL_SEARCH.md ——Workflow 内已冻结、与提供商无关的实验性搜索

• docs/CONFIGURATION.md ——config.toml、钩子和宪章

• docs/AUTHORIZATION_ORDER.md ——模式、钩子、权限规则、安全底线、仓库规则、审批和沙箱如何组合

• docs/HOOKS.md ——11 个 TUI 生命周期钩子事件、其载荷，以及其中可引导一轮操作的 3 个事件（codewhale exec 和 CLI 子命令不会触发钩子）

• docs/WEB.md ——仅限回环地址访问的浏览器客户端及其一次性认证边界

其他所有内容——模式、快捷键、沙箱细节、MCP、运行时 API 和架构——均位于 docs 和 codewhale.net。

Issue、PR、复现步骤、日志和功能请求都是实实在在的项目工作，欢迎首次贡献。当某个 PR 无法按原样合并时，维护者会提取其中可用的部分，并持续为作者保留署名——体现在提交记录、更新日志和 docs/CONTRIBUTORS.md 中。

感谢 DeepSeek 提供的模型和支持，它们促成了项目的起步；感谢 DataWhale 🐋 欢迎我们加入鲸鱼兄弟大家庭；也感谢 OpenWarp 和 Open Design 在终端 Agent 体验方面的协作。

MIT。这是一个独立的社区项目，与任何模型提供商均无关联。

An open source coding agent for your terminal — bring your own model.

Codewhale started as a native experience for DeepSeek. It has since grown into a community-driven project: one coding harness that fits a growing international community and supports as many models and providers as possible — open models first, hosted or local, none privileged over the rest.

Give it a provider, a model, and a task. It reads your code, edits files, runs commands, and checks its own work, then stops when the job is done or it needs you. Switch models mid-task with /model. Work interactively in the TUI, or run codewhale exec in scripts and CI. It's written in Rust, licensed MIT, and runs on your machine.

The part that isn't like other harnesses: you pick the model for each role, and they don't have to match. A fleet pins a provider, a model, and a reasoning tier per role — so a cheap fast model can direct an expensive reasoning one, or a GLM builder can work the same job as a Kimi reviewer. Write your own roles, your own constitution, and the harness is yours rather than ours.

We're always looking for contributors and ways to improve. If a model or provider you use is missing, or something breaks, telling us is one of the most useful things you can do — see Contributing.

简体中文 · 日本語 · Tiếng Việt · Bahasa Indonesia · 한국어 · Español · Português · Русский · Українська · codewhale.net · Docs · Changelog · Discord

Cargo, Docker, Nix, Scoop, prebuilt archives, Android/Termux, and a CNB mirror for anyone who can't reach GitHub are covered in docs/INSTALL.md. Coming from deepseek-tui? Your config and sessions carry over — see docs/REBRAND.md.

codewhale auth set --provider deepseek   # or export ANTHROPIC_API_KEY, etc.
codewhale                                # open the TUI
codewhale exec "fix the failing test"    # headless
codewhale web                            # local browser client on 127.0.0.1

In the TUI: /model switches provider and model together, /fleet builds and runs the team — one role at a time, each with its own model — /undo reverts the last turn, and /restore <N> rolls the workspace back to an earlier snapshot (bare /restore lists them). Tab cycles Plan / Work / Operate when the composer is empty — with text in it, Tab completes slash commands and @ mentions instead. Shift+Tab cycles the Ask / Auto-Review / Full Access permission posture at any time. ! runs a shell command through the normal approval path.

• Any model, any provider — and any mix of them. DeepSeek, Claude, GPT, Kimi, GLM, and 30+ providers, plus your own vLLM, SGLang, or Ollama with no key, all through one runtime and one toolset. The catalog tracks each provider's live lineup — DeepSeek's V4 Pro backend (labeled DeepSeek-V4-Pro-0813) stays callable as deepseek-v4-pro, Grok 4.6 is the direct xAI default, and OrcaRouter routes through orcarouter/auto. A saved role records its provider, model, and reasoning tier explicitly, so a fleet can span vendors in a single run and a role's route never depends on whichever provider happens to be active. Context limits and prices come from the real route, and an unknown price shows as unknown rather than $0.

• A harness you author. Roles are files you can read and edit — a model, a tool posture, and standing instructions per role — kept in the project so the team shares them, or beside your other personal settings so they follow you between repos. A constitution records how you want the agent to behave across every session, so the harness matches your practice instead of ours.

• Read-only until you allow more. Plan mode can't change files, and approvals gate risky commands. When an OS sandbox actually wraps a command, Codewhale says so: Seatbelt on macOS where available, opt-in bubblewrap on Linux. A repo's constitution.json compiles into write holds that even Full Access can't skip.

• Work you can resume. A fleet records every step to an append-only ledger, so fleet resume picks up where you left off.

• DeepSeek Harness (dsh) — connected through Codewhale. codewhale integrations dsh connect links an existing @deepseek-ai/dsh install to your Codewhale provider route, permissions, and workspace, and integrations dsh install-bundle adds the opt-in DSH plugin bundle so dsh --profile codewhale carries that identity on its own. Codewhale owns permissions and lifecycle authority; dsh keeps its own sessions, profiles, and credentials untouched. See docs/INTEGRATIONS_DSH.md.

• VS Code. The official extension scaffold (extensions/vscode) opens Codewhale in an integrated terminal and exposes a read-only Agent View over the local runtime. It is a local-development preview, not a marketplace release yet.

• docs/PROVIDERS.md — every provider route: hosted, gateway, and local

• docs/FLEET.md — fleets, the ledger, and resume

• docs/WORKFLOW_EXPERIMENTAL_SEARCH.md — frozen, provider-neutral experimental search within Workflow

• docs/CONFIGURATION.md — config.toml, hooks, and the constitution

• docs/AUTHORIZATION_ORDER.md — how modes, hooks, permission rules, safety floors, repo law, approvals, and sandboxing compose

• docs/HOOKS.md — the eleven TUI lifecycle hook events, their payloads, and which three of them can steer a turn (codewhale exec and the CLI subcommands do not fire hooks)

• docs/WEB.md — the loopback-only browser client and its one-time authentication boundary

Everything else — modes, keybindings, sandbox details, MCP, the runtime API, and architecture — lives in docs and on codewhale.net.

Issues, PRs, repro steps, logs, and feature requests are all real project work, and first contributions are welcome. When a PR can't merge as-is, maintainers harvest what works and keep the author credited — in the commit, the changelog, and docs/CONTRIBUTORS.md.

Thanks to DeepSeek for the models and support that started the project, DataWhale 🐋 for welcoming us into the Whale Brother family, and OpenWarp and Open Design for collaborating on the terminal-agent experience.

MIT. An independent community project, not affiliated with any model provider.