如何使用 Codewhale

> Codewhale 是一个面向终端的开源编程智能体（Rust 编写，MIT 协议）。它运行在你的真实工作区里，

> 用真实的工具和真实的文件完成你的请求：读取与搜索、修改文件、运行与验证，并如实汇报结果。

> 它起初名为 `deepseek-tui`，如今已不偏向任何提供商，由社区独立维护。

> 源码与文档：<https://github.com/Hmbown/CodeWhale\>

$什么是 Codewhale$ (#什么是-codewhale)
$安装$ (#安装)
$核心工作方式$ (#核心工作方式)
$工作区（Workspace）$ (#工作区workspace)
$开始使用$ (#开始使用)
$启动命令（CLI）$ (#启动命令cli)
$模式与权限姿态$ (#模式与权限姿态)
$TUI 交互命令详解$ (#tui-交互命令详解)
$键盘快捷键$ (#键盘快捷键)
$提供商与本地模型$ (#提供商与本地模型)
$配置$ (#配置)
$技能（Skills）$ (#技能skills)
$MCP / Hooks / 插件$ (#mcp--hooks--插件)
$记忆（Memory）$ (#记忆memory)
$子代理、Fleet 与并行任务$ (#子代理fleet-与并行任务)
$工作流（Workflow）$ (#工作流workflow)
$本地 Web 客户端$ (#本地-web-客户端)
$沙箱与安全边界$ (#沙箱与安全边界)
$权限与授权顺序$ (#权限与授权顺序)
$实用建议$ (#实用建议)
$常见问题$ (#常见问题)
$社区与项目历史$ (#社区与项目历史)

什么是 Codewhale

Codewhale 是一个面向真实代码仓库的 AI 编码代理。它不是只会给出建议的聊天机器人，

而是可以：

**读取与搜索**：查看文件、搜索代码、查看 Git 历史与差异。
**修改文件**：创建、编辑代码和文档。
**运行与验证**：执行测试、构建、语法检查，并读取真实输出。
**并行工作**：派发后台子代理、使用独立 worktree 进行不冲突的并行任务。
**扩展自身**：连接 MCP 服务器与技能、配置钩子（hooks）、把代理角色保存为可读文件。

它的核心原则是：**先观察，再行动，最后验证**，并且**如实汇报工具返回的结果**，

即使结果出乎意料。

安装

Codewhale 提供 `codewhale` 与 `codew` 两个命令名（指向同一运行时）。安装后可用

`codewhale --version` 和 `codewhale doctor` 验证。

**npm（推荐，Node 18+）**

```bash

npm install -g codewhale

codewhale --version

```

**官网一键脚本（macOS / Linux）**

```bash

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

```

**Cargo（任意 Tier-1 Rust 目标，Rust 1.88+）**

```bash

cargo install codewhale-cli --locked

```

在 Linux 上从源码编译需先安装系统依赖（如 Debian/Ubuntu 的

`build-essential pkg-config libdbus-1-dev`）。

**Homebrew**

```bash

brew tap Hmbown/deepseek-tui

brew install codewhale

```

**Nix**

```sh

nix run github:Hmbown/CodeWhale

```

**Windows Scoop / winget**

```powershell

scoop install codewhale # Scoop 主仓库

winget install Hmbown.CodeWhale # winget（v0.9.5+）

```

**Windows NSIS 安装包**：从 GitHub Releases 下载 `CodeWhaleSetup.exe`，双击安装（按用户，

免管理员）；静默安装用 `CodeWhaleSetup.exe /S`。

**Docker**

```bash

docker run --rm -it -v codewhale-home:/home/codewhale/.codewhale -v "$PWD:/workspace" -w /workspace ghcr.io/hmbown/codewhale:latest

```

**手动下载 GitHub Releases**：从 Releases 页下载匹配平台的 `codewhale-<platform>` 与

`codew-<platform>`，放到 `PATH` 目录，并按 `codewhale-artifacts-sha256.txt` 校验 SHA-256。

**Android / Termux（arm64，预览）**：使用 Termux 专用归档，而非 Linux arm64 归档。

**国内镜像提示**：npm 慢可改用 `npm config set registry https://registry.npmmirror.com`；

Cargo 安装可配置 TUNA / rsproxy 镜像；Linux x64 的 npm 包装器会自动在 GitHub 与 CNB 镜像间竞速下载。

**验证安装**

```bash

codewhale --version

codewhale doctor # 检查 API key、provider、运行时与 PATH 完整性

codewhale doctor --json # 机器可读报告，提交 issue 时用

```

核心工作方式

Codewhale 遵循一个简单的闭环：

**观察**：检查相关文件与仓库状态，理解上下文。
**行动**：做出最小、连贯的修改。
**验证**：运行检查并阅读真实输出，而不是只看退出码。
**汇报**：说明改了什么、验证了什么、还有什么未完成。

> 重要：**没有经过验证，就不算完成。** Codewhale 不会把部分结果当作完整结果交付。

工作区（Workspace）

Codewhale 的「工作区」就是它读写文件、运行命令所围绕的那个目录，决定了它默认能看到和改动的范围。

**默认来源**：你在哪个目录启动 `codewhale`，那个目录就是工作区；也可以用 `-C <DIR>` / `--workspace <DIR>` 指定。
**默认边界**：文件工具被限制在工作区内，无法读写工作区之外的文件。
**扩大范围**：需要访问工作区之外时，用 `/trust on` 开启信任模式；`/trust off` 重新收紧（Full Access 会自动开启信任模式）。
**项目级配置与状态**：工作区还承载 `.codewhale/config.toml`（项目 overlay，只能收紧安全姿态）、

`.codewhale/fleet.jsonl`（Fleet 账本）等本地状态；并行的编辑任务会放到工作区外的独立 Git worktree

（默认在 `.codewhale-worktrees/` 目录）。

**会话按工作区归属**：`codewhale --continue` 恢复的是「当前工作区」最近一次会话，`/sessions` 选择器默认也限定当前工作区。

一句话：**工作区是 Codewhale 的行动边界与归属范围**------先在你要它工作的项目目录里启动它，必要时再通过 `/trust` 扩大范围。

开始使用

1. 首次启动

在你希望它工作的目录下运行：

```bash

codewhale

```

首次启动只会询问本次安装仍缺失的决定：无法推断时的语言、未配置可用路由时的提供商

（含明确的离线选项）、需要决策时的目录信任。之后进入真正的输入框。DeepSeek 是默认提供商，

配置密钥最直接的方式是 `codewhale auth set --provider deepseek`，也可用环境变量

`DEEPSEEK_API_KEY`。

新配置存放在 `~/.codewhale/config.toml`（兼容旧的 `~/.deepseek/config.toml`）。

用 `/constitution` 查看或修改长期约定，用 `/setup` 渐进式引导，用 `/settings` 打开完整设置编辑器。

2. 用自然语言描述你的需求

直接告诉 Codewhale 你想做什么即可，例如：

```text

帮我写一个函数，用来解析 CSV 文件

```

```text

修复 login 模块里的空指针报错

```

```text

给这个项目写一份 README

```

描述得越具体，它越能精准完成。好的首条指令包含四要素：

期望的结果（做什么）
涉及的文件、功能或行为（在哪里）
不在范围内的事（边界）
什么算完成（验收标准）

例如：

```text

修复 config 加载器里错误的 provider 报错文案。不要改动 provider 注册表。

加一个回归测试，只运行 config crate 的测试。

```

3. 查看它做了什么

Codewhale 会先探查相关代码和仓库状态；做出修改后运行检查并报告结果；最后说明改了哪些文件、

验证了什么、有哪些未决风险或待办。**转录（transcript）就是审计轨迹**------命令失败时，

用可见的失败输出作为下一条指令的一部分，而不是推倒重来。

4. 提出修改或追加要求

完成一轮后，你可以继续：

```text

把错误处理再补充一下

```

```text

顺便加几个单元测试

```

Codewhale 会在上一轮的基础上继续，而不是从零开始。

启动命令（CLI）

Codewhale 提供多种启动方式，覆盖交互、一次性执行、服务端、编排等场景。

以下内容基于 `codewhale --help` 输出整理，可用 `codewhale help` 或

`codewhale <子命令> --help` 查看完整说明。

交互式 / 会话启动

**`codewhale $PROMPT$ `**：默认交互模式，可带一段初始提示直接开始。
**`codewhale run $ARGS$ ...`**：显式运行一个交互式或非交互式任务。
**`codewhale exec $ARGS$ ...`**：非交互式一次性执行。普通 `exec` 只做一次模型回答；

加 `--auto` 启用带工具代理的自动化模式（可读写文件、执行 shell）。

**`codewhale -c` / `--continue`**：继续当前工作区最近一次会话。
**`codewhale resume <ID>`**：按 ID 或前缀恢复一个已保存的会话。
**`codewhale fork <ID>`**：分叉一个已保存的会话，派生新分支（`fork --last` 分叉最近一次）。
**`codewhale sessions`**：列出已保存的会话。
**`codewhale rc $ARGS$ ...`**：启动交互会话并交给 Codewhale 的 Web 应用。

示例：

```text

codewhale exec "解释一下这个函数"

codewhale exec --auto "修复失败的测试"

codewhale exec --auto --output-format stream-json "完成某个任务"

```

`exec --auto --output-format stream-json` 每行输出一个 JSON 事件，供后端/harness 使用。

退出码：`0` 成功；`1` 任务/代理失败；`75`（`EX_TEMPFAIL`）表示可重试的基础设施故障

（provider/传输 `network`/`timeout`，重试后仍未恢复）。

服务端 / 网络模式

**`codewhale serve`**：启动本地 Codewhale 服务器，用转发选项选择传输方式：
`--mcp`：以 stdio 启动 MCP 服务器
`--http`：启动运行时 HTTP/SSE API 服务器
`--mobile`：启动 HTTP/SSE API 并附带手机端控制页
`--web`：启动仅回环的浏览器客户端
`--acp`：以 stdio 启动 ACP 服务器（供编辑器客户端）
`--qr`：显示手机端 URL 二维码（需 `--mobile`）
**`codewhale app-server`**：运行规范的运行时 API / 控制面（HTTP/SSE、移动端、stdio）：
`--http`：完整 HTTP/SSE 运行时 API（`/v1/*`），默认 `127.0.0.1:7878`
`--mobile`：运行时 API + 手机控制页（默认绑定 `0.0.0.0`）
`--stdio`：通过 stdio 运行 JSON-RPC 控制传输
**`codewhale web $--port 7878$ `**：打开本地浏览器客户端（基于规范运行时 API）。
**`codewhale mcp-server`**：以 stdio 运行 MCP 服务器模式。

> `serve --http` / `serve --mobile` 是 `app-server --http` / `app-server --mobile`

> 的兼容别名，新集成建议优先使用 `app-server`。

编排 / 后台运行

**`codewhale fleet`**：管理持久的 Agent Fleet 运行。
**`codewhale workflow run <name>`**：运行一个已签入的 Workflow（经 Lane Runtime 后端）。
**`codewhale lane`**：管理工作流实例（Lane）与运行时后端，子命令包括 `list`、`status`、

`attach`、`logs`、`interrupt`、`start` 等。

初始化 / 认证 / 诊断

**`codewhale login --api-key <KEY>`**：配置 provider 凭据。
**`codewhale auth`**：管理认证凭据与 provider 模式（`set`/`get`/`list`/`clear`/`status` 等）。
**`codewhale account`**：登录 Codewhale 账户并管理账户级 provider 密钥（别名 `cloud`）。
**`codewhale init`**：在当前目录创建默认的 `AGENTS.md`。
**`codewhale setup`**：引导 MCP 配置和/或 skills 目录。
**`codewhale doctor`**：运行 Codewhale 诊断（离线；`--probe-api`/`--probe-local` 做在线探测）。

其他常用命令

`models` / `model`（查看/解析模型）、`speech`（别名 `tts`，语音合成）、`review`（对 git diff

做代码审查）、`apply`（应用补丁）、`mcp`（管理 MCP 服务器）、`config`（读写配置）、`thread`

（会话元数据）、`features`（特性开关）、`metrics`（用量统计）、`update`（更新二进制）、

`completion` / `completions`（生成 shell 补全）。

常用全局选项

**`-C, --workspace <DIR>`**：指定 Codewhale 文件工具的工作区目录。
**`-c, --continue`**：继续当前工作区最近一次交互会话。
**`-p, --prompt <PROMPT>`**：传入初始提示。
**`--model <MODEL>`** / **`--provider <PROVIDER>`** / **`--profile <PROFILE>`**：选择模型、provider 或配置档。
**`--approval-policy <POLICY>`** / **`--sandbox-mode <MODE>`**：控制审批与沙箱策略。
**`--no-project-config`**：跳过加载项目级配置。
**`-h, --help`** / **`-V, --version`**：查看帮助或版本。

模式与权限姿态

Codewhale 有三个相关但独立的概念：**TUI 模式**、**权限姿态**、以及可选的**工作流覆盖层**。

TUI 模式

在输入框为空时按 `Tab` 循环切换可见模式：**Plan → Work → Operate → Plan**。也可用 `/mode` 打开

模式选择器，或直接 `/mode plan`、`/mode work`、`/mode operate`。（`Act` 与 `/mode act` 是

`Work` 的兼容别名。）

**Plan（计划）**：设计优先、只读。运行时集中拒绝文件修改与 shell 执行；只读检查与

策略允许的调研（含延迟的 Web 搜索/抓取）仍可用。适合在不熟悉的仓库里先探查、出方案。

**Work（工作，内部名 `agent`）**：常规多步执行。首批工具箱为 `read`、`write`、`edit`、

`bash`、`agent`、`todo_write`；审批、沙箱、仓库规则与管理策略仍决定什么能执行。

**Operate（操作）**：多任务调度姿态。拥有与 Work 相同的工具与执行权限，差异在调度侧重------

对独立/并行/后台/长时任务，默认派发后台 worker；小而紧耦合的任务留在父会话。**派发不等于完成**：

可写的子代理必须返回真实的验证证据。

权限姿态

按 `Shift+Tab` 循环切换：**Ask → Auto-Review → Full Access**（也可用 `/config` 编辑

`approval_mode`）。这是完整授权顺序里的一层，不是对工具准入、仓库规则或沙箱的绕过。

**Ask（默认，`suggest`）**：工具审批可能打断你；当未决选择会实质改变权限、成本、范围或结果时，

Codewhale 会提问。

**Auto-Review（`auto`）**：全自主姿态，绝不弹问题；模型从上下文消歧，选择安全可逆的解释，

或报告无法安全继续。已证明安全的调用自动放行；发布类操作与破坏性的后台/无头工作被确定性硬阻断；

无法证明安全的调用交给一次性「模型守护」判定（高风险/严重风险即使模型说允许也不会自动执行，

失败一律关闭）。

**Full Access（`bypass`）**：普通工具调用不再弹出审批；不可绕过的注册性阻断会自动批准而非弹出

矛盾弹窗。仓库规则与管理策略仍会硬阻断。请勿在不信任的仓库里使用。

**`never`**：只放行安全/只读工具，其余一律阻断。

**信任模式（Trust）**：默认文件工具被限制在 `--workspace` 目录内。要允许访问工作区之外的文件，

运行 `/trust on`；`/trust off` 重新收紧。裸 `/trust`（同 `/trust status`）只报告当前状态，

不启用任何东西。Full Access 会自动启用信任模式。

工具可用性（按模式）

|:---|:---:|:---:|:---:|

| `read` 与策略允许的调研工具 | ✅ | ✅ | ✅ |

> 模型选择与模式无关：`--model auto` / `/model auto` 会按回合路由到具体模型与思考等级，

> 不在 `Tab` 循环里。

TUI 交互命令详解

启动 Codewhale 进入交互式终端界面（TUI）后，除自然语言输入外，还提供一套以 `/` 开头的

**斜杠命令（slash commands）**，以及键盘快捷键。

如何查看 / 唤起命令

输入 `/help` 或按 **`Ctrl+K`**：列出当前构建注册的全部命令；`/help $command$ ` 可查看某条命令详情。
输入 `/` 会触发**命令补全 / 过滤**（slash 菜单），可边输入边筛选。
常用快捷键：`Ctrl+K`（命令面板）、`Ctrl+O`（推理详情）、`Ctrl+Alt+O`（回合检查器）、

`Ctrl+C`（取消当前回合）、`Esc`（关闭弹窗/取消菜单）。

> 命令以运行时 `/help` 输出为准（它是从注册表生成的唯一权威列表）；下方语法为当前版本注册形式。

会话与上下文

```text

/attach $\$ 附加文件/路径到上下文

/compact $focus$ 压缩/精简对话上下文

/context $report\|json\|prompt-json\|summary$ 查看上下文占用

/anchor <text> | /anchor list | /anchor remove <n> 固定（锚定）文本到上下文

/clear 清空会话

/rename <new title> 重命名当前会话

/relay $focus$ 创建紧凑的会话中继

/branch <entry_id> 从历史条目分叉会话

/turn inspect 查看整个回合的检查器（模型路由等）

```

会话存储 / 导入导出

```text

/save $path$ 保存会话

/load $path$ 加载会话

/export $clipboard\|file \[--force$ <path>|turn $...$ ] 导出会话

/share 导出并上传当前会话

/fork $session_id\|picker$ 分叉已保存会话

/resume $session_id\|path/to/export.json$ 恢复会话

/sessions $show\|open \\|archive \\|unarchive \\|prune \$ 管理会话

/remote-env open 打开远程运行时环境

```

模型 / 提供商 / 配置

```text

/model $name\|refresh$ 查看/切换/刷新模型；/model auto 按回合自动路由

/models 获取在线端点 ID 列表

/modeldb 打开内置模型参考

/provider $setup \[name$ |name $model$ ] 配置或查看 provider

/profile <name> 切换配置档

/config $ask-rules\|status\|\ \[value$ ] 读写配置、查看规则

/settings $text$ 打开/查看设置编辑器

/setup（含 /setup provider）引导配置（只读本地清单，不自动执行）

/statusline 选择底栏状态芯片的显示

/theme $name\|custom:\\|schema\|path$ 切换主题（如 Blue Stage）

```

模式与思考强度

```text

/thinking 控制思考（reasoning）显示/行为

/verbose $on\|off$ 切换详细输出

/advisor $on\|off\|status$ 顾问模式开关

```

代理 / 并行 / Fleet / 工作流

```text

/agent $N$ <task> 派发 1 个（或 N 个）子代理执行任务

/subagents 查看当前会话的子代理

/workflow $objective\|status\|cancel \$ 运行已签入的 Workflow

/workflows 打开 Workflow 运行仪表盘

/lane $list\|status\|interrupt\|restart\|resume \$ 管理工作流实例

/task $add \\|list\|digest\|show \\|cancel \$ 任务列表

/queue $list\|send \\|edit \\|drop \\|clear$ 排队消息

```

工具集成（MCP / 插件 / LSP / 网络）

```text

/skill <name|install <spec>|update <name>|uninstall <name>|trust <name>> 单个技能

/skills $--remote\|sync\|inspect\|suggest \\|\$ 技能管理器（无参数时打开）

/lsp $on\|off\|status$ 语言服务器协议开关

/network $list\|allow \\|deny \\|remove \\|default \$ 网络访问控制

/hooks $list\|events$ 查看钩子与事件

/tools $text\|json$ 查看代理可调用的工具

```

文件 / 工作区

```text

/open 打开文件/会话

/workspace $path\|worktrees$ 查看/设置工作区、列出 worktree

/worktree 创建/管理 Git worktree

/tree $interactive$ 交互式文件树

/rlm $N$ <file_or_text> 把文件或文本载入会话内持续可用的工作上下文

```

审查 / 差异 / 调试

```text

/diff 显示当前改动差异

/review <target> 对目标做代码审查

/tokens 查看 token 使用

/cache $count\|inspect\|stats\|zones\|warmup$ 缓存诊断

/change $version$ 查看变更/版本信息

/preview-request $json$ $--prompt \$ 预览请求

/retry 重试上一轮请求

/undo 撤销上一轮（部分情况需先 /trust on）

/restore $list \[N$ | <N>] 从 side-git 快照恢复工作区文件（不改会话历史）

```

记忆 / 笔记

```text

```

权限 / 信任 / 治理

```text

/trust $on\|off\|add \\|remove \\|list$ 目录信任管理

/permissions $list\|remove \ \[--confirm \$ ] 权限规则管理

/feedback（含 feature、security）发送反馈

```

其他

```text

/update $check\|install$ 检查/安装更新

/rc $status\|stop$ Web 应用（remote control）状态

/hf $mcp \\|concepts$ hands-free（MCP 状态/概念）

/stash $list\|pop\|clear$ 暂存管理

/structcopy 结构化复制

/hotbar 配置热键栏槽位动作

```

键盘快捷键

完整目录见官方 `docs/KEYBINDINGS.md`。以下按上下文摘录最常用项。

全局（任意上下文）

`F1` / `Ctrl-/`：切换帮助浮层
`F2`：切换设置编辑器
`Ctrl-K`：打开命令面板（slash 查找器）
`Ctrl-C`：取消当前回合 / 关闭弹窗 / 二次确认退出
`Ctrl-B`：把前台 shell 等待移入 `/jobs` 后台
`Ctrl-D`：退出（仅当输入框为空）
`Tab`：输入框为空时循环模式（Plan → Work → Operate）
`Shift+Tab`：循环权限姿态（Ask → Auto-Review → Full Access）
`Ctrl-T`：循环推理工作量；`Ctrl-Shift-T`：切换实时转录覆盖层
`Ctrl-R`：打开恢复会话选择器；`Ctrl-L`：压缩对话上下文
`Ctrl-O`：打开推理详情；`Ctrl-Alt-O`：打开整个回合检查器
`Alt-V`（macOS 为 `Option-V`）：打开工具/子代理卡片的详情分页器
`Ctrl-Shift-E` / `Cmd-Shift-E`：切换文件树侧栏
`Alt-1`--`Alt-8`：派发热键栏槽位 1--8
`Alt-!` / `Alt-@` / `Alt-#` / `Alt-$`：切换工作栏面板（Tasks/Agents/Context/Pinned）
`Alt-P` / `Alt-A`：跳到 Plan / Work；`Alt-Y`：请求 Full Access（旧权限通道）
`Ctrl-X`：取消所有后台 shell 任务（活动侧栏）
`Esc`：关闭最上层弹窗 / 取消 slash 菜单 / 关闭提示

输入框（Composer）

`Enter`：空闲时发送；忙时排队；输入框为空时发送下一条排队跟进
`Shift+Enter` / `Alt+Enter` / `Ctrl+J`：插入换行而不发送
`Ctrl+Enter` / `Cmd+Enter`：引导当前回合
`Ctrl-U`：清空草稿（可用 `Ctrl-Z` 恢复）；`Ctrl-Z`：恢复被清空的草稿
`Ctrl-A` / `Ctrl-E` / `Home` / `End`：行首/行尾；`Ctrl+←/→`：按词移动
`↑` / `↓`：历史；`Shift+↑/↓`：浏览对话历史；`Alt-R`：搜索提示历史
`Ctrl-G` / `Ctrl-S`：暂存当前草稿（`/stash pop` 恢复）
`Tab`：slash 命令 / `@` 提及补全
`Ctrl-Shift-O` / `F4`：在 ` $VISUAL\` / \`$ EDITOR` 中打开草稿
`! command`：经正常审批/沙箱运行一条 shell 命令

转录（Transcript）

`↑` / `↓` / `j` / `k`：滚动一行；`PgUp` / `PgDn`：翻页；`Home`/`g` 顶部、`End`/`G` 底部
`Alt- $\` / \`Alt-$ `：在工具输出块之间跳转
`Esc Esc`：回溯到上一个用户消息（`←`/`→` 步进，`Enter` 回绕）
鼠标拖拽：选中转录文本；`Ctrl-C`：复制选中的 Codewhale 选区

选择器与审批弹窗

会话选择器（`Ctrl-R` / `/sessions`）：`↑/↓/j/k` 移动、`Enter` 恢复、`/` 搜索、`s` 排序、

`a` 切换当前/全部工作区、`e` 归档/恢复、`d` 删除（带确认）

审批弹窗：`y`/`Y` 批准一次、`a`/`A` 全部批准、`n`/`N`/`Esc` 拒绝、`e` 先编辑再运行
首次引导：`Enter` 下一步、`Esc` 上一步、`1`--`9` 选语言、`0`--`9` 选提供商、`y` 信任工作区、`n` 跳过

提供商与本地模型

Codewhale 默认且首选的提供商是 DeepSeek，但也支持其它托管与本地 OpenAI 兼容提供商。

官方 provider 注册表共 42 个（`ProviderKind::ALL`），包括 `deepseek`、`openai`、`anthropic`、

`openrouter`、`moonshot`、`siliconflow`、`volcengine`、`qianfan`、`xai`、`google`、`mistral`、

`together`、`fireworks`、`xiaomi-mimo`、`huggingface`、以及本地/自托管路由 `ollama`、

`ollama-cloud`、`vllm`、`sglang` 和 `custom` 等。完整清单见官方 `docs/PROVIDERS.md`。

选择提供商

CLI：`codewhale --provider <id>`
TUI：`/provider <id>` 或提供商选择器
环境变量：`CODEWHALE_PROVIDER=<id>`
配置：`provider = "<id>"`

`deepseek-cn` / `deepseek-china` 等是 `deepseek` 的旧别名。`deepseek-anthropic` 不是独立路由，

而是 `deepseek` 的一种 wire 方言（`wire = "anthropic"`，走 Anthropic Messages API）。

本地模型

**Ollama**：`/setup provider ollama`，默认 `http://localhost:11434/v1\`。
**vLLM**：`python -m vllm.entrypoints.openai.api_server --model <model> --port 8000`。
**SGLang**：自托管 OpenAI 兼容端点。
**DS4（DwarfStar）**：`/setup provider ds4`。

模型与思考强度

`/model` 选择模型，`/model auto` 让 Codewhale 每回合自动选择模型与思考等级（走本地启发式，

有 DeepSeek 路由模型时可用分类器）。

`Ctrl+T` 循环推理工作量，与 `/effort` 同一阶梯（`none|minimal|low|medium|high|xhigh|ultra|max|auto|off`）。

配置

配置文件位置

默认：`~/.codewhale/config.toml`
旧路径兼容：`~/.deepseek/config.toml`
覆盖：`codewhale --config <path>` 或 `CODEWHALE_CONFIG_PATH=<path>`（`--config` 优先）
环境变量在文件加载后应用。

项目级 overlay

当工作区包含 `<workspace>/.codewhale/config.toml` 时，其声明的安全字段会叠加到全局配置之上

（`--no-project-config` 可跳过）。它只能**收紧**而不能放松安全姿态，支持的关键字为 `model`、

`reasoning_effort`、`approval_policy`（只能更严）、`sandbox_mode`（只能更严）、`notes_path`、

`max_subagents`、`allow_shell`（`false` 可禁用，`true` 被忽略）。凭据、端点、provider、MCP、

hooks、skills 等始终留在用户全局配置。

Profiles 与环境变量

`--profile <NAME>` / `/profile <name>` 切换配置档。
常用环境变量：`CODEWHALE_PROVIDER`、`CODEWHALE_MODEL`、`CODEWHALE_BASE_URL`、

`CODEWHALE_SANDBOX_MODE` 等；旧 `DEEPSEEK_*` 前缀仍作为别名兼容。

更新检查

TUI 默认后台检查新版本，仅在确有新版本且资产完整时提示；离线静默失败。可用 ` $update$ check_for_updates = false`

关闭，或用 `check_interval_hours` 调整节流。Codewhale 从不自行安装------只告诉你「有新版本」。

技能（Skills）

Skills 是可选的可复用指令包，通常是一个 `SKILL.md` 文件，教 Codewhale 如何执行某类重复流程。

例如：调试、文档、数据可视化、最佳候选（best-of-n）、委派等。

`/skill <name>` 激活某个技能；裸 `/skills` 打开技能管理器（仅自有清单，不联网）。
`/skills <prefix>`、`/skills inspect`、`/skills --remote`、`/skills suggest <task>`、

`/skills sync` 用于文本/注册表路径；建议只排名远程目录，绝不安装或激活。

技能是窄的：应告诉模型遵循什么流程、收集什么证据、避开什么。它们不应藏匿凭据，

也不替代正常的仓库文档。

技能不扩大工具、审批或信任权限。

MCP / Hooks / 插件

MCP（外部工具服务器）

```bash

codewhale mcp init # 生成起始配置

codewhale mcp add <name> --command "<cmd>" --arg "<arg>" # stdio 服务器

codewhale mcp add <name> --url "http://localhost:3000/mcp" # HTTP 服务器

codewhale mcp list / tools / enable / disable / remove / validate

```

TUI 内 `/mcp` 打开管理器，`/mcp reload` 热重载（重读配置并重连，无需重启）。MCP 工具以

`mcp_<server>_<tool>` 形式暴露，走与内置工具相同的审批流。

Codewhale 自身也可作为 MCP 服务器运行：`codewhale mcp-server`（stdio）。

Hooks（钩子）

在 `~/.codewhale/config.toml` 中启用并声明：

```toml

hooks

enabled = true

\[hooks.hooks\]

name = "announce"

event = "session_start"

command = "echo 'Codewhale session started'"

```

共 11 个事件，其中只有 3 个是「引导型」（能改变行为）：`message_submit`（可替换/阻断文本）、

`tool_call_before`（可允许/拒绝/询问、改写输入）、`shell_env`（注入环境变量）。其余

（`session_start`、`session_end`、`tool_call_after`、`mode_change`、`on_error`、`turn_end`、

`subagent_spawn`、`subagent_complete`）为观察者（observer）------结果被忽略，非零退出只记警告。

注意：观察者钩子仍是「以你的凭据运行的任意 shell 命令」，只是不能改变 Codewhale 接下来的行为。

插件（Plugins）

`/plugin install <spec>` 支持三种来源：

```text

/plugin install ./path/to/bundle # 本地目录（复制）

/plugin install github:owner/repo # GitHub 默认分支归档

/plugin install https://example.com/x.tar.gz # 直链 tarball

```

安装**从不激活任何东西**：先落盘到 `~/.codewhale/plugins/<name>/`（默认禁用且未信任），

随后进入能力审查，依次 `/plugin trust <name> <token>`（哈希绑定的信任回执）、

`/plugin enable <name>`（激活）。内容或声明能力变化会使回执失效，插件回到未激活，需重新审查。

`/plugin update` 重新下载（哈希变化则信任回执自动失效），`/plugin uninstall` 需先 `disable`。

所有安装带 `.installed-from` 溯源标记，拒绝覆盖/删除无此标记的手工目录。

记忆（Memory）

记忆让模型拥有一个小型、持久、本地的偏好与约定存储（如「本仓库用 4 空格缩进」），

跨会话存活。默认**关闭**（opt-in）。

启用

```bash

export DEEPSEEK_MEMORY=on # 或 config.toml 中 $memory$ enabled = true

```

布局

```text

~/.codewhale/memory/

├── global/MEMORY.md # 用户级笔记（跟随你到处）

├── workspace/<id>/MEMORY.md # 仓库级笔记（按 git origin 哈希隔离）

└── index.sqlite3 # 可重建的 SQLite FTS5 缓存

```

启用后，系统提示会注入最多 32 条 / 12000 字符的记忆（标记为「不受信任的用户数据」）；

更深的记忆通过 `memory_search` / `memory_get` 工具检索。

三种添加方式

**输入框 `# ` 前缀**：以单个 `#`（非 `##`、非 `#!`）开头的行会被拦截并写入全局记忆，

**不会触发回合**。例如 `# remember to use 4-space indentation`。

**`/memory` 斜杠命令**：`/memory` 查看、`/memory clear` 清空、`/memory native status/search/remember/...`

管理原生存储。

**`remember` 工具**：启用记忆后模型获得 `remember` 工具，自动捕捉持久偏好（写入自动批准，

范围限定在用户自己的记忆文件）。

**不应写入记忆**：密钥/令牌、临时任务状态、对话片段、过长的指令（后者应放 `AGENTS.md` 或技能）。

存储完全在本地，永不上传云端。

子代理、Fleet 与并行任务

子代理（Sub-agents）

后台子代理 = 用 `agent` 工具派发的聚焦 worker。父会话给出任务后收到 agent id，可继续工作。

你通常无需直接调用工具，用自然语言请求并行即可：

```text

为 config crate 开一个只读探索者，为 TUI 的 provider 选择器开另一个。

两者都返回文件引用与风险后再规划修复。

```

**角色（role）**：

| 角色 | 姿态 | 典型用途 |

|------|------|----------|

| `worker` | 灵活，做父会话要求的事（默认） | 多步任务 |

| `scout` | 只读，快速定位代码 | 「找出 `Foo` 的所有调用点」 |

| `planner` | 只分析出方案，不执行 | 「设计迁移，先别动手」 |

| `reviewer` | 只读评分 | 「审计这个 PR 的 bug」 |

| `builder` | 落地一个已明确的最小改动 | 「把 `bar()` 改成 X」 |

| `verifier` | 跑测试/校验并汇报结果 | 「跑 workspace 测试」 |

| `consultant` | 短命、高推理的顾问 | 「这个设计还漏了什么？」 |

| `custom` | 显式窄工具白名单 | 手动挑选工具 |

（别名：`worker`=`general`；`scout`=`explore`；`planner`=`plan`；`reviewer`=`review`；

`builder`=`implementer`；`verifier`=`verify`；`consultant`=`oracle`/`advisor`。）

**委派转移的是工作，不是权限**：子代理的权限始终被父会话的姿态钳制，只读角色派发可写角色

时，其子代理仍会被降为只读。

**输出契约**：非 scout 子代理以五个 Markdown 标题结束（按序）：

`### SUMMARY`（做了什么）、`### EVIDENCE`（路径:行号引用）、`### CHANGES`（改动的文件）、

`### RISKS`（风险）、`### BLOCKERS`（阻塞，无则 "None."）。scout 只输出 `SUMMARY` 和 `EVIDENCE`。

Fleet（持久多 worker 控制面）

Fleet 是本地优先的持久多 worker 运行控制面------一个 fleet worker 就是一次无头 `codewhale exec`。

需要重试、休眠/重启后存活、远程执行、回执或账本审计时，用它而不是短命的 `agent` 扇出。

```sh

codewhale fleet init

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

codewhale fleet status

codewhale fleet inspect <worker-id>

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

```

状态存于 `.codewhale/fleet.jsonl`；`/fleet status` 与 `codewhale fleet status` 是同一命令的两个表面。

Worktree 隔离

对并行的编辑任务，可用独立 Git worktree 避免在同一工作区互相冲突（`/worktree`、

`/workspace worktrees`）。

工作流（Workflow）

> 普通多代理工作不需要 Workflow。在 Operate 下正常发消息即可；只有当**顺序阶段、门禁、

> 共享预算、重放或确定性 fan-in** 重要时，才用 Workflow。

`/workflow` 编排当前工作；`/workflows` 打开运行仪表盘（查看每次运行的分阶段、子代理、进度与取消）。
编写入口：`workflow` 工具接受 `plan`（结构化目标/阶段/子代理，推荐）、`script`（模型自有的短 JS）、

`source_path`（工作区里签入的 `.workflow.js` / `.workflow.ts`）。

Workflow 脚本是**纯协调器**：没有自己的文件系统或 shell，真实工作发生在它派发的子代理里。

单个运行最多 16 个并发代理、累计 1000 个代理。

本地 Web 客户端

```bash

codewhale web # 默认 http://127.0.0.1:7878

codewhale web --port 8788 # 换回环端口

```

`codewhale web` 打开内嵌的浏览器客户端，**始终**绑定 `127.0.0.1`，不能被改绑到局域网地址，

也不能关闭运行时鉴权。它能创建/选择/重命名/归档线程、开始/引导回合、中断工作、处理审批、回答运行时

用户输入。

**鉴权边界**：启动 URL 含一次性、短时效、随机的引导凭据，**不含**运行时 bearer token；回环请求用它

换取进程本地的 `HttpOnly`、`SameSite=Strict` cookie 后立即失效。重放、过期、畸形、非回环的引导尝试

一律关闭。**local 就是 local**：不要把端口暴露到公网、反向代理或隧道。

`codewhale app-server --mobile` / `--http` 是独立的部署与鉴权契约，操作前请读官方 `docs/RUNTIME_API.md`。

沙箱与安全边界

审批、工作区感知工具、操作系统命令包装器是**相互独立**的控制：一次审批不等于沙箱，选择

`workspace-write` 也不等于当前平台真的存在 OS 包装器。

| 机制 | 平台 | 选择方式 | 报告值 |

|------|------|----------|--------|

`sandbox_mode` 取值：`read-only` | `workspace-write` | `danger-full-access` | `external-sandbox`。

`danger-full-access` 与 `external-sandbox` 有意绕过本地包装器。Windows 当前不提供广告的 OS 沙箱；

审批规则与工作区感知的文件工具仍是独立控制。相关环境变量：`CODEWHALE_SANDBOX_MODE` 等。

用 `codewhale doctor` / `setup --status` 查看本地可用的包装器。

权限与授权顺序

Codewhale 组合了工具可用性、钩子、类型化权限规则、审批姿态、仓库策略与沙箱。**某一层的审批

不是全局通行证**：后续安全层仍可要求复审或阻断。交互引擎对模型请求的工具调用按以下顺序评估：

**有效配置与姿态**：用户设置、命令行/运行时覆盖、项目 overlay 在回合前解析；项目 overlay 只能收紧。
**模式与工具准入**：Plan 模式限制、输入解析错误、逐命令 deny/allow 列表、调用方限制等。
**`tool_call_before` 钩子**：前台钩子按 `deny > ask > allow` 折叠。
**注册工具基线**：工具的 `ApprovalRequirement` 确定其普通审批需求。
**类型化 `permissions.toml` 规则**：`deny` 阻断；`allow` 只能清除普通注册审批；

硬拒绝的前缀始终优先。

**Auto-review 策略与内置安全底线**：确定性阻断（发布类、破坏性后台/无头工作）不可绕过。
**仓库规则（repo law）**：受保护路径不变量只能加审批或阻断。
**人工审批**：拒绝即停止。
**工具权限与执行沙箱**：worker 权限信封、原生工具路径检查、OS/外部沙箱在执行时仍生效。

授权顺序的要点

顺序在类型化权限层之后是单调的：auto-review 与仓库规则只能收紧，不能把先前的阻断/审批变成未复审的执行。
`permissions.toml` 是活跃 `config.toml` 的姊妹文件；`/permissions` 报告其来源、匹配器、作用域。
子代理忠实继承会话姿态，而不是一个裸的「自动批准」位。

实用建议

**先小后大**：先用小范围改动验证理解，再扩展。
**明确验收标准**：告诉它「改完后要跑哪条测试、达到什么结果」。
**一次一件事**：请求聚焦，改动更可控。
**让它先给计划**：复杂任务可以要求「先说明方案，不要动手」。
**读它汇报的「未验证/待办」**：这部分往往是最需要你留意的风险点。
**调查与实现分开**：不熟悉的代码先探查、出方案，再动手。
**出问题时先 `codewhale doctor`**：诊断配置与 provider 状态，而不是盲目重试。

常见问题

**Q：Codewhale 会擅自改我不相关的东西吗？**

不会。它遵循「做当前请求要求的事，不多做」的原则；发现相邻问题时它会报告，而不是默默扩大范围。

**Q：它说「未验证」是什么意思？**

表示某个结果还没有被工具或测试确认，仍在进行或有待确认。此时任务尚未完成。

**Q：我可以让它只读不改吗？**

可以。切到 Plan 模式（只读），或直接说明「只读，不要修改任何文件」，或使用只读/评审类子代理。

**Q：Codewhale 只支持 DeepSeek 吗？**

不是。DeepSeek 是默认且首选路由，但也支持其它托管与本地 OpenAI 兼容提供商。用 `/provider` 或

`codewhale --provider <id>` 选择。

**Q：先选哪个模式？**

不熟悉的代码用 Plan，正常实现用 Work，只有信任的仓库需要自动执行时才用 Full Access。

**Q：为什么运行命令前它会询问？**

审批是安全模型的一部分。shell 命令、付费工具、写操作、工作区之外的行动都可能有副作用，

审批提示让你保持控制。

**Q：我的配置存在哪里？**

新配置在 `~/.codewhale/config.toml`；旧的 `~/.deepseek/config.toml` 仍兼容。工作区存在项目配置时，

overlay 也会影响行为。

**Q：如何控制成本？**

用 `/model auto` 路由，需要严格边界时选固定模型，长会话用 `/compact`。大任务先规划再实现，

避免在错误路径上消耗 token。

**Q：如何继续之前的工作？**

Codewhale 会保存会话。用会话选择器或 `resume`/`--continue`；要试探不同方向，先 `fork` 再改。

`/sessions` 选择器默认限定当前工作区，按 `a` 可查看所有工作区。

**Q：如何把会话交给 Web 应用继续？**

输入 `/rc` 或 `codewhale rc`，在系统浏览器批准一次性码。租约生效期间浏览器拥有新提示与审批，

终端是只读安全面；`/rc status` 看归属、`/rc stop` 归还终端、`/rc link` 打印会话链接。

**Q：模型「懵了」怎么办？**

停下来，重述目标、约束与当前证据。转录太长用 `/compact` 或开新会话并给简短交接；

若是运行问题，跑 `codewhale doctor`。

**Q：项目规则写进提示词还是文件？**

持久的项目规则用仓库文件（`AGENTS.md` 等），回合级意图用提示词。跨项目重复的流程考虑做成技能。

**Q：遇到不确定该怎么做的任务怎么办？**

描述目标和你关心的约束即可；Codewhale 会先探查、必要时先给计划或向你确认，而不是盲目动手。

社区与项目历史

**源码**：<https://github.com/Hmbown/CodeWhale\>（MIT 协议）
**Discord**：<https://discord.gg/37gfS3ksug\>
**微信**：添加 `hunterbown`，申请加入 Whale Brothers 群
**贡献**：缺 provider、工作流别扭、终端界面碍事，都可提 $issue$ (https://github.com/Hmbown/CodeWhale/issues)；

想改进就提 pull request。首次贡献欢迎，贡献者保留署名。

**历史**：Codewhale 起初名为 `deepseek-tui`，仍保留与之配置/会话的兼容性；如今不偏向任何提供商，

独立维护，不隶属于任何模型提供商。

> 本文档为使用入门，命令与快捷键以 TUI 内 `/help` 为准；完整权威文档见官方仓库 `docs/` 目录。