Article
从 0 到 1 搭建自己的 Coding Agent(三):入口、配置与运行模式
你在仓库根目录启动 agent,想让它检查整个项目。换到 services/api 下面再启动,希望它沿用团队配置,同时照顾这个子目录的约定。
这时,同一条命令会碰到几个问题:在哪儿找配置,哪一份设置生效,相对路径从哪里算起。再把命令放进脚本,原来能弹出来问你的审批,现在还有人回答吗?
这些事在第一次模型请求之前就该说清。前两篇拆了循环和 Harness,这篇先不往里加能力,先把入口这段路走顺。
入口先解析命令行,分清用户要启动会话、跑一次任务,还是只看帮助。--help 和参数拼错这种情况,到这里就能结束,不用加载模型客户端。解析结果先留成普通数据,等工作范围和配置都检查过,再选择对应的运行入口。
先确定在哪里工作
我会先把三个位置分开:启动命令时的目录,这次任务实际工作的目录,以及用来发现项目配置和指令的项目根。
它们可以相同,也可以不同。比如在仓库根目录传入 --cwd services/api,工作目录就指向子目录。这个参数名是举例,你自己写入口时要明确规定:相对路径按启动目录解析,目录不存在就报错,别悄悄创建一个空目录继续跑。
项目根则需要另一条定位规则。可以向上找 Git 标记,也可以要求用户显式指定。无论选哪一种,都应该把结果保留在启动诊断里。工作目录选错,后面再聪明的文件搜索也可能是在错地方找。
项目指令还要有自己的发现范围。Codex 的官方说明是先读全局指令,再从项目根走到当前工作目录,沿途发现指令文件;每层最多选一份,AGENTS.override.md 优先于 AGENTS.md。没有找到项目根时,只检查当前目录的项目指令。
这说明当前目录会影响加载什么,但没有说当前目录就是可写边界。指令文件写着「只改这里」,也不能替代程序里的路径限制。
这篇只确定从哪儿找文件。指令怎样进入提示词,留到指令层那篇再讲。
配置叠上去之前,先决定哪些能进来
初版可以先用一个容易解释的顺序,从低到高:
内置默认值 < 用户配置 < 已信任的项目配置 < 指定环境变量 < 显式命令行参数
这是下面实验的教学约定,不是全行业规则,也没有囊括组织管理策略。
例如,Codex 配置文档把项目配置放在用户配置之上,项目内更靠近工作目录的配置优先;项目层只有在项目受信任时才加载。命令行覆盖普通配置,组织要求还会额外限制哪些值能用。
Claude Code 的设置文档又明确提醒:环境变量没有统一占据一层,和设置项谁先谁后,要按具体字段看。列表也有自己的合并规则,不能拿一个对象覆盖函数解释全部行为。
我会先把可调偏好和硬限制分开。默认模型可以选一个生效值;禁止写入某个目录的约束,不能因为项目配置排在后面就被放宽。安全策略怎么组合,后面专门写,这里先别把它混进普通设置的覆盖逻辑。
命令行解析还有个小坑。假设用户文件写了批处理模式,你没传 --mode,解析器却默认填了 interactive。再把所有解析结果覆盖进去,文件里的值就丢了。
我的处理是:解析阶段保留「用户没填」这个状态,只合并显式传入的字段。真正的默认值集中放在最底层。

值定下来之后,还要留下它的来源。只看到 model = demo-project,你仍不知道该改哪里;再看到 source = project.json,排查才有了落点。
批处理不能靠关掉界面凑出来
交互和非交互,说的是输入从哪里来、进度往哪里送、要不要等下一条输入。权限模式说的是一次动作能不能做、需不需要审批。这是两件需要分别配置的事。
有终端界面,不代表能随意写文件;没有界面,也不代表必须放开所有权限。批处理遇到需要确认的动作,如果没有可用的审批通道,就应该明确拒绝或退出,不能一直等一个不存在的人,也不能顺手当成同意。
输出也得提前定好。Codex 的非交互文档说明,普通 codex exec 把进度发到标准错误,最终回复写到标准输出;加 --json 后,标准输出改成逐行 JSON 事件流。
这样脚本才能知道自己接的是最终文本还是事件,避免把彩色启动横幅也当成结果。至于编辑器接入或常驻服务,入口需要选对适配器,不必在这里把协议再实现一遍。
第一次请求之前,能报的错先报
把参数、目录和配置解析完,我希望先得到一份可检查的启动计划,再把它交给交互或批处理入口。

