模式Modes
三种运行模式——与审批系统正交。按 Tab 切换。
只读调查。可以 grep、读文件、列目录、抓取 URL——不能写入或执行 shell。
默认模式。多步工具调用。Shell 和有副作用的工具按 approval_mode 设置审批。
自动批准所有操作并启用信任模式。工作区边界解除。请谨慎使用。
工具Tools
精选工具集——设计思路详见 docs/TOOL_SURFACE.md。
审批与沙箱Approval
模式与审批是两个独立的维度。通过 /config 设置。
默认——按模式规则执行。危险操作前询问。
自动批准所有工具调用。等同于无信任的 YOLO。
阻止任何非安全 / 非只读操作。仅限调查。
沙箱： bwrap、landlock (Linux)、process_hardening、seatbelt (macOS)、seccomp. 工作区边界默认为 --workspace。/trust 可解除边界限制。
配置Configuration
# ~/.codewhale/config.toml api_key = "sk-..." base_url = "https://api.deepseek.com" default_text_model = "deepseek-v4-pro" [ui] default_mode = "agent" # plan | agent | yolo approval_mode = "suggest" # suggest | auto | never reasoning_effort = "high" # off | high | max [hooks] enabled = true default_timeout_secs = 30 [[hooks.hooks]] event = "session_start" # tool_call_before / tool_call_after / message_submit / mode_change / on_error / shell_env command = "~/.codewhale/hooks/pre.sh"
完整参考：config.example.toml。
MCP 服务器MCP
codewhale 双向支持模型上下文协议：作为客户端从 ~/.codewhale/mcp.json 加载服务器，同时也可作为服务器暴露工具 （codewhale mcp）。工具以 mcp_<server>_<tool> 形式呈现。
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me"]
},
"sqlite": {
"command": "uvx",
"args": ["mcp-server-sqlite", "--db-path", "./data.db"]
}
}
}技能Skills
技能是 ~/.codewhale/skills/<name>/ 下的一个文件夹，根目录包含 SKILL.md。Agent 启动时加载技能名称和描述， 在需要时通过 Skill 工具拉取完整内容。
Fin智能路由
Fin 是 CodeWhale 的模型自动路由层。它会分析每个任务的特征——复杂度、上下文大小、工具需求——然后自动将请求分发到最合适的模型后端。
轻量任务（文件查找、fetch、简单 shell 命令）自动路由到 flash 级模型，降低延迟与成本。
复杂推理、大型重构、多步规划自动升级到全尺寸推理模型。
提供商Providers
使用 codewhale auth set --provider <id> 切换。下表为 crates/tui/src/config.rs 中 ApiProvider 枚举的实时投影，目前共 12 个。
开放模型方向：CodeWhale 正在扩展对 OpenRouter、Hugging Face 和 自托管 模型的支持——从云端 API 到本地部署均可覆盖。