CodeWhale 上手：一个终端智能体，跑遍所有模型

这篇文章假设你从来没写过代码，也没打开过”终端”那个黑框框。 读完并跟着做完，你会拥有一个能真正动手的 AI 助手——它直接在你电脑上建文件、改内容、跑命令、看到报错自己修——而且你可以随时换一个更便宜的模型来驱动它。

全文约 50 分钟，动手部分约 25 分钟。建议边读边做。 后半程有 Fleet、Workflow 这类重型功能，第一次读可以先跳过，用熟了再回来。

零、先看一眼全貌

一句话：CodeWhale 是一个装在你电脑终端里的编程智能体，你给它一个”任务”，它自己读文件、改文件、跑命令、验收结果。

它和 Claude Code、Codex 是同一类东西。真正的差别只有一个，但这个差别很大：

• Claude Code 只能用 Anthropic 的模型，Codex 只能用 OpenAI 的模型。
• CodeWhale 谁的模型都能用——DeepSeek、Claude、GPT、Kimi、GLM、Qwen、MiniMax……30 多家，甚至你自己笔记本上跑的本地模型。换模型只要在界面里敲一个 /model。

它是 Rust 写的，MIT 开源，代码在 github.com/Hmbown/CodeWhale，全程跑在你自己的机器上。它的前身叫 deepseek-tui，所以你会在很多地方看到 DeepSeek 的影子——DeepSeek 至今仍是它的默认供应商。

一、先搞懂：它和 ChatGPT 到底差在哪

很多人第一次听说这类工具，反应是”这不就是能写代码的 ChatGPT 吗”。

不是。差别大到需要换一套心智模型。

普通聊天 AI 是”军师”：你描述问题，它给你一段方案或代码，你负责把它搬进现实。中间所有的复制、粘贴、保存、运行、看报错、再回来问——全是你的活。

CodeWhale 是”能动手的实习生”：你把一间办公室（你电脑上的某个文件夹）交给它，它能自己打开文件看、自己改、自己运行、自己看结果对不对、不对就再改。你只需要提需求和验收。

这个差别带来三个后果，先记住：

1. 它需要一个”工作目录”——一个具体的文件夹。它默认只在这个文件夹里活动，看不见也改不了外面的东西。
2. 它会请求权限——“我要改这个文件，可以吗？""我要运行这条命令，可以吗？“这不是啰嗦，这是安全阀。
3. 它跑在终端里——那个黑框框。这是唯一一道门槛，但真的只需要学 5 分钟。

官方文档把这套东西叫 harness（马具/框架）：模型只是发动机，harness 是发动机之外的整辆车——工作目录、工具、权限、会话、记录。同一台发动机装在不同的车上，跑出来的效果天差地别。这也是为什么”能换模型”这件事这么重要：车是好车，发动机你随便挑。

二、为什么值得多装一个 CodeWhale

如果你已经在用 Claude Code 或 Codex，装 CodeWhale 的理由有三个：

2.1 不被单一厂商锁死

Claude Code 涨价了、Codex 限流了、某家模型突然不能用了——这些事在 2025-2026 年发生过不止一次。CodeWhale 把”用哪家模型”变成了一个可以随时换的配置项，而不是一次重新学习工具的成本。

实测本机 codewhale model list 能直接列出的路由包括（节选）：

deepseek-v4-pro (deepseek)          deepseek-v4-flash (deepseek)
gpt-5.6 / gpt-5.5-pro (openai)      deepseek/deepseek-v4-pro (openrouter)
moonshotai/kimi-k2.7-code           z-ai/glm-5.2 (openrouter)
qwen/qwen3.6-plus (openrouter)      minimax/minimax-m3 (openrouter)
GLM-5.2 (zai)                       xiaomi/mimo-v2.5-pro (openrouter)

完整的供应商 ID 有 30 多个：deepseek、openai、anthropic、openrouter、moonshot、zai、minimax、siliconflow、volcengine、qianfan、novita、fireworks、together、deepinfra、huggingface、xai、nvidia-nim、arcee、stepfun、longcat、sakana、meta、atlascloud、wanjie-ark、xiaomi-mimo，以及三个跑在你自己机器上的：ollama、vllm、sglang。

2.2 便宜

这是最实际的理由。用 DeepSeek 或 GLM 驱动同一套 harness，成本通常是 Claude 官方 API 的零头。对于”改改文案、整理文件、写个小脚本”这类日常任务，便宜模型完全够用。

具体价格各家随时在变，本文不写死数字，以各家官网为准。CodeWhale 会在界面底部显示本次会话的花费（cost 状态位），价格未知时它显示”未知”，不会假装是 0。

2.3 能力上限更高

Claude Code 和 Codex 都能开子智能体，但 CodeWhale 把这件事做成了一个叫 Fleet 的持久化系统：一群 worker 并行干活，每一步写进只追加的账本，笔记本合盖了、程序崩了，fleet resume 能从断点继续。这是本文第十四节的内容。