启动计划里可以有工作目录、项目根、选中的运行方式、模型名、指令文件路径,以及这些设置来自哪里。它不该是一份配置文件的原样转储。
API key、认证头、连接串不能跟着诊断输出。就连报 JSON 语法错,也只需要文件定位和行列号,没必要把附近那段原文一起打印出来。
配置文件损坏、参数组合冲突、批处理缺少任务输入,这些错误不需要花一次模型请求来判断。我的教学实现会停止启动,错误送到标准错误,退出码为 2,标准输出保持为空。真实项目可以选择别的约定,但要让调用方能分清成功和失败。
这也不意味着启动预检能预测所有问题。网络是否可达、服务端是否接受请求,仍可能在后面失败。能在本地确定的先确定,别把文件解析错误拖成一次难读的模型调用错误。
跑一遍配置到底听谁的
下面这个小程序只做配置合并和启动预检,不接模型,不执行工具。它在临时目录创建两份假配置,结束后清理,不读你的用户目录或真实凭证。
用户配置故意写成 batch,项目配置只改模型名。项目层要加 --trust-project 才会读取。模型名也限在几个 demo-* 值里,避免把任意输入带进诊断。
保存成 launch_demo.py,用 Python 3.9 或更新版本运行:
import argparse
import json
import os
from pathlib import Path
import sys
import tempfile
parser = argparse.ArgumentParser()
parser.add_argument('--model') # 不设默认值,避免盖掉文件里的值
parser.add_argument('--mode', choices=['interactive', 'batch'])
parser.add_argument('--approval', choices=['ask', 'deny'])
parser.add_argument('--trust-project', action='store_true')
parser.add_argument('--prompt', default='')
parser.add_argument('--broken-project', action='store_true')
args = parser.parse_args()
allowed = {
'model': {'demo-default', 'demo-user', 'demo-project',
'demo-env', 'demo-cli'},
'mode': {'interactive', 'batch'},
'approval': {'ask', 'deny'},
}
values, sources = {}, {}
def merge(data, origin):
if not isinstance(data, dict):
raise ValueError('配置顶层必须是对象')
for key, value in data.items():
if key not in allowed:
raise ValueError('发现不支持的配置字段')
if not isinstance(value, str) or value not in allowed[key]:
raise ValueError(f'{key} 的值不在演示白名单中')
values[key], sources[key] = value, origin
try:
with tempfile.TemporaryDirectory(prefix='agent-start-') as folder:
root = Path(folder)
(root / 'user.json').write_text(json.dumps({
'model': 'demo-user', 'mode': 'batch', 'approval': 'deny'
}), encoding='utf-8')
(root / 'project.json').write_text(
'{' if args.broken_project else
json.dumps({'model': 'demo-project'}), encoding='utf-8')
merge({'model': 'demo-default', 'mode': 'interactive',
'approval': 'ask'}, 'default')
names = ['user.json']
if args.trust_project:
names.append('project.json')
for name in names:
merge(json.loads((root / name).read_text(encoding='utf-8')), name)
model = os.environ.get('MINI_MODEL')
if model is not None:
merge({'model': model}, 'env:MINI_MODEL')
merge({k: getattr(args, k) for k in allowed
if getattr(args, k) is not None}, 'CLI')
if values['mode'] == 'batch':
if not args.prompt.strip():
raise ValueError('batch 缺少非空 --prompt')
if values['approval'] == 'ask':
raise ValueError('本例 batch 不支持等待审批,请显式用 deny')
print(json.dumps({
'effective': {k: {'value': v, 'source': sources[k]}
for k, v in values.items()},
'project_loaded': args.trust_project,
'request_sent': False,
}, ensure_ascii=False, indent=2))
except (OSError, ValueError) as error:
if isinstance(error, json.JSONDecodeError):
message = f'配置 JSON 无效:第 {error.lineno} 行,第 {error.colno} 列'
elif isinstance(error, OSError):
message = '演示文件读写失败'
else:
message = str(error)
print(message, file=sys.stderr)
sys.exit(2)
先运行前两条,比较 effective.model 的值和来源。第三条再加环境变量与命令行覆盖,环境变量前缀写法适用于 Bash/Zsh:
python3 launch_demo.py --prompt "检查示例"
python3 launch_demo.py --trust-project --prompt "检查示例"
MINI_MODEL=demo-env python3 launch_demo.py --trust-project --model demo-cli --prompt "检查示例"
结果依次是 demo-user 来自 user.json,demo-project 来自 project.json,demo-cli 来自 CLI。第三条去掉 --model demo-cli,就会看到环境变量生效。这些命令假设你没有另外设置 MINI_MODEL;若设置过,先清除它再比较前两条。
注意第一条没有传 --mode,最后仍然是文件里的 batch。这正好能检查解析器有没有拿自己的默认值盖掉用户设置。
再试两次失败启动:
python3 launch_demo.py --trust-project --broken-project --prompt "检查示例"
python3 launch_demo.py --prompt "检查示例" --approval ask
前一条读到故意损坏的项目文件,后一条碰到本例不支持的批处理审批组合。它们都会退出,且不产生正常结果。这个例子选择拒绝 batch + ask,只为演示预检,不代表所有非交互产品都没有远程审批能力。
代码只合并平铺的字符串字段,没有实现真实项目根发现、指令加载、终端交互或权限执行器。输出里的 request_sent: false 也表示它停在预检阶段。可以把合并逻辑接回你自己的入口,再逐项补真实配置来源。
本地测试通过了 11 种情况,包括环境变量和命令行覆盖、项目未信任时跳过配置、坏文件、缺少输入,以及错误信息不回显测试用的敏感值。
等你把诊断命令接上,最好能直接问出「这个字段为什么取这个值」。回答里有生效值、有来源文件或参数名,而且没有凭证,下一次改配置时就能少翻几层文件。
Keep Reading
Discussion
Discussion loads when you reach this section.