CodeWhale
常见问题

常见问题 FAQ

答案来自实际代码、文档、发布说明和 GitHub 议题。每个回答下方标注了信息来源。如有未覆盖的问题，请在 GitHub 上提交 Issue。

01CodeWhale 是什么？+
CodeWhale 是一个面向开源模型的终端原生编程智能体。通过 codewhale 命令启动，流式输出推理块，在有审批门槛的情况下编辑本地工作区，并可为每个回合自动选择最合适的模型和推理深度。DeepSeek V4 是一级模型路径；OpenRouter 已就绪。Hugging Face、自托管等开放模型接口已在路线图中。
来源:README.mddocs/ARCHITECTURE.md
02如何安装 CodeWhale？+

四种方式，殊途同归：

# npm（推荐 — 无需 Rust 工具链）
npm install -g codewhale

# Cargo（需要 Rust 1.88+）
cargo install codewhale-cli --locked

# Homebrew（macOS）
brew tap Hmbown/deepseek-tui && brew install deepseek-tui

# 直接下载
# https://github.com/Hmbown/CodeWhale/releases

输入 codewhale 即可启动。首次运行会自动创建 ~/.codewhale/。 查看 完整安装指南 了解国内镜像、Docker 和故障排除。

来源:README.md#1860#1914
03codewhale 和 codewhale-tui 有什么区别？+
codewhale 是调度 CLI——管理配置、认证、更新，并启动 TUI。codewhale-tui 是运行智能体循环的终端 UI 二进制文件。 当你输入 codewhale 时，调度器会自动为你启动 codewhale-tui。 两者同时安装；通常你不需要关心这个区别。
来源:README.md
04CodeWhale 和 DeepSeek TUI 是什么关系？改名是怎么回事？+
CodeWhale 是 DeepSeek TUI 的新名称。当前的主命令是 codewhale。旧的 deepseek 和 deepseek-tui 命令作为兼容垫片继续有效。 配置仍然存放在 ~/.codewhale/。DEEPSEEK_* 环境变量继续有效。 DeepSeek 并未被弃用。改名是为了体现 CodeWhale 更广泛的使命——成为面向所有提供商的开放模型智能体终端，而非弱化 DeepSeek 的地位。
来源:docs/REBRAND.mdREADME.md
05如何设置 API 密钥？+
# 方法 1：环境变量
export DEEPSEEK_API_KEY=sk-...

# 方法 2：保存在配置中（推荐 — 重启 Shell 后仍然有效）
codewhale auth set --provider deepseek --api-key sk-...

# 方法 3：config.toml
# 在 ~/.codewhale/config.toml 中添加：
api_key = "sk-..."

# 查看当前状态：
codewhale auth status # 显示配置、密钥环和环境变量状态
codewhale doctor # 完整连接检查

配置中保存的密钥优先于环境变量。 使用 codewhale auth clear --provider deepseek 移除已保存的密钥。

来源:#907#1545docs/CONFIGURATION.md
06CodeWhale 支持哪些提供商？+

CodeWhale 内建以下提供商：

  • DeepSeek — 一级支持，原生 API。推理流、缓存指标、思考力度控制。
  • OpenRouter — 统一 API，可访问 DeepSeek 等模型。
  • OpenAI、NVIDIA NIM、Novita、Fireworks、sglang、vLLM、Ollama

设置对应的环境变量（如 OPENROUTER_API_KEY）并在 ~/.codewhale/config.toml 中配置你的提供商。 Hugging Face、ZenMux 和自托管 OpenAI 兼容端点正在路线图中。

来源:docs/CONFIGURATION.md#1978#1710
07如何使用 OpenRouter？+
# 1. 设置 OpenRouter 密钥
export OPENROUTER_API_KEY=sk-or-v1-...

# 2. 在 ~/.codewhale/config.toml 中：
[providers.openrouter]
api_key = "sk-or-v1-..."

# 3. 使用 OpenRouter 模型运行：
codewhale --model openrouter/deepseek/deepseek-v4-pro

# 或在 config.toml 中设为默认：
default_text_model = "openrouter/deepseek/deepseek-v4-pro"

OpenRouter 使用与原生 DeepSeek 提供商相同的推理/缓存解析器。 模型 ID 遵循 provider/model-id 格式（如 openrouter/deepseek/deepseek-v4-flash）。

来源:docs/CONFIGURATION.md#1978
08可以使用自托管或本地模型吗（vLLM、Ollama、llama.cpp）？+
可以。使用 vllm、sglang 或 ollama 提供商连接本地端点。 对于 OpenAI 兼容端点（llama.cpp server、text-generation-webui 等），可以使用 openai 提供商并设置自定义 base_url。 CodeWhale 也支持 DEEPSEEK_ALLOW_INSECURE_HTTP=true 用于本地 HTTP 端点。 完整的 Hugging Face TGI/vLLM 集成正在路线图中。
来源:#574#1303docs/CONFIGURATION.md
09Plan、Agent、YOLO 三种模式有什么区别？+
  • Plan（计划） — 只读调查。可以 grep、读文件、列目录、抓取 URL。不能写入或执行 Shell。
  • Agent（代理） — 默认模式。多步工具调用。Shell 和有副作用的工具根据 approval_mode 设置审批。
  • YOLO（全权） — 自动批准所有操作并启用信任模式。工作区边界解除。请谨慎使用。