什么时候不该用 CodeWhale？ 如果你已经买了 Claude 或 ChatGPT 的订阅、只做一个项目、对成本不敏感——那 Claude Code / Codex 的开箱体验更顺，没必要折腾。CodeWhale 的价值在”你想控制成本”或”你想控制一切”的时候才显现。

三、准备工作：终端 5 分钟速成

如果你已经会用终端，直接跳到第四节。

3.1 终端是什么

终端就是用打字代替点鼠标的一个窗口。你点”新建文件夹”，等价于在终端里敲 mkdir 文件夹名。仅此而已，没有更玄的东西。

3.2 怎么打开

• macOS：按 Command + 空格，输入 terminal，回车。
• Windows：开始菜单搜 Windows Terminal，打开它。

打开后你会看到类似这样一行，最后有个闪烁的光标：

wangjinlong@MacBook-Pro ~ %

这行叫提示符，~ 表示”我现在在你的用户主目录”。光标处就是你打字的地方。

3.3 只需要记住 4 条命令

3.4 建一个练习用的文件夹

cd ~
mkdir codewhale-练习
cd codewhale-练习
pwd

最后一行会打印出这个文件夹的完整路径。记住它——这就是待会儿要交给 CodeWhale 的”办公室”。

四、安装：四条路，挑一条

4.1 路线 A：官网安装脚本（macOS / Linux，最短）

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

它会下载配套的三个二进制（codewhale、codew、codewhale-tui），用官方校验和文件核对完整性，默认装到 ~/.local/bin。codew 是 codewhale 的短别名，敲着省事。

4.2 路线 B：npm（跨平台，最通用）

前提是电脑里有 Node.js（nodejs.org 下载 LTS 版一路下一步即可）。

npm install -g codewhale

国内下载慢，先换个镜像源：

npm config set registry https://registry.npmmirror.com
npm install -g codewhale

4.3 路线 C：Cargo（从源码编译，最兜底）

GitHub 被墙、或者你的系统架构比较特殊（老版本 Linux ARM64、FreeBSD 等），走这条：

# 需要先装 Rust 1.88+，见 https://rustup.rs
cargo install codewhale-cli --locked
cargo install codewhale-tui --locked

两个包都要装——codewhale-cli 提供的是调度器，真正干活的运行时在 codewhale-tui 里。

4.4 路线 D：Docker（最隔离）

不想让它碰你的真实系统，用容器：

docker volume create codewhale-home
docker run --rm -it \
  -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \
  -v codewhale-home:/home/codewhale/.codewhale \
  -v "$PWD:/workspace" \
  -w /workspace \
  ghcr.io/hmbown/codewhale:latest

4.5 验证装好了

codewhale --version

正常输出长这样：

codewhale (npm wrapper) v0.8.41
binary version: v0.8.41
repo: git+https://github.com/Hmbown/CodeWhale.git

⚠️ 一个容易迷惑的点：codewhale --version 显示的是外层调度器的版本，而真正的运行时版本可能不同。跑 codewhale doctor 会看到 codewhale-tui: 0.9.0 这样的行——两个数字不一致是正常的，运行时会自己更新。以 doctor 里的数字为准。

升级：

codewhale update

4.6 平台注意事项

• macOS / Windows / Linux x64：直接装，没有坑。Linux x64 从 v0.8.65 起是静态编译（musl），任何发行版都能跑。
• Linux ARM64：v0.8.8 起才有预编译包。如果你在 Ubuntu 22.04 ARM64 上遇到 version 'GLIBC_2.39' not found，改用路线 C 从源码编译。
• Android / Termux：v0.9.1 仍是预览状态，且 Termux 上没有系统密钥链，API Key 会以明文存在 ~/.codewhale/config.toml（权限 0600）。介意的话用环境变量传 Key。

五、第一次启动：钥匙、模型、体检

5.1 先拿一把钥匙（API Key）

CodeWhale 自己不含模型，它需要一把”钥匙”去调别人的模型。默认供应商是 DeepSeek：

1. 打开 platform.deepseek.com，注册、充值（10 块钱够玩很久）
2. 在 API Keys 页面创建一个 Key，形如 sk- 开头的一长串
3. 立刻复制保存，页面关掉就再也看不到了

5.2 把钥匙交给 CodeWhale

codewhale auth set --provider deepseek

它会提示你粘贴 Key，输入时屏幕上不会显示任何字符（这是正常的防偷窥行为），粘贴完直接回车。

也可以用环境变量的方式临时给：

export DEEPSEEK_API_KEY="你的key"
codewhale

管理钥匙的几条命令：

auth list 的输出长这样，一眼看清哪家配好了：

provider     config store env  active
deepseek      yes     n/a      no    config
openrouter    no      no       no    missing
anthropic     no      no       no    missing
ollama        no      no       no    missing

