简介

铁锤（Tiechui）是用 Rust 写的终端编程代理。安装后得到一个二进制，命令名是 chui，也可以用 tiechui。

它有两种用法：直接运行 chui 进入终端界面，和模型来回对话；或者用 chui exec 在脚本、CI 里跑一次，打印结果后退出。两种用法共用同一套会话、provider、工具、权限和模块。

先看这几篇

快速开始

npm i -g @tiechui/cli
chui

第一次运行时还没有 provider，chui 会依次问你服务、地址、密钥和模型，列出服务提供的模型，发一次请求确认能用，然后把配置存到 ~/.tiechui。之后想加别的 provider，运行 chui setup。

还不支持的

铁锤还在快速变化，1.0 之前配置和会话格式都可能改。下面这些目前没有：

• 操作系统级沙箱。权限检查是规则闸门，放行后的命令以你的用户权限运行。
• 订阅账号登录。
• chui mcp serve。
• Homebrew 安装。

安装

支持 macOS、Linux 和 Windows (x64)。内容搜索用 ripgrep，npm 包、安装脚本和发布压缩包里都带了一份；文件查找和 @ 补全是内置的，不依赖外部工具。

npm

npm i -g @tiechui/cli

需要 Node 16 以上。npm 会把对应平台的原生构建作为可选依赖装上，pnpm、yarn、bun 也可以用。

macOS 和 Linux

curl -fsSL https://github.com/b1ank1108/tiechui/releases/latest/download/install.sh | sh

脚本会用 SHA256SUMS 校验压缩包，把 chui 和 tiechui 装到 ~/.local/bin，自带的 rg 放在 ~/.local/libexec/tiechui，不会替换你已经装的 rg。

• TIECHUI_VERSION：固定安装某个版本。
• TIECHUI_INSTALL_DIR：换安装目录。这时 rg 放在该目录上一级的 libexec/tiechui。

Windows

irm https://github.com/b1ank1108/tiechui/releases/latest/download/install.ps1 | iex

在 PowerShell 里运行。chui.exe、tiechui.exe 和 rg.exe 会装到 %LOCALAPPDATA%\Programs\tiechui，并加进用户的 Path。上面两个环境变量同样有效。

bash 工具在 Windows 上通过 Git for Windows 带的 Git Bash 运行。如果找不到，设置 TIECHUI_GIT_BASH_PATH 指过去。

从源码构建

需要 Git 和用 rustup 装的 Rust。仓库固定在 1.95.0，带 rustfmt 和 clippy。

cargo install --locked --path crates/tiechui-cli --root <prefix>

这会把 chui 和 tiechui 装进 <prefix>/bin，但不带 rg，内容搜索会去 PATH 或 ~/.tiechui/bin 里找。开发时可以不安装，直接 cargo run --locked --bin chui -- --help。

托管安装

在 macOS 和 Linux 上，也可以用 cargo xtask dist 打包，或者从 GitHub Release 下载 tarball，再交给 xtask 安装：

cargo xtask install tiechui-VERSION-TARGET.tar.gz --prefix ~/.local
~/.local/bin/chui doctor --prefix ~/.local
cargo xtask uninstall --prefix ~/.local

安装器没有默认 prefix，必须自己指定。它会：

• 校验压缩包和清单，包括自带的 rg，但不安装 rg；
• 在 <prefix>/.tiechui-install/ 记下自己装的每个二进制的哈希；
• 拒绝覆盖不是它装的命令，比如 cargo install 装的那份；
• 修复被移动或装了一半的安装，安装中断时按日志回滚。

安装不会碰你的 profile 和会话。

连接模型

铁锤没有内置模型列表，用哪个服务、哪个模型都要自己声明。最省事的办法是运行 chui setup，它会写出下面这样的最小配置。想手动改，看这一篇。

声明 provider

provider 只能写在 ~/.tiechui/providers.toml，项目配置和命令行参数都不能添加或修改。文件里每个顶层表是一个 provider：

[gateway]
wire = "openai-completions"            # 或 "openai-responses"、"anthropic-messages"
base_url = "https://gateway.example"   # 没有版本段时自动补 /v1
api_key_env = "GATEWAY_API_KEY"        # 或 api_key = "..." 直接写密钥

