Codewhale 终端编程智能体实战指南：安装运行、安全授权模型与配置体系

Codewhale 是一款面向终端的开源编程智能体，使用 Rust 构建，MIT 协议发布，让 AI 智能体在你的本地机器上直接读取代码、编辑文件、运行命令并持续推进任务。本文基于仓库中的中文 README 及其引用的安装、授权顺序与配置文档展开，帮助读者完成从安装验证、日常使用、headless 执行到审批策略与沙箱边界配置的完整上手路径，并能读懂 Codewhale 的分层安全模型。

项目定位与代码组织

Codewhale 最初名为 deepseek-tui，至今仍保留与其配置和会话的兼容性；如今它不偏向任何模型提供商，由社区独立维护。项目描述自己为"面向终端的编程智能体，可与用户一起在公开协作中不断改进"。

从源码结构看，这是一个规模可观的 Rust workspace：Cargo.toml 声明了 21 个成员 crate（agent、app-server、cli、command-contract、config、core、execpolicy、hooks、lane、mcp、paths、protocol、release、secrets、state、telemetry、tools、tui、workflow、workflow-js 等），工作区版本为 0.9.11，edition 为 2024，并显式要求 Rust 1.88+（rust-version = "1.88"，因为代码大量使用了 1.88 才稳定的 let_chains）。用户实际安装的命令由 crates/cli 产出——该 crate 名为 codewhale-cli，编译出的二进制名为 codewhale，入口为 crates/cli/src/main.rs。几个对理解项目有帮助的细节：

• workspace 用 rusqlite（bundled 特性）内嵌 SQLite，预构建二进制不依赖系统 libsqlite3；
• 发布二进制走 --profile dist（fat LTO + strip + 单 codegen 单元），日常开发构建走 --release（thin LTO），这是为了平衡 68 万行级别 crate 的构建时长；
• 项目对 unicode-width 打了本地补丁（patches/unicode-width-0.2.2），让 CJK 终端下全角字符宽度计算正确，避免 TUI 渲染错位。

安装

最短路径：npm

npm install -g codewhale
codewhale

首次运行会引导连接模型提供商，也可以保持离线。npm 包的 postinstall 会下载与当前平台匹配的 codewhale 和 codew（同一运行时的便捷别名）两个预构建二进制，并按 SHA-256 清单校验后才放入 PATH。仓库中 npm/codewhale 目录就是该包装器的源码。

其他安装途径

README 指出 Codewhale 还支持 Cargo、Docker、Nix、Scoop、预构建压缩包、Android/Termux 和 CNB 镜像，完整细节在 docs/INSTALL.md。要点摘录：

• Cargo（任意 Tier-1 Rust 目标）：cargo install codewhale-cli --locked，要求 Rust 1.88+；Linux 上需先装 build-essential pkg-config libdbus-1-dev（libdbus-1 是 D-Bus 凭据存储的构建期依赖）；
• Nix：nix run github:Hmbown/CodeWhale -- --help，仓库根目录的 flake.nix 即其实现；
• 手动下载：官方发布物同时提供裸二进制和带 install.sh 的 .tar.gz/.zip 压缩包，均需用发布附带的 codewhale-artifacts-sha256.txt 校验；
• Linux x64/arm64 的发布资产是静态 musl 构建，无 glibc 版本下限，可跨 Ubuntu/Debian/RHEL/Alpine 运行；
• Termux/Android arm64 处于 preview 状态，不要拿 Linux arm64 压缩包塞进 Termux；
• FreeBSD 无预构建，走 cargo install 源码路径。

面向国内网络，docs/INSTALL.md 提供了 rustup 与 Cargo 镜像配置步骤，以及一组 npm 包装器的控制变量：

