Codewhale 终端编程智能体实战上手指南：首次启动、模式审批与工具驱动开发全流程

Codewhale 终端编程智能体实战上手指南：首次启动、模式审批与工具驱动开发全流程

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale

<输出文章>

Codewhale 终端编程智能体实战指南：首次启动、安全模式与工具驱动工作流

本篇指南面向 Codewhale 的第一个小时：你将掌握如何在终端中启动这款基于 Rust 构建的编程 Agent（agentic coding agent），理解它的会话 / 工作区 / 审批安全模型，学会用 Plan / Act / Operate 三种模式组织代码任务，并通过斜杠命令、结构化工具、子代理与技能完成从仓库勘察到落地实现的完整闭环。文中还融合了仓库源码级的实现证据，帮助你建立可检索、可验证的操作心智。

1. 欢迎使用 Codewhale：一个以 Harness 为核心的终端编码 Agent

Codewhale 是一款运行在终端里的编码 Agent：你从某个工作区（workspace）启动它、给它一个任务，它会调用结构化工具来查看文件、执行命令、编辑代码，并带着证据回报结果。

它与普通聊天模型的本质区别在于，Codewhale 围绕一套harness（运行时框架）构建：

• 始终持有可见的活动工作区与会话；
• 每一轮对话都经由明确的模式（mode）与审批规则（approval rules）分发；
• 工具调用直接呈现在转录（transcript）中，而不是把过程藏起来；
• 支持保存会话、分叉对话、之后继续；
• 可以派生子代理（sub-agent）承担聚焦的后台工作。

你可以用它回答小问题：

Explain the authentication flow in this repository.

也可以让它处理多步骤任务：

Find the failing validation path, propose a fix, and wait for my approval before editing files.

新仓库的最佳起点是保守策略：先让 Codewhale 勘察并制定计划，再允许它改动文件。这样你会得到一条可审查的路径，也能在错误假设演变成代码之前尽早发现它们。

Codewhale 的运行时模型与内部 harness 结构参见 docs/ARCHITECTURE.md。

2. 首次启动：安装、鉴权与运行前诊断

2.1 安装与镜像两种入口

macOS / Linux 新装推荐使用官方 GitHub Release 安装器，它会校验发行包的校验和，并把同一套运行时同时暴露为codewhale与codew两个命令名：

curl -fsSL https://codewhale.net/install.sh | sh

Windows 用户应选择 GitHub Releases 中对应的安装器或压缩包（详见 docs/INSTALL.md 中针对占用目录、包管理器安装与 PATH 配置的迁移指引）。若是已存在的直接安装，可先codewhale update --check再codewhale update；npm 与 Cargo 是次级分发通道，Cargo 还支持在无对应预编译产物时进行源码构建。Android/Termux 走其独立的预览归档或源码构建路径，参见 docs/INSTALL.md。

需要隔离运行时可以用 Docker：

docker volume create codewhale-home docker run --rm -it \ -e DEEPSEEK_API_KEY="$DEEPSEEK_API_KEY" \ -v codewhale-home:/home/codewhale/.codewhale \ -v "$PWD:/workspace" \ -w /workspace \ ghcr.io/hmbown/codewhale:latest

一旦安装目录进入 PATH，在你想让它工作的仓库或目录中直接启动即可：

codewhale

若尚未配置 PATH，GitHub 安装器的默认落点是"$HOME/.local/bin/codewhale"。

2.2 首启只问必要决策，其余交给斜杠命令

首次启动时 Codewhale只询问当前安装确实需要的决策：无法推断语言时问语言、没有可用路由时选 provider、目录需要裁决时确认工作区信任（workspace trust），provider 步骤还包含明确的离线（offline）选项。就绪画面会直接打开真实的 composer，并保留命令行传入的任务或针对当前目录建议首个任务。

其余全部是可选项，随时可用：

• /setup——渐进式设置与修复向导；
• /settings——完整的类型化编辑器；
• /constitution——自定义随附的"工作约定"（standing guidance）。

本地化的遥测选项只会在工作区就绪后出现，不会阻塞 composer。

2.3 配置默认 provider（DeepSeek）

DeepSeek 是默认 provider。最直接的配 key 方式是：