[gateway.compat]                       # 只给非 OpenAI 的服务用
thinking_format = "deepseek"
max_tokens_field = "max_tokens"
requires_reasoning_content_on_assistant_messages = true

[[gateway.models]]
id = "example-model"
context_window = 400000
max_output = 131072
reasoning = true
images = true

• wire 是协议：Anthropic Messages、OpenAI Chat Completions 或 OpenAI Responses。
• 不写 base_url 时，按协议默认 https://api.anthropic.com 或 https://api.openai.com。地址里已经带版本段的（比如 /api/paas/v4）原样使用。
• compat 用来适配 DeepSeek 风格的推理网关这类服务。单个模型也可以有自己的 compat，覆盖其中几项，适合一个网关里混着几家模型的情况。
• 模型还可以设置 cache_retention、prices；Anthropic 协议下还有 fallback_models。

选择模型

在 ~/.tiechui/config.toml 里用 <provider>/<model id> 指定默认模型：

model = "gateway/example-model"
thinking = "high"                      # off | minimal | low | medium | high | xhigh | max

[tui]
theme = "automatic"                    # 跟随终端背景

[modules]
# goal = false                         # 内置模块默认全部开启

思考级别会被限制在模型 thinking_levels 声明的范围内。openai-responses 关闭思考时发送 effort none；不支持的模型可以把 off 映射成 "minimal"，或者标成 false。

会话里也可以随时用 /model 和 /thinking 切换，切换后会存成新会话的默认值。

密钥

每个 provider 的密钥二选一：在 providers.toml 里直接写 api_key，或者用 api_key_env 指定一个环境变量。

• 直接写进文件的密钥不会传给工具继承的环境。记得 chmod 600，chui doctor 会检查这一点。
• 铁锤不会自己加载任何密钥文件。用 api_key_env 时，要在启动 chui 的那个 shell 里先导出变量。

网络

[network] 可以给模型和 MCP 请求设置代理、不走代理的主机和额外的 CA 证书。它和 [sessions]、[skills] 一样，只从 ~/.tiechui/config.toml 读取。

命令行

交互模式

chui                                         # 在当前目录打开
chui --cwd ~/src/app --model gateway/example-model --thinking high
chui --mode auto                             # 这次运行用 auto 权限模式
chui --yolo                                  # 等于 --mode yolo
chui --resume                                # 从已保存的会话里挑一个
chui --resume SESSION_ID

chui exec

不打开界面，跑完一轮就退出，适合脚本和 CI：

chui exec "Explain the failing tests"
chui exec "Continue" --resume SESSION_ID --json --approval allow-listed

• 支持 --model、--thinking、--mode、--yolo 和 --cwd。
• --resume ID：恢复会话。无界面模式下必须给出 ID。
• --json：打印协议事件，而不只是最终回答。
• --approval：没人能回答权限询问时怎么处理，见权限。

子命令

每个子命令都支持 --help。

内置工具

模型默认能用的工具有 read、write、edit、grep、find、bash，以及管理后台命令的 shell_list、shell_output、shell_stop。模块、插件和 MCP 服务器会再加别的工具。

按键与输入

快捷键

输入框里的前缀

• /：打开命令菜单。Tab 补全，Enter 执行。
• @：查找文件和目录。Tab 进入目录，Enter 插入 @path 引用。Shift+Tab 切到 All，可以搜插件、技能和任务。
• $：按名称或描述选技能。发送消息时才会加载技能内容。
• !command：自己跑一条 shell 命令。它和模型的命令一样要过权限检查，也会出现在 /shells 里，可以转到后台。

状态行

输入框下面一行，左边是模型、目录和分支，右边是权限模式（不是 rules 时才显示）和剩余上下文。后台有 shell、目标或定时任务在跑时，会多出第二行。用 /statusline 选择要显示哪些项。

斜杠命令

在输入框里输入 / 打开。关掉某个模块后，它带的命令也会消失；插件和提示模板可以加新命令。

后台 shell

开发服务器、文件监听这类命令不会自己结束。模型给 bash 加上 background: true 后，半秒左右就能拿到任务 ID 和这段时间的输出，然后继续干别的；命令结束时模型会收到通知。如果命令在这半秒内已经跑完，直接返回完整结果。

• shell_output 读后面的输出，shell_stop 停掉命令。
• 命令的超时设置照样生效。
• 后台任务跟着会话结束。子代理只能在前台跑命令。