5.3 配置从哪来：优先级链

这是新手最容易困惑的地方。同一个设置可能有四五个地方能写，谁说了算？优先级从高到低：

1. 命令行参数 —— codewhale --provider openrouter --model xxx
2. 环境变量 —— DEEPSEEK_API_KEY、CODEWHALE_PROVIDER、CODEWHALE_MODEL、CODEWHALE_BASE_URL
3. 配置档案（profile） —— codewhale --profile work
4. 用户全局配置 —— ~/.codewhale/config.toml
5. 内置默认值 —— DeepSeek + deepseek-v4-pro

🔥 最常见的诡异问题：你明明改了 config.toml，但它就是不生效。90% 的原因是某个环境变量在压着它。codewhale doctor 会明确告诉你”这个 Key 来自 env”，看到就去 unset 掉那个变量。

~/.codewhale/ 目录里都有什么：

~/.codewhale/
├── config.toml        # 供应商、模型、Key、项目信任级别
├── settings.toml      # 界面偏好：语言、主题、动画、默认模式
├── sessions/          # 所有历史会话（JSON）
├── skills/            # 装好的技能包
├── secrets/           # 密钥存储
├── catalog/           # 模型目录缓存
├── tasks/             # 后台任务队列
└── audit.log          # 审计日志

一份典型的 config.toml（这是我本机的，Key 已抹掉）：

provider = "deepseek"
api_key = "sk-***"
default_text_model = "deepseek-v4-pro"
reasoning_effort = "auto"

[projects."/Users/你的用户名/某个项目"]
trust_level = "trusted"

settings.toml 管界面，常用的几项：

locale = "zh-Hans"           # 界面中文
theme = "system"
default_mode = "agent"       # 启动时的默认模式
auto_compact = false         # 是否自动压缩上下文
show_thinking = true         # 显示模型的思考过程
show_tool_details = true     # 显示工具调用细节
status_indicator = "whale"   # 那只小鲸鱼

不想手改文件的话，进 TUI 后用 /config 和 /settings 图形化改，等价。

5.4 体检

codewhale doctor

这条命令是你以后所有排错的第一步。它会检查版本、更新、配置文件位置、状态目录、首次设置进度、以及每家供应商的 Key 状态。需要给别人看的时候用 codewhale doctor --json。

5.5 启动

先 cd 到你想让它工作的文件夹，再启动：

cd ~/codewhale-练习
codewhale

第一次启动会走一个引导流程：选语言 → 确认供应商和模型 → 确认运行时权限姿态 → 创建或确认你的 “constitution”（宪法，见第十节）。全部可以先按默认走完，以后用 /setup 随时回来改。

六、认识界面

TUI 是 “Terminal User Interface” 的缩写——在终端里画出来的图形界面。CodeWhale 的界面分五块：

• Header（顶栏）：当前会话、正在用的模型、当前模式、总体状态
• Transcript（主区）：对话内容、工具调用、命令输出、模型回复。这是审计轨迹——它读了什么文件、跑了什么命令，全在这里，不藏着
• Composer（输入框）：你打字的地方，也接受斜杠命令
• Sidebar（侧栏）：任务状态、正在跑的子智能体、上下文信息
• Footer（底栏）：实时活动、排队的后续指令、快捷键提示

底栏显示哪些信息可以自己挑，/statusline 打开选择器，可选项包括 mode（模式）、model（模型）、cost（花费）、balance（余额，仅 DeepSeek）、context_percent（上下文占用百分比）、git_branch（分支）、tokens 等。

6.1 必须记住的 6 个快捷键

另外两个好用的：

• Ctrl + G：把当前没写完的草稿”寄存”起来（/stash list 查看，/stash pop 取回）
• ! 开头：直接跑 shell 命令，走正常审批流程。比如输入 !ls 就是列目录

💡 Shift+Enter 换行：在输入框里想换行不发送，按 Shift + Enter。如果你的终端不支持，试 Alt + Enter。

6.2 常用斜杠命令

在输入框里打 / 会弹出命令菜单。第一次用只需要认识这几个：

完整命令列表变化很快，以 TUI 里打 / 弹出的实时菜单为准，不要背文档。

七、跑通第一个需求

7.1 一轮对话到底发生了什么

你敲一句话回车之后，内部是这样跑的：

1. 拼上下文：你的话 + 系统提示 + 项目规矩（AGENTS.md）+ 历史对话 + 相关文件
2. 发给模型：整包送到你选的那家供应商
3. 模型回复：可能是一段话，也可能是”我要调用工具”
4. 执行工具：读文件 / 改文件 / 跑命令。风险高的会先弹审批
5. 结果回填：工具输出接回上下文，再发给模型
6. 循环 3-5，直到模型认为任务完成或需要你介入
7. 停下，等你下一句

理解这个循环，你才知道”上下文占用 80%“意味着什么、为什么长对话会变笨、/compact 在干嘛。