变量	作用
CODEWHALE_RELEASE_BASE_URL	覆盖下载根地址，跳过 GitHub 探测
CODEWHALE_USE_CNB_MIRROR=1	强制使用 CNB 第一方镜像（仅 Linux x64 / OpenHarmony x64）
CODEWHALE_VERSION	固定包装器下载的发布版本
CODEWHALE_GITHUB_REPO	指向某个 fork（owner/repo）
CODEWHALE_FORCE_DOWNLOAD=1	忽略缓存标记强制重新下载
CODEWHALE_DISABLE_INSTALL=1	完全跳过 postinstall 下载（CI 场景）
CODEWHALE_OPTIONAL_INSTALL=1	下载失败不使 npm install 报错

旧版 DEEPSEEK_TUI_* / DEEPSEEK_* 前缀的变量仍作为遗留别名被接受，但新自动化应只使用 CODEWHALE_* 名称。

Shell 补全

每种 shell 一条命令即可生成补全脚本（同时覆盖 codewhale 与 codew 两个命令名），codewhale completions 是等价别名：

codewhale completion bash|zsh|fish|powershell|elvish

脚本输出到 stdout，重定向到你 shell 的补全目录即可，例如 Bash：

mkdir -p ~/.local/share/bash-completion/completions
codewhale completion bash > ~/.local/share/bash-completion/completions/codewhale

注意：补全脚本是生成它的那个版本的命令面快照，升级 Codewhale 后应重新生成。

验证安装

codewhale --version
codewhale doctor        # 检查 API key、提供商、运行时与 PATH 完整性
codewhale doctor --json # 结构化输出，便于贴给社区求助

doctor 发现问题时以非零码退出并打印修复提示。

使用

TUI 交互模式

直接运行 codewhale 进入终端 UI，像与队友交流一样描述任务：

Fix the failing tests and explain what changed.

Codewhale 会读取代码仓库、编辑文件、运行命令、检查结果，并持续推进目标——由你决定授予它多少访问权限。/help 可查看全部命令与键盘快捷键；Ctrl+T 循环切换推理档位，Shift+Tab 循环切换审批姿态（Ask / Auto-Review / Full Access）。

Headless 执行：codewhale exec

不打开 TUI 也能跑任务，这在 CI 与脚本中尤其有用：

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

从源码看，exec 的参数面定义在 crates/tui/src/lib.rs 的 ExecArgs 中，关键参数包括：

• --auto：启用带工具的 agent 模式并自动批准工具调用。注意其明确注释：这不改变沙箱姿态、也不会提升被拒工具——沙箱提升必须显式用 --sandbox danger-full-access 或 --allow-sandbox-elevation；
• --model / --provider：按次覆盖模型与提供商（如 --provider openrouter），凭据仍从环境变量或配置解析；
• --reasoning-effort：取值 auto | off | low | medium | high | max；
• --sandbox：本次运行的沙箱策略，独立于 --auto；
• --allowed-tools / --disallowed-tools：按工具类别（Bash、File、Git 等，不区分大小写）白名单/黑名单，deny 优先；
• --resume <SESSION_ID> / --session-id / --continue：恢复历史会话或继续本工作区最近会话；
• --json 与 --output-format（text / stream-json）：机器可读输出；
• --max-turns：限制模型步数，防失控循环。

示例（摘自该参数结构体的 doc 注释）：

codewhale exec "explain this function"
codewhale exec --auto "list crates/ with ls"
codewhale exec --auto --output-format stream-json "fix the failing test"

模型自由切换

• 托管提供商与本地模型都可以：连接托管 API，或用 Ollama、vLLM、SGLang 跑本地模型；
• /model 在会话内切换提供商和模型；
• 所有提供商的接入方式与模型目录见 docs/PROVIDERS.md。

安全与授权模型

README 的安全立场很明确：Codewhale 运行在你的机器上，仅拥有你授予的访问权限；审批模式和仓库规则约束智能体行为，支持的平台上可选的操作系统沙箱提供更强的执行边界；未知模型价格保持显示为"未知"，而不会被误报为免费。

审批姿态与沙箱模式

配置文件中两组核心键（见 config.example.toml）：

allow_shell = true
approval_policy = "on-request" # on-request | untrusted | never
sandbox_mode = "workspace-write" # read-only | workspace-write | danger-full-access | external-sandbox