/shells 面板

列出正在跑和最近跑过的命令。在面板里：

• b：把正在跑的命令转到后台；
• x：停止；
• Enter：看输出；Esc：关闭。

你自己用 !command 跑的命令也会出现在这里。

会话与回退

会话

每个会话是一棵只追加的 JSONL 树，可以分支。会话文件按工作目录分组，放在 ~/.tiechui/sessions/。

• 恢复会话会还原消息和各模块的状态。
• 会话内的临时授权和旁聊不会还原。
• chui --resume 或 /resume 打开选择器，可以搜索和预览。

回退

/rewind，或者在输入框为空时按两次 Esc，可以把代码、对话或两者恢复到之前的某一轮。恢复前会先列出受影响的修改让你确认，被放弃的那条分支也会保留。

旁聊

主对话正在跑，你又想问点别的，可以用 /btw。旁聊拿到的是主对话上下文的一份冻结副本，在侧栏里单独进行，不会打断主对话。

• 旁聊里可以用工具。读取和搜索直接允许；要改工作区，得在旁聊里明说，并且照样要过权限检查。文件系统和主对话是共享的。
• 主对话需要你回应（比如权限询问）时，侧栏底部会提示，按 Ctrl+/ 切回去。
• Ctrl+S 把旁聊最后一条回答发到主对话里。
• /btw model [provider/id] 可以给旁聊单独指定模型。

除了用 Ctrl+S 发过去的内容，旁聊在重新加载或重启后就没了。

目标

/goal 目标描述 给当前会话设一个持续的目标。会话空闲时，代理会自己接着往下做，不用你每次再发消息。

• 目标挂在当前分支上。进行中时，规则线下方会显示已用的 token 和时长。
• Esc 或 Ctrl+C 会暂停目标。重启之后，目标会等你输入或者 /goal resume 才继续。
• /goal edit、pause、resume、clear 分别是修改、暂停、继续、清除。

定时提示

/loop 5m 检查一下 CI 结果

上面这条会立刻执行一次，之后在会话空闲时每 5 分钟执行一次。像 7m 这种不能均匀落在时钟上的间隔，会取最接近的 cron 周期，确认信息里会写明。

• 模型也可以自己用 cron 表达式（本地时间）安排一次性或周期性的提示。
• /cron-list 列出所有任务，包括项目里保存的；/cron-delete <id> 取消。
• 输入框里有没发出去的草稿时，到点的任务会等你发送或清空之后再跑。

任务默认只活在当前会话里。要跨会话保留，存到已信任项目的 .agents/scheduled_tasks.json。周期任务 7 天后过期。

上下文压缩

会话很长时不用重开。有两种压缩方式，共用同一套界面提示（◇）。

检查点

上下文接近上限、请求溢出但还能恢复、或者你手动执行 /compact 时，铁锤会把较早的对话总结成一份摘要，后面的请求从摘要接着走。/compact 后面可以加说明，告诉它摘要里要保留什么。

区间压缩

模型可以用 context_status、compact_history、search_history、read_history 这四个工具自己按区间压缩历史，压掉的原文之后还能搜索和读取。

查看上下文

/context 打开上下文面板，能看到各类内容占了多少，以及系统提示、工具、注入、消息和缓存的明细。

子代理