codewhale auth set --provider deepseek

也可以走环境变量：

export DEEPSEEK_API_KEY="your-key" codewhale

CLI 层的这一能力对应 crates/cli/src/lib.rs 中的auth set实现，仓库测试还专门验证了"auth set使用隔离文件存储、写入密钥存储并保持配置不含明文凭据、且不会切换当前激活 provider"等边界行为（见 crates/cli/src/lib.rs 中auth_set_*系列测试用例）。新配置统一存放在~/.codewhale/config.toml；为兼容旧名称迁移用户，旧~/.deepseek/config.toml依旧被支持。

2.4 doctor 诊断：离线优先，明确区分"已声明"与"可用"

装好之后跑一次体检：

codewhale doctor

需要给 issue 附上机器可读报告时用 JSON 形态：

codewhale doctor --json

两种形态默认都处于离线状态：它们只报告结构性配置与"字面上未知 / 未探测"的凭据状态，而不会加载工作区.env凭据、打开 secret/OAuth 文件、探测 keyring、联系 provider 或启动 MCP 服务器。只有当你确实想越过该实时边界时才显式开启--check-updates、--probe-api、--probe-local或--probe-mcp。JSON 形态始终离线，也不接受这些 live 标志。

JSON 报告把凭据的source（来源）与字面的availability（可用性）分开表述：配置了环境变量、external-auth、OAuth、consent、secret-store 等来源的凭据一律保持not_probed——仅有声明并不会让 Setup 或 fleet 就绪；只有"结构上确实存在的字面配置值"或"无需凭据的路由"才能证明离线就绪。若某条路由上残留了无法使用共享存储的旧 secret-store 哨兵，会单独报告为secret_store_unavailable/unavailable，而不是当作 eligible 或 merely unknown。

doctor与doctor --json还包含一项会话恢复诊断：比较旧版会话文件名与当前存储，报告isolated、no_legacy_sessions、migration_pending、migration_incomplete、migration_complete或scan_failed之一，且从不读取会话内容。出现migration_pending或migration_incomplete时，请把会话从~/.deepseek迁移到~/.codewhale。显式设置CODEWHALE_HOME可抑制这项环境级检查。

平台相关安装路径、配置解析与 provider 标识分别见 docs/INSTALL.md、docs/CONFIGURATION.md 与 docs/PROVIDERS.md。

3. 你的第一个任务：写好四要素提示词

先在一个真实工作区里做只读任务：

Map the repository structure and tell me where the CLI entrypoint lives.

然后请求一份聚焦的计划：

I want to add a small validation for empty config values. Inspect the relevant code and propose the smallest safe change before editing anything.

准备好改代码时，务必写清验收标准：

Implement the validation you proposed. Keep the change scoped to config parsing, add or update the narrowest test, and run the relevant check.

好的首任务提示词通常包含四点：

• 你想要的结果；
• 你关心的文件 / 功能 / 行为；
• 什么不在范围内（out of scope）；
• 什么样的验证算完成。

一个完整示例：

Fix the broken provider error message in the config loader. Do not change the provider registry. Add a regression test and run only the config crate tests.

不确定 bug 在哪时就直说：

Investigate why `codewhale doctor` reports the wrong provider. Do not edit files yet. Return the likely cause, evidence, and a proposed patch plan.

经验法则：陌生代码把"调查"与"落地"分成两步，小且理解透彻的改动可以一步提交。关于何时使用 Plan / Act / Operate，见 docs/MODES.md。

4. 理解交互界面：TUI 的稳定区域与可配置状态栏

交互式 TUI 由几个稳定区域组成：

• Header：当前会话、激活模型、模式与高层状态；
• Transcript：对话、工具调用、命令输出摘要与模型回复；
• Composer：输入提示词、斜杠命令与文件提及（file mentions）；
• Workbar：composer 下方的条带（或可选的侧边 workbar），持有激活的 goal、待办列表与子代理。行会在整个会话中保留——完成的工作读起来是"已办"而不是消失——点击一行（或在其上按Enter）会打开详情；
• Status / footer：实时活动、排队中的后续动作与简短的命令提示。

