返回 CodeWhale
page.tsx
根目录 / web / app / [locale] / faq / page.tsx
1 import Link from "next/link";
2 import { Seal } from "@/components/seal";
3 import { FaqSearch } from "@/components/faq-search";
4 import { buildPageMetadata } from "@/lib/page-meta";
5 import { FACTS } from "@/lib/facts.generated";
6
7 export async function generateMetadata({ params }: { params: Promise<{ locale: string }> }) {
8 const { locale } = await params;
9 const isZh = locale === "zh";
10 return buildPageMetadata({
11 path: "/faq",
12 locale,
13 title: isZh ? "常见问题 · Codewhale" : "FAQ · Codewhale",
14 description: isZh
15 ? "Codewhale 常见问题：安装、配置、提供商、模型、模式、安全与隐私。答案来自实际代码、文档和 GitHub 议题。"
16 : "Codewhale frequently asked questions: install, config, providers, models, modes, security, and privacy. Answers sourced from real code, docs, and GitHub issues.",
17 });
18 }
19
20 interface FaqItem {
21 q: string;
22 a: React.ReactNode;
23 sources?: string[];
24 }
25
26 const faqEn: FaqItem[] = [
27 {
28 q: "What is Codewhale?",
29 a: (
30 <>
31 Codewhale is a terminal-native coding agent that works across hosted and local models. It runs from the <code className="inline">codewhale</code> command, streams reasoning blocks, edits local workspaces with approval gates, and can route each turn to a configured model and thinking level. DeepSeek is the bundled default route, while OpenRouter, Anthropic, OpenAI-compatible services, and self-hosted runtimes use the same runtime and tools.
32 </>
33 ),
34 sources: ["README.md", "docs/ARCHITECTURE.md"],
35 },
36 {
37 q: "How do I install Codewhale?",
38 a: (
39 <>
40 <p className="mb-2">Published channels differ in timing and platform support:</p>
41 <pre className="code-block mb-2">
42 {`# npm (recommended — no Rust toolchain needed)
43 npm install -g codewhale
44
45 # Cargo (needs Rust 1.88+)
46 cargo install codewhale-cli --locked
47 cargo install codewhale-tui --locked
48
49 # Homebrew (macOS)
50 brew tap Hmbown/deepseek-tui && brew install deepseek-tui
51
52 # Direct download
53 # https://github.com/Hmbown/CodeWhale/releases`}
54 </pre>
55 <p>
56 Run <code className="inline">codewhale</code> to start. First run creates <code className="inline">~/.codewhale/</code> automatically. Legacy <code className="inline">~/.deepseek/</code> is still read as a compatibility fallback.
57 Android arm64 / Termux is preview support: npm works only when the
58 selected package version has matching Android assets in its GitHub Release.
59 See the <Link href="/install" className="body-link">full install guide</Link> for China mirrors, Docker, and troubleshooting.
60 </p>
61 </>
62 ),
63 sources: ["README.md", "docs/INSTALL.md", "#1860", "#1914"],
64 },
65 {
66 q: "What's the difference between codewhale and codewhale-tui?",
67 a: (
68 <>
69 <code className="inline">codewhale</code> is the dispatcher CLI — it manages config, auth, updates, and launches the TUI.
70 <code className="inline">codewhale-tui</code> is the terminal UI binary that runs the agent loop.
71 When you type <code className="inline">codewhale</code>, the dispatcher spawns <code className="inline">codewhale-tui</code> for you.
72 npm and release bundles install them together. Cargo users install the
73 <code className="inline">codewhale-cli</code> and <code className="inline">codewhale-tui</code> crates separately.
74 </>
75 ),
76 sources: ["README.md"],
77 },
78 {
79 q: "Is Codewhale the same as DeepSeek TUI? What about the rename?",
80 a: (
81 <>
82 Yes. Codewhale is the new name for what was previously called DeepSeek TUI.
83 The canonical command is now <code className="inline">codewhale</code>. Legacy <code className="inline">deepseek</code> and <code className="inline">deepseek-tui</code> commands remain as compatibility shims — they still work.
84 Config lives at <code className="inline">~/.codewhale/</code>. Legacy <code className="inline">~/.deepseek/</code> config is still read as a compatibility fallback, and <code className="inline">DEEPSEEK_*</code> env vars continue to work.
85 DeepSeek is not deprecated. The rename reflects a mission idea put in this version: Codewhale as an agentic terminal for open models across providers, not a narrowing away from DeepSeek.
86 </>
87 ),
88 sources: ["docs/REBRAND.md", "README.md"],
89 },
90 {
91 q: "How do I set my API key?",
92 a: (
93 <>
94 <pre className="code-block mb-2">
95 {`# Method 1: Environment variable
96 export DEEPSEEK_API_KEY=sk-...
97
98 # Method 2: Saved config (recommended — survives shell restarts)
99 codewhale auth set --provider deepseek --api-key sk-...
100
101 # Method 3: config.toml
102 # Add to ~/.codewhale/config.toml:
103 api_key = "sk-..."
104
105 # Check what's active:
106 codewhale auth status # shows config, keyring, and env-var state
107 codewhale doctor # full connectivity check`}
108 </pre>
109 <p>
110 Saved config keys take precedence over environment variables.
111 Use <code className="inline">codewhale auth clear --provider deepseek</code> to remove a saved key.
112 </p>
113 </>
114 ),
115 sources: ["#907", "#1545", "docs/CONFIGURATION.md"],
116 },
117 {
118 q: "Which providers does Codewhale support?",
119 a: (
120 <>
121 <p className="mb-2">Codewhale ships with {FACTS.providers.length} built-in provider routes:</p>
122 <ul className="list-disc pl-5 space-y-1 text-sm text-ink-soft mb-3">
123 <li><strong>DeepSeek</strong> — bundled default with a native API route, reasoning streaming, cache metrics, and thinking effort control.</li>
124 <li><strong>OpenRouter</strong> — unified API for DeepSeek models and other open-model routes.</li>
125 <li><strong>{FACTS.providers.length - 2} more routes</strong> — including OpenAI-compatible, Anthropic, OpenAI Codex, xAI, Moonshot/Kimi, Z.ai, MiniMax, StepFun, Volcengine Ark, Baidu Qianfan, Model Studio, NVIDIA NIM, Fireworks AI, Together AI, DeepInfra, SiliconFlow, Novita AI, Hugging Face, Arcee AI, AtlasCloud, and the keyless local endpoints SGLang, vLLM, and Ollama. <Link href="/models" className="body-link">The full list is generated from the provider registry</Link>.</li>
126 </ul>
127 <p>
128 Set the corresponding env var (e.g. <code className="inline">OPENROUTER_API_KEY</code>) and your provider in <code className="inline">~/.codewhale/config.toml</code>.
129 Self-hosted OpenAI-compatible endpoints are supported through the provider config.
130 </p>
131 </>
132 ),
133 sources: ["docs/CONFIGURATION.md", "#1978", "#1710"],
134 },
135 {
136 q: "How do I use OpenRouter with Codewhale?",
137 a: (
138 <>
139 <pre className="code-block mb-2">
140 {`# 1. Set your OpenRouter key
141 export OPENROUTER_API_KEY=sk-or-v1-...
142
143 # 2. In ~/.codewhale/config.toml:
144 [providers.openrouter]
145 api_key = "sk-or-v1-..."
146
147 # 3. Run with an OpenRouter model:
148 codewhale --model openrouter/deepseek/deepseek-v4-pro
149
150 # Or set it as default in config.toml:
151 default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
152 </pre>
153 <p>
154 OpenRouter uses the same reasoning/cache parser as the native DeepSeek provider.
155 Model IDs follow the <code className="inline">provider/model-id</code> pattern (e.g. <code className="inline">openrouter/deepseek/deepseek-v4-flash</code>).
156 </p>
157 </>
158 ),
159 sources: ["docs/CONFIGURATION.md", "#1978"],
160 },
161 {
162 q: "Can I use self-hosted or local models (vLLM, Ollama, llama.cpp)?",
163 a: (
164 <>
165 Yes. Use the <code className="inline">vllm</code>, <code className="inline">sglang</code>, or <code className="inline">ollama</code> providers with your local endpoint.
166 For OpenAI-compatible endpoints (llama.cpp server, text-generation-webui, Aphrodite, etc.), you can use the <code className="inline">openai</code> provider with a custom <code className="inline">base_url</code>.
167 Codewhale also respects <code className="inline">DEEPSEEK_ALLOW_INSECURE_HTTP=true</code> for local HTTP endpoints.
168 Hugging Face Inference Providers are also available through the <code className="inline">huggingface</code> provider. Broader Hub discovery, model cards, datasets, and Jobs belong to Model Lab.
169 </>
170 ),
171 sources: ["#574", "#1303", "docs/CONFIGURATION.md"],
172 },
173 {
174 q: "What are Plan, Act, and Operate modes?",
175 a: (
176 <>
177 <ul className="list-disc pl-5 space-y-2 text-sm text-ink-soft">
178 <li><strong>Plan</strong> — Read-only investigation. Can grep, read files, list directories, fetch URLs. Cannot write or execute shell.</li>
179 <li><strong>Act</strong> — Normal interactive coding. Tool availability and approval prompts follow the active configuration and permission posture.</li>
180 <li><strong>Operate</strong> — Direct tools follow the same permission, sandbox, shell, and safety rules as Act. Fleet workers are preferred for independent, parallel, background, or long-running work, but delegation is not mandatory. Workflow is optional for ordered phases and gates.</li>
181 </ul>
182 <p className="mt-2">
183 When the composer is idle, press <kbd className="font-mono text-xs px-1.5 py-0.5 hairline-t hairline-b hairline-l hairline-r">Tab</kbd> to cycle modes.
184 Press <kbd className="font-mono text-xs px-1.5 py-0.5 hairline-t hairline-b hairline-l hairline-r">Shift+Tab</kbd> to cycle the independent Ask / Auto-Review / Full Access permission posture; Plan remains read-only.
185 </p>
186 </>
187 ),
188 sources: ["docs/MODES.md"],
189 },
190 {
191 q: "What is model auto-routing? What is Fin?",
192 a: (
193 <>
194 <p className="mb-2">
195 Use <code className="inline">codewhale --model auto</code> or <code className="inline">/model auto</code> to let Codewhale decide how much model power each turn needs.
196 </p>
197 <p className="mb-2">
198 <strong>Fin</strong> is the fast non-thinking path (<code className="inline">deepseek-v4-flash</code> 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.
199 </p>
200 <p>
201 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 <code className="inline">model: "auto"</code>.
202 </p>
203 </>
204 ),
205 sources: ["README.md", "#1207"],
206 },
207 {
208 q: "What does /goal do?",
209 a: (
210 <>
211 <code className="inline">/goal</code> sets a goal for the current TUI session.
212 App-server clients can also persist a thread-scoped goal through the
213 <code className="inline">thread/goal/*</code> methods. It does not add another
214 app mode; the mode switcher remains Plan, Act, and Operate, while permission posture is selected independently.
215 Track progress in <a href="https://github.com/Hmbown/CodeWhale/issues/891" className="body-link">#891</a>.
216 </>
217 ),
218 sources: ["#891"],
219 },
220 {
221 q: "Is my code safe? What sandboxing does Codewhale use?",
222 a: (
223 <>
224 The Codewhale runtime, workspace state, and audit log stay on your machine.
225 Product telemetry is opt-in and off by default — nothing is collected until
226 you answer the first-run notice with Enable. An enabled session posts counts
227 and closed enums to the first-party endpoint{" "}
228 <code className="inline">https://telemetry.codewhale.net/v1/telemetry</code>,
229 a Cloudflare Worker whose full source is in the repo under{" "}
230 <code className="inline">telemetry-ingest/</code>. Its storage has no IP,
231 country, or geo column — structurally, not as a setting — nothing is logged,
232 and retention is a fixed three months. Set{" "}
233 <code className="inline">telemetry_endpoint = &quot;&quot;</code> to stay
234 enabled and contact nobody. It never carries prompts, file contents, paths,
235 repo names, or credentials (schema:{" "}
236 <code className="inline">docs/TELEMETRY.md</code>;
237 off with <code className="inline">codewhale config set telemetry false</code>
238 or <code className="inline">CODEWHALE_TELEMETRY=0</code>). There is no
239 mandatory hosted relay. The hosted
240 provider you select receives the prompt, project context, tool definitions,
241 and tool results required for that turn. Use a loopback local-model route to
242 keep model inference local.
243 OS command sandboxing is platform-specific: Codewhale uses <strong>Seatbelt</strong> on macOS when available. On Linux it uses <strong>bubblewrap</strong> only when <code className="inline">prefer_bwrap = true</code> and <code className="inline">/usr/bin/bwrap</code> is executable; otherwise commands have no Codewhale OS wrapper. Windows currently reports no OS sandbox.
244 Workspace boundaries default to <code className="inline">--workspace</code>. <code className="inline">/trust</code> lifts them.
245 Permission posture is configurable per session. Sensitive credential, approval, and elevation events are appended best-effort to <code className="inline">$CODEWHALE_HOME/audit.log</code> (default <code className="inline">~/.codewhale/audit.log</code>); write failures are logged.
246 </>
247 ),
248 sources: ["SECURITY.md", "docs/PROVIDERS.md", "docs/RUNTIME_API.md"],
249 },
250 {
251 q: "How do MCP servers work?",
252 a: (
253 <>
254 Codewhale is a bidirectional MCP client and server. Define servers in <code className="inline">~/.codewhale/mcp.json</code>.
255 Tools appear as <code className="inline">mcp_&lt;server&gt;_&lt;tool&gt;</code>. You can also expose Codewhale as an MCP server with <code className="inline">codewhale mcp</code>.
256 See the <Link href="/docs#mcp" className="body-link">docs page</Link> for configuration examples.
257 </>
258 ),
259 sources: ["docs/MCP.md"],
260 },
261 {
262 q: "How do I contribute?",
263 a: (
264 <>
265 No CLA required. Fork, branch with conventional commits (<code className="inline">feat:</code>, <code className="inline">fix:</code>, etc.), run the local checks, open a PR.
266 The maintainer reads everything personally. Start with issues labeled <code className="inline">good first issue</code>.
267 See the <Link href="/contribute" className="body-link">contribute page</Link> and <a href="https://github.com/Hmbown/CodeWhale/blob/main/CONTRIBUTING.md" className="body-link">CONTRIBUTING.md</a>.
268 </>
269 ),
270 sources: ["CONTRIBUTING.md"],
271 },
272 {
273 q: "I'm in China — how do I install? Downloads are slow.",
274 a: (
275 <>
276 Use mirror registries:
277 <pre className="code-block my-2">
278 {`# npm mirror
279 npm config set registry https://registry.npmmirror.com
280 npm install -g codewhale
281
282 # Cargo mirror (Tsinghua TUNA)
283 # Add to ~/.cargo/config.toml:
284 [source.crates-io]
285 replace-with = "tuna"
286 [source.tuna]
287 registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"`}
288 </pre>
289 <p>
290 Prebuilt binaries are also available from <a href="https://github.com/Hmbown/CodeWhale/releases" className="body-link">GitHub Releases</a>.
291 A maintained CNB mirror covers its documented targets; no Gitee mirror is advertised until one exists.
292 </p>
293 </>
294 ),
295 sources: ["README.md", "#1914", "docs/CNB_MIRROR.md"],
296 },
297 {
298 q: "Is codewhale.net the official site? What about mirrors?",
299 a: (
300 <>
301 <p className="mb-2">
302 <strong>codewhale.net</strong> and <strong>www.codewhale.net</strong> are the
303 official Codewhale sites, deployed on Cloudflare. The website source is open
304 and lives under <code className="inline">web/</code> in the{" "}
305 <code className="inline">Hmbown/CodeWhale</code> repository — anyone can
306 self-deploy it as a mirror.
307 </p>
308 <p className="mb-2">
309 All official releases and SHA-256 checksums are distributed exclusively through{" "}
310 <a href="https://github.com/Hmbown/CodeWhale/releases" className="body-link">GitHub Releases</a>.
311 The npm package downloads verified binaries from GitHub Releases.
312 </p>
313 <p className="mb-2">
314 A CNB mirror is maintained for users who cannot reliably reach GitHub
315 (<Link href="/docs#cnb-mirror" className="body-link">docs/CNB_MIRROR.md</Link>).
316 Cargo users can use the TUNA mirror for faster downloads in China.
317 </p>
318 <p>
319 Self-deployed website copies, mirror sites, and third-party packages are not
320 controlled by the Codewhale project. Verify download sources and checksums.
321 </p>
322 </>
323 ),
324 sources: ["#2624", "#3421", "docs/CNB_MIRROR.md"],
325 },
326 {
327 q: "My API key was rejected or I get auth errors on first run.",
328 a: (
329 <>
330 <p className="mb-2">Run <code className="inline">codewhale doctor</code> — it checks API key, network, sandbox, and MCP servers. Full report is written to <code className="inline">~/.codewhale/doctor.log</code>.</p>
331 <p className="mb-2">Common causes:</p>
332 <ul className="list-disc pl-5 space-y-1 text-sm text-ink-soft">
333 <li>Stale <code className="inline">DEEPSEEK_API_KEY</code> in shell startup file — open a fresh shell or use <code className="inline">codewhale auth set</code></li>
334 <li>Key from wrong provider — make sure the key matches the provider you're using</li>
335 <li>Network connectivity — check <code className="inline">curl https://api.deepseek.com/v1/models</code></li>
336 </ul>
337 </>
338 ),
339 sources: ["#907", "#1545"],
340 },
341 {
342 q: "What is Model Lab? What Hugging Face pieces are available?",
343 a: (
344 <>
345 The <code className="inline">huggingface</code> provider is the shipped OpenAI-compatible route for Hugging Face Inference Providers.
346 Model Lab is the planned open-model infrastructure layer for Hub discovery, model cards, datasets, safetensors adapters, and Jobs.
347 Track broader progress in <a href="https://github.com/Hmbown/CodeWhale/issues/1977" className="body-link">#1977</a>.
348 </>
349 ),
350 sources: ["#1977", "docs/MODEL_LAB.md"],
351 },
352 {
353 q: "Why is token consumption so high? / Why is cache hit rate low?",
354 a: (
355 <>
356 Codewhale sends substantial context (system prompt, project instructions, tool definitions) with each turn.
357 DeepSeek's prefix cache is used aggressively — the system prompt is layered to maximize cache hits.
358 If you see high token usage, check: are you using <code className="inline">deepseek-v4-pro</code> for simple queries better suited to Flash?
359 Model auto-routing (Fin) can help pick the right model per turn.
360 Cache hit rate depends on prompt stability — modifying the system prompt or switching models resets the cache.
361 </>
362 ),
363 sources: ["#1177", "#1818", "#743"],
364 },
365 {
366 q: "How do I update Codewhale?",
367 a: (
368 <>
369 <pre className="code-block mb-2">
370 {`# Release-binary updater (works for npm/release-binary installs)
371 codewhale update
372
373 # npm
374 npm install -g codewhale@latest
375
376 # Cargo
377 cargo install codewhale-cli --locked --force
378
379 # Homebrew
380 brew update && brew upgrade deepseek-tui`}
381 </pre>
382 <p>
383 If you installed via npm, <code className="inline">codewhale update</code> downloads the latest release binaries.
384 If a mirror is lagging, download directly from <a href="https://github.com/Hmbown/CodeWhale/releases" className="body-link">GitHub Releases</a>.
385 </p>
386 </>
387 ),
388 sources: ["README.md", "#1869", "#1914"],
389 },
390 ];
391
392 const faqZh: FaqItem[] = [
393 {
394 q: "Codewhale 是什么？",
395 a: (
396 <>
397 Codewhale 是一个可使用托管与本地模型的终端原生编程智能体。通过 <code className="inline">codewhale</code> 命令启动，流式输出推理块，在有审批门槛的情况下编辑本地工作区，并可为每个回合选择已配置的模型和推理深度。DeepSeek 是内置默认路由；OpenRouter、Anthropic、OpenAI 兼容服务与自托管运行时使用同一套运行时和工具。
398 </>
399 ),
400 sources: ["README.md", "docs/ARCHITECTURE.md"],
401 },
402 {
403 q: "如何安装 Codewhale？",
404 a: (
405 <>
406 <p className="mb-2">已发布渠道的更新时间与平台覆盖各不相同：</p>
407 <pre className="code-block mb-2">
408 {`# npm（推荐 — 无需 Rust 工具链）
409 npm install -g codewhale
410
411 # Cargo（需要 Rust 1.88+）
412 cargo install codewhale-cli --locked
413 cargo install codewhale-tui --locked
414
415 # Homebrew（macOS）
416 brew tap Hmbown/deepseek-tui && brew install deepseek-tui
417
418 # 直接下载
419 # https://github.com/Hmbown/CodeWhale/releases`}
420 </pre>
421 <p>
422 输入 <code className="inline">codewhale</code> 即可启动。首次运行会自动创建 <code className="inline">~/.codewhale/</code>。旧版 <code className="inline">~/.deepseek/</code> 仍会作为兼容回退读取。
423 Android arm64 / Termux 仍是预览支持：只有当所选 npm 包版本对应的 GitHub Release 发布了匹配的 Android 资产时，npm 安装才可用。
424 查看 <Link href="/zh/install" className="body-link">完整安装指南</Link> 了解国内镜像、Docker 和故障排除。
425 </p>
426 </>
427 ),
428 sources: ["README.md", "docs/INSTALL.md", "#1860", "#1914"],
429 },
430 {
431 q: "codewhale 和 codewhale-tui 有什么区别？",
432 a: (
433 <>
434 <code className="inline">codewhale</code> 是调度 CLI——管理配置、认证、更新，并启动 TUI。
435 <code className="inline">codewhale-tui</code> 是运行智能体循环的终端 UI 二进制文件。
436 当你输入 <code className="inline">codewhale</code> 时，调度器会自动为你启动 <code className="inline">codewhale-tui</code>。
437 npm 与发布归档会同时安装两者。Cargo 用户需要分别安装
438 <code className="inline">codewhale-cli</code> 与 <code className="inline">codewhale-tui</code> crate。
439 </>
440 ),
441 sources: ["README.md"],
442 },
443 {
444 q: "Codewhale 和 DeepSeek TUI 是什么关系？改名是怎么回事？",
445 a: (
446 <>
447 Codewhale 是 DeepSeek TUI 的新名称。当前的主命令是 <code className="inline">codewhale</code>。旧的 <code className="inline">deepseek</code> 和 <code className="inline">deepseek-tui</code> 命令作为兼容垫片继续有效。
448 配置存放在 <code className="inline">~/.codewhale/</code>。旧版 <code className="inline">~/.deepseek/</code> 配置仍会作为兼容回退读取，<code className="inline">DEEPSEEK_*</code> 环境变量继续有效。
449 DeepSeek 并未被弃用。改名是为了体现 Codewhale 更广泛的使命——成为面向所有提供商的开放模型智能体终端，而非弱化 DeepSeek 的地位。
450 </>
451 ),
452 sources: ["docs/REBRAND.md", "README.md"],
453 },
454 {
455 q: "如何设置 API 密钥？",
456 a: (
457 <>
458 <pre className="code-block mb-2">
459 {`# 方法 1：环境变量
460 export DEEPSEEK_API_KEY=sk-...
461
462 # 方法 2：保存在配置中（推荐 — 重启 Shell 后仍然有效）
463 codewhale auth set --provider deepseek --api-key sk-...
464
465 # 方法 3：config.toml
466 # 在 ~/.codewhale/config.toml 中添加：
467 api_key = "sk-..."
468
469 # 查看当前状态：
470 codewhale auth status # 显示配置、密钥环和环境变量状态
471 codewhale doctor # 完整连接检查`}
472 </pre>
473 <p>
474 配置中保存的密钥优先于环境变量。
475 使用 <code className="inline">codewhale auth clear --provider deepseek</code> 移除已保存的密钥。
476 </p>
477 </>
478 ),
479 sources: ["#907", "#1545", "docs/CONFIGURATION.md"],
480 },
481 {
482 q: "Codewhale 支持哪些提供商？",
483 a: (
484 <>
485 <p className="mb-2">Codewhale 内建 {FACTS.providers.length} 条提供商路由：</p>
486 <ul className="list-disc pl-5 space-y-1 text-sm text-ink-soft mb-3">
487 <li><strong>DeepSeek</strong> — 内置默认原生 API 路由，支持推理流、缓存指标和思考力度控制。</li>
488 <li><strong>OpenRouter</strong> — 统一 API，可访问 DeepSeek 和其他开放模型路由。</li>
489 <li><strong>另外 {FACTS.providers.length - 2} 条路由</strong>——包括 OpenAI 兼容、Anthropic、OpenAI Codex、xAI、Moonshot/Kimi、Z.ai、MiniMax、StepFun、Volcengine Ark、百度千帆、Model Studio、NVIDIA NIM、Fireworks、Together AI、DeepInfra、SiliconFlow、Novita、Hugging Face、Arcee AI、AtlasCloud，以及无需密钥的本地端点 SGLang、vLLM 和 Ollama。<Link href="/models" className="body-link">完整列表由提供商注册表生成</Link>。</li>
490 </ul>
491 <p>
492 设置对应的环境变量（如 <code className="inline">OPENROUTER_API_KEY</code>）并在 <code className="inline">~/.codewhale/config.toml</code> 中配置你的提供商。
493 自托管 OpenAI 兼容端点可通过 provider 配置接入。
494 </p>
495 </>
496 ),
497 sources: ["docs/CONFIGURATION.md", "#1978", "#1710"],
498 },
499 {
500 q: "如何使用 OpenRouter？",
501 a: (
502 <>
503 <pre className="code-block mb-2">
504 {`# 1. 设置 OpenRouter 密钥
505 export OPENROUTER_API_KEY=sk-or-v1-...
506
507 # 2. 在 ~/.codewhale/config.toml 中：
508 [providers.openrouter]
509 api_key = "sk-or-v1-..."
510
511 # 3. 使用 OpenRouter 模型运行：
512 codewhale --model openrouter/deepseek/deepseek-v4-pro
513
514 # 或在 config.toml 中设为默认：
515 default_text_model = "openrouter/deepseek/deepseek-v4-pro"`}
516 </pre>
517 <p>
518 OpenRouter 使用与原生 DeepSeek 提供商相同的推理/缓存解析器。
519 模型 ID 遵循 <code className="inline">provider/model-id</code> 格式（如 <code className="inline">openrouter/deepseek/deepseek-v4-flash</code>）。
520 </p>
521 </>
522 ),
523 sources: ["docs/CONFIGURATION.md", "#1978"],
524 },
525 {
526 q: "可以使用自托管或本地模型吗（vLLM、Ollama、llama.cpp）？",
527 a: (
528 <>
529 可以。使用 <code className="inline">vllm</code>、<code className="inline">sglang</code> 或 <code className="inline">ollama</code> 提供商连接本地端点。
530 对于 OpenAI 兼容端点（llama.cpp server、text-generation-webui 等），可以使用 <code className="inline">openai</code> 提供商并设置自定义 <code className="inline">base_url</code>。
531 Codewhale 也支持 <code className="inline">DEEPSEEK_ALLOW_INSECURE_HTTP=true</code> 用于本地 HTTP 端点。
532 Hugging Face Inference Providers 也可以通过 <code className="inline">huggingface</code> provider 使用。更完整的 Hub 发现、模型卡片、数据集和 Jobs 属于 Model Lab。
533 </>
534 ),
535 sources: ["#574", "#1303", "docs/CONFIGURATION.md"],
536 },
537 {
538 q: "Plan、Act、Operate 三种模式有什么区别？",
539 a: (
540 <>
541 <ul className="list-disc pl-5 space-y-2 text-sm text-ink-soft">
542 <li><strong>Plan（计划）</strong> — 只读调查。可以 grep、读文件、列目录、抓取 URL。不能写入或执行 Shell。</li>
543 <li><strong>Act（执行）</strong> — 常规交互式编码。工具是否可用以及何时请求批准，取决于当前配置和权限姿态。</li>
544 <li><strong>Operate（编排）</strong> — 直接工具遵循与 Act 相同的权限、沙箱、Shell 和安全规则。独立、并行、后台或长时间工作会优先交给 Fleet worker，但不强制委派；只有需要有序阶段和门禁时才需要 Workflow。</li>
545 </ul>
546 <p className="mt-2">
547 输入区空闲时，按 <kbd className="font-mono text-xs px-1.5 py-0.5 hairline-t hairline-b hairline-l hairline-r">Tab</kbd> 切换模式。
548 按 <kbd className="font-mono text-xs px-1.5 py-0.5 hairline-t hairline-b hairline-l hairline-r">Shift+Tab</kbd> 循环独立的 Ask / Auto-Review / Full Access 权限姿态；Plan 始终只读。
549 </p>
550 </>
551 ),
552 sources: ["docs/MODES.md"],
553 },
554 {
555 q: "什么是模型自动路由？Fin 是什么？",
556 a: (
557 <>
558 <p className="mb-2">
559 使用 <code className="inline">codewhale --model auto</code> 或 <code className="inline">/model auto</code> 让 Codewhale 为每个回合自动选择最合适的模型和推理深度。
560 </p>
561 <p className="mb-2">
562 <strong>Fin</strong> 是快速非推理路径（<code className="inline">deepseek-v4-flash</code>，推理关闭），用于路由决策、摘要、RLM 子任务、上下文维护等协调工作。在真实请求发送前，Fin 会做一个小的路由调用来选择具体的模型和推理级别。
563 </p>
564 <p>
565 简短简单的请求可以留在 Flash + 推理关闭的状态。编码、调试、发布工作、架构设计或安全审查则会提升到 Pro 和/或更高的推理级别。Fin 是 Codewhale 本地逻辑——上游 API 永远不会收到 <code className="inline">model: "auto"</code>。
566 </p>
567 </>
568 ),
569 sources: ["README.md", "#1207"],
570 },
571 {
572 q: "什么是 Goal 模式？现在可用吗？",
573 a: (
574 <>
575 <code className="inline">/goal</code> 为当前 TUI 会话设置目标，支持 <code className="inline">pause</code>、<code className="inline">resume</code>、<code className="inline">complete</code>、<code className="inline">blocked</code> 和 <code className="inline">clear</code> 控制。
576 App-server 客户端也可以通过 <code className="inline">thread/goal/*</code> 方法持久化线程范围的目标，支持 <code className="inline">set</code>、<code className="inline">get</code> 和 <code className="inline">clear</code>。
577 它不会新增一个应用模式；模式切换器仍然是 Plan、Act 和 Operate，权限姿态独立选择。
578 跟踪进展：<a href="https://github.com/Hmbown/CodeWhale/issues/891" className="body-link">#891</a>。
579 </>
580 ),
581 sources: ["#891"],
582 },
583 {
584 q: "我的代码安全吗？Codewhale 使用什么沙箱机制？",
585 a: (
586 <>
587 Codewhale 运行时、工作区状态与审计日志保留在你的机器上。产品遥测是可选加入且默认关闭的——
588 在你把首次运行提示回答为“启用”之前不会收集任何内容。启用后的会话会把计数与封闭枚举 POST 到第一方端点{" "}
589 <code className="inline">https://telemetry.codewhale.net/v1/telemetry</code>，
590 那是一个 Cloudflare Worker，完整源码就在仓库的 <code className="inline">telemetry-ingest/</code> 目录里。
591 它的存储中没有 IP、国家或任何地理位置列——这是结构上不存在，而不是某个开关——不写任何日志，保留期固定为三个月。
592 若想保持启用但不联系任何服务器，设置 <code className="inline">telemetry_endpoint = &quot;&quot;</code>。
593 它永远不会携带 prompt、文件内容、路径、仓库名或凭据（schema 见 <code className="inline">docs/TELEMETRY.md</code>；
594 可用 <code className="inline">codewhale config set telemetry false</code> 或
595 <code className="inline">CODEWHALE_TELEMETRY=0</code> 关闭）。也不要求经过托管中继。你选择的托管 provider 会收到本轮所需的
596 prompt、项目上下文、工具定义与工具结果。若要让模型推理也保持本地，请使用回环地址上的本地模型路由。
597 OS 命令沙箱因平台而异：macOS 在可用时使用 <strong>Seatbelt</strong>。Linux 仅在 <code className="inline">prefer_bwrap = true</code> 且 <code className="inline">/usr/bin/bwrap</code> 可执行时使用 <strong>bubblewrap</strong>；否则命令没有 Codewhale OS 包装器。Windows 当前报告无 OS 沙箱。
598 工作区边界默认为 <code className="inline">--workspace</code>。<code className="inline">/trust</code> 可解除边界。
599 权限姿态可按会话配置。敏感的凭证、审批和提权事件会尽力追加到 <code className="inline">$CODEWHALE_HOME/audit.log</code>（默认 <code className="inline">~/.codewhale/audit.log</code>）；写入失败会记录日志。
600 </>
601 ),
602 sources: ["SECURITY.md", "docs/PROVIDERS.md", "docs/RUNTIME_API.md"],
603 },
604 {
605 q: "MCP 服务器如何工作？",
606 a: (
607 <>
608 Codewhale 是双向 MCP 客户端和服务器。在 <code className="inline">~/.codewhale/mcp.json</code> 中定义服务器。
609 工具以 <code className="inline">mcp_&lt;server&gt;_&lt;tool&gt;</code> 形式呈现。你也可以通过 <code className="inline">codewhale mcp</code> 将 Codewhale 暴露为 MCP 服务器。
610 查看 <Link href="/zh/docs#mcp" className="body-link">文档页面</Link> 了解配置示例。
611 </>
612 ),
613 sources: ["docs/MCP.md"],
614 },
615 {
616 q: "如何参与贡献？",
617 a: (
618 <>
619 无需签署 CLA。Fork、用约定式提交（<code className="inline">feat:</code>、<code className="inline">fix:</code> 等）创建分支、通过本地检查、提交 PR。
620 维护者亲自阅读每一条内容。从标记为 <code className="inline">good first issue</code> 的议题开始。
621 查看 <Link href="/zh/contribute" className="body-link">贡献页面</Link> 和 <a href="https://github.com/Hmbown/CodeWhale/blob/main/CONTRIBUTING.md" className="body-link">CONTRIBUTING.md</a>。
622 </>
623 ),
624 sources: ["CONTRIBUTING.md"],
625 },
626 {
627 q: "我在国内，安装很慢怎么办？",
628 a: (
629 <>
630 使用镜像源：
631 <pre className="code-block my-2">
632 {`# npm 镜像
633 npm config set registry https://registry.npmmirror.com
634 npm install -g codewhale
635
636 # Cargo 镜像（清华 TUNA）
637 # 在 ~/.cargo/config.toml 中添加：
638 [source.crates-io]
639 replace-with = "tuna"
640 [source.tuna]
641 registry = "sparse+https://mirrors.tuna.tsinghua.edu.cn/crates.io-index/"`}
642 </pre>
643 <p>
644 也可以从 <a href="https://github.com/Hmbown/CodeWhale/releases" className="body-link">GitHub Releases</a> 直接下载预编译二进制。
645 维护中的 CNB 镜像覆盖其文档列出的目标；Gitee 镜像只有实际存在后才会对外展示。
646 </p>
647 </>
648 ),
649 sources: ["README.md", "#1914", "docs/CNB_MIRROR.md"],
650 },
651 {
652 q: "codewhale.net 是官方网站吗？镜像站点呢？",
653 a: (
654 <>
655 <p className="mb-2">
656 <strong>codewhale.net</strong> 和 <strong>www.codewhale.net</strong> 是
657 Codewhale 的官方站点，部署在 Cloudflare 上。网站源码存放于{" "}
658 <code className="inline">Hmbown/CodeWhale</code> 仓库的{" "}
659 <code className="inline">web/</code> 目录下，任何人都可自行部署为镜像。
660 </p>
661 <p className="mb-2">
662 所有正式发布和 SHA-256 校验文件仅通过{" "}
663 <a href="https://github.com/Hmbown/CodeWhale/releases" className="body-link">GitHub Releases</a> 分发。
664 npm 包从 GitHub Releases 下载经校验的二进制。
665 </p>
666 <p className="mb-2">
667 面向无法稳定访问 GitHub 的用户，提供 CNB 镜像（
668 <Link href="/docs#cnb-mirror" className="body-link">docs/CNB_MIRROR.md</Link>）。
669 Cargo 用户可使用 TUNA 镜像在国内加速下载。
670 </p>
671 <p>
672 自行部署的网站副本、镜像站和第三方包不受 Codewhale 项目控制。
673 请验证下载来源和校验和。
674 </p>
675 </>
676 ),
677 sources: ["#2624", "#3421", "docs/CNB_MIRROR.md"],
678 },
679 {
680 q: "首次运行时提示 API 密钥被拒绝或认证错误？",
681 a: (
682 <>
683 <p className="mb-2">运行 <code className="inline">codewhale doctor</code>——它会检查 API 密钥、网络、沙箱和 MCP 服务器。完整报告写入 <code className="inline">~/.codewhale/doctor.log</code>。</p>
684 <p className="mb-2">常见原因：</p>
685 <ul className="list-disc pl-5 space-y-1 text-sm text-ink-soft">
686 <li>Shell 启动文件中的 <code className="inline">DEEPSEEK_API_KEY</code> 已过期——打开新 Shell 或使用 <code className="inline">codewhale auth set</code></li>
687 <li>密钥来自错误的提供商——确保密钥与你使用的提供商匹配</li>
688 <li>网络连接问题——检查 <code className="inline">curl https://api.deepseek.com/v1/models</code></li>
689 </ul>
690 </>
691 ),
692 sources: ["#907", "#1545"],
693 },
694 {
695 q: "Model Lab 是什么？Hugging Face 哪些部分可用？",
696 a: (
697 <>
698 <code className="inline">huggingface</code> provider 是已经接入的 OpenAI 兼容 Hugging Face Inference Providers 路由。
699 Model Lab 是规划中的开放模型基础设施层：Hub 发现、模型卡片、数据集、safetensors 适配器和 Jobs。
700 更完整的进展见 <a href="https://github.com/Hmbown/CodeWhale/issues/1977" className="body-link">#1977</a>。
701 </>
702 ),
703 sources: ["#1977", "docs/MODEL_LAB.md"],
704 },
705 {
706 q: "为什么 token 消耗这么大？/ 缓存命中率为什么低？",
707 a: (
708 <>
709 Codewhale 每次请求都会发送大量上下文（系统提示、项目说明、工具定义）。
710 DeepSeek 的前缀缓存被积极使用——系统提示按最稳定的层级排列以最大化缓存命中。
711 如果你发现 token 使用量很高，请检查：是否在简单查询中使用了 <code className="inline">deepseek-v4-pro</code>（更适合用 Flash）？
712 模型自动路由（Fin）可以帮助为每个回合选择合适的模型。
713 缓存命中率取决于提示的稳定性——修改系统提示或切换模型会重置缓存。
714 </>
715 ),
716 sources: ["#1177", "#1818", "#743"],
717 },
718 {
719 q: "如何更新 Codewhale？",
720 a: (
721 <>
722 <pre className="code-block mb-2">
723 {`# 发布二进制更新器（适用于 npm/二进制安装）
724 codewhale update
725
726 # npm
727 npm install -g codewhale@latest
728
729 # Cargo
730 cargo install codewhale-cli --locked --force
731
732 # Homebrew
733 brew update && brew upgrade deepseek-tui`}
734 </pre>
735 <p>
736 如果通过 npm 安装，<code className="inline">codewhale update</code> 会下载最新发布二进制。
737 如果镜像延迟，请从 <a href="https://github.com/Hmbown/CodeWhale/releases" className="body-link">GitHub Releases</a> 直接下载。
738 </p>
739 </>
740 ),
741 sources: ["README.md", "#1869", "#1914"],
742 },
743 ];
744
745 export default async function FaqPage({ params }: { params: Promise<{ locale: string }> }) {
746 const { locale } = await params;
747 const isZh = locale === "zh";
748 const items = isZh ? faqZh : faqEn;
749
750 return (
751 <>
752 <section className="mx-auto max-w-[1400px] px-6 pt-12 pb-8">
753 <div className="flex items-baseline gap-4 mb-3">
754 <Seal char="问" />
755 <div className="eyebrow">{isZh ? "常见问题" : "FAQ"}</div>
756 </div>
757 <h1 className="font-display tracking-crisp">
758 {isZh ? (
759 <>常见问题 <span className="font-cjk text-indigo text-5xl ml-2">FAQ</span></>
760 ) : (
761 <>FAQ <span className="font-cjk text-indigo text-5xl ml-2">常见问题</span></>
762 )}
763 </h1>
764 <p className="mt-5 max-w-3xl text-ink-soft text-lg leading-[1.9] tracking-wide">
765 {isZh
766 ? "答案来自实际代码、文档、发布说明和 GitHub 议题。每个回答下方标注了信息来源。如有未覆盖的问题，请在 GitHub 上提交 Issue。"
767 : "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."}
768 </p>
769 </section>
770
771 <section className="mx-auto max-w-[1400px] px-6 pb-20">
772 <FaqSearch items={items} locale={locale} />
773
774 <div className="mt-12 text-center">
775 <p className="text-ink-soft text-sm mb-4">
776 {isZh
777 ? "没找到你的问题？"
778 : "Didn't find your question?"}
779 </p>
780 <a
781 href="https://github.com/Hmbown/CodeWhale/issues/new/choose"
782 className="inline-flex items-center gap-2 px-5 py-3 bg-ink text-paper font-mono text-sm uppercase tracking-wider hover:bg-indigo transition-colors"
783 >
784 {isZh ? "提交 Issue →" : "Open an issue →"}
785 </a>
786 </div>
787 </section>
788 </>
789 );
790 }
791
791 lines Plain Text