codewhale command, streams reasoning blocks, edits local workspaces with approval gates, and can auto-route each turn to the right model and thinking level. DeepSeek V4 is the first-class model path; OpenRouter is ready. Hugging Face, self-hosted, and other open-model surfaces are on the roadmap.
+
+ ),
+ sources: ["README.md", "docs/ARCHITECTURE.md"],
+ },
+ {
+ q: "How do I install CodeWhale?",
+ a: (
+ <>
+ Four paths, same result:
+
+{`# npm (recommended — no Rust toolchain needed)
+npm install -g codewhale
+
+# Cargo (needs Rust 1.88+)
+cargo install codewhale-cli --locked
+
+# Homebrew (macOS)
+brew tap Hmbown/deepseek-tui && brew install deepseek-tui
+
+# Direct download
+# https://github.com/Hmbown/CodeWhale/releases`}
+
+
+ Run codewhale to start. First run creates ~/.deepseek/ automatically.
+ See the full install guide for China mirrors, Docker, and troubleshooting.
+
codewhale is the dispatcher CLI — it manages config, auth, updates, and launches the TUI.
+ codewhale-tui is the terminal UI binary that runs the agent loop.
+ When you type codewhale, the dispatcher spawns codewhale-tui for you.
+ Both are installed together; you rarely need to think about the split.
+
+ ),
+ sources: ["README.md"],
+ },
+ {
+ q: "Is CodeWhale the same as DeepSeek TUI? What about the rename?",
+ a: (
+ <>
+ Yes. CodeWhale is the new name for what was previously called DeepSeek TUI.
+ The canonical command is now codewhale. Legacy deepseek and deepseek-tui commands remain as compatibility shims — they still work.
+ Config lives at ~/.deepseek/. DEEPSEEK_* env vars continue to work.
+ DeepSeek is not deprecated. The rename reflects CodeWhale's broader mission as the agentic terminal for open models across providers, not a narrowing away from DeepSeek.
+
+ ),
+ sources: ["docs/REBRAND.md", "README.md"],
+ },
+ {
+ q: "How do I set my API key?",
+ a: (
+ <>
+
+{`# Method 1: Environment variable
+export DEEPSEEK_API_KEY=sk-...
+
+# Method 2: Saved config (recommended — survives shell restarts)
+codewhale auth set --provider deepseek --api-key sk-...
+
+# Method 3: config.toml
+# Add to ~/.deepseek/config.toml:
+api_key = "sk-..."
+
+# Check what's active:
+codewhale auth status # shows config, keyring, and env-var state
+codewhale doctor # full connectivity check`}
+
+
+ Saved config keys take precedence over environment variables.
+ Use codewhale auth clear --provider deepseek to remove a saved key.
+
CodeWhale ships with these built-in providers:
+
+ Set the corresponding env var (e.g. OPENROUTER_API_KEY) and your provider in ~/.deepseek/config.toml.
+ Hugging Face, ZenMux, and self-hosted OpenAI-compatible endpoints are on the roadmap.
+
+{`# 1. Set your OpenRouter key
+export OPENROUTER_API_KEY=sk-or-v1-...
+
+# 2. In ~/.deepseek/config.toml:
+[providers.openrouter]
+api_key = "sk-or-v1-..."
+
+# 3. Run with an OpenRouter model:
+codewhale --model openrouter/deepseek/deepseek-v4-pro
+
+# Or set it as default in config.toml:
+default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
+
+
+ OpenRouter uses the same reasoning/cache parser as the native DeepSeek provider.
+ Model IDs follow the provider/model-id pattern (e.g. openrouter/deepseek/deepseek-v4-flash).
+
vllm, sglang, or ollama providers with your local endpoint.
+ For OpenAI-compatible endpoints (llama.cpp server, text-generation-webui, Aphrodite, etc.), you can use the openai provider with a custom base_url.
+ CodeWhale also respects DEEPSEEK_ALLOW_INSECURE_HTTP=true for local HTTP endpoints.
+ Full Hugging Face TGI/vLLM integration is on the roadmap.
+
+ ),
+ sources: ["#574", "#1303", "docs/CONFIGURATION.md"],
+ },
+ {
+ q: "What are Plan, Agent, and YOLO modes?",
+ a: (
+ <>
+ + Press Tab to cycle modes. + Approval mode (suggest / auto / never) is orthogonal — you can be in Agent mode with auto-approval, for example. +
+ + ), + sources: ["docs/MODES.md"], + }, + { + q: "What is model auto-routing? What is Fin?", + a: ( + <> +
+ Use codewhale --model auto or /model auto to let CodeWhale decide how much model power each turn needs.
+
+ Fin is the fast non-thinking path (deepseek-v4-flash with thinking off) used for routing decisions, summaries, RLM children, context maintenance, and other coordination work. Before the real turn is sent, Fin makes a small routing call to pick the concrete model and thinking level.
+
+ Short/simple turns can stay on Flash with thinking off. Coding, debugging, release work, architecture, or security review can move up to Pro and/or higher thinking. Fin is local to CodeWhale — the upstream API never receives model: "auto".
+
/goal command.
+ The current /goal is a simple goal-setter. The full Goal mode (autonomous multi-turn task execution with checkpoint/resume) is planned but not yet implemented.
+ Track progress in #891.
+
+ ),
+ sources: ["#891"],
+ },
+ {
+ q: "Is my code safe? What sandboxing does CodeWhale use?",
+ a: (
+ <>
+ CodeWhale runs entirely on your machine. No telemetry, no cloud processing of your code.
+ Sandbox backends: seatbelt (macOS), landlock (Linux), restricted tokens (Windows).
+ Workspace boundaries default to --workspace. /trust lifts them.
+ Approval mode is configurable per session. All credential/approval/elevation events are written to ~/.deepseek/audit.log.
+
+ ),
+ sources: ["SECURITY.md", "docs/ARCHITECTURE.md"],
+ },
+ {
+ q: "How do MCP servers work?",
+ a: (
+ <>
+ CodeWhale is a bidirectional MCP client and server. Define servers in ~/.deepseek/mcp.json.
+ Tools appear as mcp_<server>_<tool>. You can also expose CodeWhale as an MCP server with codewhale mcp.
+ See the docs page for configuration examples.
+
+ ),
+ sources: ["docs/MCP.md"],
+ },
+ {
+ q: "How do I contribute?",
+ a: (
+ <>
+ No CLA required. Fork, branch with conventional commits (feat:, fix:, etc.), run the local checks, open a PR.
+ The maintainer reads everything personally. Start with issues labeled good first issue.
+ See the contribute page and CONTRIBUTING.md.
+
+ ),
+ sources: ["CONTRIBUTING.md"],
+ },
+ {
+ q: "I'm in China — how do I install? Downloads are slow.",
+ a: (
+ <>
+ Use mirror registries:
+
+{`# npm mirror
+npm config set registry https://registry.npmmirror.com
+npm install -g codewhale
+
+# Cargo mirror (Tsinghua TUNA)
+# Add to ~/.cargo/config.toml:
+[source.crates-io]
+replace-with = "tuna"
+[source.tuna]
+registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"`}
+
+ + Prebuilt binaries are also available from GitHub Releases. + The Gitee mirror and CNB mirror may also be available. +
+ + ), + sources: ["README.md", "#1914", "docs/CNB_MIRROR.md"], + }, + { + q: "My API key was rejected or I get auth errors on first run.", + a: ( + <> +Run codewhale doctor — it checks API key, network, sandbox, and MCP servers. Full report is written to ~/.deepseek/doctor.log.
Common causes:
+DEEPSEEK_API_KEY in shell startup file — open a fresh shell or use codewhale auth setcurl https://api.deepseek.com/v1/modelsdeepseek-v4-pro for simple queries better suited to Flash?
+ Model auto-routing (Fin) can help pick the right model per turn.
+ Cache hit rate depends on prompt stability — modifying the system prompt or switching models resets the cache.
+
+ ),
+ sources: ["#1177", "#1818", "#743"],
+ },
+ {
+ q: "How do I update CodeWhale?",
+ a: (
+ <>
+
+{`# Release-binary updater (works for npm/release-binary installs)
+codewhale update
+
+# npm
+npm install -g codewhale@latest
+
+# Cargo
+cargo install codewhale-cli --locked --force
+
+# Homebrew
+brew update && brew upgrade deepseek-tui`}
+
+
+ If you installed via npm, codewhale update downloads the latest release binaries.
+ If a mirror is lagging, download directly from GitHub Releases.
+
codewhale 命令启动，流式输出推理块，在有审批门槛的情况下编辑本地工作区，并可为每个回合自动选择最合适的模型和推理深度。DeepSeek V4 是一级模型路径；OpenRouter 已就绪。Hugging Face、自托管等开放模型接口已在路线图中。
+
+ ),
+ sources: ["README.md", "docs/ARCHITECTURE.md"],
+ },
+ {
+ q: "如何安装 CodeWhale？",
+ a: (
+ <>
+ 四种方式，殊途同归：
+
+{`# 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 即可启动。首次运行会自动创建 ~/.deepseek/。
+ 查看 完整安装指南 了解国内镜像、Docker 和故障排除。
+
codewhale 是调度 CLI——管理配置、认证、更新，并启动 TUI。
+ codewhale-tui 是运行智能体循环的终端 UI 二进制文件。
+ 当你输入 codewhale 时，调度器会自动为你启动 codewhale-tui。
+ 两者同时安装；通常你不需要关心这个区别。
+
+ ),
+ sources: ["README.md"],
+ },
+ {
+ q: "CodeWhale 和 DeepSeek TUI 是什么关系？改名是怎么回事？",
+ a: (
+ <>
+ CodeWhale 是 DeepSeek TUI 的新名称。当前的主命令是 codewhale。旧的 deepseek 和 deepseek-tui 命令作为兼容垫片继续有效。
+ 配置仍然存放在 ~/.deepseek/。DEEPSEEK_* 环境变量继续有效。
+ DeepSeek 并未被弃用。改名是为了体现 CodeWhale 更广泛的使命——成为面向所有提供商的开放模型智能体终端，而非弱化 DeepSeek 的地位。
+
+ ),
+ sources: ["docs/REBRAND.md", "README.md"],
+ },
+ {
+ q: "如何设置 API 密钥？",
+ a: (
+ <>
+
+{`# 方法 1：环境变量
+export DEEPSEEK_API_KEY=sk-...
+
+# 方法 2：保存在配置中（推荐 — 重启 Shell 后仍然有效）
+codewhale auth set --provider deepseek --api-key sk-...
+
+# 方法 3：config.toml
+# 在 ~/.deepseek/config.toml 中添加：
+api_key = "sk-..."
+
+# 查看当前状态：
+codewhale auth status # 显示配置、密钥环和环境变量状态
+codewhale doctor # 完整连接检查`}
+
+
+ 配置中保存的密钥优先于环境变量。
+ 使用 codewhale auth clear --provider deepseek 移除已保存的密钥。
+
CodeWhale 内建以下提供商：
+
+ 设置对应的环境变量（如 OPENROUTER_API_KEY）并在 ~/.deepseek/config.toml 中配置你的提供商。
+ Hugging Face、ZenMux 和自托管 OpenAI 兼容端点正在路线图中。
+
+{`# 1. 设置 OpenRouter 密钥
+export OPENROUTER_API_KEY=sk-or-v1-...
+
+# 2. 在 ~/.deepseek/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）。
+
vllm、sglang 或 ollama 提供商连接本地端点。
+ 对于 OpenAI 兼容端点（llama.cpp server、text-generation-webui 等），可以使用 openai 提供商并设置自定义 base_url。
+ CodeWhale 也支持 DEEPSEEK_ALLOW_INSECURE_HTTP=true 用于本地 HTTP 端点。
+ 完整的 Hugging Face TGI/vLLM 集成正在路线图中。
+
+ ),
+ sources: ["#574", "#1303", "docs/CONFIGURATION.md"],
+ },
+ {
+ q: "Plan、Agent、YOLO 三种模式有什么区别？",
+ a: (
+ <>
+ + 按 Tab 切换模式。 + 审批模式（建议 / 自动 / 拒绝）是独立的——例如你可以在 Agent 模式下使用自动审批。 +
+ + ), + sources: ["docs/MODES.md"], + }, + { + q: "什么是模型自动路由？Fin 是什么？", + a: ( + <> +
+ 使用 codewhale --model auto 或 /model auto 让 CodeWhale 为每个回合自动选择最合适的模型和推理深度。
+
+ Fin 是快速非推理路径（deepseek-v4-flash，推理关闭），用于路由决策、摘要、RLM 子任务、上下文维护等协调工作。在真实请求发送前，Fin 会做一个小的路由调用来选择具体的模型和推理级别。
+
+ 简短简单的请求可以留在 Flash + 推理关闭的状态。编码、调试、发布工作、架构设计或安全审查则会提升到 Pro 和/或更高的推理级别。Fin 是 CodeWhale 本地逻辑——上游 API 永远不会收到 model: "auto"。
+
/goal 命令。
+ 当前的 /goal 是一个简单的目标设置器。完整的 Goal 模式（自主多回合任务执行，支持检查点/恢复）已规划但尚未实现。
+ 关注 #891 的进展。
+
+ ),
+ sources: ["#891"],
+ },
+ {
+ q: "我的代码安全吗？CodeWhale 使用什么沙箱机制？",
+ a: (
+ <>
+ CodeWhale 完全在你的机器上运行。无遥测，不会将你的代码上传到云端处理。
+ 沙箱后端：seatbelt（macOS）、landlock（Linux）、受限令牌（Windows）。
+ 工作区边界默认为 --workspace。/trust 可解除边界。
+ 审批模式可按会话配置。所有凭证/审批/提权事件写入 ~/.deepseek/audit.log。
+
+ ),
+ sources: ["SECURITY.md", "docs/ARCHITECTURE.md"],
+ },
+ {
+ q: "MCP 服务器如何工作？",
+ a: (
+ <>
+ CodeWhale 是双向 MCP 客户端和服务器。在 ~/.deepseek/mcp.json 中定义服务器。
+ 工具以 mcp_<server>_<tool> 形式呈现。你也可以通过 codewhale mcp 将 CodeWhale 暴露为 MCP 服务器。
+ 查看 文档页面 了解配置示例。
+
+ ),
+ sources: ["docs/MCP.md"],
+ },
+ {
+ q: "如何参与贡献？",
+ a: (
+ <>
+ 无需签署 CLA。Fork、用约定式提交（feat:、fix: 等）创建分支、通过本地检查、提交 PR。
+ 维护者亲自阅读每一条内容。从标记为 good first issue 的议题开始。
+ 查看 贡献页面 和 CONTRIBUTING.md。
+
+ ),
+ sources: ["CONTRIBUTING.md"],
+ },
+ {
+ q: "我在国内，安装很慢怎么办？",
+ a: (
+ <>
+ 使用镜像源：
+
+{`# 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 镜像也可能可用。 +
+ + ), + sources: ["README.md", "#1914", "docs/CNB_MIRROR.md"], + }, + { + q: "首次运行时提示 API 密钥被拒绝或认证错误？", + a: ( + <> +运行 codewhale doctor——它会检查 API 密钥、网络、沙箱和 MCP 服务器。完整报告写入 ~/.deepseek/doctor.log。
常见原因：
+DEEPSEEK_API_KEY 已过期——打开新 Shell 或使用 codewhale auth setcurl https://api.deepseek.com/v1/modelsdeepseek-v4-pro（更适合用 Flash）？
+ 模型自动路由（Fin）可以帮助为每个回合选择合适的模型。
+ 缓存命中率取决于提示的稳定性——修改系统提示或切换模型会重置缓存。
+
+ ),
+ sources: ["#1177", "#1818", "#743"],
+ },
+ {
+ q: "如何更新 CodeWhale？",
+ a: (
+ <>
+
+{`# 发布二进制更新器（适用于 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 直接下载。
+
+ {isZh + ? "答案来自实际代码、文档、发布说明和 GitHub 议题。每个回答下方标注了信息来源。如有未覆盖的问题，请在 GitHub 上提交 Issue。" + : "Answers sourced from real code, docs, release notes, and GitHub issues. Sources are cited below each answer. If your question isn't covered, open an issue on GitHub."} +
++ {isZh + ? "没找到你的问题？" + : "Didn't find your question?"} +
+ + {isZh ? "提交 Issue →" : "Open an issue →"} + +