底部 chrome 可配置：用/statusline选择可见内容，或在config.toml中设置[tui].status_items。每个键在屏幕上只负责一件事：mode是姿态栏（posture bar）上的 plan/act/operate 芯片；model、context_percent、cost、balance（仅限预付 provider：DeepSeek、DeepSeekCN、OpenRouter、SiliconFlow）、cache、tokens、session_metrics则属于其下方的指标行分段。省略status_items保留内置默认；设为[]则把指标行裁到只剩帮助提示。

几点源码可证实的细节：

• context_percent默认开启，任何饱满度下都显示ctx NN%——0.9.12 曾让其在 50% 以下静默、导致大部分会话没有任何上下文信号；读数从 80% 起保持警告色。
• session_metrics（默认开启）在指标行绘制延迟对：ttft 1.5s（首个流式 token 的平均到达时间）与120 tok/s（provider 报告的、按流式秒数折算的输出 token）。二者来自/status完整打印的同一组累加器（turns、steps、LLM 与工具的 wall time、缓存命中、输入量）；provider 或运行时证据尚未到达的量会被省略而非估算。窄行上这一对会先于 cost 与 context 读数被裁掉，而不是截断数字。
• 0.9.13 退役了status、agents、reasoning_replay、prefix_stability、git_branch、last_tool_elapsed、rate_limit这些不起作用的键；旧配置文件仍可加载——退役键被忽略并写一条日志警告。

这些行为在 crates/tui/src/config.rs 中有直接实现：status_items采用宽容反序列化（未知键跳过并警告，保证旧配置兼容），StatusItem枚举（如ContextPercent => "context_percent"、SessionMetrics => "session_metrics"）定义了持久化字符串到运行时片段的映射。TUI 进程内的doctor与sessions等命令分发可见于 crates/cli/src/lib.rs。

Transcript 就是审计轨迹：Codewhale 读文件、跑命令、改代码都会出现在其中。命令失败时，把可见的失败输出作为下一条指令的一部分，而不是推倒重来。

Composer 接受普通提示与斜杠命令，输入/即可发现可用命令；想让模型聚焦某个文件/目录而非大范围搜索时，用文件提及。Workbar 在跨多步的回合中很有价值：转录持续增长的同时，goal、待办与代理状态始终可见——即便工作已尘埃落定，你仍能打开查看当时发生了什么。

键盘快捷键随上下文、终端与平台而变，本指南不复制完整快捷键目录以免与 TUI 漂移。完整参考见 docs/KEYBINDINGS.md。

5. 模式（Modes）：Plan / Act / Operate 与审批姿态

Codewhale 有三种可见的 TUI 模式：

TUI 内用模式选择器切换：

/mode

或直接切换：

/mode plan /mode act /mode operate

• Plan 模式是陌生仓库里最安全的起点，用于检查与决策而非改文件。在非平凡任务中，Plan 模式的确认提示可展示有依据的 PlanArtifact：objective、context、sources used、critical files、constraints、approach、verification plan、risks、handoff notes。当代理使用这种富工件形态时，空章节也是可见的——你可以要求修订，而不是接受一份未充分定义的方案。
• Act 模式是大多数贡献工作的默认选择：可读、可跑检查、可编辑文件，同时把有风险的操作挡在审批门之后。
• Operate 模式保留直接工具面及其审批、沙箱、shell、ask-rule 与仓库保护，差异在于编排侧重：独立、并行、后台或长时工作优先交给 fleet worker；小而紧耦合的工作可留在父进程。重活也可通过codewhale dispatch或/dispatch提议给 Daytona 云代理（需显式确认；远端为github/cnb/gitee），详见 docs/DAYTONA_CLOUD_DISPATCH.md。

对可信工作区，若你有意让动作无需审批提示直接执行，用Shift+Tab选择Full Access权限姿态——但不要在你不信任的仓库里用 Full Access。

模式与模型路由相互独立：Tab在 composer 空闲时循环可见模式，/model auto控制每轮对话的模型与思考级别。你也可以从/config编辑审批模式来改变审批行为——只有理解它会如何影响工具执行时才这样做。完整参考见 docs/MODES.md。

6. 斜杠命令：直接改状态的控制面