按 Tab 切换模式。 审批模式（建议 / 自动 / 拒绝）是独立的——例如你可以在 Agent 模式下使用自动审批。

来源:docs/MODES.md
10什么是模型自动路由？Fin 是什么？+

使用 codewhale --model auto 或 /model auto 让 CodeWhale 为每个回合自动选择最合适的模型和推理深度。

Fin 是快速非推理路径（deepseek-v4-flash，推理关闭），用于路由决策、摘要、RLM 子任务、上下文维护等协调工作。在真实请求发送前，Fin 会做一个小的路由调用来选择具体的模型和推理级别。

简短简单的请求可以留在 Flash + 推理关闭的状态。编码、调试、发布工作、架构设计或安全审查则会提升到 Pro 和/或更高的推理级别。Fin 是 CodeWhale 本地逻辑——上游 API 永远不会收到 model: "auto"。

来源:README.md#1207
11什么是 Goal 模式？现在可用吗？+
Goal 模式是未来的工作流/标签页方向，用于长时间运行的多步目标——不是当前的 /goal 命令。 当前的 /goal 是一个简单的目标设置器。完整的 Goal 模式（自主多回合任务执行，支持检查点/恢复）已规划但尚未实现。 关注 #891 的进展。
来源:#891
12我的代码安全吗？CodeWhale 使用什么沙箱机制？+
CodeWhale 完全在你的机器上运行。无遥测，不会将你的代码上传到云端处理。 沙箱后端：seatbelt（macOS）、landlock（Linux）、受限令牌（Windows）。 工作区边界默认为 --workspace。/trust 可解除边界。 审批模式可按会话配置。所有凭证/审批/提权事件写入 ~/.codewhale/audit.log。
来源:SECURITY.mddocs/ARCHITECTURE.md
13MCP 服务器如何工作？+
CodeWhale 是双向 MCP 客户端和服务器。在 ~/.codewhale/mcp.json 中定义服务器。 工具以 mcp_<server>_<tool> 形式呈现。你也可以通过 codewhale mcp 将 CodeWhale 暴露为 MCP 服务器。 查看 文档页面 了解配置示例。
来源:docs/MCP.md
14如何参与贡献？+
无需签署 CLA。Fork、用约定式提交（feat:、fix: 等）创建分支、通过本地检查、提交 PR。 维护者亲自阅读每一条内容。从标记为 good first issue 的议题开始。 查看 贡献页面 和 CONTRIBUTING.md。
来源:CONTRIBUTING.md
15我在国内，安装很慢怎么办？+
使用镜像源：
# npm 镜像
npm config set registry https://registry.npmmirror.com
npm install -g codewhale

# Cargo 镜像（清华 TUNA）
# 在 ~/.cargo/config.toml 中添加：
[source.crates-io]
replace-with = "tuna"
[source.tuna]
registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"

也可以从 GitHub Releases 直接下载预编译二进制。 Gitee 镜像和 CNB 镜像也可能可用。

来源:README.md#1914docs/CNB_MIRROR.md
16首次运行时提示 API 密钥被拒绝或认证错误？+

运行 codewhale doctor——它会检查 API 密钥、网络、沙箱和 MCP 服务器。完整报告写入 ~/.codewhale/doctor.log。

常见原因：

  • Shell 启动文件中的 DEEPSEEK_API_KEY 已过期——打开新 Shell 或使用 codewhale auth set
  • 密钥来自错误的提供商——确保密钥与你使用的提供商匹配
  • 网络连接问题——检查 curl https://api.deepseek.com/v1/models
来源:#907#1545
17Model Lab 是什么？Hugging Face 集成什么时候可用？+
Model Lab 是规划中的开放模型基础设施层：Hugging Face Hub API 用于模型发现、模型卡片、数据集、safetensors 适配器、推理提供商和 Jobs。 它尚未完全实现。关注 #1977 的进展。 目前，你可以通过 OpenRouter 提供商或自托管端点使用 Hugging Face 模型。
来源:#1977docs/MODEL_LAB.md
18为什么 token 消耗这么大？/ 缓存命中率为什么低？+
CodeWhale 每次请求都会发送大量上下文（系统提示、项目说明、工具定义）。 DeepSeek 的前缀缓存被积极使用——系统提示按最稳定的层级排列以最大化缓存命中。 如果你发现 token 使用量很高，请检查：是否在简单查询中使用了 deepseek-v4-pro（更适合用 Flash）？ 模型自动路由（Fin）可以帮助为每个回合选择合适的模型。 缓存命中率取决于提示的稳定性——修改系统提示或切换模型会重置缓存。
来源:#1177#1818#743
19如何更新 CodeWhale？+
# 发布二进制更新器（适用于 npm/二进制安装）
codewhale update

# npm
npm install -g codewhale@latest

# Cargo
cargo install codewhale-cli --locked --force

# Homebrew
brew update && brew upgrade deepseek-tui

如果通过 npm 安装，codewhale update 会下载最新发布二进制。 如果镜像延迟，请从 GitHub Releases 直接下载。

来源:README.md#1869#1914

没找到你的问题？

提交 Issue →