7.2 动手：做一个个人主页

在练习文件夹里启动 CodeWhale，然后输入：

帮我做一个单页个人主页，只用一个 index.html 文件，样式内联，不引任何外部资源。

内容：
- 我叫「王小明」，是一名产品经理
- 三个板块：关于我、我做过的项目（放 3 个占位卡片）、联系方式
- 配色用米白底 + 深灰字 + 一个橙色强调色
- 手机上要能正常看

做完之后请你自己在浏览器里检查一遍：有没有排版错位、有没有引用不存在的资源。
确认没问题再告诉我完成。

注意这条指令的四个零件，缺一个效果都会打折：

1. 要什么结果：单页个人主页，一个文件
2. 在哪个范围：只改 index.html
3. 什么不要：不引外部资源
4. 怎么算完成：自己先检查排版和引用

它会开始动，可能弹出”我要创建 index.html，可以吗？“——按提示确认。

完成后：

open index.html      # macOS
start index.html     # Windows

7.3 关键：迭代，而不是重来

第一版一般不完美。不要重新描述一遍整个需求，那样它会推倒重做，你之前调好的部分全丢了。正确的做法是提增量修改：

橙色太艳了，换成砖红色。其他都别动。

项目卡片在手机上挤成一坨了，改成竖排。只改这一处的样式。

“只改这一处""其他别动”这类话很重要——它是在给 AI 划改动边界。不划边界，AI 很容易”顺手”重构一堆你没让它碰的东西。

7.4 让它自己验收

这是拉开差距最大的一个习惯。人类验收之前，先让 AI 自己查一遍：

提交前先自查：
1. 所有引用的文件路径都真实存在吗？
2. 有没有写了但没用上的代码？
3. 在 375px 宽度下排版会不会坏？
逐条回答，有问题就直接修掉。

这叫 Loop 工程——让它自己跑一个”做 → 检 → 修”的小循环，而不是每次都等你来当质检员。

八、模式：Plan / Act / Operate

CodeWhale 有三个可见模式，按 Tab 循环切换，或者 /mode plan 直接跳。

8.1 Plan（计划模式）

只读。 它能看文件、能搜索、能诊断，但不能改文件、不能跑 shell 命令。

用在：进入一个不熟的项目、想让它先出方案、需要一份可以review 的计划。

Plan 模式在确认时会给出一份结构化的计划书：目标、上下文、用到的资料、关键文件、约束、方案、验证计划、风险、交接说明。哪一项是空的你一眼就能看见，可以直接要求它补，而不是稀里糊涂地放它去动手。

8.2 Act（执行模式，也叫 Agent）

默认模式，日常工作用这个。 能读能写能跑命令，风险操作走审批门。文件写入默认不弹窗，shell 命令默认弹窗。

想彻底关掉 shell 能力，在配置里写 allow_shell = false，工具列表里就不会出现 shell 了。

8.3 Operate（统筹模式）

权限和 Act 完全一样，区别只在调度倾向：它会更主动地把独立的、可并行的、耗时长的活派给后台 worker 去做（就是第十四节的 Fleet），而你的输入框保持可用，可以继续发新指令。

⚠️ 一个常见误解：Operate 不是”权限更大的模式”。它不放宽任何审批、沙箱、仓库保护。它只是更爱派活。

8.4 选哪个

• 不熟的项目 → Plan
• 正常干活 → Act
• 一个任务能拆成好几摊互不干扰的活 → Operate

九、权限与沙箱：这一节最重要

9.1 四档审批姿态

按 Shift + Tab 循环，或者 /config 里改 approval_mode：

新手前两周固定在 Ask。你需要用这段时间建立直觉：它想干什么、什么该批什么不该批。

Full Access 会同时打开信任模式（允许访问工作目录以外的文件）和自动审批。只在你完全信任的仓库里用。

9.2 操作系统级沙箱

审批是”问你”，沙箱是”就算你批了，系统层面也拦住”。这是最后一道防线，各平台能力不一样，必须知道差别：

只有 macOS 能在沙箱层面阻止网络访问。 Linux 和 Windows 上，被批准的命令可以自由联网。这一点在你让 AI 跑一段来路不明的脚本时非常关键。

沙箱明确挡不住的东西：内核漏洞、时序侧信道、CPU/磁盘资源耗尽、供应链攻击（它能限制下载下来的代码能干什么，但拦不住”下载”这个动作本身）。

9.3 三条硬规矩

1. 动手之前先 git init + git commit。 这是你唯一的后悔药。CodeWhale 有 /restore 能从快照回滚文件，但 git 更可靠、更通用。
2. 不要在家目录 ~ 直接启动它。 永远 cd 到具体项目文件夹再开。工作目录就是它的活动边界，边界越小越安全。
3. 看不懂的命令不要批。 尤其是含 rm -rf、sudo、curl xxx | sh、git push --force 的。不确定就问它”这条命令会造成什么后果、可逆吗”。