斜杠命令直接输入 composer，用于直接改变 Codewhale 状态，而不是用自然语言请模型代劳。新手常用命令：

Toolbox 命令直接输入也可搜索到：/models拉取实时端点 ID、/modeldb打开随附模型参考、/rlm把文件或文本块装入会在整个会话保持可用的工作上下文。

想切换默认 DeepSeek 路由时用/provider——provider ID、环境变量、模型默认值与能力说明都在 provider registry 文档中（docs/PROVIDERS.md）。软自动多代理工作见 docs/AUTOMATIC_WORKFLOWS.md；以 bot 身份发布 Codewhale PR 评审见 docs/GITHUB_APP.md。持久化多 worker 工作入门走 docs/FLEET_WORKFLOW_TUTORIAL.md，它逐步讲解 fleet 任务规格、监控与 Workflow 编写。

Fleet 是持久化名册的公开名词：codewhale fleet …是命令，/fleet是斜杠命令。Fleet 这个名字承载着跨版本必须稳定的那些东西：持久化账本.codewhale/fleet.jsonl、保存的名册fleets/<name>.toml、[fleet]与[fleets.*]配置表，以及codewhale workflow run --fleet标志。

自动模型路由与理性化审计

需要 Codewhale 每轮自主选择模型与思考级别时用/model auto。当 DeepSeek 路由模型可用时，Auto 会在脱敏库存（redacted inventory）中选择任何可运行的 provider/model 组合。该分类会把最新请求（上限 4000 字符）加上至多六条最近上下文行的有界摘要（每条 900 字符）发给DeepSeek / deepseek-v4-flash；凭据、端点与 provider 报错文本不会进入库存。没有该路由器时，Auto 使用本地的、provider 感知启发式，且不发送任何路由请求。若分类尝试校验失败或出错，Auto 回退到该启发式，同时把尝试过的分类器数据路径保留在回合回执中。

/model选择器会说明当前可用哪条数据路径，并显示最近解析的路由。Ctrl+O打开当前回合的推理明细；Ctrl+Alt+O（或/turn inspect）打开整回合的 Turn Inspector，其 model-route 一节记录具体 provider/model、strong/fast 对、所选档位、选择范围、路由理由，以及分类器是否收到路由上下文。需要可复现对比、严格 provider 边界或不想发分类请求时，使用固定模型。

会话变长、模型背负过多历史时用/compact——它以牺牲原始转录细节换取简洁的工作摘要。本指南有意不穷举命令：命令面变化快于引导流，会话内的 TUI 命令面板才是事实源头。运行时设置见 docs/CONFIGURATION.md，MCP 集成见 docs/MCP.md，默认禁用的插件包清单 / 能力评审 / 命名空间化 Skill-MCP 激活边界见 docs/PLUGIN_BUNDLES.md。

7. 与工具协作：结构化动作、工作区边界与沙箱

Codewhale 的"工具"是结构化动作：模型不只产散文，还可以调用工具检查与改变工作区。工具型工作包括：解释前先读文件、提议重构前先搜索调用点、运行聚焦的测试命令、打一个小补丁、派生子代理做并行调查。

工具使用受模式、审批与沙箱策略约束，具体行为取决于当前模式与配置，但基本规则很简单：Plan 做只读探索，Act 做常规改动，Full Access 留给可信自动化。工作区边界很重要——Codewhale 预期工作在你启动它的目录或配置的工作区里。任务应明确限定在仓库内：

Only inspect and edit files under this repository. Do not touch parent directories or global config.

命令需要网络、写到工作区之外、或属于高风险 shell 操作时，除非你配置了更宽松的行为，否则会看到审批提示。工具指令要具体：

Run the narrowest test that covers this parser change. If it fails, report the failure and stop before broadening the test scope.

避免在聚焦修复时顺手做宽泛清理——更小的工具作用域让转录更好审、最终 diff 更容易合入。工具面清单与沙箱行为分别见 docs/TOOL_SURFACE.md 与 docs/SANDBOX.md。

8. 子代理与并行工作：角色、agent 工具与长程一致性

子代理是后台子级 Agent：父会话给子代理一个聚焦任务、拿到一个 agent id，即可在子代理运行的同时继续自己的工作。