• Plan 模式是只读的；Ask、Auto-Review、Full Access 三种审批姿态的行为被清晰展示；
• /undo 撤销上一轮操作，/restore 可将工作区恢复到较早快照。快照机制由 [snapshots] 配置：每轮在 ~/.codewhale/snapshots/<project_hash>/<worktree_hash>/.git 的旁路 git 仓库中存 pre-turn/post-turn 快照，你自己的 .git 绝不被触碰；
• sandbox_network_access（默认 false）控制 workspace-write 沙箱下 shell 命令能否触网——被拒时会给出"仅本次调用提权"的提示，可改为整会话放行；
• Linux 上沙箱后端可为 Landlock 或 bubblewrap（prefer_bwrap），docs/SANDBOX.md 描述各平台的强制力与回退。

九层授权管线

一层批准不是万能通行证——docs/AUTHORIZATION_ORDER.md 完整记录了交互引擎评估模型发起的工具调用的顺序：

顺序	层	结果要点
1	生效配置与姿态	用户设置、命令行/运行时覆盖、项目 overlay 先于回合解析；项目 overlay 只能收紧不能放宽 approval_policy、sandbox_mode 或 shell 可用性
2	模式与工具准入	Plan 模式限制、解析错误、逐命令工具 deny/allow 列表在策略规则之前生效；同时出现在两个列表中的工具被拒绝
3	准备与 tool_call_before 钩子	前景钩子按 deny > ask > allow 折叠，无法产出裁决的严格匹配钩子失败关闭
4	注册工具基线	工具的 ApprovalRequirement 建立常规审批需求；非可绕过的注册保留项在可提示的姿态下保持强制
5	类型化 permissions.toml 规则	匹配 deny 阻断；匹配 allow 只能清除常规注册审批，不能清除钩子 ask；Full Access 不被降级成提示，但显式 deny 依然阻断
6	自动审查策略与内置安全底线	可追加提示或阻断，不能移除前序保留项
7	仓库法则	受保护路径不变量只能追加提示或阻断；Full Access 下此类提示变成硬阻断
8	人工审批	拒绝即停；批准仅授权本次计划调用
9	工具权限与执行沙箱	worker 权限信封、原生工具路径检查与所选 OS 沙箱在执行期仍然生效

排序在类型化权限层之后是单调的：后续层只能收紧，不能把此前的阻断或提示变回未审查执行。类型化规则的选择细则（来源层 User > Agent > BuiltinDefault、动作强度 deny > ask > allow、再比匹配器特异性）也在该文档中定义。permissions.toml 是用户 config.toml 的同级文件，目前没有项目级权限规则源；/permissions 命令可列出规则来源、匹配器、作用域。一个典型的规则示例（摘自 config.example.toml 注释）：

# ~/.codewhale/permissions.toml
[[rules]]
tool = "exec_shell"
command = "cargo test"
action = "ask"

[[rules]]
tool = "exec_shell"
command = "sed"
action = "deny"

[[rules]]
tool = "exec_shell"
command = "git status"
command_exact = true
workspace = "/absolute/path/to/project"
action = "allow"

这套合同有回归测试覆盖，例如 crates/execpolicy/tests/authorization_order.rs 验证硬前缀拒绝与 层 → 动作 → 特异性 → 审批模式 的优先级序列，可用 cargo test -p codewhale-execpolicy --test authorization_order --locked 复现。项目级 overlay 的单调性由 crates/config 中的测试 project_merge_only_tightens_approval_and_sandbox_policy 保证。更多背景见 docs/MODES.md 与 docs/CONFIGURATION.md。

扩展：MCP、技能、钩子与智能体团队

README 的第四个价值主张是"扩展你已有的智能体"：连接 MCP 服务器和技能、配置钩子，并把智能体角色作为可读文件保存在项目或个人设置中。

