diff --git a/src/content/docs-lite/en/claude-code-other-models.md b/src/content/docs-lite/en/claude-code-other-models.md new file mode 100644 index 0000000..b573382 --- /dev/null +++ b/src/content/docs-lite/en/claude-code-other-models.md @@ -0,0 +1,42 @@ +# Use Claude Code with GLM, DeepSeek or Kimi + +ThinkWatch Lite connects Claude Code to a gateway on the same computer, which forwards each request to an upstream that serves the model asked for. A GLM, DeepSeek or Kimi model is either named in Claude Code, with `/model` or the model variables in `settings.json`, or reached by a routing rule that rewrites Claude's model names to it. All three providers offer an Anthropic-compatible address, so Claude Code's requests reach them without format conversion. + +## Before you start + +- ThinkWatch Lite, [installed](/docs/lite/install/), and Claude Code, run at least once. +- An API key from the provider. For GLM, a Z.ai or BigModel account with a GLM Coding Plan can sign in from the app instead. +- A Claude Pro or Max sign-in cannot serve as an upstream; once connected, Claude Code uses its gateway key instead. + +## Steps + +1. On the Upstreams page, choose **New upstream** and pick a **Service**: + - **DeepSeek** fills in `https://api.deepseek.com/anthropic` and the protocol. Enter the **API key**. + - GLM with a key: **Custom**, with `https://open.bigmodel.cn/api/anthropic` or `https://api.z.ai/api/anthropic` as the **Base URL**, **Protocol** set to **Anthropic Messages**, and the **API key**. + - GLM with an account: **Z.ai / BigModel account**. Select the **Account service**, tick **Acknowledge the notes above and continue signing in**, choose **Sign in** and authorize in the browser. The app creates an API key named `thinkwatch` on the account and saves the upstream. + - Kimi: **Custom**, with the Anthropic-compatible base URL from Kimi's documentation and **Protocol** set to **Anthropic Messages**. For Kimi For Coding, also turn on **Forward client identity**. + + **Check connection** verifies the address and key and fetches the model list at no cost. Choose **Next** twice, then **Create**. +2. On the Clients page, choose **Connect…** on the Claude Code row. The dialog lists the fields that change in `~/.claude/settings.json`: `env.ANTHROPIC_BASE_URL`, `env.ANTHROPIC_AUTH_TOKEN` (a new key named `claude-code`) and `env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`. Choose **Connect**. +3. Choose how the model is selected: + - **By name.** In Claude Code, `/model ` switches to the model, and `claude --model ` starts with it. To map Claude Code's model aliases to it, add these to the `env` block of `~/.claude/settings.json`; the Haiku one also runs background tasks. + + ```json + "ANTHROPIC_DEFAULT_OPUS_MODEL": "", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "" + ``` + + No routing rule is needed; the default route skips upstreams whose model list does not contain it. + - **By rewriting.** On the Routing page, open the `default` route and choose **Add rule**. With **Add condition**, add **Model** `claude-*`, and **Key** `claude-code` to leave other clients alone. Set **On match** to **Forward**, **Forward to** to the upstream, and **Change model to** under **Parameter rewrites** to the model ID. Choose **Add**, then **Save**. Claude Code keeps showing Claude's names. + +## Notes + +- **Format conversion.** Claude Code sends Anthropic Messages; with that protocol the request goes out unchanged, apart from identity fields such as `metadata.user_id`, which the gateway removes. Only an upstream in another format, such as an OpenAI-compatible address set to OpenAI Chat Completions, gets a converted request: Traffic marks it **Converted** and its details list any dropped fields. Web search, a server-side tool, cannot be converted and is not sent to such an upstream. **Auto-detect** does not recognize these addresses and forwards requests in the client's own format, which suits Claude Code but not Codex. +- **Forward client identity** is off by default, so upstreams see ThinkWatch's User-Agent and no client identity. Kimi For Coding, Bailian Coding Plan and similar upstreams accept only certain clients; with the switch on, they receive Claude Code's own User-Agent, identity headers such as `x-app` and the identity fields in the body, unaltered. +- **GLM Coding Plan.** An upstream on `api.z.ai` or `open.bigmodel.cn`, signed in or added with a key, shows its 5-hour and weekly limits, and the credits left on a plan billed in credits, in the Quota / billing column and in the menu bar or tray menu. +- **The /model list** shows gateway models only when their names contain `claude` or `anthropic`. Other models are typed by name, or added as one entry with `ANTHROPIC_CUSTOM_MODEL_OPTION`. +- **Cost.** A rewritten request is priced as the model actually sent. +- **Restore…** puts back only the fields the app wrote; model variables added by hand stay in `settings.json`. + +Related: [Features](/docs/lite/features/), [Use Codex with Claude, Gemini or a Chat Completions-only relay](/docs/lite/codex-other-models/), [Use Claude Desktop with third-party models](/docs/lite/claude-desktop-third-party-models/). diff --git a/src/content/docs-lite/en/claude-desktop-third-party-models.md b/src/content/docs-lite/en/claude-desktop-third-party-models.md new file mode 100644 index 0000000..3346239 --- /dev/null +++ b/src/content/docs-lite/en/claude-desktop-third-party-models.md @@ -0,0 +1,36 @@ +# Use Claude Desktop with third-party models + +ThinkWatch Lite connects Claude Desktop through its official third-party inference mode, with the gateway on the same computer as the inference provider. Claude Desktop accepts only model names that look like Claude's, so a routing rule rewrites those names to the model that serves the request, from GLM, DeepSeek, Kimi or any other upstream. A Claude Desktop managed by an organization is left unchanged. + +## Before you start + +- ThinkWatch Lite, [installed](/docs/lite/install/), and Claude Desktop on macOS or Windows, opened at least once. The third-party inference mode needs no Anthropic account. +- An upstream for the model, added on the Upstreams page. [Use Claude Code with GLM, DeepSeek or Kimi](/docs/lite/claude-code-other-models/) shows how for those three. + +## Steps + +1. On the Clients page, choose **Connect…** on the Claude Desktop row. The dialog lists four files, under `~/Library/Application Support` on macOS; on Windows, `Claude-3p` is under `%LOCALAPPDATA%` and `Claude` under `%APPDATA%`. + + | File | Change | + |---|---| + | `Claude-3p/configLibrary/7477a7c4-1ce0-4d3a-9b1e-7477a7c40001.json` | A configuration named ThinkWatch: `inferenceProvider` set to `gateway`, the gateway address, the key with the `x-api-key` scheme, `chatTabEnabled` and the model list `inferenceModels` | + | `Claude-3p/configLibrary/_meta.json` | Adds the ThinkWatch entry and points `appliedId` at it; other configurations stay | + | `Claude-3p/claude_desktop_config.json` | `deploymentMode` set to `3p`, nothing else | + | `Claude/claude_desktop_config.json` | `deploymentMode` set to `3p`; the MCP servers in it stay | + + `inferenceModels` receives the gateway's models whose names look like Claude's: `claude-` followed by `sonnet`, `opus`, `haiku` or `fable` and a version. When there are none, the notes say that `claude-sonnet-5` is written and give an example rule. Choose **Connect**. +2. On the Routing page, open the `default` route and choose **Add rule**. With **Add condition**, add **Model** `claude-*` and **Key** `claude-desktop`, the key named in the connect dialog. Set **On match** to **Forward** and **Forward to** to the upstream, and under **Parameter rewrites** enter the model ID in **Change model to**. Choose **Add**, then **Save**. +3. Quit Claude Desktop completely and open it again. If the sign-in page appears, choose to continue with the gateway there; this happens once. + +## Notes + +- **Managed by an organization.** A managed configuration overrides everything set on the computer: on macOS a `com.anthropic.claudefordesktop.plist` under `/Library/Managed Preferences`, on Windows the registry key `SOFTWARE\Policies\Claude` under `HKLM` or `HKCU`. The Clients page then offers no **Connect…**, and the details say "Claude Desktop on this computer is managed by an organization". +- **Model list.** `inferenceModels` is written when connecting and is not offered for update afterwards. After the gateway's models change, **Restore…** and connect again to refresh it. +- **Cloud providers.** When Claude Desktop uses Amazon Bedrock, Google Cloud Agent Platform or Microsoft Foundry through another configuration, the dialog says so: the ThinkWatch configuration is used while connected, and restoring switches back. For Bedrock it also offers **New Bedrock upstream…** with the previous settings. +- **History and web search.** Conversations in this mode are kept apart from the existing ones. Web search does not work through the gateway and needs its own setup. +- **Restore…** sets `deploymentMode` back in both files, removes the ThinkWatch entry from `_meta.json`, points `appliedId` back at the configuration used before if it still exists, and deletes the ThinkWatch configuration. +- **Checks.** The details report "Another configuration is in use in Claude Desktop" when another configuration has been applied in the app, and "Claude Desktop may still open in its usual mode" when `deploymentMode` is not `3p`. +- **By hand.** The same setup can be made in Claude Desktop: turn on Help → Troubleshooting → Enable Developer Mode, then open Developer → Configure Third-Party Inference. Choose the gateway provider, enter the gateway address and the key, set the authentication scheme to `x-api-key`, and click Apply Changes. +- **Cost.** A rewritten request is priced as the model actually sent. + +Related: [Features](/docs/lite/features/), [Use Claude Code with GLM, DeepSeek or Kimi](/docs/lite/claude-code-other-models/), [Install and update](/docs/lite/install/). diff --git a/src/content/docs-lite/en/codex-other-models.md b/src/content/docs-lite/en/codex-other-models.md new file mode 100644 index 0000000..a927202 --- /dev/null +++ b/src/content/docs-lite/en/codex-other-models.md @@ -0,0 +1,38 @@ +# Use Codex with Claude, Gemini or a Chat Completions-only relay + +ThinkWatch Lite connects Codex to a gateway on the same computer that accepts the OpenAI Responses API, the only format Codex uses with a custom provider. The gateway converts each request and its answer between Responses and the upstream's format: Anthropic Messages for Claude, Google Gemini, or OpenAI Chat Completions for a relay that offers nothing else. The model is named in Codex's configuration or set by a routing rule. + +## Before you start + +- ThinkWatch Lite, [installed](/docs/lite/install/). +- Codex, either the Codex CLI or the Codex in the ChatGPT desktop app, run at least once. +- An API key for Anthropic, Google Gemini or the relay. + +## Steps + +1. On the Upstreams page, choose **New upstream** and pick a **Service**: **Anthropic** for Claude, or **Google Gemini**; each fills in the address and protocol. For a relay, choose **Custom**, enter its **Base URL** without an endpoint path such as `/chat/completions`, and set **Protocol** to **OpenAI Chat Completions**. Enter the **API key**, choose **Check connection**, then **Next**. If the relay does not list its models, enter them one per line under **Manual list**. Choose **Next**, then **Create**. +2. On the Clients page, choose **Connect…** on the Codex row. The dialog shows the change to `~/.codex/config.toml`: + + | Field | Value | + |---|---| + | `model_provider` | `thinkwatch` | + | `model_providers.thinkwatch.base_url` | The gateway address with `/v1`, by default `http://127.0.0.1:8788/v1` | + | `model_providers.thinkwatch.wire_api` | `responses` | + | `model_providers.thinkwatch.experimental_bearer_token` | A new key named `codex` | + | `model_providers.thinkwatch.http_headers` | `X-ThinkWatch-Client = "codex"` | + | `name`, `requires_openai_auth`, `supports_websockets` in the same table | `ThinkWatch`, `false`, `false` | + + Choose **Connect**, then reopen the terminal. The ChatGPT desktop app reads the same file and picks up the change after a restart. +3. Name the model. Connecting leaves `model` as it was, so Codex keeps asking for the model it used before. Either: + - set `model = ""` at the top of `~/.codex/config.toml`, before the first `[section]`, or pass `-c model=` for a single run; or + - keep Codex's model and rewrite it: on the Routing page, open the `default` route and choose **Add rule**, add the conditions **Model** `gpt-*` and **Key** `codex`, set **On match** to **Forward** and **Forward to** to the upstream, and under **Parameter rewrites** enter the model ID in **Change model to**. Choose **Add**, then **Save**. + +## Notes + +- **Codex's model table.** Codex carries metadata for its own models, such as the context window, inside the program. A model it does not know, such as a Claude or Gemini model, runs on fallback metadata with a 272,000-token context window, and Codex warns: "Model metadata for `` not found. Defaulting to fallback metadata; this can degrade performance and cause issues." For a model with a smaller window, `model_context_window` in `config.toml` sets the window Codex assumes. The gateway's model list does not appear in Codex's model picker, as Codex expects a catalog in its own format. +- **Conversion.** Requests and streamed answers are converted in both directions. Traffic marks such requests **Converted**; fields the target format cannot carry are dropped and listed in the request details. Server-side tools such as web search run only at the provider they belong to and are dropped in conversion. Codex accepts only `responses` for `wire_api`, so this conversion is what makes a Chat Completions-only relay usable. +- **Credentials.** With `requires_openai_auth = false`, Codex authenticates to the gateway with its own key and sends no OpenAI key or ChatGPT token. A ChatGPT account signed in from the app can still serve the OpenAI models next to Claude or Gemini: each request goes to an upstream that lists the model asked for. +- **Sessions.** Codex lists sessions started before and after connecting separately. `codex resume -c model_provider=thinkwatch` continues an earlier session through the gateway. After **Restore…**, sessions started while connected can still be opened, and go straight to OpenAI. +- **Cost.** A rewritten request is priced as the model actually sent. + +Related: [Features](/docs/lite/features/), [Use Claude Code with GLM, DeepSeek or Kimi](/docs/lite/claude-code-other-models/), [Install and update](/docs/lite/install/). diff --git a/src/content/docs-lite/en/compare-cc-switch.md b/src/content/docs-lite/en/compare-cc-switch.md new file mode 100644 index 0000000..77281c1 --- /dev/null +++ b/src/content/docs-lite/en/compare-cc-switch.md @@ -0,0 +1,52 @@ +# ThinkWatch Lite vs CC Switch + +CC Switch and ThinkWatch Lite both connect AI coding clients such as Claude Code and Codex to different providers, and both are MIT-licensed. CC Switch switches providers by writing each client's configuration file, with an optional local proxy. ThinkWatch Lite points each client at a local gateway once, then switches, routes and records every request in the gateway, where credentials can be replaced and dangerous tool calls cut off. + +## How they work + +CC Switch keeps providers in its own database. Enabling one writes its address and key into the client's configuration, such as `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json` for Claude Code, or `~/.codex/auth.json` and `config.toml` for Codex. Claude Code picks up the change without a restart; most other clients need the client or its terminal restarted. + +Its local proxy mode, called routing in its manual, covers Claude Code, Codex, Gemini CLI and Grok Build. Turning it on writes the client's configuration to point at the proxy (`http://127.0.0.1:15721` by default); providers are then switched inside the proxy without restarting the client, and the configuration is restored when the proxy is turned off. Proxy request logs, failover and format conversion need this mode. + +ThinkWatch Lite runs a gateway, ThinkWatch Core, on the computer. The Clients page connects each client once, showing the full diff, backing up the original file and giving the client its own key. Upstreams, routing rules and failover then change in the gateway without touching the client's configuration. + +## Comparison + +A dash means the feature is not described in that product's documentation. + +| | CC Switch | ThinkWatch Lite | +|---|---|---| +| Clients | Claude Code, Claude Desktop, Codex, Gemini CLI, Grok Build, OpenCode, OpenClaw, Hermes Agent, Pi, MiniMax Code | In one step: Claude Code, Claude Desktop, Codex (also in the ChatGPT desktop app), opencode, Pi, oh-my-pi, Grok Build, Qwen Code, Hermes Agent, Zed, Aider, DeepSeek Harness. With instructions: Cursor, Continue, Antigravity CLI | +| Adding providers | More than 50 presets; `ccswitch://` links import providers, MCP servers, prompts and skills | Anthropic, OpenAI, Google Gemini, Amazon Bedrock, DeepSeek and Ollama in the service list, or any compatible endpoint; `thinkwatch://import` links from a relay or vendor pre-fill one upstream | +| Routing | In proxy mode, each client's requests go to its current provider; models can be mapped per provider | Ordered rules per key by model, API format, input tokens, tools, images, extended thinking and more; rules can rewrite the model | +| Failover | Queue in priority order with a circuit breaker (proxy mode) | Next upstream in the group when an attempt fails before the answer begins; a session stays on one upstream | +| Load balancing | — | Group strategies: in order, manual, round robin, lowest latency, lowest cost | +| API format conversion | Proxy mode: Claude Code to OpenAI Chat Completions or Responses; Codex to Chat Completions or Anthropic Messages | Among Anthropic Messages, OpenAI Chat Completions, OpenAI Responses and Gemini | +| Usage and cost | Requests, tokens, cache hit rate and estimated cost, from proxy logs or the clients' session logs; custom prices, optional sync from models.dev; quota and balance display | Tokens, cost and requests by period, model and upstream; LiteLLM prices refreshed daily, or custom price sheets; estimates marked, unpriced requests counted separately | +| Request details | Provider, model, tokens, cost, timing and status; parameters, a response summary and errors | Matched rule, each attempt with its status, request and response bodies, cost; full-text search; replay against another upstream | +| Outbound redaction and tool-call inspection | — | API keys, private keys, ID and bank card numbers replaced before a request leaves; tool calls that download and run code or send out credentials cut off. Both start by only recording | +| MCP and skills | One MCP server list synced to the selected clients; skills installed from GitHub or ZIP files | MCP servers of 13 clients side by side, copied or removed for 4; skills and hooks listed; all scanned for hidden characters, prompt injection, dangerous commands and overly broad permissions | +| Prompts | Prompt presets written to `CLAUDE.md`, `AGENTS.md` or `GEMINI.md` | — | +| Sessions | Reads the clients' own session files; search, resume in a terminal, delete | Requests that passed through the gateway grouped into sessions and replayed turn by turn | +| Subscription accounts | ChatGPT (Codex OAuth), GitHub Copilot and xAI accounts through its reverse proxies | ChatGPT and Z.ai / BigModel accounts as upstreams; Claude Pro or Max sign-in is not supported | +| Server and remote use | — (the proxy can listen on `0.0.0.0`; provider data syncs across devices through Dropbox, OneDrive, iCloud or WebDAV) | The gateway runs as a systemd service on a Linux server, managed from the app over an encrypted control channel | +| Platforms | Windows 10 or later; macOS 12 or later on Intel and Apple silicon, signed and notarized; Linux as deb, rpm or AppImage | macOS 12 or later on Apple silicon; Windows 10 21H2 or later on x64 and ARM64; Linux on x86_64 and aarch64 as an AppImage; not signed by Apple or Microsoft | +| License | MIT | MIT | + +## Which one fits + +- **CC Switch** is the more direct choice for switching among a few providers, starting from presets, and managing MCP servers, prompts and skills for several clients in one place. +- **ThinkWatch Lite** fits when the cost and destination of each request need to be visible, requests should follow routing rules, credentials in requests should not reach a relay, or the gateway should run on a server. + +## Using both + +Both apps write Claude Code's endpoint, `env.ANTHROPIC_BASE_URL` in `~/.claude/settings.json`, and Codex's `~/.codex/config.toml`. When both connect the same client they overwrite each other: the last write decides where the client sends requests, and each app's restore puts back the value it saved before its own change. + +They can run side by side when each client goes through only one of them, for example CC Switch for Gemini CLI or OpenClaw, which ThinkWatch Lite does not connect, and ThinkWatch Lite for Claude Code and Codex. To move a client from CC Switch to ThinkWatch Lite, turn off CC Switch's proxy for that client and stop switching its providers there, then connect it on the Clients page. To move it back, restore it on the Clients page first. + +## Notes + +- The description of CC Switch is based on its README, user manual and release notes for v3.20.4, as of October 2026 ([farion1231/cc-switch](https://github.com/farion1231/cc-switch)). Later versions may differ. +- The description of ThinkWatch Lite applies to version 2026.10.4. + +Related: [Features](/docs/lite/features/), [Install and update](/docs/lite/install/), [Connecting to a remote core](/docs/lite/remote-core/), [FAQ](/docs/lite/faq/). diff --git a/src/content/docs-lite/en/failover-and-load-balancing.md b/src/content/docs-lite/en/failover-and-load-balancing.md new file mode 100644 index 0000000..823c26d --- /dev/null +++ b/src/content/docs-lite/en/failover-and-load-balancing.md @@ -0,0 +1,35 @@ +# Fail over and balance load across relays and API keys + +ThinkWatch Lite turns each relay key into an upstream and puts several upstreams behind a group. A routing rule sends requests to the group, whose strategy sets the order of its members; when one fails before the answer starts, the gateway passes the request to the next without the client seeing the error. A conversation stays with the upstream that answered it while its prompt cache is worth keeping. + +## Before you start + +- ThinkWatch Lite, [installed](/lite/#install), with a client connected on the Clients page. This guide follows version 2026.10.4. +- The base URL and API keys of each relay. + +## Steps + +1. On the Upstreams page, choose **New upstream**. Under **Connection**, enter a **Name**, the **Base URL** and one **API key**, choose **Check connection**, then **Next** until **Create**. Repeat for each key: an upstream holds one key, and failover and pauses work per upstream. +2. On the Routing page, choose **New group** under **Groups**. Enter a **Name**, choose a **Strategy**, tick the upstreams under **Members**, drag them into order and choose **Create**. +3. Under **Routes**, open the route, choose **Edit…** on the rule that should use the group (usually **All requests (catch-all)**), select the group in **Forward to** and choose **Save** in both dialogs. +4. **Dry run** checks the result without sending anything. On the Traffic page, a request's **Routing** tab lists the upstreams it tried under **Attempts**. + +## Notes + +| Strategy | Order of the members | +|---|---| +| **In order** | As listed. | +| **Round robin** | Requests are distributed across the members in turn. | +| **Lowest latency** | Median time to first byte over each upstream's last 32 requests; an upstream with fewer than 3 samples ranks after. | +| **Lowest cost** | Input price of the requested model in each upstream's price sheet; free upstreams first, unpriced ones last. | +| **Manual** | The preferred upstream first, then the rest as listed. | + +A strategy only sets the order; every member remains available for failover. + +- **When the next upstream is tried.** Before anything has reached the client, the gateway moves on when the upstream cannot be reached or its credential cannot be read; answers 5xx, 429, 401, 403, 402 or 404; answers 400 or 422 with an error about an insufficient balance, a used-up quota or an unavailable model; or, in a streamed answer, reports an error before the first content, such as an overload. The gateway waits for that first content for up to **Wait for the answer to start** in Settings › Failover, 15 seconds by default. Other 4xx responses, and the last member's 4xx other than 429, go back to the client unchanged. +- **Pauses.** A failing upstream is paused for as long as Settings › Failover sets: by default 60 seconds after 3 **Consecutive failures**, doubling up to 600; 30 minutes for **Insufficient balance**; until the reset time, or 60 minutes, for **Quota used up**; the wait a rate-limited upstream asks for, up to 60 minutes. A rule with a single upstream is never held back, and when every member is paused they are tried anyway. +- **Sessions and prompt cache.** Within a turn, while the client sends tool results back, requests keep the rule chosen at the start of the turn and the upstream that answered. Across turns, a conversation stays with the upstream that answered last if that answer read or wrote at least 1,024 cached tokens within the last five minutes; moving would rebuild the cache at full price. Otherwise, or when that upstream is paused, the strategy orders the members again, which is when **Round robin** moves on. The **Conversation** line on a request's **Routing** tab shows when a request stayed. +- **Same model name.** Every member is asked for the model the client sent, or the name a rule rewrote it to. A member whose model list lacks it is skipped; one without a list is tried, and its 404 moves the request on. +- **Falling back to another model.** Add a rule with the condition **Selected upstream** set to the backup upstream, **On match** set to **Continue matching**, and its model in **Change model to** under **Parameter rewrites**. Such a rule is evaluated for each upstream as it is tried, failover included. The changed model no longer hits the cached prompt, and the request is priced by the name sent. + +Related: [Switch relays, upstreams or models without restarting Claude Code or Codex](/docs/lite/switch-upstreams-without-restart/), [Features](/docs/lite/features/#routing-and-failover), [Install and update](/docs/lite/install/). diff --git a/src/content/docs-lite/en/faq.md b/src/content/docs-lite/en/faq.md new file mode 100644 index 0000000..af3e54e --- /dev/null +++ b/src/content/docs-lite/en/faq.md @@ -0,0 +1,79 @@ +# ThinkWatch Lite FAQ + +Short answers to common questions about ThinkWatch Lite, as of version 2026.10.4. The details are in [Features](/docs/lite/features/) and [Install and update](/docs/lite/install/). + +## What is ThinkWatch Lite? + +ThinkWatch Lite is a desktop app that runs a local gateway for Claude Code, Codex and other AI clients on macOS, Windows and Linux. Each client is connected to the gateway once; upstreams and models then change in the gateway without touching the client's configuration. Every request is recorded with its route and cost, credentials can be replaced with placeholders before a request leaves the computer, and dangerous tool calls in an answer can be cut off before the client runs them. + +## Is ThinkWatch Lite free? + +Yes. ThinkWatch Lite and its gateway, ThinkWatch Core, are open source under the MIT license: free to use, modify and redistribute, commercially or not. The app needs no account. Requests are paid for at the upstreams they go to, such as an API provider or a relay. + +## Which clients does ThinkWatch Lite support? + +ThinkWatch Lite connects twelve clients in one step on its Clients page: Claude Code, Claude Desktop, Codex (including the Codex in the ChatGPT desktop app), opencode, Pi, oh-my-pi, Grok Build, Qwen Code, Hermes Agent, Zed, Aider and DeepSeek Harness. Cursor, Continue and Antigravity CLI come with step-by-step instructions and a key created for them. + +Other clients that use the Anthropic, OpenAI or Gemini API can use the gateway address, `http://127.0.0.1:8788` by default, with a key from the Keys page. + +## Which platforms does ThinkWatch Lite run on? + +ThinkWatch Lite runs on macOS 12 or later on Apple silicon, with no build for Intel Macs; on Windows 10 21H2 or later on x64 or ARM64, as an installer or a portable zip; and on Linux on x86_64 or aarch64 as an AppImage, from Ubuntu 22.04, Debian 12 or Fedora 36 onwards. + +On Windows, Claude Code and Codex installed inside WSL can be connected under WSL 1, or under WSL 2 with mirrored networking, which needs Windows 11 22H2 and WSL 2.0.5 or later. + +## Can ThinkWatch Lite use a Claude Pro or Max subscription? + +No. ThinkWatch Lite does not support Claude subscription sign-in, and its gateway rejects Claude subscription credentials. A connected Claude Code sends its requests with a gateway key instead; restoring Claude Code on the Clients page returns it to its own sign-in. + +Through the gateway, Claude Code can use an Anthropic API key, Amazon Bedrock, a relay, a ChatGPT account, or other providers' models through API format conversion. + +## Can ThinkWatch Lite use relays and Chinese models such as GLM, Kimi, Qwen or DeepSeek? + +Yes. Any service with an Anthropic, OpenAI or Gemini API can be an upstream: on the Upstreams page, choose **New upstream**, set **Service** to **Custom**, and enter the **Base URL** and **API key**. DeepSeek is in the Service list, and a Z.ai or BigModel account can be signed in directly, with its GLM Coding Plan quota shown in the app. + +Upstreams that accept only particular clients, such as Kimi For Coding or Bailian Coding Plan, need **Forward client identity** turned on in the upstream's connection settings; otherwise requests identify themselves as ThinkWatch. A custom price sheet covers a relay whose prices differ from the official ones, and a routing rule can rewrite the model name, in which case the request is priced by the name it was sent with. + +## How is ThinkWatch Lite different from CC Switch? + +CC Switch switches providers by writing each client's configuration file, and manages MCP servers, prompts and skills across clients. ThinkWatch Lite connects each client to a local gateway once, then routes, records and prices every request in the gateway, where credentials can be redacted and dangerous tool calls cut off. A detailed comparison is in [ThinkWatch Lite vs CC Switch](/docs/lite/compare-cc-switch/). + +## Does ThinkWatch Lite change client configuration files, and how are they restored? + +ThinkWatch Lite changes a client's configuration when the client is connected on the Clients page, and only the settings that point it at the gateway. Before anything is written, the page shows the full diff and backs up the original file. **Restore…** on a client, or **Restore all…**, puts the original values back. + +**Settings › Full uninstall** restores every connected client and should run before the app is removed: moving the app to the Trash, or deleting the AppImage or the portable folder, restores nothing. + +## Where does ThinkWatch Lite store data, and what does it connect to? + +Configuration, keys and request history stay on the computer: in `~/.thinkwatch` on macOS and Linux, in `%APPDATA%\ThinkWatch` for the Windows installer, and in the `data\` folder next to the program for the Windows portable copy. The gateway listens on `127.0.0.1` port 8788 by default. + +Besides the upstreams it forwards requests to, ThinkWatch Lite connects to GitHub to check for updates and to refresh LiteLLM's public price list once a day. Signing in to a ChatGPT or Z.ai account goes through their sign-in pages, and a remote core is contacted only when one is configured. + +## Does ThinkWatch Lite collect usage data? + +No. ThinkWatch Lite contains no analytics or telemetry and sends nothing about its use to the project. The update check downloads a small manifest from the project's GitHub releases, which GitHub counts like any other download; the automatic check can be turned off with **Check for updates automatically** in Settings › About. A diagnostics bundle from Settings › About is saved on the computer with keys and addresses redacted, and leaves it only if it is shared. + +## Why is ThinkWatch Lite not signed, and how can a download be verified? + +ThinkWatch Lite is not signed by a registered Apple developer, and its Windows builds are not code-signed, so the first launch needs one extra step. The Homebrew cask removes macOS's quarantine attribute itself; after installing from the disk image, run `xattr -dr com.apple.quarantine "/Applications/ThinkWatch Lite.app"`, or choose **Open Anyway** in System Settings › Privacy & Security after the first refused launch. On Windows, choose **More info**, then **Run anyway** in the SmartScreen warning. + +Each file on the [releases page](https://github.com/ThinkWatchProject/ThinkWatch-Lite/releases/latest) has a `.sha256` file beside it, checked with `shasum -a 256 -c` on macOS, `sha256sum -c` on Linux, or against the output of `Get-FileHash` on Windows. Updates installed by the app are verified against a key compiled into it, and the source code can be built locally. + +## Does switching upstreams lose Codex sessions? + +No. ThinkWatch Lite writes Codex's configuration once, with a model provider named `thinkwatch` that points at the gateway; upstreams then change in the gateway, so every session keeps the same provider and stays in Codex's list. Sessions from before Codex was connected are listed separately, and `codex resume -c model_provider=thinkwatch` continues one through the gateway. + +When a conversation moves to another upstream partway, reasoning sealed by the previous account cannot be read by the new one. When the new upstream rejects it, the gateway removes that sealed reasoning and sends the request once more, so the conversation continues with its messages and tool calls intact. + +## Can ThinkWatch Lite run on a server? + +Its gateway can. ThinkWatch Core runs as a systemd service on Linux on x86_64 or aarch64 with glibc 2.35 or later, such as Ubuntu 22.04 or Debian 12. The desktop app connects to it from **Settings › Connection** with **Add remote connection**, over a control channel encrypted and authenticated by a Noise handshake, and shows that server's traffic, cost and configuration. Clients on other machines are set up by hand with the server's gateway address and a gateway key. See [Server deployment](/docs/core/server-deployment/) and [Connecting to a remote core](/docs/lite/remote-core/). + +## How is ThinkWatch Lite updated and uninstalled? + +ThinkWatch Lite checks for a new version two minutes after it starts and once a day. Installed from the releases page, it updates itself with one press: it verifies the download and waits for the requests in progress to finish before restarting. A Homebrew installation updates through Homebrew instead, with `brew update && brew upgrade --cask thinkwatch-lite`. + +To uninstall, run **Settings › Full uninstall** first, which restores connected clients, turns off launch at login and can delete the data directory; then move the app to the Trash on macOS, or delete the AppImage on Linux or the portable folder on Windows. The Windows installer can also be removed through the system, which does the same restoring first. + +Related: [Features](/docs/lite/features/), [Install and update](/docs/lite/install/), [ThinkWatch Lite vs CC Switch](/docs/lite/compare-cc-switch/), [Connecting to a remote core](/docs/lite/remote-core/). diff --git a/src/content/docs-lite/en/features.md b/src/content/docs-lite/en/features.md index b7bebb4..0d17000 100644 --- a/src/content/docs-lite/en/features.md +++ b/src/content/docs-lite/en/features.md @@ -77,7 +77,7 @@ Plugins are short JavaScript files that change requests before they go to an ups ## Settings -Settings has six sections. Connection lists the local core and the saved remote cores, described in [Connecting to a remote core](/docs/lite/remote-core). General sets the language, the appearance, what the menu bar item shows on macOS, launch at login, whether notices arrive as system notifications, in the app only or not at all, and shows hidden guidance hints again. Listening sets who can reach the gateway (this machine only, the local network of a chosen interface, or every interface), its port and the allowed address ranges. Log retention sets how long request payloads and request records are kept, and a size cap for payloads. About shows the version, checks for updates and produces a diagnostics bundle with keys and addresses masked. Uninstall restores every connected client and removes the autostart entry, and is meant to be run before the app is deleted. +Settings has seven sections. Connection lists the local core and the saved remote cores, described in [Connecting to a remote core](/docs/lite/remote-core). General sets the language, the appearance, what the menu bar item shows on macOS, launch at login, whether notices arrive as system notifications, in the app only or not at all, and shows hidden guidance hints again. Listening sets who can reach the gateway (this machine only, the local network of a chosen interface, or every interface), its port and the allowed address ranges. Failover sets how long a failing upstream is paused before requests go to the next one: after how many consecutive failures, for how long, and separate pauses for an insufficient balance, a used-up quota and rate limits, and how long to wait for a streamed answer to start before trying the next upstream. Log retention sets how long request payloads and request records are kept, and a size cap for payloads. About shows the version, checks for updates and produces a diagnostics bundle with keys and addresses masked. Uninstall restores every connected client and removes the autostart entry, and is meant to be run before the app is deleted. ## Menu bar, system tray and notifications diff --git a/src/content/docs-lite/en/keep-api-keys-from-relays.md b/src/content/docs-lite/en/keep-api-keys-from-relays.md new file mode 100644 index 0000000..dd5f0e5 --- /dev/null +++ b/src/content/docs-lite/en/keep-api-keys-from-relays.md @@ -0,0 +1,34 @@ +# Keep the API keys in requests away from relays, and block dangerous tool calls + +A relay receives every request in full, including keys that end up in the conversation, such as a pasted `.env` file or a configuration file a tool has read. ThinkWatch Lite's outbound redaction finds such credentials before a request leaves the machine and, in **Replace** mode, sends placeholders such as `<>` in their place, restoring the real values where the answer repeats them. Tool-call inspection checks the tool calls that come back and, in **Cut off** mode, stops those that download and run code or send credentials out before the client can run them. + +## Before you start + +- ThinkWatch Lite, [installed](/lite/#install), with clients connected to the gateway. This guide follows version 2026.10.4. +- Both protections start in **Observe**: they record what they find and change nothing. **Off** checks nothing. + +## Steps + +1. Open the Security page. The **Log** tab lists every finding with its request; since both modes use the same rules, a few days in **Observe** show what **Replace** would change. +2. Open **Redaction**. Built-in rules turn on or off one at a time, and **Test…** shows **What is sent** for a pasted text. +3. For a key format the built-in rules do not cover, choose **New rule**, enter a **Name**, a pattern under **Match (regular expression)** and a **Placeholder name** such as `INTERNAL` (giving `<>`), then choose **Create**. +4. Set the mode at the top of the tab to **Replace**. +5. Open **Tool calls**. Each built-in rule is marked **Cut off** or **Record only**, which **View rule** can change. Set the mode to **Cut off**. +6. The log's **Action** column then shows **Replaced** or **Cut off**, and a cut-off call also raises a system notification. + +## Notes + +| Mode | Outbound redaction | Tool-call inspection | +|---|---|---| +| **Observe** (default) | Findings are recorded; the request is sent unchanged. | Matching calls are recorded and returned as usual. | +| **Replace** / **Cut off** | Findings are replaced with placeholders before sending and restored in the response. | Calls matching a **Cut off** rule never fully reach the client; **Record only** rules still only record. | + +- **What redaction covers.** The whole request, system prompt, earlier turns and tool calls included, except base64 data such as images. Built-in rules find API keys and tokens for Anthropic, OpenAI, GitHub, Slack, AWS (access key IDs), Google, GitLab, Stripe, npm, DigitalOcean and SendGrid, private keys, JWTs, passwords in connection strings, and Chinese resident ID and bank card numbers whose structure and check digit are valid. The rules for email addresses, Chinese mainland mobile numbers, internal IP addresses and internal domains start off. +- **How values come back.** A value keeps one placeholder throughout a request, on every upstream. Placeholders the model writes back, in text or tool-call arguments, are restored before the client receives them: a command using the key runs locally with the real value, while the relay sees only the placeholder. +- **What is cut off.** Calls that download or decode code and run it, send out environment variables or credential files, read private keys or cloud credentials, send a credential to an unknown host, or install startup items or scheduled jobs. Built-in rules for deleting home or root, world-writable permissions and uploading a local file only record. +- **What the relay still sees.** The key configured for its upstream in the app, and the rest of the request as written: code, file contents, the conversation. The key a client uses for the gateway is not forwarded, and neither is the client's identity unless **Forward client identity** is on for that upstream. +- **Rules, not judgement.** Only values that match a rule are replaced; a credential without a recognizable prefix, such as an AWS secret access key, needs a custom rule. A dangerous command written in a form no rule matches passes tool-call inspection. +- **Nothing beyond the gateway.** What a relay does on its own servers, such as keeping requests or answering with another model, is out of sight; the **Check-up** tab on the Upstreams page can show signs of the latter, not prove it. +- **The cost of acting.** Changed request content may miss the upstream's prompt cache, and a false match in **Cut off** stops the answer at that call. + +Related: [Features](/docs/lite/features/#security), including the third protection, the content filter; [Install and update](/docs/lite/install/). diff --git a/src/content/docs-lite/en/switch-upstreams-without-restart.md b/src/content/docs-lite/en/switch-upstreams-without-restart.md new file mode 100644 index 0000000..4df092f --- /dev/null +++ b/src/content/docs-lite/en/switch-upstreams-without-restart.md @@ -0,0 +1,35 @@ +# Switch relays, upstreams or models without restarting Claude Code or Codex + +ThinkWatch Lite points Claude Code and Codex at a gateway on the local machine once; from then on, the gateway decides which upstream and model each request goes to. Switching a relay, an upstream or a model is a change to a routing rule or to a manually selected group in the app. The gateway applies it to the requests that follow without restarting, and neither client is restarted or has its configuration file edited again. + +## Before you start + +- ThinkWatch Lite, [installed](/lite/#install). This guide follows version 2026.10.4. +- Claude Code or Codex connected with **Connect…** on the Clients page. Claude Code uses the new configuration from its next request; Codex needs its terminal reopened once. This is the last change on the client side. +- At least two upstreams on the Upstreams page, such as two relays, or one upstream that offers several models. + +## Steps + +With a routing rule: + +1. On the Routing page, open the route that the client's key follows under **Routes**. When there are no other routes, it is the one marked **Default**. +2. In its rule list, choose **Edit…** on the rule to change, usually the one shown as **All requests (catch-all)**. +3. Under **On match**, keep **Forward** and choose the new upstream or group in **Forward to**. +4. To change the model as well, open **Parameter rewrites** and enter a model name in **Change model to**. +5. Choose **Save** in the rule dialog, then **Save** in the route dialog. + +With a manually selected group: + +1. On the Routing page, choose **New group** under **Groups**, enter a **Name**, set **Strategy** to **Manual**, tick the upstreams under **Members**, choose **Set as preferred** on one of them, then choose **Create**. +2. Select the group in a rule's **Forward to**, as in the steps above. +3. To switch later, open the group's menu on the Routing page and choose a member under **Preferred upstream**. The same switch is in the menu bar menu on macOS and in the tray menu on Windows and Linux: each manually selected group is listed with its current upstream, and its submenu lists the members. + +## Notes + +- **Why no restart is needed.** A connected client holds only the gateway's address and a key of its own: `ANTHROPIC_BASE_URL` and `ANTHROPIC_AUTH_TOKEN` in `~/.claude/settings.json` for Claude Code, a provider named `thinkwatch` in `~/.codex/config.toml` for Codex. Upstream addresses, keys and models live in the gateway's configuration, which the gateway reloads in place. A request already in progress finishes on the configuration it started with. +- **Codex sessions stay in one list.** Codex lists only the sessions of its current provider. While connected, it always uses the `thinkwatch` provider, so every session started through the gateway stays in the same list, whichever upstream answers it. Sessions from before connecting remain under their original provider and are listed separately; `codex resume -c model_provider=thinkwatch` continues one of them through the gateway. +- **Conversations in progress.** Inside a group, a conversation stays with the upstream that answered it until the current turn ends, and across turns while that upstream's prompt cache is warm: an answer within the last five minutes that read or wrote at least 1,024 cached tokens. After the preferred upstream of a manual group changes, new conversations move at once, while one in progress may stay until its cache cools or that upstream fails. A rule pointed at another upstream or group applies to every conversation from the next request. +- **Model names.** An upstream whose model list lacks the requested model is skipped. When the new upstream uses other model names, such as GLM in place of Claude, set **Change model to** on the rule. A changed model no longer hits the cached prompt, and the request is priced by the name sent. +- **One client only.** Each connected client has its own key. To switch one client and leave the others as they are, create a route with **New route** and add that client's key under **Keys using this route**. + +Related: [Features](/docs/lite/features/#routing-and-failover), [Fail over and balance load across relays and API keys](/docs/lite/failover-and-load-balancing/), [Install and update](/docs/lite/install/). diff --git a/src/content/docs-lite/en/wsl-claude-code-codex.md b/src/content/docs-lite/en/wsl-claude-code-codex.md new file mode 100644 index 0000000..07123fe --- /dev/null +++ b/src/content/docs-lite/en/wsl-claude-code-codex.md @@ -0,0 +1,39 @@ +# Use Claude Code and Codex in WSL + +ThinkWatch Lite on Windows lists the Claude Code and Codex installed in each WSL distribution on its Clients page and connects them to the gateway on Windows, the same way as the clients on Windows itself. They are given the address `127.0.0.1`, which WSL reaches in WSL 1 and in WSL 2 with mirrored networking. For WSL 2 on its default NAT networking, the app offers to switch to mirrored networking and to restart WSL. + +## Before you start + +- ThinkWatch Lite on Windows 10 21H2 or later, [installed](/lite/#install) or portable. The app runs on Windows, not inside WSL. This guide follows version 2026.10.4. +- WSL 1, or WSL 2 with mirrored networking, which needs Windows 11 22H2 or later and WSL 2.0.5 or later. `wsl --version` shows the version and `wsl --update` updates it. +- Claude Code or Codex installed in the distribution and run once, so that `~/.claude` or `~/.codex` exists. +- At least one upstream on the Upstreams page. + +## Steps + +1. Open the Clients page. Below **This computer**, each distribution has a group named **WSL · **, with a line under the name stating its networking. +2. If the line reads **NAT networking; clients cannot be connected.**, choose **Switch to mirrored…**. The dialog shows the change to `%USERPROFILE%\.wslconfig`; choose **Switch**. +3. Choose **Restart WSL…**, then **Restart WSL**. This runs `wsl --shutdown`: every running distribution stops, together with the programs running in it. +4. In the distribution's group, choose **Connect…** on Claude Code or Codex, review the fields and the full change, and choose **Connect**. +5. Claude Code goes through the gateway from its next request. For Codex, reopen the terminal in WSL. +6. After the first request, the client's status changes to **In use**, and its requests appear on the Traffic page under a key of its own. + +## Notes + +| Setup | Result | +|---|---| +| WSL 1 | Connects; WSL 1 shares the network with Windows. | +| WSL 2 with mirrored networking | Connects. | +| WSL 2 with NAT networking (the default) | Not connected: inside WSL, `127.0.0.1` is WSL itself, and the gateway does not listen on the WSL virtual adapter. **Switch to mirrored…** is offered. | +| Windows 10 or Windows 11 21H2 | No mirrored networking, so clients in WSL 2 cannot be connected. | +| WSL older than 2.0.5 | `wsl --update` is needed first. | + +- **The `.wslconfig` change.** Only `networkingMode` is added or changed, under `[wsl2]`, or in place where it is written under the older `[experimental]`. The rest of the file is left as it is, and the whole file is backed up first. The setting applies to every WSL 2 distribution on the computer. A full uninstall does not change it back, and the backup is kept. +- **When NAT remains.** If WSL still uses NAT networking after the restart, the group says so and offers **Restart WSL…** again. +- **Only Claude Code and Codex.** These two are the clients listed inside WSL. Desktop clients such as Claude Desktop and Zed run on Windows and are connected under **This computer**. +- **Separate keys.** Each copy in WSL gets a key of its own, separate from the copy on Windows, and its files are edited through `\\wsl.localhost`. Restoring a client, **Restore all…** and a full uninstall cover the copies in WSL as well. +- **Reading starts a distribution.** Opening the Clients page reads each distribution through `\\wsl.localhost`, which starts a distribution that is not running. +- **Remote core.** When the app is connected to a gateway on a server, clients in WSL are pointed at the server like those on Windows, whatever the networking. +- **Paths.** A model may hand a client a path written for the other side. The built-in plugin **Convert WSL and Windows paths** on the Plugins page, off by default, rewrites drive paths in tool-call arguments to the form the client can open. Its scope can be limited to the clients in WSL, whose names look like `claude-code-wsl-ubuntu`. + +Related: [Features](/docs/lite/features/#client-setup), [Install and update](/docs/lite/install/), [Plugins](/docs/lite/plugins/). diff --git a/src/content/docs-lite/zh-CN/claude-code-other-models.md b/src/content/docs-lite/zh-CN/claude-code-other-models.md new file mode 100644 index 0000000..45a8ba4 --- /dev/null +++ b/src/content/docs-lite/zh-CN/claude-code-other-models.md @@ -0,0 +1,42 @@ +# 让 Claude Code 使用 GLM、DeepSeek 或 Kimi + +ThinkWatch Lite 把 Claude Code 接到本机的网关上，网关再把每个请求转发给提供所请求模型的上游。使用 GLM、DeepSeek 或 Kimi 的模型有两种做法：在 Claude Code 中直接使用模型名（`/model`，或 `settings.json` 中的模型变量），或者用路由规则把 Claude 的模型名改写为目标模型。这三个服务商都提供兼容 Anthropic 接口的地址，Claude Code 的请求无需格式转换即可发出。 + +## 准备 + +- 已[安装](/zh-CN/docs/lite/install/) ThinkWatch Lite；Claude Code 已至少运行过一次。 +- 服务商的 API 密钥。GLM 也可以改用开通了 GLM Coding Plan 的 Z.ai 或 BigModel 账号在应用内登录。 +- Claude Pro / Max 订阅登录不能作为上游；接管之后，Claude Code 改用网关密钥。 + +## 步骤 + +1. 在「上游」页点击「新建上游」，选择「服务类型」： + - 「DeepSeek」：自动填入 `https://api.deepseek.com/anthropic` 和接口协议，再填写「API 密钥」。 + - GLM（API 密钥）：选「自定义」，「接口地址」填 `https://open.bigmodel.cn/api/anthropic` 或 `https://api.z.ai/api/anthropic`，「接口协议」选「Anthropic Messages」，再填写「API 密钥」。 + - GLM（账号登录）：选「Z.ai / BigModel 账号」，在「账号归属」中选择站点，勾选「已阅读上述说明，继续登录」，点击「登录」并在浏览器中完成授权。应用在该账号中创建一把名为 `thinkwatch` 的 API 密钥，并写入上游。 + - Kimi：选「自定义」，「接口地址」填 Kimi 文档给出的兼容 Anthropic 接口的地址，「接口协议」选「Anthropic Messages」。Kimi For Coding 还需打开「转发客户端身份」。 + + 「检测连接」验证地址与凭据并获取模型列表，不产生费用。之后点击两次「下一步」，再点击「创建」。 +2. 在「客户端」页 Claude Code 一行点击「接管…」。对话框列出 `~/.claude/settings.json` 中要修改的字段：`env.ANTHROPIC_BASE_URL`、`env.ANTHROPIC_AUTH_TOKEN`（新密钥 `claude-code`）和 `env.CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY`。点击「接管」。 +3. 选择指定模型的方式： + - **直接使用模型名。**在 Claude Code 中输入 `/model <模型 ID>` 即切换到该模型，也可以用 `claude --model <模型 ID>` 启动。要让 Claude Code 的模型别名对应到该模型，在 `~/.claude/settings.json` 的 `env` 中加入以下变量；其中 Haiku 一项也用于后台任务。 + + ```json + "ANTHROPIC_DEFAULT_OPUS_MODEL": "<模型 ID>", + "ANTHROPIC_DEFAULT_SONNET_MODEL": "<模型 ID>", + "ANTHROPIC_DEFAULT_HAIKU_MODEL": "<模型 ID>" + ``` + + 这种做法不需要路由规则：默认路由会跳过模型列表中没有该模型的上游。 + - **改写模型名。**在「路由」页打开 `default` 路由，点击「添加规则」。通过「添加条件」加入「模型」`claude-*`，再加入「密钥」`claude-code`，使其他客户端不受影响。「命中后」选「转发」，「转发至」选该上游，在「改写参数」的「模型改为」中填入目标模型 ID。点击「添加」，再点击「保存」。Claude Code 中显示的仍是 Claude 的模型名。 + +## 说明 + +- **格式转换。**Claude Code 发出的是 Anthropic Messages；接口协议同为 Anthropic Messages 时，请求按原格式发出，网关只去掉 `metadata.user_id` 等身份字段。只有上游使用其他格式时才会转换，例如兼容 OpenAI 的地址配合接口协议 OpenAI Chat Completions：此时「流量」页把该请求标为「已转换」，请求详情列出被丢弃的字段。网页搜索是服务端工具，无法转换，这类请求不会发往此类上游。「自动识别」认不出这三个服务商的地址，会按客户端的原格式转发，对 Claude Code 可用，对 Codex 这类使用其他格式的客户端则不可用。 +- **转发客户端身份**默认关闭，上游看到的是 ThinkWatch 的 User-Agent，不带客户端身份。Kimi For Coding、百炼 Coding Plan 等上游只接受特定客户端；打开开关后，上游收到 Claude Code 自己的 User-Agent、`x-app` 等身份请求头和请求体中的身份字段，均为原值。 +- **GLM Coding Plan。**地址在 `api.z.ai` 或 `open.bigmodel.cn` 上的上游，无论应用内登录还是手动填写密钥，都在「额度 / 计费」列和菜单栏（或托盘菜单）中显示 5 小时与每周额度，积分制套餐另外显示剩余积分。 +- **`/model` 列表**只显示名称含 `claude` 或 `anthropic` 的网关模型；其他模型需要输入名称，或用 `ANTHROPIC_CUSTOM_MODEL_OPTION` 加入一项。 +- **费用。**改写过模型名的请求按实际发出的模型计价。 +- **「还原…」**只恢复应用写入的字段，手动加入的模型变量仍留在 `settings.json` 中。 + +相关文档：[功能详解](/zh-CN/docs/lite/features/)、[让 Codex 使用 Claude、Gemini 或只提供 Chat Completions 的中转](/zh-CN/docs/lite/codex-other-models/)、[让 Claude Desktop 使用第三方模型](/zh-CN/docs/lite/claude-desktop-third-party-models/)。 diff --git a/src/content/docs-lite/zh-CN/claude-desktop-third-party-models.md b/src/content/docs-lite/zh-CN/claude-desktop-third-party-models.md new file mode 100644 index 0000000..c163eaa --- /dev/null +++ b/src/content/docs-lite/zh-CN/claude-desktop-third-party-models.md @@ -0,0 +1,36 @@ +# 让 Claude Desktop 使用第三方模型 + +ThinkWatch Lite 通过 Claude Desktop 官方的第三方推理模式接入，把本机的网关设为推理提供方。Claude Desktop 只接受形如 Claude 的模型名，因此由一条路由规则把这些名称改写为实际服务请求的模型，可以是 GLM、DeepSeek、Kimi 或其他任何上游的模型。由组织统一管理的 Claude Desktop 不做修改。 + +## 准备 + +- 已[安装](/zh-CN/docs/lite/install/) ThinkWatch Lite；Claude Desktop（macOS 或 Windows）已至少打开过一次。第三方推理模式不需要 Anthropic 账号。 +- 已在「上游」页添加提供该模型的上游。GLM、DeepSeek 与 Kimi 的添加方法见[让 Claude Code 使用 GLM、DeepSeek 或 Kimi](/zh-CN/docs/lite/claude-code-other-models/)。 + +## 步骤 + +1. 在「客户端」页 Claude Desktop 一行点击「接管…」。对话框列出四个文件，macOS 上位于 `~/Library/Application Support`；Windows 上 `Claude-3p` 位于 `%LOCALAPPDATA%`，`Claude` 位于 `%APPDATA%`。 + + | 文件 | 改动 | + |---|---| + | `Claude-3p/configLibrary/7477a7c4-1ce0-4d3a-9b1e-7477a7c40001.json` | 名为 ThinkWatch 的一份配置：`inferenceProvider` 为 `gateway`、网关地址、以 `x-api-key` 方式发送的密钥、`chatTabEnabled`，以及模型列表 `inferenceModels` | + | `Claude-3p/configLibrary/_meta.json` | 登记 ThinkWatch 这一项，并把 `appliedId` 指向它；其他配置保持不变 | + | `Claude-3p/claude_desktop_config.json` | 只把 `deploymentMode` 设为 `3p` | + | `Claude/claude_desktop_config.json` | 把 `deploymentMode` 设为 `3p`；其中的 MCP 服务器保持不变 | + + `inferenceModels` 写入网关模型中名称形如 Claude 的那些：`claude-` 之后紧跟 `sonnet`、`opus`、`haiku` 或 `fable` 及版本号。一个都没有时，说明中会写明将写入 `claude-sonnet-5`，并给出一条示例规则。点击「接管」。 +2. 在「路由」页打开 `default` 路由，点击「添加规则」。通过「添加条件」加入「模型」`claude-*` 和「密钥」`claude-desktop`（接管对话框中写明的密钥）。「命中后」选「转发」，「转发至」选该上游，在「改写参数」的「模型改为」中填入目标模型 ID。点击「添加」，再点击「保存」。 +3. 完全退出 Claude Desktop 再重新打开。打开时如出现登录页，在登录页选择通过网关继续，只需一次。 + +## 说明 + +- **由组织统一管理。**托管配置优先于本机的一切设置：macOS 上是 `/Library/Managed Preferences` 下的 `com.anthropic.claudefordesktop.plist`，Windows 上是 `HKLM` 或 `HKCU` 下的注册表项 `SOFTWARE\Policies\Claude`。此时「客户端」页不提供「接管…」，详情中显示「这台电脑的 Claude Desktop 由组织统一管理」。 +- **模型列表。**`inferenceModels` 在接管时写入，之后不提示更新。网关上的模型变化后，先「还原…」再重新接管即可刷新。 +- **云服务商配置。**Claude Desktop 原本通过另一份配置使用 Amazon Bedrock、Google Cloud Agent Platform 或 Microsoft Foundry 时，对话框会说明：接管期间改用 ThinkWatch 的配置，还原时切回原配置。原配置为 Bedrock 时，还提供「新建 Bedrock 上游…」，按原来的设置预填。 +- **对话与联网搜索。**该模式下的对话与原有对话分开保存。联网搜索不经过网关，需要另外配置。 +- **「还原…」**把两个文件中的 `deploymentMode` 改回原值，从 `_meta.json` 中摘掉 ThinkWatch 这一项；接管前使用的配置仍在时，`appliedId` 指回它；并删除 ThinkWatch 的那份配置。 +- **配置检查。**在 Claude Desktop 中换用了其他配置时，详情显示「Claude Desktop 中正在使用的是另一份配置」；`deploymentMode` 不是 `3p` 时，显示「Claude Desktop 可能仍以原有模式启动」。 +- **手动配置。**同样的设置也可以在 Claude Desktop 中完成：依次打开 Help → Troubleshooting → Enable Developer Mode，然后打开 Developer → Configure Third-Party Inference；选择网关作为提供方，填入网关地址和密钥，鉴权方式设为 `x-api-key`，点击 Apply Changes。 +- **费用。**改写过模型名的请求按实际发出的模型计价。 + +相关文档：[功能详解](/zh-CN/docs/lite/features/)、[让 Claude Code 使用 GLM、DeepSeek 或 Kimi](/zh-CN/docs/lite/claude-code-other-models/)、[安装与更新](/zh-CN/docs/lite/install/)。 diff --git a/src/content/docs-lite/zh-CN/codex-other-models.md b/src/content/docs-lite/zh-CN/codex-other-models.md new file mode 100644 index 0000000..d9252b3 --- /dev/null +++ b/src/content/docs-lite/zh-CN/codex-other-models.md @@ -0,0 +1,38 @@ +# 让 Codex 使用 Claude、Gemini 或只提供 Chat Completions 的中转 + +ThinkWatch Lite 把 Codex 接到本机的网关上，网关接收 OpenAI Responses API，这也是 Codex 对自定义服务商使用的唯一格式。网关在 Responses 与上游的格式之间双向转换请求和回答：Claude 用 Anthropic Messages，Gemini 用 Google Gemini，只提供 OpenAI Chat Completions 的中转用 Chat Completions。使用哪个模型，在 Codex 的配置中指定，或由路由规则改写。 + +## 准备 + +- 已[安装](/zh-CN/docs/lite/install/) ThinkWatch Lite。 +- Codex 已至少运行过一次：Codex 命令行，或 ChatGPT 桌面版中的 Codex 均可。 +- Anthropic、Google Gemini 或中转站的 API 密钥。 + +## 步骤 + +1. 在「上游」页点击「新建上游」，选择「服务类型」：Claude 选「Anthropic」，Gemini 选「Google Gemini」，接口地址和接口协议会自动填入。中转站选「自定义」，「接口地址」填它的 Base URL（不含 `/chat/completions` 等接口路径），「接口协议」选「OpenAI Chat Completions」。填写「API 密钥」，点击「检测连接」，再点击「下一步」。中转站不提供模型列表时，在「手动清单」中每行填写一个模型 ID。再点击「下一步」，然后点击「创建」。 +2. 在「客户端」页 Codex 一行点击「接管…」。对话框列出对 `~/.codex/config.toml` 的修改： + + | 字段 | 写入 | + |---|---| + | `model_provider` | `thinkwatch` | + | `model_providers.thinkwatch.base_url` | 带 `/v1` 的网关地址，默认为 `http://127.0.0.1:8788/v1` | + | `model_providers.thinkwatch.wire_api` | `responses` | + | `model_providers.thinkwatch.experimental_bearer_token` | 新密钥 `codex` | + | `model_providers.thinkwatch.http_headers` | `X-ThinkWatch-Client = "codex"` | + | 同一表中的 `name`、`requires_openai_auth`、`supports_websockets` | `ThinkWatch`、`false`、`false` | + + 点击「接管」，然后重新打开终端。ChatGPT 桌面版读取同一份配置文件，重新启动后生效。 +3. 指定模型。接管不修改 `model`，Codex 仍会请求原来的模型。可以任选一种做法： + - 在 `~/.codex/config.toml` 开头、第一个 `[表名]` 之前写入 `model = "<模型 ID>"`；只用一次时，运行时加 `-c model=<模型 ID>`。 + - 保留 Codex 的模型名并改写：在「路由」页打开 `default` 路由，点击「添加规则」，加入条件「模型」`gpt-*` 和「密钥」`codex`，「命中后」选「转发」，「转发至」选该上游，在「改写参数」的「模型改为」中填入目标模型 ID。点击「添加」，再点击「保存」。 + +## 说明 + +- **Codex 的内置模型表。**Codex 把自家模型的元数据（上下文窗口等）编在程序里。它不认识的模型，例如 Claude 或 Gemini 的模型，按兜底元数据运行，上下文窗口为 272,000 token，并提示「Model metadata for `<模型>` not found. Defaulting to fallback metadata; this can degrade performance and cause issues.」。模型的上下文窗口更小时，可在 `config.toml` 中用 `model_context_window` 设定 Codex 采用的窗口。网关的模型列表不会出现在 Codex 的模型选择中，因为 Codex 要求的是它自己格式的模型目录。 +- **格式转换。**请求和流式回答双向转换。「流量」页把这类请求标为「已转换」，目标格式无法承载的字段被丢弃，并在请求详情中列出。网页搜索这类服务端工具只能由所属的服务商执行，转换时被丢弃。Codex 的 `wire_api` 只支持 `responses`，只提供 Chat Completions 的中转正是靠这一转换才能使用。 +- **凭据。**`requires_openai_auth = false` 使 Codex 用自己的网关密钥连接网关，不发送 OpenAI 密钥或 ChatGPT 令牌。应用内登录的 ChatGPT 账号仍可同时作为 OpenAI 模型的上游：每个请求都交给模型列表中有所请求模型的上游。 +- **会话。**接管前后的会话在 Codex 中分开显示。运行 `codex resume <会话 ID> -c model_provider=thinkwatch` 可以通过网关继续之前的会话。「还原…」之后，接管期间的会话仍可打开，此时直连 OpenAI。 +- **费用。**改写过模型名的请求按实际发出的模型计价。 + +相关文档：[功能详解](/zh-CN/docs/lite/features/)、[让 Claude Code 使用 GLM、DeepSeek 或 Kimi](/zh-CN/docs/lite/claude-code-other-models/)、[安装与更新](/zh-CN/docs/lite/install/)。 diff --git a/src/content/docs-lite/zh-CN/compare-cc-switch.md b/src/content/docs-lite/zh-CN/compare-cc-switch.md new file mode 100644 index 0000000..45a0557 --- /dev/null +++ b/src/content/docs-lite/zh-CN/compare-cc-switch.md @@ -0,0 +1,52 @@ +# ThinkWatch Lite 与 CC Switch 对比 + +CC Switch 与 ThinkWatch Lite 都用于把 Claude Code、Codex 等 AI 编程客户端接到不同的服务商，两者都采用 MIT 许可证。CC Switch 通过改写各客户端的配置文件切换供应商，另有可选的本地代理；ThinkWatch Lite 让客户端只接入一次本机网关，此后的切换、路由与记录都在网关中完成，发出前可以替换请求中的凭据，回答中的危险工具调用可以被切断。 + +## 做法的区别 + +CC Switch 把供应商保存在自己的数据库中。启用一个供应商时，把它的地址和密钥写入客户端的配置，例如 Claude Code 的 `~/.claude/settings.json` 中的 `env.ANTHROPIC_BASE_URL`，或 Codex 的 `~/.codex/auth.json` 与 `config.toml`。Claude Code 无需重启即可生效，其他多数客户端需要重启客户端或终端。 + +它的本地代理模式（手册中称为「路由」）适用于 Claude Code、Codex、Gemini CLI 与 Grok Build。为某个客户端开启后，CC Switch 把该客户端的配置改为指向本地代理（默认 `http://127.0.0.1:15721`）；此后在代理内切换供应商，不需要重启客户端；关闭代理时还原配置。代理请求日志、故障转移与格式转换都需要这一模式。 + +ThinkWatch Lite 在本机运行网关 ThinkWatch Core。在客户端页把每个客户端接管一次：给出完整的改动差异，备份原文件，并为该客户端分配单独的密钥。此后更换上游、调整路由规则与故障转移都在网关中进行，不再改动客户端的配置。 + +## 对比 + +表中的「—」表示该产品的文档中没有描述这项功能。 + +| | CC Switch | ThinkWatch Lite | +|---|---|---| +| 客户端 | Claude Code、Claude Desktop、Codex、Gemini CLI、Grok Build、OpenCode、OpenClaw、Hermes Agent、Pi、MiniMax Code | 一键接管：Claude Code、Claude Desktop、Codex（含 ChatGPT 桌面版中的 Codex）、opencode、Pi、oh-my-pi、Grok Build、Qwen Code、Hermes Agent、Zed、Aider、DeepSeek Harness；提供配置方法：Cursor、Continue、Antigravity CLI | +| 添加供应商 | 50 余个供应商预设；`ccswitch://` 链接可导入供应商、MCP 服务器、提示词与技能 | 服务类型中列有 Anthropic、OpenAI、Google Gemini、Amazon Bedrock、DeepSeek 与 Ollama，也可填写任何兼容接口；中转站或服务商可通过 `thinkwatch://import` 链接预填一个上游 | +| 路由 | 代理模式下，每个客户端的请求发往它当前的供应商；可按供应商映射模型 | 每把密钥的规则按顺序匹配模型、API 格式、输入 token、工具、图片、扩展思考等条件；规则可以改写模型 | +| 故障转移 | 按优先级排列的故障转移队列，带熔断（代理模式） | 回答开始之前尝试失败时，转到策略组中的下一个上游；同一会话默认保持在同一个上游 | +| 负载均衡 | — | 策略组：按顺序、手动选择、轮询、延迟最低、费用最低 | +| API 格式转换 | 代理模式下：Claude Code 接 OpenAI Chat Completions 或 Responses 的供应商；Codex 接 Chat Completions 或 Anthropic Messages 的供应商 | 在 Anthropic Messages、OpenAI Chat Completions、OpenAI Responses 与 Gemini 之间转换 | +| 用量与费用 | 请求数、token、缓存命中率与估算费用，数据来自代理日志或客户端的会话日志；自定义价格，可选从 models.dev 同步价格；显示订阅额度与余额 | 按区间、模型、上游统计 token、费用与请求数；价格取自每天更新的 LiteLLM 价目表或自定义价目表；估算部分单独标出，无法计价的请求单独计数 | +| 请求详情 | 供应商、模型、token、费用、耗时与状态；可查看请求参数、响应摘要与错误信息 | 命中的规则、每一次尝试及其状态、请求与响应正文、费用；可全文搜索；可在另一个上游重放 | +| 出站脱敏与工具调用审查 | — | 请求发出前把 API 密钥、私钥、身份证号与银行卡号替换为占位符；回答中含下载并执行代码、外发凭据等工具调用时切断响应。两项出厂均为「观察」，只记录、不改动 | +| MCP 与技能 | 统一的 MCP 服务器列表，同步到选定的客户端；从 GitHub 仓库或 ZIP 文件安装技能 | 并排列出 13 个客户端的 MCP 服务器，其中 4 个可复制或移除；列出技能与钩子；扫描隐藏字符、提示注入、危险命令与过宽权限 | +| 提示词 | 提示词预设写入 `CLAUDE.md`、`AGENTS.md` 或 `GEMINI.md` | — | +| 会话 | 读取客户端自己的会话文件；可搜索、在终端中恢复、删除 | 把经过网关的请求归为会话，按轮还原对话 | +| 订阅账号 | 通过其反向代理使用 ChatGPT（Codex OAuth）、GitHub Copilot 与 xAI 账号 | ChatGPT 与 Z.ai / BigModel 账号作为上游登录；不支持 Claude Pro 或 Max 订阅登录 | +| 服务器与远程 | —（代理可监听 `0.0.0.0` 供局域网访问；供应商数据可通过 Dropbox、OneDrive、iCloud 或 WebDAV 在设备间同步） | 网关以 systemd 服务运行在 Linux 服务器上，由桌面应用经加密的控制通道管理 | +| 平台 | Windows 10 及以上；macOS 12 及以上（Intel 与 Apple 芯片，已签名并经 Apple 公证）；Linux（deb、rpm、AppImage） | macOS 12 及以上（Apple 芯片）；Windows 10 21H2 及以上（x64、ARM64）；Linux（x86_64、aarch64，AppImage）；未经 Apple 或微软签名 | +| 许可证 | MIT | MIT | + +## 如何选择 + +- **CC Switch**：只需要在几个供应商之间快速切换、希望从预设开始配置、需要统一管理多个客户端的 MCP 服务器、提示词与技能时，CC Switch 更直接。 +- **ThinkWatch Lite**：需要按请求查看费用与去向、按规则路由、避免请求中的凭据落到中转站手中，或需要在服务器上运行网关时，适合 ThinkWatch Lite。 + +## 同时使用 + +两者都会写入 Claude Code 的接口地址（`~/.claude/settings.json` 中的 `env.ANTHROPIC_BASE_URL`）以及 Codex 的 `~/.codex/config.toml`。两者同时接管同一个客户端时会相互覆盖：最后一次写入决定客户端的请求发往哪里，而各自的还原会写回自己改动之前保存的值。 + +每个客户端只交给其中一个管理时，两者可以并存，例如由 CC Switch 管理 ThinkWatch Lite 不接管的 Gemini CLI 或 OpenClaw，由 ThinkWatch Lite 接管 Claude Code 与 Codex。把一个客户端从 CC Switch 转给 ThinkWatch Lite 时，先在 CC Switch 中关闭该客户端的代理，并停止在 CC Switch 中切换它的供应商，再到客户端页接管；转回时，先在客户端页还原。 + +## 说明 + +- 关于 CC Switch 的内容据 CC Switch 2026 年 10 月的文档，即 v3.20.4 的 README、用户手册与发布说明（[farion1231/cc-switch](https://github.com/farion1231/cc-switch)），之后的版本可能有所变化。 +- 关于 ThinkWatch Lite 的内容适用于 2026.10.4 版本。 + +相关文档：[功能详解](/zh-CN/docs/lite/features/)、[安装与更新](/zh-CN/docs/lite/install/)、[连接远程 core](/zh-CN/docs/lite/remote-core/)、[常见问题](/zh-CN/docs/lite/faq/)。 diff --git a/src/content/docs-lite/zh-CN/failover-and-load-balancing.md b/src/content/docs-lite/zh-CN/failover-and-load-balancing.md new file mode 100644 index 0000000..28418e9 --- /dev/null +++ b/src/content/docs-lite/zh-CN/failover-and-load-balancing.md @@ -0,0 +1,35 @@ +# 在多个中转站和多把密钥之间自动故障转移与负载均衡 + +ThinkWatch Lite 把每个中转站的每把密钥建成一个上游，再把多个上游放进一个策略组。路由规则把请求转发至策略组，由策略决定成员的先后；某个上游在回答开始之前失败时，网关把请求交给下一个上游，客户端不会看到这次错误。提示缓存值得保留时，同一段对话继续使用上次回答它的上游。 + +## 准备 + +- 已[安装](/zh-CN/lite/#install) ThinkWatch Lite，并已在客户端页接管客户端。本文按 2026.10.4 版编写。 +- 各中转站的接口地址和 API 密钥。 + +## 步骤 + +1. 在上游页选择「新建上游」。在「连接」中填写「名称」「接口地址」和一把「API 密钥」，选择「检测连接」，再依次选择「下一步」直到「创建」。每把密钥重复一次：一个上游只有一把密钥，故障转移和暂停都以上游为单位。 +2. 在路由页的「策略组」标签中选择「新建策略组」。填写「名称」，选择「策略」，在「成员」中勾选上游并拖动排序，然后选择「创建」。 +3. 在「路由」标签中打开路由，对要使用该策略组的规则选择「编辑…」（通常是「全部请求（兜底）」那一条），在「转发至」中选择该策略组，并在两个对话框中各选择一次「保存」。 +4. 「试算」可以检查结果，不会发出请求。在流量页打开请求，「路由」标签的「尝试链」列出尝试过的每个上游。 + +## 说明 + +| 策略 | 成员的顺序 | +|---|---| +| 「按顺序」 | 按列表顺序。 | +| 「轮询」 | 在成员之间轮流分配请求。 | +| 「延迟最低」 | 按各上游最近 32 个请求首字节时间的中位数排序；样本少于 3 个的排在后面。 | +| 「费用最低」 | 按各上游价目表中所请求模型的输入单价排序；设为不计费的排在最前，无法计价的排在最后。 | +| 「手动选择」 | 优先使用的上游排在最前，其余按列表顺序。 | + +策略只决定顺序，所有成员都留作故障转移的后备。 + +- **何时换到下一个上游。**在尚未向客户端发出任何内容时，上游出现以下情况，网关即改用下一个成员：无法连接或读不到它的凭据；返回 5xx、429、401、403、402 或 404；返回 400 或 422，且错误信息说明余额不足、额度用完或模型不可用；流式回答在第一段内容之前报错，例如过载。等待第一段内容的时长为「设置 › 故障转移」中的「等待回答开头」，默认 15 秒。其他 4xx，以及最后一个成员返回的 4xx（429 除外），原样返回客户端。 +- **暂停。**失败的上游按「设置 › 故障转移」暂停使用，默认值为：「连续失败」3 次后暂停 60 秒，此后每次加倍，最长 600 秒；「余额不足」暂停 30 分钟；「额度用完」暂停到重置时刻，未给出时暂停 60 分钟；「限流」按上游要求的等待时间暂停，最长 60 分钟。只有一个上游的规则不受暂停影响；所有成员都在暂停时，网关仍会逐个尝试。 +- **会话与提示缓存。**同一轮之内（客户端回传工具结果期间），请求沿用这一轮开头确定的规则和回答它的上游。跨轮时，如果上次回答在五分钟以内、且读写了至少 1,024 个缓存 token，对话继续使用该上游，因为换到别处要按全价重建缓存；否则，或者该上游正在暂停时，由策略重新排序，「轮询」正是在这时轮到下一个成员。请求「路由」标签中的「对话延续」一行说明请求是否因此留在原上游。 +- **模型名相同。**每个成员收到的都是客户端请求的模型名，或者规则改写之后的模型名。模型列表中没有该模型的成员会被跳过；没有模型列表的成员照常尝试，它返回 404 时请求换到下一个。 +- **回退到另一个模型。**添加一条规则：条件「选定上游」选择后备上游，「命中后」选择「继续匹配」，在「改写参数」的「模型改为」中填写它的模型。这样的规则在每次选定上游之后判断，故障转移之后同样适用。更换模型后已缓存的 prompt 不再命中，费用按发出的模型名计算。 + +相关文档：[切换中转站、上游或模型，无需重启 Claude Code 与 Codex](/zh-CN/docs/lite/switch-upstreams-without-restart/)、[功能详解](/zh-CN/docs/lite/features/#路由与故障转移)、[安装与更新](/zh-CN/docs/lite/install/)。 diff --git a/src/content/docs-lite/zh-CN/faq.md b/src/content/docs-lite/zh-CN/faq.md new file mode 100644 index 0000000..3b3eaec --- /dev/null +++ b/src/content/docs-lite/zh-CN/faq.md @@ -0,0 +1,79 @@ +# ThinkWatch Lite 常见问题 + +关于 ThinkWatch Lite 的常见问题与简要回答，适用于 2026.10.4 版本。详细说明见[功能详解](/zh-CN/docs/lite/features/)与[安装与更新](/zh-CN/docs/lite/install/)。 + +## ThinkWatch Lite 是什么？ + +ThinkWatch Lite 是一款桌面应用，在本机为 Claude Code、Codex 等 AI 客户端运行一个网关，支持 macOS、Windows 与 Linux。客户端只需接入网关一次，此后更换上游或模型都在网关中完成，不再改动客户端的配置。每个请求的去向与费用都有记录；请求离开本机之前可以把其中的凭据替换为占位符，回答中的危险工具调用可以在客户端执行之前切断。 + +## ThinkWatch Lite 免费吗？ + +免费。ThinkWatch Lite 及其网关 ThinkWatch Core 以 MIT 许可证开源，可免费使用、修改和再分发，商业或非商业用途均可。应用不需要注册账号。请求产生的费用由所发往的上游收取，例如 API 服务商或中转站。 + +## ThinkWatch Lite 支持哪些客户端？ + +ThinkWatch Lite 可以在客户端页一键接管 12 个客户端：Claude Code、Claude Desktop、Codex（含 ChatGPT 桌面版中的 Codex）、opencode、Pi、oh-my-pi、Grok Build、Qwen Code、Hermes Agent、Zed、Aider 与 DeepSeek Harness。Cursor、Continue 与 Antigravity CLI 提供逐步的配置方法，并为其创建密钥。 + +其他使用 Anthropic、OpenAI 或 Gemini 接口的客户端，可以填入网关地址（默认 `http://127.0.0.1:8788`）和密钥页中的一把密钥接入。 + +## ThinkWatch Lite 支持哪些平台？ + +ThinkWatch Lite 支持 macOS 12 及以上（Apple 芯片，不提供 Intel 芯片 Mac 的版本）；Windows 10 21H2 及以上（x64、ARM64，提供安装程序与绿色版）；Linux（x86_64、aarch64，以 AppImage 发布），需要 Ubuntu 22.04、Debian 12、Fedora 36 或更新的发行版。 + +在 Windows 上，安装在 WSL 中的 Claude Code 与 Codex 也可以接管，前提是 WSL 1，或使用 mirrored 网络模式的 WSL 2（需要 Windows 11 22H2 及以上、WSL 2.0.5 及以上）。 + +## ThinkWatch Lite 能使用 Claude Pro 或 Max 订阅吗？ + +不能。ThinkWatch Lite 不支持 Claude 订阅账号登录，网关也会拒绝配置中的 Claude 订阅登录凭据。Claude Code 被接管后，请求使用网关密钥发出，不再使用 Claude Code 中登录的订阅；在客户端页还原 Claude Code 后，它恢复使用自己的登录。 + +经由网关，Claude Code 可以使用 Anthropic API 密钥、Amazon Bedrock、中转站、ChatGPT 账号，或经 API 格式转换使用其他服务商的模型。 + +## ThinkWatch Lite 能使用中转站和 GLM、Kimi、通义千问、DeepSeek 等国产模型吗？ + +能。任何提供 Anthropic、OpenAI 或 Gemini 接口的服务都可以作为上游：在上游页点击「新建上游」，「服务类型」选择「自定义」，填写「接口地址」与「API 密钥」。「服务类型」中列有 DeepSeek；Z.ai 或 BigModel 账号可以直接在应用内登录，并显示 GLM Coding Plan 的额度。 + +Kimi For Coding、百炼 Coding Plan 等只接受特定客户端的上游，需要在该上游的连接设置中打开「转发客户端身份」，否则请求以 ThinkWatch 的身份发出。中转站的价格与官方不同时，可以使用自定义价目表；路由规则可以改写客户端请求的模型名，此时按发出的模型名计价。 + +## ThinkWatch Lite 与 CC Switch 有什么区别？ + +CC Switch 通过改写各客户端的配置文件切换供应商，并统一管理各客户端的 MCP 服务器、提示词与技能。ThinkWatch Lite 让客户端只接入一次本机网关，由网关对每个请求进行路由、记录与计价，并可以在请求发出前替换凭据、切断回答中的危险工具调用。详细对比见 [ThinkWatch Lite 与 CC Switch 对比](/zh-CN/docs/lite/compare-cc-switch/)。 + +## ThinkWatch Lite 会修改客户端的配置吗？如何还原？ + +ThinkWatch Lite 只在客户端页接管客户端时修改它的配置，且只修改指向网关所需的设置。写入之前，页面给出完整的改动差异，并完整备份原文件。对某个客户端选择「还原…」，或选择「全部还原…」，即可写回原来的值。 + +删除应用之前应先在「设置 › 完全卸载」中卸载，它会还原所有已接管的客户端：直接把应用移到废纸篓，或直接删除 AppImage、绿色版文件夹，都不会还原客户端的配置。 + +## ThinkWatch Lite 的数据保存在哪里？会连接哪些地址？ + +配置、密钥与请求记录都保存在本机：macOS 与 Linux 在 `~/.thinkwatch`，Windows 安装版在 `%APPDATA%\ThinkWatch`，Windows 绿色版在程序旁边的 `data\` 文件夹。网关默认只监听本机 `127.0.0.1` 的 8788 端口。 + +除了转发请求时连接所配置的上游，ThinkWatch Lite 还会连接 GitHub 检查更新，并每天更新一次 LiteLLM 公开的价目表。登录 ChatGPT 或 Z.ai 账号时会打开它们的授权页面；只有配置了远程 core 时才会连接远程 core。 + +## ThinkWatch Lite 会收集使用数据吗？ + +不会。ThinkWatch Lite 不含任何统计或遥测代码，不向项目发送任何使用情况。检查更新时从项目的 GitHub release 页面下载一份很小的版本清单，GitHub 会像对待其他下载一样计入下载次数；在「设置 › 关于」中关闭「自动检查新版本」即可停止自动检查。「设置 › 关于」中生成的诊断包保存在本机，其中的密钥与地址已脱敏，只有在用户主动提供时才会离开本机。 + +## ThinkWatch Lite 的安装包为什么没有签名？如何校验？ + +ThinkWatch Lite 未经 Apple 注册开发者签名，Windows 版本也未经代码签名，因此首次打开需要多一步操作。通过 Homebrew 安装时，cask 会自动移除 macOS 的隔离属性；从磁盘映像安装时，执行 `xattr -dr com.apple.quarantine "/Applications/ThinkWatch Lite.app"`，或在首次打开被拒绝后，于「系统设置 › 隐私与安全性」中点击「仍要打开」。Windows 上 SmartScreen 显示警告时，依次点击「更多信息」「仍要运行」。 + +[release 页面](https://github.com/ThinkWatchProject/ThinkWatch-Lite/releases/latest)上的每个文件旁都附有 `.sha256` 文件，macOS 上用 `shasum -a 256 -c`、Linux 上用 `sha256sum -c` 校验，Windows 上与 `Get-FileHash` 的输出核对。应用内更新下载的文件用编译进应用的公钥验签；源代码也可以在本机自行构建。 + +## 在 ThinkWatch Lite 中切换上游会丢失 Codex 的会话吗？ + +不会。ThinkWatch Lite 只写入一次 Codex 的配置，其中的 model provider 名为 `thinkwatch`，指向网关；此后更换上游都在网关中进行，每个会话记录的 provider 不变，仍留在 Codex 的会话列表中。接管之前的会话单独显示，可以用 `codex resume <会话 ID> -c model_provider=thinkwatch` 通过网关继续。 + +对话中途换到另一个上游时，前一个账号封存的推理内容新上游无法读取。新上游因此拒绝请求时，网关去掉这部分封存的推理并重发一次，对话中的消息与工具调用都保留，对话得以继续。 + +## ThinkWatch Lite 能部署在服务器上吗？ + +网关可以。ThinkWatch Core 以 systemd 服务运行在 Linux 上（x86_64 或 aarch64，glibc 2.35 及以上，例如 Ubuntu 22.04、Debian 12）。桌面应用在「设置 › 连接」中选择「添加远程连接」即可连接它，控制通道经 Noise 握手加密和认证，连接后显示该服务器的流量、费用与配置。其他机器上的客户端需手动填入服务器的网关地址和一把网关密钥。详见[服务器部署](/zh-CN/docs/core/server-deployment/)与[连接远程 core](/zh-CN/docs/lite/remote-core/)。 + +## ThinkWatch Lite 如何更新和卸载？ + +ThinkWatch Lite 启动两分钟后检查一次新版本，此后每天检查一次。从 release 页面下载安装的，点击一次即可完成更新：应用校验下载的文件，等待进行中的请求结束后重新启动。通过 Homebrew 安装的，改用 Homebrew 更新：`brew update && brew upgrade --cask thinkwatch-lite`。 + +卸载时先在「设置 › 完全卸载」中卸载，它会还原已接管的客户端、取消开机启动，并可同时删除数据目录；之后在 macOS 上把应用移到废纸篓，在 Linux 上删除 AppImage，在 Windows 绿色版上删除整个文件夹。Windows 安装版也可以通过系统卸载，卸载程序会先完成同样的还原。 + +相关文档：[功能详解](/zh-CN/docs/lite/features/)、[安装与更新](/zh-CN/docs/lite/install/)、[ThinkWatch Lite 与 CC Switch 对比](/zh-CN/docs/lite/compare-cc-switch/)、[连接远程 core](/zh-CN/docs/lite/remote-core/)。 diff --git a/src/content/docs-lite/zh-CN/features.md b/src/content/docs-lite/zh-CN/features.md index 769962a..f0a4919 100644 --- a/src/content/docs-lite/zh-CN/features.md +++ b/src/content/docs-lite/zh-CN/features.md @@ -77,7 +77,7 @@ MCP 页管理客户端从自己的配置文件中加载的内容，这些内容 ## 设置 -设置页分为六节。「连接」列出本机 core 和已保存的远程 core，详见[连接远程 core](/zh-CN/docs/lite/remote-core)。「通用」设置语言、外观、菜单栏显示的内容（仅 macOS）、开机启动、提醒以系统通知发送、仅在应用内显示还是关闭，并可让设为不再显示的引导提示重新显示。「网关监听」设置网关的访问范围（仅本机、所选网卡所在的局域网或所有网卡）、端口和放行网段。「日志保留」分别设置请求报文与请求记录的保留天数，以及报文的空间上限。「关于」显示版本、检查更新，并可生成诊断包，其中的密钥与地址均已脱敏。「卸载」还原所有已接管的客户端并取消开机启动，应在删除应用之前执行。 +设置页分为七节。「连接」列出本机 core 和已保存的远程 core，详见[连接远程 core](/zh-CN/docs/lite/remote-core)。「通用」设置语言、外观、菜单栏显示的内容（仅 macOS）、开机启动、提醒以系统通知发送、仅在应用内显示还是关闭，并可让设为不再显示的引导提示重新显示。「网关监听」设置网关的访问范围（仅本机、所选网卡所在的局域网或所有网卡）、端口和放行网段。「故障转移」设置上游失败后暂停多久、请求交给下一个上游：连续失败几次后暂停、暂停多长，以及余额不足、额度用完和限流时各自的暂停时长，以及流式回答等待开头的时长。「日志保留」分别设置请求报文与请求记录的保留天数，以及报文的空间上限。「关于」显示版本、检查更新，并可生成诊断包，其中的密钥与地址均已脱敏。「卸载」还原所有已接管的客户端并取消开机启动，应在删除应用之前执行。 ## 菜单栏、系统托盘与通知 diff --git a/src/content/docs-lite/zh-CN/keep-api-keys-from-relays.md b/src/content/docs-lite/zh-CN/keep-api-keys-from-relays.md new file mode 100644 index 0000000..755237b --- /dev/null +++ b/src/content/docs-lite/zh-CN/keep-api-keys-from-relays.md @@ -0,0 +1,34 @@ +# 防止中转站拿到请求中的 API 密钥，并拦截危险的工具调用 + +中转站能看到请求的全部内容，包括混进对话中的密钥，例如粘贴进来的 `.env` 文件、工具读取的配置文件。ThinkWatch Lite 的出站脱敏在请求离开本机之前查找这些凭据，在「替换」档下改为发送 `<>` 这样的占位符，回答中出现占位符时再还原为原值。工具调用审查检查上游返回的工具调用，在「切断」档下，下载即执行、外发凭据之类的调用在客户端执行之前即被拦下。 + +## 准备 + +- 已[安装](/zh-CN/lite/#install) ThinkWatch Lite，并已接管客户端，请求经过网关。本文按 2026.10.4 版编写。 +- 两项防护出厂均为「观察」：只记录检出的内容，不做任何改动。「关闭」档不检查也不记录。 + +## 步骤 + +1. 打开安全页。「日志」标签列出各项防护检出的内容及其所属的请求；两档使用同一套规则，因此先在「观察」档下运行几天，即可看出切换到「替换」后会改动哪些内容。 +2. 打开「出站脱敏」标签。内置规则可以逐条启用或停用，「测试…」对粘贴的文本显示「发出的内容」。 +3. 内置规则未覆盖的密钥格式，选择「新建规则」，填写「名称」、「匹配（正则表达式）」和「占位符名称」（例如 `INTERNAL`，替换为 `<>`），然后选择「创建」。 +4. 把标签顶部的档位切换到「替换」。 +5. 打开「工具调用审查」标签。每条内置规则的处置为「切断」或「仅记录」，可以在「查看规则」中修改。把档位切换到「切断」。 +6. 此后日志的「处置」一栏显示「已替换」或「已切断」；调用被切断时还会发送系统通知。 + +## 说明 + +| 档位 | 出站脱敏 | 工具调用审查 | +|---|---|---| +| 「观察」（出厂） | 检出的内容记入日志，请求原样发出。 | 命中的调用记入日志，照常返回。 | +| 「替换」/「切断」 | 检出的内容替换为占位符后发出，响应中的占位符还原为原值。 | 命中「切断」规则的调用不会完整到达客户端；「仅记录」规则仍只记录。 | + +- **出站脱敏的范围。**查找整个请求，包括系统提示、之前的对话和工具调用，但不查找图片等 base64 数据。内置规则覆盖 Anthropic、OpenAI、GitHub、Slack、AWS（访问密钥 ID）、Google、GitLab、Stripe、npm、DigitalOcean、SendGrid 的 API 密钥与令牌，私钥、JWT、连接串中的口令，以及号码结构与校验位都正确的身份证号和银行卡号。邮箱地址、中国大陆手机号、内网地址、内部域名四条规则出厂为停用。 +- **原值如何还原。**同一个值在整个请求中只对应一个占位符，无论发往哪个上游都不变。模型在文字或工具调用参数中写回的占位符，在交给客户端之前还原：用到这把密钥的命令在本机以原值执行，中转站始终只看到占位符。 +- **哪些调用会被切断。**下载或解码后执行代码、外发环境变量或凭据文件、读取私钥或云凭据、把凭据发往陌生主机、写入启动项或安装定时任务的调用。删除主目录或根目录、开放全部写权限、上传本地文件三类内置规则出厂只记录。 +- **中转站仍能看到的内容。**应用中为该上游配置的密钥，以及请求的其余内容，例如代码、文件内容和对话，均按原样发给中转站。客户端连接网关所用的密钥不会转发；客户端的身份信息也不转发，除非在该上游上打开「转发客户端身份」。 +- **只按规则匹配。**只有命中规则的值才会被替换；没有固定前缀的凭据（例如 AWS 私有访问密钥）需要自定义规则。写法不在任何规则之内的危险命令，工具调用审查拦不住。 +- **看不到网关之外。**中转站在自己的服务器上做了什么，例如留存请求、换用其他模型作答，各项防护无从得知。上游页的「体检」标签可以显示后者的迹象，但不能证明。 +- **动手的代价。**请求内容改变后，上游的提示缓存可能无法命中；「切断」档下误判时，回答会在该调用处中断。 + +相关文档：[功能详解](/zh-CN/docs/lite/features/#安全)（含第三项防护内容过滤）、[安装与更新](/zh-CN/docs/lite/install/)。 diff --git a/src/content/docs-lite/zh-CN/switch-upstreams-without-restart.md b/src/content/docs-lite/zh-CN/switch-upstreams-without-restart.md new file mode 100644 index 0000000..513955f --- /dev/null +++ b/src/content/docs-lite/zh-CN/switch-upstreams-without-restart.md @@ -0,0 +1,35 @@ +# 切换中转站、上游或模型，无需重启 Claude Code 与 Codex + +ThinkWatch Lite 只需把 Claude Code、Codex 指向本机网关一次，此后每个请求发往哪个上游、使用哪个模型都由网关决定。切换中转站、上游或模型，改的是应用中的路由规则或手动选择的策略组；网关不重启，从随后的请求起按新的设置转发，客户端无需重启，也无需再改配置文件。 + +## 准备 + +- 已[安装](/zh-CN/lite/#install) ThinkWatch Lite。本文按 2026.10.4 版编写。 +- 已在客户端页用「接管…」接管 Claude Code 或 Codex。Claude Code 下一个请求即使用新配置；Codex 接管后需要重新打开一次终端。客户端一侧的改动到此为止。 +- 上游页中至少有两个上游，例如两个中转站，或一个提供多个模型的上游。 + +## 步骤 + +用路由规则切换： + +1. 在路由页的「路由」标签中，打开客户端密钥所用的路由；没有其他路由时，就是标有「默认」的那一条。 +2. 在规则列表中，对要修改的规则选择「编辑…」，通常是条件显示为「全部请求（兜底）」的那一条。 +3. 「命中后」保持「转发」，在「转发至」中选择新的上游或策略组。 +4. 同时更换模型时，展开「改写参数」，在「模型改为」中填写模型名。 +5. 在规则对话框中选择「保存」，再在路由对话框中选择「保存」。 + +用手动选择的策略组切换： + +1. 在路由页的「策略组」标签中选择「新建策略组」，填写「名称」，「策略」选「手动选择」，在「成员」中勾选上游，对其中一个选择「设为优先」，然后选择「创建」。 +2. 按上面的步骤，在规则的「转发至」中选择这个策略组。 +3. 之后切换时，在路由页打开该策略组的操作菜单，在「优先使用」中选择一个成员。macOS 的菜单栏菜单和 Windows、Linux 的托盘菜单中也可以切换：每个手动选择的策略组显示当前使用的上游，子菜单中列出全部成员。 + +## 说明 + +- **为什么无需重启。**接管后的客户端配置中只有网关地址和它自己的密钥：Claude Code 是 `~/.claude/settings.json` 中的 `ANTHROPIC_BASE_URL` 与 `ANTHROPIC_AUTH_TOKEN`，Codex 是 `~/.codex/config.toml` 中名为 `thinkwatch` 的 provider。上游的地址、密钥和模型都在网关的配置中，由网关就地重新加载。已在进行的请求按它开始时的配置完成。 +- **Codex 的会话列表不会拆开。**Codex 的会话列表只列出当前 provider 的会话。接管期间它始终使用 `thinkwatch` 这个 provider，因此经网关开始的会话都在同一个列表中，与由哪个上游回答无关。接管之前的会话仍在原来的 provider 下，分开显示；要通过网关继续其中一个，运行 `codex resume <会话 ID> -c model_provider=thinkwatch`。 +- **进行中的对话。**在策略组中，一段对话在当前这一轮结束之前留在回答它的上游上；跨轮时，只要该上游的提示缓存仍有效，即最近一次回答在五分钟以内、且读写了至少 1,024 个缓存 token，也会留下。手动选择的策略组更换优先使用的上游后，新对话立即改用新上游，进行中的对话可能留在原上游，直到缓存过期或原上游失败。把规则改为转发至另一个上游或策略组，则从下一个请求起对所有对话生效。 +- **模型名。**模型列表中没有所请求模型的上游会被跳过。新上游使用不同的模型名时（例如以 GLM 代替 Claude），在规则上设置「模型改为」。更换模型后已缓存的 prompt 不再命中，费用按发出的模型名计算。 +- **只切换一个客户端。**每个接管的客户端都有自己的密钥。只切换其中一个、其余不变时，用「新建路由」建一条路由，在「使用此路由的密钥」中加入它的密钥。 + +相关文档：[功能详解](/zh-CN/docs/lite/features/#路由与故障转移)、[在多个中转站和多把密钥之间自动故障转移与负载均衡](/zh-CN/docs/lite/failover-and-load-balancing/)、[安装与更新](/zh-CN/docs/lite/install/)。 diff --git a/src/content/docs-lite/zh-CN/wsl-claude-code-codex.md b/src/content/docs-lite/zh-CN/wsl-claude-code-codex.md new file mode 100644 index 0000000..db3f39a --- /dev/null +++ b/src/content/docs-lite/zh-CN/wsl-claude-code-codex.md @@ -0,0 +1,39 @@ +# 在 WSL 中使用 Claude Code 和 Codex + +Windows 上的 ThinkWatch Lite 在客户端页列出每个 WSL 发行版中安装的 Claude Code 与 Codex，并像这台电脑上的客户端一样，把它们指向 Windows 上的网关。写入的地址是 `127.0.0.1`，WSL 1 和使用 mirrored 网络模式的 WSL 2 都能访问；WSL 2 默认使用 NAT 网络，此时应用提供改为 mirrored 模式和重启 WSL 的操作。 + +## 准备 + +- 在 Windows 10 21H2 及以上运行 ThinkWatch Lite，[安装版](/zh-CN/lite/#install)或绿色版均可。应用运行在 Windows 上，不在 WSL 内。本文按 2026.10.4 版编写。 +- WSL 1，或使用 mirrored 网络模式的 WSL 2；后者需要 Windows 11 22H2 及以上、WSL 2.0.5 及以上。`wsl --version` 查看版本，`wsl --update` 更新。 +- 发行版中已安装 Claude Code 或 Codex 并运行过一次，即 `~/.claude` 或 `~/.codex` 已存在。 +- 上游页中至少有一个上游。 + +## 步骤 + +1. 打开客户端页。在「这台电脑」之后，每个发行版是一个名为「WSL · <发行版>」的分组，组名下方说明它使用的网络。 +2. 组名下方显示「NAT 网络，无法接管。」时，选择「改为 mirrored 模式…」。对话框列出对 `%USERPROFILE%\.wslconfig` 的改动，选择「改为 mirrored」。 +3. 选择「重启 WSL…」，再选择「重启 WSL」。这会执行 `wsl --shutdown`：所有正在运行的发行版都会停止，其中运行的程序随之退出。 +4. 在该发行版的分组中，对 Claude Code 或 Codex 选择「接管…」，核对字段和完整改动后选择「接管」。 +5. Claude Code 从下一个请求起经过网关；Codex 需要在 WSL 中重新打开终端。 +6. 第一个请求之后，客户端的状态变为「使用中」，它的请求以它自己的密钥出现在流量页中。 + +## 说明 + +| 情况 | 结果 | +|---|---| +| WSL 1 | 可以接管，WSL 1 与 Windows 共用网络。 | +| 使用 mirrored 网络的 WSL 2 | 可以接管。 | +| 使用 NAT 网络的 WSL 2（默认） | 不能接管：WSL 内的 `127.0.0.1` 是 WSL 自身，网关也不监听 WSL 的虚拟网卡。页面提供「改为 mirrored 模式…」。 | +| Windows 10、Windows 11 21H2 | 没有 mirrored 网络模式，WSL 2 中的客户端无法接管。 | +| WSL 低于 2.0.5 | 需要先运行 `wsl --update`。 | + +- **对 `.wslconfig` 的改动。**只新增或修改 `networkingMode` 一项：写在 `[wsl2]` 下，原先写在旧的 `[experimental]` 下的就地修改。文件的其他内容保持不变，写入前完整备份。该设置对这台电脑上所有 WSL 2 发行版生效。完全卸载时不会改回，备份保留。 +- **重启后仍是 NAT。**WSL 重启后仍在使用 NAT 网络时，分组会说明未能启用 mirrored 网络模式，并再次提供「重启 WSL…」。 +- **只接管 Claude Code 和 Codex。**WSL 中只列出这两个客户端。Claude Desktop、Zed 等桌面客户端运行在 Windows 上，在「这台电脑」中接管。 +- **密钥分开。**WSL 中的每一份都有自己的密钥，与 Windows 上的那一份分开；配置文件经由 `\\wsl.localhost` 修改。单独还原、「全部还原…」和完全卸载都包括 WSL 中的客户端。 +- **读取会启动发行版。**打开客户端页时，应用经由 `\\wsl.localhost` 读取各个发行版，未运行的发行版会因此启动。 +- **远程 core。**连接部署在服务器上的网关时，WSL 中的客户端与 Windows 上的一样指向服务器，不受网络模式限制。 +- **路径。**模型可能给出另一侧写法的路径，客户端无法打开。插件页自带的「WSL 路径转换」插件（出厂关闭）把工具调用参数中的盘符路径改写为客户端能打开的写法；其适用范围可以限定为 WSL 中的客户端，这些客户端的名字形如 `claude-code-wsl-ubuntu`。 + +相关文档：[功能详解](/zh-CN/docs/lite/features/#客户端接管)、[安装与更新](/zh-CN/docs/lite/install/)、[插件](/zh-CN/docs/lite/plugins/)。 diff --git a/src/content/docs/_meta.ts b/src/content/docs/_meta.ts index bb2cad3..a1f23d7 100644 --- a/src/content/docs/_meta.ts +++ b/src/content/docs/_meta.ts @@ -10,10 +10,11 @@ import { localePath, type Lang } from "~/i18n"; export type ProductId = "thinkwatch" | "lite" | "core"; -export type GroupId = "getStarted" | "concepts" | "reference" | "operations" | "contributing"; +export type GroupId = "getStarted" | "guides" | "concepts" | "reference" | "operations" | "contributing"; export const groupLabels: Record> = { getStarted: { en: "Get started", "zh-CN": "入门" }, + guides: { en: "Guides", "zh-CN": "教程" }, concepts: { en: "Concepts", "zh-CN": "概念" }, reference: { en: "Reference", "zh-CN": "参考" }, operations: { en: "Operations", "zh-CN": "运维" }, @@ -31,6 +32,12 @@ export type DocMeta = { group: GroupId; /** Optional one-liner shown on docs home pages */ summary?: Record; + /** + * The page's own title, for the browser tab and search results, when the + * sidebar label is a shortened form of it (the guides: their titles are the + * questions people search for, too long for the sidebar) + */ + title?: Record; }; export type Product = { @@ -186,6 +193,105 @@ export const products: Product[] = [ "zh-CN": "用 pnpm tauri dev 运行开发版本，或打包 macOS 应用、Windows 安装程序与 Linux AppImage。", }, }, + { + slug: "claude-code-other-models", + label: { en: "Claude Code with other models", "zh-CN": "Claude Code 接国产模型" }, + title: { en: "Use Claude Code with GLM, DeepSeek or Kimi", "zh-CN": "让 Claude Code 使用 GLM、DeepSeek 或 Kimi" }, + locales: both, + group: "guides", + summary: { + en: "Point Claude Code at GLM, DeepSeek or Kimi through ThinkWatch Lite: name the model directly, or rewrite Claude model names with a routing rule.", + "zh-CN": "让 Claude Code 使用 GLM、DeepSeek 或 Kimi：直接用模型名，或用路由规则改写 Claude 模型名。", + }, + }, + { + slug: "codex-other-models", + label: { en: "Codex with other models", "zh-CN": "Codex 接其他模型" }, + title: { en: "Use Codex with Claude, Gemini or a Chat Completions-only relay", "zh-CN": "让 Codex 使用 Claude、Gemini 或只提供 Chat Completions 的中转" }, + locales: both, + group: "guides", + summary: { + en: "Run Codex on Claude, Gemini or a Chat Completions-only relay: ThinkWatch Lite converts the Responses API; the model is set in config.toml or a rule.", + "zh-CN": "让 Codex 使用 Claude、Gemini 或 Chat Completions 中转：网关转换格式，模型在配置或规则中指定。", + }, + }, + { + slug: "claude-desktop-third-party-models", + label: { en: "Claude Desktop with third-party models", "zh-CN": "Claude Desktop 用第三方模型" }, + title: { en: "Use Claude Desktop with third-party models", "zh-CN": "让 Claude Desktop 使用第三方模型" }, + locales: both, + group: "guides", + summary: { + en: "Connect Claude Desktop's official third-party inference mode to ThinkWatch Lite and rewrite its Claude model names to GLM, DeepSeek, Kimi or others.", + "zh-CN": "经官方第三方推理模式接入 Claude Desktop，用路由规则把 Claude 模型名改写为其他上游的模型。", + }, + }, + { + slug: "switch-upstreams-without-restart", + label: { en: "Switch upstreams without restarting", "zh-CN": "切换上游无需重启" }, + title: { en: "Switch relays, upstreams or models without restarting Claude Code or Codex", "zh-CN": "切换中转站、上游或模型，无需重启 Claude Code 与 Codex" }, + locales: both, + group: "guides", + summary: { + en: "Connect Claude Code or Codex once, then switch relays, upstreams or models in the gateway, with no client restart or config edit.", + "zh-CN": "Claude Code、Codex 接管一次，之后在网关中切换中转站、上游或模型，无需重启客户端或修改其配置。", + }, + }, + { + slug: "failover-and-load-balancing", + label: { en: "Failover and load balancing", "zh-CN": "故障转移与负载均衡" }, + title: { en: "Fail over and balance load across relays and API keys", "zh-CN": "在多个中转站和多把密钥之间自动故障转移与负载均衡" }, + locales: both, + group: "guides", + summary: { + en: "One upstream per relay key, grouped by strategy: in order, round robin, lowest latency, lowest cost or manual, with failover.", + "zh-CN": "每把密钥建一个上游，放进策略组按顺序、轮询、延迟最低、费用最低或手动选择，失败时自动换下一个。", + }, + }, + { + slug: "keep-api-keys-from-relays", + label: { en: "Keep API keys from relays", "zh-CN": "不让中转站拿到密钥" }, + title: { en: "Keep the API keys in requests away from relays, and block dangerous tool calls", "zh-CN": "防止中转站拿到请求中的 API 密钥，并拦截危险的工具调用" }, + locales: both, + group: "guides", + summary: { + en: "Outbound redaction swaps keys in requests for placeholders before a relay sees them; tool-call inspection cuts off dangerous calls.", + "zh-CN": "出站脱敏在中转站看到请求之前把其中的密钥换成占位符，工具调用审查切断危险的工具调用。", + }, + }, + { + slug: "wsl-claude-code-codex", + label: { en: "Claude Code and Codex in WSL", "zh-CN": "在 WSL 中使用" }, + title: { en: "Use Claude Code and Codex in WSL", "zh-CN": "在 WSL 中使用 Claude Code 和 Codex" }, + locales: both, + group: "guides", + summary: { + en: "Connect Claude Code and Codex inside WSL to ThinkWatch Lite on Windows, with WSL 1 or WSL 2 in mirrored networking.", + "zh-CN": "WSL 中的 Claude Code、Codex 接入 Windows 上的网关：支持 WSL 1 和 mirrored 网络。", + }, + }, + { + slug: "compare-cc-switch", + label: { en: "Compared with CC Switch", "zh-CN": "与 CC Switch 对比" }, + title: { en: "ThinkWatch Lite vs CC Switch", "zh-CN": "ThinkWatch Lite 与 CC Switch 对比" }, + locales: both, + group: "guides", + summary: { + en: "CC Switch rewrites client configs to switch providers; ThinkWatch Lite routes every request through a local gateway. Feature table and using both.", + "zh-CN": "CC Switch 改写客户端配置切换供应商，ThinkWatch Lite 经本机网关路由每个请求：功能对照、如何选择与同时使用。", + }, + }, + { + slug: "faq", + label: { en: "FAQ", "zh-CN": "常见问题" }, + title: { en: "ThinkWatch Lite FAQ", "zh-CN": "ThinkWatch Lite 常见问题" }, + locales: both, + group: "guides", + summary: { + en: "Answers about ThinkWatch Lite: cost, clients, platforms, Claude subscriptions, relays, data, signing, Codex sessions, servers and updates.", + "zh-CN": "Lite 常见问题：是否免费、支持的客户端与平台、Claude 订阅、中转站、数据与联网、签名、Codex 会话、服务器与更新。", + }, + }, { slug: "architecture", label: { en: "Architecture", "zh-CN": "架构" }, diff --git a/src/lib/faq.ts b/src/lib/faq.ts new file mode 100644 index 0000000..89f5f2e --- /dev/null +++ b/src/lib/faq.ts @@ -0,0 +1,47 @@ +// FAQPage structured data from a markdown FAQ: each `## ` heading is a question +// and the text up to the next heading is its answer, with the markdown reduced +// to plain text. The page shows the same questions and answers, as the +// structured data requires. + +function plain(markdown: string): string { + return markdown + .replace(/```[\s\S]*?```/g, " ") + .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1") + .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1") + .replace(/`([^`]+)`/g, "$1") + .replace(/(\*\*|__)(.+?)\1/g, "$2") + .replace(/(^|\s)[*_](\S[^*_]*?)[*_](?=\s|[.,;:!?)]|$)/g, "$1$2") + .replace(/^\s*(?:[-*+]|\d+\.)\s+/gm, "") + .replace(/^\|.*\|\s*$/gm, (row) => row.replace(/\|/g, " ").replace(/\s-{3,}\s/g, " ")) + .replace(/\s+/g, " ") + .trim(); +} + +export function faqPage(body: string, lang: string): Record | null { + const items: { q: string; a: string }[] = []; + let current: { q: string; lines: string[] } | null = null; + for (const line of body.split("\n")) { + const heading = /^##\s+(.+?)\s*$/.exec(line); + if (heading) { + if (current) items.push({ q: current.q, a: plain(current.lines.join("\n")) }); + current = { q: plain(heading[1]), lines: [] }; + } else if (/^#\s/.test(line)) { + continue; + } else if (current) { + current.lines.push(line); + } + } + if (current) items.push({ q: current.q, a: plain(current.lines.join("\n")) }); + const answered = items.filter((i) => i.q && i.a); + if (answered.length === 0) return null; + return { + "@context": "https://schema.org", + "@type": "FAQPage", + inLanguage: lang, + mainEntity: answered.map((i) => ({ + "@type": "Question", + name: i.q, + acceptedAnswer: { "@type": "Answer", text: i.a }, + })), + }; +} diff --git a/src/pages/docs/_DocArticle.astro b/src/pages/docs/_DocArticle.astro index 8afee6c..5697fe3 100644 --- a/src/pages/docs/_DocArticle.astro +++ b/src/pages/docs/_DocArticle.astro @@ -11,6 +11,7 @@ import { CORE_REPO } from "~/lib/core-docs.mjs"; import { firstPublished, lastModified } from "~/lib/lastmod"; import { docsOgCard, ogImagePath } from "~/lib/og"; import { organizationRef } from "~/lib/structured-data"; +import { faqPage } from "~/lib/faq"; import type { DocsEntry } from "./_lib"; interface Props { @@ -29,7 +30,14 @@ const { Content, headings } = await render(entry); const { prev, next } = getNeighbours(product, slug, lang); const docLabel = meta?.label[lang] ?? slug; -const title = `${docLabel} · ${productName(p, lang)} ${zh ? "文档" : "Docs"}`; +// A guide's own title is the question people search for: it names the product +// itself or is followed by it, in place of the shorter sidebar label. +const ownTitle = meta?.title?.[lang]; +const title = ownTitle + ? ownTitle.includes(p.name) + ? ownTitle + : `${ownTitle} · ${p.name}` + : `${docLabel} · ${productName(p, lang)} ${zh ? "文档" : "Docs"}`; const description = meta?.summary?.[lang] ?? p.tagline[lang]; // A document published from the Core repository: edited there, and credited @@ -65,7 +73,7 @@ const jsonLd: Record[] = [ { "@context": "https://schema.org", "@type": "TechArticle", - headline: slug ? docLabel : `${productName(p, lang)} ${zh ? "文档" : "documentation"}`, + headline: slug ? (ownTitle ?? docLabel) : `${productName(p, lang)} ${zh ? "文档" : "documentation"}`, description, inLanguage: lang, url: pageUrl, @@ -79,8 +87,13 @@ const jsonLd: Record[] = [ }, ]; -// On a product's docs home, list the rest of its docs below the overview. -const homeCards = slug ? [] : p.docs.filter((d) => d.slug); +// The FAQ also carries FAQPage structured data, built from its own headings. +const faq = slug === "faq" && entry.body ? faqPage(entry.body, lang) : null; +if (faq) jsonLd.push(faq); + +// On a product's docs home, list the rest of its docs below the overview. The +// guides are in the sidebar only, so the home keeps its few cards. +const homeCards = slug ? [] : p.docs.filter((d) => d.slug && d.group !== "guides"); ---