核心编排工具是agent：用一个任务与角色启动聚焦的子代理，子代理在后台运行并返回紧凑回执加转录句柄。通常你不必直接调用它，用自然语言请求并行工作即可：

Open one read-only explorer for the config crate and another for the TUI provider picker. Have both return file references and risks before we plan the fix.

常用角色：

角色的字符串解析与能力边界在仓库中有明确实现：例如 crates/config/src/lib.rs 的FleetSlot把general/scout/planner/implementer/reviewer/verifier/operator/summarizer等名称规范化，并注明"运行时对未声明的角色不再视为可写，而是关闭到只读explore姿态（#5575）"——即未知角色默认只读、fail-closed；默认FleetRole的名字正是general（见同文件Default实现）。消息层Role的封闭集合与字节级序列化约束见 crates/core/src/role.rs。

子代理在能干净切分的工作里最有用：不要为微小编辑动用它们，也不要让多个代理同时写同一批文件。

跨很多回合的工作如何保持一致

多回合工作不依赖一份无限膨胀的聊天转录，这是 Agent 的常态行为——没有需要开启的开关，也没有需要额外学习的工作流：

• 工作上下文（working context）在整个会话保持加载。大型源材料与持久转录作为可搜索、可切片的数据被持有，有用的变量与导入跨回合存活。
• Workflow 组合独立的task(...)调用与并行扇出。
• agent消息与后续动作直接协调存活的子代理。
• Goals 在工作过程中保留持久目标。

/rlm <file-or-text>把工作上下文指向特定文件或文本块。历史上 action 形态的rlm工具仍被注册，仅为让旧会话重放，且刻意不教给新模型回合。

Codewhale 还会在工作区维护一个项目本地账本.codewhale/harness/state.json：有证据的提示笔记、可复用的子代理简报与技能路由提示。后续回合把它当作不可信的补充引导（untrusted supplemental guidance），绝不是权威或可执行指令。读取是自动的；增删条目走正常审批回执。它与个人 memory 分离，绝不应存放 secrets、草稿转录或未经证实的断言。角色、生命周期、并发与输出契约的完整说明见 docs/SUBAGENTS.md。

9. 技能（Skills）：把可复用流程固化为 SKILL.md

技能（Skills）是可复用的指令包，通常是一个SKILL.md文件，教 Codewhale 如何执行一类循环工作流、使用某个工具族或遵循某项项目约定。当任务有可重复流程时使用：评审某种 PR、处理某种文档/表格格式、跟随团队发布清单、走项目专属的 memory/wiki 工作流。

TUI 内/skill <name>在有可用技能时激活它；裸/skills打开Skills Manager（仅拥有的清单，无网络）。文本/registry 路径用/skills <prefix>、/skills inspect、/skills --remote、/skills suggest <task>或/skills sync。suggestions 会给远程目录排序，但绝不安装或激活任何东西。命令面板也能把技能条目与普通斜杠命令并列展示。

好的技能应该窄：告诉模型遵循什么工作流、收集什么证据、避开什么；不应藏凭据，也不应取代普通仓库文档。如果仓库自带指引，把它当作活跃工作的一部分：编辑前先读本地指引，让任何贡献符合仓库约定。仓库本身也沉淀了一批真实的技能样例，例如docs/skills/cw-land、cw-slice、cw-orient、gh-*系列等，可作为编写自有SKILL.md的参考范本。详见 docs/SKILLS.md（manager、ownership 与 provenance 规则）、docs/CLAUDE_PLUGIN_COMPAT.md（Claude Code 技能/插件兼容）与 docs/CONFIGURATION.md（配置路径与项目权威）。

10. 获取帮助：诊断、报 issue 与故障排查

先看 doctor 输出：

codewhale doctor

要给详细 issue 附 JSON 报告：

codewhale doctor --json

认证问题用结构性来源状态识别"声明了什么"——doctor 刻意不检查环境、secret-store、keyring 或 OAuth token 的值。确实需要活体检查时，用codewhale doctor --probe-api（或本地端点用--probe-local）显式打开。Provider 问题先确认激活的 provider 与模型：/provider、/model。长或混乱的会话用/compact降低上下文压力，或同一工作区开新会话并总结你需要的上下文。