9.4 工作目录边界与信任

默认情况下，文件工具只能碰启动时所在的那个目录。想让它访问外面：

/trust

或者在 config.toml 里给某个项目标记 trust_level = "trusted"。Full Access 会自动打开信任模式。

明确告诉它边界，比依赖设置更保险：

只检查和修改这个仓库里的文件。不要碰上级目录，不要动全局配置。

十、让它记住你的规矩

每次开新对话都要重复”用中文回复""不要加注释""改完跑一遍测试”，很烦。把这些写进文件，它每次自动读。

CodeWhale 有四层，权威从高到低：

10.1 第一层：本轮指令

你这次说的话权威最高。它可以覆盖下面所有层。

10.2 第二层：constitution（宪法）

文件位置：仓库里的 .codewhale/constitution.json（和 .github/ 同级）。

它回答两个问题：当各方信息冲突时，先信谁？ 和 宣布任务完成之前必须验证什么？

{
  "schema_version": 1,
  "authority": [
    "current user request",
    "live code and tests",
    "GitHub issue/PR details",
    "AGENTS.md",
    "memory",
    "old handoffs"
  ],
  "protected_invariants": [
    "不要破坏历史会话的回放能力"
  ]
}

protected_invariants（受保护的不变量）会被编译成写入拦截——连 Full Access 都跳不过去。这是 CodeWhale 比 Claude Code / Codex 强硬的地方：其他工具的项目规则是”建议”，这里的宪法是”硬约束”。

用 /constitution 在 TUI 里查看和修改。

10.3 第三层：AGENTS.md（项目说明）

这是行业通用格式（agents.md），Codex 也认。放在项目根目录。

生成一份骨架：

codewhale init

该往里写什么：

# 项目说明

## 这是什么
一个个人博客网站，用 Astro 框架，部署在 Vercel。

## 硬性要求
- 所有回复用中文
- 不要引入新的依赖包，除非我明确同意
- 改完 CSS 之后跑一遍 `npm run build` 确认没报错
- 不要碰 `content/` 目录里的文章内容

## 我的偏好
- 代码里不要写注释，除非逻辑真的绕
- 提交信息用中文，一句话说清改了什么

写作要点：写”不要做什么”比写”要做什么”更有效，因为 AI 的默认行为已经覆盖了大部分”要做什么”。

10.4 第四层：memory（记忆）

跨会话回忆起来的状态。有用，但权威最低——因为它可能过时。/memory 查看和管理。

十一、会话管理：别把一个对话用到死

长对话会变笨，这是所有 AI 编程工具的通病。原因是上下文窗口被塞满了无关的历史。

11.1 上下文压缩

CodeWhale 默认开启自动压缩：上下文用到 80% 时自动总结前面的内容，把摘要带进下一轮。想手动控制：

/compact

不想让它自动压缩，在 settings.toml 里写 auto_compact = false。

11.2 会话的四种操作

codewhale sessions 的输出：

Saved Sessions
==============
  * 40d2191d | uptate | 4 msgs | 2026-06-25 05:38 UTC (3w ago)
    d3a76e1d | https://github.com/... | 10 msgs | 2026-06-18 07:37 UTC (4w ago)

/sessions 默认只显示当前工作目录的会话，按 a 显示所有目录的。

11.3 三种”后悔”方式，别搞混

/restore list 10 会列出最近 10 个可回滚的快照点。

11.4 什么时候该开新对话

• 换了一个完全不相关的任务
• 上下文占用超过 70% 且当前任务快结束了
• 它开始反复犯同一个错、听不懂人话了

开新对话时给一句交接：「上一轮我们做完了 X，现在要做 Y，注意 Z。」

十二、Skills 与 MCP：给它装技能和外挂

这两个东西经常被搞混，一句话区分：

• Skill 教它”怎么做事” —— 是一段写好的工作流说明书，纯文字
• **MCP 给它”新的手” ** —— 是一个外部程序，提供它原本没有的能力（查数据库、发飞书消息、控制浏览器）

12.1 Skills（技能包）

一个 skill 就是一个文件夹，里面一个 SKILL.md，写明：遇到什么情况用、按什么步骤做、要收集什么证据、不要做什么。

装在 ~/.codewhale/skills/ 下。我本机装的这些是官方/社区包：

delegate          fleet-manager     mcp-builder       skill-creator
documents         pdf               plugin-creator    skill-installer
feishu            presentations     spreadsheets      v4-best-practices

TUI 里的操作：

• /skills 列出装了哪些
• /skill 激活某个技能

好的 skill 是窄的：只讲一个重复性流程。别写成万能手册，那等于没写。

CodeWhale 兼容 Claude Code 的 skill / plugin 格式（见官方 CLAUDE_PLUGIN_COMPAT.md），所以社区里现成的 Claude skills 大多能直接用。

12.2 MCP（外部工具服务器）