• MCP：docs/MCP.md；配置路径默认 ~/.codewhale/mcp.json；
• 钩子：docs/HOOKS.md。config.example.toml 中列出了全部 11 个生命周期事件（session_start、tool_call_before、shell_env 等），其中只有 message_submit、tool_call_before、shell_env 的结果能改变 Codewhale 的行为，其余是观察者；钩子仅在交互 TUI 及其驱动的引擎回合循环中触发，codewhale exec 与 workflow 工具不触发；
• 智能体团队：docs/FLEET.md。[fleet] 与 [fleets.<name>] 表配置成员身份、角色档案（manager/operator/scout/builder/reviewer/verifier/synthesizer/general 为内置角色），内置角色可被用户档案按 id 覆盖，优先级为"工作区 .codewhale/agents/*.toml > 配置文件 > 内置"；
• Workflow 编排：[workflow] 表控制自动启动、审批与并发上限（如 auto_start_read_only、require_approval_for_writes、max_concurrent）；
• 工具覆盖与插件：[tools] 表可把任意内置工具替换为自定义脚本/命令或整体禁用（脚本从 stdin 收 JSON 输入、向 stdout 返回 ToolResult），插件目录中的脚本被自动发现注册为模型可见工具。

配置体系速览

配置主文件为 ~/.codewhale/config.toml（旧 ~/.deepseek/ 文件仍作为兼容回退读取），完整加载规则（profiles、环境变量覆盖）见 docs/CONFIGURATION.md，仓库根目录的 config.example.toml 是一份逐段注释的活文档。与日常使用最相关的几段：

provider = "deepseek"
default_text_model = "deepseek-v4-pro"
reasoning_effort = "max"   # off | low | medium | high | max

skills_dir = "~/.codewhale/skills"
mcp_config_path = "~/.codewhale/mcp.json"
memory_path = "~/.codewhale/memory.md"

[tui]
locale = "auto"   # auto | en | ja | zh-Hans | zh-Hant | pt-BR | es-419 | vi | ko | ...
max_model_steps = 200        # 单回合模型步数上限（0 = 默认，1-100000）
turn_wall_clock_secs = 3600  # 单回合累计墙钟上限（不含等待人工审批的时间）

[features]
shell_tool = true
subagents = true
web_search = true
mcp = true
exec_policy = true

几个值得注意的设计点：

• 回合预算全部有限：max_model_steps、turn_wall_clock_secs、stream_max_content_mb、stream_max_duration_secs 默认与上限都是有限值，0 一律回退默认值，从机制上防止无界 agent 循环烧钱；
• 多环境 profiles：[profiles.work]、[profiles.dev] 等，用 --profile <name> 或环境变量选择；
• locale 只影响 TUI 界面文案，不改变模型输出语言；zh-Hans 对应简体中文界面；
• 遥测默认关闭：需要配置文件 telemetry = true 与首次运行通知选择 Enable 同时成立才会收集，且仓库内文件明确列出了永不收集的内容清单（提示词、完成结果、工具参数、diff、文件内容、路径、API key 等）；
• 项目 overlay（<workspace>/.codewhale/config.toml）只能把审批与沙箱姿态往更严格的方向调，不能添加凭据、钩子或项目级 permissions.toml。

文档索引与参与

官方文档入口（均位于仓库 docs/ 目录）：

• docs/PROVIDERS.md — 提供商和本地模型
• docs/FLEET.md — 智能体团队
• docs/MCP.md、docs/HOOKS.md、docs/CONFIGURATION.md — MCP、钩子与配置
• docs/WEB.md — 本地 Web 客户端
• docs/AUTHORIZATION_ORDER.md — 授权顺序
• docs/INSTALL.md — 全平台安装与故障排查
• docs/ 目录下另有架构、记忆、沙箱、工作流等主题文档可继续深入

当缺少某个提供商、工作流体验不佳或终端界面妨碍使用时，可以提交 issue 反馈；知道如何改进则欢迎提交 pull request（流程见 CONTRIBUTING.md），贡献者会保留已合入工作的署名。项目采用 MIT 许可证，从其他开源项目改编的部分记录在 docs/THIRD_PARTY_NOTICES.md，贡献者名单见 docs/CONTRIBUTORS.md。