codewhale-hq/Codewhale

在终端中运行、可搭配任意模型的开源编程智能体。

给 Codewhale 一个任务，它会读取仓库、编辑文件、运行命令，直到任务完成或需要你提供输入为止。 它支持超过 40 个内置提供商（默认使用 DeepSeek V4.1 Flash），也支持在你自己机器上运行的模型。 /receipts 会列出它修改过的文件、运行过的命令，以及它发起的 Web 和 MCP 调用。

官网 · 文档 · 更新日志 · 参与贡献

English · 日本語 · Tiếng Việt · Bahasa Indonesia · 한국어 · Español · Português · Русский · Українська · Français · Deutsch · 繁體中文 · हिन्दी · Türkçe · Italiano · Polski · العربية · Català

_{一个使用脚本化测试模型的 0.10.2 开发版本，在一次性工作区中以“完全访问”权限运行。其中的编辑、三个测试和一次子智能体审查都是真实运行的。}

查看 Codewhale × OrcaRouter 优惠. Codewhale 会从 OrcaRouter 获得推荐佣金。

macOS 和 Linux：

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

安装器会把经过校验和验证的 codewhale 及其简短别名 codew 放到 ~/.local/bin。 如果之后 shell 提示 command not found，请运行安装器打印出的那行 PATH 命令 （详情）。使用 codewhale update 升级。这些命令安装的是最新发布版本。 本页跟随 main 更新，因此标注了版本号的功能会在该版本中推出；更新日志列出了每个版本新增的内容。

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  # crates.io; can trail GitHub Releases

1. 先提交或 stash 你的改动，然后在 git 仓库的根目录运行 codewhale。默认情况下， 它会直接在这里应用文件编辑而不询问，并向你展示 diff。
2. 运行 /provider（或按 F3），选择一个提供商，粘贴它的 API 密钥，然后选择模型。 默认提供商是 DeepSeek。没有密钥时，可以改选本地运行时。如果尚未配置任何提供商， 而 Ollama 已经在提供聊天模型，Codewhale 会自动使用它； 从 0.10.2 起，它会在你发送第一条消息时提议使用它。
3. 输入一个任务：

Fix the failing tests and explain what changed.

只读命令会直接运行。其他任何 shell 命令，Codewhale 都会先询问：y 运行这一次， a 在本次对话接下来的时间里允许类似的命令，n 拒绝。/undo 会撤销你的上一个请求及其 文件改动。/help 列出命令和按键。

在脚本和 CI 中，codewhale exec 不启动界面，只运行一个任务。默认情况下，--auto 使用 “完全访问”权限：工具不经询问就运行，shell 命令不受 Codewhale 沙箱限制，信任模式允许 文件工具写入工作区之外的位置。加上 --sandbox workspace-write 可保留 shell 沙箱和 文件工具的工作区限制，并关闭信任模式：

codewhale exec --auto --sandbox workspace-write "fix the failing tests and explain what changed"

全新安装后，默认处于 Work 模式和“询问”权限。

详情见模式与权限指南。

• /pet on 会把你的终端变成一头动画鲸鱼，展示智能体正在做什么，同时消息框仍可正常使用。 它的 980 个粒子会用英文、中文或日文拼出当前步骤。
• /workbar terminal 会实时显示智能体正在运行的 shell。你可以在其中输入， 也可以按 Ctrl+N 打开一个你自己的 shell（macOS 和 Linux）。
• /undo 一步撤销你的整个上一个请求，包括它修改过的每个文件；/diff 也可以在没有 Git 的文件夹中使用。
• 当计划准备就绪时，Codewhale 会询问你是以“询问”还是“自动审核”权限开始 Work，还是继续规划。
• /color 为每个对话设置各自的输入框颜色，并随会话一起保存。
• web_search 可以使用 DeepSeek 新推出的 Search API：在拥有 DeepSeek 密钥的情况下设置 [search] provider = "deepseek"。
• 在“完全访问”之外，会上传凭据的 curl 或 wget 命令未经你批准绝不会运行， 隐藏了不可见 Unicode 字符的命令会被拒绝。write 不再替换智能体尚未读取过的文件， 也不再替换在它读取之后发生过变化的文件。

内置超过 40 个提供商，包括 Anthropic、OpenAI、DeepSeek、Google、Mistral、Moonshot、 OpenRouter 和 xAI。任何兼容 OpenAI 的端点都可以使用，通过 Ollama、vLLM 或 SGLang 运行的本地模型也可以。默认模型是 DeepSeek 的 deepseek-flash，DeepSeek 已于 2026-10-17 将其切换为 DeepSeek-V4.1-Flash-1017；0.10.1 无需更新即可运行它 （详情）。