报 issue 时请附上：

• Codewhale 版本；
• 安装方式；
• 操作系统与终端；
• provider 与 model；
• 确切的命令或提示词；
• 相关 doctor 输出；
• 该问题在全新工作区是否复现。

不要把 API key、私有源码或 secrets 贴进公开 issue。运维分级与恢复步骤见 docs/OPERATIONS_RUNBOOK.md。

FAQ

Codewhale 只支持 DeepSeek 吗？

DeepSeek 是默认且一等公民的路由，但 Codewhale 也支持其他托管与本地 OpenAI 兼容 provider。用/provider或codewhale --provider <id>选择；配置非默认路由时请打开 provider registry 文档（docs/PROVIDERS.md）。

第一个模式应该用哪个？

陌生代码用 Plan，常规实现用 Act，Full Access 仅限可信仓库、且可接受自动执行时才用。

为什么运行命令前 Codewhale 会询问？

审批是安全模型的一部分。shell 命令、付费工具、写操作与预期工作区之外的动作都可能产生副作用。审批提示让你在模型干活的同时保持控制。

如何在 macOS 上运行一个 Python 文件？

在文件所在目录打开 Terminal 运行：

python3 your_file.py

若系统提示缺python3，可以从 python.org 下载，或用 Homebrew 安装：

brew install python

在 Codewhale 里，可以让代理先检查文件再用python3 your_file.py运行。脚本需要依赖时先在虚拟环境里安装：

python3 -m venv .venv source .venv/bin/activate python3 -m pip install -r requirements.txt python3 your_file.py

配置存在哪里？

新 Codewhale 配置在~/.codewhale/config.toml；旧~/.deepseek/config.toml为兼容仍受支持。存在工作区配置时，项目覆盖层（project overlays）也可能影响行为。

如何让成本可预测？

用/model auto做路由、需要严格画像时选固定模型、长会话及时压缩。更大任务先让 Codewhale 规划再实现，避免把 token 花在错误路径上。

如何继续之前的工作？

Codewhale 会保存会话。用/sessions选择器或 README / modes 指南里的 resume/continue CLI 路径恢复。做有风险的实验时，先 fork 会话再改变方向。/sessions选择器默认限定当前工作区，让恢复保持在打开的项目内；在 picker 里按a显示所有工作区的会话，或运行codewhale sessions在恢复前查看全部保存会话及最近更新时间戳。

要把当前正在运行的会话接到 Web 应用继续，输入/rc或codewhale rc启动，在系统浏览器里批准一次性授权码。租约有效期内浏览器持有新提示与审批，终端是可读的安全观测面。连接后横幅与转录备注会显示实时会话链接；/rc open在浏览器打开、/rc link打印链接。/rc status显示所有权、/rc stop把控制权交还终端，interrupt 始终可用。断连会让本地输入保持锁定，直到最后一个 Web 租约过期——保证两个控制器永不竞争。同一终端纳入的每个目录共享一个稳定 device id，因此 Web 应用按机器列出一台电脑，而不是按会话列出一堆。

模型变糊涂了怎么办？

停下来重述目标、约束与当前证据。转录太长就/compact或开新会话做简短 handoff。若是运维问题，跑codewhale doctor检查配置与 provider 状态。

项目规则该写进提示词还是文件？

持久性项目规则放仓库文件，单回合意图放提示词。如果某个流程跨项目重复，考虑把它固化成技能。

Codewhale 能编辑当前仓库之外的文件吗？

取决于工作区边界、沙箱设置、信任模式与审批策略。做贡献工作时应把指令限定在当前仓库，除非你确实需要别的。

本指南之后该去哪？

针对你正在改的东西读对应参考。多数用户接下来的页面是：安装、配置、providers、modes、keybindings、tools 与 sub-agents——即 docs/INSTALL.md、docs/CONFIGURATION.md、docs/PROVIDERS.md、docs/MODES.md 与 docs/TOOL_SURFACE.md。

【免费下载链接】CodewhaleOpen-source coding agent for your terminal, built in Rust and on a journey of continuous community improvement. Issues and PRs welcome.项目地址: https://gitcode.com/GitHub_Trending/de/Codewhale