MCP 全称 Model Context Protocol，是一套”给 AI 接外设”的开放协议。两种接法：

• stdio：本地启一个程序，通过标准输入输出通信
• HTTP：连一个远程服务器（支持 OAuth 登录）

配置文件在 ~/.codewhale/mcp.json，也可以放项目级的。初始化：

codewhale setup --mcp
# 或
codewhale mcp init

TUI 里 /mcp 查看状态和健康检查。MCP 工具在模型眼里叫 mcp_<服务器名>_<工具名>，走和内置工具完全一样的审批流程——只读的可能自动放行，有副作用的必须你批准。

12.3 反向用法：把 CodeWhale 当成别人的 MCP

CodeWhale 自己也能当服务器，被别的 AI 工具调用：

codewhale mcp-server          # 以 MCP stdio 模式运行
codewhale serve               # 本地运行时服务

三种服务模式的区别：

十三、exec：把它塞进脚本和 CI

TUI 是给人用的，exec 是给脚本用的——不开界面，跑完就退出。

# 一次性问答，不动文件
codewhale exec "解释一下这个函数在干什么"

# 带工具、自动批准，真的动手
codewhale exec --auto "修好那个失败的测试"

# 输出结构化 JSON，方便程序解析
codewhale exec --auto --output-format stream-json "修好那个失败的测试"

# 接着上次的会话继续
codewhale exec --continue "再把文档也更新一下"
codewhale exec --resume 40d2191d "继续"

注意 --auto 的分量：不加它，exec 只是一次纯模型问答，不碰文件；加了它，就是无人值守地动手。在 CI 里用之前先在本地确认过它的行为。

其他好用的非交互命令：

codewhale review              # 对当前 git diff 做一次代码复查
codewhale apply patch.diff    # 把补丁打到工作区
codewhale metrics             # 从审计日志出一份用量汇总
codewhale models              # 拉取供应商的实时模型列表
codewhale model list          # 列出内置模型注册表
codewhale model set pro       # 设默认模型

十四、Fleet：一群智能体同时干活

到这里开始是重型功能。第一次读可以跳过，等你遇到”这个活一个 AI 干太慢了”的时候再回来。

14.1 Fleet 是什么

Fleet 是一个持久化的多 worker 控制台。它不是另一个执行引擎——每个 worker 本质上就是一个后台跑的 codewhale exec，只是 Fleet 帮你把它们记账、监控、恢复。

关键词是持久：每一步写进只追加的账本 .codewhale/fleet.jsonl。笔记本合盖、程序崩溃、你手滑关了终端，fleet resume 都能从断点接着跑。这是它和”临时开几个子智能体”的本质区别。

14.2 最省事的用法：直接说人话

绝大多数情况下，你不需要写任何配置文件。切到 Operate 模式，直接说：

开两个只读的探查员，一个看 config 模块，一个看 TUI 的供应商选择器。
两边都要给我文件位置和风险点，然后我们再定方案。

它会自己派 worker，界面上出现 worker 卡片，你能看到每个在干嘛。

内置角色：

别滥用：小改动不要派 worker，也绝对不要让两个 worker 同时改同一批文件。

14.3 手动路径：写任务规格

需要可复查、可提交进仓库的规格时，走手动路径。

第一步，初始化账本：

codewhale fleet init

第二步，写一份 tasks.json（JSON 或 TOML 都行）：

{
  "name": "docs readiness check",
  "security_policy": {
    "default_trust_level": "sandbox",
    "max_trust_level": "sandbox",
    "allowed_secrets": [],
    "capability_grants": [],
    "require_identity_verification": true
  },
  "tasks": [
    {
      "id": "map-docs",
      "name": "Map current docs",
      "objective": "找出描述 Fleet 和 Workflow 的文档。",
      "instructions": "读 docs/FLEET.md 和 docs/WORKFLOW_AUTHORING.md，报告命令面、当前限制、以及任何讲不清的地方。",
      "worker": {
        "role": "reviewer",
        "profile": "reviewer",
        "tools": ["rg", "sed", "git"],
        "model": "deepseek-v4-flash"
      },
      "workspace": {
        "required_files": ["docs/FLEET.md", "docs/WORKFLOW_AUTHORING.md"],
        "writable_paths": []
      },
      "expected_artifacts": ["log", "report"],
      "scorer": { "kind": "manual" },
      "retry_policy": { "max_attempts": 1 }
    }
  ]
}

几个字段的意思：

security_policy 里 default_trust_level: "sandbox" 是保守默认；allowed_secrets: [] 表示不给任何密钥。这些字段的存在本身就是提醒你：派出去的 worker 也是有权限边界的。

第三步，跑起来并监控：

codewhale fleet run tasks.json --max-workers 4

# 另开一个终端
codewhale fleet status              # 各状态的计数
codewhale fleet inspect <worker-id> # 单个 worker 的详情
codewhale fleet logs <worker-id>    # 日志
codewhale fleet artifacts <worker-id>

