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 构建的编程 Agentagentic coding agent理解它的会话 / 工作区 / 审批安全模型学会用 Plan / Act / Operate 三种模式组织代码任务并通过斜杠命令、结构化工具、子代理与技能完成从仓库勘察到落地实现的完整闭环。文中还融合了仓库源码级的实现证据帮助你建立可检索、可验证的操作心智。1. 欢迎使用 Codewhale一个以 Harness 为核心的终端编码 AgentCodewhale 是一款运行在终端里的编码 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 | shWindows 用户应选择 GitHub Releases 中对应的安装器或压缩包详见 docs/INSTALL.md 中针对占用目录、包管理器安装与 PATH 配置的迁移指引。若是已存在的直接安装可先codewhale update --check再codewhale updatenpm 与 Cargo 是次级分发通道Cargo 还支持在无对应预编译产物时进行源码构建。Android/Termux 走其独立的预览归档或源码构建路径参见 docs/INSTALL.md。需要隔离运行时可以用 Dockerdocker 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若尚未配置 PATHGitHub 安装器的默认落点是$HOME/.local/bin/codewhale。2.2 首启只问必要决策其余交给斜杠命令首次启动时 Codewhale只询问当前安装确实需要的决策无法推断语言时问语言、没有可用路由时选 provider、目录需要裁决时确认工作区信任workspace trustprovider 步骤还包含明确的离线offline选项。就绪画面会直接打开真实的 composer并保留命令行传入的任务或针对当前目录建议首个任务。其余全部是可选项随时可用/setup——渐进式设置与修复向导/settings——完整的类型化编辑器/constitution——自定义随附的工作约定standing guidance。本地化的遥测选项只会在工作区就绪后出现不会阻塞 composer。2.3 配置默认 providerDeepSeekDeepSeek 是默认 provider。最直接的配 key 方式是codewhale auth set --provider deepseek也可以走环境变量export DEEPSEEK_API_KEYyour-key codewhaleCLI 层的这一能力对应 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 mentionsWorkbarcomposer 下方的条带或可选的侧边 workbar持有激活的 goal、待办列表与子代理。行会在整个会话中保留——完成的工作读起来是已办而不是消失——点击一行或在其上按Enter会打开详情Status / footer实时活动、排队中的后续动作与简短的命令提示。底部 chrome 可配置用/statusline选择可见内容或在config.toml中设置[tui].status_items。每个键在屏幕上只负责一件事mode是姿态栏posture bar上的 plan/act/operate 芯片model、context_percent、cost、balance仅限预付 providerDeepSeek、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/sprovider 报告的、按流式秒数折算的输出 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. 模式ModesPlan / Act / Operate 与审批姿态Codewhale 有三种可见的 TUI 模式模式用途默认姿态Plan改动前的探索、设计与评审只读调查Act常规多步编码工作带审批门禁的工具使用Operate直接工作 并行或后台协调工具遵循当前姿态适合时委托TUI 内用模式选择器切换/mode或直接切换/mode plan /mode act /mode operatePlan 模式是陌生仓库里最安全的起点用于检查与决策而非改文件。在非平凡任务中Plan 模式的确认提示可展示有依据的 PlanArtifactobjective、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。对可信工作区若你有意让动作无需审批提示直接执行用ShiftTab选择Full Access权限姿态——但不要在你不信任的仓库里用 Full Access。模式与模型路由相互独立Tab在 composer 空闲时循环可见模式/model auto控制每轮对话的模型与思考级别。你也可以从/config编辑审批模式来改变审批行为——只有理解它会如何影响工具执行时才这样做。完整参考见 docs/MODES.md。6. 斜杠命令直接改状态的控制面斜杠命令直接输入 composer用于直接改变 Codewhale 状态而不是用自然语言请模型代劳。新手常用命令命令用途/mode打开模式选择器或用/mode agent切换/model选择模型或用/model auto/provider选择当前 API provider/fleet打开所选 fleet 的成员名册/fleet saved选择 / 切换命名的已保存 fleet/goal设置跨回合持久的客观目标裸/goal显示进度/workflow把当前工作编排为 Workflowstatus、cancel、settings无需模型回合即可应答/workflows打开实时 Workflow 运行看板本工作区 journal 保留的每次运行含阶段、子任务、进度与 host 侧取消/config编辑运行时与 provider 设置/statusline选择底部状态芯片的可见性/compact压缩长上下文以回收 token 预算/copy复制最后一条完成的助手回复到剪贴板/review请求一次结构化评审工作流/memory启用时检查或管理 memory/mcp配置或检查 MCP 服务器集成/plugin审查与管理默认禁用的本地插件包/rc将会话交接给已登录的 Codewhale Web 应用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选择器会说明当前可用哪条数据路径并显示最近解析的路由。CtrlO打开当前回合的推理明细CtrlAltO或/turn inspect打开整回合的 Turn Inspector其 model-route 一节记录具体 provider/model、strong/fast 对、所选档位、选择范围、路由理由以及分类器是否收到路由上下文。需要可复现对比、严格 provider 边界或不想发分类请求时使用固定模型。会话变长、模型背负过多历史时用/compact——它以牺牲原始转录细节换取简洁的工作摘要。本指南有意不穷举命令命令面变化快于引导流会话内的 TUI 命令面板才是事实源头。运行时设置见 docs/CONFIGURATION.mdMCP 集成见 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.常用角色角色适用general多步任务未指定角色时的默认explore只读代码勘测plan设计与迁移规划review针对既有改动的 bug 聚焦评审implementer严格规格化的编辑verifier运行检查并回报通过/失败证据角色的字符串解析与能力边界在仓库中有明确实现例如 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.mdmanager、ownership 与 provenance 规则、docs/CLAUDE_PLUGIN_COMPAT.mdClaude 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。FAQCodewhale 只支持 DeepSeek 吗DeepSeek 是默认且一等公民的路由但 Codewhale 也支持其他托管与本地 OpenAI 兼容 provider。用/provider或codewhale --provider id选择配置非默认路由时请打开 provider registry 文档docs/PROVIDERS.md。第一个模式应该用哪个陌生代码用 Plan常规实现用 ActFull 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考