FAQ 常见问题
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.
01What is CodeWhale?+
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.02How do I install CodeWhale?+
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 ~/.codewhale/ automatically. See the full install guide for China mirrors, Docker, and troubleshooting.
03What's the difference between codewhale and codewhale-tui?+
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.04Is CodeWhale the same as DeepSeek TUI? What about the rename?+
codewhale. Legacy deepseek and deepseek-tui commands remain as compatibility shims — they still work. Config lives at ~/.codewhale/. 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.05How do I set my API key?+
# 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 ~/.codewhale/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.
06Which providers does CodeWhale support?+
CodeWhale ships with these built-in providers:
- DeepSeek — first-class, native API. Reasoning streaming, cache metrics, thinking effort control.
- OpenRouter — unified API for DeepSeek models and more.
- OpenAI, NVIDIA NIM, Novita, Fireworks, sglang, vLLM, Ollama
Set the corresponding env var (e.g. OPENROUTER_API_KEY) and your provider in ~/.codewhale/config.toml. Hugging Face, ZenMux, and self-hosted OpenAI-compatible endpoints are on the roadmap.
07How do I use OpenRouter with CodeWhale?+
# 1. Set your OpenRouter key export OPENROUTER_API_KEY=sk-or-v1-... # 2. In ~/.codewhale/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).
08Can I use self-hosted or local models (vLLM, Ollama, llama.cpp)?+
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.09What are Plan, Agent, and YOLO modes?+
- Plan — Read-only investigation. Can grep, read files, list directories, fetch URLs. Cannot write or execute shell.
- Agent — Default mode. Multi-step tool calling. Shell and side-effect tools require approval based on your approval_mode setting.
- YOLO — Auto-approves all operations and enables trust mode. Workspace boundaries lift. Use carefully.
Press Tab to cycle modes. Approval mode (suggest / auto / never) is orthogonal — you can be in Agent mode with auto-approval, for example.
10What is model auto-routing? What is Fin?+
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".
11What does /goal do?+
/goal is a simple goal-setter for the current session. It does not add another app mode; the mode switcher remains Plan, Agent, and YOLO. Track progress in #891.12Is my code safe? What sandboxing does CodeWhale use?+
--workspace. /trust lifts them. Approval mode is configurable per session. All credential/approval/elevation events are written to ~/.codewhale/audit.log.13How do MCP servers work?+
~/.codewhale/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.14How do I contribute?+
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.15I'm in China — how do I install? Downloads are slow.+
# 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.
16My API key was rejected or I get auth errors on first run.+
Run codewhale doctor — it checks API key, network, sandbox, and MCP servers. Full report is written to ~/.codewhale/doctor.log.
Common causes:
- Stale
DEEPSEEK_API_KEYin shell startup file — open a fresh shell or usecodewhale auth set - Key from wrong provider — make sure the key matches the provider you're using
- Network connectivity — check
curl https://api.deepseek.com/v1/models
17What is Model Lab? When will Hugging Face integration be available?+
18Why is token consumption so high? / Why is cache hit rate low?+
deepseek-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.19How do I update CodeWhale?+
# 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.
Didn't find your question?
Open an issue →