docs(account): lead sign-in with central provider key management

Explain registration and the existing account key store in English and Simplified Chinese README, installation and configuration guides, plus terminal login help. Account keys remain on the service for account-routed requests; uploading local keys is explicit, local use stays optional. Correct obsolete local/account secret-store claims and preserve historical v0.10.0 installation receipts rather than treating them as candidate proof. Validation: cargo fmt -p codewhale-cli --check passed. npm test: 531 passed, 0 failed, 7 skipped. npm run check:web: 772 tests passed, 0 failed; 894 pages built. Local English/Chinese install pages inspected in the in-app browser at desktop and phone widths; no page overflow or console errors. No real account or provider keys uploaded, modified or removed. Full Rust and cross-platform proof remains owned by exact-head CI and final binary QA. Signed-off-by: CodeWhale Bot <[email protected]>
2026-11-08 08:04:25 -10:00 · 2026-10-06 21:21:03 -07:00
1 parent 4a3001df70
commit a8e3d030ac
@@ -57,6 +57,13 @@ machine end up fighting over `PATH`.

 ## Quickstart

+**Your provider keys, managed in one place.** [Create a Codewhale account](https://app.codewhale.net/register)
+or run `codewhale login` to sign in. Save and update your API keys in your
+account, then use them through the Codewhale model route on your signed-in
+devices. [Set up account keys](docs/CONFIGURATION.md#account-provider-keys).
+Signing in does not upload existing local keys; local use remains available
+without an account.
+
 1. **Open your project.** Run `codewhale` in the folder you want to work on.
 2. **Connect a model.** Run `/provider` (or press `F3`) to add a hosted key or
   pick a local runtime. If Ollama is already running with a chat model,
@@ -1,4 +1,4 @@
-<!-- source: README.md sha256:604da19bff2c -->
+<!-- source: README.md sha256:004b3d422063 -->
 <div align="center">

 <picture>
@@ -57,6 +57,11 @@ Docker、Nix、Linux 上的 Homebrew、Android/Termux、带校验和验证的手

 ## 快速开始

+**在一个地方管理你的模型 API 密钥。** [注册 Codewhale 账号](https://app.codewhale.net/register)，
+或运行 `codewhale login` 登录。将密钥保存到账号后，可以集中更新，并在已登录的设备上
+通过 Codewhale 模型通道使用。[设置账号密钥](docs/zh_hans/CONFIGURATION.md#账号提供商密钥)。
+登录不会自动上传已有的本地密钥；不注册账号也可以继续在本地使用。
+
 1. **打开你的项目。** 在要处理的文件夹中运行 `codewhale`。
 2. **连接模型。** 运行 `/provider`（或按 `F3`）添加托管服务的密钥，或选择本地运行时。
   如果 Ollama 已在运行并带有聊天模型，Codewhale 会自动切换到它。使用 `/model` 更换模型。
@@ -343,14 +343,17 @@ New integrations should prefer `codewhale app-server`.")]
        after_help = "The browser receives a one-time loopback bootstrap capability, never the Runtime token.\nThe capability is exchanged for a bounded, process-local HttpOnly, SameSite=Strict web session and then invalidated."
    )]
    Web(WebArgs),
-    /// Sign in to your Codewhale account (browser device flow).
+    /// Sign in to manage your provider API keys in one place.
+    #[command(
+        after_help = "Create an account at https://app.codewhale.net/register or sign in through the browser.\nSave a provider key with `codewhale account keys set deepseek`, then choose Codewhale in /provider to use it across your signed-in devices.\nSigning in does not upload existing local keys. Local use does not require an account."
+    )]
    Login(LoginArgs),
    /// Remove saved authentication state (every provider key, OAuth login,
    /// the account session and the Daytona token). Asks before deleting.
    Logout(LogoutArgs),
    /// Manage authentication credentials and provider mode.
    Auth(AuthArgs),
-    /// Sign in to your Codewhale account and manage account-scoped provider keys.
+    /// Manage your Codewhale account and centrally stored provider keys.
    #[command(visible_alias = "cloud")]
    Account(cloud::CloudArgs),
    /// Offload a coding agent to the Codewhale cloud. Never spends or pushes without --confirm.
