catbus/docs/guide/configuration.md

配置与数据目录

catbus 的配置很少：代理和请求超时。登录态、缓存和配置都在一个数据目录里。

规范见 AGENTS.md 5.1、5.5。

数据目录

默认是 ~/.catbus/，可以用环境变量 CATBUS_HOME 换成别的目录：

export CATBUS_HOME=/data/catbus          # 之后所有命令都用这个目录
CATBUS_HOME=/tmp/catbus-test catbus auth list   # 只对这一条命令生效

目录结构：

~/.catbus/
├── config.toml                    # 配置，见下文
├── auth/
│   └── <platform>/                # 规范 id：xhs、douyin、bilibili……
│       └── <endpoint>/            # web | app | pc
│           ├── <account>.json     # 一个账号一个凭证文件
│           ├── guest.json         # 游客态的设备数据（只在支持游客态的端上生成，web 端没有）
│           └── _current           # 当前账号名
└── cache/<platform>/              # 可以随时删除：二维码 PNG、短信登录的中间态

• 权限：目录 0700、文件 0600；Windows 依赖用户目录本身的 ACL。catbus doctor 会检查数据目录，其他用户能访问时报错并给出 chmod 700 的命令。
• 所有写入都是原子的（先写临时文件再 rename），命令中途被中断不会写坏凭证。
• 凭证文件只由 catbus 自己读写，不需要手动编辑。凭证文件的格式见 AGENTS.md 5.4。
• cache/ 可以随时删除；删掉正在进行的短信登录中间态后，需要重新发验证码。

这个目录里有你的全部登录态，不要提交到 git、打包分享或贴到 issue 里。

config.toml

只有这几项：

proxy = "http://127.0.0.1:7890"   # 全局代理
timeout = 30                      # 单次请求超时（秒），默认 30

[xhs]
proxy = "socks5://127.0.0.1:1080" # 平台代理，段名用平台的规范 id

用 catbus config 读写，不需要手动编辑：

catbus config set proxy http://127.0.0.1:7890
catbus config set xhs.proxy socks5://127.0.0.1:1080   # 点号表示平台段；平台别名也可以（bili.proxy 会存成 bilibili.proxy）
catbus config set timeout 60
catbus config get xhs.proxy
catbus config unset xhs.proxy
catbus config list                                     # 只列出已设置的项，键用点号展开

{"ok":true,"platform":null,"endpoint":null,"resource":"config","action":"list","account":null,
 "data":{"proxy":"http://127.0.0.1:7890","timeout":60,"xhs.proxy":"socks5://127.0.0.1:1080"},"page":null,"error":null}

• 可设置的键只有 proxy、timeout、<platform>.proxy，其他键报 USAGE。
• timeout 必须是大于 0 的秒数。
• 手动编辑 config.toml 出现格式错误时，命令报 ERROR 并在 hint 里给出文件路径。

代理

代理的优先级：

--proxy（本次命令） > <platform>.proxy > proxy

catbus x user get elonmusk --proxy http://127.0.0.1:7890

• 支持 http、https、socks4、socks5、socks5h，地址可以带用户名密码（http://user:pass@host:port），-v 的日志里会打码。
• catbus 不读取 HTTP_PROXY / HTTPS_PROXY 环境变量，也不用系统代理，代理只能通过上面三种方式显式配置。
• 访问 TikTok、X 这类需要代理的平台，推荐按平台设置（tiktok.proxy、x.proxy），国内平台保持直连。
• 代理连不上、握手失败时报 NETWORK（退出码 6）。

环境变量

变量	说明
CATBUS_HOME	数据目录，默认 ~/.catbus

除此之外 catbus 不读取别的环境变量来改变行为（代理见上文）。开发时用到的环境变量（例如取回模型的 CATBUS_DDDDOCR_WHEEL）见 AGENTS.md 7.2。