/model 可在回合之间切换模型，/model auto 会为每个回合挑选一个模型（用 /router 设置挑选方式）。/turn inspect 显示某个回合使用了哪个模型、花费多少以及耗时多久。 codewhale auth chatgpt 让你可以用 ChatGPT 套餐代替 API 密钥（实验性）。 参见提供商。

/receipts（退出后可用 codewhale receipts --last）会列出修改过的文件、运行过的命令、 Web 和 MCP 调用、启动过的智能体、审批及审批人，以及失败记录。/undo 一步撤销你的上一个请求及其修改的文件，无需信任模式。/restore 把整个工作区回滚到更早的快照；由于这会覆盖之后的编辑，它需要 /trust on 或“完全访问”权限。参见回执。

可使用工具的 exec 运行无论采用哪种输出格式都会保存，因此在 exec --auto 之后， 包括使用 --json 时，codewhale receipts --last 都能正常工作。仅作答且使用文本输出或 --json 的运行，只有在恢复对话或开始压缩对话时才会保存；使用 --output-format stream-json 可始终保存这些运行，供回执或 exec --continue 使用。

/goal 设定一个跨回合持续有效的目标。Codewhale 可以把工作拆分给 子智能体，运行由多个智能体组成的 Fleet， 或者按照提交到仓库中的工作流执行。

Codewhale 会自动读取 AGENTS.md。为其他工具编写的指令文件，例如 CLAUDE.md、 .cursorrules 或 .github/copilot-instructions.md，只有在你于配置中设置 project_instruction_imports = ["claude"]（或 "cursor"、"cline"、"windsurf"、 "copilot"、"all"）主动启用后才会加载；参见 config.example.toml。 如果 Codewhale 发现了未加载的此类文件，会给出警告。

/import-claude 会准备一份导入你的 Claude Code 设置和 MCP 服务器的方案，供你审阅。 /plugin install 接受包含技能、命令、智能体配置文件和 MCP 服务器的 Claude Code 插件， 但会拒绝需要钩子或 LSP 服务器的插件（详情）。

连接 MCP 服务器，添加技能和插件， 并在会话和工具事件上运行钩子。代码模式（Code mode，实验性，默认开启） 让模型编写一个 execute_tools 程序来调用多个 MCP 和插件工具；每次调用仍要遵守你的审批规则， 并保留各自的回执。内置的 Computer Use 插件（实验性， 仅限 macOS）可以观察和操作其他应用。在你审阅其访问权限并启用之前，它保持关闭 （指南）。

终端应用、exec、web 和 Runtime API 共用同一个引擎（架构）。 社区维护的 VS Code 扩展 可以从侧边栏连接到它（源码）。 基于 Runtime API 构建的原生桌面应用正在开发中，目前还没有公开下载。

Codewhale 免费，采用 MIT 许可证。使用你自己的 API 密钥时，费用直接付给提供商； 本地模型不需要密钥。价格已知时，底部状态栏和 /cost 会显示一次会话的花费； 价格未知时会显示为未知，而不会显示为免费。

你不需要账号。通过 /provider 添加的密钥会留在你的机器上。

在“询问”和“自动审核”权限下，只要系统提供操作系统沙箱，命令就会在其中运行： macOS 上是 Seatbelt，Linux 上是 bubblewrap（需已安装）。Windows 目前还没有操作系统沙箱， 而“完全访问”会关闭沙箱。在沙箱内，shell 命令无法读取 ~/.ssh、~/.aws 和 .env 文件等凭据存储；从 0.10.2 起，同样的规则也适用于终端会话和更多文件工具。 /preview-request 会显示下一次请求经过脱敏的预览，但不会发送它。

遥测默认开启。它发送汇总计数（版本和平台、会话时长和结果、你使用了哪些内置提供商、 功能和错误计数），并附带一个每 90 天轮换一次的随机安装 ID；它从不包含对话、代码、提示词、 模型名称、文件名或仓库名，也从不包含凭据。运行 codewhale config set telemetry false 即可关闭。启动时，Codewhale 还会 检查 GitHub 上是否有新版本；设置 CODEWHALE_NO_UPDATE_CHECK=1 可跳过这一检查。 更多信息见授权顺序、沙箱和 遥测。

如果缺少某个提供商，或某个工作流用起来不顺手， 请提交 issue或 提交 PR。被合并的工作会保留贡献者的署名； 仓库结构说明了各部分代码所在的位置。

欢迎在 Discord 上交流，或在微信上添加维护者 Hunter （hunterbown），申请加入 Whale Brothers 群。

Codewhale 最初名为 deepseek-tui，至今仍会读取该项目的配置和会话。它是独立维护的项目， 与 DeepSeek 或任何其他模型提供商均无隶属关系。感谢每一位贡献者。

MIT。改编自其他开源项目的代码列在第三方声明中。