@@ -329,29 +329,50 @@ If a repo-local config declares `api_key`, `base_url`, `providers`, `provider`,
 `mcp_config_path`, `notes_path`, `hotbar`, `allow_shell = true`, or `instructions`,
 Codewhale ignores that key and keeps the user's global setting.

-The consolidated `codewhale` runtime uses one config file for DeepSeek auth
-and model defaults. `codewhale auth set --provider deepseek` saves
-the key to `~/.codewhale/config.toml` (migrating legacy `~/.deepseek/config.toml`
-on first launch when needed), and `codewhale --model deepseek-v4-flash` is
-forwarded to the TUI as `CODEWHALE_MODEL`. The dispatcher no longer writes the
-`DEEPSEEK_*` twins of these variables; a `DEEPSEEK_*` value you set yourself is
-still read as a legacy alias when the `CODEWHALE_*` one is unset.
+The consolidated `codewhale` runtime uses `~/.codewhale/config.toml` for
+provider and model settings. `codewhale auth set --provider deepseek` saves
+the key in the local secret store (a private file under `~/.codewhale/secrets/`
+by default; the OS keychain is an explicit option), rather than writing it
+into that config file. Legacy `~/.deepseek/config.toml` is migrated on first
+launch when needed. `codewhale --model deepseek-v4-flash` is forwarded to the
+TUI as `CODEWHALE_MODEL`. The dispatcher no longer writes `DEEPSEEK_*` twins;
+a value you set yourself remains a legacy alias when its `CODEWHALE_*`
+equivalent is unset.

-`codewhale login` signs in to the Codewhale account — it is the same browser
-device flow as `codewhale account login`, not a provider-key command. Provider
-credentials are configured exclusively through `codewhale auth set
--provider <provider>`.
+### Account provider keys