出问题时的干预手段：

codewhale fleet interrupt <worker-id>   # 打断
codewhale fleet restart <worker-id>     # 重来
codewhale fleet resume <run-id>         # 从账本恢复整个运行
codewhale fleet stop --all              # 全停

14.4 可复用的 worker 档案

TUI 里跑：

/fleet setup

选角色、决定这个档案是继承当前模型还是钉死一个供应商/模型、检查权限和工具、保存。

• 项目级档案存 .codewhale/agents/<角色>.toml
• 个人级档案（跨仓库可用）在预览前按 s 保存到 $CODEWHALE_HOME/agents/<角色>.toml
• 同名时项目级优先

模型继承是字面意义的：你在 /model 里选的模型就是”指挥官”，任何没有钉死模型的 worker 都跑在这个模型上。常见的省钱布局是——指挥官用贵模型（deepseek-v4-pro），干活的 worker 用便宜模型（deepseek-v4-flash）。

十五、Workflow 与 Lane：把编排写进仓库

15.1 三个词的关系

这是最容易绕晕的一组概念，一句话各自定位：

• Workflow = 剧本。写明有几个阶段、哪些并行、结果怎么汇总。可以提交进 git，可以复查，可以重跑。
• Fleet = 演员和后勤。真正干活的 worker、它们的模型、权限、日志、账本。
• Lane = 这一场演出。Workflow 跑起来的一个具体实例，有 ID，能查状态、看日志、中途接管。

一句话串起来：Workflow 描述怎么演，Fleet 提供谁来演，Lane 是正在演的这一场。

15.2 写一个 Workflow

放在仓库里，比如 workflows/docs_readiness.workflow.js：

export default workflow({
  "id": "docs-readiness",
  "goal": "检查 Fleet 和 Workflow 文档，然后综合出一份就绪报告",
  "nodes": [
    {
      "branch": {
        "id": "parallel-docs-audit",
        "parallel": true,
        "children": [
          {
            "agent": {
              "id": "fleet-docs",
              "prompt": "检查 docs/FLEET.md 的命令与任务规格覆盖度。",
              "agent_type": "review",
              "mode": "read_only",
              "profile": "reviewer",
              "file_scope": ["docs/FLEET.md"]
            }
          },
          {
            "agent": {
              "id": "workflow-docs",
              "prompt": "检查 docs/WORKFLOW_AUTHORING.md 的编写指引覆盖度。",
              "agent_type": "review",
              "mode": "read_only",
              "profile": "reviewer",
              "file_scope": ["docs/WORKFLOW_AUTHORING.md"]
            }
          }
        ]
      }
    },
    {
      "reduce": {
        "id": "readiness-summary",
        "inputs": ["fleet-docs", "workflow-docs"],
        "prompt": "总结确切的文档缺口，以及最安全的下一步修改。"
      }
    }
  ]
});

可用的节点类型：agent（一个智能体）、branch（分支/并行）、sequence（顺序）、reduce（汇总）、teacher_review（复审）、loop_until（循环到满足条件）、cond（条件）、expand（展开）。

⚠️ 它不是一个通用 JavaScript 运行时。 import、进程访问、读写文件、网络请求、eval、async/await 全部被拒绝。它只是一种声明式的写法，最终会被编译成 Rust 里的类型化结构。这个限制是安全设计，不是缺陷。

15.3 跑起来

codewhale workflow run docs-readiness --fleet reviewer --runtime tmux --goal 检查文档就绪度
codewhale workflow run docs-readiness --fleet reviewer --runtime inline --verify

--runtime 有四种后端：tmux（可断开重连，长任务首选）、inline（就在当前进程里跑）、vm、ci。

15.4 管理 Lane

codewhale lane list              # 列出所有 lane，最新的在前
codewhale lane status <lane-id>  # 状态和接管信息
codewhale lane attach <lane-id>  # 接管一个 tmux lane，去现场看
codewhale lane logs <lane-id>    # 跟踪日志
codewhale lane stop <lane-id>    # 停掉并清理工作树

Lane 记录存在 $CODEWHALE_HOME/lanes/。

15.5 什么时候真的需要 Workflow

大多数时候不需要。 官方明确说了：普通的多智能体活儿，直接说人话让 Operate 派 Fleet worker 就行，不用写文件。

只有当你需要这几样时，Workflow 才有价值：

• 有序的阶段（必须 A 做完才能做 B）
• 闸门（某个条件不满足就不许往下走）
• 共享预算（整个流程总共不许超过多少 token）
• 确定性的汇总（结果必须按固定方式合并）

15.6 一个好用的过渡提示词

不知道怎么写规格时，让它先给你起草、但别跑：

帮我为这个目标起草一份 Fleet 任务规格，但先不要执行。
把你打算派的任务、worker 档案、可写路径、期望产出、验收规则和安全策略都列出来给我看。
除非我明确授权，否则不要开启任何密钥。