模型可以用 subagent 工具把一部分工作交给子代理。不指定 agent 时运行默认的通用子代理；也可以用 profile 或项目 agents/*.md 里定义的代理。

• 每个任务可以单独指定 model（<provider>/<id> 或 inherit）和 thinking。父会话会自动知道当前有哪些模型可用。
• 一次可以派一个任务，最多 8 个并行的任务，或者一串按顺序执行的任务。整个会话同时最多跑 8 个子任务，多出来的排队。
• 子代理有自己的会话和授权，但受父代理的权限策略约束。

/subagents 查看子任务和输出。输入框为空时按 Alt+Left / Alt+Right 打开查看器，左边是任务列表，右边是详情；ctrl+x 停止，ctrl+f 搜索。

权限

检查什么

每次工具调用、每条 shell 命令（用 tree-sitter 解析）、涉及的路径和 MCP 调用，都会先经过拦截器。

规则

每条规则有 surface、pattern 和 action，action 是 allow、ask 或 deny，deny 可以附带 reason。同一个 surface 里，最后匹配上的规则生效；显式的 deny 总是优先。

默认允许读取和搜索类工具、会话工具、MCP 元数据和只读的 shell 命令，其余都要问你。设置 permissions.rules = [] 会去掉这些默认放行。

问你的时候，可以允许这一次、在本会话内允许同类操作，或者拒绝。恢复会话时，会话内的授权不会带过去。

模式

模式决定规则本来要问你的那些调用怎么处理：

设置模式的几种方法：

• 用户配置里的 permissions.mode。项目配置不能设置模式。
• 命令行 --mode 或 --yolo，只对这次运行有效，两者不能同时用。
• /permissions <mode> 切换当前会话，并存到 permissions.mode。存成 yolo 后，之后每个会话都是 yolo，直到你改回来。

受保护路径

写入下面这些路径时，rules 和 auto 模式都会问你，除非你有用户级的 protected_path 规则放行：

.git、.agents、.claude、.tiechui、.vscode、.idea、shell 配置文件、.gitconfig、.mcp.json、.env 文件。

显式的 deny 规则在任何模式下都有效。项目里无效的权限规则会失效关闭：rules 和 auto 下问你，yolo 下直接拒绝。即使是 yolo，request_user_input 以及目录、hooks、插件的信任确认仍然会问你。

无界面运行

chui exec 没法问你，用 --approval 决定怎么办：

在 chui exec 里，--yolo 也不能和显式的 --approval 一起用。

项目信任

项目里的 .agents/（以及兼容的 .claude/）可以带配置、权限规则、技能、提示模板和 hooks。这些东西在你信任这个项目之前不会被加载。

chui trust allow --cwd DIR
chui trust deny --cwd DIR
chui trust status --cwd DIR

界面里用 /trust。

• chui 第一次打开带这些文件的项目时会问你，答案按 Git 根目录保存。之后新增或修改了命令 hooks，还会再问。
• 主目录和它的上级目录不会这样自动保存，因为下面所有项目都会继承。要信任这些目录，用 chui trust allow。
• chui exec 从来不问，遇到还没决定的项目内容会跳过并给出警告。
• 命令 hooks 和 T2 插件的能力各有单独的审批，不包含在项目信任里。

插件

两种插件

• T1 插件：声明式的包，由技能、MCP 服务器和 hooks 组成。
• T2 插件：独立进程，通过换行分隔的 JSON-RPC 2.0 和铁锤通信，可以加工具、命令、拦截器和面板。插件面板的内容只能是 text、markdown、list、form、progress 这几类描述，由终端界面负责绘制。

T2 插件的能力要你交互式授权一次，授权和包的内容哈希绑定，包变了会再问。无界面运行时，授权必须事先存在。

安装和管理

chui plugin marketplace add ~/src/tiechui-plugins --ref main   # 本地克隆或公开的 Git URL
chui plugin add sdk-typescript@tiechui-plugins
chui plugin list --json
chui plugin upgrade [NAME]        # 只在你执行时才升级，并显示改了什么
chui plugin remove NAME
chui plugin add ./path/to/package # 本地包

市场沿用 Codex 的 marketplace.json 格式。安装时固定到解析出的提交和内容哈希。拉取 Git 时会隔离你的 Git 配置，也不带凭据，所以私有市场要先克隆到本地再添加。官方示例市场 tiechui-plugins 暂时还没公开。

SDK

• Rust SDK：crates/tiechui-plugin-sdk。
• TypeScript SDK：sdk/typescript，零依赖，需要 Node 25，不用 npm。

技能、提示模板与 Hooks

技能

技能从这些位置加载：

• 主目录和已信任项目里的 .agents/skills 与 .claude/skills；
• profile 里的 skills/。

这些目录默认都会扫描，[skills] disabled 可以按名称排除。chui skills list 列出所有技能；在输入框里用 $ 或 /skills 插入。技能内容在发送消息时才加载。

提示模板

提示模板是 Markdown 文件，放在 profile 的 prompts/，或者已信任项目的 .agents/prompts、.claude/commands 里。每个文件注册成一个同名命令：输入 /name 一些文字，正文里的 $ARGUMENTS 会被替换成这些文字，然后作为你的消息发出去。

上下文文件

AGENTS.md 这类文件会作为上下文发给模型。/context 可以查看实际发给模型的全部内容。

Hooks

• chui hooks list 列出 hooks，chui hooks trust 批准命令 hooks。
• 除了铁锤自己的配置，.claude/settings.json 和 .claude/settings.local.json 里支持的 hooks 也会读取；其他 Claude 设置不会导入。
• 桌面客户端只编辑 hooks.json，存在里面的处理器视为已批准。

MCP

支持 stdio 和 Streamable HTTP 两种 MCP 服务器，包括工具、资源和 elicitation，所有调用都要过权限检查。

配置

[mcp_servers.local]
command = "/path/to/server"
args = []
env_vars = ["SERVICE_TOKEN"]     # 只透传列出的变量，以及 HOME、PATH 等少数基础变量

[mcp_servers.remote]
url = "https://mcp.example/mcp"
tool_timeout_sec = 60

登录

chui mcp list
chui mcp login remote [--scopes a,b]   # 浏览器 OAuth，PKCE 加本地回调
chui mcp logout remote

• OAuth 令牌会自动刷新，存在 ~/.tiechui/mcp-oauth/，权限 0600。
• 登出只删本地令牌，不会去服务器上吊销。
• 配置了静态 header 或 bearer_token_env_var 时，优先用它们，不走 OAuth。

配置文件

profile 目录

profile 目录是 $TIECHUI_HOME，默认 ~/.tiechui：

加载顺序

后面的覆盖前面的：

1. 内置默认值；
2. ~/.tiechui/config.toml；
3. 最近的项目里的 .agents/config.toml（或 .claude/config.toml）；
4. 命令行参数。

• 项目配置从当前目录往上找，最远到 Git 根目录，在你信任项目之前不会生效。
• 离得最近的配置优先；同一目录下 .agents/config.toml 优先于 .claude/config.toml。两者都用铁锤的 TOML 格式。
• 项目里的 .tiechui/ 目录会被忽略。
• provider 只能来自 ~/.tiechui/providers.toml。

完整字段

仓库里的 examples/config.toml 和 examples/providers.toml 列出了所有字段和说明，没注释掉的条目就是默认行为。schema/config.json 和 schema/providers.json 是完整的 JSON Schema。

诊断

chui doctor 只读，发现问题时以非零状态退出。它会检查：

• 装好的二进制和安装记录是否一致，有没有中断的安装；
• profile 目录是不是 0700，密钥和令牌文件是不是 0600，providers.toml 里有没有直接写的密钥；
• 配置和授权文件的结构，以及会话的版本。

它不会打开密钥或令牌文件，也不会打印任何凭据。用 --prefix 和 --profile 检查别的位置。从源码构建的二进制会跳过安装检查。

参与开发

准备

• Rust 1.95.0、Git、Python 3.10+（只用标准库），Node 25 可选；
• just、cargo-nextest、cargo-deny；
• rg，内容搜索的测试要用。

测试不联网，也不用真实凭据。

常用命令

cargo fetch --locked && cargo deny fetch    # 离线检查前先跑一次
just check     # fmt、clippy、nextest、deny、schema 与 SDK 漂移、打包测试
just pty       # 对着本地模拟 provider 跑终端模拟器测试
just pty resume approval                    # 只跑选中的 PTY 用例
just plugins-check                          # 存在 ../tiechui-plugins 时校验它

• check 的每一项都能单独跑：fmt、lint、test、deny、schema-check、sdk-check、packaging-check。
• just fmt 只检查，cargo fmt --all 才会改文件。
• 磁盘紧张时设置 CARGO_INCREMENTAL=0。

目录结构

所有功能都以模块的形式放在 tiechui-plugin-api 后面，内核不带功能策略，终端界面只依赖协议。

CI 与发布

• CI 在 Linux 和 macOS 上跑 just check 和 just pty，在 Windows 上构建并跑单元测试和文档测试。
• 推送和 workspace 版本一致的 v* tag 会触发发布：构建 Linux x86_64 / aarch64、macOS arm64 / x86_64 的 tarball 和 Windows x86_64 的 zip，连同 SHA256SUMS 挂到一个草稿 release 上，由人工发布。
• 带注释的 tag 说明就是 release 说明，比如 git tag -a v0.5.0 -F notes.md。
• release 发布后，自动发布 npm 包 @tiechui/cli。