-That provider credential is distinct from the optional managed-product
-account. `codewhale account login` starts the Codewhale browser device flow;
-`codewhale account status` and `codewhale account logout` inspect or remove the
-session for the selected `--profile`. Account sessions prefer the OS
-credential manager and fall back automatically to the private `0600`
-Codewhale secrets file when no credential manager is available (headless
-hosts, SSH, containers).
-`codewhale account keys list|set|remove` manages the
-signed-in account's BYOK vault without displaying secret values. The older
-`codewhale cloud ...` spelling remains a command alias.
+A Codewhale account lets you **manage your provider API keys in one place**.
+[Register](https://app.codewhale.net/register) or [sign in](https://app.codewhale.net/login),
+then add, replace or remove keys in [Providers settings](https://app.codewhale.net/providers)
+or from the terminal:
+
+```bash
+codewhale login                         # browser sign-in; also: account login
+codewhale account keys set deepseek      # hidden prompt; add or replace a key
+codewhale account keys list              # configured status, never secret values
+codewhale --provider codewhale           # use the account's model route
+```
+
+Account keys stay on the service and are used for account-routed requests.
+Sign in on another device and choose Codewhale in `/provider` to use them
+without pasting keys again. `/models` lists models available to that account.
+Replacing a saved account key affects subsequent requests through this route;
+it does not change independent local copies or revoke keys at the provider.
+`codewhale account keys remove deepseek` removes the account's saved key.
+
+Login does **not** upload existing local keys. If you want to copy one, choose
+`codewhale account keys set deepseek --from-local` explicitly. Normal local
+provider setup remains `codewhale auth set --provider <provider>`; local keys
+and local models work without a Codewhale account. Signing in preserves an
+explicit or already configured local provider. Choose `--provider codewhale`
+when you want the account route instead.
+
+The account session is separate from provider keys. `codewhale account status`
+inspects it; `codewhale account logout` removes it for the selected `--profile`
+without removing your provider keys. Account sessions use the private `0600`
+Codewhale secrets file, scoped to the profile and account API origin; they do
+not use the OS keychain. The older `codewhale cloud ...` spelling remains an
+alias for account commands.

 ### Portable config bundles

@@ -468,7 +489,7 @@ Anthropic providers, set `provider = "<id>"` or pass
 For the provider-by-provider registry, including wire protocol, auth variables,
 default base URLs, model IDs, and capability metadata, see
 [PROVIDERS.md](PROVIDERS.md).
-The facade saves provider credentials to the shared user config and forwards
+The facade saves provider credentials in the local secret store and forwards
 the resolved key, base URL, provider, and model to the TUI process. Use
 `codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"` or
 `codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"` or
@@ -11,9 +11,9 @@ works with many model providers. **DeepSeek** is the default.

 The command is `codewhale`. `codew` is a shorter alias for the same program.

-This guide was written by installing **v0.10.0** (released 2026-09-22) on a
-fresh **Ubuntu 24.04 x86_64** machine, on every path described here. Every
-command shown was run and its output checked (see the [install receipts](https://github.com/codewhale-hq/Codewhale/blob/37ecdfcc49bc68a9b0d058b97c3946e62c34bd31/docs/install-report/v0.10.0-2026-09-23/RECEIPTS.md)). Steps that
+The installation paths were first checked with **v0.10.0** (released 2026-09-22) on a
+fresh **Ubuntu 24.04 x86_64** machine. The dated
+[install receipts](https://github.com/codewhale-hq/Codewhale/blob/37ecdfcc49bc68a9b0d058b97c3946e62c34bd31/docs/install-report/v0.10.0-2026-09-23/RECEIPTS.md) record the commands and output checked at that time. Steps that
 could not be run on that machine are marked **(untested on this VM: reason)**.
 macOS, Windows and Android are out of scope, apart from a few notes. A second
 pass re-ran the installer, manual-download, archive and npm paths, the no-key
@@ -27,6 +27,29 @@ version (for example a v0.10.1 source candidate before its tag). A
 prebuilt candidate is available through the official installer only after its
 tag, checksums and release assets exist. Contributors can build `main` now.

+## One account for your provider keys
+
+[Register](https://app.codewhale.net/register) or [sign in](https://app.codewhale.net/login)
+to keep your model providers' API keys in one place. Add, replace or remove
+keys in your account's [Providers settings](https://app.codewhale.net/providers),
+or use the terminal commands below. On another device, sign in and select the
+Codewhale model route to use the same account keys without pasting them again.
+
+```bash
+codewhale login
+codewhale account keys set deepseek  # asks for the key without echoing it
+codewhale account keys list         # shows status, never the key itself
+codewhale --provider codewhale      # use your account's model route
+```
+
+The account setup here describes the 0.10.1 source candidate. Signing in does
+not upload existing local keys. To copy one deliberately, use
+`codewhale account keys set deepseek --from-local`. Account keys stay on the
+service; they are used for account-routed requests, not downloaded into each
+device's local key store. You can keep using local keys or a local model
+without an account. See [account key settings](CONFIGURATION.md#account-provider-keys)
+for updating keys and switching between these options.
+
 ## Test and contribute to current source

 `latest` selects the latest published release. To test unreleased repairs,
@@ -183,11 +183,44 @@ allow_shell = true

 覆盖刻意很窄——它覆盖仓库维护者最可能想要跨贡献者标准化的字段。凭据、端点、provider 选择、MCP 配置、hooks、skills、重试、热栏绑定和 `instructions = [...]` 设置保持用户全局。如果仓库本地配置声明了 `api_key`、`base_url`、`providers`、`provider`、`mcp_config_path`、`notes_path`、`hotbar`、`allow_shell = true` 或 `instructions`，Codewhale 会忽略该键并保留用户的全局设置。

-合并的 `codewhale` 运行时为 DeepSeek 认证和模型默认值使用同一个配置文件。`codewhale auth set --provider deepseek` 把 key 保存到 `~/.codewhale/config.toml`(需要时在首次启动迁移旧 `~/.deepseek/config.toml`)，`codewhale --model deepseek-v4-flash` 作为 `CODEWHALE_MODEL` 转发给 TUI。分发器不再写入这些变量的 `DEEPSEEK_*` 孪生变量；你自己设置的 `DEEPSEEK_*` 值在对应的 `CODEWHALE_*` 未设置时仍作为旧别名读取。
+合并的 `codewhale` 运行时使用 `~/.codewhale/config.toml` 保存提供商和模型设置。
+`codewhale auth set --provider deepseek` 把密钥保存在本地机密存储中（默认是
+`~/.codewhale/secrets/` 下的私有文件；OS 钥匙串需显式选择），而不是写入该配置文件。
+需要时，首次启动会迁移旧 `~/.deepseek/config.toml`。
+`codewhale --model deepseek-v4-flash` 作为 `CODEWHALE_MODEL` 转发给 TUI。
+分发器不再写入对应的 `DEEPSEEK_*` 变量；用户自己设置的值在 `CODEWHALE_*`
+未设置时仍作为旧别名读取。

-`codewhale login` 登录 Codewhale 账号——它与 `codewhale account login` 是同一个浏览器设备流(device flow)，不是 provider-key 命令。Provider 凭据完全通过 `codewhale auth set --provider <provider>` 配置。
+### 账号提供商密钥

-该 provider 凭据与可选的管理产品账号是分开的。`codewhale account login` 启动 Codewhale 浏览器设备流；`codewhale account status` 和 `codewhale account logout` 检查或移除所选 `--profile` 的会话。账号会话优先使用 OS 凭据管理器，在无凭据管理器可用时自动回退到私有 `0600` Codewhale secrets 文件(无头主机、SSH、容器)。`codewhale account keys list|set|remove` 管理已登录账号的 BYOK 保险库(vault)，不显示机密值。更旧的 `codewhale cloud ...` 拼写仍是命令别名。
+Codewhale 账号的直接好处是：**在一个地方管理模型提供商的 API 密钥**。
+[注册](https://app.codewhale.net/register)或[登录](https://app.codewhale.net/login)后，
+可以在[提供商设置](https://app.codewhale.net/providers)中添加、更换或移除密钥，
+也可以使用终端：
+
+```bash
+codewhale login                         # 浏览器登录；也可用 account login
+codewhale account keys set deepseek      # 隐藏输入，添加或更换密钥
+codewhale account keys list              # 只显示配置状态，不显示密钥
+codewhale --provider codewhale           # 使用账号的模型通道
+```
+
+账号密钥保存在服务端，用于经过账号通道的请求。在另一台设备上登录并在
+`/provider` 中选择 Codewhale，即可使用这些密钥，无需再次粘贴。`/models`
+列出该账号可用的模型。更换账号中保存的密钥会影响此通道的后续请求，但不会改变
+独立的本地副本，也不会撤销提供商侧的密钥。`codewhale account keys remove deepseek`
+移除账号中保存的密钥。
+
+登录**不会**自动上传已有的本地密钥。若希望复制本地密钥，请明确使用
+`codewhale account keys set deepseek --from-local`。本地提供商仍通过
+`codewhale auth set --provider <provider>` 配置；使用本地密钥或本地模型不需要
+Codewhale 账号。登录会保留显式选择或已配置的本地提供商；需要切换到账号通道时，
+使用 `--provider codewhale`。
+
+账号会话与提供商密钥分开保存。`codewhale account status` 查看会话；
+`codewhale account logout` 移除所选 `--profile` 的账号会话，不删除提供商密钥。
+账号会话使用私有 `0600` Codewhale secrets 文件，按 profile 和账号 API 来源隔离，
+不使用 OS 钥匙串。旧的 `codewhale cloud ...` 仍是账号命令的别名。

 ### 可移植配置包（Portable config bundles）

@@ -217,7 +250,7 @@ allow_shell = true

 运行 `codewhale auth status` 检查活动 provider 的配置文件、OS 钥匙串后端、环境变量、胜出来源和末四位标签，而不打印 key 本身。该命令只探测活动 provider 的钥匙串条目。

-对于托管、通用 OpenAI 兼容、自托管、OpenAI Responses 或原生 Anthropic provider，设置 `provider = "<id>"` 或传 `codewhale --provider <id>`。规范的 provider ID 是 `deepseek`、`nvidia-nim`、`openai`、`atlascloud`、`wanjie-ark`、`volcengine`、`openrouter`、`orcarouter`、`xiaomi-mimo`、`novita`、`fireworks`、`siliconflow`、`arcee`、`siliconflow-CN`、`moonshot`、`sglang`、`vllm`、`ollama`、`ollama-cloud`、`huggingface`、`modelscope`、`together`、`qianfan`、`openai-codex`、`anthropic`、`openmodel`、`zai`、`stepfun`、`minimax`、`deepinfra`、`sakana`、`longcat`、`opencode-go`、`opencode-zen`、`meta`、`xai`、`mistral`、`telecomjs`、`modelstudio-token-plan`、`google`、`edenai`、`concentrate`、`codewhale` 和 `custom`(通过 `[providers.<name>]` 定义的用户自定义 OpenAI 兼容端点)。逐 provider 的 registry，包括线协议、认证变量、默认 base URL、模型 ID 和能力元数据，见 [PROVIDERS.md](PROVIDERS.md)。facade 把 provider 凭据保存到共享用户配置，并把解析后的 key、base URL、provider 和模型转发给 TUI 进程。使用 `codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"` 或 `codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"` 或 `codewhale auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"` 或 `codewhale auth set --provider wanjie-ark --api-key "YOUR_WANJIE_API_KEY"` 或 `codewhale auth set --provider xiaomi-mimo --api-key "YOUR_XIAOMI_KEY"` 或 `codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"` 或 `codewhale auth set --provider siliconflow --api-key "YOUR_SILICONFLOW_API_KEY"` 或 `codewhale auth set --provider arcee --api-key "YOUR_ARCEE_API_KEY"` 或 [PROVIDERS.md](PROVIDERS.md) 中匹配的 provider ID，通过 facade 保存 provider key。通用 `openai` provider 默认 `https://api.openai.com/v1`,接受 `OPENAI_BASE_URL`，默认 `gpt-5.6`。自定义 OpenAI 兼容网关仍可显式选择自己的模型。`atlascloud` 默认 `https://api.atlascloud.ai/v1`,接受 `ATLASCLOUD_BASE_URL`，默认模型是 `deepseek-ai/deepseek-v4-flash`。`wanjie-ark` 指向 Wanjie Ark 的 OpenAI 兼容端点 `https://maas-openapi.wanjiedata.com/api/v1`,默认 `deepseek-reasoner`，并原样透传模型 ID，因为 Wanjie 模型访问按账号作用域。SGLang、vLLM 和 Ollama 是自托管的，默认可以不用 API key 运行。Ollama 默认 `http://localhost:11434/v1`,并原样发送 `codewhale-coder:1.3b` 或 `qwen2.5-coder:7b` 这样的模型标签。自托管 provider 和 loopback 自定义 URL(`localhost`、`127.0.0.1`、`[::1]`、`0.0.0.0`)不读取 secret store，除非显式请求 API key 认证；当本地服务器确实需要 bearer 认证时，用环境变量或配置文件 key。Ollama Cloud 是独立的托管 `ollama-cloud` provider。它默认 `https://ollama.com/v1` 和 `gpt-oss:120b`；用 `codewhale auth set --provider ollama-cloud` 保存它的 key。环境认证先读 `OLLAMA_CLOUD_API_KEY`，然后是 Ollama 官方的 `OLLAMA_API_KEY`。SiliconFlow 默认 `https://api.siliconflow.com/v1`,接受 `SILICONFLOW_BASE_URL`，默认用 `deepseek-ai/DeepSeek-V4-Pro`。`provider = "siliconflow-CN"` 选择中国区域默认 `https://api.siliconflow.cn/v1`,配 `[providers.siliconflow_cn]` 表和 `SILICONFLOW_API_KEY` 凭据槽位。Arcee AI 默认 `https://api.arcee.ai/api/v1`,接受 `ARCEE_BASE_URL`，对 Codewhale 智能体工作默认用 `trinity-large-thinking`。`trinity-large-preview` 也作为直接的 Arcee API 模型列出；OpenRouter 的 `arcee-ai/trinity-large-thinking` 仍是 OpenRouter 命名空间形式，而直接 Arcee provider 用裸的 `trinity-large-thinking` ID。直接的 Arcee 大模型 API 调用按 256K 上下文 BF16 服务跟踪；Thinking 具备推理能力，而 Preview 未标记为推理模型。
+对于托管、通用 OpenAI 兼容、自托管、OpenAI Responses 或原生 Anthropic provider，设置 `provider = "<id>"` 或传 `codewhale --provider <id>`。规范的 provider ID 是 `deepseek`、`nvidia-nim`、`openai`、`atlascloud`、`wanjie-ark`、`volcengine`、`openrouter`、`orcarouter`、`xiaomi-mimo`、`novita`、`fireworks`、`siliconflow`、`arcee`、`siliconflow-CN`、`moonshot`、`sglang`、`vllm`、`ollama`、`ollama-cloud`、`huggingface`、`modelscope`、`together`、`qianfan`、`openai-codex`、`anthropic`、`openmodel`、`zai`、`stepfun`、`minimax`、`deepinfra`、`sakana`、`longcat`、`opencode-go`、`opencode-zen`、`meta`、`xai`、`mistral`、`telecomjs`、`modelstudio-token-plan`、`google`、`edenai`、`concentrate`、`codewhale` 和 `custom`(通过 `[providers.<name>]` 定义的用户自定义 OpenAI 兼容端点)。逐 provider 的 registry，包括线协议、认证变量、默认 base URL、模型 ID 和能力元数据，见 [PROVIDERS.md](PROVIDERS.md)。facade 把 provider 凭据保存到本地机密存储，并把解析后的 key、base URL、provider 和模型转发给 TUI 进程。使用 `codewhale auth set --provider nvidia-nim --api-key "YOUR_NVIDIA_API_KEY"` 或 `codewhale auth set --provider openai --api-key "YOUR_OPENAI_COMPATIBLE_API_KEY"` 或 `codewhale auth set --provider atlascloud --api-key "YOUR_ATLASCLOUD_API_KEY"` 或 `codewhale auth set --provider wanjie-ark --api-key "YOUR_WANJIE_API_KEY"` 或 `codewhale auth set --provider xiaomi-mimo --api-key "YOUR_XIAOMI_KEY"` 或 `codewhale auth set --provider fireworks --api-key "YOUR_FIREWORKS_API_KEY"` 或 `codewhale auth set --provider siliconflow --api-key "YOUR_SILICONFLOW_API_KEY"` 或 `codewhale auth set --provider arcee --api-key "YOUR_ARCEE_API_KEY"` 或 [PROVIDERS.md](PROVIDERS.md) 中匹配的 provider ID，通过 facade 保存 provider key。通用 `openai` provider 默认 `https://api.openai.com/v1`,接受 `OPENAI_BASE_URL`，默认 `gpt-5.6`。自定义 OpenAI 兼容网关仍可显式选择自己的模型。`atlascloud` 默认 `https://api.atlascloud.ai/v1`,接受 `ATLASCLOUD_BASE_URL`，默认模型是 `deepseek-ai/deepseek-v4-flash`。`wanjie-ark` 指向 Wanjie Ark 的 OpenAI 兼容端点 `https://maas-openapi.wanjiedata.com/api/v1`,默认 `deepseek-reasoner`，并原样透传模型 ID，因为 Wanjie 模型访问按账号作用域。SGLang、vLLM 和 Ollama 是自托管的，默认可以不用 API key 运行。Ollama 默认 `http://localhost:11434/v1`,并原样发送 `codewhale-coder:1.3b` 或 `qwen2.5-coder:7b` 这样的模型标签。自托管 provider 和 loopback 自定义 URL(`localhost`、`127.0.0.1`、`[::1]`、`0.0.0.0`)不读取 secret store，除非显式请求 API key 认证；当本地服务器确实需要 bearer 认证时，用环境变量或配置文件 key。Ollama Cloud 是独立的托管 `ollama-cloud` provider。它默认 `https://ollama.com/v1` 和 `gpt-oss:120b`；用 `codewhale auth set --provider ollama-cloud` 保存它的 key。环境认证先读 `OLLAMA_CLOUD_API_KEY`，然后是 Ollama 官方的 `OLLAMA_API_KEY`。SiliconFlow 默认 `https://api.siliconflow.com/v1`,接受 `SILICONFLOW_BASE_URL`，默认用 `deepseek-ai/DeepSeek-V4-Pro`。`provider = "siliconflow-CN"` 选择中国区域默认 `https://api.siliconflow.cn/v1`,配 `[providers.siliconflow_cn]` 表和 `SILICONFLOW_API_KEY` 凭据槽位。Arcee AI 默认 `https://api.arcee.ai/api/v1`,接受 `ARCEE_BASE_URL`，对 Codewhale 智能体工作默认用 `trinity-large-thinking`。`trinity-large-preview` 也作为直接的 Arcee API 模型列出；OpenRouter 的 `arcee-ai/trinity-large-thinking` 仍是 OpenRouter 命名空间形式，而直接 Arcee provider 用裸的 `trinity-large-thinking` ID。直接的 Arcee 大模型 API 调用按 256K 上下文 BF16 服务跟踪；Thinking 具备推理能力，而 Preview 未标记为推理模型。

 ### OpenRouter 提供商固定

@@ -7,10 +7,30 @@ Codewhale 是一个在终端里运行的开源编码智能体（coding agent）

 命令是 `codewhale`。`codew` 是同一个程序的较短别名。

-本指南是在一台全新的 **Ubuntu 24.04 x86_64** 机器上安装 **v0.10.0**（2026-09-22 发布）时写成的，这里描述的每条路径都实际走过。文中每条命令都运行过，输出也核对过（见[安装回执](https://github.com/codewhale-hq/Codewhale/blob/37ecdfcc49bc68a9b0d058b97c3946e62c34bd31/docs/install-report/v0.10.0-2026-09-23/RECEIPTS.md)）。在那台机器上无法运行的步骤标注为 **（该虚拟机上未测试：原因）**。macOS、Windows 和 Android 不在测试范围内，只有少量说明。第二轮在 **macOS 26.1（Apple silicon）** 上重新运行了安装器、手动下载、压缩包和 npm 路径、无密钥检查以及 zsh 补全，见 [macOS 说明](#macos-说明)。需要调用模型的步骤没有在 macOS 上重跑。
+安装路径最初是在一台全新的 **Ubuntu 24.04 x86_64** 机器上使用 **v0.10.0**（2026-09-22 发布）验证的。带日期的[安装回执](https://github.com/codewhale-hq/Codewhale/blob/37ecdfcc49bc68a9b0d058b97c3946e62c34bd31/docs/install-report/v0.10.0-2026-09-23/RECEIPTS.md)记录了当时实际运行的命令和核对的输出。在那台机器上无法运行的步骤标注为 **（该虚拟机上未测试：原因）**。macOS、Windows 和 Android 不在测试范围内，只有少量说明。第二轮在 **macOS 26.1（Apple silicon）** 上重新运行了安装器、手动下载、压缩包和 npm 路径、无密钥检查以及 zsh 补全，见 [macOS 说明](#macos-说明)。需要调用模型的步骤没有在 macOS 上重跑。

 使用 `latest` 的安装命令会解析到最新**已发布**的 GitHub Release 或包。两次发布之间，`main` 可能已经在描述下一个版本（例如尚未打标签的 v0.10.1 源码候选版）。预编译候选版只有在标签、校验和与发布资源齐备后，才可通过官方安装器获取；贡献者可以先从 `main` 构建源码。

+## 用一个账号管理提供商密钥
+
+[注册](https://app.codewhale.net/register)或[登录](https://app.codewhale.net/login)
+后，就能集中管理模型提供商的 API 密钥。在账号的[提供商设置](https://app.codewhale.net/providers)
+中添加、更换或移除密钥，也可以使用下面的终端命令。换一台设备时，登录并选择
+Codewhale 模型通道，就能使用同一组账号密钥，无需再次粘贴。
+
+```bash
+codewhale login
+codewhale account keys set deepseek  # 隐藏输入，不回显密钥
+codewhale account keys list         # 只显示状态，不显示密钥
+codewhale --provider codewhale      # 使用账号的模型通道
+```
+
+这里的账号设置说明针对 0.10.1 源码候选版。登录不会自动上传已有的本地密钥。
+如果明确希望复制本地密钥，请使用 `codewhale account keys set deepseek --from-local`。
+账号密钥保存在服务端，用于经过账号通道的请求，不会下载到每台设备的本地密钥存储。
+不注册账号也可以使用本地密钥或本地模型。更换密钥、选择账号或本地通道的说明见
+[账号密钥设置](CONFIGURATION.md#账号提供商密钥)。
+
 ## 使用当前源码参与测试与贡献

 `latest` 表示最新已发布版本；想测试尚未发布的修复，请使用权威 GitHub