这一步复查是故意设计的：它逼你在持久 worker 真正启动之前，把模型路由、可写路径、网络访问、密钥使用全部摆到台面上。

十六、省钱：模型路由策略

CodeWhale 最大的实用价值就在这一节。

16.1 三层路由思路

任务中途可以随时 /model 切换——这是 CodeWhale 独有的。前面用便宜模型探索，卡住了切贵的，解决了再切回来。

16.2 /model auto

让它每轮自己挑模型和思考深度。

它的工作方式值得知道：会把你最新的请求（截断到 4000 字符）加上最近最多 6 条上下文摘要（每条 900 字符），发给 deepseek-v4-flash 做一次分类。你的凭证、端点、供应商错误信息不会被发送。 如果没有这个路由模型，它会退回到本地启发式规则，不发任何分类请求。

需要严格控制成本或做可重复对比时，用固定模型，不要用 auto。

Ctrl + O 打开 Turn Inspector，能看到这一轮的具体路由：用了哪个供应商/模型、选了哪个档位、为什么这么选。

16.3 推理力度

Ctrl + T 循环切换，或者在配置里写 reasoning_effort。可选 auto 以及不同的档位。

简单任务把力度调低，省钱且更快。这个旋钮的收益经常被低估。

16.4 其他省钱习惯

1. 让它先给方案再动手 —— Plan 模式一次规划，比反复推翻重做便宜得多
2. 管住上下文 —— 长对话每一轮都在重复付费。及时 /compact 或开新会话
3. 给 Fleet worker 钉便宜模型 —— 指挥官用 pro，干活的用 flash
4. 用 /goal 设预算 —— 给会话设一个 token 上限，超了它会停

十七、出问题时怎么排查

17.1 固定的四步

1. codewhale doctor —— 先看版本、配置路径、Key 状态。八成问题这一步就定位了
2. 看是哪一层的问题 —— 是模型笨（换模型）、还是没给够信息（补上下文）、还是权限被拦（看审批姿态）、还是环境坏了（看 doctor）
3. 看 Transcript —— 它到底读了什么、跑了什么、报了什么错。不要重新描述需求，把报错原文喂回去
4. 实在不行开新会话 —— 带一句交接说明

17.2 高频问题对照

17.3 提 issue 时该带什么

CodeWhale 是社区项目，维护者很积极。报 bug 时附上：版本、安装方式、操作系统和终端、供应商和模型、确切的命令或提示词、codewhale doctor --json 的输出、以及”在全新的空目录里会不会复现”。

不要粘贴 API Key、私有代码或任何密钥。

十八、速查表

18.1 命令行

18.2 TUI 里

18.3 关键文件位置

十九、最后

装好 CodeWhale 大概 15 分钟。但这只是入场券。

用下来最真实的体会是：工具的上限很高，大部分人卡住的地方是”不会提需求”。

同样一句”帮我做个网站”，有人得到一坨垃圾，有人得到能直接上线的东西，差别在于后者说清楚了：给谁看、什么风格、参考哪个站、必须有什么、绝对不要什么、做完怎么算合格。

这套能力和写代码无关，和你能不能把脑子里模糊的想法说成一份清晰的需求有关。这恰恰是不懂代码的人也能练、甚至更容易练好的东西。

CodeWhale 额外给你的，是不用为这份能力支付垄断价格。同一份需求，你可以先用便宜模型试，不行再换贵的；可以今天用 DeepSeek，明天用 GLM，后天用自己电脑上的本地模型——而你的工作方式、配置文件、项目规矩，一行都不用改。

所以最后的建议还是那句：别停在教程里，今晚就找一个你真正想做的小东西，从头做到能打开为止。

延伸阅读

• 从零开始用 Codex 和 Claude Code：一篇写给完全不懂代码的人的上手指南 —— 另外两个主流选择，界面和心智模型是相通的
• 一把钥匙、三种协议、两个配置文件：AI API 小白指南 —— 搞懂 API Key、中转站、多套配置切换
• 你不是不会用 AI，你只是只做了第一层：Prompt / Context / Harness / Loop —— 为什么”能换模型”这么重要，四层工程的全貌

信息核实说明（2026 年 7 月 22 日）

• 项目地址：https://github.com/Hmbown/CodeWhale
• 官网：https://codewhale.net/
• 官方文档：仓库 docs/ 目录，重点看 GUIDE.md、INSTALL.md、PROVIDERS.md、MODES.md、FLEET.md、FLEET_WORKFLOW_TUTORIAL.md
• 本文的命令输出均来自本机实测（codewhale v0.8.41 / 运行时 v0.9.0，macOS）

CodeWhale 迭代很快，命令、模型名、界面细节可能变化。遇到对不上的地方，以 codewhale --help、codewhale doctor 的实际输出和官方 docs/ 为准。